pydecide 0.1.0__py3-none-any.whl

decide/__init__.py

@@ -0,0 +1,53 @@
+from decide.client import AsyncClient, Client
+from decide.errors import (
+    AllBackendsFailed,
+    AuthError,
+    BackendConnectionError,
+    BackendError,
+    BadResponseError,
+    ConfigError,
+    DecideError,
+    RateLimitError,
+)
+from decide.gate import Gate
+from decide.types import (
+    Choice,
+    ChoiceAnswer,
+    Content,
+    Meta,
+    Noul,
+    NoulAnswer,
+    Question,
+    Request,
+    Response,
+    Score,
+    ScoreAnswer,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AllBackendsFailed",
+    "AsyncClient",
+    "AuthError",
+    "BackendConnectionError",
+    "BackendError",
+    "BadResponseError",
+    "Choice",
+    "ChoiceAnswer",
+    "Client",
+    "ConfigError",
+    "Content",
+    "DecideError",
+    "Gate",
+    "Meta",
+    "Noul",
+    "NoulAnswer",
+    "Question",
+    "RateLimitError",
+    "Request",
+    "Response",
+    "Score",
+    "ScoreAnswer",
+    "__version__",
+]

decide/backends/__init__.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+
+from decide.backends.base import Backend, BaseBackend, Capabilities
+from decide.errors import ConfigError
+
+REGISTRY: dict[str, str] = {
+    "typesafe": "decide.backends.typesafe:TypeSafeBackend",
+    "openrouter": "decide.backends.openrouter:OpenRouterBackend",
+    "laya": "decide.backends.laya:LayaBackend",
+    "laya_mlx": "decide.backends.laya_mlx:LayaMLXBackend",
+    "crossencoder": "decide.backends.crossencoder:CrossEncoderBackend",
+    "llm": "decide.backends.llm:LLMBackend",
+}
+
+# The extra (if any) that installs the third-party dependency a backend needs.
+_EXTRAS: dict[str, str | None] = {
+    "typesafe": None,
+    "openrouter": None,
+    "laya": "pydecide[laya]",
+    "laya_mlx": "pydecide[mlx]",
+    "crossencoder": "pydecide[st]",
+    "llm": None,
+}
+
+# The third-party package whose presence determines whether a backend is importable.
+_REQUIRES: dict[str, str] = {
+    "typesafe": "httpx",
+    "openrouter": "httpx",
+    "laya": "laya",
+    "laya_mlx": "laya_mlx",
+    "crossencoder": "sentence_transformers",
+    "llm": "httpx",
+}
+
+
+def load(name: str, **kwargs: object) -> Backend:
+    """Load and instantiate a backend by its registry name, forwarding kwargs untouched."""
+    target = REGISTRY.get(name)
+    if target is None:
+        raise ConfigError(f"unknown backend {name!r}; available: {sorted(REGISTRY)}")
+
+    module_path, _, class_name = target.partition(":")
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        extra = _EXTRAS.get(name)
+        if extra:
+            message = (
+                f"backend {name!r} requires the {extra!r} extra; install it to use this backend"
+            )
+        else:
+            message = f"backend {name!r} is not available: {module_path} could not be imported"
+        raise ConfigError(message) from exc
+
+    cls = getattr(module, class_name)
+    return cls(**kwargs)
+
+
+def available() -> dict[str, bool]:
+    """Report, for each registered backend, whether its dependency is importable."""
+    return {name: importlib.util.find_spec(pkg) is not None for name, pkg in _REQUIRES.items()}
+
+
+__all__ = ["REGISTRY", "Backend", "BaseBackend", "Capabilities", "available", "load"]

decide/backends/_http.py

