system-one 0.1.0__py3-none-any.whl

system_one/__init__.py

@@ -0,0 +1,65 @@
+"""A vendor-neutral SDK for System One models: `ask(state, questions) -> answers`."""
+
+from importlib.metadata import version
+
+from system_one.agent import AsyncSystemOne, SystemOne
+from system_one.errors import (
+    RETRY_STATUSES,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    SystemOneError,
+)
+from system_one.schemas import (
+    Answer,
+    Choice,
+    ChoiceAnswer,
+    Noul,
+    NoulAnswer,
+    NoulCriteria,
+    Question,
+    Score,
+    ScoreAnswer,
+    SystemOneInput,
+    SystemOneOutput,
+    Usage,
+)
+from system_one.settings import (
+    HTTPConfig,
+    ONNXConfig,
+    OpenRouterConfig,
+    Settings,
+    TypesafeConfig,
+)
+
+__version__ = version("system-one")
+
+__all__ = [
+    "RETRY_STATUSES",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "Answer",
+    "AsyncSystemOne",
+    "AuthenticationError",
+    "Choice",
+    "ChoiceAnswer",
+    "HTTPConfig",
+    "Noul",
+    "NoulAnswer",
+    "NoulCriteria",
+    "ONNXConfig",
+    "OpenRouterConfig",
+    "Question",
+    "Score",
+    "ScoreAnswer",
+    "Settings",
+    "SystemOne",
+    "SystemOneError",
+    "SystemOneInput",
+    "SystemOneOutput",
+    "TypesafeConfig",
+    "Usage",
+    "__version__",
+]

system_one/agent.py

