modelgov 1.0.0__py3-none-any.whl

modelgov/__init__.py

@@ -0,0 +1,82 @@
+"""Modelgov Python SDK.
+
+A typed, idiomatic Python client for the Modelgov AI policy gateway. Mirrors
+the TypeScript SDK's surface (``@modelgov/sdk``).
+
+Example:
+    >>> from modelgov import ModelgovClient
+    >>> client = ModelgovClient(base_url="http://localhost:3000", api_key="sk-...")
+    >>> res = client.chat(
+    ...     user_id="user_123",
+    ...     user_type="logged_in",
+    ...     feature="support_chat",
+    ...     model_class="cheap",
+    ...     messages=[{"role": "user", "content": "Help me reset my password"}],
+    ... )
+    >>> print(res["message"]["content"])
+"""
+
+from .client import ModelgovClient
+from .errors import ModelgovError, PolicyBlockedError, SafetyBlockedError
+from .types import (
+    BudgetRemaining,
+    ChatMessage,
+    ChatResponse,
+    ChatResult,
+    ContentPart,
+    Cost,
+    EmbeddingsResponse,
+    EmbeddingsResult,
+    EmbeddingsUsage,
+    ExplainBudget,
+    ExplainBudgetUsed,
+    ExplainCost,
+    ExplainRequested,
+    ExplainResolved,
+    ExplainResponse,
+    ExplainResult,
+    ExplainSafety,
+    ImagePart,
+    ImageUrl,
+    ResponseMessage,
+    Safety,
+    TextPart,
+    Usage,
+    UsageResponse,
+    UsageResult,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ModelgovClient",
+    "ModelgovError",
+    "PolicyBlockedError",
+    "SafetyBlockedError",
+    "ChatMessage",
+    "ChatResponse",
+    "ChatResult",
+    "TextPart",
+    "ImageUrl",
+    "ImagePart",
+    "ContentPart",
+    "EmbeddingsResponse",
+    "EmbeddingsResult",
+    "EmbeddingsUsage",
+    "Usage",
+    "Cost",
+    "BudgetRemaining",
+    "Safety",
+    "ResponseMessage",
+    "ExplainRequested",
+    "ExplainResolved",
+    "ExplainSafety",
+    "ExplainCost",
+    "ExplainBudgetUsed",
+    "ExplainBudget",
+    "ExplainResponse",
+    "ExplainResult",
+    "UsageResponse",
+    "UsageResult",
+    "__version__",
+]

modelgov/client.py

