zihin 0.1.0__tar.gz

zihin-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env
+.env.*
+.env-*

zihin-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 (2026-10-05)
+
+First release: `Zihin` client with `list_agents`, `invoke_agent` and `stream_agent`, a single
+`ZihinError` with a `kind` to branch on, and an offline test suite.

zihin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zihin.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zihin-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: zihin
+Version: 0.1.0
+Summary: Official Python client for invoking Zihin.ai hosted AI agents (buffered and streaming calls).
+Project-URL: Homepage, https://zihin.ai
+Project-URL: Documentation, https://docs.zihin.ai
+Project-URL: Repository, https://github.com/zihin-ai/zihin-python
+Project-URL: Issues, https://github.com/zihin-ai/zihin-python/issues
+Author: Zihin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-sdk,ai-agents,llm,sse,streaming,zihin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zihin
+
+Official Python client for [Zihin.ai](https://zihin.ai), a platform for building and running hosted
+AI agents. Use it to invoke an agent from your backend and get its answer, buffered or as a stream.
+
+This is an early release (0.1.x). It covers the direct invocation path. Structured context,
+attachments, async triggers and tasks, which the Node.js client
+[`@zihin/agent-client`](https://www.npmjs.com/package/@zihin/agent-client) already has, are not
+implemented here yet.
+
+## Install
+
+```bash
+pip install zihin
+```
+
+Requires Python 3.9 or later.
+
+## Usage
+
+Create an API key in the Zihin console. Keys start with `zhn_live_`, `zhn_test_` or `zhn_dev_`.
+The client reads `ZIHIN_API_KEY` from the environment when no key is passed.
+
+```python
+from zihin import Zihin
+
+with Zihin() as zihin:
+    for agent in zihin.list_agents():
+        print(agent.id, agent.name)
+
+    result = zihin.invoke_agent("AGENT_ID", "What is the status of order 1234?")
+    print(result.content)
+
+    # Continue the same conversation
+    follow_up = zihin.invoke_agent("AGENT_ID", "And when does it ship?", session_id=result.session_id)
+```
+
+### Streaming
+
+```python
+for event in zihin.stream_agent("AGENT_ID", "Hello"):
+    if event.type == "token":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool":
+        print("\n[tool]", event.data)
+```
+
+`token` events are the model's working text across iterations. The answer the agent delivers is the
+`response` event, which is what `invoke_agent` returns. Stopping the iteration early closes the
+connection and cancels the turn on the server.
+
+### Errors
+
+Every failure raises `ZihinError`, with a `kind` you can branch on:
+
+```python
+from zihin import Zihin, ZihinError
+
+try:
+    Zihin().invoke_agent("AGENT_ID", "Hi")
+except ZihinError as err:
+    print(err.kind, err.status, err.code, err.message)
+```
+
+| `kind` | Meaning |
+|---|---|
+| `config` | Missing or malformed API key, or missing arguments |
+| `auth` | The key was rejected, or its role does not allow the action |
+| `not_found` | The agent does not exist or is not accessible with this key |
+| `rate_limit` | Too many requests |
+| `timeout` | The request or the agent turn timed out |
+| `agent` | The agent turn ended with an error reported by the server |
+| `server` | The Zihin server failed (5xx) |
+| `network` | The connection failed |
+| `protocol` | The response did not match the API contract |
+
+`request_id`, `execution_id` and `session_id` are set on the error when the server provides them;
+include them when contacting support.
+
+## Configuration
+
+```python
+Zihin(
+    api_key="zhn_live_...",          # default: ZIHIN_API_KEY
+    base_url="https://llm.zihin.ai", # default
+    timeout=35.0,                     # seconds, for short requests
+    stream_timeout=200.0,             # seconds, for an agent turn
+)
+```
+
+The stream timeout is above the server's own turn deadline on purpose, so the client receives the
+server's structured outcome instead of cutting the connection first.
+
+An agent turn costs LLM tokens on your Zihin workspace.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The tests are offline: every request is answered by a mock transport.
+
+## License
+
+MIT

zihin-0.1.0/README.md

@@ -0,0 +1,107 @@
+# zihin
+
+Official Python client for [Zihin.ai](https://zihin.ai), a platform for building and running hosted
+AI agents. Use it to invoke an agent from your backend and get its answer, buffered or as a stream.
+
+This is an early release (0.1.x). It covers the direct invocation path. Structured context,
+attachments, async triggers and tasks, which the Node.js client
+[`@zihin/agent-client`](https://www.npmjs.com/package/@zihin/agent-client) already has, are not
+implemented here yet.
+
+## Install
+
+```bash
+pip install zihin
+```
+
+Requires Python 3.9 or later.
+
+## Usage
+
+Create an API key in the Zihin console. Keys start with `zhn_live_`, `zhn_test_` or `zhn_dev_`.
+The client reads `ZIHIN_API_KEY` from the environment when no key is passed.
+
+```python
+from zihin import Zihin
+
+with Zihin() as zihin:
+    for agent in zihin.list_agents():
+        print(agent.id, agent.name)
+
+    result = zihin.invoke_agent("AGENT_ID", "What is the status of order 1234?")
+    print(result.content)
+
+    # Continue the same conversation
+    follow_up = zihin.invoke_agent("AGENT_ID", "And when does it ship?", session_id=result.session_id)
+```
+
+### Streaming
+
+```python
+for event in zihin.stream_agent("AGENT_ID", "Hello"):
+    if event.type == "token":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool":
+        print("\n[tool]", event.data)
+```
+
+`token` events are the model's working text across iterations. The answer the agent delivers is the
+`response` event, which is what `invoke_agent` returns. Stopping the iteration early closes the
+connection and cancels the turn on the server.
+
+### Errors
+
+Every failure raises `ZihinError`, with a `kind` you can branch on:
+
+```python
+from zihin import Zihin, ZihinError
+
+try:
+    Zihin().invoke_agent("AGENT_ID", "Hi")
+except ZihinError as err:
+    print(err.kind, err.status, err.code, err.message)
+```
+
+| `kind` | Meaning |
+|---|---|
+| `config` | Missing or malformed API key, or missing arguments |
+| `auth` | The key was rejected, or its role does not allow the action |
+| `not_found` | The agent does not exist or is not accessible with this key |
+| `rate_limit` | Too many requests |
+| `timeout` | The request or the agent turn timed out |
+| `agent` | The agent turn ended with an error reported by the server |
+| `server` | The Zihin server failed (5xx) |
+| `network` | The connection failed |
+| `protocol` | The response did not match the API contract |
+
+`request_id`, `execution_id` and `session_id` are set on the error when the server provides them;
+include them when contacting support.
+
+## Configuration
+
+```python
+Zihin(
+    api_key="zhn_live_...",          # default: ZIHIN_API_KEY
+    base_url="https://llm.zihin.ai", # default
+    timeout=35.0,                     # seconds, for short requests
+    stream_timeout=200.0,             # seconds, for an agent turn
+)
+```
+
+The stream timeout is above the server's own turn deadline on purpose, so the client receives the
+server's structured outcome instead of cutting the connection first.
+
+An agent turn costs LLM tokens on your Zihin workspace.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The tests are offline: every request is answered by a mock transport.
+
+## License
+
+MIT

zihin-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zihin"
+version = "0.1.0"
+description = "Official Python client for invoking Zihin.ai hosted AI agents (buffered and streaming calls)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Zihin" }]
+keywords = ["zihin", "ai-agents", "agent-sdk", "llm", "sse", "streaming"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://zihin.ai"
+Documentation = "https://docs.zihin.ai"
+Repository = "https://github.com/zihin-ai/zihin-python"
+Issues = "https://github.com/zihin-ai/zihin-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zihin"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zihin-0.1.0/src/zihin/__init__.py

@@ -0,0 +1,8 @@
+"""Official Python client for the Zihin.ai agent platform."""
+
+from ._client import Agent, AgentResult, StreamEvent, Usage, Zihin
+from ._errors import ZihinError
+
+__version__ = "0.1.0"
+
+__all__ = ["Agent", "AgentResult", "StreamEvent", "Usage", "Zihin", "ZihinError", "__version__"]

zihin-0.1.0/src/zihin/_client.py

@@ -0,0 +1,280 @@
+"""Zihin client: list agents, invoke an agent, stream an agent turn."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Optional
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import ZihinError, error_from_response
+from ._sse import parse_sse
+
+DEFAULT_BASE_URL = "https://llm.zihin.ai"
+# The server has its own turn deadline; the stream timeout stays above it so the client
+# receives the server's structured outcome instead of cutting the connection first.
+DEFAULT_STREAM_TIMEOUT = 200.0
+DEFAULT_TIMEOUT = 35.0
+_KEY_PREFIXES = ("zhn_live_", "zhn_test_", "zhn_dev_")
+
+
+@dataclass
+class Agent:
+    """An agent visible to the API key."""
+
+    id: str
+    name: Optional[str] = None
+    commercial_name: Optional[str] = None
+    bio: Optional[str] = None
+    type: Optional[str] = None
+    status: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Usage:
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    cost_usd: Optional[float] = None
+
+
+@dataclass
+class StreamEvent:
+    """One event of an agent turn.
+
+    ``type`` is the server event name (``metadata``, ``status``, ``thinking``, ``tool``,
+    ``token``, ``response``, ``metrics``, ``done``, ``error`` and others). ``data`` is the
+    decoded payload. ``content`` is filled for ``token`` and ``response`` events.
+    """
+
+    type: str
+    data: Any
+    content: Optional[str] = None
+
+
+@dataclass
+class AgentResult:
+    """The consolidated result of an agent turn."""
+
+    content: str
+    session_id: Optional[str] = None
+    model: Optional[str] = None
+    usage: Optional[Usage] = None
+    execution_id: Optional[str] = None
+    outcome: Optional[str] = None
+    sources: Optional[List[Any]] = None
+
+
+def _d(value: Any) -> dict:
+    return value if isinstance(value, dict) else {}
+
+
+def _s(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def _n(value: Any) -> Any:
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def _usage(value: Any) -> Optional[Usage]:
+    u = _d(value)
+    if not u:
+        return None
+    return Usage(
+        input_tokens=_n(u.get("input_tokens")) if _n(u.get("input_tokens")) is not None else _n(u.get("prompt_tokens")),
+        output_tokens=_n(u.get("output_tokens"))
+        if _n(u.get("output_tokens")) is not None
+        else _n(u.get("completion_tokens")),
+        total_tokens=_n(u.get("total_tokens")),
+        cost_usd=_n(u.get("cost_usd")),
+    )
+
+
+class Zihin:
+    """Client for the Zihin.ai agent API.
+
+    ``api_key`` defaults to the ``ZIHIN_API_KEY`` environment variable. Use the client as a
+    context manager, or call ``close()`` when done.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        stream_timeout: float = DEFAULT_STREAM_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("ZIHIN_API_KEY", "")
+        if not key:
+            raise ZihinError("config", "No API key. Pass api_key or set the ZIHIN_API_KEY environment variable.")
+        if not key.startswith(_KEY_PREFIXES):
+            raise ZihinError("config", "Invalid API key format. Zihin keys start with zhn_live_, zhn_test_ or zhn_dev_.")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._stream_timeout = stream_timeout
+        self._headers = {"Content-Type": "application/json", "Accept": "application/json", "X-Api-Key": key}
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client()
+
+    def __enter__(self) -> "Zihin":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __repr__(self) -> str:
+        # The API key is deliberately left out.
+        return f"Zihin(base_url={self._base_url!r})"
+
+    # -- agents ---------------------------------------------------------------------------
+
+    def list_agents(self) -> List[Agent]:
+        """List the agents accessible with the API key."""
+        try:
+            res = self._http.get(f"{self._base_url}/api/v2/agents", headers=self._headers, timeout=self._timeout)
+        except httpx.TimeoutException as exc:
+            raise ZihinError("timeout", "The request timed out.") from exc
+        except httpx.HTTPError as exc:
+            raise ZihinError("network", f"Could not reach the Zihin server: {exc}") from exc
+        body = self._json_or_none(res)
+        if res.status_code >= 400:
+            raise error_from_response(res.status_code, body)
+        items = _d(body).get("data")
+        if not isinstance(items, list):
+            raise ZihinError("protocol", "Expected a list of agents from GET /api/v2/agents.", status=res.status_code)
+        agents = []
+        for item in items:
+            a = _d(item)
+            agents.append(
+                Agent(
+                    id=_s(a.get("id")) or "",
+                    name=_s(a.get("name")),
+                    commercial_name=_s(a.get("commercial_name")),
+                    bio=_s(a.get("bio")),
+                    type=_s(a.get("type")),
+                    status=_s(a.get("status")),
+                    tags=[t for t in a.get("tags") or [] if isinstance(t, str)],
+                )
+            )
+        return agents
+
+    # -- invocation -----------------------------------------------------------------------
+
+    def stream_agent(self, agent_id: str, message: str, *, session_id: Optional[str] = None) -> Iterator[StreamEvent]:
+        """Run one agent turn and yield its events as they arrive.
+
+        Closing the iterator early closes the connection, which cancels the turn on the server.
+        An ``error`` event is yielded like any other; ``invoke_agent`` is the method that turns
+        it into an exception.
+        """
+        if not agent_id:
+            raise ZihinError("config", "agent_id is required.")
+        if not message:
+            raise ZihinError("config", "message is required.")
+        body: Dict[str, Any] = {"message": message}
+        if session_id:
+            body["session_id"] = session_id
+        url = f"{self._base_url}/api/v2/agents/{quote(agent_id, safe='')}/stream"
+        try:
+            with self._http.stream(
+                "POST", url, headers=self._headers, json=body, timeout=self._stream_timeout
+            ) as res:
+                if res.status_code >= 400:
+                    res.read()
+                    raise error_from_response(res.status_code, self._json_or_none(res))
+                for name, data in parse_sse(res.iter_lines()):
+                    payload = _d(data)
+                    content = _s(payload.get("content")) if name in ("token", "response") else None
+                    yield StreamEvent(type=name, data=data, content=content)
+        except httpx.TimeoutException as exc:
+            raise ZihinError("timeout", "The agent stream timed out on the client side.") from exc
+        except httpx.HTTPError as exc:
+            raise ZihinError("network", f"The connection to the Zihin server failed: {exc}") from exc
+
+    def invoke_agent(self, agent_id: str, message: str, *, session_id: Optional[str] = None) -> AgentResult:
+        """Run one agent turn and return the final answer.
+
+        Pass the returned ``session_id`` to the next call to continue the conversation.
+        """
+        response: Optional[dict] = None
+        metrics: dict = {}
+        done: Optional[dict] = None
+        meta_session: Optional[str] = None
+        minted_session: Optional[str] = None
+
+        for event in self.stream_agent(agent_id, message, session_id=session_id):
+            payload = _d(event.data)
+            if event.type == "error":
+                err = _d(payload.get("error"))
+                timed_out = err.get("timed_out") is True
+                raise ZihinError(
+                    "timeout" if timed_out else "agent",
+                    _s(err.get("message")) or "The agent turn failed.",
+                    code=_s(err.get("code")),
+                    request_id=_s(err.get("request_id")),
+                )
+            if event.type == "response":
+                response = payload
+            elif event.type == "metrics":
+                metrics = payload
+            elif event.type == "metadata":
+                meta_session = _s(payload.get("session_id")) or meta_session
+            elif event.type == "session":
+                minted_session = _s(payload.get("session_id")) or minted_session
+            elif event.type == "done":
+                done = payload
+
+        resolved_session = (
+            minted_session or _s(_d(response).get("session_id")) or meta_session or session_id
+        )
+        execution_id = _s(metrics.get("execution_id"))
+
+        if done is not None and (done.get("outcome") == "TIMEOUT" or done.get("timed_out") is True):
+            # The response event of a timed-out turn carries the failure, not an answer.
+            raise ZihinError(
+                "timeout",
+                "The agent turn timed out on the server.",
+                code="TURN_TIMEOUT",
+                execution_id=execution_id,
+                session_id=resolved_session,
+            )
+        if response is None:
+            # Token events are the model's working text across iterations, not the answer the
+            # server chose to deliver, so they are never returned in its place.
+            raise ZihinError(
+                "protocol",
+                "The stream ended without a response event.",
+                execution_id=execution_id,
+                session_id=resolved_session,
+            )
+
+        model = _s(_d(metrics.get("model_config")).get("model")) or _s(metrics.get("model"))
+        sources = response.get("sources")
+        return AgentResult(
+            content=_s(response.get("content")) or "",
+            session_id=resolved_session,
+            model=model,
+            usage=_usage(metrics.get("usage")),
+            execution_id=execution_id,
+            outcome=_s(_d(done).get("outcome")),
+            sources=sources if isinstance(sources, list) else None,
+        )
+
+    # -- internals ------------------------------------------------------------------------
+
+    @staticmethod
+    def _json_or_none(res: httpx.Response) -> Any:
+        try:
+            return res.json()
+        except ValueError:
+            return None

zihin-0.1.0/src/zihin/_errors.py

@@ -0,0 +1,88 @@
+"""Error type raised by the Zihin client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ZihinError(Exception):
+    """Raised for every failure of a Zihin API call.
+
+    ``kind`` says what went wrong, so callers can branch without parsing messages:
+
+    - ``config``: invalid client configuration or arguments
+    - ``auth``: the API key was rejected or its role does not allow the action
+    - ``not_found``: the agent does not exist or is not accessible with this key
+    - ``rate_limit``: too many requests
+    - ``timeout``: the request or the agent turn timed out
+    - ``server``: the Zihin server failed (5xx)
+    - ``network``: the connection failed
+    - ``protocol``: the response was not what the API contract describes
+    - ``agent``: the agent turn ended with an error reported by the server
+    """
+
+    def __init__(
+        self,
+        kind: str,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        execution_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.execution_id = execution_id
+        self.session_id = session_id
+
+    def __repr__(self) -> str:
+        return f"ZihinError(kind={self.kind!r}, message={self.message!r}, status={self.status!r}, code={self.code!r})"
+
+
+def _as_dict(value: Any) -> dict:
+    return value if isinstance(value, dict) else {}
+
+
+def _as_str(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def error_from_response(status: int, body: Any) -> ZihinError:
+    """Map an HTTP error response to a ``ZihinError``."""
+    root = _as_dict(body)
+    err = _as_dict(root.get("error"))
+    message = _as_str(err.get("message")) or _as_str(root.get("message"))
+    code = _as_str(err.get("code")) or _as_str(root.get("code"))
+    meta = {
+        "status": status,
+        "code": code,
+        "request_id": _as_str(err.get("request_id")) or _as_str(root.get("request_id")),
+        "execution_id": _as_str(root.get("execution_id")),
+    }
+
+    if status == 401:
+        return ZihinError("auth", message or "Authentication failed. Check the API key.", **meta)
+    if status == 403:
+        # The tenant gate answers 403 for an agent that does not exist as well as for one that
+        # belongs to another workspace, so the useful advice is about the agent ID, not the key.
+        if _as_str(_as_dict(err.get("details")).get("reason")) == "AGENT_ACCESS_DENIED":
+            return ZihinError(
+                "not_found",
+                "Agent not found, inactive, or not accessible with this API key. "
+                "Check the agent ID and that the key belongs to the same Zihin workspace.",
+                **meta,
+            )
+        return ZihinError("auth", message or "This API key's role does not allow this action.", **meta)
+    if status == 404:
+        return ZihinError("not_found", message or "Not found.", **meta)
+    if status == 429:
+        return ZihinError("rate_limit", message or "Too many requests.", **meta)
+    if status >= 500:
+        return ZihinError("server", message or f"Zihin server error ({status}).", **meta)
+    return ZihinError("protocol", message or f"Unexpected HTTP status {status}.", **meta)

zihin-0.1.0/src/zihin/_sse.py

@@ -0,0 +1,46 @@
+"""Minimal Server-Sent Events parser."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable, Iterator, List, Tuple
+
+
+def parse_sse(lines: Iterable[str]) -> Iterator[Tuple[str, Any]]:
+    """Turn an iterable of text lines into ``(event, data)`` pairs.
+
+    ``data`` is decoded from JSON when possible and left as a string otherwise. Events with
+    no data are skipped; comment lines (keep-alives) are ignored.
+    """
+    event = ""
+    data: List[str] = []
+
+    def flush() -> Iterator[Tuple[str, Any]]:
+        nonlocal event, data
+        raw = "\n".join(data)
+        name = event or "message"
+        event, data = "", []
+        if raw == "":
+            return
+        try:
+            yield name, json.loads(raw)
+        except ValueError:
+            yield name, raw
+
+    for line in lines:
+        line = line.rstrip("\r\n")
+        if line == "":
+            yield from flush()
+            continue
+        if line.startswith(":"):
+            continue
+        field, sep, value = line.partition(":")
+        if sep and value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event = value
+        elif field == "data":
+            data.append(value)
+        # `id` and `retry` are ignored: this client does not reconnect.
+
+    yield from flush()

zihin-0.1.0/tests/test_client.py

@@ -0,0 +1,136 @@
+"""Offline tests: every request is answered by an httpx MockTransport."""
+
+import json
+
+import httpx
+import pytest
+
+from zihin import Zihin, ZihinError
+from zihin._sse import parse_sse
+
+KEY = "zhn_test_" + "x" * 16
+
+
+def sse(*events):
+    out = []
+    for name, data in events:
+        out.append(f"event: {name}\ndata: {json.dumps(data)}\n\n")
+    return "".join(out).encode()
+
+
+def client(handler):
+    return Zihin(KEY, http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+
+def test_requires_api_key(monkeypatch):
+    monkeypatch.delenv("ZIHIN_API_KEY", raising=False)
+    with pytest.raises(ZihinError) as exc:
+        Zihin()
+    assert exc.value.kind == "config"
+
+
+def test_rejects_key_with_unknown_prefix():
+    with pytest.raises(ZihinError) as exc:
+        Zihin("sk-not-a-zihin-key")
+    assert exc.value.kind == "config"
+
+
+def test_reads_key_from_environment(monkeypatch):
+    monkeypatch.setenv("ZIHIN_API_KEY", KEY)
+    assert "zhn_" not in repr(Zihin())
+
+
+def test_list_agents_sends_key_and_maps_fields():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["key"] = request.headers.get("x-api-key")
+        return httpx.Response(200, json={"data": [{"id": "a1", "name": "Support", "commercial_name": "Ana", "tags": ["x", 3]}]})
+
+    agents = client(handler).list_agents()
+    assert seen == {"url": "https://llm.zihin.ai/api/v2/agents", "key": KEY}
+    assert agents[0].id == "a1" and agents[0].commercial_name == "Ana" and agents[0].tags == ["x"]
+
+
+def test_list_agents_maps_401_to_auth():
+    with pytest.raises(ZihinError) as exc:
+        client(lambda r: httpx.Response(401, json={"error": {"code": "UNAUTHORIZED", "message": "bad key"}})).list_agents()
+    assert (exc.value.kind, exc.value.status, exc.value.code) == ("auth", 401, "UNAUTHORIZED")
+
+
+def test_invoke_agent_consolidates_response_and_metrics():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            content=sse(
+                ("metadata", {"session_id": "s-meta"}),
+                ("token", {"content": "thinking out loud"}),
+                ("response", {"content": "Hello!", "session_id": "s-1", "sources": []}),
+                ("metrics", {"usage": {"input_tokens": 10, "output_tokens": 2, "cost_usd": 0.001}, "model_config": {"model": "m-1"}, "execution_id": "e-1"}),
+                ("done", {"outcome": "COMPLETED"}),
+            ),
+        )
+
+    result = client(handler).invoke_agent("agent/1", "Hi", session_id="s-0")
+    assert seen["url"] == "https://llm.zihin.ai/api/v2/agents/agent%2F1/stream"
+    assert seen["body"] == {"message": "Hi", "session_id": "s-0"}
+    assert result.content == "Hello!"
+    assert result.session_id == "s-1"
+    assert (result.model, result.execution_id, result.outcome) == ("m-1", "e-1", "COMPLETED")
+    assert (result.usage.input_tokens, result.usage.output_tokens, result.usage.cost_usd) == (10, 2, 0.001)
+
+
+def test_invoke_agent_raises_on_error_event():
+    body = sse(("token", {"content": "partial"}), ("error", {"error": {"code": "ENGINE_ERROR", "message": "boom", "request_id": "r-1"}}))
+    with pytest.raises(ZihinError) as exc:
+        client(lambda r: httpx.Response(200, content=body)).invoke_agent("a", "Hi")
+    assert (exc.value.kind, exc.value.code, exc.value.request_id) == ("agent", "ENGINE_ERROR", "r-1")
+
+
+def test_invoke_agent_raises_timeout_even_with_a_response_event():
+    body = sse(("response", {"content": "the turn timed out", "session_id": "s-1"}), ("done", {"outcome": "TIMEOUT", "timed_out": True}))
+    with pytest.raises(ZihinError) as exc:
+        client(lambda r: httpx.Response(200, content=body)).invoke_agent("a", "Hi")
+    assert (exc.value.kind, exc.value.code, exc.value.session_id) == ("timeout", "TURN_TIMEOUT", "s-1")
+
+
+def test_invoke_agent_does_not_return_tokens_as_the_answer():
+    body = sse(("token", {"content": "deliberation"}), ("done", {"outcome": "COMPLETED"}))
+    with pytest.raises(ZihinError) as exc:
+        client(lambda r: httpx.Response(200, content=body)).invoke_agent("a", "Hi")
+    assert exc.value.kind == "protocol"
+
+
+def test_agent_access_denied_is_reported_as_not_found():
+    def handler(request):
+        return httpx.Response(403, json={"error": {"code": "FORBIDDEN", "details": {"reason": "AGENT_ACCESS_DENIED"}}})
+
+    with pytest.raises(ZihinError) as exc:
+        client(handler).invoke_agent("a", "Hi")
+    assert (exc.value.kind, exc.value.status) == ("not_found", 403)
+
+
+def test_stream_agent_yields_events_in_order():
+    body = sse(("token", {"content": "He"}), ("token", {"content": "llo"}), ("response", {"content": "Hello"}))
+    events = list(client(lambda r: httpx.Response(200, content=body)).stream_agent("a", "Hi"))
+    assert [e.type for e in events] == ["token", "token", "response"]
+    assert "".join(e.content for e in events if e.type == "token") == "Hello"
+
+
+def test_network_failure_is_reported_as_network():
+    def handler(request):
+        raise httpx.ConnectError("refused")
+
+    with pytest.raises(ZihinError) as exc:
+        client(handler).list_agents()
+    assert exc.value.kind == "network"
+
+
+def test_parse_sse_handles_comments_multiline_data_and_plain_text():
+    lines = [": keep-alive", "event: a", 'data: {"x":', "data: 1}", "", "data: plain", "", "event: empty", ""]
+    assert list(parse_sse(lines)) == [("a", {"x": 1}), ("message", "plain")]