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

## 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")
session.tool_result(tool_name="search_docs", correlation_id="req_abc", latency_ms=120)
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({ ... })`

## Local tests

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.