@@ -0,0 +1,564 @@
+"""Synchronous Modelgov API client.
+
+A thin, typed HTTP client over the Modelgov REST API. Policy enforcement is
+always server-side; this client just shapes requests and maps errors. It
+mirrors the TypeScript SDK (``packages/sdk-typescript``) in API surface and
+ergonomics, adapted to idiomatic Python:
+
+* keyword-only, snake_case call signatures (``user_id`` -> JSON ``userId``);
+* structured exceptions (:class:`~modelgov.errors.ModelgovError` and
+  subclasses) carrying the API error envelope;
+* a streaming generator (:meth:`ModelgovClient.chat_stream`) over SSE.
+"""
+
+from __future__ import annotations
+
+import json
+from types import TracebackType
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Type, Union
+
+import httpx
+
+from .errors import ModelgovError, PolicyBlockedError, SafetyBlockedError
+from .types import (
+    ChatMessage,
+    ChatResult,
+    EmbeddingsResult,
+    ExplainResult,
+    UsageResult,
+)
+
+__all__ = ["ModelgovClient"]
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class ModelgovClient:
+    """Synchronous client for the Modelgov API.
+
+    Args:
+        base_url: Base URL of the Modelgov API (e.g. ``http://localhost:3000``).
+            A trailing slash is stripped.
+        api_key: Sent as ``Authorization: Bearer <api_key>`` when provided.
+        timeout: Request timeout in seconds (or any value ``httpx`` accepts).
+            Defaults to 30s.
+        http_client: Optional pre-built ``httpx.Client`` for custom transports
+            or test injection. When provided, ``timeout`` is ignored and the
+            caller owns the client's lifecycle.
+
+    Example:
+        >>> client = ModelgovClient(base_url="http://localhost:3000", api_key="sk-...")
+        >>> res = client.chat(
+        ...     user_id="user_123",
+        ...     user_type="logged_in",
+        ...     feature="support_chat",
+        ...     messages=[{"role": "user", "content": "Hello"}],
+        ... )
+        >>> res["message"]["content"]
+
+    The client is a context manager; use ``with ModelgovClient(...) as c:`` to
+    close the underlying connection pool automatically.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        *,
+        timeout: Union[float, httpx.Timeout, None] = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if this instance owns it)."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "ModelgovClient":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    # -- headers ------------------------------------------------------------
+
+    def _headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        headers: Dict[str, str] = {"content-type": "application/json"}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        if extra:
+            headers.update({k: v for k, v in extra.items() if v is not None})
+        return headers
+
+    # -- public API ---------------------------------------------------------
+
+    def chat(
+        self,
+        *,
+        user_id: str,
+        user_type: str,
+        feature: str,
+        messages: Sequence[ChatMessage],
+        context: Optional[Sequence[str]] = None,
+        model_class: Optional[str] = None,
+        requested_model_class: Optional[str] = None,
+        input_tokens_estimate: Optional[int] = None,
+        temperature: Optional[float] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> ChatResult:
+        """Run a guarded chat completion (``POST /v1/chat``).
+
+        Args:
+            user_id: Your end-user id. Required.
+            user_type: Must match a user type in ``modelgov.yaml``. Required.
+            feature: Registered feature name. Required.
+            messages: List of ``{"role", "content"}`` messages. ``content`` is a
+                string, or a list of content parts (``{"type": "text", ...}`` /
+                ``{"type": "image_url", "image_url": {"url": ...}}``) for vision.
+            context: Retrieved passages for a grounded feature (safety
+                ``grounding: strict``). The gateway answers ONLY from these,
+                forces verbatim citations, and verifies them; unverifiable
+                answers become a safe refusal.
+            model_class: Requested model class (e.g. ``"cheap"``). Maps to the
+                API's ``modelClass`` field.
+            requested_model_class: Alias for ``model_class``; if both are given,
+                ``model_class`` wins. Provided for parity with callers that use
+                the more explicit name.
+            input_tokens_estimate: Optional pre-estimate for budget checks.
+            temperature: Sampling temperature (0-2).
+            project_id: Optional project scope.
+            environment: Optional environment tag.
+            idempotency_key: Sent as the ``Idempotency-Key`` header. Retrying
+                with the same key + body replays the first result instead of
+                re-charging budget or re-calling the model.
+            metadata: Arbitrary key/value data stored on the audit log
+                (max 32 keys). Does not affect policy.
+
+        Returns:
+            The decoded :class:`~modelgov.types.ChatResponse` body.
+
+        Raises:
+            SafetyBlockedError: 403 ``safety_blocked``.
+            PolicyBlockedError: 403 ``policy_blocked`` / ``budget_exceeded``.
+            ModelgovError: any other non-2xx response.
+        """
+        body = self._chat_body(
+            user_id=user_id,
+            user_type=user_type,
+            feature=feature,
+            messages=messages,
+            context=context,
+            model_class=model_class,
+            requested_model_class=requested_model_class,
+            input_tokens_estimate=input_tokens_estimate,
+            temperature=temperature,
+            project_id=project_id,
+            environment=environment,
+            metadata=metadata,
+        )
+        extra = {"idempotency-key": idempotency_key} if idempotency_key else None
+        response = self._client.post(
+            f"{self.base_url}/v1/chat",
+            headers=self._headers(extra),
+            json=body,
+        )
+        return self._handle_json(response)  # type: ignore[return-value]
+
+    def chat_stream(
+        self,
+        *,
+        user_id: str,
+        user_type: str,
+        feature: str,
+        messages: Sequence[ChatMessage],
+        context: Optional[Sequence[str]] = None,
+        model_class: Optional[str] = None,
+        requested_model_class: Optional[str] = None,
+        input_tokens_estimate: Optional[int] = None,
+        temperature: Optional[float] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> Iterator[str]:
+        """Stream a guarded chat completion as incremental text chunks.
+
+        Sends the same body as :meth:`chat` plus ``"stream": true`` and yields
+        text deltas as they arrive. The generator holds the HTTP connection
+        open until it is fully consumed (or closed); use it in a ``for`` loop
+        or wrap it in ``contextlib.closing`` if you may abandon it early.
+
+        SSE framing assumption:
+            The server responds with ``Content-Type: text/event-stream`` and
+            OpenAI-style Server-Sent Events — one event per ``data:`` line,
+            terminated by a literal ``data: [DONE]`` sentinel. Each non-sentinel
+            ``data:`` payload is JSON. This client extracts the incremental
+            text from, in order of preference:
+
+            * ``chunk["choices"][0]["delta"]["content"]`` (OpenAI chat delta),
+            * ``chunk["delta"]`` or ``chunk["content"]`` or ``chunk["text"]``
+              (simpler shapes the Modelgov API may emit).
+
+            If a ``data:`` payload is not valid JSON it is yielded verbatim as a
+            text chunk (tolerant of a plain-text delta stream). Empty deltas are
+            skipped. This mirrors how the TypeScript SDK's streaming is expected
+            to parse SSE; adjust here if the server's framing diverges.
+
+        Policy/safety blocks that happen *before* streaming starts are returned
+        as a normal non-2xx JSON response and raised as the usual typed errors.
+
+        Yields:
+            ``str`` chunks of assistant text, in order.
+
+        Raises:
+            SafetyBlockedError / PolicyBlockedError / ModelgovError: on a non-2xx
+                response received before the stream body begins.
+        """
+        body = self._chat_body(
+            user_id=user_id,
+            user_type=user_type,
+            feature=feature,
+            messages=messages,
+            context=context,
+            model_class=model_class,
+            requested_model_class=requested_model_class,
+            input_tokens_estimate=input_tokens_estimate,
+            temperature=temperature,
+            project_id=project_id,
+            environment=environment,
+            metadata=metadata,
+        )
+        body["stream"] = True
+
+        extra: Dict[str, str] = {"accept": "text/event-stream"}
+        if idempotency_key:
+            extra["idempotency-key"] = idempotency_key
+
+        with self._client.stream(
+            "POST",
+            f"{self.base_url}/v1/chat",
+            headers=self._headers(extra),
+            json=body,
+        ) as response:
+            if response.status_code < 200 or response.status_code >= 300:
+                # Materialize the error body, then map to a typed exception.
+                response.read()
+                self._raise_for_status(response)
+
+            for line in response.iter_lines():
+                chunk = _parse_sse_line(line)
+                if chunk is _DONE:
+                    break
+                if chunk:
+                    yield chunk
+
+    def explain(
+        self,
+        *,
+        user_id: str,
+        user_type: str,
+        feature: str,
+        model_class: Optional[str] = None,
+        requested_model_class: Optional[str] = None,
+        input_tokens_estimate: Optional[int] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+    ) -> ExplainResult:
+        """Dry-run policy evaluation (``POST /v1/explain``).
+
+        Returns the decision, resolved model, safety plan, and a live budget
+        snapshot *without* calling the model or reserving budget. Same identity
+        fields as :meth:`chat`, but no ``messages``.
+        """
+        body: Dict[str, Any] = {
+            "userId": user_id,
+            "userType": user_type,
+            "feature": feature,
+        }
+        resolved_model_class = model_class or requested_model_class
+        if resolved_model_class is not None:
+            body["modelClass"] = resolved_model_class
+        if input_tokens_estimate is not None:
+            body["inputTokensEstimate"] = input_tokens_estimate
+        if project_id is not None:
+            body["projectId"] = project_id
+        if environment is not None:
+            body["environment"] = environment
+
+        response = self._client.post(
+            f"{self.base_url}/v1/explain",
+            headers=self._headers(),
+            json=body,
+        )
+        return self._handle_json(response)  # type: ignore[return-value]
+
+    def embed(
+        self,
+        *,
+        user_id: str,
+        user_type: str,
+        feature: str,
+        input: Union[str, Sequence[str]],
+        model_class: Optional[str] = None,
+        requested_model_class: Optional[str] = None,
+        input_tokens_estimate: Optional[int] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> EmbeddingsResult:
+        """Embed one or more texts through the gateway (``POST /v1/embeddings``).
+
+        Policy-checked (``feature`` + ``user_type``), budget-reserved, and
+        audited exactly like :meth:`chat`, and raises the same typed errors on a
+        ``403`` policy/budget block.
+
+        Args:
+            input: A single text, or a batch of texts to embed. A list is sent
+                as a JSON array (one vector is returned per input, in order).
+
+        Returns:
+            The decoded :class:`~modelgov.types.EmbeddingsResponse` body, whose
+            ``embeddings`` is one vector per input in request order.
+        """
+        body: Dict[str, Any] = {
+            "userId": user_id,
+            "userType": user_type,
+            "feature": feature,
+            "input": input if isinstance(input, str) else list(input),
+        }
+        resolved_model_class = model_class or requested_model_class
+        if resolved_model_class is not None:
+            body["modelClass"] = resolved_model_class
+        if input_tokens_estimate is not None:
+            body["inputTokensEstimate"] = input_tokens_estimate
+        if project_id is not None:
+            body["projectId"] = project_id
+        if environment is not None:
+            body["environment"] = environment
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+
+        response = self._client.post(
+            f"{self.base_url}/v1/embeddings",
+            headers=self._headers(),
+            json=body,
+        )
+        return self._handle_json(response)  # type: ignore[return-value]
+
+    def get_usage(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        feature: Optional[str] = None,
+        project_id: Optional[str] = None,
+    ) -> UsageResult:
+        """Fetch budget counters and recent stats (``GET /v1/usage``).
+
+        Requires an API key with the ``usage:read`` permission.
+        """
+        params: Dict[str, str] = {}
+        if user_id is not None:
+            params["userId"] = user_id
+        if feature is not None:
+            params["feature"] = feature
+        if project_id is not None:
+            params["projectId"] = project_id
+
+        response = self._client.get(
+            f"{self.base_url}/v1/usage",
+            headers=self._headers(),
+            params=params,
+        )
+        return self._handle_json(response)  # type: ignore[return-value]
+
+    def get_usage_summary(
+        self,
+        *,
+        feature: Optional[str] = None,
+        user_type: Optional[str] = None,
+        since: Optional[str] = None,
+        project_id: Optional[str] = None,
+    ) -> UsageResult:
+        """Fetch aggregated cost/request summary (``GET /v1/usage/summary``).
+
+        Args:
+            since: ``"24h"``, ``"7d"``, or an ISO-8601 timestamp (default
+                ``"24h"`` server-side).
+        """
+        params: Dict[str, str] = {}
+        if feature is not None:
+            params["feature"] = feature
+        if user_type is not None:
+            params["userType"] = user_type
+        if since is not None:
+            params["since"] = since
+        if project_id is not None:
+            params["projectId"] = project_id
+
+        response = self._client.get(
+            f"{self.base_url}/v1/usage/summary",
+            headers=self._headers(),
+            params=params,
+        )
+        return self._handle_json(response)  # type: ignore[return-value]
+
+    # -- internals ----------------------------------------------------------
+
+    @staticmethod
+    def _chat_body(
+        *,
+        user_id: str,
+        user_type: str,
+        feature: str,
+        messages: Sequence[ChatMessage],
+        context: Optional[Sequence[str]],
+        model_class: Optional[str],
+        requested_model_class: Optional[str],
+        input_tokens_estimate: Optional[int],
+        temperature: Optional[float],
+        project_id: Optional[str],
+        environment: Optional[str],
+        metadata: Optional[Mapping[str, Any]],
+    ) -> Dict[str, Any]:
+        """Build the camelCase JSON body the API expects, omitting None fields."""
+        body: Dict[str, Any] = {
+            "userId": user_id,
+            "userType": user_type,
+            "feature": feature,
+            "messages": [dict(m) for m in messages],
+        }
+        if context is not None:
+            body["context"] = list(context)
+        resolved_model_class = model_class or requested_model_class
+        if resolved_model_class is not None:
+            body["modelClass"] = resolved_model_class
+        if input_tokens_estimate is not None:
+            body["inputTokensEstimate"] = input_tokens_estimate
+        if temperature is not None:
+            body["temperature"] = temperature
+        if project_id is not None:
+            body["projectId"] = project_id
+        if environment is not None:
+            body["environment"] = environment
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        return body
+
+    def _handle_json(self, response: httpx.Response) -> Any:
+        """Return the parsed JSON body, or raise a typed error on non-2xx."""
+        if response.status_code < 200 or response.status_code >= 300:
+            self._raise_for_status(response)
+        try:
+            return response.json()
+        except (json.JSONDecodeError, ValueError):
+            return {}
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        """Map a non-2xx response to the appropriate ModelgovError subclass."""
+        try:
+            body = response.json()
+        except (json.JSONDecodeError, ValueError):
+            body = {}
+
+        code = _error_code(body)
+        if code == "safety_blocked":
+            raise SafetyBlockedError(response.status_code, code, body)
+        if code in ("policy_blocked", "budget_exceeded"):
+            raise PolicyBlockedError(response.status_code, code, body)
+        raise ModelgovError(response.status_code, code, body)
+
+
+def _error_code(body: Any) -> str:
+    """Extract ``error.code`` from the envelope, tolerating loose shapes."""
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, str):
+            return error
+        if isinstance(error, dict):
+            code = error.get("code")
+            if isinstance(code, str):
+                return code
+    return "error"
+
+
+# Sentinel returned by _parse_sse_line for the terminal `data: [DONE]` event.
+_DONE = object()
+
+
+def _parse_sse_line(line: str) -> Any:
+    """Parse one SSE line into a text chunk, ``""``, or the ``_DONE`` sentinel.
+
+    Returns ``_DONE`` for the ``[DONE]`` sentinel, ``""`` for lines with no
+    text delta (comments, blank lines, non-``data:`` fields, empty deltas), and
+    the extracted text chunk otherwise. See :meth:`ModelgovClient.chat_stream`
+    for the framing assumptions.
+    """
+    if not line:
+        return ""
+    stripped = line.strip()
+    if not stripped or stripped.startswith(":"):
+        # Blank line (event separator) or SSE comment.
+        return ""
+    if not stripped.startswith("data:"):
+        # Ignore other SSE fields (event:, id:, retry:).
+        return ""
+
+    data = stripped[len("data:"):].strip()
+    if data == "[DONE]":
+        return _DONE
+    if not data:
+        return ""
+
+    try:
+        payload = json.loads(data)
+    except (json.JSONDecodeError, ValueError):
+        # Tolerate a plain-text delta stream.
+        return data
+
+    return _extract_delta(payload)
+
+
+def _extract_delta(payload: Any) -> str:
+    """Pull the incremental text out of a decoded SSE JSON payload."""
+    if not isinstance(payload, dict):
+        return ""
+
+    # OpenAI-style: choices[0].delta.content
+    choices = payload.get("choices")
+    if isinstance(choices, list) and choices:
+        first = choices[0]
+        if isinstance(first, dict):
+            delta = first.get("delta")
+            if isinstance(delta, dict):
+                content = delta.get("content")
+                if isinstance(content, str):
+                    return content
+            # Non-streaming-style fallback within a choice.
+            message = first.get("message")
+            if isinstance(message, dict) and isinstance(message.get("content"), str):
+                return message["content"]
+            if isinstance(first.get("text"), str):
+                return first["text"]
+
+    # Simpler shapes the Modelgov API may emit.
+    for key in ("delta", "content", "text"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+
+    return ""

modelgov/errors.py

@@ -0,0 +1,96 @@
+"""Typed exceptions raised by :class:`modelgov.client.ModelgovClient`.
+
+Mirrors the TypeScript SDK's error hierarchy (``ModelgovError`` /
+``PolicyBlockedError`` / ``SafetyBlockedError``) while surfacing the API's
+structured error envelope (``code``, ``message``, ``details``, ``requestId``,
+and block metadata from ``details``) as first-class attributes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ModelgovError(Exception):
+    """Base error carrying the HTTP status and the API's structured error body.
+
+    The Modelgov error envelope looks like::
+
+        {
+          "error": {
+            "code": "policy_blocked",
+            "message": "...",
+            "details": {
+              "auditRequestId": "req_42"      # audit-log row (block/safety only)
+            },
+            "requestId": "550e8400-..."       # HTTP trace id (UUID)
+          }
+        }
+
+    Attributes:
+        status: HTTP status code (0 if the request never got a response).
+        code: The stable ``error.code`` string (e.g. ``"policy_blocked"``).
+        message: Human-readable ``error.message``.
+        details: The ``error.details`` object, if present.
+        request_id: ``error.requestId`` — the HTTP trace id (UUID).
+        audit_request_id: ``error.details.auditRequestId`` — the ``req_<n>``
+            audit id, present on policy/safety/budget blocks. Use with
+            ``modelgov requests show``.
+        reason_code: ``error.details.reasonCode`` — stable machine-readable
+            block reason (e.g. ``"daily_budget_exceeded"``), when present.
+        budget_remaining: ``error.details.budgetRemaining`` — remaining budget
+            headroom at decision time, when the API reports it.
+        body: The full parsed response body.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        body: Any = None,
+        *,
+        message: Optional[str] = None,
+    ) -> None:
+        self.status = status
+        self.code = code
+        self.body = body
+
+        error = body.get("error") if isinstance(body, dict) else None
+        error_obj: Dict[str, Any] = error if isinstance(error, dict) else {}
+
+        self.message: str = message or error_obj.get("message") or code
+        self.details: Optional[Dict[str, Any]] = (
+            error_obj.get("details") if isinstance(error_obj.get("details"), dict) else None
+        )
+        self.request_id: Optional[str] = error_obj.get("requestId")
+        details = self.details if isinstance(self.details, dict) else {}
+        self.audit_request_id: Optional[str] = (
+            details.get("auditRequestId")
+            if isinstance(details.get("auditRequestId"), str)
+            else error_obj.get("auditRequestId")
+        )
+        # Block metadata surfaced from `error.details` as first-class attributes,
+        # mirroring the TypeScript SDK's `reasonCode` / `budgetRemaining`.
+        reason_code = details.get("reasonCode")
+        self.reason_code: Optional[str] = reason_code if isinstance(reason_code, str) else None
+        budget_remaining = details.get("budgetRemaining")
+        self.budget_remaining: Optional[Dict[str, Any]] = (
+            budget_remaining if isinstance(budget_remaining, dict) else None
+        )
+
+        super().__init__(f"modelgov request failed ({status}): {code} - {self.message}")
+
+
+class PolicyBlockedError(ModelgovError):
+    """Raised on 403 ``policy_blocked`` or ``budget_exceeded``.
+
+    Inspect :attr:`~ModelgovError.body` / :attr:`~ModelgovError.details` for the
+    block reason, and :attr:`~ModelgovError.audit_request_id` for the audit id.
+    """
+
+
+class SafetyBlockedError(ModelgovError):
+    """Raised on 403 ``safety_blocked`` (PII or prompt injection)."""
+
+
+__all__ = ["ModelgovError", "PolicyBlockedError", "SafetyBlockedError"]

modelgov/types.py

@@ -0,0 +1,236 @@
+"""Typed request/response models for the Modelgov API.
+
+These mirror ``packages/sdk-typescript/src/types.ts`` and the shapes in
+``packages/api/openapi.json``. Response models are :class:`typing.TypedDict`
+so a decoded JSON body *is* the typed object with no conversion step — the
+API already returns camelCase keys and the SDK returns them unchanged.
+
+``ChatResult`` / ``ExplainResult`` / ``UsageResult`` are exported aliases used
+by the client's return-type annotations.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, List, Optional, Union
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict
+else:  # pragma: no cover - exercised on 3.9/3.10 runtimes
+    from typing_extensions import NotRequired, TypedDict  # type: ignore
+
+
+# --- Chat -------------------------------------------------------------------
+
+
+class TextPart(TypedDict):
+    """A text segment of a multimodal message (``type`` is ``"text"``)."""
+
+    type: str
+    text: str
+
+
+class ImageUrl(TypedDict):
+    url: str
+    detail: NotRequired[str]  # "low" | "high" | "auto"
+
+
+class ImagePart(TypedDict):
+    """An image segment of a multimodal message (``type`` is ``"image_url"``).
+
+    ``image_url.url`` is an http(s) URL or a ``data:`` URI (base64) — e.g. a
+    page scan for OCR. Passed through to a vision model; the gateway still
+    governs budget, audit, and text-part safety.
+    """
+
+    type: str
+    image_url: ImageUrl
+
+
+ContentPart = Union[TextPart, ImagePart]
+
+
+class ChatMessage(TypedDict):
+    """A single chat message. ``role`` is one of system/user/assistant/tool.
+
+    ``content`` is a plain string, or a list of OpenAI-style content parts
+    (text + images) for vision / multimodal features.
+    """
+
+    role: str
+    content: Union[str, List[ContentPart]]
+
+
+class Usage(TypedDict):
+    inputTokens: Optional[int]
+    outputTokens: Optional[int]
+
+
+class Cost(TypedDict):
+    estimatedUsd: float
+    actualUsd: float
+
+
+class BudgetRemaining(TypedDict):
+    userDailyUsd: float
+    # null when no cap is configured (monthly_usd: 0).
+    featureMonthlyUsd: Optional[float]
+    globalMonthlyUsd: Optional[float]
+    # Token headroom; present when a token cap is configured, null otherwise.
+    userDailyTokens: NotRequired[Optional[int]]
+    featureMonthlyTokens: NotRequired[Optional[int]]
+    globalMonthlyTokens: NotRequired[Optional[int]]
+
+
+class Safety(TypedDict):
+    piiMasked: bool
+    injectionBlocked: bool
+    # Present only for grounded features: whether the answer's citations were
+    # verified against the provided context.
+    grounded: NotRequired[bool]
+
+
+class ResponseMessage(TypedDict):
+    role: str
+    content: str
+
+
+class ChatResponse(TypedDict):
+    """``200`` body of ``POST /v1/chat``."""
+
+    message: ResponseMessage
+    model: str
+    # Provider of the model that ran, e.g. "openai", "openrouter", "ollama".
+    provider: str
+    decision: str  # "allow" | "degrade" | "fallback"
+    reason: NotRequired[str]
+    usage: Usage
+    cost: Cost
+    # null under hierarchical budgets (the node tree is the authority).
+    budgetRemaining: Optional[BudgetRemaining]
+    safety: Safety
+    requestId: str  # audit id ("req_<n>")
+
+
+# --- Explain ----------------------------------------------------------------
+
+
+class ExplainRequested(TypedDict):
+    userId: str
+    userType: str
+    feature: str
+    modelClass: str
+
+
+class ExplainResolved(TypedDict):
+    modelClass: str
+    model: str
+    provider: str
+    fallbackModel: NotRequired[str]
+
+
+class ExplainSafety(TypedDict):
+    preset: str
+    pii: str
+    promptInjection: str
+    maxOutputTokens: int
+
+
+class ExplainCost(TypedDict):
+    estimatedUsd: float
+
+
+class ExplainBudgetUsed(TypedDict):
+    userDailyUsd: float
+    userDailyRequests: int
+    featureMonthlyUsd: float
+    globalMonthlyUsd: float
+
+
+class ExplainBudget(TypedDict):
+    remaining: BudgetRemaining
+    used: ExplainBudgetUsed
+    permittedModels: List[str]
+    dailyRequestLimit: int
+    dailyRequestsRemaining: int
+
+
+class ExplainResponse(TypedDict):
+    """``200`` body of ``POST /v1/explain``."""
+
+    decision: str  # "allow" | "block" | "degrade" | "fallback"
+    reason: NotRequired[str]
+    reasonCode: NotRequired[str]
+    requested: ExplainRequested
+    resolved: ExplainResolved
+    safety: ExplainSafety
+    cost: ExplainCost
+    budget: ExplainBudget
+    wouldCallModel: bool
+    summary: str
+
+
+# --- Embeddings -------------------------------------------------------------
+
+
+class EmbeddingsUsage(TypedDict):
+    inputTokens: Optional[int]
+
+
+class EmbeddingsResponse(TypedDict):
+    """``200`` body of ``POST /v1/embeddings``."""
+
+    embeddings: List[List[float]]  # one vector per input, in request order
+    model: str
+    provider: str
+    decision: str  # "allow" | "degrade" | "fallback"
+    reason: NotRequired[str]
+    usage: EmbeddingsUsage
+    cost: Cost
+    # null under hierarchical budgets (the node tree is the authority).
+    budgetRemaining: Optional[BudgetRemaining]
+    requestId: str
+
+
+# --- Usage ------------------------------------------------------------------
+
+# The /v1/usage and /v1/usage/summary bodies are operator-facing and not fully
+# fixed in the OpenAPI spec, so they are typed as a loose mapping.
+UsageResponse = Dict[str, Any]
+
+
+# --- Public aliases (match the naming used in the task/client signatures) ---
+
+ChatResult = ChatResponse
+ExplainResult = ExplainResponse
+EmbeddingsResult = EmbeddingsResponse
+UsageResult = UsageResponse
+
+
+__all__ = [
+    "ChatMessage",
+    "TextPart",
+    "ImageUrl",
+    "ImagePart",
+    "ContentPart",
+    "Usage",
+    "Cost",
+    "BudgetRemaining",
+    "Safety",
+    "ResponseMessage",
+    "ChatResponse",
+    "ChatResult",
+    "EmbeddingsUsage",
+    "EmbeddingsResponse",
+    "EmbeddingsResult",
+    "ExplainRequested",
+    "ExplainResolved",
+    "ExplainSafety",
+    "ExplainCost",
+    "ExplainBudgetUsed",
+    "ExplainBudget",
+    "ExplainResponse",
+    "ExplainResult",
+    "UsageResponse",
+    "UsageResult",
+]

