diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index edc5f8020..2964f966a 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -113,6 +113,43 @@ 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'/); + 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/); + 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('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(); 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 748885a12..ad15f777a 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -13,48 +13,87 @@ description: "Trace vector database operations in Java. Qdrant, Milvus, ChromaDB ## Prerequisites -For Elasticsearch, follow the self-contained [native setup](#elasticsearch) below. For the other wrappers, 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 Elasticsearch, follow the self-contained [native setup](#elasticsearch) below. For the other wrappers, complete the Java SDK setup first. For Pinecone, see the [dedicated Pinecone page](/docs/integrations/traceai/java/pinecone). --- ## 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. + +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. ```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' +repositories { + mavenCentral() +} + +dependencies { + implementation 'com.futureagi:traceai-java-qdrant:1.0.0' + implementation 'io.qdrant:client:1.16.2' +} ``` +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; +import ai.traceai.TraceConfig; import ai.traceai.qdrant.TracedQdrantClient; import io.qdrant.client.QdrantClient; import io.qdrant.client.QdrantGrpcClient; +import io.qdrant.client.grpc.Collections.Distance; +import io.qdrant.client.grpc.Points.PointStruct; +import java.util.List; -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); +import static io.qdrant.client.PointIdFactory.id; +import static io.qdrant.client.VectorsFactory.vectors; -// Create collection -traced.createCollection("my-collection", 1536, Distance.Cosine); +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) @@ -63,6 +102,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 dense vectors created by `VectorsFactory.vectors(List)`, 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 @@ -630,6 +673,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 |