Metadata-Version: 2.4
Name: meridian-ai
Version: 0.1.0
Summary: Python SDK for Meridian, an AI observability product.
Author: Meridian
Maintainer: Meridian
License: MIT License
        
        Copyright (c) 2026 Meridian
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/meridian-ai/meridian-ai-python
Project-URL: Documentation, https://github.com/meridian-ai/meridian-ai-python#readme
Project-URL: Source, https://github.com/meridian-ai/meridian-ai-python
Project-URL: Issues, https://github.com/meridian-ai/meridian-ai-python/issues
Keywords: meridian,ai,observability,sdk,telemetry,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# 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`

```python
import meridian_ai
from meridian_ai import Meridian
```

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

## Installation

```bash
pip install meridian-ai
```

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

## Quick start

```python
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.

| Argument     | Environment variable   | Required for submission |
|--------------|------------------------|-------------------------|
| `endpoint`   | `MERIDIAN_ENDPOINT`    | yes                     |
| `project_id` | `MERIDIAN_PROJECT_ID`  | yes                     |
| `api_key`    | `MERIDIAN_API_KEY`     | no                      |

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

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

```python
from meridian_ai import Meridian

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

### Explicit configuration

```python
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.

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

All metadata is optional:

```python
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.

```python
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()`:

```python
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:

```python
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

```bash
git clone <repository-url>
cd meridian-ai

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

pip install -e ".[dev]"
pytest
```

Build distributions:

```bash
python -m build
```

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

## License

MIT — see [LICENSE](LICENSE).
