fix: dev publishing pipeline

Author: itspunkaj

.github/workflows/snapshot.yml

@@ -34,11 +34,8 @@ jobs:
             mvn versions:set -DnewVersion="${VERSION}-SNAPSHOT" -DgenerateBackupPoms=false
           fi
 
-      - name: Build and test
-        run: mvn -B clean verify
-
-      - name: Publish to GitHub Packages
-        run: mvn -B deploy -DskipTests
+      - name: Build, test and publish to GitHub Packages
+        run: mvn -B clean deploy -Dmaven.resolver.transport=wagon
         env:
           GITHUB_ACTOR: ${{ github.actor }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -189,12 +189,14 @@ for (QueryResult item : results) {
 
 **Query Parameters:**
 
-| Parameter        | Description                                             | Default  | Max  |
-| ---------------- | ------------------------------------------------------- | -------- | ---- |
-| `vector`         | Query vector (must match index dimension)               | Required | -    |
-| `topK`           | Number of results to return                             | 10       | 512  |
-| `ef`             | Search quality parameter - higher values improve recall | 128      | 1024 |
-| `includeVectors` | Include vector data in results                          | false    | -    |
+| Parameter                        | Description                                                                 | Default | Max       |
+| -------------------------------- | --------------------------------------------------------------------------- | ------- | --------- |
+| `vector`                         | Query vector (must match index dimension)                                   | Required | -        |
+| `topK`                           | Number of results to return                                                 | 10      | 512       |
+| `ef`                             | Search quality parameter - higher values improve recall                     | 128     | 1024      |
+| `includeVectors`                 | Include vector data in results                                              | false   | -         |
+| `prefilterCardinalityThreshold`  | Switch from prefilter to postfilter when estimated matches exceed this value | 10,000  | 1,000,000 |
+| `filterBoostPercentage`          | Bias results toward filter matches (0 = no boost, 100 = maximum boost)     | 0       | 100       |
 
 ## Filtered Querying
 
@@ -223,6 +225,30 @@ List<QueryResult> results = index.query(
 
 > **Note:** The `$range` operator supports values within **[0 - 999]**. Normalize larger values before upserting.
 
+### Filter Performance Tuning
+
+Two parameters control how filters are applied during search:
+
+**`prefilterCardinalityThreshold`** — controls the cutover between prefiltering and postfiltering:
+- **Prefilter** (default for small result sets): filters are applied *before* the ANN search, scanning only matching vectors. Fast when the filter is selective.
+- **Postfilter**: the ANN search runs first, then results are filtered. Used when the estimated number of matches exceeds the threshold.
+
+**`filterBoostPercentage`** — biases the ANN search toward vectors that match the filter (0–100). Higher values trade some recall for better filter alignment.
+
+```java
+List<QueryResult> results = index.query(
+    QueryOptions.builder()
+        .vector(new double[] {0.15, 0.25 /* ... */})
+        .topK(5)
+        .filter(List.of(
+            Map.of("category", Map.of("$eq", "tech"))
+        ))
+        .prefilterCardinalityThreshold(50000)  // switch to postfilter above 50k matches
+        .filterBoostPercentage(20)              // slight boost toward filter matches
+        .build()
+);
+```
+
 ## Hybrid Search
 
 ### Upserting Hybrid Vectors
@@ -524,13 +550,15 @@ CreateIndexOptions.builder(String name, int dimension)
 
 ```java
 QueryOptions.builder()
-    .vector(double[])                        // Required for dense search
-    .topK(int)                               // Required
-    .ef(int)                                 // Default: 128
-    .filter(List<Map<String, Object>>)       // Optional
-    .includeVectors(boolean)                 // Default: false
-    .sparseIndices(int[])                    // Optional, for hybrid search
-    .sparseValues(double[])                  // Optional, for hybrid search
+    .vector(double[])                           // Required for dense search
+    .topK(int)                                  // Default: 10, Max: 512
+    .ef(int)                                    // Default: 128, Max: 1024
+    .filter(List<Map<String, Object>>)          // Optional
+    .includeVectors(boolean)                    // Default: false
+    .sparseIndices(int[])                       // Optional, for hybrid search
+    .sparseValues(double[])                     // Optional, for hybrid search
+    .prefilterCardinalityThreshold(int)         // Default: 10000, range: 1000–1000000
+    .filterBoostPercentage(int)                 // Default: 0, range: 0–100
     .build()
 ```
 
@@ -582,6 +610,87 @@ VectorItem.builder(String id, double[] vector)
 | `precision`       | `Precision` | Quantization precision               |
 | `m`               | `int`       | Graph connectivity                   |
 
+## Publishing & Versioning
+
+### Version Convention
+
+The version in `pom.xml` always carries a `-SNAPSHOT` suffix during development (e.g., `0.1.2-SNAPSHOT`). The CI/CD pipeline handles stripping it for releases automatically — you never need to edit the version manually.
+
+### Branching Strategy
+
+| Branch | Action | Publishes To |
+| ------ | ------ | ------------ |
+| `dev` | Push / merge | GitHub Packages (`pkg.github.com`) as a SNAPSHOT |
+| `main` | Push / merge | Maven Central as a release + GitHub Release tag |
+
+### Release Flow (main branch)
+
+When code is pushed to `main`, GitHub Actions automatically:
+1. Strips `-SNAPSHOT` from the version (e.g., `0.1.2-SNAPSHOT` → `0.1.2`)
+2. Signs artifacts with GPG and deploys to Maven Central
+3. Creates a git tag `v0.1.2` and a GitHub Release
+4. Bumps the pom version to the next patch SNAPSHOT (`0.1.3-SNAPSHOT`) and commits back to `main`
+
+### Snapshot Flow (dev branch)
+
+When code is pushed to `dev`, GitHub Actions:
+1. Builds and runs all tests
+2. Publishes `0.1.2-SNAPSHOT` to GitHub Packages
+
+> Sonatype Central Portal does **not** support SNAPSHOT versions, which is why snapshots go to GitHub Packages.
+
+### Consuming a Snapshot
+
+To use a snapshot version in another project, add the GitHub Packages repository and authenticate with a GitHub token that has `read:packages` scope:
+
+```xml
+<repositories>
+    <repository>
+        <id>github</id>
+        <url>https://maven.pkg.github.com/EndeeLabs/endee-java-client</url>
+    </repository>
+</repositories>
+```
+
+Add credentials in `~/.m2/settings.xml`:
+
+```xml
+<server>
+    <id>github</id>
+    <username>YOUR_GITHUB_USERNAME</username>
+    <password>YOUR_GITHUB_TOKEN</password>
+</server>
+```
+
+Then depend on the snapshot:
+
+```xml
+<dependency>
+    <groupId>io.endee</groupId>
+    <artifactId>endee-java-client</artifactId>
+    <version>0.1.2-SNAPSHOT</version>
+</dependency>
+```
+
+### Required GitHub Secrets
+
+| Secret | Purpose |
+| ------ | ------- |
+| `CENTRAL_USERNAME` | Sonatype Central Portal username |
+| `CENTRAL_PASSWORD` | Sonatype Central Portal token |
+| `GPG_PRIVATE_KEY` | Armored GPG private key for signing |
+| `GPG_PASSPHRASE` | GPG key passphrase |
+
+### Local Manual Deploy
+
+```bash
+# Deploy a release to Maven Central (requires GPG installed)
+mvn clean deploy -Prelease
+
+# Pass GPG passphrase inline if not in settings.xml
+mvn clean deploy -Prelease -Dgpg.passphrase="your-passphrase"
+```
+
 ## Dependencies
 
 - Jackson (JSON serialization)