From 3904939aa50dc4cee7ad0bd5421446733ac10fde Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Sat, 31 Oct 2026 05:31:26 -0700 Subject: [PATCH] fix(chromadb-java): document the released legacy setup Use Central coordinates, declare the provided client, and bound Java Chroma support to existing API-v1 deployments. Co-Authored-By: Claude Code --- package.json | 2 +- scripts/chromadb-java.test.mjs | 37 ++++++++++ .../traceai/java/vector-databases.mdx | 71 +++++++++++++------ 3 files changed, 88 insertions(+), 22 deletions(-) create mode 100644 scripts/chromadb-java.test.mjs diff --git a/package.json b/package.json index 273d686fd..e02049c5a 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", + "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.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 6e9610bc5..95f391a74 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -120,47 +120,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. ---