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
28 changes: 28 additions & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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];
Expand Down
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"},
Expand Down
94 changes: 94 additions & 0 deletions src/pages/docs/integrations/traceai/voyage.mdx
Original file line number Diff line number Diff line change
@@ -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.
Loading