Metadata-Version: 2.4
Name: qontain
Version: 0.1.0
Summary: SDK for agents running under the qontain runtime: broker client and agent server
Author-email: Albin <albin@albyte.ai>
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/albyte-ai/qontain
Project-URL: Repository, https://github.com/albyte-ai/qontain
Project-URL: Issues, https://github.com/albyte-ai/qontain/issues
Keywords: ai,agents,sandbox,llm,broker,qontain
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
License-File: NOTICE
Dynamic: license-file

# qontain (Python SDK)

For agents running under the qontain runtime. Standard library only, Python 3.10+.

- `Broker`: calls brokered tools, sends messages on declared wires, and builds
  egress URLs. Broker refusals raise typed errors.
- `Agent`: HTTP server for the agent's ports, with `/health` built in and a
  receiver for each wire channel.

```python
from qontain import Agent, Broker, BudgetExceeded, PolicyDenied

broker = Broker.from_env()  # QONTAIN_BROKER, optional QONTAIN_BROKER_TOKEN
agent = Agent("researcher", port=8080)

@agent.route("/research")
def research(body):
    try:
        hits = broker.call_tool("web-search", {"q": body["topic"]})
    except BudgetExceeded:
        return {"error": "tool budget used up"}
    broker.send("findings", {"topic": body["topic"], "hits": hits})
    return {"ok": True}

@agent.channel("reviews")
def on_review(message, source_agent):
    return {"ack": True}

agent.serve()
```

LLM SDKs need no changes: qontain sets `ANTHROPIC_BASE_URL` and
`OPENAI_BASE_URL` to the broker. For other APIs use
`broker.egress_url("api.example.com", "v1/items")`.

| Error | Broker status | Meaning |
|---|---|---|
| `BrokerAuthError` | 401 | Missing or wrong `QONTAIN_BROKER_TOKEN` |
| `PolicyDenied` | 403 | Host, tool or channel not allowed for this agent |
| `ReplayDivergence` | 409 | Strict replay has no recorded response to this request (`detail["differed"]` says why) |
| `ReplayExhausted` | 410 | No more recorded responses in replay mode |
| `SchemaViolation` | 422 | Message fails the wire's JSON schema (`detail` has the reason) |
| `BudgetExceeded` | 429 | Token, cost or tool-call budget used up |
| `ToolUnavailable` | 501 | No backend registered for the tool on the host |
| `UpstreamError` | 502 | Tool backend or receiving agent failed |
| `BrokerUnavailable` | 503 | Circuit breaker tripped |

All of these subclass `BrokerDenied` (`is_denial` is true) and `BrokerError`,
which is also raised as-is for error statuses that did not come from broker
policy. `BrokerTransportError` (`status` is `None`) means the broker could not be
reached or did not answer within `timeout`; `Broker.from_env()` raises
`BrokerNotConfigured` (also a `RuntimeError`) when `QONTAIN_BROKER` is unset.

The broker token is sent as `X-Qontain-Token`, so `Authorization` stays free for
the agent's own API keys. `call_tool(name)` with no arguments sends JSON `null`.

A channel receiver runs only for deliveries the broker signed with this
agent's `QONTAIN_WIRE_KEY` (set by qontain; `Agent(..., wire_key=...)`
overrides it) within the last 300 seconds and not seen before; anything else
gets 401, so a local process posting to the agent's port cannot pose as
another agent. Without a key every delivery is refused. Plain routes are not
signed: anything that can reach the port can call them.

`Agent` routes on the path without its query string, answers request bodies
over 8 MiB with 413 and a bad `Content-Length` with 400. Raise
`AgentError(status, message)` from a handler to reply with that status; any
other exception is logged (logger `qontain.agent`) and the caller gets a 500
with a generic message.

The three SDKs side by side:

| | Python | TypeScript | Rust (`qontain-sdk`) |
|---|---|---|---|
| Request handler | `@agent.route(path)` | `agent.route(path, fn)` | `AgentBuilder::handler(path, fn)` |
| Wire receiver | `@agent.channel(name)` | `agent.channel(name, fn)` | `AgentBuilder::channel(name, fn)` |
| Handler failure | `raise AgentError(status, msg)` | `throw new AgentError(status, msg)` | return `Err(AgentError::new(status, msg))` |
| Bind, then serve | `agent.server(host, port)` | `await agent.listen(port, host)` | `agent.bind().await?` then `.serve()` |
| Denial check | `isinstance(e, BrokerDenied)` / `e.is_denial` | `e instanceof BrokerDenied` / `e.isDenial` | `BrokerError::Denied` / `e.denial()` |
| Transport failure | `BrokerTransportError` | `BrokerTransportError` | `BrokerError::Transport` |
| No broker configured | `BrokerNotConfigured` | `BrokerNotConfigured` | `BrokerError::NotConfigured` |

Python and TypeScript raise one class per denial status; Rust uses
`BrokerError::Denied { kind: DenialKind, .. }`.

Tests: `PYTHONPATH=src python -m unittest discover -s tests`