modelgov-1.0.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: modelgov
+Version: 1.0.0
+Summary: Modelgov API client. `feature` and `userType` are mandatory on every request.
+Project-URL: Homepage, https://github.com/mml555/modelgov
+Author: Modelgov
+License: MIT
+Keywords: budget,gateway,llm,modelgov,policy,safety
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Modelgov Python SDK
+
+Package: `modelgov` (module `modelgov`). The Python counterpart to
+[`@modelgov/sdk`](../sdk-typescript).
+
+The SDK is a **thin HTTP client** to the Modelgov API. Policy enforcement is
+always server-side. Every request declares a **user**, **user type**, and
+**feature**; policy is checked **before** the model call.
+
+## Install
+
+```bash
+pip install modelgov
+```
+
+> Note: `modelgov` is not yet published to PyPI. Until then, install from
+> source with the editable install below (see also [self-host.md](../../docs/self-host.md)).
+
+From the monorepo (editable, with test deps):
+
+```bash
+pip install -e "packages/sdk-python[dev]"
+```
+
+Requires Python >= 3.9. Depends on [`httpx`](https://www.python-httpx.org/).
+
+## Create a client
+
+```python
+import os
+from modelgov import ModelgovClient
+
+ai = ModelgovClient(
+    base_url=os.environ.get("MODELGOV_URL", "http://localhost:3000"),
+    api_key=os.environ["MODELGOV_API_KEY"],
+)
+```
+
+`ModelgovClient` is a context manager and closes its connection pool on exit:
+
+```python
+with ModelgovClient(base_url=..., api_key=...) as ai:
+    ...
+```
+
+## Chat
+
+```python
+res = ai.chat(
+    user_id="user_123",        # your end-user id
+    user_type="logged_in",     # must match modelgov.yaml budgets
+    feature="support_chat",    # required — registered feature
+    model_class="cheap",
+    messages=[{"role": "user", "content": "Help me reset my password"}],
+    # optional:
+    # input_tokens_estimate=120,
+    # temperature=0.7,
+    # project_id="checkout",
+    # environment="production",
+    # metadata={"trace_id": "abc"},
+)
+
+print(res["message"]["content"])
+print(res["model"], res["decision"], res["requestId"])
+```
+
+Snake_case keyword args are converted to the camelCase JSON the API expects
+(`user_id` → `userId`, `model_class` → `modelClass`, etc.). `None`-valued
+optional args are omitted from the request body.
+
+### Response
+
+`chat()` returns a `ChatResponse` (a `TypedDict`), so it is a plain `dict` with
+typed keys:
+
+```python
+{
+  "message": {"role": "assistant", "content": "..."},
+  "model": "openai/gpt-4o-mini",
+  "decision": "allow",             # "allow" | "degrade" | "fallback"
+  "usage": {"inputTokens": 12, "outputTokens": 8},
+  "cost": {"estimatedUsd": 0.0001, "actualUsd": 0.00008},
+  "budgetRemaining": {"userDailyUsd": 0.24, "featureMonthlyUsd": None, "globalMonthlyUsd": 499.5},
+  "safety": {"piiMasked": False, "injectionBlocked": False},
+  "requestId": "req_42",           # audit id — log with your domain ids
+}
+```
+
+### Vision (multimodal)
+
+Pass content parts instead of a string to send images to a vision model. The
+gateway governs budget/audit and still runs safety on the text parts:
+
+```python
+res = ai.chat(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="document_extraction",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Extract the total from this receipt."},
+            {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
+        ],
+    }],
+)
+```
+
+### Grounding
+
+For a feature with safety `grounding: strict`, pass retrieved passages as
+`context`. The gateway answers only from them, forces verbatim citations, and
+verifies them — unverifiable answers become a safe refusal, and
+`res["safety"]["grounded"]` reports whether the citations checked out:
+
+```python
+res = ai.chat(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="grounded_support",
+    messages=[{"role": "user", "content": "How long do refunds take?"}],
+    context=["Refunds are issued within 5 business days of approval."],
+)
+```
+
+## Streaming
+
+`chat_stream()` yields incremental text chunks over Server-Sent Events. It
+sends `"stream": true` and iterates `data:` lines until the `[DONE]` sentinel.
+
+```python
+for chunk in ai.chat_stream(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="support_chat",
+    messages=[{"role": "user", "content": "Write a haiku about budgets"}],
+):
+    print(chunk, end="", flush=True)
+```
+
+**SSE framing assumption:** OpenAI-style events — one JSON payload per `data:`
+line, terminated by `data: [DONE]`. Text is read from
+`choices[0].delta.content` (or a simpler `delta` / `content` / `text` field).
+Non-JSON `data:` payloads are yielded verbatim. See the `chat_stream` docstring
+if the server's framing differs.
+
+The generator holds the connection open until fully consumed. Policy/safety
+blocks that occur before the stream begins raise the usual typed errors.
+
+## Embeddings
+
+`embed()` runs governed embeddings (`POST /v1/embeddings`) — policy-checked,
+budget-reserved, and audited like `chat()`. Pass one string or a batch:
+
+```python
+res = ai.embed(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="rag_ingest",
+    input=["first passage", "second passage"],   # or a single string
+)
+vectors = res["embeddings"]   # one vector per input, in request order
+```
+
+## Idempotency
+
+Pass a stable key to retry safely without double-charging budget or re-calling
+the model:
+
+```python
+ai.chat(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="support_chat",
+    messages=[{"role": "user", "content": "..."}],
+    idempotency_key=f"chat-{user_id}-{session_id}",
+)
+```
+
+The API returns `x-idempotent-replay: true` on cache hits; a same-key request
+with a different body returns `422 idempotency_key_reuse`.
+
+## Explain (dry run)
+
+Evaluate policy without calling the model or reserving budget:
+
+```python
+plan = ai.explain(
+    user_id="user_123",
+    user_type="logged_in",
+    feature="support_chat",
+    model_class="premium",
+)
+print(plan["decision"], plan["summary"])
+```
+
+## Usage
+
+Requires an API key with `usage:read`.
+
+```python
+usage = ai.get_usage(user_id="user_123")
+summary = ai.get_usage_summary(feature="support_chat", since="7d")
+```
+
+## Errors
+
+| Class | When |
+| --- | --- |
+| `PolicyBlockedError` | 403 `policy_blocked` or `budget_exceeded` |
+| `SafetyBlockedError` | 403 `safety_blocked` (PII or prompt injection) |
+| `ModelgovError` | Other 4xx / 5xx |
+
+`PolicyBlockedError` and `SafetyBlockedError` subclass `ModelgovError`. Each
+error carries the API's structured envelope:
+
+```python
+from modelgov import ModelgovError, PolicyBlockedError, SafetyBlockedError
+
+try:
+    ai.chat(
+        user_id="user_123",
+        user_type="logged_in",
+        feature="support_chat",
+        messages=[{"role": "user", "content": "..."}],
+    )
+except PolicyBlockedError as err:
+    print(err.status)            # 403
+    print(err.code)              # "policy_blocked" | "budget_exceeded"
+    print(err.message)           # human-readable
+    print(err.details)           # error.details object
+    print(err.audit_request_id)  # "req_<n>" — modelgov requests show
+    print(err.request_id)        # HTTP trace id (UUID)
+    print(err.body)              # full parsed envelope
+except ModelgovError as err:
+    ...
+```
+
+## Integration pattern
+
+```text
+1. Authenticate user (your app)
+2. Authorize product action (your app)
+3. ai.chat(user_id=..., user_type=..., feature=..., messages=...)
+4. Return res["message"]["content"] to the user
+```
+
+Never call Modelgov before your app has decided the user may use this feature.
+
+## Development
+
+```bash
+pip install -e "packages/sdk-python[dev]"
+cd packages/sdk-python
+pytest
+```

modelgov-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+modelgov/__init__.py,sha256=TG3dZTOrt7LyUpvmT0GC-p8QGL9sDqgCcqpqA3PgNew,1824
+modelgov/client.py,sha256=-GLUV2aZW9iJIpbHnMDqU97Pn2gc1kB3J1UmA9bj8KU,21036
+modelgov/errors.py,sha256=GkfgnYbcCbD9Yw5zQrmpmlIGLKYYiimO_3hSePng-P8,3827
+modelgov/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelgov/types.py,sha256=O2LPIj4yTjOvIYJZ5GEcUOBJgNgtMbScE9MQlqGLSr8,5994
+modelgov-1.0.0.dist-info/METADATA,sha256=fD6eei3pu4SQmF9STK2LkpXMRZiFd1WKMfYuVtQLhm0,7824
+modelgov-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modelgov-1.0.0.dist-info/RECORD,,

modelgov-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any