jev-lite 0.0.1__py3-none-any.whl

jev_lite/__init__.py

@@ -0,0 +1,70 @@
+"""jev-lite — OpenAI-style Pydantic client for TypeSafe Jev."""
+
+from jev_lite._client import AsyncClient, AsyncTypeSafe, Client, TypeSafe
+from jev_lite._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    OverloadedError,
+    PermissionDeniedError,
+    RateLimitError,
+    TypeSafeError,
+    UnprocessableEntityError,
+)
+from jev_lite._telemetry import instrument
+from jev_lite._version import __version__
+from jev_lite.types import (
+    Choice,
+    ChoiceAnswer,
+    Model,
+    ModelList,
+    Noul,
+    NoulAnswer,
+    NoulCriteria,
+    Score,
+    ScoreAnswer,
+    SystemOneRequest,
+    SystemOneResponse,
+    Usage,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncClient",
+    "AsyncTypeSafe",
+    "AuthenticationError",
+    "BadRequestError",
+    "Choice",
+    "ChoiceAnswer",
+    "Client",
+    "InternalServerError",
+    "Model",
+    "ModelList",
+    "NotFoundError",
+    "Noul",
+    "NoulAnswer",
+    "NoulCriteria",
+    "OverloadedError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Score",
+    "ScoreAnswer",
+    "SystemOneRequest",
+    "SystemOneResponse",
+    "TypeSafe",
+    "TypeSafeError",
+    "UnprocessableEntityError",
+    "Usage",
+    "__version__",
+    "instrument",
+]

jev_lite/_client.py

