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.
---