zonrad-sdk 0.1.0__py3-none-any.whl

zonrad/__init__.py

@@ -0,0 +1,4 @@
+from .client import Zonrad
+from .exceptions import ZonradAPIError, ZonradError, ZonradToolNotRegisteredError
+
+__all__ = ["Zonrad", "ZonradAPIError", "ZonradError", "ZonradToolNotRegisteredError"]

zonrad/_http.py

@@ -0,0 +1,23 @@
+import requests
+
+from .exceptions import ZonradAPIError
+
+
+class HTTPClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers["Authorization"] = f"Bearer {api_key}"
+
+    def request(self, method: str, path: str, **kwargs):
+        resp = self.session.request(method, f"{self.base_url}{path}", timeout=self.timeout, **kwargs)
+        if not resp.ok:
+            raise ZonradAPIError.from_response(resp)
+        return resp.json() if resp.content else None
+
+    def stream(self, method: str, path: str, **kwargs):
+        resp = self.session.request(method, f"{self.base_url}{path}", stream=True, timeout=None, **kwargs)
+        if not resp.ok:
+            raise ZonradAPIError.from_response(resp)
+        return resp

zonrad/_schema.py

@@ -0,0 +1,62 @@
+"""
+Ported from apps.custom_agents.tool_registry's build_schema_from_function /
+_python_type_to_json_schema (backend_django) — same conversion rules, so a
+function looks identical to the model whether registered server-side via
+@agent_tool_registry.register_tool(...) or client-side via @z.tools.local(...).
+"""
+
+import inspect
+import typing
+
+
+class ToolSchemaError(Exception):
+    pass
+
+
+def _python_type_to_json_schema(annotation):
+    origin = typing.get_origin(annotation)
+
+    if origin is typing.Union:
+        args = [a for a in typing.get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return _python_type_to_json_schema(args[0])  # Optional[X]
+        raise ToolSchemaError(f"Unsupported Union type: {annotation!r}. Only Optional[X] is supported.")
+
+    if origin in (list, typing.List):
+        item_args = typing.get_args(annotation)
+        item_schema = _python_type_to_json_schema(item_args[0]) if item_args else {"type": "string"}
+        return {"type": "array", "items": item_schema}
+
+    if origin in (dict, typing.Dict) or annotation is dict:
+        return {"type": "object"}
+
+    simple = {str: "string", int: "integer", float: "number", bool: "boolean"}
+    if annotation in simple:
+        return {"type": simple[annotation]}
+    if annotation is list:
+        return {"type": "array", "items": {"type": "string"}}
+
+    raise ToolSchemaError(f"Unsupported parameter type: {annotation!r}. Supports str, int, float, bool, list, dict, and Optional[...] of these.")
+
+
+def _is_optional(annotation):
+    return typing.get_origin(annotation) is typing.Union and type(None) in typing.get_args(annotation)
+
+
+def build_schema_from_function(fn):
+    """Derives an OpenAI-compliant JSON schema from a function's type hints."""
+    sig = inspect.signature(fn)
+    properties = {}
+    required = []
+    for name, param in sig.parameters.items():
+        if param.annotation is inspect.Parameter.empty:
+            raise ToolSchemaError(
+                f"Tool function '{fn.__name__}' parameter '{name}' has no type hint — "
+                f"all parameters must be annotated for schema derivation."
+            )
+        schema = _python_type_to_json_schema(param.annotation)
+        schema["description"] = f"Parameter '{name}'"
+        properties[name] = schema
+        if param.default is inspect.Parameter.empty and not _is_optional(param.annotation):
+            required.append(name)
+    return {"type": "object", "properties": properties, "required": required}

zonrad/_sse.py

@@ -0,0 +1,18 @@
+import json
+
+
+def iter_sse_events(response):
+    """Parses a streaming requests.Response as SSE.
+
+    Matches the server's exact wire format (apps.custom_agents.runtime.sse_format
+    in backend_django): one single-line `data: {...}` per event, with a blank
+    line between events — the server never emits multi-line SSE data blocks,
+    so this doesn't need a general-purpose SSE parser, just line splitting.
+    """
+    for raw_line in response.iter_lines(decode_unicode=True):
+        if not raw_line or not raw_line.startswith("data: "):
+            continue
+        try:
+            yield json.loads(raw_line[len("data: "):])
+        except json.JSONDecodeError:
+            continue

zonrad/client.py

@@ -0,0 +1,32 @@
+from ._http import HTTPClient
+from .resources.agents import AgentsResource
+from .resources.api_keys import ApiKeysResource
+from .resources.connections import ConnectionsResource
+from .resources.models import ModelsResource
+from .resources.policies import PoliciesResource
+from .resources.runs import RunsResource
+from .resources.sessions import SessionsResource
+from .resources.tools import ToolkitsResource, ToolsResource
+
+
+class Zonrad:
+    """
+    workspace_id is captured once here, not passed per-call — a
+    PlatformAPIKey is already scoped to exactly one workspace server-side
+    (docs/PLATFORM_PHASE_5_SPEC.md §4.3), so requiring it again on every
+    resource call would be redundant. Every key-minting response
+    (z.api_keys.create()) includes the workspace_id to pair with it.
+    """
+
+    def __init__(self, api_key: str, workspace_id, base_url: str = "http://localhost:8000/platform/v1"):
+        self._http = HTTPClient(base_url, api_key)
+        self.workspace_id = workspace_id
+        self.agents = AgentsResource(self)
+        self.sessions = SessionsResource(self)
+        self.runs = RunsResource(self)
+        self.tools = ToolsResource(self)
+        self.toolkits = ToolkitsResource(self)
+        self.connections = ConnectionsResource(self)
+        self.models = ModelsResource(self)
+        self.policies = PoliciesResource(self)
+        self.api_keys = ApiKeysResource(self)

zonrad/exceptions.py

@@ -0,0 +1,34 @@
+class ZonradError(Exception):
+    """Base class for all errors raised by this SDK."""
+
+
+class ZonradAPIError(ZonradError):
+    """Raised for any non-2xx response from the Zonrad platform API."""
+
+    def __init__(self, status_code, message, error_code=None, body=None):
+        self.status_code = status_code
+        self.error_code = error_code
+        self.body = body
+        super().__init__(f"[{status_code}] {message}")
+
+    @classmethod
+    def from_response(cls, resp):
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"message": resp.text}
+        message = body.get("message") or body.get("error") or "Request failed."
+        error_code = body.get("error_code")
+        return cls(resp.status_code, message, error_code=error_code, body=body)
+
+
+class ZonradToolNotRegisteredError(ZonradError):
+    """Raised when the server asks the SDK to execute a client tool
+    (docs/PLATFORM_PHASE_6_SPEC.md) that has no @z.tools.local(...) handler
+    registered in this process."""
+
+    def __init__(self, name):
+        self.name = name
+        super().__init__(
+            f"Server requested client tool '{name}', but no @z.tools.local(...) handler is registered for it."
+        )

