Metadata-Version: 2.4
Name: refario-sdk
Version: 0.1.3
Summary: Refario Python telemetry SDK for LLM run and span ingestion
Author: Refario
License: MIT
Keywords: refario,sdk,telemetry,observability,llm,ingestion,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Python SDK

Refario Python ingestion SDK package: `refario-sdk`.
This package publishes Refario telemetry helpers for LLM run/span ingestion and MCP telemetry emission from Python services.

## Install

```bash
pip install refario-sdk
```

## Usage

```python
from refario_sdk import refario

client = refario.init(
    endpoint="http://localhost:3000",
    api_key="YOUR_API_KEY",
)

run = client.start_run(workflow="example-workflow", environment="prod")

run.llm_call(
    name="openai-call",
    provider="openai",
    model="gpt-4o",
    status="success",
    prompt_tokens=120,
    completion_tokens=80,
    latency_ms=900,
)

run.end(success=True)
```

`timeout_seconds` must be positive and finite for both `RefarioClient` and
`McpTelemetryEmitter`. NaN, infinities, zero, and negative values raise `ValueError`.

### Customer and feature attribution

```python
run = client.start_run(
    workflow="document-summary",
    customer_id="cus_123",
    workspace_id="workspace_45",
    feature_id="document_summary",
)

run.llm_call(name="summarize", provider="openai", model="gpt-5-mini")
run.end(success=True)
```

All attribution fields are optional. Unknown customer and feature identifiers create
project-scoped placeholder records in Refario.

## MCP helper

```python
from refario_sdk import create_mcp_telemetry_emitter

mcp = create_mcp_telemetry_emitter(
    endpoint="http://localhost:3000",
    api_key="YOUR_API_KEY",
    default_workflow="mcp-session",
    default_environment="production",
    default_transport="http",
)

session = mcp.start_session(session_id="session_123", request_id="req_abc")
session.tool_call(
    tool_name="search_docs",
    correlation_id="req_abc",
    invocation_id="inv_123",
    retry_count=1,
)
session.tool_result(
    tool_name="search_docs",
    correlation_id="req_abc",
    invocation_id="inv_123",
    retry_count=1,
    latency_ms=120,
)
session.tool_error(
    tool_name="search_docs",
    correlation_id="req_abc",
    invocation_id="inv_123",
    retry_count=2,
    failure_type="timeout",
    error="Timed out after 30s",
)
session.flush(success=True)
```

## TS-Style Compatibility Helpers

- `refario.init({ "endpoint": "...", "apiKey": "..." })`
- `client.startRun({ "workflow": "...", "environment": "..." })`
- `run.llmCall({ ... })`, `run.toolCall({ ... })`, `run.chainCall({ ... })`
- `create_mcp_telemetry_emitter({ "endpoint": "...", "apiKey": "..." })`
- `mcp.startSession({ ... })`, `session.toolCall({ ... })`, `session.toolResult({ ... })`

For `mcp.startSession`, `session.toolCall`, `session.toolResult`, and `session.toolError`,
if both naming styles are supplied for the same field, the canonical snake_case value wins.
Input mappings are not modified, and unknown fields still raise `TypeError`.

## Local tests

From the repository root, run `npm run validate:python-sdk`.

From `python-sdk/`:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -p "test_*.py"
```

## Local package checks

From repo root:

```bash
python3 -m pip install --upgrade build twine
PYTHONPATH=python-sdk/src python3 -m unittest discover -s python-sdk/tests -p "test_*.py"
python3 -m build python-sdk
python3 -m twine check python-sdk/dist/*
```

## Release process

1. Bump version in `python-sdk/pyproject.toml`.
2. Commit and push to `main`.
3. Create and push a release tag matching the package version (for example `python-sdk-v0.1.0`):

```bash
git tag python-sdk-v<version>
git push origin python-sdk-v<version>
```

The `Release Python SDK` GitHub Action publishes to PyPI when the tag is pushed.
You can also run the workflow manually via `workflow_dispatch` and optionally select a
version bump (`patch`, `minor`, `major`, or `custom`) before publishing.

## Required GitHub secret

- `PYPI_API_TOKEN` with publish access to the `refario-sdk` package on PyPI.
