diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 4dab77cf1..edc5f8020 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -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(/([\s\S]*?)<\/dependency>/g)] + .map(([, block]) => ['groupId', 'artifactId', 'version'] + .map(tag => block.match(new RegExp(`<${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 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]; diff --git a/src/pages/docs/integrations/traceai/java/vector-databases.mdx b/src/pages/docs/integrations/traceai/java/vector-databases.mdx index 014aa694b..748885a12 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -210,50 +210,72 @@ Extra attributes: `weaviate.object_id`, `weaviate.imported_count`, `weaviate.has ## MongoDB Atlas Vector Search -Wraps `com.mongodb.client.MongoCollection`. Builds the `$vectorSearch` aggregation pipeline internally. +Trace vector searches through `TracedMongoVectorSearch`, which wraps a synchronous `MongoCollection`. 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. ```xml Maven - com.github.future-agi.traceAI + com.futureagi + traceai-java-core + 1.0.0 + + + com.futureagi traceai-java-mongodb - main-SNAPSHOT + 1.0.0 + + + org.mongodb + mongodb-driver-sync + 5.14.0 ``` ```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' +} ``` +[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`. 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 collection = /* your MongoDB collection */; -TracedMongoVectorSearch traced = new TracedMongoVectorSearch(collection, "my-collection"); - -// Vector search (uses List, not List) -var results = traced.vectorSearch( - queryVectorDoubles, // List - "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 search( + MongoCollection collection, List 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. ---