diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 30ff909ed..81d70c9ed 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -429,6 +429,34 @@ test('public prose and catalog labels contain no internal QA label or Alpha rele assert.equal(publicProse('Beta. `pkg==1.0.0-alpha`\n```python\nmodel="alpha"\n```\n'),'Beta. \n\n'); }); +test('Voyage AI guide installs the package and keeps customer-facing privacy guidance', () => { + const page = read('src/pages/docs/integrations/traceai/voyage.mdx'); + const catalog = integrations.find(i => i.id === 'voyage-ai'); + assert.equal(catalog?.href, '/docs/integrations/traceai/voyage'); + assert.equal(catalog?.method, 'traceAI SDK'); + for (const text of [ + 'pip install "traceAI-voyage>=0.1.2" "fi-instrumentation-otel>=1.2.3"', 'voyageai>=0.3.7,<1', + 'voyage.multimodal_embed', 'voyage.contextualized_embed', '[media omitted]', + 'VoyageInstrumentor().instrument(tracer_provider=trace_provider)', 'trace_provider.force_flush()', + 'capture_content=True', 'FI_HIDE_INPUTS=true', 'FI_HIDE_OUTPUTS=true', + ]) assert.ok(page.includes(text), text); + assert.doesNotMatch(page, /Live vendor verification|verified live|Not yet run live|trace [0-9a-f]{8}-/i); +}); + +test('Voyage AI privacy guidance requires error suppression and explains explicit overrides', () => { + const page = read('src/pages/docs/integrations/traceai/voyage.mdx'); + const install = page.split('## 1. Installation')[1].split('## 2.')[0]; + assert.match(install, /```bash\s+pip install "traceAI-voyage>=0\.1\.2" "fi-instrumentation-otel>=1\.2\.3"\s+```/); + const privacy = page.split('## Privacy')[1].split('## Hosts')[0]; + assert.match(privacy, /Set privacy environment variables before calling `register\(\)` and `instrument\(\)`/); + assert.match(privacy, /Hides query, texts, documents, scores and error messages; counts, model, tokens and error types remain/); + assert.match(privacy, /Error-message suppression requires `fi-instrumentation-otel>=1\.2\.3`/); + assert.match(privacy, /Leave `FI_HIDE_ERROR_DETAILS` unset or set it to `true`/); + assert.match(privacy, /do not override it with `FI_HIDE_ERROR_DETAILS=false` or `TraceConfig\(hide_error_details=False\)`/); + assert.match(privacy, /overrides can expose response content in exception messages and `ERROR` status descriptions/); + assert.doesNotMatch(page, /No content at all|fi-instrumentation-otel>=1\.1\.0/); +}); + test('Temporal TypeScript warns about incompatible histories before setup', () => { const page = read('src/pages/docs/integrations/frameworks/temporal-typescript.mdx'); const prerequisites = page.split('## Set up tracing')[0]; diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index df0f390a2..4c2dffdbf 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -56,6 +56,7 @@ export const integrations = [ {"id": "openlit", "name": "OpenLIT", "href": "/docs/integrations/traceai/openlit", "category": "frameworks", "summary": "Export synchronous Python OpenAI spans with OpenLIT.", "method": "Native OTLP", "logo": "generic-framework"}, { id: 'gradio', name: 'Gradio', href: '/docs/integrations/traceai/gradio', category: 'frameworks', summary: 'Trace synchronous chat callbacks through their model client.', method: 'OpenAI client', logo: 'generic-framework' }, { id: 'z-ai', name: 'Z.ai', href: '/docs/integrations/providers/z-ai', category: 'providers', summary: 'Trace Python chat completions on the general-platform endpoint.', method: 'OpenAI client', logo: 'generic-model' }, + { id: 'voyage-ai', name: 'Voyage AI', href: '/docs/integrations/traceai/voyage', category: 'providers', summary: 'Trace embedding and rerank calls from the Python client.', method: 'traceAI SDK', logo: 'generic-model', aliases: ['Voyage', 'voyageai', 'rerank'] }, { id: 'cursor', name: 'Cursor IDE', href: '/docs/integrations/coding-agents/cursor', category: 'coding', summary: 'Trace macOS IDE agent sessions through observation hooks.', method: 'Hook-to-OTLP', logo: 'generic-framework' }, { id: 'langsmith', name: 'LangSmith', href: '/docs/integrations/langsmith', category: 'frameworks', summary: 'Forward supported LangSmith SDK traces over OTLP.', method: 'Native OTLP', logo: 'generic-framework' }, {"id": "mlflow", "name": "MLflow", "href": "/docs/integrations/mlflow", "category": "frameworks", "summary": "Export current MLflow traces with OTLP/HTTP.", "method": "Native OTLP", "logo": "generic-framework"}, diff --git a/src/pages/docs/integrations/traceai/voyage.mdx b/src/pages/docs/integrations/traceai/voyage.mdx new file mode 100644 index 000000000..847a93ff9 --- /dev/null +++ b/src/pages/docs/integrations/traceai/voyage.mdx @@ -0,0 +1,94 @@ +--- +title: "Voyage AI Integration with Future AGI for Embedding and Rerank Tracing" +description: "Trace the Voyage AI Python client (embeddings and rerank) in Future AGI with traceAI-voyage: install, configure, what is captured and privacy settings." +--- + +`traceAI-voyage` traces the official Voyage AI Python client, `voyageai.Client` and `voyageai.AsyncClient`. `traceAI-openai` does **not** trace Voyage: it wraps the OpenAI client only and never sees `voyageai.Client`. Use this package for Voyage embeddings and reranking. + +## 1. Installation + +Use Python 3.10 through 3.13. + +```bash +pip install "traceAI-voyage>=0.1.2" "fi-instrumentation-otel>=1.2.3" +``` + +The supported Voyage client range is `voyageai>=0.3.7,<1`. Install `fi-instrumentation-otel>=1.2.3` as shown above so content-hide settings also suppress error details. + +## 2. Set environment variables + +```python +import os + +os.environ["FI_API_KEY"] = "your-futureagi-api-key" +os.environ["FI_SECRET_KEY"] = "your-futureagi-secret-key" +os.environ["VOYAGE_API_KEY"] = "your-voyage-api-key" +``` + +## 3. Register and instrument + +```python +import voyageai +from fi_instrumentation import register +from fi_instrumentation.fi_types import ProjectType +from traceai_voyage import VoyageInstrumentor + +trace_provider = register(project_type=ProjectType.OBSERVE, project_name="my-rag-app") +VoyageInstrumentor().instrument(tracer_provider=trace_provider) + +client = voyageai.Client() # reads VOYAGE_API_KEY +client.embed(["What is the capital of France?"], model="voyage-3.5", input_type="query") +client.rerank("capital of France", ["Paris is...", "Berlin is..."], model="rerank-2.5", top_k=1) + +trace_provider.force_flush() +``` + +The methods are patched on the client classes, so a client created before `instrument()` is traced too. `uninstrument()` restores the originals. + +## 4. View the trace + +Open **Observe** in Future AGI and select the `my-rag-app` project. Each call appears as a `voyage.embed` or `voyage.rerank` span. + +## What is captured + +These methods are traced on both `voyageai.Client` and `voyageai.AsyncClient`: + +| Method | Span name | Span kind | +|---|---|---| +| `embed` | `voyage.embed` | `EMBEDDING` | +| `multimodal_embed` | `voyage.multimodal_embed` | `EMBEDDING` | +| `contextualized_embed` | `voyage.contextualized_embed` | `EMBEDDING` | +| `rerank` | `voyage.rerank` | `RERANKER` | + +One span per call, including a whole batch and the client's own retries. Spans nest under the active span, so an agent or chain span becomes their parent. Recorded: provider `voyage`, model, `server.address` (host only), input/document/result counts, `input_type`, output dimension, `top_k`, and the token total reported by the client (shown as input tokens; never estimated, no cost set). Multimodal text tokens and image/video pixels are recorded separately; pixels are not added to the token total. + +By default, a failed call is an `ERROR` span with the error type and message (API key removed). For `multimodal_embed` and `contextualized_embed`, only the error type and a generic message are recorded, because SDK errors can echo media or whole documents. The privacy settings below can suppress error messages while preserving the error type and `ERROR` status. No stack trace is exported. + +The deprecated module functions `voyageai.get_embedding(s)` and the TypeScript client are not traced. Embedding vectors are never recorded. + +## Privacy + +This package follows the standard traceAI `TraceConfig`. Set privacy environment variables before calling `register()` and `instrument()`. + +| Setting | Recorded | +|---|---| +| Default | Rerank query and relevance scores. Embedding inputs and rerank documents are **not** recorded. | +| `VoyageInstrumentor().instrument(..., capture_content=True)` | Also embedding text inputs and rerank documents (first 64 items, each cut to 2 KB). Media in multimodal inputs is recorded as `[media omitted]`. | +| `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true` | Hides query, texts, documents, scores and error messages; counts, model, tokens and error types remain. | +| `FI_PII_REDACTION=true` | Applies pattern-based PII redaction to recorded strings. | + +Error-message suppression requires `fi-instrumentation-otel>=1.2.3`, installed above. Leave `FI_HIDE_ERROR_DETAILS` unset or set it to `true`; do not override it with `FI_HIDE_ERROR_DETAILS=false` or `TraceConfig(hide_error_details=False)`. Those overrides can expose response content in exception messages and `ERROR` status descriptions even when inputs and outputs are hidden. + +Media payloads, media URLs and embedding vectors are never recorded. PII redaction can also match long numeric relevance scores; set `FI_HIDE_OUTPUTS=true` if you do not need scores in traces. + +## Hosts and `base_url` + +The instrumentor never sets `base_url`. The Voyage client chooses the host from the key (keys created in MongoDB Atlas go to `ai.mongodb.com`, Voyage platform keys to `api.voyageai.com`); a `base_url` you pass to the client wins. A key sent to the wrong host fails in the client, the span records that error, and nothing retries elsewhere. + +## Troubleshooting + +- **No Voyage spans after installing `traceAI-openai`.** That package cannot see `voyageai.Client`. Install `traceAI-voyage`. +- **Token counts look doubled.** Another instrumentation that wraps the same Voyage call also records usage; disable one. +- **Texts missing on embedding spans.** They are off by default; pass `capture_content=True`. +- **No `multimodal_embed` or `contextualized_embed` spans.** Upgrade `traceAI-voyage` to the version in the install step. +- **Atlas key fails on `api.voyageai.com`.** Pass the host you need as `base_url` when building the client.