relivio-sdk 0.2.0

Python SDK for Relivio deploy registration, log ingestion, and minimal latest verdict reads.

relivio-sdk-python

Thin Python SDK for Relivio deploy registration, log ingestion, and one minimal latest verdict read for service-side guard flows.

PyPI · GitHub

Status

• current package scope: 0.2.0
• supported Python versions: 3.9+
• current public surface:
  • deployments.register()
  • deployments.register_from_environment()
  • ingest.send()
  • ingest.send_batch()
  • verdicts.latest()
  • capture.install_unhandled()
  • stats()
• automatic retry only for 429 RATE_LIMITED

Non-goals

• full verdict consumer surface
• feedback/history/list/search APIs
• framework integration
• guard or middleware
• broad auto instrumentation or metric collection

Installation

pip install relivio-sdk

Verify the installed package:

python -c "import relivio; print(relivio.__all__)"

For local development:

pip install -e ".[dev]"

Quick Start

from relivio import Relivio, IngestLogInput

relivio = Relivio(api_key="rk_...")

deployment = relivio.deployments.register(version="1.2.3")
print(deployment.id)

result = relivio.ingest.send(
    IngestLogInput(
        level="ERROR",
        message="checkout failed",
        api_path="/api/orders/finalize",
    )
)
print(result.log_event_id)

verdict = relivio.verdicts.latest()
if verdict is not None:
    print(verdict.verdict, verdict.decision_tier)

Opt into cold-path exception capture when you want raw error events to be sent without adding request-path measurement:

from relivio import CaptureUnhandledOptions

installation = relivio.capture.install_unhandled(
    CaptureUnhandledOptions(
        service="checkout-api",
        capture_threading_exceptions=True,
    )
)

print(relivio.stats())

# Later, during shutdown or test cleanup:
installation.dispose()

Async Example

import asyncio
from relivio import Relivio, RegisterDeploymentInput

relivio = Relivio(api_key="rk_...")

async def main() -> None:
    deployment = await relivio.deployments.aregister(
        RegisterDeploymentInput(version="1.2.3")
    )
    print(deployment.id)

asyncio.run(main())

Development

python -m venv .venv
./.venv/bin/pip install -e ".[dev]"
./.venv/bin/pytest
./.venv/bin/python -m build

Behavior Notes

• API key is sent through X-API-Key
• Idempotency-Key is supported for v0 writer endpoints
• 429 responses are retried with Retry-After
• 5xx responses are not retried
• server can accept gzip payloads, but SDK v0 sends plain JSON only
• verdicts.latest() is intentionally narrow and only exists to support service-side guard logic
• verdicts.latest() returns None on 404 when a verdict is not available yet
• capture.install_unhandled() chains cold-path exception hooks; it does not replace existing handlers
• stats() reports SDK self-diagnostics locally; it does not send host metrics to Relivio

Related Repos

• relivio-server: server-side deploy registration, ingest, and summary generation
• relivio-mcp: agent-facing verdict consumer surface

Security

Do not commit project API keys. Keep X-API-Key values in environment variables or local secret storage outside source control.

Contributing

Small, behavior-preserving changes are preferred. Keep transport, resource, type, and error responsibilities separate, and run the smallest effective test/build checks before sending a change.