@@ -0,0 +1,364 @@
+"""Synchronous and asynchronous TypeSafe clients, in the OpenAI SDK style."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from collections.abc import Mapping
+from typing import Any, Self
+from urllib.parse import urlparse
+
+import httpx
+from opentelemetry.trace import SpanKind
+
+from jev_lite._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MODEL,
+    DEFAULT_TIMEOUT_SECONDS,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    ENV_DEFAULT_MODEL,
+    REQUEST_ID_HEADER,
+    RETRYABLE_STATUS_CODES,
+)
+from jev_lite._exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    TypeSafeError,
+    decode_json,
+    raise_for_status,
+)
+from jev_lite._telemetry import get_tracer, json_attribute, record_exception
+from jev_lite._version import __version__
+from jev_lite.resources.models import AsyncModels, Models
+from jev_lite.resources.system_one import AsyncSystemOne, SystemOne
+
+
+def _read_env(name: str) -> str | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+class TypeSafe:
+    """Synchronous TypeSafe API client.
+
+    Authentication and the default model are inferred from the environment when
+    omitted, matching `openai.OpenAI`:
+
+    - `api_key` from `TYPESAFE_API_KEY`
+    - `base_url` from `TYPESAFE_BASE_URL`
+    - `model` from `TYPESAFE_DEFAULT_MODEL`
+    """
+
+    api_key: str
+    base_url: str
+    model: str
+    max_retries: int
+    timeout: float | httpx.Timeout
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else _read_env(ENV_API_KEY)
+        if not resolved_key:
+            raise TypeSafeError(
+                "The api_key client option must be set either by passing api_key "
+                f"to the client or by setting the {ENV_API_KEY} environment variable"
+            )
+        self.api_key = resolved_key
+        self.base_url = (
+            base_url or _read_env(ENV_BASE_URL) or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.model = model or _read_env(ENV_DEFAULT_MODEL) or DEFAULT_MODEL
+        self.timeout = DEFAULT_TIMEOUT_SECONDS if timeout is None else timeout
+        self.max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+        self._owns_http_client = http_client is None
+        self._http_client = http_client or httpx.Client(
+            base_url=self.base_url, timeout=self.timeout
+        )
+        self.system_one = SystemOne(self)
+        self.models = Models(self)
+
+    def close(self) -> None:
+        """Close the owned HTTP client. A caller-supplied `http_client` is left open."""
+        if self._owns_http_client:
+            self._http_client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"jev_lite/{__version__}",
+        }
+        headers.update(self._default_headers)
+        if extra:
+            headers.update(
+                {key: value for key, value in extra.items() if value is not None}
+            )
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> httpx.Response:
+        extra = extra or {}
+        extra_headers = extra.get("headers")
+        timeout = extra.get("timeout")
+        tracer = get_tracer()
+        with tracer.start_as_current_span(
+            f"http.{method.lower()}",
+            kind=SpanKind.CLIENT,
+        ) as span:
+            _set_http_span(
+                span, method=method, base_url=self.base_url, path=path, json=json
+            )
+            last_error: Exception | None = None
+            for attempt in range(self.max_retries + 1):
+                try:
+                    response = self._http_client.request(
+                        method,
+                        path,
+                        headers=self._headers(extra_headers),
+                        json=json,
+                        timeout=timeout if timeout is not None else self.timeout,
+                    )
+                except httpx.TimeoutException as exc:
+                    last_error = APITimeoutError(request=exc.request)
+                    if attempt >= self.max_retries:
+                        record_exception(span, last_error)
+                        raise last_error from exc
+                    _sleep_backoff(attempt)
+                    continue
+                except httpx.RequestError as exc:
+                    last_error = APIConnectionError(request=exc.request)
+                    if attempt >= self.max_retries:
+                        record_exception(span, last_error)
+                        raise last_error from exc
+                    _sleep_backoff(attempt)
+                    continue
+
+                span.set_attribute("http.response.status_code", response.status_code)
+                request_id = response.headers.get(REQUEST_ID_HEADER)
+                if request_id:
+                    span.set_attribute("typesafe.request_id", request_id)
+                if (
+                    response.status_code in RETRYABLE_STATUS_CODES
+                    and attempt < self.max_retries
+                ):
+                    _sleep_backoff(
+                        attempt, retry_after=response.headers.get("retry-after")
+                    )
+                    continue
+                try:
+                    raise_for_status(response)
+                except Exception as exc:
+                    record_exception(span, exc)
+                    raise
+                return response
+            assert last_error is not None
+            record_exception(span, last_error)
+            raise last_error
+
+    def _decode(self, response: httpx.Response) -> Any:
+        return decode_json(response)
+
+
+class AsyncTypeSafe:
+    """Asynchronous TypeSafe API client."""
+
+    api_key: str
+    base_url: str
+    model: str
+    max_retries: int
+    timeout: float | httpx.Timeout
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else _read_env(ENV_API_KEY)
+        if not resolved_key:
+            raise TypeSafeError(
+                "The api_key client option must be set either by passing api_key "
+                f"to the client or by setting the {ENV_API_KEY} environment variable"
+            )
+        self.api_key = resolved_key
+        self.base_url = (
+            base_url or _read_env(ENV_BASE_URL) or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.model = model or _read_env(ENV_DEFAULT_MODEL) or DEFAULT_MODEL
+        self.timeout = DEFAULT_TIMEOUT_SECONDS if timeout is None else timeout
+        self.max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+        self._owns_http_client = http_client is None
+        self._http_client = http_client or httpx.AsyncClient(
+            base_url=self.base_url, timeout=self.timeout
+        )
+        self.system_one = AsyncSystemOne(self)
+        self.models = AsyncModels(self)
+
+    async def close(self) -> None:
+        """Close the owned HTTP client. A caller-supplied `http_client` is left open."""
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"jev_lite/{__version__}",
+        }
+        headers.update(self._default_headers)
+        if extra:
+            headers.update(
+                {key: value for key, value in extra.items() if value is not None}
+            )
+        return headers
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> httpx.Response:
+        extra = extra or {}
+        extra_headers = extra.get("headers")
+        timeout = extra.get("timeout")
+        tracer = get_tracer()
+        with tracer.start_as_current_span(
+            f"http.{method.lower()}",
+            kind=SpanKind.CLIENT,
+        ) as span:
+            _set_http_span(
+                span, method=method, base_url=self.base_url, path=path, json=json
+            )
+            last_error: Exception | None = None
+            for attempt in range(self.max_retries + 1):
+                try:
+                    response = await self._http_client.request(
+                        method,
+                        path,
+                        headers=self._headers(extra_headers),
+                        json=json,
+                        timeout=timeout if timeout is not None else self.timeout,
+                    )
+                except httpx.TimeoutException as exc:
+                    last_error = APITimeoutError(request=exc.request)
+                    if attempt >= self.max_retries:
+                        record_exception(span, last_error)
+                        raise last_error from exc
+                    await _asleep_backoff(attempt)
+                    continue
+                except httpx.RequestError as exc:
+                    last_error = APIConnectionError(request=exc.request)
+                    if attempt >= self.max_retries:
+                        record_exception(span, last_error)
+                        raise last_error from exc
+                    await _asleep_backoff(attempt)
+                    continue
+
+                span.set_attribute("http.response.status_code", response.status_code)
+                request_id = response.headers.get(REQUEST_ID_HEADER)
+                if request_id:
+                    span.set_attribute("typesafe.request_id", request_id)
+                if (
+                    response.status_code in RETRYABLE_STATUS_CODES
+                    and attempt < self.max_retries
+                ):
+                    await _asleep_backoff(
+                        attempt, retry_after=response.headers.get("retry-after")
+                    )
+                    continue
+                try:
+                    raise_for_status(response)
+                except Exception as exc:
+                    record_exception(span, exc)
+                    raise
+                return response
+            assert last_error is not None
+            record_exception(span, last_error)
+            raise last_error
+
+    def _decode(self, response: httpx.Response) -> Any:
+        return decode_json(response)
+
+
+Client = TypeSafe
+AsyncClient = AsyncTypeSafe
+
+
+def _set_http_span(
+    span: Any,
+    *,
+    method: str,
+    base_url: str,
+    path: str,
+    json: dict[str, Any] | None,
+) -> None:
+    span.set_attribute("http.request.method", method)
+    span.set_attribute("url.full", f"{base_url}{path}")
+    host = urlparse(base_url).hostname
+    if host:
+        span.set_attribute("server.address", host)
+    if json is not None:
+        span.set_attribute("http.request.body.json", json_attribute(json))
+
+
+def _backoff_seconds(attempt: int, retry_after: str | None = None) -> float:
+    if retry_after:
+        try:
+            return max(0.0, float(retry_after))
+        except ValueError:
+            pass
+    return min(8.0, 0.25 * (2**attempt)) + random.random() * 0.05
+
+
+def _sleep_backoff(attempt: int, retry_after: str | None = None) -> None:
+    time.sleep(_backoff_seconds(attempt, retry_after))
+
+
+async def _asleep_backoff(attempt: int, retry_after: str | None = None) -> None:
+    import asyncio
+
+    await asyncio.sleep(_backoff_seconds(attempt, retry_after))

jev_lite/_constants.py

@@ -0,0 +1,19 @@
+"""Client defaults."""
+
+from __future__ import annotations
+
+DEFAULT_BASE_URL = "https://api.typesafe.ai"
+DEFAULT_MODEL = "jev-latest"
+DEFAULT_TIMEOUT_SECONDS = 60.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_OTLP_ENDPOINT = "http://127.0.0.1:4318"
+
+ENV_API_KEY = "TYPESAFE_API_KEY"
+ENV_BASE_URL = "TYPESAFE_BASE_URL"
+ENV_DEFAULT_MODEL = "TYPESAFE_DEFAULT_MODEL"
+ENV_OTEL_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"
+ENV_OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME"
+
+REQUEST_ID_HEADER = "x-typesafe-request-id"
+RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504, 529})
+MAX_SPAN_VALUE_CHARS = 8192

jev_lite/_exceptions.py

@@ -0,0 +1,189 @@
+"""HTTP and client errors, named after the OpenAI Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+
+from jev_lite._constants import REQUEST_ID_HEADER
+
+
+class TypeSafeError(Exception):
+    """Base error for the TypeSafe client."""
+
+
+class APIError(TypeSafeError):
+    """An error associated with an HTTP request."""
+
+    message: str
+    request: httpx.Request
+    body: object | None
+    code: str | None
+    type: str | None
+
+    def __init__(
+        self, message: str, request: httpx.Request, *, body: object | None
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+        self.body = body
+        self.code = None
+        self.type = None
+        if isinstance(body, dict):
+            detail = body.get("detail", body)
+            if isinstance(detail, dict):
+                self.code = _as_str(detail.get("error_type") or detail.get("code"))
+                self.type = self.code
+
+
+class APIResponseValidationError(APIError):
+    """The response JSON did not match the expected Pydantic schema."""
+
+    response: httpx.Response
+    status_code: int
+
+    def __init__(
+        self,
+        response: httpx.Response,
+        body: object | None,
+        *,
+        message: str | None = None,
+    ) -> None:
+        super().__init__(
+            message or "Data returned by the API was invalid for the expected schema.",
+            response.request,
+            body=body,
+        )
+        self.response = response
+        self.status_code = response.status_code
+
+
+class APIStatusError(APIError):
+    """Raised when the API responds with a 4xx or 5xx status code."""
+
+    response: httpx.Response
+    status_code: int
+    request_id: str | None
+
+    def __init__(
+        self, message: str, *, response: httpx.Response, body: object | None
+    ) -> None:
+        super().__init__(message, response.request, body=body)
+        self.response = response
+        self.status_code = response.status_code
+        self.request_id = response.headers.get(REQUEST_ID_HEADER)
+
+
+class APIConnectionError(APIError):
+    def __init__(
+        self, *, message: str = "Connection error.", request: httpx.Request
+    ) -> None:
+        super().__init__(message, request, body=None)
+
+
+class APITimeoutError(APIConnectionError):
+    def __init__(self, request: httpx.Request) -> None:
+        super().__init__(message="Request timed out.", request=request)
+
+
+class BadRequestError(APIStatusError):
+    status_code: Literal[400] = 400
+
+
+class AuthenticationError(APIStatusError):
+    status_code: Literal[401] = 401
+
+
+class PermissionDeniedError(APIStatusError):
+    status_code: Literal[403] = 403
+
+
+class NotFoundError(APIStatusError):
+    status_code: Literal[404] = 404
+
+
+class UnprocessableEntityError(APIStatusError):
+    status_code: Literal[422] = 422
+
+
+class RateLimitError(APIStatusError):
+    status_code: Literal[429] = 429
+
+
+class InternalServerError(APIStatusError):
+    pass
+
+
+class OverloadedError(InternalServerError):
+    """TypeSafe returned 529 (temporarily overloaded)."""
+
+    status_code: Literal[529] = 529
+
+
+def _as_str(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _message_from_body(body: object | None, fallback: str) -> str:
+    if isinstance(body, dict):
+        detail = body.get("detail", body)
+        if isinstance(detail, dict):
+            message = detail.get("message")
+            if isinstance(message, str) and message:
+                return message
+        if isinstance(detail, str) and detail:
+            return detail
+        if isinstance(detail, list) and detail:
+            first = detail[0]
+            if isinstance(first, dict):
+                loc = first.get("loc")
+                msg = first.get("msg")
+                if msg:
+                    return f"{msg} ({loc})" if loc is not None else str(msg)
+    return fallback
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP errors onto OpenAI-style exception classes."""
+    if response.is_success:
+        return
+
+    body: object | None
+    try:
+        body = response.json()
+    except ValueError:
+        body = response.text or None
+
+    message = _message_from_body(body, fallback=f"HTTP {response.status_code}")
+    status = response.status_code
+    error_cls: type[APIStatusError]
+    if status == 400:
+        error_cls = BadRequestError
+    elif status == 401:
+        error_cls = AuthenticationError
+    elif status == 403:
+        error_cls = PermissionDeniedError
+    elif status == 404:
+        error_cls = NotFoundError
+    elif status == 422:
+        error_cls = UnprocessableEntityError
+    elif status == 429:
+        error_cls = RateLimitError
+    elif status == 529:
+        error_cls = OverloadedError
+    elif status >= 500:
+        error_cls = InternalServerError
+    else:
+        error_cls = APIStatusError
+    raise error_cls(message, response=response, body=body)
+
+
+def decode_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise APIResponseValidationError(
+            response, body=response.text, message=str(exc)
+        ) from exc

jev_lite/_resource.py

@@ -0,0 +1,18 @@
+"""Resource objects bound to a client, matching the OpenAI SDK pattern."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from jev_lite._client import AsyncTypeSafe, TypeSafe
+
+
+class SyncAPIResource:
+    def __init__(self, client: TypeSafe) -> None:
+        self._client = client
+
+
+class AsyncAPIResource:
+    def __init__(self, client: AsyncTypeSafe) -> None:
+        self._client = client