@@ -0,0 +1,106 @@
+"""The one public entry point: `SystemOne.ask(state, questions)`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from system_one.backends import create_async_backend, create_backend
+from system_one.schemas import SystemOneInput
+from system_one.settings import ONNXConfig, Settings
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from system_one.backends import AsyncBackend, Backend
+    from system_one.schemas import QuestionInput, State, SystemOneOutput
+    from system_one.settings import BackendConfig
+
+
+class BaseSystemOne:
+    """Settings resolution and input building, shared by the sync and async agents.
+
+    `config` is the backend's own configuration — `TypesafeConfig()`,
+    `OpenRouterConfig()`, `HTTPConfig(base_url=..., model=...)` or `ONNXConfig()` —
+    and picks the backend to build; omitted, `SYSTEM_ONE_BACKEND` decides and the
+    config is read from the environment. `using` hands over an already-built backend
+    instead, which is how tests and custom providers plug in.
+    """
+
+    backend: Any  # narrowed to `Backend` / `AsyncBackend` by the two subclasses
+
+    def __init__(self, config: BackendConfig | None = None, **overrides: Any) -> None:
+        if config is not None and "backend" not in overrides:
+            overrides["backend"] = "onnx" if isinstance(config, ONNXConfig) else "http"
+        self.settings = Settings(**overrides)
+        self.config = config
+
+    def _input(
+        self, state: State, questions: QuestionInput, model: str | None
+    ) -> SystemOneInput:
+        return SystemOneInput.model_validate(
+            {
+                "state": state,
+                "model": model or self.settings.model or self.backend.model,
+                "questions": questions,
+            }
+        )
+
+
+class SystemOne(BaseSystemOne):
+    """Ask typed questions about a state and get calibrated answers back."""
+
+    def __init__(
+        self,
+        config: BackendConfig | None = None,
+        *,
+        using: Backend | None = None,
+        **overrides: Any,
+    ) -> None:
+        super().__init__(config, **overrides)
+        self.backend: Backend = (
+            using if using is not None else create_backend(self.settings, config)
+        )
+
+    def ask(
+        self, state: State, questions: QuestionInput, *, model: str | None = None
+    ) -> SystemOneOutput:
+        return self.backend.ask(self._input(state, questions, model))
+
+    def close(self) -> None:
+        self.backend.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncSystemOne(BaseSystemOne):
+    """The async counterpart of `SystemOne`: the same `ask`, awaited."""
+
+    def __init__(
+        self,
+        config: BackendConfig | None = None,
+        *,
+        using: AsyncBackend | None = None,
+        **overrides: Any,
+    ) -> None:
+        super().__init__(config, **overrides)
+        self.backend: AsyncBackend = (
+            using if using is not None else create_async_backend(self.settings, config)
+        )
+
+    async def ask(
+        self, state: State, questions: QuestionInput, *, model: str | None = None
+    ) -> SystemOneOutput:
+        return await self.backend.ask(self._input(state, questions, model))
+
+    async def close(self) -> None:
+        await self.backend.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

system_one/backends/__init__.py

@@ -0,0 +1,94 @@
+"""Backend selection. Vendor imports stay inside the factories so the extras stay optional."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Protocol, TypeVar
+
+from system_one.errors import SystemOneError
+from system_one.settings import BackendConfig, HTTPConfig, ONNXConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from system_one.schemas import SystemOneInput, SystemOneOutput
+    from system_one.settings import Settings
+
+Config = TypeVar("Config", bound=BackendConfig)
+
+EXTRA_HINTS = {
+    "http": "The http backend needs httpx2: pip install 'system-one[http]'",
+    "onnx": "The onnx backend needs onnxruntime, tokenizers and numpy: "
+    "pip install 'system-one[onnx]'",
+}
+
+
+class Backend(Protocol):
+    """What `SystemOne` needs from a backend."""
+
+    model: str
+    """The model to ask when neither the call nor `SYSTEM_ONE_MODEL` names one."""
+
+    def ask(self, request: SystemOneInput) -> SystemOneOutput: ...
+
+    def close(self) -> None: ...
+
+
+class AsyncBackend(Protocol):
+    """The same two methods as `Backend`, awaited."""
+
+    model: str
+
+    async def ask(self, request: SystemOneInput) -> SystemOneOutput: ...
+
+    async def close(self) -> None: ...
+
+
+@contextmanager
+def _hint(name: str) -> Iterator[None]:
+    """Turn a missing vendor dependency — and only that — into its install hint."""
+    try:
+        yield
+    except ImportError as exc:
+        raise ImportError(EXTRA_HINTS[name]) from exc
+
+
+def _resolve(
+    settings: Settings, config: BackendConfig | None, default: type[Config]
+) -> Config:
+    """The config to build with: the given one, or one read from the environment."""
+    # mypy cannot see that pydantic-settings fills the required fields from env.
+    config = default() if config is None else config  # type: ignore[call-arg]
+    if not isinstance(config, default):
+        message = (
+            f"{type(config).__name__} does not configure the "
+            f"{settings.backend!r} backend."
+        )
+        raise SystemOneError(message)
+    if settings.model is not None:
+        config = config.model_copy(update={"model": settings.model})
+    return config
+
+
+def create_backend(settings: Settings, config: BackendConfig | None = None) -> Backend:
+    """The sync backend named by `settings.backend`."""
+    if settings.backend == "onnx":
+        with _hint("onnx"):
+            from system_one.backends.onnx import ONNXBackend
+        return ONNXBackend(_resolve(settings, config, ONNXConfig))
+    with _hint("http"):
+        from system_one.backends.http import HTTPBackend
+    return HTTPBackend(_resolve(settings, config, HTTPConfig))
+
+
+def create_async_backend(
+    settings: Settings, config: BackendConfig | None = None
+) -> AsyncBackend:
+    """The async backend named by `settings.backend`."""
+    if settings.backend == "onnx":
+        with _hint("onnx"):
+            from system_one.backends.onnx import AsyncONNXBackend
+        return AsyncONNXBackend(_resolve(settings, config, ONNXConfig))
+    with _hint("http"):
+        from system_one.backends.http import AsyncHTTPBackend
+    return AsyncHTTPBackend(_resolve(settings, config, HTTPConfig))

system_one/backends/http.py

