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

pip install refario-sdk

Usage

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

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

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/:

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

Local package checks

From repo root:

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):

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.