Courier OS SDK

The Courier OS SDK offers robust tools for building programmatic agents in Python using OpenAI-compatible APIs or for licensed builders running local agents on Apple Silicon using our proprietary and industry leading infrastructure.

Install: uv add courier-os or pip install courier-os
Import: import courier_os

Dual mode

from courier_os import Model, Agent, Operator, tools

@tools.tool
def get_weather(city: str) -> dict:
    """Get weather for a city."""
    return {"city": city, "temp_f": 72}

# Cloud / any OpenAI-compatible endpoint
model = Model("gpt-4o", api_key="…", base_url="https://api.openai.com/v1")

# Or local MLX (requires courier-os-binary on Apple Silicon)
# model = Model("mlx-community/Qwen3.5-2B-MLX-8bit", mode="local")
# if not model.can_load:
#     model = Model("gpt-4o", api_key="…", base_url="…")

agent = Agent(model, tools=[get_weather])
messages = [{"role": "user", "content": "Weather in Denver?"}]

# Agent — one model turn (you handle tool_calls if present)
resp = agent.chat(messages)
if resp.tool_calls:
    messages.append({"role": "assistant", "content": resp.content, "tool_calls": resp.tool_calls})
    messages.extend(agent.call_tools(resp.tool_calls))
    resp = agent.chat(messages)
print(resp.content)

# Operator — auto tool loop until the model finishes
out = Operator(agent).run([{"role": "user", "content": "Weather in Denver?"}])
print(out.content)

Register tools mid-loop

Pass a Session and tools=session.tools, then event.register_tool(...) from an intercept. New tools are available on the next Operator iteration:

from courier_os import Agent, Model, Operator, Session, tools

@tools.tool
def list_tools() -> list[dict]:
    """Discover available tools."""
    return [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }]

@tools.tool
def get_weather(city: str) -> dict:
    """Get weather for a city."""
    return {"city": city, "temp_f": 72}

IMPLS = {"get_weather": get_weather}

def unlock(event):
    for tc in event.tool_calls:
        if tc.name == "list_tools":
            for spec in tc.result or []:
                name = spec["function"]["name"]
                if name in IMPLS:
                    event.register_tool(IMPLS[name])

session = Session.open(tools=[list_tools])
agent = Agent(Model("gpt-4o", api_key="…", base_url="…"), tools=session.tools)
out = Operator(agent, on_intercept=unlock).run(
    [{"role": "user", "content": "List tools, then weather in Denver."}],
    session=session,
    tools=session.tools,
)

HTTP relay

from courier_os import relay

out = relay(
    model="gpt-4o",
    messages=[{"role": "user", "content": "hi"}],
    api_key="…",
    base_url="https://api.openai.com/v1",
    tools=[get_weather],
).response

Multimodal messages

OpenAI-shaped image/audio content parts work on both paths (local omni models extract media before inference):

messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,…"}},
    ],
}]
Operator(agent).run(messages)

Local runtime

Local inference lives in the proprietary courier-os-binary package (not on public PyPI yet). In this monorepo:

cd playground && uv sync

That editable-installs courier-os → courier-os-binary.

Docs

• Getting started
• Architecture