novarch 0.1.2__py3-none-any.whl

novarch/__init__.py

@@ -0,0 +1,18 @@
+"""Novarch SDK — public surface customers depend on.
+
+``from novarch import augur, NovarchKillError`` is the only import customers
+need. Everything else (HTTP client, ContextVar plumbing, upstream wrapping)
+is private.
+
+See ``docs/designs/live-system-implementation.md`` Phase 3.
+"""
+from __future__ import annotations
+
+from novarch._version import __version__ as __version__  # re-export (not in __all__)
+from novarch.augur import augur
+from novarch.exceptions import NovarchKillError
+
+# ``__version__`` is accessible as ``novarch.__version__`` but deliberately
+# kept out of ``__all__`` — the ``*``-exported surface stays augur +
+# NovarchKillError only (see test_public_novarch_surface_is_minimal).
+__all__ = ["augur", "NovarchKillError"]

novarch/_client.py

@@ -0,0 +1,393 @@
+"""HTTP client to ``novarch_server``.
+
+Sync ``httpx.Client`` because v0 SDK is sync. One client is created per
+session at decoration time and torn down at function exit.
+
+The client deals only in plain dicts — Pydantic validation lives at the
+caller (decorator) layer where it can attach session/action context to
+errors.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from novarch._version import VERSION as _SDK_VERSION
+
+
+class NovarchAPIError(RuntimeError):
+    """Raised when the backend returns a non-2xx response.
+
+    The decorator catches this to translate timeouts and 5xxs into a
+    fail-closed ``NovarchKillError`` rather than letting an httpx
+    ``HTTPStatusError`` bubble up to customer code.
+    """
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"novarch_server {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class NovarchClient:
+    def __init__(
+        self,
+        server_url: str,
+        *,
+        timeout_s: float = 30.0,
+        http_client: httpx.Client | None = None,
+        sdk_key: str | None = None,
+    ) -> None:
+        # Strip trailing slash so urljoin-style paths in the methods stay
+        # readable (`f"{base}/sessions"` instead of conditional joins).
+        self._base = server_url.rstrip("/")
+        # ``http_client`` is the SDK's seam for tests: pass a TestClient (or
+        # any httpx.Client subclass) bound to a TestClient-driven app and
+        # the SDK talks to your in-process server with no socket.
+        self._owns_http = http_client is None
+        # Phase 2 task 1: resolve the SDK key from explicit kwarg → env →
+        # nothing. When the SDK is calling a configured server the
+        # ``X-Novarch-Key`` header is required; partner agents deploy with
+        # ``NOVARCH_SDK_KEY`` set in their env. Tests that pass an
+        # explicit ``http_client`` bypass this default-header path —
+        # FastAPI's dependency_overrides handle auth in that case.
+        resolved_key = (
+            sdk_key if sdk_key is not None else os.environ.get("NOVARCH_SDK_KEY")
+        )
+        # Phase 6 task 4: declare the SDK version on every request so the
+        # server can reject a major.minor-incompatible SDK with one explicit
+        # 400 instead of a silent fail-closed kill on every action. Sent only
+        # on clients that own their httpx.Client; tests injecting an
+        # ``http_client`` (TestClient) deliberately skip the default headers.
+        default_headers: dict[str, str] = {"X-Novarch-SDK-Version": _SDK_VERSION}
+        if resolved_key:
+            default_headers["X-Novarch-Key"] = resolved_key
+        self._http = http_client or httpx.Client(
+            base_url=self._base,
+            timeout=timeout_s,
+            headers=default_headers,
+        )
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> NovarchClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def create_session(
+        self,
+        *,
+        tenant_id: str,
+        team_id: str,
+        agent_id: str,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "team_id": team_id,
+            "agent_id": agent_id,
+        }
+        if session_id is not None:
+            body["session_id"] = session_id
+        return self._post_json("/sessions", body)
+
+    def submit_action(
+        self,
+        session_id: str,
+        *,
+        action_type: str,
+        action_context: dict[str, Any],
+        agent_reasoning: str,
+        tools_called: list[dict[str, Any]],
+        action_id: str | None = None,
+        poll_timeout_s: float | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "action_type": action_type,
+            "action_context": action_context,
+            "agent_reasoning": agent_reasoning,
+            "tools_called": tools_called,
+        }
+        # Zombie-hold resolution Task 6: forward the SDK's own poll deadline
+        # so the server can stamp decisions.hold_deadline precisely (Task 5)
+        # instead of leaving it NULL for the conservative reaper sweep.
+        # Omitted (not sent as None) for back-compat with servers that
+        # predate this field.
+        if poll_timeout_s is not None:
+            body["poll_timeout_s"] = poll_timeout_s
+        if action_id is not None:
+            body["action_id"] = action_id
+        return self._post_json(f"/sessions/{session_id}/actions", body)
+
+    def report_timeout(self, session_id: str, action_id: str) -> None:
+        """Best-effort: tell the server the agent gave up waiting on a HOLD
+        so it fail-closes server-side (precise) instead of waiting for the
+        reaper backstop (Task 4). Callers swallow ``NovarchAPIError`` —
+        the local fail-closed raise stands regardless of whether this
+        report lands."""
+        self._post_no_content(f"/sessions/{session_id}/actions/{action_id}/timeout")
+
+    def complete_session(self, session_id: str) -> None:
+        """Mark the session completed (Task 2.5 / D3).
+
+        Called by ``@augur.session``'s ``finally`` on every exit path
+        (normal return or exception, including ``NovarchKillError``) so the
+        backend leaves ``status='active'``. Best-effort: the decorator
+        wraps this in a try/except and never lets a completion failure
+        break customer code, so any ``NovarchAPIError`` here is the
+        caller's problem to catch, not ours to hide."""
+        self._post_no_content(f"/sessions/{session_id}/complete")
+
+    def get_decision(self, session_id: str, action_id: str) -> dict[str, Any]:
+        """Returns ``{"decision": {...}, "verdict": {...} | None}`` immediately."""
+        return self._get_json(
+            f"/sessions/{session_id}/actions/{action_id}/decision"
+        )
+
+    def wait_for_verdict(
+        self, session_id: str, action_id: str, *, wait_s: float
+    ) -> dict[str, Any]:
+        """Long-poll for the operator verdict (Phase 4 Task 4).
+
+        The server holds the request open up to ``wait_s`` seconds until a
+        verdict for this action is committed, then returns the same
+        ``{"decision": ..., "verdict": ...}`` shape as ``get_decision`` (verdict
+        ``None`` on timeout, so the caller loops). The caller keeps ``wait_s``
+        below the client's read timeout (default 30s) so the hold returns before
+        httpx gives up; a verdict that lands mid-hold is returned at once
+        regardless, so a low client timeout only re-polls more often.
+        """
+        return self._get_json(
+            f"/sessions/{session_id}/actions/{action_id}/decision/wait?wait={wait_s}"
+        )
+
+    def submit_operator_verdict(
+        self,
+        session_id: str,
+        action_id: str,
+        *,
+        verdict: str,
+        note: str | None = None,
+        operator_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Phase 2 task 3: ``operator_id`` (when supplied) is sent as the
+        ``X-Operator-Id`` header. The server validates it against the
+        ``NOVARCH_OPERATOR_IDS`` allowlist and writes it into the audit
+        row's ``operator_id`` column."""
+        body: dict[str, Any] = {"verdict": verdict}
+        if note is not None:
+            body["note"] = note
+        headers: dict[str, str] = {}
+        if operator_id is not None:
+            headers["X-Operator-Id"] = operator_id
+        return self._post_json(
+            f"/sessions/{session_id}/actions/{action_id}/decision",
+            body,
+            headers=headers,
+        )
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _post_json(
+        self,
+        path: str,
+        body: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            r = self._http.post(path, json=body, headers=headers or None)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+        return _json_or_raise(r)
+
+    def _get_json(self, path: str) -> dict[str, Any]:
+        try:
+            r = self._http.get(path)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+        return _json_or_raise(r)
+
+    def _post_no_content(self, path: str) -> None:
+        """POST with no request body. The response body (if any) is never
+        parsed — distinct from ``_post_json``, which always parses JSON.
+        Used by endpoints like ``/complete`` (204) and the Task 6
+        ``/timeout`` self-report (200 JSON) that are state-transition
+        writes whose response payload the caller doesn't need."""
+        try:
+            r = self._http.post(path)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+
+
+class NovarchAsyncClient:
+    """Async mirror of ``NovarchClient`` over ``httpx.AsyncClient``.
+
+    Intended for framework adapters that run on an event loop (LangGraph,
+    CrewAI, ADK, etc.) where the sync client would block the loop during
+    the judge round-trip. Constructor surface is identical to
+    ``NovarchClient`` so adapters can switch by swapping the class.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        *,
+        timeout_s: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+        sdk_key: str | None = None,
+    ) -> None:
+        self._base = server_url.rstrip("/")
+        self._owns_http = http_client is None
+        resolved_key = (
+            sdk_key if sdk_key is not None else os.environ.get("NOVARCH_SDK_KEY")
+        )
+        default_headers: dict[str, str] = {"X-Novarch-SDK-Version": _SDK_VERSION}
+        if resolved_key:
+            default_headers["X-Novarch-Key"] = resolved_key
+        self._http = http_client or httpx.AsyncClient(
+            base_url=self._base,
+            timeout=timeout_s,
+            headers=default_headers,
+        )
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> NovarchAsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def acreate_session(
+        self,
+        *,
+        tenant_id: str,
+        team_id: str,
+        agent_id: str,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "team_id": team_id,
+            "agent_id": agent_id,
+        }
+        if session_id is not None:
+            body["session_id"] = session_id
+        return await self._apost_json("/sessions", body)
+
+    async def asubmit_action(
+        self,
+        session_id: str,
+        *,
+        action_type: str,
+        action_context: dict[str, Any],
+        agent_reasoning: str,
+        tools_called: list[dict[str, Any]],
+        action_id: str | None = None,
+        poll_timeout_s: float | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "action_type": action_type,
+            "action_context": action_context,
+            "agent_reasoning": agent_reasoning,
+            "tools_called": tools_called,
+        }
+        if poll_timeout_s is not None:
+            body["poll_timeout_s"] = poll_timeout_s
+        if action_id is not None:
+            body["action_id"] = action_id
+        return await self._apost_json(f"/sessions/{session_id}/actions", body)
+
+    async def await_for_verdict(
+        self, session_id: str, action_id: str, *, wait_s: float
+    ) -> dict[str, Any]:
+        return await self._aget_json(
+            f"/sessions/{session_id}/actions/{action_id}/decision/wait?wait={wait_s}"
+        )
+
+    async def areport_timeout(self, session_id: str, action_id: str) -> None:
+        """Async mirror of ``NovarchClient.report_timeout`` (Task 6)."""
+        await self._apost_no_content(
+            f"/sessions/{session_id}/actions/{action_id}/timeout"
+        )
+
+    # ------------------------------------------------------------------
+    # Internals — reuse module-level _json_or_raise and _safe_body helpers
+    # ------------------------------------------------------------------
+
+    async def _apost_json(
+        self,
+        path: str,
+        body: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            r = await self._http.post(path, json=body, headers=headers or None)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+        return _json_or_raise(r)
+
+    async def _aget_json(self, path: str) -> dict[str, Any]:
+        try:
+            r = await self._http.get(path)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+        return _json_or_raise(r)
+
+    async def _apost_no_content(self, path: str) -> None:
+        """Async mirror of ``NovarchClient._post_no_content``: POST with no
+        request body, response body (204 or 200 JSON) never parsed."""
+        try:
+            r = await self._http.post(path)
+        except httpx.HTTPError as e:
+            raise NovarchAPIError(0, f"network error: {e}") from e
+        if r.status_code >= 400:
+            raise NovarchAPIError(r.status_code, _safe_body(r))
+
+
+def _json_or_raise(r: httpx.Response) -> dict[str, Any]:
+    """Parse a 2xx body as JSON, or raise ``NovarchAPIError``.
+
+    A 200 with a non-JSON body (a proxy, captive portal, or wrong service
+    answering) would otherwise raise a raw ``json.JSONDecodeError`` from
+    ``r.json()`` — which is not an ``httpx.HTTPError``, so it would bypass the
+    decorator's fail-closed translation and crash customer code with an
+    undocumented exception. Funnel it through ``NovarchAPIError`` so the
+    write decorator turns it into a ``NovarchKillError`` like every other
+    transport failure.
+    """
+    try:
+        return r.json()
+    except ValueError as e:  # json.JSONDecodeError is a ValueError subclass
+        content_type = r.headers.get("content-type", "unknown")
+        raise NovarchAPIError(
+            r.status_code,
+            f"expected JSON but got {content_type}: {_safe_body(r)[:200]}",
+        ) from e
+
+
+def _safe_body(r: httpx.Response) -> str:
+    try:
+        return r.json().get("detail") or r.text
+    except Exception:
+        return r.text