kyrodb 1.0.1

Python SDK for KyroDB, the freshness-aware context runtime for AI systems.

KyroDB Python SDK

Typed Python client for KyroDB, the freshness-aware context runtime for AI systems.

KyroDB fixes stale agent context by serving retrieval through an explicit freshness, invalidation, trace, proof, and replay contract. This SDK is intentionally only a client for a running KyroDB Runtime. It does not implement vector search, local caching, freshness proofs, or planner logic in Python.

Install

pip install kyrodb

For local development from this repository:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Quickstart

from kyrodb import KyroDBClient, Scope

client = KyroDBClient(
    base_url="https://runtime.example.com",
    data_plane_token="data-plane-token",
    observability_token="observability-token",
)

packet = client.retrieve(
    query_embedding=[1.0, 0.0, 0.0, 0.0],
    scope=Scope(tenant_id="acme", namespace="kb"),
    top_k=3,
    freshness_mode="balanced",
)

trace = client.observability.get_trace(packet.trace_id)
diagnosis = client.observability.diagnose_trace(packet.trace_id)

For production apps that load credentials from environment variables:

client = KyroDBClient.from_env()

from_env() reads KYRO_RUNTIME_URL, KYRO_DATA_PLANE_TOKEN, optional KYRO_OBSERVABILITY_TOKEN, and optional KYRO_SHADOW_SESSION_ID.

Security Defaults

• HTTPS is required for non-loopback hosts unless allow_insecure_http=True is explicit.
• Redirects are disabled by default to prevent replaying captured documents or bearer tokens to another origin.
• Data-plane and observability/admin tokens are separate by default.
• Tokens are never included in repr, logs, or SDK exceptions.
• Data-plane-only clients cannot access client.observability or client.admin until an observability token is configured.
• Side-effecting calls are not retried automatically because retrieval and mutations write trace, replay, and freshness evidence.
• Responses are read through a bounded stream to protect callers from unbounded memory use.
• Requests are preflighted against the runtime's default body, top_k, embedding, metadata, filter, replay, and recent limits before they leave the process.
• Shadow-session IDs are validated before being sent as kyro-shadow-session-id.

API Shape

Data-plane methods live on KyroDBClient:

• retrieve
• invalidate
• ingest_change_event
• upsert_document
• delete_document
• record_feedback

Observability methods live under client.observability:

• get_feedback
• get_trace
• diagnose_trace
• health
• context_proof_report

Admin/evidence methods live under client.admin:

• build_proof_bundle
• build_root_cause_report
• diff_replay_runs
• run_counterfactual_replay
• create_shadow_session
• export_replay_capture

Async parity is available through AsyncKyroDBClient.

Counterfactual replay and replay diff calls use typed request models at the SDK boundary while keeping replay artifacts as forward-compatible JSON objects:

from kyrodb import CounterfactualIntervention, CounterfactualReplayScenario

capture = client.admin.export_replay_capture(recent=50)
scenario = CounterfactualReplayScenario(
    name="drop retry noise",
    interventions=[CounterfactualIntervention.drop_step(0)],
)
summary = client.admin.run_counterfactual_replay(capture=capture, scenario=scenario)

Shadow replay workflows can pass the server-returned session ID explicitly:

shadow = KyroDBClient(
    base_url="https://candidate-runtime.example.com",
    data_plane_token="candidate-data-token",
    observability_token="candidate-observability-token",
    shadow_session_id="session-id-from-create-shadow-session",
)

Development

python -m pytest
python -m ruff format .
python -m ruff check .
python -m mypy src/kyrodb
python scripts/check_release.py --no-build

Optional live tests should be wired to a running KyroDB Runtime with:

• KYRO_RUNTIME_URL
• KYRO_DATA_PLANE_TOKEN
• KYRO_OBSERVABILITY_TOKEN
• KYRO_LIVE_TESTS=1

KYRO_LIVE_TESTS=1 python -m pytest -m live

You can point the live tests at a seeded fixture with KYRO_TEST_TENANT_ID, KYRO_TEST_NAMESPACE, and KYRO_TEST_QUERY_EMBEDDING.

Examples

The examples/ directory contains small production-shaped flows:

• retrieve.py: retrieve fresh context and print trace evidence identifiers.
• trace_diagnosis.py: inspect why a trace was stale, degraded, or fresh.
• proof_bundle.py: build a redacted proof bundle from retained replay evidence.
• design_partner_shadow.py: create a candidate shadow session from replay primer state.

Release

Release candidates must pass the full local gate in RELEASE.md, including build artifact validation and the optional runtime-dependency audit via python -m pip_audit ..