orloj — Official Python SDK

Typed Python client for the Orloj v1 REST API: synchronous and asynchronous usage (httpx), Pydantic v2 models, SSE watch streams, cursor-based pagination, tasks.run(wait=True) with typed output, and a small graph-as-code authoring layer.

Requirements

• Python 3.10+

Install

From PyPI (with uv):

uv add orloj-sdk

Then import the orloj_sdk package (from orloj_sdk import OrlojClient). pip install orloj-sdk works too.

From a git checkout:

uv sync

Configuration

The client reads defaults from the environment (same order as orlojctl):

If unset, the base URL defaults to http://127.0.0.1:8080 and the namespace defaults to default. HTTP max_retries defaults to 3 for production-friendly transient failure handling.

Quickstart

from orloj_sdk import OrlojClient

client = OrlojClient(api_token="your-token")
who = client.auth.whoami()
print(who.authenticated, who.username)

for agent in client.agents.list_all():
    print(agent.metadata.name)

Run a task and wait

from pydantic import BaseModel
from orloj_sdk import OrlojClient

class Answer(BaseModel):
    summary: str

client = OrlojClient(api_token="your-token")
answer = client.tasks.run(
    name="job-1",
    system="demo-pipeline",
    input={"query": "hello"},
    wait=True,
    output_type=Answer,
    output_key="result",
)
print(answer.summary)

Author a system in Python

from orloj_sdk import OrlojClient
from orloj_sdk.authoring import agent, edge, node, system

@agent("researcher", model_ref="default-model")
def researcher() -> None:
    """Research the query and list key facts."""

pipeline = (
    system("demo-pipeline")
    .add_agent(researcher)
    .set_graph({"researcher": node()})
)
pipeline.apply(OrlojClient(api_token="your-token"))

Async

from orloj_sdk import AsyncOrlojClient

async with AsyncOrlojClient(api_token="your-token") as client:
    page = await client.agents.list(limit=20)

Durability

Orloj durability (leases, retries, idempotency, dead-letter) lives in the server. See docs/durability.md for guarantees, terminal phases, production server baseline, and SDK wait defaults. Temporal interop is intentionally deferred — Orloj remains the control-plane identity.

OpenAPI sync

The SDK vendors Orloj’s OpenAPI under openapi/ (see openapi/PIN.json). CI fails if:

• hand-written models lag schema properties (scripts/check_schema_parity.py), or
• generated models under src/orloj_sdk/models/_generated/ are stale (scripts/generate_models.py).

Workflow: sync from orloj → regenerate → fix parity → commit. Details in CONTRIBUTING.md.

API surface

Resource accessors on OrlojClient / AsyncOrlojClient:

Examples

Runnable scripts (require a running Orloj API):

export ORLOJ_API_TOKEN=...
uv run python examples/quickstart.py

Development

See CONTRIBUTING.md for setup, checks, and pull request expectations.

uv sync
uv run ruff check src/orloj_sdk tests examples
uv run ruff format src/orloj_sdk tests examples
uv run mypy src/orloj_sdk
uv run pytest --cov=orloj_sdk

License

Apache-2.0