vin-guard-sdk 0.3.0__py3-none-any.whl

ai_gateway/__init__.py

@@ -0,0 +1,23 @@
+"""AI Gateway Python SDK — Level 1 thin wrapper (API_DESIGN §3)."""
+
+from .client import ChatCompletion, GatewayClient, ModelEntry
+from .async_client import AsyncGatewayClient
+from .control_plane import ControlPlaneClient, Page
+from .errors import (GatewayConnectionError, GatewayError, GatewayTimeoutError,
+                     GatewayTransportError)
+from .types import GatewayInfo, Usage
+
+__all__ = [
+    "AsyncGatewayClient",
+    "ControlPlaneClient",
+    "Page",
+    "ChatCompletion",
+    "GatewayClient",
+    "GatewayConnectionError",
+    "GatewayError",
+    "GatewayInfo",
+    "GatewayTimeoutError",
+    "GatewayTransportError",
+    "ModelEntry",
+    "Usage",
+]

ai_gateway/_shared.py

@@ -0,0 +1,116 @@
+"""Wire encoding shared by the sync and async clients."""
+
+import json
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any
+
+import httpx
+
+from .errors import GatewayError, snippet, transport_error_from
+
+GATEWAY_HEADERS = (
+    "x-gateway-request-id", "x-gateway-provider", "x-gateway-model",
+    "x-gateway-route-tier", "x-gateway-route-reason", "x-gateway-cost-usd",
+    "x-gateway-latency-ms", "x-ratelimit-remaining-requests",
+    "x-ratelimit-remaining-tokens", "retry-after",
+)
+
+
+def gateway_headers(response: httpx.Response) -> dict[str, str]:
+    return {key: response.headers[key] for key in GATEWAY_HEADERS if key in response.headers}
+
+
+def _error_payload(response: httpx.Response) -> Any:
+    """Parse an error body without ever masking the HTTP status.
+
+    Non-JSON, empty or HTML bodies become a bounded plain-text message; the
+    original HTTP status is always carried by :meth:`GatewayError.from_response`.
+    """
+    try:
+        return response.json()
+    except ValueError:
+        text = response.text
+        if text and text.strip():
+            return {"error": {"message": snippet(text)}}
+        return None
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    payload = _error_payload(response)
+    raise GatewayError.from_response(response.status_code, payload, response.headers)
+
+
+@contextmanager
+def translate_transport_errors():
+    """Map HTTPX transport failures to SDK errors, preserving cancellation.
+
+    Only ``httpx.TransportError`` is caught, so ``KeyboardInterrupt``,
+    ``asyncio.CancelledError`` and input ``ValueError``/``TypeError`` pass
+    through untouched.
+    """
+    try:
+        yield
+    except httpx.TransportError as exc:
+        raise transport_error_from(exc) from exc
+
+
+@asynccontextmanager
+async def translate_transport_errors_async():
+    try:
+        yield
+    except httpx.TransportError as exc:
+        raise transport_error_from(exc) from exc
+
+
+def gateway_extras(*, tags=None, metadata=None, route_policy=None,
+                   no_store=False, idempotency_key=None) -> dict[str, str]:
+    extra = {}
+    encoded = tags if isinstance(tags, str) else ",".join(f"{k}={v}" for k, v in (tags or {}).items())
+    if encoded:
+        extra["X-Gateway-Tags"] = encoded
+    if metadata is not None:
+        value = json.dumps(metadata, separators=(",", ":"), allow_nan=False)
+        if len(value.encode("utf-8")) > 4096:
+            raise ValueError("metadata must fit in the 4KB gateway header")
+        extra["X-Gateway-Metadata"] = value
+    if route_policy:
+        extra["X-Gateway-Route-Policy"] = route_policy
+    if no_store:
+        extra["X-Gateway-No-Store"] = "true"
+    if idempotency_key:
+        extra["Idempotency-Key"] = idempotency_key
+    return extra
+
+
+def chat_request(*, model: str, messages: list[dict[str, Any]], stream=False,
+                 temperature=None, max_tokens=None, top_p=None, stop=None,
+                 tools=None, tool_choice=None, response_format=None, user=None,
+                 seed=None, tags=None, metadata=None, route_policy=None,
+                 no_store=False, idempotency_key=None):
+    """Accept the documented chat subset; reject misspelled options."""
+    body = {"model": model, "messages": messages, "stream": stream}
+    options = dict(temperature=temperature, max_tokens=max_tokens, top_p=top_p,
+                   stop=stop, tools=tools, tool_choice=tool_choice,
+                   response_format=response_format, user=user, seed=seed)
+    body.update({key: value for key, value in options.items() if value is not None})
+    return body, gateway_extras(tags=tags, metadata=metadata, route_policy=route_policy,
+                               no_store=no_store, idempotency_key=idempotency_key)
+
+
+def health_url(base_url: str, endpoint: str) -> str:
+    url = httpx.URL(base_url)
+    if url.scheme not in ("http", "https") or not url.host:
+        raise ValueError("base_url must be an absolute HTTP(S) URL")
+    path = url.path.rstrip("/")
+    if path.endswith("/v1"):
+        path = path[:-3]
+    return str(url.copy_with(path=f"{path}/{endpoint}", query=None, fragment=None))
+
+
+def ensure_sse(response: httpx.Response) -> None:
+    if response.headers.get("content-type", "").split(";", 1)[0].strip().lower() != "text/event-stream":
+        raise GatewayError("Gateway returned a non-SSE response; this backend does not stream yet",
+                           code="streaming_not_supported", status=response.status_code,
+                           request_id=response.headers.get("x-gateway-request-id"))

