Metadata-Version: 2.4
Name: alloy-runtime-sdk
Version: 0.2.100
Summary: Python SDK for Alloy Runtime - client, pipeline, and logging
Keywords: alloy,api,client,python,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: httpx==0.28.1
Requires-Dist: pydantic==2.12.5
Requires-Dist: structlog==25.5.0
Requires-Dist: alloy-runtime-types==0.2.100
Requires-Dist: uuid-extension==0.2.0
Requires-Dist: psycopg[binary]==3.3.3

# alloy-runtime-sdk

Python SDK for Alloy Runtime.

## Install

```bash
pip install alloy-runtime-sdk
```

## Quick start

```python
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:

```python
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:

```python
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:

```python
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.

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

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.