@@ -0,0 +1,182 @@
+"""One HTTP backend for every vendor: same JSON body, the config carries the endpoint."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+import time
+from typing import TYPE_CHECKING, Any
+
+import httpx2
+
+from system_one import __version__
+from system_one.errors import (
+    RETRY_STATUSES,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    SystemOneError,
+)
+from system_one.schemas import SystemOneOutput
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from system_one.schemas import SystemOneInput
+    from system_one.settings import HTTPConfig
+
+logger = logging.getLogger("system_one")
+
+MAX_BACKOFF = 5.0
+INITIAL_BACKOFF = 0.5
+MAX_ERROR_BODY = 200
+AUTH_STATUSES = frozenset({401, 403})
+
+
+def retry_after(headers: Mapping[str, str]) -> float | None:
+    """Read `retry-after-ms` then `retry-after`. HTTP-date forms fall back to backoff."""
+    for header, divisor in (("retry-after-ms", 1000.0), ("retry-after", 1.0)):
+        raw = headers.get(header)
+        if raw is None:
+            continue
+        try:
+            return float(raw) / divisor
+        except ValueError:
+            continue
+    return None
+
+
+def backoff(attempt: int, after: float | None) -> float:
+    if after is not None:
+        return min(after, MAX_BACKOFF)
+    delay = min(MAX_BACKOFF, INITIAL_BACKOFF * (1 << attempt))
+    return delay * (0.5 + secrets.randbelow(500) / 1000)
+
+
+def api_error(response: httpx2.Response) -> APIError:
+    status = response.status_code
+    error = AuthenticationError if status in AUTH_STATUSES else APIError
+    return error(
+        f"System One API returned {status}",
+        status=status,
+        body=response.text[:MAX_ERROR_BODY],
+        retry_after=retry_after(response.headers),
+    )
+
+
+def is_retryable(error: SystemOneError) -> bool:
+    if isinstance(error, AuthenticationError):
+        return False
+    if isinstance(error, APIError):
+        return error.status in RETRY_STATUSES
+    return True
+
+
+def transport_error(request: httpx2.Request, exc: httpx2.HTTPError) -> SystemOneError:
+    if isinstance(exc, httpx2.TimeoutException):
+        return APITimeoutError(f"Request to {request.url} timed out")
+    return APIConnectionError(f"Could not reach {request.url}")
+
+
+class BaseHTTPBackend:
+    """Request building, error mapping and retry pacing, shared by both flavours."""
+
+    def __init__(self, config: HTTPConfig, *, transport: Any = None) -> None:
+        self.config = config
+        self.model = config.model
+        self.base_url = config.base_url.rstrip("/")
+        self.path = config.path
+        self._transport = transport
+        self._headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"system-one/{__version__}",
+        }
+        if config.api_key is not None:
+            self._headers["Authorization"] = (
+                f"Bearer {config.api_key.get_secret_value()}"
+            )
+
+    def _build(self, method: str, path: str, body: str | None = None) -> httpx2.Request:
+        url = self.base_url + path
+        logger.debug("%s %s", method, url)
+        return httpx2.Request(method, url, headers=self._headers, content=body)
+
+    def _ask_request(self, request: SystemOneInput) -> httpx2.Request:
+        return self._build("POST", self.path, request.model_dump_json())
+
+    def _delay_or_reraise(self, error: SystemOneError, attempt: int) -> float:
+        if attempt >= self.config.max_retries or not is_retryable(error):
+            raise error
+        after = error.retry_after if isinstance(error, APIError) else None
+        return backoff(attempt, after)
+
+
+class HTTPBackend(BaseHTTPBackend):
+    """Talks to any vendor implementing the System One contract over HTTP."""
+
+    def __init__(self, config: HTTPConfig, *, transport: Any = None) -> None:
+        super().__init__(config, transport=transport)
+        self._client = httpx2.Client(timeout=config.timeout, transport=transport)
+
+    def ask(self, request: SystemOneInput) -> SystemOneOutput:
+        response = self._send(self._ask_request(request))
+        return SystemOneOutput.model_validate_json(response.content)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _send(self, request: httpx2.Request) -> httpx2.Response:
+        attempt = 0
+        while True:
+            try:
+                return self._attempt(request)
+            except SystemOneError as exc:
+                delay = self._delay_or_reraise(exc, attempt)
+                attempt += 1
+            time.sleep(delay)
+
+    def _attempt(self, request: httpx2.Request) -> httpx2.Response:
+        try:
+            response = self._client.send(request)
+        except httpx2.HTTPError as exc:
+            raise transport_error(request, exc) from exc
+        if response.is_success:
+            return response
+        raise api_error(response)
+
+
+class AsyncHTTPBackend(BaseHTTPBackend):
+    """The async counterpart of `HTTPBackend`, sharing its config and retry policy."""
+
+    def __init__(self, config: HTTPConfig, *, transport: Any = None) -> None:
+        super().__init__(config, transport=transport)
+        self._client = httpx2.AsyncClient(timeout=config.timeout, transport=transport)
+
+    async def ask(self, request: SystemOneInput) -> SystemOneOutput:
+        response = await self._send(self._ask_request(request))
+        return SystemOneOutput.model_validate_json(response.content)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def _send(self, request: httpx2.Request) -> httpx2.Response:
+        attempt = 0
+        while True:
+            try:
+                return await self._attempt(request)
+            except SystemOneError as exc:
+                delay = self._delay_or_reraise(exc, attempt)
+                attempt += 1
+            await asyncio.sleep(delay)
+
+    async def _attempt(self, request: httpx2.Request) -> httpx2.Response:
+        try:
+            response = await self._client.send(request)
+        except httpx2.HTTPError as exc:
+            raise transport_error(request, exc) from exc
+        if response.is_success:
+            return response
+        raise api_error(response)