ai_gateway/_sse.py

@@ -0,0 +1,59 @@
+"""OpenAI SSE decoding with multiline events and visible protocol errors."""
+
+import json
+from collections.abc import Iterable, Iterator
+from typing import Any
+
+from .errors import GatewayError
+
+
+class SSEDecoder:
+    def __init__(self) -> None:
+        self._data: list[str] = []
+        self.done = False
+
+    def feed(self, line: str) -> dict[str, Any] | None:
+        if self.done:
+            return None
+        if line.strip():
+            if line.startswith("data:"):
+                self._data.append(line[5:].removeprefix(" "))
+            return None
+        if not self._data:
+            return None
+        data = "\n".join(self._data)
+        self._data.clear()
+        if data.strip() == "[DONE]":
+            self.done = True
+            return None
+        try:
+            event = json.loads(data)
+        except ValueError as exc:
+            raise GatewayError("Invalid JSON in gateway SSE event", code="invalid_stream") from exc
+        if not isinstance(event, dict):
+            raise GatewayError("Expected an object in gateway SSE event", code="invalid_stream")
+        if "error" in event:
+            raise GatewayError.from_response(200, event, {})
+        return event
+
+
+def parse_sse_lines(lines: Iterable[str]) -> Iterator[dict[str, Any]]:
+    decoder = SSEDecoder()
+    for line in lines:
+        event = decoder.feed(line)
+        if decoder.done:
+            return
+        if event is not None:
+            yield event
+    event = decoder.feed("")
+    if event is not None:
+        yield event
+
+
+def iter_text_chunks(events: Iterable[dict[str, Any]]) -> Iterator[str]:
+    for event in events:
+        choices = event.get("choices") or []
+        if choices and isinstance(choices[0], dict):
+            content = (choices[0].get("delta") or {}).get("content")
+            if content:
+                yield content

ai_gateway/async_client.py

