Meridian AI SDK

Python SDK for Meridian, an AI observability product. The SDK collects trace events from your AI application and sends them to the Meridian backend for storage and analysis.

• PyPI install name: meridian-ai
• Python import package: meridian_ai

import meridian_ai
from meridian_ai import Meridian

[!NOTE] This project is in early development. The public API may change.

Installation

pip install meridian-ai

Requires Python 3.9 or newer. The SDK has no required third-party dependencies.

Quick start

from meridian_ai import Meridian

meridian = Meridian()

with meridian.trace("my-ai-request"):
    result = my_application()

meridian.flush()

With no configuration the client is disabled: trace(...) still runs so your instrumentation never breaks the application, and flush() sends nothing until an endpoint and project are configured.

Configuration

endpoint, project_id, and api_key can be passed explicitly or read from the environment. Explicit arguments always take precedence; the environment is only consulted for arguments you omit.

The project_id refers to an existing Meridian project. Projects are created and managed in the Meridian web application, never from the SDK.

Environment variables

export MERIDIAN_ENDPOINT="https://meridian.example.com"
export MERIDIAN_PROJECT_ID="my-project"
export MERIDIAN_API_KEY="your-api-key"

from meridian_ai import Meridian

meridian = Meridian()  # reads MERIDIAN_* from the environment

Explicit configuration

from meridian_ai import Meridian

meridian = Meridian(
    endpoint="https://meridian.example.com",  # placeholder; use your endpoint
    project_id="my-project",
    api_key="your-api-key",                   # optional; sent as a Bearer token
    ingest_path="/v1/traces",                 # configurable; this is the default
    timeout=10.0,                             # seconds
)

The API key is stored privately and never appears in logs, repr(), or error messages.

Basic tracing

Wrap a block of work in meridian.trace(...). The trace records its start time, end time, and latency, and is marked successful or failed automatically.

with meridian.trace("customer-question"):
    answer = run_pipeline(question)

All metadata is optional:

with meridian.trace(
    "customer-question",
    model="example-model",
    provider="example-provider",
    input_tokens=120,
    output_tokens=48,
    metadata={"conversation_id": "abc123"},
):
    answer = run_pipeline(question)

total_tokens is derived from input_tokens and output_tokens when you provide them; you never have to compute it yourself.

Completed traces are buffered in memory. Call meridian.flush() to send the buffered events to the Meridian backend as JSON.

meridian.flush()

Error behavior

Telemetry problems should not take down your application, so by default flush() never raises for a transport or backend failure:

• transport failures (connection errors, DNS failures) → recorded as a connection error
• timeouts → recorded as a timeout error
• backend error responses (HTTP 4xx/5xx) → recorded as an API error
• malformed responses → ignored safely

Exceptions raised inside a with meridian.trace(...) block are never swallowed — they propagate to your application unchanged, and the trace is marked as an error.

Inspect the outcome of the most recent flush():

meridian.flush()

if meridian.last_result and not meridian.last_result.ok:
    print(meridian.last_error)          # a MeridianError; never contains the api_key
    retry_later(meridian.last_result.events)

Failures are also logged on the meridian_ai logger. To make failures raise instead, enable strict mode:

meridian = Meridian(strict=True)

MeridianError is the base class for every SDK exception and is importable from the top level. The specific subclasses live in meridian_ai.exceptions.

Development

git clone <repository-url>
cd meridian-ai

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
pytest

Build distributions:

python -m build

The project uses a src-based layout and setuptools for packaging. See RELEASE.md for the step-by-step release checklist.

License

MIT — see LICENSE.