zonrad/resources/agents.py

@@ -0,0 +1,20 @@
+class AgentsResource:
+    """Plain dict in, plain dict out — CRUD has no behavior worth a wrapper object."""
+
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/agents")
+
+    def create(self, **fields):
+        return self._c._http.request("POST", f"/workspaces/{self._c.workspace_id}/agents", json=fields)
+
+    def get(self, agent_id):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/agents/{agent_id}")
+
+    def update(self, agent_id, **fields):
+        return self._c._http.request("PATCH", f"/workspaces/{self._c.workspace_id}/agents/{agent_id}", json=fields)
+
+    def delete(self, agent_id):
+        return self._c._http.request("DELETE", f"/workspaces/{self._c.workspace_id}/agents/{agent_id}")

zonrad/resources/api_keys.py

@@ -0,0 +1,15 @@
+class ApiKeysResource:
+    """Note: the `key` field in create()'s response is shown exactly once —
+    it is never retrievable again after this call returns."""
+
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/api-keys")
+
+    def create(self, name: str = ""):
+        return self._c._http.request("POST", f"/workspaces/{self._c.workspace_id}/api-keys", json={"name": name})
+
+    def revoke(self, key_id):
+        return self._c._http.request("DELETE", f"/workspaces/{self._c.workspace_id}/api-keys/{key_id}")

