Metadata-Version: 2.4
Name: custodia-sdk
Version: 0.1.0
Summary: Custodia tracing SDK
Author: ssabrut
Author-email: ssabrut <michael.gunawan2002@gmail.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: httpx>=0.28.1
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.44.0
Requires-Dist: opentelemetry-sdk>=1.44.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# custodia-sdk

Python tracing SDK for Custodia. Instruments function calls as OpenTelemetry
spans and exports them via OTLP/HTTP.

> **License:** proprietary. Use requires a paid commercial license from
> Neurona. See [LICENSE](./LICENSE). Contact michael.gunawan2002@gmail.com
> to obtain one.

## Install

```bash
pip install custodia-sdk
# or
uv add custodia-sdk
```

## Configuration

Set via environment variables:

| Variable | Description | Default |
|---|---|---|
| `CUSTODIA_INGEST_URL` | OTLP/HTTP traces endpoint | `http://localhost:4318/v1/traces` |
| `CUSTODIA_API_KEY` | Bearer token sent with exported spans | *(none)* |
| `CUSTODIA_SERVICE_NAME` | `service.name` resource attribute | `unknown-service` |

## Usage

```python
from custodia import trace, trace_async, trace_span, atrace_span

@trace(name="fetch_user", metadata={"component": "db"})
def get_user(user_id: str):
    return db.query(user_id)

@trace_async(name="call_llm")
async def generate(prompt: str) -> str:
    return await llm_client.complete(prompt)

with trace_span("parse_response") as span:
    data = json.loads(raw)
    span.set_attribute("record_count", len(data))

async with atrace_span("call_downstream") as span:
    resp = await http_client.get(url)
    span.set_attribute("http.status_code", resp.status_code)
```

- `trace` / `trace_async`: decorators that auto-capture args/return value as
  `gen_ai.prompt` / `gen_ai.completion` span attributes.
- `trace_span` / `atrace_span`: context managers for manual span control,
  no automatic I/O capture.
