courier-os

Python agent framework for OpenAI-compatible APIs, with optional local Apple Silicon inference via courier-os-binary.

Install: pip install courier-os
Import: import courier_os

Dual mode

Credentials resolve from args or env: COURIER_OS_API_KEY / COURIER_OS_BASE_URL, then OPENAI_API_KEY / OPENAI_BASE_URL.

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)

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