@@ -0,0 +1,99 @@
+"""Shared plumbing for httpx-based backends.
+
+`HttpClientMixin` gives a backend a lazily-created, reused `httpx.Client` /
+`httpx.AsyncClient` pair (plus `close()`/`aclose()`), and `raise_for_status`
+maps a non-2xx `httpx.Response` to the right `decide.errors.BackendError`
+subclass. Both `typesafe.py` and `llm.py` build on these instead of
+duplicating the client lifecycle and status-code mapping.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from decide.errors import AuthError, BackendConnectionError, BackendError, RateLimitError
+
+
+class HttpClientMixin:
+    """Lazy `httpx.Client`/`httpx.AsyncClient` lifecycle shared by HTTP backends.
+
+    Subclasses must set `self.name: str`, `self.base_url: str`,
+    `self.timeout: float`,
+    `self._transport: httpx.BaseTransport | httpx.AsyncBaseTransport | None`,
+    `self._client: httpx.Client | None = None` and
+    `self._aclient: httpx.AsyncClient | None = None` in `__init__`.
+    """
+
+    name: str
+    base_url: str
+    timeout: float
+    _transport: httpx.BaseTransport | httpx.AsyncBaseTransport | None
+    _client: httpx.Client | None
+    _aclient: httpx.AsyncClient | None
+
+    def _client_(self) -> httpx.Client:
+        """Lazily create and reuse one `httpx.Client` for this backend instance."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url, timeout=self.timeout, transport=self._transport
+            )
+        return self._client
+
+    def _aclient_(self) -> httpx.AsyncClient:
+        """Lazily create and reuse one `httpx.AsyncClient` for this backend instance."""
+        if self._aclient is None:
+            self._aclient = httpx.AsyncClient(
+                base_url=self.base_url, timeout=self.timeout, transport=self._transport
+            )
+        return self._aclient
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    async def aclose(self) -> None:
+        if self._aclient is not None:
+            await self._aclient.aclose()
+            self._aclient = None
+
+    def _post_json(
+        self, path: str, *, json: dict[str, Any], headers: dict[str, str]
+    ) -> httpx.Response:
+        """POST `json` to `path` on the sync client, mapping a transport failure to
+        `BackendConnectionError`."""
+        try:
+            return self._client_().post(path, json=json, headers=headers)
+        except httpx.TransportError as exc:
+            raise BackendConnectionError(
+                self.name, f"could not reach {self.name}: {exc}", exc
+            ) from exc
+
+    async def _apost_json(
+        self, path: str, *, json: dict[str, Any], headers: dict[str, str]
+    ) -> httpx.Response:
+        """POST `json` to `path` on the async client, mapping a transport failure to
+        `BackendConnectionError`."""
+        try:
+            return await self._aclient_().post(path, json=json, headers=headers)
+        except httpx.TransportError as exc:
+            raise BackendConnectionError(
+                self.name, f"could not reach {self.name}: {exc}", exc
+            ) from exc
+
+
+def raise_for_status(backend: str, response: httpx.Response) -> None:
+    """Raise the appropriate `BackendError` subclass for a non-2xx response.
+
+    No-op for a successful response. 401/403 -> `AuthError`, 429 ->
+    `RateLimitError`, any other 4xx/5xx -> `BackendError` carrying a short
+    excerpt of the response body.
+    """
+    if response.status_code in (401, 403):
+        raise AuthError(backend, f"authentication failed (HTTP {response.status_code})")
+    if response.status_code == 429:
+        raise RateLimitError(backend, "rate limited (HTTP 429)")
+    if response.status_code >= 400:
+        raise BackendError(backend, f"HTTP {response.status_code}: {response.text[:200]}")

decide/backends/base.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from decide.types import Answer, Meta, Request, Response
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    batch: bool = False
+    local: bool = False
+    max_choice_options: int | None = None
+
+
+@runtime_checkable
+class Backend(Protocol):
+    name: str
+
+    def capabilities(self) -> Capabilities: ...
+
+    def decide(self, request: Request) -> Response: ...
+
+    async def adecide(self, request: Request) -> Response: ...
+
+    def decide_batch(self, requests: Sequence[Request]) -> list[Response]: ...
+
+
+class BaseBackend:
+    """Common scaffolding for backend implementations.
+
+    Subclasses implement `_decide` (and, for a real async transport rather than
+    a thread-pooled sync call, `_adecide`) and may override `capabilities` and
+    `decide_batch` for backend-specific behavior (e.g. real batching).
+
+    `_decide`/`_adecide` return `(answers, raw, model)`: `model` is the model
+    name actually used to answer, or `None` to mean "report `self.model`" (the
+    common case for backends with a single fixed or instance-configured
+    model). This lets a backend that resolves its model per-request (e.g. from
+    `request.model` or a value the response itself reports) surface that in
+    `Meta.model` instead of `decide()`/`adecide()` always reporting the
+    backend's static default.
+    """
+
+    name = "base"
+    model: str | None = None
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities()
+
+    def decide(self, request: Request) -> Response:
+        start = time.perf_counter()
+        answers, raw, model = self._decide(request)
+        latency_ms = (time.perf_counter() - start) * 1000
+        return Response(
+            answers=answers,
+            meta=Meta(
+                backend=self.name,
+                model=model if model is not None else self.model,
+                latency_ms=latency_ms,
+                route=[],
+                raw=raw,
+            ),
+        )
+
+    def _decide(self, request: Request) -> tuple[dict[str, Answer], Any, str | None]:
+        raise NotImplementedError
+
+    async def adecide(self, request: Request) -> Response:
+        start = time.perf_counter()
+        answers, raw, model = await self._adecide(request)
+        latency_ms = (time.perf_counter() - start) * 1000
+        return Response(
+            answers=answers,
+            meta=Meta(
+                backend=self.name,
+                model=model if model is not None else self.model,
+                latency_ms=latency_ms,
+                route=[],
+                raw=raw,
+            ),
+        )
+
+    async def _adecide(self, request: Request) -> tuple[dict[str, Answer], Any, str | None]:
+        return await asyncio.to_thread(self._decide, request)
+
+    def decide_batch(self, requests: Sequence[Request]) -> list[Response]:
+        return [self.decide(r) for r in requests]