Moda SDK for Python

The Moda SDK for Python (moda-ai) auto-instruments the OpenAI and Anthropic client libraries: after one moda.init() call, every LLM request, response, streamed completion, and tool call is captured and sent to Moda without changes to your provider code. This page covers installation, configuration, provider coverage, and conversation context.

Prerequisites

Python 3.10 or later
A Moda API key, created at Settings → Ingestion keys (see Authentication)
The openai or anthropic package your app already uses

Set up

Install the SDK

pip install moda-ai

The package installs as moda-ai but imports as moda. Instrumentation for OpenAI and Anthropic is bundled — no extra packages are needed for these two providers.

Initialize and make a call

Call moda.init() once at startup, before your app makes LLM calls. Initialization is synchronous.

app.py

import os

import moda
from openai import OpenAI

moda.init(api_key=os.environ["MODA_API_KEY"])

client = OpenAI()

moda.conversation_id = "session_8f2a"
moda.user_id = "user_1042"

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

moda.flush()

Verify in the dashboard

Open Conversations in the dashboard. Within minutes you should see a conversation with ID session_8f2a containing the user message and the assistant response, with the model name and token counts attached.

Configuration

`moda.init()` options

import moda

moda.init(
    api_key="YOUR_MODA_API_KEY",
    app_name="support-bot",
    resource_attributes={"deployment.environment": "staging"},
)

Option	Type	Default	Description
`api_key`	`str`	`None`	Your Moda API key. Falls back to the `MODA_API_KEY` environment variable.
`app_name`	`str`	script name	Application name attached to all telemetry (OTel `service.name`).
`endpoint`	`str`	`https://moda-ingest.modas.workers.dev/v1/traces`	Ingestion endpoint URL.
`debug`	`bool`	`False`	Verbose logging; also disables batching so spans are sent immediately.
`enabled`	`bool`	`True`	Set `False` to disable instrumentation entirely (no data is captured or sent).
`disable_batch`	`bool`	`False`	Send each span immediately instead of batching. Useful for short-lived scripts.
`headers`	`dict`	`{}`	Custom exporter headers. When set, they replace the default `Authorization: Bearer` header.
`resource_attributes`	`dict`	`{}`	Extra resource attributes. Set `deployment.environment` here to tag events as `development`, `staging`, or `production`.
`instruments`	`set[Instruments]`	`None` (all)	Allowlist of instrumentations to enable. See Selecting instrumentations.
`block_instruments`	`set[Instruments]`	`None`	Instrumentations to disable.

Advanced OpenTelemetry options

For custom OpenTelemetry pipelines, moda.init() also accepts exporter (a custom SpanExporter), processor (a SpanProcessor or list of them), propagator, sampler, and span_postprocess_callback. When exporter or processor is set, spans are exported through your components instead of Moda’s default OTLP exporter.

Environment variables

Variable	Description
`MODA_API_KEY`	Your Moda API key.
`MODA_BASE_URL`	Overrides the ingestion endpoint.
`MODA_HEADERS`	Custom exporter headers; replaces the default `Authorization` header.

Environment variables take precedence over arguments passed to moda.init(). If MODA_API_KEY or MODA_BASE_URL is set in the process environment, it overrides the api_key and endpoint arguments.

What gets instrumented

moda.init() patches the provider client libraries. Anything your app does through them is captured, including streaming. OpenAI (openai package, sync and async clients):

Chat Completions — create and parse, including streaming and tool calls
Responses API — create, retrieve, cancel
Legacy Completions
Embeddings
Image generation
Assistants API (assistants, threads, runs)
Realtime API — sessions opened through beta.realtime.connect()

Anthropic (anthropic package, sync and async clients):

Messages — create and stream, including tool use and extended thinking
Beta Messages
Legacy Completions
The AnthropicBedrock client, so Claude called through Amazon Bedrock is captured

Provider detection for OpenAI-compatible endpoints

When you point the OpenAI client at a different base_url, the SDK detects the vendor from the URL and records it as the provider:

`base_url` contains	Provider recorded
`openai.azure.com`	`Azure`
`openrouter.ai`	`OpenRouter` (the `provider/` prefix is stripped from model names)
`amazonaws.com` or `bedrock`	`AWS` (cross-region model IDs such as `us.anthropic...` are normalized to the base model name)
`googleapis.com` or `vertex`	`Google`
anything else	`openai`

Other OpenAI-compatible endpoints (for example Groq) are still fully captured — requests, responses, and token usage — but are recorded with provider openai.

openrouter.py

import os

import moda
from openai import OpenAI

moda.init(api_key=os.environ["MODA_API_KEY"])

openrouter = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

moda.conversation_id = "session_8f2a"

response = openrouter.chat.completions.create(
    model="anthropic/claude-3-haiku",
    messages=[{"role": "user", "content": "Hello!"}],
)

moda.flush()

Supported providers

Provider	Support
OpenAI	Supported — instrumentation bundled with `moda-ai`
Anthropic	Supported — instrumentation bundled with `moda-ai`
Azure OpenAI	Supported through the OpenAI client with an Azure `base_url`
OpenRouter	Supported through the OpenAI client with the OpenRouter `base_url` — see OpenRouter
Claude on Amazon Bedrock	Supported through the `AnthropicBedrock` client — see Bedrock
Bedrock via `boto3`	Requires installing `opentelemetry-instrumentation-bedrock` separately
Claude Agent SDK	Supported through the separate `moda-claude-agent-sdk` package — see Claude Agent SDK
Vapi	Supported via `moda.process_vapi_end_of_call_report` — see Vapi
Other frameworks (LangChain, LlamaIndex, and more)	The SDK activates them only if you install the matching `opentelemetry-instrumentation-<name>` package; these packages are not bundled

