diff --git a/package.json b/package.json index 9e16f294e..937a8d1de 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "astro": "astro", "new-doc": "node scripts/new-doc.mjs", "audit-links": "node scripts/audit-links.mjs", - "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/langfuse-import.test.mjs scripts/n8n-page.test.mjs scripts/openlit-endpoint.test.mjs", + "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/langfuse-import.test.mjs scripts/n8n-page.test.mjs scripts/openlit-endpoint.test.mjs scripts/chromadb-java.test.mjs", "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs", "check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs" }, diff --git a/scripts/chromadb-java.test.mjs b/scripts/chromadb-java.test.mjs new file mode 100644 index 000000000..4a20ebed8 --- /dev/null +++ b/scripts/chromadb-java.test.mjs @@ -0,0 +1,37 @@ +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import test from 'node:test'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/java/vector-databases.mdx', import.meta.url), 'utf8'); +const chroma = page.split('## ChromaDB\n')[1]?.split('\n## Weaviate')[0]; + +test('Chroma Java uses released Central coordinates and declares the provided client', () => { + assert.ok(chroma, 'ChromaDB section exists'); + for (const artifact of ['traceai-java-core', 'traceai-java-chromadb']) { + assert.match(chroma, new RegExp(`com\\.futureagi\\s*${artifact}\\s*1\\.0\\.0`)); + assert.ok(chroma.includes(`com.futureagi:${artifact}:1.0.0`)); + } + assert.match(chroma, /io\.github\.amikos-tech<\/groupId>\s*chromadb-java-client<\/artifactId>\s*0\.1\.7<\/version>/); + assert.ok(chroma.includes('io.github.amikos-tech:chromadb-java-client:0.1.7')); + assert.ok(chroma.includes('mavenCentral()')); + assert.doesNotMatch(chroma, /main-SNAPSHOT|com\.github\.future-agi\.traceAI/); +}); + +test('Chroma Java bounds compatibility before installation without recommending a downgrade', () => { + const warning = chroma.match(/([\s\S]*?)<\/Warning>/)?.[1]; + assert.ok(warning); + assert.match(warning, /\/api\/v1/); + assert.match(warning, /1\.5\.9/); + assert.match(warning, /HTTP 410/); + assert.match(warning, /Do not downgrade/); + assert.ok(chroma.indexOf('') < chroma.indexOf('```xml')); + assert.doesNotMatch(chroma, /main-SNAPSHOT|0\.2\.0|traced\.updateEmbeddings/); +}); + +test('Chroma Java query example has imports and uses the existing collection', () => { + assert.match(chroma, /import java\.util\.List;/); + assert.match(chroma, /import tech\.amikos\.chromadb\.model\.QueryEmbedding\.IncludeEnum;/); + assert.match(chroma, /new TracedChromaCollection\(collection, collection\.getName\(\)\)/); + assert.match(chroma, /embedding function/); + assert.doesNotMatch(chroma, /\/\* get from ChromaDB client \*\//); +}); diff --git a/src/pages/docs/integrations/traceai/java/vector-databases.mdx b/src/pages/docs/integrations/traceai/java/vector-databases.mdx index b7b174c9b..0585db2e0 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -164,47 +164,76 @@ Extra attributes: `milvus.top_score`, `milvus.filter`, `milvus.inserted_count`, ## ChromaDB -Wraps `tech.amikos.chromadb.Collection`. Text-based queries only (the SDK v0.1.7 doesn't support raw vector queries). +Trace text queries and document operations on an existing `tech.amikos.chromadb.Collection` using Java client **0.1.7**. + + +This client uses Chroma's legacy `/api/v1` endpoints. Use this integration only with an existing API-v1-compatible deployment. Chroma **1.5.9** rejects v1 GET requests with **HTTP 410**; this wrapper does not add API-v2 support. Do not downgrade or recreate a database to use it. For a v2-only server, keep your working client; this wrapper is not a compatible tracing route. + + +Install the released packages from Maven Central, including the Chroma client: the wrapper declares that client as a provided dependency. Use these core and ChromaDB coordinates **instead of** their JitPack equivalents; do not mix both copies of the SDK. ```xml Maven - com.github.future-agi.traceAI + com.futureagi + traceai-java-core + 1.0.0 + + + com.futureagi traceai-java-chromadb - main-SNAPSHOT + 1.0.0 + + + io.github.amikos-tech + chromadb-java-client + 0.1.7 ``` ```groovy Gradle -implementation 'com.github.future-agi.traceAI:traceai-java-chromadb:main-SNAPSHOT' +repositories { + mavenCentral() +} + +dependencies { + implementation 'com.futureagi:traceai-java-core:1.0.0' + implementation 'com.futureagi:traceai-java-chromadb:1.0.0' + implementation 'io.github.amikos-tech:chromadb-java-client:0.1.7' +} ``` +[Initialize TraceAI](/docs/integrations/traceai/java#initialization) once before calling this example. Pass your existing collection, configured with the same embedding function used to populate it. For example, obtain it with `client.getCollection("my-collection", embeddingFunction)` using your existing `Client` and embedding function. Queries in client 0.1.7 accept text, not raw vectors. + ```java import ai.traceai.chromadb.TracedChromaCollection; +import java.util.List; import tech.amikos.chromadb.Collection; - -Collection collection = /* get from ChromaDB client */; -TracedChromaCollection traced = new TracedChromaCollection(collection, "my-collection"); - -// Query by text -var results = traced.query( - List.of("What is machine learning?"), // query texts - 10, // nResults - null, // where filter - null, // whereDocument filter - List.of(IncludeEnum.DOCUMENTS, IncludeEnum.DISTANCES) -); - -// Add documents -traced.add(embeddings, metadatas, documents, ids); +import tech.amikos.chromadb.model.QueryEmbedding.IncludeEnum; + +public final class ChromaQueries { + public static Collection.QueryResponse findDocuments( + Collection collection, String question) throws Exception { + TracedChromaCollection traced = + new TracedChromaCollection(collection, collection.getName()); + return traced.query( + List.of(question), + 10, + null, // metadata filter + null, // document filter + List.of(IncludeEnum.DOCUMENTS, IncludeEnum.DISTANCES)); + } +} ``` -**Spans:** "ChromaDB Query" (RETRIEVER), "ChromaDB Add" (VECTOR_DB), "ChromaDB Upsert" (VECTOR_DB), "ChromaDB Delete" (VECTOR_DB), "ChromaDB Get" (VECTOR_DB), "ChromaDB Count" (VECTOR_DB) +Call `ChromaQueries.findDocuments(collection, "What is machine learning?")` from your application, then open your project in Future AGI and look for **ChromaDB Query**. Query text is captured unless you set `hideInputs(true)` in your `TraceConfig`; review the [Java privacy settings](/docs/integrations/traceai/java#traceconfig-reference) before tracing sensitive data. + +**Spans in 1.0.0:** "ChromaDB Query" (RETRIEVER), "ChromaDB Add" (VECTOR_DB), "ChromaDB Upsert" (VECTOR_DB), "ChromaDB Delete" (VECTOR_DB), "ChromaDB Get" (VECTOR_DB), "ChromaDB Count" (VECTOR_DB). -Extra attributes: `chromadb.top_distance` (distance, not similarity score - ChromaDB is distance-based) +`chromadb.top_distance` is a distance, not a similarity score. If collection lookup or a traced operation returns HTTP 410, check server/client API compatibility; changing tracing credentials will not resolve it. ---