nullprotocol 0.2.0__py3-none-any.whl

nullprotocol/_transport.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import os
+import re
+import time
+from typing import Any, NoReturn
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._errors import APIError, ProtocolError, TransportError
+
+_UNSET = object()
+
+
+def json_body(value: Any) -> bytes:
+    try:
+        return json.dumps(
+            value, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+        ).encode()
+    except (TypeError, ValueError, UnicodeError) as exc:
+        raise ValueError("Request data must be valid UTF-8 JSON (no NaN or Infinity).") from exc
+
+
+def utf16_length(value: str) -> int:
+    try:
+        return len(value.encode("utf-16-le")) // 2
+    except UnicodeError as exc:
+        raise ValueError("Text must not contain unpaired surrogates.") from exc
+
+
+def identifier(value: str, kind: str) -> str:
+    pattern = r"[a-z0-9][a-z0-9._-]{0,63}" if kind == "agent ID" else r"[a-z][a-z0-9._-]{0,63}"
+    if not isinstance(value, str) or not re.fullmatch(pattern, value):
+        raise ValueError(f"Invalid {kind}.")
+    return value
+
+
+def scope_id(value: str | None) -> str | None:
+    if value is not None and (
+        not isinstance(value, str)
+        or not 1 <= utf16_length(value) <= 128
+        or re.search(r"[\x00-\x1f\x7f-\x9f]", value)
+    ):
+        raise ValueError("scope must be 1–128 UTF-16 characters without control characters.")
+    return value
+
+
+def request_id(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[\x21-\x7e]{1,128}", value):
+        raise ValueError("idempotency_key must be 1–128 visible ASCII characters without spaces.")
+    return value
+
+
+class _Config:
+    def __init__(
+        self, key: str | None, endpoint: str | None, timeout: float, max_retries: int
+    ) -> None:
+        actual = key if key is not None else os.environ.get("NULLPROTOCOL_KEY")
+        if (
+            not isinstance(actual, str)
+            or not actual.strip()
+            or re.search(r"[\s\x00-\x1f\x7f]", actual)
+        ):
+            raise ValueError("Set key or NULLPROTOCOL_KEY to an active Space SDK key.")
+        address = (
+            endpoint or os.environ.get("NULLPROTOCOL_API_URL") or "https://api.nullprotocol.ai"
+        )
+        parsed = urlsplit(address)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.netloc
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or parsed.path.rstrip("/") not in ("", "/v1")
+        ):
+            raise ValueError("endpoint must be an HTTP(S) origin, optionally ending in /v1.")
+        if (
+            not isinstance(timeout, (int, float))
+            or isinstance(timeout, bool)
+            or not math.isfinite(timeout)
+            or timeout <= 0
+        ):
+            raise ValueError("timeout must be a positive number of seconds.")
+        if type(max_retries) is not int or not 0 <= max_retries <= 5:
+            raise ValueError("max_retries must be an integer from 0 to 5.")
+        self.base = address.rstrip("/").removesuffix("/v1") + "/v1"
+        self.key = actual
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+
+def _invalid_constant(_value: str) -> NoReturn:
+    raise ValueError("Non-finite numbers are not valid JSON.")
+
+
+def _decode(response: httpx.Response, task_id: str | None) -> dict[str, Any]:
+    try:
+        body = response.json(parse_constant=_invalid_constant)
+    except ValueError as exc:
+        if not response.is_success:
+            raise APIError(
+                response.status_code,
+                "non_json_response",
+                request_id=task_id,
+                retry_after=response.headers.get("retry-after"),
+            ) from exc
+        raise ProtocolError("Expected a JSON response.", request_id=task_id) from exc
+    if not response.is_success:
+        detail = body if isinstance(body, dict) else {}
+        error = detail.get("error", "http_error")
+        raise APIError(
+            response.status_code,
+            error if isinstance(error, str) else "http_error",
+            request_id=task_id,
+            details=detail,
+            retry_after=response.headers.get("retry-after"),
+        )
+    if not isinstance(body, dict):
+        raise ProtocolError("Expected a JSON object response.", request_id=task_id)
+    return body
+
+
+def _delay(response: httpx.Response | None, attempt: int) -> float | None:
+    if response is not None:
+        retry_after = response.headers.get("retry-after")
+        if retry_after is not None:
+            try:
+                value = float(retry_after)
+            except ValueError:
+                return None  # Do not guess when a server supplies an unsupported date format.
+            if not math.isfinite(value) or value < 0 or value > 30:
+                return None  # Return the response instead of ignoring a long delay.
+            return value
+    return float(min(0.25 * (2**attempt), 2.0))
+
+
+def _retryable(response: httpx.Response) -> bool:
+    if response.status_code == 429:
+        return True
+    if response.status_code == 409:
+        try:
+            return bool(response.json().get("error") == "in_progress")
+        except (ValueError, AttributeError):
+            return False
+    if response.status_code == 503:
+        try:
+            return bool(response.json().get("error") == "busy")
+        except (ValueError, AttributeError):
+            return False
+    return False
+
+
+class Transport:
+    def __init__(self, config: _Config, client: httpx.Client | None = None) -> None:
+        self.config = config
+        self.client = client if client is not None else httpx.Client(follow_redirects=False)
+        self.owned = client is None
+        self.closed = False
+
+    def close(self) -> None:
+        if not self.closed:
+            self.closed = True
+            if self.owned:
+                self.client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = _UNSET,
+        params: dict[str, str] | None = None,
+        task_id: str | None = None,
+    ) -> dict[str, Any]:
+        if self.closed:
+            raise TransportError("This NullProtocol client is closed.", request_id=task_id)
+        content = None if body is _UNSET else json_body(body)
+        headers = {"Authorization": f"Bearer {self.config.key}", "Accept": "application/json"}
+        if content is not None:
+            headers["Content-Type"] = "application/json"
+        if task_id is not None:
+            headers["Idempotency-Key"] = task_id
+        retries = self.config.max_retries if method == "GET" or task_id is not None else 0
+        for attempt in range(retries + 1):
+            response = None
+            try:
+                response = self.client.request(
+                    method,
+                    self.config.base + path,
+                    headers=headers,
+                    content=content,
+                    params=params,
+                    timeout=self.config.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TransportError as exc:
+                if attempt == retries:
+                    raise TransportError(
+                        "NullProtocol could not be reached. "
+                        "Preserve request_id before retrying a run.",
+                        request_id=task_id,
+                    ) from exc
+            if response is not None and (attempt == retries or not _retryable(response)):
+                return _decode(response, task_id)
+            delay = _delay(response, attempt)
+            if delay is None:
+                assert response is not None
+                return _decode(response, task_id)
+            time.sleep(delay)
+        raise AssertionError("Unreachable transport state")
+
+
+class AsyncTransport:
+    def __init__(self, config: _Config, client: httpx.AsyncClient | None = None) -> None:
+        self.config = config
+        self.client = client if client is not None else httpx.AsyncClient(follow_redirects=False)
+        self.owned = client is None
+        self.closed = False
+
+    async def close(self) -> None:
+        if not self.closed:
+            self.closed = True
+            if self.owned:
+                await self.client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = _UNSET,
+        params: dict[str, str] | None = None,
+        task_id: str | None = None,
+    ) -> dict[str, Any]:
+        if self.closed:
+            raise TransportError("This NullProtocol client is closed.", request_id=task_id)
+        content = None if body is _UNSET else json_body(body)
+        headers = {"Authorization": f"Bearer {self.config.key}", "Accept": "application/json"}
+        if content is not None:
+            headers["Content-Type"] = "application/json"
+        if task_id is not None:
+            headers["Idempotency-Key"] = task_id
+        retries = self.config.max_retries if method == "GET" or task_id is not None else 0
+        for attempt in range(retries + 1):
+            response = None
+            try:
+                response = await self.client.request(
+                    method,
+                    self.config.base + path,
+                    headers=headers,
+                    content=content,
+                    params=params,
+                    timeout=self.config.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TransportError as exc:
+                if attempt == retries:
+                    raise TransportError(
+                        "NullProtocol could not be reached. "
+                        "Preserve request_id before retrying a run.",
+                        request_id=task_id,
+                    ) from exc
+            if response is not None and (attempt == retries or not _retryable(response)):
+                return _decode(response, task_id)
+            delay = _delay(response, attempt)
+            if delay is None:
+                assert response is not None
+                return _decode(response, task_id)
+            await asyncio.sleep(delay)
+        raise AssertionError("Unreachable transport state")

nullprotocol/_types.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+from uuid import UUID
+
+from ._errors import ProtocolError
+
+T = TypeVar("T")
+
+
+def _count(value: Any, name: str) -> int:
+    if type(value) is not int or value < 0:
+        raise ProtocolError(f"Invalid {name} in the server response.")
+    return value
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int
+    output_tokens: int
+    uncounted_requests: int | None = None
+
+    @classmethod
+    def from_dict(cls, value: Any) -> Usage | None:
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise ProtocolError("Invalid generation usage in the server response.")
+        uncounted = value.get("uncountedRequests")
+        if uncounted is not None:
+            uncounted = _count(uncounted, "uncountedRequests")
+            if uncounted == 0:
+                raise ProtocolError("uncountedRequests must be positive when reported.")
+        return cls(
+            _count(value.get("inputTokens"), "inputTokens"),
+            _count(value.get("outputTokens"), "outputTokens"),
+            uncounted,
+        )
+
+
+@dataclass(frozen=True)
+class KnowledgeUsage:
+    input_tokens: int | None = None
+    uncounted_requests: int | None = None
+
+    @classmethod
+    def from_dict(cls, value: Any) -> KnowledgeUsage | None:
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise ProtocolError("Invalid Knowledge usage in the server response.")
+        counted, uncounted = value.get("inputTokens"), value.get("uncountedRequests")
+        if counted is not None:
+            counted = _count(counted, "Knowledge inputTokens")
+        if uncounted is not None:
+            uncounted = _count(uncounted, "Knowledge uncountedRequests")
+            if uncounted == 0:
+                raise ProtocolError("Knowledge uncountedRequests must be positive.")
+        return cls(counted, uncounted)
+
+
+@dataclass(frozen=True, eq=False)
+class Result(Generic[T]):
+    """A model-operation result. raw preserves all server fields without renaming JSON data."""
+
+    success: bool
+    operation_id: str | None
+    request_id: str
+    data: T | None = None
+    summary: str | None = None
+    key_points: list[str] | None = None
+    recommendation: str | None = None
+    score: float | None = None
+    reasoning: str | None = None
+    action: str | None = None
+    parameters: dict[str, Any] | None = None
+    error_code: str | None = None
+    error: str | None = None
+    attempts: int | None = None
+    repaired: bool | None = None
+    usage: Usage | None = None
+    knowledge_usage: KnowledgeUsage | None = None
+    knowledge: dict[str, Any] | None = None
+    history_error: str | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        return deepcopy(self._raw)
+
+    @classmethod
+    def from_response(cls, response: dict[str, Any], request_id: str) -> Result[Any]:
+        value = response.get("result")
+        if not isinstance(value, dict) or type(value.get("success")) is not bool:
+            raise ProtocolError(
+                "Missing operation result in the server response.", request_id=request_id
+            )
+        if "operationId" not in response:
+            raise ProtocolError(
+                "Missing operationId in the server response.", request_id=request_id
+            )
+        operation_id = response.get("operationId")
+        if operation_id is not None and not isinstance(operation_id, str):
+            raise ProtocolError(
+                "Invalid operationId in the server response.", request_id=request_id
+            )
+        if operation_id is not None:
+            try:
+                UUID(operation_id)
+            except ValueError as exc:
+                raise ProtocolError("Invalid operationId UUID.", request_id=request_id) from exc
+        for name in ("attempts",):
+            if name in value:
+                try:
+                    _count(value[name], name)
+                except ProtocolError as exc:
+                    exc.request_id = request_id
+                    raise
+        if "repaired" in value and type(value["repaired"]) is not bool:
+            raise ProtocolError("Invalid repaired flag.", request_id=request_id)
+        if "historyError" in value and not isinstance(value["historyError"], str):
+            raise ProtocolError("Invalid historyError.", request_id=request_id)
+        if "knowledge" in value and not isinstance(value["knowledge"], dict):
+            raise ProtocolError("Invalid Knowledge evidence.", request_id=request_id)
+        if not value["success"] and not all(
+            isinstance(value.get(key), str) for key in ("errorCode", "error")
+        ):
+            raise ProtocolError("Missing operation error details.", request_id=request_id)
+        try:
+            usage = Usage.from_dict(value.get("usage"))
+            knowledge_usage = KnowledgeUsage.from_dict(value.get("knowledgeUsage"))
+        except ProtocolError as exc:
+            exc.request_id = request_id
+            raise
+        return cls(
+            success=value["success"],
+            operation_id=operation_id,
+            request_id=request_id,
+            data=deepcopy(value.get("data")),
+            summary=value.get("summary"),
+            key_points=deepcopy(value.get("keyPoints")),
+            recommendation=value.get("recommendation"),
+            score=value.get("score"),
+            reasoning=value.get("reasoning"),
+            action=value.get("action"),
+            parameters=deepcopy(value.get("parameters")),
+            error_code=value.get("errorCode"),
+            error=value.get("error"),
+            attempts=value.get("attempts"),
+            repaired=value.get("repaired"),
+            usage=usage,
+            knowledge_usage=knowledge_usage,
+            knowledge=deepcopy(value.get("knowledge")),
+            history_error=value.get("historyError"),
+            _raw=deepcopy(value),
+        )
+
+
+@dataclass(frozen=True)
+class Execution:
+    success: bool
+    outcome: str
+    action: str | None = None
+    result: Any = None
+    error_code: str | None = None
+    error: str | None = None
+    history_error: str | None = None
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    decision: Result[Any]
+    input: Any