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
33 changes: 33 additions & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,39 @@ test('machine-readable overview serializes every catalog entry and setup aid', (
assert.equal(integrations.find(i => i.id === 'eve').name, 'Eve');
assert.doesNotMatch(read('src/components/IntegrationDirectory.astro'), /↗/);
});
test('MongoDB Java setup uses matching pinned Maven Central dependencies in both build tools', () => {
const section = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx')
.split('## MongoDB Atlas Vector Search\n')[1]?.split('\n## Redis')[0];
assert.ok(section, 'MongoDB setup section must exist');
const maven = section.match(/```xml Maven\n([\s\S]*?)```/)?.[1];
const gradle = section.match(/```groovy Gradle\n([\s\S]*?)```/)?.[1];
assert.ok(maven && gradle, 'Both build tools need installation snippets');
const dependencies = [...maven.matchAll(/<dependency>([\s\S]*?)<\/dependency>/g)]
.map(([, block]) => ['groupId', 'artifactId', 'version']
.map(tag => block.match(new RegExp(`<${tag}>([^<]+)</${tag}>`))?.[1]).join(':'));
assert.deepEqual(dependencies, [
'com.futureagi:traceai-java-core:1.0.0',
'com.futureagi:traceai-java-mongodb:1.0.0',
'org.mongodb:mongodb-driver-sync:5.14.0',
]);
assert.deepEqual([...gradle.matchAll(/implementation '([^']+)'/g)].map(([, coordinate]) => coordinate), dependencies);
assert.match(gradle, /mavenCentral\(\)/);
assert.doesNotMatch(maven + gradle, /main-SNAPSHOT|com\.github\.future-agi/);
});

test('MongoDB Java setup keeps initialization and explicit vector-search scope clear', () => {
const section = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx')
.split('## MongoDB Atlas Vector Search\n')[1]?.split('\n## Redis')[0];
assert.ok(section, 'MongoDB setup section must exist');
assert.match(section, /Replace any JitPack core or MongoDB dependencies/);
assert.match(section, /\/docs\/integrations\/traceai\/java#initialization/);
assert.match(section, /only operations called through the wrapper/);
assert.match(section, /import java\.util\.List;/);
assert.match(section, /List<Double> queryVector/);
assert.match(section, /collection\.getNamespace\(\)\.getCollectionName\(\)/);
assert.doesNotMatch(section, /\/\* your MongoDB collection \*\//);
});

test('Envoy native OTLP endpoints retain the Future AGI receiver prefix', () => {
const page = read('src/pages/docs/integrations/gateways/envoy-ai-gateway.mdx');
const cloud = page.match(/export OTEL_EXPORTER_OTLP_ENDPOINT="([^"]+)"/)?.[1];
Expand Down
66 changes: 44 additions & 22 deletions src/pages/docs/integrations/traceai/java/vector-databases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -210,50 +210,72 @@ Extra attributes: `weaviate.object_id`, `weaviate.imported_count`, `weaviate.has

## MongoDB Atlas Vector Search

Wraps `com.mongodb.client.MongoCollection<Document>`. Builds the `$vectorSearch` aggregation pipeline internally.
Trace vector searches through `TracedMongoVectorSearch`, which wraps a synchronous `MongoCollection<Document>`. It builds the `$vectorSearch` pipeline and traces only operations called through the wrapper.

Use Java 17 or later. Install the released packages from Maven Central, including the MongoDB driver, which the wrapper does not install transitively. Replace any JitPack core or MongoDB dependencies with these coordinates to avoid duplicate SDK classes.

<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-mongodb</artifactId>
<version>main-SNAPSHOT</version>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<version>5.14.0</version>
</dependency>
```

```groovy Gradle
implementation 'com.github.future-agi.traceAI:traceai-java-mongodb:main-SNAPSHOT'
repositories {
mavenCentral()
}

dependencies {
implementation 'com.futureagi:traceai-java-core:1.0.0'
implementation 'com.futureagi:traceai-java-mongodb:1.0.0'
implementation 'org.mongodb:mongodb-driver-sync:5.14.0'
}
```

</CodeGroup>

[Initialize TraceAI once](/docs/integrations/traceai/java#initialization) before calling the example, and review the [content and error settings](/docs/integrations/traceai/java#traceconfig-reference). Pass your existing collection and a query embedding as `List<Double>`. The example expects a Vector Search index named `vector_index` on the `embedding` field; use your index name and match its vector dimensions.

```java
import ai.traceai.mongodb.TracedMongoVectorSearch;
import com.mongodb.client.MongoCollection;
import java.util.List;
import org.bson.Document;

MongoCollection<Document> collection = /* your MongoDB collection */;
TracedMongoVectorSearch traced = new TracedMongoVectorSearch(collection, "my-collection");

// Vector search (uses List<Double>, not List<Float>)
var results = traced.vectorSearch(
queryVectorDoubles, // List<Double>
"embedding", // vector field path
"vector_index", // Atlas Search index name
10, // limit
100 // numCandidates
);

// Insert
traced.insertOne(new Document("text", "hello").append("embedding", vectorDoubles));
public class MongoVectorSearchExample {
public static List<Document> search(
MongoCollection<Document> collection, List<Double> queryVector) {
TracedMongoVectorSearch traced = new TracedMongoVectorSearch(
collection, collection.getNamespace().getCollectionName());

return traced.vectorSearch(
queryVector,
"embedding", // vector field path
"vector_index", // Vector Search index name
10, // limit
100 // numCandidates
);
}
}
```

**Spans:** "MongoDB Vector Search" (RETRIEVER), "MongoDB Insert" (VECTOR_DB), "MongoDB Insert Many" (VECTOR_DB), "MongoDB Delete" (VECTOR_DB)

Extra attributes: `mongodb.num_candidates`, `mongodb.path`, `mongodb.top_score`
Each result includes a `score` field from `vectorSearchScore`. The `MongoDB Vector Search` span covers aggregation and result consumption. Open your project in Future AGI to inspect its `RETRIEVER` span, requested result limit, result count, and top score.

Note: the wrapper constructs the `$vectorSearch` aggregation pipeline for you and appends `vectorSearchScore` to results.
The wrapper also exposes `insertOne`, `insertMany`, and `deleteMany`, which emit `VECTOR_DB` spans named "MongoDB Insert", "MongoDB Insert Many", and "MongoDB Delete". It does not automatically instrument other collection calls.

---

Expand Down
Loading