Conversation and user context

Set a conversation ID to group related calls into one conversation, and a user ID to attribute them to a user. Context is stored in contextvars, so it is safe in async code and threaded request handlers.

Module properties

import moda

moda.conversation_id = "support_ticket_123"
moda.user_id = "user_1042"

# ... make LLM calls ...

moda.conversation_id = None  # clear when done
moda.user_id = None

Context managers

set_conversation_id and set_user_id scope the context to a block and restore the previous value on exit — use them in concurrent request handlers:

handler.py

import os

import moda
from openai import OpenAI

moda.init(api_key=os.environ["MODA_API_KEY"])
client = OpenAI()


def handle_request(session_id: str, user_id: str, question: str) -> str:
    with moda.set_conversation_id(f"session_{session_id}"):
        with moda.set_user_id(user_id):
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": question}],
            )
    return response.choices[0].message.content

Setters and getters

from moda import (
    set_conversation_id_value,
    set_user_id_value,
    get_conversation_id,
    get_user_id,
)

set_conversation_id_value("session_123")   # persists until cleared
set_user_id_value("user_456")

print(get_conversation_id())  # "session_123"
print(get_user_id())          # "user_456"

set_conversation_id_value(None)  # clear
set_user_id_value(None)

Set the conversation ID before the first model call of a session — from your session, thread, or run ID — so every call in the session lands in one conversation.

Selecting instrumentations

By default all instrumentations are enabled, but each activates only when its target package is installed. Restrict them with instruments (allowlist) or block_instruments (blocklist):

import moda
from moda import Instruments

# Only instrument OpenAI
moda.init(api_key="YOUR_MODA_API_KEY", instruments={Instruments.OPENAI})

import moda
from moda import Instruments

# Everything except the HTTP-library instrumentations
moda.init(
    api_key="YOUR_MODA_API_KEY",
    block_instruments={Instruments.REQUESTS, Instruments.URLLIB3},
)

Available Instruments values:

Category	Values
LLM providers	`OPENAI`, `ANTHROPIC`, `BEDROCK`, `COHERE`, `GOOGLE_GENERATIVEAI`, `GROQ`, `MISTRAL`, `OLLAMA`, `REPLICATE`, `SAGEMAKER`, `TOGETHER`, `VERTEXAI`, `WATSONX`, `WRITER`, `ALEPHALPHA`, `TRANSFORMERS`
Agent frameworks	`AGNO`, `CLAUDE_AGENT_SDK`, `CREWAI`, `HAYSTACK`, `LANGCHAIN`, `LLAMA_INDEX`, `MCP`, `OPENAI_AGENTS`
Vector stores	`CHROMA`, `LANCEDB`, `MARQO`, `MILVUS`, `PINECONE`, `QDRANT`, `WEAVIATE`
Infrastructure	`PYMYSQL`, `REDIS`, `REQUESTS`, `URLLIB3`

Only the OpenAI and Anthropic instrumentation packages ship with moda-ai. All other values take effect only if you install the corresponding opentelemetry-instrumentation-<name> package yourself.

Flushing

Spans are batched and exported in the background. Call moda.flush() to force-export pending spans:

Always flush before a script or worker exits — unexported spans are lost when the process ends.
In long-running servers, flushing on shutdown is enough; the batch exporter sends data continuously while the process runs.
For very short-lived processes, pass disable_batch=True to moda.init() so each span is sent immediately.

There is no separate shutdown function in the Python SDK; moda.flush() is the only lifecycle call you need.

Troubleshooting

Symptom	Fix
Nothing appears in the dashboard	Call `moda.flush()` before the process exits. Confirm `moda.init()` runs before your first LLM call and that the API key is valid.
`Error: Missing Moda API key` printed at startup	Pass `api_key` to `moda.init()` or set `MODA_API_KEY`. The SDK prints this error and stays disabled rather than raising.
An `api_key` or `endpoint` argument seems ignored	`MODA_API_KEY` and `MODA_BASE_URL` environment variables override init arguments. Unset the variable to use the argument.
One session shows up as many conversations	Set `moda.conversation_id` (or the `set_conversation_id` context manager) before the first model call of the session.
A gateway provider shows as `openai`	Expected: URL-based detection covers Azure, OpenRouter, AWS, and Google. Other OpenAI-compatible endpoints (for example Groq) are recorded with provider `openai`.
`ModuleNotFoundError: No module named 'moda'`	Install `moda-ai` (the import name is `moda`) and confirm Python 3.10 or later.

Next steps

Claude Agent SDK — instrument agents built on claude-agent-sdk.
OpenAI and Anthropic — provider-specific setup details.
Data model — how captured messages become conversations and signals.
Reliability — delivery guarantees and limits.

Send data

SDKs

Providers

Frameworks and agents

OpenTelemetry

API reference

Moda SDK for Python

Prerequisites

Set up

Configuration

`moda.init()` options

Environment variables

What gets instrumented

Provider detection for OpenAI-compatible endpoints

Supported providers

Conversation and user context

Module properties

Context managers

Setters and getters

Selecting instrumentations

Flushing

Troubleshooting

Next steps

​Prerequisites

​Set up

​Configuration

​moda.init() options

​Environment variables

​What gets instrumented

​Provider detection for OpenAI-compatible endpoints

​Supported providers

​Conversation and user context

​Module properties

​Context managers

​Setters and getters

​Selecting instrumentations

​Flushing

​Troubleshooting

​Next steps

Prerequisites

Set up

Configuration

`moda.init()` options

Environment variables

What gets instrumented

Provider detection for OpenAI-compatible endpoints

Supported providers

Conversation and user context

Module properties

Context managers

Setters and getters

Selecting instrumentations

Flushing

Troubleshooting

Next steps