Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
37 changes: 37 additions & 0 deletions scripts/chromadb-java.test.mjs
Original file line number Diff line number Diff line change
@@ -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(`<groupId>com\\.futureagi</groupId>\\s*<artifactId>${artifact}</artifactId>\\s*<version>1\\.0\\.0</version>`));
assert.ok(chroma.includes(`com.futureagi:${artifact}:1.0.0`));
}
assert.match(chroma, /<groupId>io\.github\.amikos-tech<\/groupId>\s*<artifactId>chromadb-java-client<\/artifactId>\s*<version>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(/<Warning>([\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('<Warning>') < 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 \*\//);
});
71 changes: 50 additions & 21 deletions src/pages/docs/integrations/traceai/java/vector-databases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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**.

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

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.

<CodeGroup titles={["Maven", "Gradle"]}>

```xml Maven
<dependency>
<groupId>com.github.future-agi.traceAI</groupId>
<groupId>com.futureagi</groupId>
<artifactId>traceai-java-core</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.futureagi</groupId>
<artifactId>traceai-java-chromadb</artifactId>
<version>main-SNAPSHOT</version>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>io.github.amikos-tech</groupId>
<artifactId>chromadb-java-client</artifactId>
<version>0.1.7</version>
</dependency>
```

```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'
}
```

</CodeGroup>

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

---

Expand Down
Loading