@@ -0,0 +1,99 @@
+"""Native HTTPX async counterpart of GatewayClient."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from ._shared import (chat_request, ensure_sse, health_url, raise_for_status,
+                      translate_transport_errors_async)
+from ._sse import SSEDecoder
+from .client import ChatCompletion, ModelEntry, parse_chat_response, parse_models
+from .errors import GatewayError
+
+
+class AsyncGatewayClient:
+    def __init__(self, *, api_key: str,
+                 base_url: str = "https://gateway.example.com/v1",
+                 timeout: float | httpx.Timeout = 30.0,
+                 transport: httpx.AsyncBaseTransport | None = None) -> None:
+        if not api_key:
+            raise ValueError("api_key is required (gw_live_...)")
+        self._health_url = health_url(base_url, "healthz")
+        self._ready_url = health_url(base_url, "readyz")
+        self._http = httpx.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout,
+                                       transport=transport,
+                                       headers={"Authorization": f"Bearer {api_key}"})
+
+    async def chat_completions(self, *, model: str, messages: list[dict[str, Any]],
+                               **options: Any) -> ChatCompletion:
+        body, headers = chat_request(model=model, messages=messages, **options)
+        if body["stream"]:
+            raise ValueError("Use stream_chat_completions for stream=True")
+        async with translate_transport_errors_async():
+            response = await self._http.post("/chat/completions", json=body, headers=headers)
+        raise_for_status(response)
+        return parse_chat_response(response)
+
+    async def stream_chat_completions(self, *, model: str, messages: list[dict[str, Any]],
+                                      **options: Any) -> AsyncIterator[dict[str, Any]]:
+        body, headers = chat_request(model=model, messages=messages, stream=True, **options)
+        async with translate_transport_errors_async():
+            async with self._http.stream("POST", "/chat/completions", json=body, headers=headers) as response:
+                if not response.is_success:
+                    await response.aread()
+                    raise_for_status(response)
+                ensure_sse(response)
+                decoder = SSEDecoder()
+                async for line in response.aiter_lines():
+                    event = decoder.feed(line)
+                    if decoder.done:
+                        return
+                    if event is not None:
+                        yield event
+                event = decoder.feed("")
+                if event is not None:
+                    yield event
+
+    async def stream_text(self, **kwargs: Any) -> str:
+        parts = []
+        async for event in self.stream_chat_completions(**kwargs):
+            choices = event.get("choices") or []
+            if choices and isinstance(choices[0], dict):
+                parts.append((choices[0].get("delta") or {}).get("content") or "")
+        return "".join(parts)
+
+    async def list_models(self) -> list[ModelEntry]:
+        async with translate_transport_errors_async():
+            response = await self._http.get("/models")
+        raise_for_status(response)
+        return parse_models(response)
+
+    async def _probe(self, url: str) -> dict[str, Any]:
+        async with translate_transport_errors_async():
+            response = await self._http.send(httpx.Request("GET", url))
+        raise_for_status(response)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise GatewayError("Gateway returned an unexpected response body",
+                               code="invalid_response", status=response.status_code,
+                               request_id=response.headers.get("x-gateway-request-id"),
+                               payload=None, headers=response.headers) from exc
+
+    async def health(self) -> dict[str, Any]:
+        return await self._probe(self._health_url)
+
+    async def ready(self) -> dict[str, Any]:
+        return await self._probe(self._ready_url)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncGatewayClient:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()

ai_gateway/client.py

@@ -0,0 +1,169 @@
+"""Synchronous data-plane client; health probes use the service root."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from collections.abc import Iterator
+
+import httpx
+
+from ._shared import (chat_request, ensure_sse, gateway_headers, health_url,
+                      raise_for_status, translate_transport_errors)
+from ._sse import iter_text_chunks, parse_sse_lines
+from .errors import GatewayError
+from .types import GatewayInfo, Usage
+
+
+@dataclass(frozen=True)
+class ModelEntry:
+    id: str
+    owned_by: str = "gateway"
+    type: str = "policy"
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ChatCompletion:
+    id: str
+    model: str
+    content: str
+    choices: list[dict[str, Any]]
+    usage: Usage
+    gateway: GatewayInfo
+    headers: dict[str, str]
+    raw: dict[str, Any]
+
+
+def _decode_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise GatewayError("Gateway returned an unexpected response body",
+                           code="invalid_response", status=response.status_code,
+                           request_id=response.headers.get("x-gateway-request-id"),
+                           payload=None, headers=response.headers) from exc
+
+
+def parse_chat_response(response: httpx.Response) -> ChatCompletion:
+    payload = _decode_json(response)
+    if not isinstance(payload, dict):
+        raise GatewayError("Gateway returned an unexpected response body",
+                           code="invalid_response", status=response.status_code,
+                           request_id=response.headers.get("x-gateway-request-id"),
+                           payload=payload, headers=response.headers)
+    choices = payload.get("choices") or []
+    if not isinstance(choices, list):
+        choices = []
+    first = choices[0] if choices and isinstance(choices[0], dict) else {}
+    message = first.get("message") if isinstance(first.get("message"), dict) else {}
+    content = message.get("content")
+    usage = payload.get("usage") if isinstance(payload.get("usage"), dict) else {}
+    gateway = payload.get("_gateway") if isinstance(payload.get("_gateway"), dict) else {}
+    headers = gateway_headers(response)
+    try:
+        usage_typed = Usage(**{key: int(usage.get(key) or 0) for key in
+                           ("prompt_tokens", "completion_tokens", "total_tokens")})
+        cost_usd = float(gateway["costUsd"] if gateway.get("costUsd") is not None
+                         else headers.get("x-gateway-cost-usd") or 0)
+    except (ValueError, TypeError) as exc:
+        raise GatewayError("Gateway returned an unexpected response body",
+                           code="invalid_response", status=response.status_code,
+                           request_id=headers.get("x-gateway-request-id"),
+                           payload=payload, headers=response.headers) from exc
+    return ChatCompletion(
+        id=str(payload.get("id", "")), model=str(payload.get("model", "")),
+        content=content if isinstance(content, str) else "", choices=choices,
+        usage=usage_typed,
+        gateway=GatewayInfo(
+            request_id=gateway.get("requestId") or headers.get("x-gateway-request-id", ""),
+            tier=gateway.get("tier") or headers.get("x-gateway-route-tier", ""),
+            policy=gateway.get("policy"), confidence=gateway.get("confidence"),
+            cost_usd=cost_usd,
+        ), headers=headers, raw=payload,
+    )
+
+
+def parse_models(response: httpx.Response) -> list[ModelEntry]:
+    known = {"id", "owned_by", "type"}
+    payload = _decode_json(response)
+    data = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(data, list):
+        return []
+    return [ModelEntry(id=str(item.get("id", "")),
+                       owned_by=str(item.get("owned_by", "gateway")),
+                       type=str(item.get("type", "policy")),
+                       extra={k: v for k, v in item.items() if k not in known})
+            for item in data if isinstance(item, dict)]
+
+
+class GatewayClient:
+    """Auth, gateway headers, typed results and explicit resource ownership.
+
+    Chat keyword options follow API_DESIGN §3.1. Tools, structured output,
+    top_p, stop, user and seed are forwarded for future compatible backends;
+    the current Java DTO only consumes temperature and max_tokens.
+    """
+
+    def __init__(self, *, api_key: str,
+                 base_url: str = "https://gateway.example.com/v1",
+                 timeout: float | httpx.Timeout = 30.0,
+                 transport: httpx.BaseTransport | None = None) -> None:
+        if not api_key:
+            raise ValueError("api_key is required (gw_live_...)")
+        self._health_url = health_url(base_url, "healthz")
+        self._ready_url = health_url(base_url, "readyz")
+        self._http = httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout,
+                                  transport=transport,
+                                  headers={"Authorization": f"Bearer {api_key}"})
+
+    def chat_completions(self, *, model: str, messages: list[dict[str, Any]],
+                         **options: Any) -> ChatCompletion:
+        body, headers = chat_request(model=model, messages=messages, **options)
+        if body["stream"]:
+            raise ValueError("Use stream_chat_completions for stream=True")
+        with translate_transport_errors():
+            response = self._http.post("/chat/completions", json=body, headers=headers)
+        raise_for_status(response)
+        return parse_chat_response(response)
+
+    def stream_chat_completions(self, *, model: str, messages: list[dict[str, Any]],
+                                **options: Any) -> Iterator[dict[str, Any]]:
+        body, headers = chat_request(model=model, messages=messages, stream=True, **options)
+        with translate_transport_errors():
+            with self._http.stream("POST", "/chat/completions", json=body, headers=headers) as response:
+                if not response.is_success:
+                    response.read()
+                    raise_for_status(response)
+                ensure_sse(response)
+                yield from parse_sse_lines(response.iter_lines())
+
+    def stream_text(self, **kwargs: Any) -> str:
+        return "".join(iter_text_chunks(self.stream_chat_completions(**kwargs)))
+
+    def list_models(self) -> list[ModelEntry]:
+        with translate_transport_errors():
+            response = self._http.get("/models")
+        raise_for_status(response)
+        return parse_models(response)
+
+    def _probe(self, url: str) -> dict[str, Any]:
+        with translate_transport_errors():
+            response = self._http.send(httpx.Request("GET", url))
+        raise_for_status(response)
+        return _decode_json(response)
+
+    def health(self) -> dict[str, Any]:
+        return self._probe(self._health_url)
+
+    def ready(self) -> dict[str, Any]:
+        return self._probe(self._ready_url)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> GatewayClient:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