zonrad/resources/connections.py

@@ -0,0 +1,6 @@
+class ConnectionsResource:
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/connections")["connections"]

zonrad/resources/models.py

@@ -0,0 +1,6 @@
+class ModelsResource:
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/models")

zonrad/resources/policies.py

@@ -0,0 +1,9 @@
+class PoliciesResource:
+    def __init__(self, client):
+        self._c = client
+
+    def get(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/policies")
+
+    def update(self, **fields):
+        return self._c._http.request("PATCH", f"/workspaces/{self._c.workspace_id}/policies", json=fields)

zonrad/resources/runs.py

@@ -0,0 +1,125 @@
+import itertools
+
+from .._sse import iter_sse_events
+
+# Safety cap: if a stream never carries an agent_run_id (a malformed or
+# very early error case), stop eagerly buffering after this many events
+# rather than draining a whole broken stream into memory.
+_MAX_BUFFER_WHILE_RESOLVING_RUN_ID = 5
+
+
+class Run:
+    """
+    Wraps one agent execution's SSE stream. For a brand-new conversation,
+    CustomAgentChatView emits `conversation.assigned` first (conversation_id,
+    no agent_run_id yet), then the runtime's own first event carries
+    agent_run_id — so resolving the run's id may take up to two events. For
+    an existing conversation, the first event already carries agent_run_id.
+    Buffered events are re-yielded, in order, the first time stream() runs.
+    """
+
+    def __init__(self, client, id, session=None):
+        self._c = client
+        self.id = id
+        self.session = session
+        self._buffered_events = []
+        self._events_iter = None
+
+    @classmethod
+    def _from_stream(cls, client, response, session=None):
+        events_iter = iter_sse_events(response)
+        buffered = []
+        run_id = None
+        conversation_id = None
+
+        for event in events_iter:
+            buffered.append(event)
+            data = event.get("data") or {}
+            run_id = data.get("agent_run_id") or run_id
+            conversation_id = data.get("conversation_id") or conversation_id
+            if run_id is not None or len(buffered) >= _MAX_BUFFER_WHILE_RESOLVING_RUN_ID:
+                break
+
+        run = cls(client, id=run_id, session=session)
+        run._buffered_events = buffered
+        run._events_iter = events_iter
+
+        if session is not None and session.id is None and conversation_id is not None:
+            session.id = conversation_id  # lazy Session resolves its id from the first stream
+
+        return run
+
+    def stream(self):
+        """
+        Yields events as they arrive. On `tool.execution_requested` (Phase
+        6, docs/PLATFORM_PHASE_6_SPEC.md §3.3), transparently executes the
+        matching @z.tools.local(...) handler(s), submits the results, and
+        continues yielding from the continuation stream — the caller never
+        sees the pause. `approval.required` is NOT auto-handled; that still
+        needs a human decision via run.resume(...).
+
+        buffered and self._events_iter are chained into a SINGLE generator
+        before draining — a pause resolved entirely from buffered events
+        (the very first turn) must not leave a second, separate drain of
+        self._events_iter trying to read the now-exhausted original stream.
+        """
+        buffered, self._buffered_events = self._buffered_events, []
+        all_events = itertools.chain(buffered, self._events_iter if self._events_iter is not None else ())
+        yield from self._drain(all_events)
+
+    def _drain(self, events):
+        pending_batch = []
+        expected_batch_size = None
+        for event in events:
+            if event.get("event") == "tool.execution_requested":
+                pending_batch.append(event["data"])
+                expected_batch_size = event["data"].get("batch_size", 1)
+                if len(pending_batch) < expected_batch_size:
+                    continue  # wait for the rest of the batch before executing anything
+                yield from self._execute_and_continue(pending_batch)
+                return  # the continuation's own stream()/_drain() has taken over completely
+            else:
+                yield event
+
+    def _execute_and_continue(self, pending_batch):
+        results = []
+        for call in pending_batch:
+            try:
+                output = self._c.tools._execute_local(call["tool"], call["input"])
+                results.append({"tool_call_id": call["tool_call_id"], "output": output, "error": None})
+            except Exception as exc:
+                results.append({"tool_call_id": call["tool_call_id"], "output": None, "error": str(exc)})
+
+        resp = self._c._http.stream(
+            "POST", f"/workspaces/{self._c.workspace_id}/runs/{self.id}/submit-tool-results",
+            json={"results": results},
+        )
+        continuation = Run._from_stream(self._c, resp, session=self.session)
+        yield from continuation.stream()
+
+    def get(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/runs/{self.id}")
+
+    def get_trace(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/runs/{self.id}/trace")
+
+    def resume(self, decision: str, reason: str = ""):
+        resp = self._c._http.stream(
+            "POST", f"/workspaces/{self._c.workspace_id}/runs/{self.id}/resume",
+            json={"decision": decision, "reason": reason},
+        )
+        return Run._from_stream(self._c, resp, session=self.session)
+
+
+class RunsResource:
+    def __init__(self, client):
+        self._c = client
+
+    def get(self, run_id):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/runs/{run_id}")
+
+    def get_trace(self, run_id):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/runs/{run_id}/trace")
+
+    def resume(self, run_id, decision: str, reason: str = ""):
+        return Run(self._c, id=run_id).resume(decision, reason)

zonrad/resources/sessions.py

@@ -0,0 +1,49 @@
+from .runs import Run
+
+
+class Session:
+    """A Session is a Conversation (docs/PLATFORM_PHASE_5_SPEC.md decision 3).
+    `id` is None for a lazily-created session until its first run() resolves
+    a server-assigned conversation id from the stream."""
+
+    def __init__(self, client, id, agent_id):
+        self._c = client
+        self.id = id
+        self.agent_id = agent_id
+
+    def run(self, prompt: str) -> Run:
+        payload = {"message": prompt}
+        if self.id is not None:
+            payload["conversation_id"] = self.id
+        # Phase 6 (docs/PLATFORM_PHASE_6_SPEC.md §3.2): every locally
+        # registered tool's schema rides along on this one request — never
+        # persisted server-side, only meaningful for this run.
+        local_specs = self._c.tools._local_specs()
+        if local_specs:
+            payload["client_tools"] = local_specs
+        resp = self._c._http.stream(
+            "POST", f"/workspaces/{self._c.workspace_id}/agents/{self.agent_id}/chat", json=payload,
+        )
+        return Run._from_stream(self._c, resp, session=self)
+
+
+class SessionsResource:
+    def __init__(self, client):
+        self._c = client
+
+    def create(self, agent_id) -> Session:
+        """Explicit creation — POSTs to conversations immediately."""
+        data = self._c._http.request(
+            "POST", f"/workspaces/{self._c.workspace_id}/conversations", json={"agent_id": agent_id},
+        )
+        return Session(self._c, id=data["id"], agent_id=agent_id)
+
+    def new(self, agent_id) -> Session:
+        """Lazy creation — no HTTP call yet; the first run() call creates
+        the conversation server-side and this Session captures its id from
+        the stream's conversation.assigned event."""
+        return Session(self._c, id=None, agent_id=agent_id)
+
+    def get(self, session_id) -> Session:
+        data = self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/conversations/{session_id}")
+        return Session(self._c, id=data["id"], agent_id=data.get("agent_id"))

zonrad/resources/tools.py

@@ -0,0 +1,63 @@
+import json
+
+from .._schema import build_schema_from_function
+from ..exceptions import ZonradToolNotRegisteredError
+
+
+class ToolsResource:
+    """Read-only listing (Phase 5) plus local tool registration (Phase 6,
+    docs/PLATFORM_PHASE_6_SPEC.md §3.1) — one z.tools namespace for
+    everything tool-related."""
+
+    def __init__(self, client):
+        self._c = client
+        self._local = {}  # name -> {"spec": {...}, "fn": callable}
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/tools")
+
+    def local(self, name=None, description=None, parameters=None):
+        """Registers a plain Python function as a client-side tool. Its
+        schema travels with every session.run() call this process makes —
+        it is never sent, stored, or visible anywhere else."""
+        def decorator(fn):
+            resolved_name = name or fn.__name__
+            schema = parameters or build_schema_from_function(fn)
+            spec = {
+                "name": resolved_name,
+                "description": description or (fn.__doc__ or "").strip() or f"Local tool '{resolved_name}'.",
+                "parameters": schema,
+            }
+            self._local[resolved_name] = {"spec": spec, "fn": fn}
+            return fn
+        return decorator
+
+    def _local_specs(self):
+        return [entry["spec"] for entry in self._local.values()]
+
+    def _execute_local(self, name, arguments):
+        entry = self._local.get(name)
+        if not entry:
+            raise ZonradToolNotRegisteredError(name)
+        # Defensive: the wire contract expects `arguments` already
+        # JSON-decoded, but a proxy or future server change could hand this
+        # back as a raw JSON string — **arguments would then raise TypeError
+        # instead of a clear, catchable error.
+        if isinstance(arguments, str):
+            try:
+                arguments = json.loads(arguments)
+            except (ValueError, TypeError):
+                arguments = {}
+        elif not isinstance(arguments, dict):
+            arguments = {}
+        return entry["fn"](**arguments)
+
+
+class ToolkitsResource:
+    """Grouped view of tools by toolkit — distinct shape from ToolsResource."""
+
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        return self._c._http.request("GET", f"/workspaces/{self._c.workspace_id}/toolkits")

zonrad_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: zonrad-sdk
+Version: 0.1.0
+Summary: Python SDK for the Zonrad platform (/platform/v1/) — agents, sessions, runs, tools, and connections.
+Author: Zonrad
+License: Proprietary
+Project-URL: Homepage, https://zonrad.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# Zonrad Python SDK — Quickstart
+
+The Zonrad SDK talks to the `/platform/v1/` boundary of your Zonrad workspace:
+create agents, run them, stream their output, and inspect what they did —
+all from a Python script, with no Django code in sight.
+
+This guide is copy-paste runnable end to end.
+
+## 1. Install
+
+```bash
+pip install zonrad-sdk
+```
+
+The package on PyPI is named `zonrad-sdk` (`zonrad` was already taken), but
+the import is unaffected: `from zonrad import Zonrad`, exactly as below.
+
+Working against an unreleased local checkout of this repo instead? Use
+`pip install -e sdk/python` — same import, no PyPI round trip.
+
+## 2. Get an API key
+
+Every request needs a `PlatformAPIKey`, scoped to exactly one workspace.
+Mint one with an authenticated session (e.g. your zonrad-ui login) against
+the key-management endpoint:
+
+```bash
+curl -X POST https://<your-zonrad-host>/platform/v1/workspaces/<workspace_id>/api-keys \
+  -H "Authorization: Bearer <your JWT access token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my laptop"}'
+```
+
+The response looks like:
+
+```json
+{
+  "id": 1,
+  "name": "my laptop",
+  "prefix": "zk_live_7792c540",
+  "key": "zk_live_7792c540_9dQwhgufdWlqEkq5hZy-fD5IaZffHAHy",
+  "workspace_id": 38,
+  "last_used_at": null,
+  "revoked_at": null,
+  "created_at": "2026-09-18T11:29:08.140046Z"
+}
+```
+
+**Save the `key` and `workspace_id` now** — the raw key is shown exactly
+once and can never be retrieved again (only its prefix, for identifying it
+later). If you lose it, mint a new one and revoke the old.
+
+## 3. Your first agent, session, and run
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+agent = z.agents.create(
+    name="Release Notes Bot",
+    instructions="Summarize engineering updates concisely for a non-technical audience.",
+)
+
+session = z.sessions.new(agent_id=agent["id"])  # lazy — no request sent yet
+run = session.run("Say hello in exactly three words.")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+    elif event["event"] == "response.completed":
+        print()  # final newline
+
+print("session id (assigned by the server):", session.id)
+print("run id:", run.id)
+```
+
+`workspace_id` is set once, at client construction — every resource call
+uses it automatically, since your API key is already scoped to that one
+workspace.
+
+`z.sessions.new()` is lazy: no HTTP request happens until the first
+`.run()`. Use `z.sessions.create(agent_id=...)` instead if you want the
+conversation to exist before you send the first message (e.g. to save its
+`id` before running anything).
+
+## 4. Inspecting a trace
+
+Every run is recorded. If something looks wrong, pull the full trace —
+every model call and tool call, in order, with token counts:
+
+```python
+trace = z.runs.get_trace(run.id)
+for span in trace["spans"]:
+    print(span["type"], span["name"], span.get("total_tokens"))
+```
+
+## 5. Running your own Python function as a tool
+
+`@z.tools.local(...)` registers a plain Python function that runs **on
+this machine** — the agent calls it mid-run, the SDK executes it locally,
+and the conversation continues automatically. No backend deploy, no new
+tool registration anywhere except this script:
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+@z.tools.local()
+def get_local_file(path: str) -> dict:
+    """Reads a file from this machine's filesystem."""
+    with open(path) as f:
+        return {"content": f.read()}
+
+agent = z.agents.create(
+    name="File Assistant",
+    instructions="Use get_local_file to answer questions about files on the user's machine.",
+)
+session = z.sessions.new(agent_id=agent["id"])
+run = session.run("What's in ~/notes.txt?")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+```
+
+That's the whole thing — `run.stream()` sees the model call
+`get_local_file`, runs your function, sends the result back, and keeps
+streaming. You never handle the pause yourself.
+
+The function's parameter types (`str`, `int`, `float`, `bool`, `list`,
+`dict`, `Optional[...]`) are turned into the schema the model sees — same
+rule as the backend's own `register_tool()` below, so a function looks the
+same either way. Every parameter needs a type hint. Give the tool an
+explicit name/description if the function's own name/docstring aren't
+what you want the model to see: `@z.tools.local(name="read_file",
+description="...")`.
+
+**What this can't do:** a name that collides with an existing server-side
+tool, or one your workspace has denied via policy, is rejected with a
+clear error the moment you call `.run()` — not silently ignored. And a
+local tool only exists for runs started by *this* process; it's not
+visible to other users or other scripts, and `z.tools.list()` still only
+shows the server-side registry (see below).
+
+## 6. Adding a tool for everyone (backend registration)
+
+If a tool should be available to any agent in the workspace, not just from
+your own script, register it in the backend repo instead:
+
+```python
+# backend_django/apps/custom_agents/tools/my_tool.py
+from apps.custom_agents.tool_registry import register_tool
+
+@register_tool(
+    id="fetch_release_notes",
+    name="Fetch Release Notes",
+    description="Fetches the latest release notes for a given repo.",
+    risk_level="low",
+)
+def fetch_release_notes(repo: str) -> dict:
+    ...
+    return {"notes": "..."}
+```
+
+This requires a backend deploy and then shows up in `z.tools.list()` for
+everyone — unlike `@z.tools.local(...)`, which is private to the process
+that registered it and needs no deploy at all.
+
+## What's not supported yet
+
+- **Non-Python SDKs.** Python only, for now.
+- **Streaming partial output *from* a local tool.** Your function's return
+  value is submitted as one complete result — there's no equivalent of
+  `response.chunk` for a tool's own execution.
+
+## Reference
+
+```python
+z.agents.list() / .create(**fields) / .get(id) / .update(id, **fields) / .delete(id)
+z.sessions.create(agent_id) / .new(agent_id) / .get(session_id)
+session.run(prompt) -> Run
+run.stream()               # generator of {"event": ..., "data": {...}} dicts — auto-handles local tool calls
+run.get() / .get_trace() / .resume(decision, reason="")
+z.runs.get(run_id) / .get_trace(run_id) / .resume(run_id, decision, reason="")
+z.tools.list() / z.toolkits.list()             # server-side registry (read-only)
+z.tools.local(name=None, description=None, parameters=None)  # decorator — registers a local function
+z.connections.list()
+z.models.list()
+z.policies.get() / .update(**fields)
+z.api_keys.list() / .create(name="") / .revoke(key_id)
+```
+
+A `tool.execution_requested` event your own code never has to handle
+raises `zonrad.ZonradToolNotRegisteredError` internally if no matching
+`@z.tools.local(...)` handler exists — the SDK catches this itself and
+submits it as that call's error, so the run continues rather than your
+script crashing.
+
+Errors raise `zonrad.ZonradAPIError` with `.status_code`, `.error_code`
+(when the server sent one, e.g. `"insufficient_credits"`), and `.body`
+(the full parsed response).

zonrad_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+zonrad/__init__.py,sha256=6cOzJaRedb855ouQiYKt8R8gTpwUrWSUkMxJYYUJb1o,196
+zonrad/_http.py,sha256=SnhKQumO7A9Av5s0rHQzuJ87MzxHFVjzJptnnUo3s38,887
+zonrad/_schema.py,sha256=aOfjbNxLPgCBCfHMaABVIpOzvQV2v3C-rB--egprMB4,2515
+zonrad/_sse.py,sha256=8aS6Ft2kXbd1pfvrjUe_S_R6lD_hb97FCXUZ0aIY05U,692
+zonrad/client.py,sha256=QWRgHULlR_DprnJY6cnftYVf_QFIT5Z_OIc7O0cXscQ,1407
+zonrad/exceptions.py,sha256=BFMPOR-U8IYQYaR7kExCMSrwhorhizsoGVt7bL81vz4,1228
+zonrad/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zonrad/resources/agents.py,sha256=iKMKa8pN2gLQ70UsnqEeQGADxMiqx7lhMuV8kCfyXvg,844
+zonrad/resources/api_keys.py,sha256=VpgQYxgiTF6niaysgO70KKrcDmR2y7euFibvKchNMik,622
+zonrad/resources/connections.py,sha256=gh_rJJRBiqS6-okdOhK59HvWS02gYWQnV1cMhN-e-Fw,215
+zonrad/resources/models.py,sha256=LWa15gQjgpAbzzuXpZDznY7uVqDNQ0jSia4Ds2tHlbQ,190
+zonrad/resources/policies.py,sha256=dvkfZ1KS-rLii91fdc-qJUnBtcVv6iVynk2TnYD1kSk,333
+zonrad/resources/runs.py,sha256=3kirVDDdnArkrK2k_BbVCFd_1URrfHy0fk19oHgwyn4,5315
+zonrad/resources/sessions.py,sha256=LgfGDNH43U6r_l3dDB9zbfKS_UtoSqZba6iXOP2A-z4,2034
+zonrad/resources/tools.py,sha256=B5gyiPQI68zRrPzyZKDBoyI2oIgNwvsRbDeAV1ql6r0,2404
+zonrad_sdk-0.1.0.dist-info/METADATA,sha256=0zIMqaWxkb21M9FZcegSU7nLr36kJkrzVPFnk2RmYAI,7730
+zonrad_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+zonrad_sdk-0.1.0.dist-info/top_level.txt,sha256=MBtWQ16cbC8MZtWc1Xm2MI33qkJ84yWEysEk3byC898,7
+zonrad_sdk-0.1.0.dist-info/RECORD,,

zonrad_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zonrad_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zonrad