autonai 1.0.0__tar.gz

autonai-1.0.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.pyc
+
+# Build / cargo
+rust/target/
+target/
+
+# AUTON local artifacts
+.auton/
+.auton-agents/
+.claude/
+.clawd-todos.json
+.omc/
+.sandbox-home/
+*.local.json
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Node
+node_modules/
+.next/
+out/
+dist/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Internal documentation (kept local, not published)
+docs-Gu-Marca/
+MV-comercial/
+r-docs-extra/
+r-integracaodocs/
+rr-arquitetura-soft-sist/
+rr-newfiles/
+auton-releases-pubkey.asc
+prompt:

autonai-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: autonai
+Version: 1.0.0
+Summary: Official Python SDK for AUTON — the operating system for AI-augmented companies.
+Project-URL: Homepage, https://getauton.ai
+Project-URL: Documentation, https://docs.getauton.ai
+Project-URL: Repository, https://github.com/caio-bessa/auton
+Author-email: AUTON <hello@getauton.ai>
+License: MIT
+Keywords: agents,ai,auton,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autonai
+
+Official Python SDK for [AUTON](https://getauton.ai) — the operating system
+for AI-augmented companies. Full docs at
+[docs.getauton.ai](https://docs.getauton.ai).
+
+```bash
+pip install autonai
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from autonai import AutonClient
+
+client = AutonClient(
+    base_url="https://api.getauton.ai",
+    api_key=os.environ["AUTON_API_KEY"],  # Settings → API keys → auton_pat_…
+)
+
+# 1. Spawn a run
+run = client.runs.spawn({
+    "agent_id": "…",
+    "company_id": "…",
+    "area_id": "…",
+    "actor_user_id": "…",
+    "domain_config": {"template_id": "marketing.performance_marketing_manager"},
+    "initial_messages": [
+        {"role": "user", "content": "Pull last week's perf data and draft a Slack update"},
+    ],
+})
+
+# 2. Stream deltas (generator; stops at the terminal delta)
+for delta in client.runs.stream(run["run_id"]):
+    print(delta["seq"], delta["kind"])
+
+# 3. Triage approvals
+inbox = client.approvals.list(status="pending")
+client.approvals.decide(inbox[0]["id"], verdict="approve", by="…user uuid…", reason="Looks good")
+```
+
+## More examples
+
+```python
+# Knowledge: upload → search → cite
+client.knowledge.upload(
+    company_id=company_id,
+    title="Brand book",
+    source="upload",
+    body="Voice: warm, direct, never jargon-heavy…",
+)
+hits = client.knowledge.search(company_id=company_id, query="brand voice")["hits"]
+
+# Billing: this month's spend vs plan cap
+usage = client.billing.usage("this_month")
+print(usage["totals"]["cost_usd_micros"] / 1e6, "USD spent")
+
+# Agent manuals: resolve with user preferences inlined
+manual = client.agent_manuals.resolve(
+    "marketing.performance_marketing_manager",
+    company_id=company_id,
+    user_preferences={"manual_tone": "concise", "preferred_locale": "pt-BR"},
+)
+
+# Heartbeats: a weekday 9am curator tick
+hb = client.heartbeats.upsert(**heartbeat_fields)
+client.heartbeats.fire_now(hb["id"])
+```
+
+## Behaviour
+
+- **Auth** — `Authorization: Bearer <api_key>` on every call.
+- **Retries** — idempotent GETs retry on 5xx/network (max 3, exponential
+  backoff). Non-idempotent calls never retry unless you pass
+  `idempotency_key=`.
+- **Rate limits** — `Retry-After` on 429 is honoured automatically; the
+  final failure raises `RateLimitError` with `.retry_after`.
+- **Errors** — typed: `ValidationError`, `AuthenticationError`,
+  `PermissionError_`, `NotFoundError`, `ConflictError`, `RateLimitError`,
+  `ServerError` — all subclassing `AutonError` with `.status` / `.request_id`.
+- **Self-hosting** — pass `orchestrator_url=` / `knowledge_url=` /
+  `approvals_url=` when those services are exposed on their own origins.
+
+Versioning follows the gateway major: `autonai==1.x` ↔ gateway `1.x`.

autonai-1.0.0/README.md

@@ -0,0 +1,87 @@
+# autonai
+
+Official Python SDK for [AUTON](https://getauton.ai) — the operating system
+for AI-augmented companies. Full docs at
+[docs.getauton.ai](https://docs.getauton.ai).
+
+```bash
+pip install autonai
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from autonai import AutonClient
+
+client = AutonClient(
+    base_url="https://api.getauton.ai",
+    api_key=os.environ["AUTON_API_KEY"],  # Settings → API keys → auton_pat_…
+)
+
+# 1. Spawn a run
+run = client.runs.spawn({
+    "agent_id": "…",
+    "company_id": "…",
+    "area_id": "…",
+    "actor_user_id": "…",
+    "domain_config": {"template_id": "marketing.performance_marketing_manager"},
+    "initial_messages": [
+        {"role": "user", "content": "Pull last week's perf data and draft a Slack update"},
+    ],
+})
+
+# 2. Stream deltas (generator; stops at the terminal delta)
+for delta in client.runs.stream(run["run_id"]):
+    print(delta["seq"], delta["kind"])
+
+# 3. Triage approvals
+inbox = client.approvals.list(status="pending")
+client.approvals.decide(inbox[0]["id"], verdict="approve", by="…user uuid…", reason="Looks good")
+```
+
+## More examples
+
+```python
+# Knowledge: upload → search → cite
+client.knowledge.upload(
+    company_id=company_id,
+    title="Brand book",
+    source="upload",
+    body="Voice: warm, direct, never jargon-heavy…",
+)
+hits = client.knowledge.search(company_id=company_id, query="brand voice")["hits"]
+
+# Billing: this month's spend vs plan cap
+usage = client.billing.usage("this_month")
+print(usage["totals"]["cost_usd_micros"] / 1e6, "USD spent")
+
+# Agent manuals: resolve with user preferences inlined
+manual = client.agent_manuals.resolve(
+    "marketing.performance_marketing_manager",
+    company_id=company_id,
+    user_preferences={"manual_tone": "concise", "preferred_locale": "pt-BR"},
+)
+
+# Heartbeats: a weekday 9am curator tick
+hb = client.heartbeats.upsert(**heartbeat_fields)
+client.heartbeats.fire_now(hb["id"])
+```
+
+## Behaviour
+
+- **Auth** — `Authorization: Bearer <api_key>` on every call.
+- **Retries** — idempotent GETs retry on 5xx/network (max 3, exponential
+  backoff). Non-idempotent calls never retry unless you pass
+  `idempotency_key=`.
+- **Rate limits** — `Retry-After` on 429 is honoured automatically; the
+  final failure raises `RateLimitError` with `.retry_after`.
+- **Errors** — typed: `ValidationError`, `AuthenticationError`,
+  `PermissionError_`, `NotFoundError`, `ConflictError`, `RateLimitError`,
+  `ServerError` — all subclassing `AutonError` with `.status` / `.request_id`.
+- **Self-hosting** — pass `orchestrator_url=` / `knowledge_url=` /
+  `approvals_url=` when those services are exposed on their own origins.
+
+Versioning follows the gateway major: `autonai==1.x` ↔ gateway `1.x`.

autonai-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+# autonai — official Python SDK (file 09 PR-278).
+# PyPI org: autonai (created 2026-07-04); publishing uses Trusted Publishers
+# (GitHub OIDC), no long-lived tokens.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autonai"
+version = "1.0.0"
+description = "Official Python SDK for AUTON — the operating system for AI-augmented companies."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "AUTON", email = "hello@getauton.ai" }]
+dependencies = ["httpx>=0.27"]
+keywords = ["auton", "agents", "ai", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://getauton.ai"
+Documentation = "https://docs.getauton.ai"
+Repository = "https://github.com/caio-bessa/auton"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autonai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

autonai-1.0.0/src/autonai/__init__.py

@@ -0,0 +1,33 @@
+"""autonai — official Python SDK for AUTON (file 09 PR-278)."""
+
+from ._http import SDK_VERSION, USER_AGENT
+from .client import AutonClient
+from .errors import (
+    AutonError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PermissionError_,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .streaming import stream_deltas
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "AutonClient",
+    "AutonError",
+    "AuthenticationError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionError_",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "SDK_VERSION",
+    "USER_AGENT",
+    "stream_deltas",
+    "__version__",
+]

autonai-1.0.0/src/autonai/_http.py

@@ -0,0 +1,111 @@
+"""Transport core (file 09 PR-278): auth, retry/backoff, Retry-After.
+
+Same policy as the TypeScript SDK: idempotent GETs retry on 5xx/network up
+to ``max_retries`` with exponential backoff; non-idempotent methods never
+retry unless an ``idempotency_key`` is supplied; 429 honours ``Retry-After``
+on every method.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional
+
+import httpx
+
+from .errors import RateLimitError, error_for_status
+
+SDK_VERSION = "1.0.0"
+USER_AGENT = f"autonai-sdk-py/{SDK_VERSION}"
+
+
+class Transport:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._sleep = sleep
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Any = None,
+        query: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> Any:
+        retryable = method == "GET" or idempotency_key is not None
+        url = (base_url.rstrip("/") if base_url else self._base_url) + path
+        headers = {
+            "authorization": f"Bearer {self._api_key}",
+            "user-agent": USER_AGENT,
+        }
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        params = {k: v for k, v in (query or {}).items() if v is not None}
+
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                response = self._client.request(
+                    method, url, json=body, params=params, headers=headers
+                )
+            except httpx.TransportError:
+                if retryable and attempt <= self._max_retries:
+                    self._sleep(_backoff_secs(attempt))
+                    continue
+                raise
+
+            if response.is_success:
+                if response.status_code == 204 or not response.content:
+                    return None
+                return response.json()
+
+            request_id = response.headers.get("x-request-id")
+            retry_after_header = response.headers.get("retry-after")
+            retry_after = float(retry_after_header) if retry_after_header else None
+            message = _error_message(response)
+
+            if response.status_code == 429 and attempt <= self._max_retries:
+                self._sleep(retry_after if retry_after is not None else 1.0)
+                continue
+            if response.status_code >= 500 and retryable and attempt <= self._max_retries:
+                self._sleep(_backoff_secs(attempt))
+                continue
+            if response.status_code == 429:
+                raise RateLimitError(message, 429, retry_after, request_id)
+            raise error_for_status(response.status_code, message, retry_after, request_id)
+
+
+def _backoff_secs(attempt: int) -> float:
+    return min(0.25 * (2 ** (attempt - 1)), 4.0)
+
+
+def _error_message(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+        if isinstance(payload, dict) and isinstance(payload.get("error"), str):
+            return payload["error"]
+    except ValueError:
+        pass
+    return f"HTTP {response.status_code}"

autonai-1.0.0/src/autonai/client.py

@@ -0,0 +1,346 @@
+"""AutonClient (file 09 PR-278) — typed namespaces over the public surface.
+
+>>> from autonai import AutonClient
+>>> client = AutonClient(base_url="https://api.getauton.ai", api_key=key)
+>>> run = client.runs.spawn({"agent_id": ..., "mission": ...})
+>>> for delta in client.runs.stream(run["run_id"]):
+...     ...
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, List, Optional
+
+from ._http import Transport
+from .streaming import stream_deltas
+
+Json = Dict[str, Any]
+
+
+class AutonClient:
+    """Synchronous client. The gateway is the public door; self-hosters can
+    point ``orchestrator_url`` / ``knowledge_url`` / ``approvals_url`` at
+    directly-exposed services."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        orchestrator_url: Optional[str] = None,
+        knowledge_url: Optional[str] = None,
+        approvals_url: Optional[str] = None,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        http_client: Any = None,
+        sleep: Any = None,
+    ) -> None:
+        kwargs: Dict[str, Any] = {"max_retries": max_retries, "timeout": timeout}
+        if http_client is not None:
+            kwargs["http_client"] = http_client
+        if sleep is not None:
+            kwargs["sleep"] = sleep
+        self._tx = Transport(base_url, api_key, **kwargs)
+        self._orchestrator_url = orchestrator_url
+        self._knowledge_url = knowledge_url
+        self._approvals_url = approvals_url
+
+        self.runs = _Runs(self)
+        self.approvals = _Approvals(self)
+        self.knowledge = _Knowledge(self)
+        self.billing = _Billing(self)
+        self.api_keys = _ApiKeys(self)
+        self.process_modules = _ProcessModules(self)
+        self.agent_manuals = _AgentManuals(self)
+        self.heartbeats = _Heartbeats(self)
+        self.proposals = _Proposals(self)
+        self.preferences = _Preferences(self)
+        self.tenant = _Tenant(self)
+
+    def health(self) -> Any:
+        return self._tx.request("/readyz")
+
+    def close(self) -> None:
+        self._tx.close()
+
+    def __enter__(self) -> "AutonClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class _Runs:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def spawn(self, body: Json, *, idempotency_key: Optional[str] = None) -> Json:
+        return self._c._tx.request(
+            "/v1/runs", method="POST", body=body, idempotency_key=idempotency_key
+        )
+
+    def deltas(self, run_id: str, *, from_seq: int = 0, limit: Optional[int] = None) -> Json:
+        return self._c._tx.request(
+            f"/v1/runs/{run_id}/deltas",
+            query={"from_seq": from_seq, "limit": limit},
+            base_url=self._c._orchestrator_url,
+        )
+
+    def stream(self, run_id: str, **kwargs: Any) -> Iterator[Json]:
+        return stream_deltas(lambda seq: self.deltas(run_id, from_seq=seq), **kwargs)
+
+    def intervene(self, run_id: str, action: Json) -> Json:
+        return self._c._tx.request(
+            f"/v1/runs/{run_id}/intervene",
+            method="POST",
+            body=action,
+            base_url=self._c._orchestrator_url,
+        )
+
+
+class _Approvals:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def list(self, *, status: Optional[str] = None, company_id: Optional[str] = None) -> List[Json]:
+        out = self._c._tx.request(
+            "/v1/approvals",
+            query={"status": status, "company_id": company_id},
+            base_url=self._c._approvals_url,
+        )
+        return out["items"]
+
+    def decide(
+        self,
+        approval_id: str,
+        *,
+        verdict: str,
+        by: str,
+        reason: Optional[str] = None,
+        edited_payload: Any = None,
+    ) -> Json:
+        return self._c._tx.request(
+            f"/v1/approvals/{approval_id}",
+            method="PATCH",
+            body={
+                "verdict": verdict,
+                "by": by,
+                "reason": reason,
+                "edited_payload": edited_payload,
+            },
+            base_url=self._c._approvals_url,
+        )
+
+    def decide_bulk(
+        self, *, ids: List[str], verdict: str, by: str, reason: Optional[str] = None
+    ) -> Json:
+        return self._c._tx.request(
+            "/v1/approvals/bulk",
+            method="PATCH",
+            body={"ids": ids, "verdict": verdict, "by": by, "reason": reason},
+            base_url=self._c._approvals_url,
+        )
+
+
+class _Knowledge:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def upload(self, **body: Any) -> Json:
+        return self._c._tx.request(
+            "/v1/knowledge/upload", method="POST", body=body, base_url=self._c._knowledge_url
+        )
+
+    def search(self, **body: Any) -> Json:
+        return self._c._tx.request(
+            "/v1/knowledge/search", method="POST", body=body, base_url=self._c._knowledge_url
+        )
+
+    def list(self, company_id: str) -> Json:
+        return self._c._tx.request(
+            "/v1/knowledge/documents",
+            query={"company_id": company_id},
+            base_url=self._c._knowledge_url,
+        )
+
+    def remove(self, document_id: str) -> None:
+        self._c._tx.request(
+            f"/v1/knowledge/documents/{document_id}",
+            method="DELETE",
+            base_url=self._c._knowledge_url,
+        )
+
+    def reindex(self, document_id: str) -> Json:
+        return self._c._tx.request(
+            f"/v1/knowledge/documents/{document_id}/reindex",
+            method="POST",
+            base_url=self._c._knowledge_url,
+        )
+
+
+class _Billing:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def plans(self) -> Json:
+        return self._c._tx.request("/v1/billing/plans")
+
+    def subscription(self) -> Json:
+        return self._c._tx.request("/v1/billing/subscription")
+
+    def usage(self, period: str = "this_month") -> Json:
+        return self._c._tx.request("/v1/billing/usage", query={"period": period})
+
+    def checkout(self, *, plan: str, period: str) -> Json:
+        return self._c._tx.request(
+            "/v1/billing/checkout", method="POST", body={"plan": plan, "period": period}
+        )
+
+    def portal(self) -> Json:
+        return self._c._tx.request("/v1/billing/portal", method="POST")
+
+
+class _ApiKeys:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def create(self, *, name: str, scopes: Optional[List[str]] = None) -> Json:
+        return self._c._tx.request(
+            "/v1/api-keys", method="POST", body={"name": name, "scopes": scopes or []}
+        )
+
+    def list(self) -> Json:
+        return self._c._tx.request("/v1/api-keys")
+
+    def revoke(self, key_id: str) -> Json:
+        return self._c._tx.request(f"/v1/api-keys/{key_id}/revoke", method="POST")
+
+
+class _ProcessModules:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def list(self) -> Json:
+        return self._c._tx.request("/v1/process-modules")
+
+    def detail(self, module_id: str) -> Json:
+        return self._c._tx.request(f"/v1/process-modules/{module_id}")
+
+    def manual(self, module_id: str, *, company_id: Optional[str] = None) -> Json:
+        return self._c._tx.request(
+            f"/v1/process-modules/{module_id}/manual", query={"company_id": company_id}
+        )
+
+    def agents(self, module_id: str) -> Json:
+        return self._c._tx.request(f"/v1/process-modules/{module_id}/agents")
+
+
+class _AgentManuals:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def list(self) -> Json:
+        return self._c._tx.request("/v1/agent-manuals")
+
+    def detail(self, template_id: str, *, company_id: Optional[str] = None) -> Json:
+        return self._c._tx.request(
+            f"/v1/agent-manuals/{template_id}", query={"company_id": company_id}
+        )
+
+    def resolve(self, template_id: str, **body: Any) -> Json:
+        return self._c._tx.request(
+            f"/v1/agent-manuals/{template_id}/resolved", method="POST", body=body
+        )
+
+    def save_section(self, template_id: str, section: str, **body: Any) -> Json:
+        return self._c._tx.request(
+            f"/v1/agent-manuals/{template_id}/sections/{section}", method="PUT", body=body
+        )
+
+
+class _Heartbeats:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def list(self) -> Json:
+        return self._c._tx.request("/v1/heartbeats", base_url=self._c._orchestrator_url)
+
+    def upsert(self, **heartbeat: Any) -> Json:
+        return self._c._tx.request(
+            "/v1/heartbeats", method="POST", body=heartbeat, base_url=self._c._orchestrator_url
+        )
+
+    def fire_now(self, heartbeat_id: str) -> Json:
+        return self._c._tx.request(
+            f"/v1/heartbeats/{heartbeat_id}/fire",
+            method="POST",
+            base_url=self._c._orchestrator_url,
+        )
+
+    def remove(self, heartbeat_id: str) -> None:
+        self._c._tx.request(
+            f"/v1/heartbeats/{heartbeat_id}",
+            method="DELETE",
+            base_url=self._c._orchestrator_url,
+        )
+
+
+class _Proposals:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def list(self, *, company_id: str, status: str = "pending") -> Json:
+        return self._c._tx.request(
+            "/v1/proposals",
+            query={"company_id": company_id, "status": status},
+            base_url=self._c._orchestrator_url,
+        )
+
+    def resolve(self, proposal_id: str, *, status: str) -> Json:
+        return self._c._tx.request(
+            f"/v1/proposals/{proposal_id}",
+            method="PATCH",
+            body={"status": status},
+            base_url=self._c._orchestrator_url,
+        )
+
+
+class _Preferences:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def get(self) -> Json:
+        return self._c._tx.request("/v1/user-preferences")
+
+    def set(self, prefs: Json) -> Json:
+        return self._c._tx.request("/v1/user-preferences", method="PUT", body={"prefs": prefs})
+
+
+class _Tenant:
+    def __init__(self, client: AutonClient) -> None:
+        self._c = client
+
+    def charter(self, company_id: str) -> Json:
+        return self._c._tx.request(f"/v1/tenants/{company_id}/charter")
+
+    def install_charter(self, company_id: str, charter: Json) -> Json:
+        return self._c._tx.request(
+            f"/v1/tenants/{company_id}/charter", method="PUT", body=charter
+        )
+
+    def patch_charter_section(self, company_id: str, section: str, body: Json) -> Json:
+        return self._c._tx.request(
+            f"/v1/tenants/{company_id}/charter/sections/{section}", method="PATCH", body=body
+        )
+
+    def events(self, company_id: str, **query: Any) -> Json:
+        return self._c._tx.request(f"/v1/tenants/{company_id}/events", query=query)
+
+    def locks(self, company_id: str) -> Json:
+        return self._c._tx.request(f"/v1/tenants/{company_id}/locks")
+
+    def company_progress(self, company_id: str, **query: Any) -> Json:
+        return self._c._tx.request(f"/v1/tenants/{company_id}/company-progress", query=query)
+
+    def swimlanes(self, company_id: str) -> Json:
+        return self._c._tx.request(f"/v1/tenants/{company_id}/swimlanes")

autonai-1.0.0/src/autonai/errors.py

@@ -0,0 +1,71 @@
+"""Typed error hierarchy (file 09 PR-278)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class AutonError(Exception):
+    """Base for every non-2xx response."""
+
+    def __init__(self, message: str, status: int, request_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.request_id = request_id
+
+
+class ValidationError(AutonError):
+    pass
+
+
+class AuthenticationError(AutonError):
+    pass
+
+
+class PermissionError_(AutonError):  # noqa: N801 — avoid shadowing builtins.PermissionError
+    pass
+
+
+class NotFoundError(AutonError):
+    pass
+
+
+class ConflictError(AutonError):
+    pass
+
+
+class ServerError(AutonError):
+    pass
+
+
+class RateLimitError(AutonError):
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        retry_after: Optional[float],
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status, request_id)
+        self.retry_after = retry_after
+
+
+def error_for_status(
+    status: int,
+    message: str,
+    retry_after: Optional[float],
+    request_id: Optional[str] = None,
+) -> AutonError:
+    if status in (400, 422):
+        return ValidationError(message, status, request_id)
+    if status == 401:
+        return AuthenticationError(message, status, request_id)
+    if status == 403:
+        return PermissionError_(message, status, request_id)
+    if status == 404:
+        return NotFoundError(message, status, request_id)
+    if status == 409:
+        return ConflictError(message, status, request_id)
+    if status == 429:
+        return RateLimitError(message, status, retry_after, request_id)
+    return ServerError(message, status, request_id)

autonai-1.0.0/src/autonai/streaming.py

@@ -0,0 +1,35 @@
+"""Delta streaming (file 09 PR-278): consumer-paced generator over the
+replayable ``/deltas?from_seq=`` endpoint."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence
+
+TERMINAL_KINDS = ("run_completed", "run_failed", "run_cancelled")
+
+
+def stream_deltas(
+    fetch_page: Callable[[int], Dict[str, Any]],
+    *,
+    interval_secs: float = 1.0,
+    terminal_kinds: Sequence[str] = TERMINAL_KINDS,
+    max_polls: Optional[int] = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Iterator[Dict[str, Any]]:
+    """Yield deltas in order; stop after a terminal kind. Back-pressure is
+    inherent — the next poll fires only when the consumer resumes."""
+    terminal = set(terminal_kinds)
+    from_seq = 0
+    polls = 0
+    while max_polls is None or polls < max_polls:
+        polls += 1
+        page = fetch_page(from_seq)
+        deltas: List[Dict[str, Any]] = page.get("deltas", [])
+        for delta in deltas:
+            from_seq = max(from_seq, int(delta.get("seq", from_seq)) + 1)
+            yield delta
+            if delta.get("kind") in terminal:
+                return
+        if not deltas:
+            sleep(interval_secs)

autonai-1.0.0/tests/test_sdk.py

@@ -0,0 +1,198 @@
+"""SDK contract tests (file 09 PR-278) against an in-process http.server —
+auth header, retries, Retry-After, typed errors, streaming."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Callable, Dict, List, Optional
+
+import pytest
+
+from autonai import (
+    AuthenticationError,
+    AutonClient,
+    RateLimitError,
+    ValidationError,
+)
+
+Handler = Callable[[str, str, Dict[str, str], bytes], "Reply"]
+
+
+class Reply:
+    def __init__(self, status: int, body: Any = None, headers: Optional[Dict[str, str]] = None):
+        self.status = status
+        self.body = body
+        self.headers = headers or {}
+
+
+class _Server:
+    def __init__(self) -> None:
+        self.seen: List[Dict[str, Any]] = []
+        self.handler: Handler = lambda m, p, h, b: Reply(200, {})
+        outer = self
+
+        class RequestHandler(BaseHTTPRequestHandler):
+            def _serve(self) -> None:
+                length = int(self.headers.get("content-length") or 0)
+                body = self.rfile.read(length) if length else b""
+                outer.seen.append(
+                    {
+                        "method": self.command,
+                        "path": self.path,
+                        "headers": {k.lower(): v for k, v in self.headers.items()},
+                        "body": body.decode() if body else "",
+                    }
+                )
+                reply = outer.handler(self.command, self.path, dict(self.headers), body)
+                payload = b"" if reply.body is None else json.dumps(reply.body).encode()
+                self.send_response(reply.status)
+                self.send_header("content-type", "application/json")
+                for k, v in reply.headers.items():
+                    self.send_header(k, v)
+                self.send_header("content-length", str(len(payload)))
+                self.end_headers()
+                if payload:
+                    self.wfile.write(payload)
+
+            do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _serve
+
+            def log_message(self, *args: Any) -> None:  # silence
+                pass
+
+        self.httpd = HTTPServer(("127.0.0.1", 0), RequestHandler)
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+        self.thread.start()
+        self.url = f"http://127.0.0.1:{self.httpd.server_port}"
+
+    def stop(self) -> None:
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+
+@pytest.fixture()
+def server():
+    s = _Server()
+    yield s
+    s.stop()
+
+
+def make_client(server: _Server, **kwargs: Any) -> AutonClient:
+    kwargs.setdefault("sleep", lambda _s: None)
+    return AutonClient(base_url=server.url, api_key="auton_pat_test", **kwargs)
+
+
+def test_auth_header_and_user_agent(server: _Server) -> None:
+    server.handler = lambda m, p, h, b: Reply(200, {"items": [], "count": 0})
+    with make_client(server) as client:
+        client.api_keys.list()
+    assert server.seen[0]["headers"]["authorization"] == "Bearer auton_pat_test"
+    assert server.seen[0]["headers"]["user-agent"].startswith("autonai-sdk-py/1.")
+
+
+def test_runs_spawn_and_idempotent_retry(server: _Server) -> None:
+    calls = {"n": 0}
+
+    def handler(method: str, path: str, headers: Dict[str, str], body: bytes) -> Reply:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return Reply(503, {"error": "warming up"})
+        return Reply(202, {"run_id": "r-9"})
+
+    server.handler = handler
+    with make_client(server) as client:
+        run = client.runs.spawn({"mission": "draft"}, idempotency_key="idem-1")
+    assert run["run_id"] == "r-9"
+    assert calls["n"] == 2
+    assert server.seen[0]["headers"]["idempotency-key"] == "idem-1"
+
+
+def test_non_idempotent_post_never_retries(server: _Server) -> None:
+    calls = {"n": 0}
+
+    def handler(method: str, path: str, headers: Dict[str, str], body: bytes) -> Reply:
+        calls["n"] += 1
+        return Reply(500, {"error": "boom"})
+
+    server.handler = handler
+    with make_client(server) as client:
+        with pytest.raises(Exception, match="boom"):
+            client.runs.spawn({"mission": "x"})
+    assert calls["n"] == 1
+
+
+def test_retry_after_honoured_on_429(server: _Server) -> None:
+    waits: List[float] = []
+    calls = {"n": 0}
+
+    def handler(method: str, path: str, headers: Dict[str, str], body: bytes) -> Reply:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return Reply(429, {"error": "quota"}, {"retry-after": "3"})
+        return Reply(200, {"items": [], "count": 0})
+
+    server.handler = handler
+    with make_client(server, sleep=waits.append) as client:
+        client.api_keys.list()
+    assert 3.0 in waits
+
+
+def test_typed_errors(server: _Server) -> None:
+    server.handler = lambda m, p, h, b: Reply(401, {"error": "bad token"})
+    with make_client(server, max_retries=0) as client:
+        with pytest.raises(AuthenticationError):
+            client.api_keys.list()
+
+    server.handler = lambda m, p, h, b: Reply(400, {"error": "name required"})
+    with make_client(server) as client:
+        with pytest.raises(ValidationError):
+            client.api_keys.create(name="")
+
+    server.handler = lambda m, p, h, b: Reply(429, {"error": "limit"}, {"retry-after": "5"})
+    with make_client(server, max_retries=0) as client:
+        with pytest.raises(RateLimitError) as excinfo:
+            client.api_keys.list()
+    assert excinfo.value.retry_after == 5.0
+
+
+def test_stream_yields_until_terminal(server: _Server) -> None:
+    pages = [
+        {"deltas": [{"run_id": "r", "seq": 0, "kind": "thinking", "payload": {}}], "high_water": 1},
+        {"deltas": [], "high_water": 1},
+        {
+            "deltas": [
+                {"run_id": "r", "seq": 1, "kind": "text", "payload": {"assistant": "hi"}},
+                {"run_id": "r", "seq": 2, "kind": "run_completed", "payload": {}},
+                {"run_id": "r", "seq": 3, "kind": "never_seen", "payload": {}},
+            ],
+            "high_water": 4,
+        },
+    ]
+    calls = {"n": 0}
+
+    def handler(method: str, path: str, headers: Dict[str, str], body: bytes) -> Reply:
+        page = pages[min(calls["n"], len(pages) - 1)]
+        calls["n"] += 1
+        return Reply(200, page)
+
+    server.handler = handler
+    with make_client(server) as client:
+        kinds = [d["kind"] for d in client.runs.stream("r", sleep=lambda _s: None)]
+    assert kinds == ["thinking", "text", "run_completed"]
+    assert "from_seq=1" in server.seen[-1]["path"]
+
+
+def test_orchestrator_url_override(server: _Server) -> None:
+    server.handler = lambda m, p, h, b: Reply(200, {"items": [], "count": 0})
+    client = AutonClient(
+        base_url="http://never-called.invalid",
+        api_key="k",
+        orchestrator_url=server.url,
+        sleep=lambda _s: None,
+    )
+    try:
+        client.heartbeats.list()
+    finally:
+        client.close()
+    assert server.seen[0]["path"] == "/v1/heartbeats"