ai_gateway/control_plane.py

@@ -0,0 +1,161 @@
+"""Read-only dashboard API client with JWT auth and cursor pagination.
+
+These routes belong to the serverless control plane, not the Java data plane.
+Dict payloads deliberately preserve unknown fields and nullable wire values.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._shared import raise_for_status, translate_transport_errors
+from .errors import GatewayError
+
+
+@dataclass(frozen=True)
+class Page:
+    data: list[dict[str, Any]]
+    next_cursor: str | None
+    has_more: bool
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> Page:
+        if not isinstance(payload, dict):
+            raise ValueError("Expected {data, pagination} control-plane envelope")
+        pagination = payload.get("pagination")
+        data = payload.get("data")
+        if not isinstance(data, list) or not isinstance(pagination, dict):
+            raise ValueError("Expected {data, pagination} control-plane envelope")
+        more = pagination.get("hasMore")
+        cursor = pagination.get("nextCursor")
+        if not isinstance(more, bool) or (cursor is not None and not isinstance(cursor, str)):
+            raise ValueError("Invalid pagination fields")
+        if more and not cursor:
+            raise ValueError("hasMore=true requires a non-empty nextCursor")
+        return cls(data=data, next_cursor=cursor, has_more=more)
+
+
+def _id(value: str) -> str:
+    if not value or value in (".", ".."):
+        raise ValueError("A resource ID is required")
+    return quote(value, safe="")
+
+
+class ControlPlaneClient:
+    """Use an OIDC access token, or explicitly opt into a dev principal.
+
+    Token callables are resolved on every request so applications can refresh
+    tokens themselves. Gateway API keys are not dashboard credentials.
+    """
+
+    def __init__(self, *, base_url: str,
+                 access_token: str | Callable[[], str] | None = None,
+                 dev_subject: str | None = None,
+                 timeout: float | httpx.Timeout = 30.0,
+                 transport: httpx.BaseTransport | None = None) -> None:
+        if bool(access_token) == bool(dev_subject):
+            raise ValueError("Provide exactly one of access_token or dev_subject")
+        self._access_token = access_token
+        self._dev_subject = dev_subject
+        self._http = httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout,
+                                  transport=transport)
+
+    def _get(self, path: str, **params: Any) -> dict[str, Any]:
+        if self._dev_subject:
+            headers = {"x-dev-sub": self._dev_subject}
+        else:
+            token = self._access_token() if callable(self._access_token) else self._access_token
+            if not token:
+                raise ValueError("Access token provider returned an empty token")
+            headers = {"Authorization": f"Bearer {token}"}
+        if "limit" in params and params["limit"] is not None:
+            limit = params["limit"]
+            if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 100:
+                raise ValueError("limit must be an integer between 1 and 100")
+        with translate_transport_errors():
+            response = self._http.get(path, headers=headers,
+                                      params={k: v for k, v in params.items() if v is not None})
+        raise_for_status(response)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise GatewayError("Control plane returned an unexpected response body",
+                               code="invalid_response", status=response.status_code,
+                               request_id=response.headers.get("x-gateway-request-id"),
+                               payload=None, headers=response.headers) from exc
+
+    def _page(self, path: str, **params: Any) -> Page:
+        return Page.from_payload(self._get(path, **params))
+
+    def me(self) -> dict[str, Any]:
+        return self._get("/me")
+
+    def list_orgs(self, **params: Any) -> Page:
+        return self._page("/orgs", **params)
+
+    def list_projects(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/projects", **params)
+
+    def list_api_keys(self, project_id: str, **params: Any) -> Page:
+        return self._page(f"/projects/{_id(project_id)}/api-keys", **params)
+
+    def list_providers(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/providers", **params)
+
+    def list_models(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/models", **params)
+
+    def list_routing_policies(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/routing-policies", **params)
+
+    def list_policy_versions(self, policy_id: str, **params: Any) -> Page:
+        return self._page(f"/routing-policies/{_id(policy_id)}/versions", **params)
+
+    def get_usage(self, org_id: str, *, from_: str | None = None,
+                  to: str | None = None, group_by: str = "model") -> Page:
+        if group_by not in ("model", "provider", "project", "key", "tag"):
+            raise ValueError("Unsupported usage group_by")
+        # The current control plane only supports daily rollups (audit M4).
+        return self._page(f"/orgs/{_id(org_id)}/usage",
+                          **{"from": from_, "to": to, "groupBy": group_by})
+
+    def list_requests(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/requests", **params)
+
+    def get_request(self, request_id: str) -> dict[str, Any]:
+        return self._get(f"/requests/{_id(request_id)}")
+
+    def get_routing_insights(self, org_id: str, *, from_: str | None = None,
+                             to: str | None = None) -> dict[str, Any]:
+        return self._get(f"/orgs/{_id(org_id)}/routing/insights", **{"from": from_, "to": to})
+
+    def list_audit_logs(self, org_id: str, **params: Any) -> Page:
+        return self._page(f"/orgs/{_id(org_id)}/audit-logs", **params)
+
+    def iter_items(self, list_method: Callable[..., Page], *args: Any,
+                   **params: Any) -> Iterator[dict[str, Any]]:
+        """Traverse pages lazily; fail if the server repeats a cursor."""
+        seen = {params["cursor"]} if params.get("cursor") else set()
+        while True:
+            page = list_method(*args, **params)
+            yield from page.data
+            if not page.has_more:
+                return
+            if not page.next_cursor or page.next_cursor in seen:
+                raise ValueError("Pagination cursor did not advance")
+            seen.add(page.next_cursor)
+            params["cursor"] = page.next_cursor
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ControlPlaneClient:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()