alloy-runtime-sdk 0.2.109

Python SDK for Alloy Runtime - client, pipeline, and logging

alloy-runtime-sdk

Python SDK for Alloy Runtime.

Install

pip install alloy-runtime-sdk

Quick start

from alloy_runtime_sdk.api_client.client import ApiClient

async def main() -> None:
    async with ApiClient(
        base_url="https://your-alloy-runtime-host",
        api_key="your_api_key",
    ) as client:
        models = await client.list_models()
        print(models)

What it includes

• Authenticated HTTP client methods for the Alloy Runtime API.
• Pipeline runtime helpers for Python-based pipeline steps.
• Structured logging helpers used by runtime integrations.

Logging

SDK logging is pretty, human-readable text by default:

from alloy_runtime_sdk.logging.config import LogConfig, LogLevel, configure, get_logger

configure(LogConfig(level=LogLevel.DEBUG))
logger = get_logger()

Use JSON Lines explicitly for files, CI, and log shippers:

from alloy_runtime_sdk.logging.config import LogConfig, LogFormat, configure

configure(LogConfig(format=LogFormat.JSONL, output_file="logs/sdk.jsonl"))

SDK logs stay compact: the logging formatter does not add default environment, service, resource, or process-level session_id fields, and successful HTTP responses are not logged. HTTP response logs are emitted only for error responses.

JSON to Markdown helper

Convert JSON-like Python values into LLM-readable Markdown prompt context:

from alloy_runtime_sdk.markdown import json_to_markdown

markdown = json_to_markdown(
    {"customer": {"name": "Ada", "plan": "enterprise"}},
    title="Customer Context",
)

Nested dictionaries become Markdown headings, leaves become key/value lines, and list-of-dictionary values can render as Markdown tables. See docs/sdk/json_to_markdown.md for options.

Local pipeline runner

The SDK supports both Hosted execution and SDK local execution for pipelines.

Use python -m alloy_runtime_sdk.pipeline.local_runner to run a local pipeline module against a hosted Alloy Runtime, or call run_local_pipeline() directly from Python. Local runs return both the stable pipeline_execution_id and active attempt_id/epoch; rerun with the same execution ID to continue the logical workflow.

See docs/pipelines/local_testing.md for the full workflow and examples.

Inspect compact execution live state without querying the database:

execution_state = await client.get_execution_live_state(execution_id)
pipeline_state = await client.get_pipeline_execution_live_state(
    pipeline_id,
    execution_id,
)

Use these methods for current status/progress polling. Use get_execution(...) for the durable model-execution transcript and get_pipeline_execution(...) for durable pipeline result, stdout/stderr, failure context, and generation-step detail.

Hosted pipeline executions can be cancelled through the API client:

await client.cancel_pipeline_execution(pipeline_id, execution_id)

Cancellation marks Alloy's execution record cancelled first; hosted provider shutdown and child generation cancellation are handled by the server best-effort.

The SDK depends on alloy-runtime-types, which is published separately for stable, versioned cross-package compatibility.

Hard-cut API migration

Use this SDK with the matching alloy-runtime-types version. Generation requests now use canonical model / agent_id, flat model_options, flat extra_headers, and canonical result.model response identity. See docs/generate/hardcut_migration.md before updating older SDK or pipeline code.