From 1b3bd2950e024d8141f520b4ec12a350411583f9 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Sat, 31 Oct 2026 09:26:10 -0700 Subject: [PATCH 1/2] fix(qdrant-java): document released Maven Central installation Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 16 +++++ .../traceai/java/vector-databases.mdx | 59 +++++++++++++------ 2 files changed, 57 insertions(+), 18 deletions(-) diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 0a8e2c289..20c3734a5 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -47,6 +47,22 @@ test('all logo references have provenance, existing files, matching hashes and p const manifest = JSON.parse(read('public/images/integrations/manifest.json')); for (const i of integrations) assert.ok(manifest.assets[i.logo],`Missing logo record: ${i.logo}`); }); +test('Qdrant Java uses released Central coordinates and a complete blocking example', () => { + const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx'); + const section = page.split('## Qdrant\n')[1].split('\n## Milvus')[0]; + assert.match(section, /com\.futureagi<\/groupId>/); + assert.match(section, /traceai-java-qdrant<\/artifactId>\s*1\.0\.0<\/version>/); + assert.match(section, /implementation 'com\.futureagi:traceai-java-qdrant:1\.0\.0'/); + assert.match(section, /implementation 'io\.qdrant:client:1\.16\.2'/); + assert.doesNotMatch(section, /main-SNAPSHOT|com\.github\.future-agi/); + assert.match(section, /blocking methods/); + assert.match(section, /unwrap\(\).*bypass/); + assert.match(section, /public class QdrantExample/); + assert.match(section, /import io\.qdrant\.client\.grpc\.Collections\.Distance;/); + assert.match(section, /TraceAI\.shutdown\(\)/); + assert.doesNotMatch(section, /queryVector|pointsList|queryAsync\(/); +}); + test('machine-readable overview serializes every catalog entry and setup aid', () => { const text = integrationDirectoryMarkdown(); for (const entry of integrations) { diff --git a/src/pages/docs/integrations/traceai/java/vector-databases.mdx b/src/pages/docs/integrations/traceai/java/vector-databases.mdx index 6e9610bc5..2ef5525aa 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -18,42 +18,65 @@ Complete the [Java SDK setup](/docs/integrations/traceai/java) first. For Pineco ## Qdrant -Wraps `io.qdrant.client.QdrantClient`. All operations are async internally (the wrapper calls `.get()` on futures). +Trace searches, writes, point retrieval, and collection operations through `TracedQdrantClient`. Version 1.0.0 exposes blocking methods: each call waits for the underlying Qdrant future to complete. Calls made directly on the original client or through `unwrap()` bypass this wrapper. + +Install the released package from Maven Central and add the Qdrant SDK explicitly. No JitPack repository is required. ```xml Maven - com.github.future-agi.traceAI + com.futureagi traceai-java-qdrant - main-SNAPSHOT + 1.0.0 + + + io.qdrant + client + 1.16.2 ``` ```groovy Gradle -implementation 'com.github.future-agi.traceAI:traceai-java-qdrant:main-SNAPSHOT' +implementation 'com.futureagi:traceai-java-qdrant:1.0.0' +implementation 'io.qdrant:client:1.16.2' ``` +With the credentials from the [Java SDK setup](/docs/integrations/traceai/java) in your environment and Qdrant running locally on gRPC port 6334, run this example once to create and search a demo collection. If the collection already exists, omit the `createCollection` call. + ```java +import ai.traceai.TraceAI; +import ai.traceai.TraceConfig; import ai.traceai.qdrant.TracedQdrantClient; import io.qdrant.client.QdrantClient; import io.qdrant.client.QdrantGrpcClient; - -QdrantClient client = new QdrantClient( - QdrantGrpcClient.newBuilder("localhost", 6334, false).build() -); -TracedQdrantClient traced = new TracedQdrantClient(client); - -// Search -var results = traced.search("my-collection", queryVector, 10); - -// Upsert -traced.upsert("my-collection", pointsList); - -// Create collection -traced.createCollection("my-collection", 1536, Distance.Cosine); +import io.qdrant.client.grpc.Collections.Distance; +import io.qdrant.client.grpc.Points.PointStruct; +import java.util.List; + +import static io.qdrant.client.PointIdFactory.id; +import static io.qdrant.client.VectorsFactory.vectors; + +public class QdrantExample { + public static void main(String[] args) throws Exception { + TraceAI.init(TraceConfig.builder().projectName("qdrant-java").build()); + try (QdrantClient client = new QdrantClient( + QdrantGrpcClient.newBuilder("localhost", 6334, false).build())) { + TracedQdrantClient traced = new TracedQdrantClient(client); + String collection = "traceai-qdrant-example"; + List vector = List.of(0.1f, 0.2f, 0.3f); + traced.createCollection(collection, 3, Distance.Cosine); + traced.upsert(collection, List.of(PointStruct.newBuilder() + .setId(id(1)).setVectors(vectors(vector)).build())); + var results = traced.search(collection, vector, 3); + System.out.println("Matches: " + results.size()); + } finally { + TraceAI.shutdown(); + } + } +} ``` **Spans:** "Qdrant Search" (RETRIEVER), "Qdrant Upsert" (VECTOR_DB), "Qdrant Create Collection" (VECTOR_DB), "Qdrant Delete" (VECTOR_DB), "Qdrant Get" (VECTOR_DB), "Qdrant List Collections" (VECTOR_DB) From 2c620ff646d73b5ef250ec49f60655d59262b31d Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 4 Nov 2026 06:19:56 -0800 Subject: [PATCH 2/2] fix(qdrant-java): complete tracing setup and disclose metadata limitation Configure the required exporter URL, keep Qdrant on the released Central dependency path, and document the pinned adapter upsert dimension limitation. Add regression checks for each documentation contract. Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 21 +++++++++++++ .../traceai/java/vector-databases.mdx | 30 +++++++++++++++---- 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 20c3734a5..9e3cb5997 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -54,6 +54,13 @@ test('Qdrant Java uses released Central coordinates and a complete blocking exam assert.match(section, /traceai-java-qdrant<\/artifactId>\s*1\.0\.0<\/version>/); assert.match(section, /implementation 'com\.futureagi:traceai-java-qdrant:1\.0\.0'/); assert.match(section, /implementation 'io\.qdrant:client:1\.16\.2'/); + const gradle = section.match(/```groovy Gradle\n([\s\S]*?)```/)[1]; + assert.match(gradle, /repositories\s*\{\s*mavenCentral\(\)\s*\}/); + assert.match(gradle, /dependencies\s*\{/); + assert.doesNotMatch(gradle, /traceai-java-core/); + assert.match(page, /For Qdrant, follow the Maven Central installation below \*\*instead of\*\* that page's JitPack installation/); + assert.match(section, /Replace any existing JitPack TraceAI core and Qdrant dependencies/); + assert.match(section, /com\.futureagi:traceai-java-core:1\.0\.0` transitively/); assert.doesNotMatch(section, /main-SNAPSHOT|com\.github\.future-agi/); assert.match(section, /blocking methods/); assert.match(section, /unwrap\(\).*bypass/); @@ -62,6 +69,20 @@ test('Qdrant Java uses released Central coordinates and a complete blocking exam assert.match(section, /TraceAI\.shutdown\(\)/); assert.doesNotMatch(section, /queryVector|pointsList|queryAsync\(/); }); +test('Qdrant Java configures export and discloses the pinned upsert metadata limitation', () => { + const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx'); + const section = page.split('## Qdrant\n')[1].split('\n## Milvus')[0]; + const environment = section.match(/```bash\n([\s\S]*?)```/)[1]; + assert.match(environment, /^export FI_BASE_URL="https:\/\/api\.futureagi\.com"$/m); + assert.match(environment, /^export FI_API_KEY="your-fi-api-key"$/m); + assert.match(environment, /^export FI_SECRET_KEY="your-fi-secret-key"$/m); + assert.match(section, /credentials alone do not enable span export/); + assert.match(section, /\s*With `traceai-java-qdrant:1\.0\.0` and Qdrant SDK `1\.16\.2`/); + assert.match(section, /"Qdrant Upsert" spans incorrectly report `embedding\.dimensions` as `0`/); + assert.match(section, /Do not rely on this upsert field/); + assert.match(section, /use your collection configuration instead/); + assert.match(page, /\| `embedding\.dimensions` \|[^\n]*\[Qdrant limitation\]\(#qdrant\)/); +}); test('machine-readable overview serializes every catalog entry and setup aid', () => { const text = integrationDirectoryMarkdown(); diff --git a/src/pages/docs/integrations/traceai/java/vector-databases.mdx b/src/pages/docs/integrations/traceai/java/vector-databases.mdx index 2ef5525aa..ff6999255 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -12,7 +12,7 @@ description: "Trace vector database operations in Java. Qdrant, Milvus, ChromaDB ## Prerequisites -Complete the [Java SDK setup](/docs/integrations/traceai/java) first. For Pinecone, see the [dedicated Pinecone page](/docs/integrations/traceai/java/pinecone). +Use Java 17+ and your Future AGI API key and secret key. The [Java SDK setup](/docs/integrations/traceai/java) describes authentication and configuration. For Qdrant, follow the Maven Central installation below **instead of** that page's JitPack installation. For the other databases on this page, complete the Java SDK setup first. For Pinecone, see the [dedicated Pinecone page](/docs/integrations/traceai/java/pinecone). --- @@ -20,7 +20,7 @@ Complete the [Java SDK setup](/docs/integrations/traceai/java) first. For Pineco Trace searches, writes, point retrieval, and collection operations through `TracedQdrantClient`. Version 1.0.0 exposes blocking methods: each call waits for the underlying Qdrant future to complete. Calls made directly on the original client or through `unwrap()` bypass this wrapper. -Install the released package from Maven Central and add the Qdrant SDK explicitly. No JitPack repository is required. +Replace any existing JitPack TraceAI core and Qdrant dependencies with the Maven Central dependencies below; do not keep both sets of dependencies. The adapter brings `com.futureagi:traceai-java-core:1.0.0` transitively, so you do not need a separate core dependency. Add the Qdrant SDK explicitly. No JitPack repository is required. @@ -38,13 +38,27 @@ Install the released package from Maven Central and add the Qdrant SDK explicitl ``` ```groovy Gradle -implementation 'com.futureagi:traceai-java-qdrant:1.0.0' -implementation 'io.qdrant:client:1.16.2' +repositories { + mavenCentral() +} + +dependencies { + implementation 'com.futureagi:traceai-java-qdrant:1.0.0' + implementation 'io.qdrant:client:1.16.2' +} ``` -With the credentials from the [Java SDK setup](/docs/integrations/traceai/java) in your environment and Qdrant running locally on gRPC port 6334, run this example once to create and search a demo collection. If the collection already exists, omit the `createCollection` call. +Set all three environment variables before running the example. `FI_BASE_URL` is required to enable the exporter; credentials alone do not enable span export. + +```bash +export FI_BASE_URL="https://api.futureagi.com" +export FI_API_KEY="your-fi-api-key" +export FI_SECRET_KEY="your-fi-secret-key" +``` + +With Qdrant running locally on gRPC port 6334, run this example once to create and search a demo collection. If the collection already exists, omit the `createCollection` call. ```java import ai.traceai.TraceAI; @@ -85,6 +99,10 @@ Open your project in Future AGI to inspect the spans. Extra attributes: `qdrant.top_score`, `qdrant.has_filter`, `qdrant.distance`, `qdrant.status` + +With `traceai-java-qdrant:1.0.0` and Qdrant SDK `1.16.2`, "Qdrant Upsert" spans incorrectly report `embedding.dimensions` as `0` for vectors created by `VectorsFactory.vectors()`, including the three-dimensional vector above. Do not rely on this upsert field for dimension validation or filtering; use your collection configuration instead. Search spans report `embedding.dimensions` correctly, and collection-creation spans report the configured size in `qdrant.vector_size`. + + --- ## Milvus @@ -477,6 +495,6 @@ Depending on the wrapper and operation, spans may include: |-----------|-------------| | `db.system` | Database name (e.g., `pinecone`, `qdrant`, `milvus`) | | `db.vector.collection.name` or `db.vector.index.name` | Collection or index name | -| `embedding.dimensions` | Vector dimensions | +| `embedding.dimensions` | Vector dimensions; do not rely on this field for Qdrant upserts with the versions above (see the [Qdrant limitation](#qdrant)) | | `retriever.top_k` | Number of results requested (search operations) | | `db.vector.results.count` | Number of results returned |