structx-sdk 0.2.0__py3-none-any.whl

structx_sdk/__init__.py

@@ -0,0 +1,82 @@
+"""struct-x Python SDK — official client for the structured-extraction API.
+
+Quickstart:
+
+    from structx_sdk import StructX
+
+    client = StructX(api_key="sx_...")
+    result = client.extract(
+        content="<div>$99 Widget</div>",
+        schema={
+            "type": "object",
+            "properties": {
+                "price_cents": {"type": "integer"},
+                "title": {"type": "string"},
+            },
+        },
+    )
+    print(result.data)               # {'price_cents': 9900, 'title': 'Widget'}
+    print(result.field_confidences)  # [FieldConfidence(field='price_cents', ...)]
+
+Async variant — same surface:
+
+    from structx_sdk import AsyncStructX
+
+    async with AsyncStructX(api_key="sx_...") as client:
+        result = await client.extract(content="...", schema={...})
+"""
+from ._client import AsyncStructX, RetryPolicy, StructX
+from ._exceptions import (
+    ApiError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    StructXError,
+    TransportError,
+    ValidationError,
+)
+from ._models import (
+    Extraction,
+    FieldConfidence,
+    InferenceResult,
+    InferredField,
+    InferredSchema,
+    Model,
+    Recommendation,
+    Template,
+    TokenCounts,
+    Usage,
+)
+from ._version import __version__
+
+__all__ = [
+    # Clients
+    "StructX",
+    "AsyncStructX",
+    "RetryPolicy",
+    # Exceptions
+    "StructXError",
+    "TransportError",
+    "ApiError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    # Models
+    "Extraction",
+    "FieldConfidence",
+    "TokenCounts",
+    "InferenceResult",
+    "InferredSchema",
+    "InferredField",
+    "Recommendation",
+    "Template",
+    "Model",
+    "Usage",
+    # Meta
+    "__version__",
+]

structx_sdk/_client.py

@@ -0,0 +1,526 @@
+"""Sync (`StructX`) and async (`AsyncStructX`) clients.
+
+Both share `_BaseClient` for configuration + response parsing + retry
+policy; only the I/O path differs. We intentionally don't subclass
+across sync/async (Python's protocol mismatch makes that messy);
+instead, the response-parsing and retry logic are pure functions
+operating on `httpx.Response`-shaped data, callable from either side.
+
+httpx is the underlying HTTP library — supports sync + async with one
+API, ships its own connection pool, and respects PEP 8.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import random
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+from urllib.parse import urljoin
+
+import httpx
+
+from ._exceptions import (
+    ApiError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    StructXError,
+    TransportError,
+    ValidationError,
+)
+from ._models import (
+    Extraction,
+    InferenceResult,
+    Model,
+    Template,
+    Usage,
+)
+from ._version import __version__
+
+_DEFAULT_BASE_URL = "https://api.structx.ai"
+_USER_AGENT = (
+    f"structx-sdk/{__version__} "
+    f"httpx/{httpx.__version__} "
+    f"Python/{platform.python_version()}"
+)
+
+# Endpoints that mutate / bill — retry only on TransportError, never
+# on 5xx (the server may have partially processed before failing).
+_WRITE_PATHS = frozenset({"/v1/extract", "/v1/extract/batch", "/v1/schemas/infer"})
+
+
+# ── Retry policy ────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Controls retry behavior for transient failures.
+
+    Defaults are conservative: 3 attempts total, exponential backoff
+    capped at 30s, 5xx-retry enabled for reads but disabled for writes
+    (the SDK enforces the write-exclusion at call sites; this flag only
+    affects reads). `respect_retry_after` lets the server tell us
+    when to come back — used by 429s.
+    """
+
+    max_attempts: int = 3
+    initial_backoff: float = 1.0
+    max_backoff: float = 30.0
+    retry_on_5xx: bool = True
+    respect_retry_after: bool = True
+    jitter: float = 0.2
+
+    def backoff_for(self, attempt: int, retry_after: float | None = None) -> float:
+        """Seconds to sleep before `attempt` (1-indexed). If the server
+        sent `Retry-After`, use that — caps still apply."""
+        if retry_after is not None and self.respect_retry_after:
+            return min(retry_after, self.max_backoff)
+        base = self.initial_backoff * (2 ** (attempt - 1))
+        jitter_range = base * self.jitter
+        return min(base + random.uniform(-jitter_range, jitter_range), self.max_backoff)
+
+
+# ── Base client (shared config + parsing) ────────────────────
+
+
+_EXC_BY_STATUS: dict[int, type[ApiError]] = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    400: ValidationError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+@dataclass
+class _BaseClient:
+    api_key: str
+    base_url: str = _DEFAULT_BASE_URL
+    timeout: float = 30.0
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    default_headers: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            raise StructXError(
+                "api_key is required. Pass it directly or set the "
+                "STRUCTX_API_KEY environment variable."
+            )
+        # Normalize base_url so urljoin works predictably with leading-
+        # slash paths.
+        self.base_url = self.base_url.rstrip("/") + "/"
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        h = {
+            "X-API-Key": self.api_key,
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        h.update(self.default_headers)
+        if extra:
+            h.update(extra)
+        return h
+
+    def _url(self, path: str) -> str:
+        # urljoin requires trailing-slash on base; we ensured that in
+        # __post_init__. Path may be absolute (/v1/...) or relative.
+        return urljoin(self.base_url, path.lstrip("/"))
+
+    @staticmethod
+    def _parse_response(response: httpx.Response) -> dict[str, Any]:
+        """Translate a raw HTTP response into either the JSON body or
+        an appropriate typed exception. Single source of truth for
+        error mapping — both sync and async paths route through here."""
+        request_id = response.headers.get("x-request-id") or response.headers.get(
+            "request-id"
+        )
+        if 200 <= response.status_code < 300:
+            if not response.content:
+                return {}
+            try:
+                return response.json()
+            except ValueError as e:
+                raise ApiError(
+                    f"Server returned a non-JSON 2xx response: {e}",
+                    status_code=response.status_code,
+                    request_id=request_id,
+                ) from e
+
+        # Error path. Backend convention is {"error": str, "code": str}.
+        body: dict[str, Any] = {}
+        try:
+            body = response.json() if response.content else {}
+        except ValueError:
+            pass
+
+        message = body.get("error") or response.text or response.reason_phrase
+        code = body.get("code")
+        exc_cls = _EXC_BY_STATUS.get(response.status_code)
+        if exc_cls is None:
+            exc_cls = ServerError if response.status_code >= 500 else ApiError
+
+        if exc_cls is RateLimitError:
+            retry_after_header = response.headers.get("retry-after")
+            try:
+                retry_after = float(retry_after_header) if retry_after_header else None
+            except ValueError:
+                retry_after = None
+            raise RateLimitError(
+                message,
+                status_code=response.status_code,
+                code=code,
+                response_body=body,
+                request_id=request_id,
+                retry_after=retry_after,
+                credits_used=body.get("credits_used"),
+                credits_remaining=body.get("credits_remaining"),
+            )
+
+        raise exc_cls(
+            message,
+            status_code=response.status_code,
+            code=code,
+            response_body=body,
+            request_id=request_id,
+        )
+
+    def _is_retryable_response(self, path: str, status: int) -> bool:
+        """5xx retry rule. Writes never retry on 5xx — see _WRITE_PATHS
+        and the docstring on TransportError."""
+        if not self.retry.retry_on_5xx:
+            return False
+        if path in _WRITE_PATHS:
+            return False
+        return 500 <= status < 600 and status != 501  # Not Implemented isn't transient
+
+
+# ── Sync client ──────────────────────────────────────────────
+
+
+class StructX(_BaseClient):
+    """Synchronous client.
+
+    Example:
+        >>> from structx_sdk import StructX
+        >>> client = StructX(api_key="sx_...")
+        >>> result = client.extract(
+        ...     content="<div>$99 Widget</div>",
+        ...     schema={"type": "object", "properties": {
+        ...         "price_cents": {"type": "integer"},
+        ...         "title": {"type": "string"},
+        ...     }},
+        ... )
+        >>> result.data
+        {'price_cents': 9900, 'title': 'Widget'}
+        >>> result.field_confidences[0].confidence
+        0.92
+
+    Picks up `STRUCTX_API_KEY` and `STRUCTX_BASE_URL` from the
+    environment if not passed explicitly:
+
+        >>> client = StructX.from_env()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        retry: RetryPolicy | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        _http: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key or os.environ.get("STRUCTX_API_KEY", ""),
+            base_url=base_url or os.environ.get("STRUCTX_BASE_URL", _DEFAULT_BASE_URL),
+            timeout=timeout,
+            retry=retry or RetryPolicy(),
+            default_headers=default_headers or {},
+        )
+        self._http = _http or httpx.Client(timeout=timeout)
+        self._owns_http = _http is None
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "StructX":
+        return cls(**overrides)
+
+    def __enter__(self) -> "StructX":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    # ── Internal request loop ────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        for attempt in range(1, self.retry.max_attempts + 1):
+            try:
+                response = self._http.request(
+                    method=method,
+                    url=self._url(path),
+                    headers=self._headers(headers),
+                    json=json,
+                    params=params,
+                )
+            except (httpx.TransportError, httpx.TimeoutException) as e:
+                last_exc = TransportError(f"{type(e).__name__}: {e}")
+                if attempt < self.retry.max_attempts:
+                    time.sleep(self.retry.backoff_for(attempt))
+                    continue
+                raise last_exc from e
+
+            if attempt < self.retry.max_attempts and self._is_retryable_response(
+                path, response.status_code
+            ):
+                retry_after = response.headers.get("retry-after")
+                try:
+                    ra = float(retry_after) if retry_after else None
+                except ValueError:
+                    ra = None
+                time.sleep(self.retry.backoff_for(attempt, retry_after=ra))
+                continue
+
+            return self._parse_response(response)
+
+        # The loop always returns or raises; this is unreachable.
+        raise last_exc or StructXError("retry loop exhausted with no response")
+
+    # ── Public API ───────────────────────────────────────────
+
+    def extract(
+        self,
+        content: str,
+        *,
+        schema: dict[str, Any] | None = None,
+        template_slug: str | None = None,
+        tier: str = "required",
+        options: dict[str, Any] | None = None,
+    ) -> Extraction:
+        """Run a structured extraction against `content`.
+
+        Pass EXACTLY ONE of `schema` (inline JSON Schema) or
+        `template_slug` (a catalog template like `"logs.stripe.event"`).
+        The backend enforces this; passing both raises `ValidationError`.
+
+        `tier` selects field depth: `"required"` is the cheapest /
+        narrowest extraction; `"extended"` returns every field in the
+        schema. See backend docs for the full tier ladder.
+
+        `options` is forwarded as-is to the backend — use it for
+        `include_citations`, `use_cache`, `confidence_threshold`, etc.
+        """
+        body: dict[str, Any] = {"content": content, "tier": tier}
+        if schema is not None:
+            body["schema"] = schema
+        if template_slug is not None:
+            body["template_slug"] = template_slug
+        if options is not None:
+            body["options"] = options
+        return Extraction.model_validate(self._request("POST", "/v1/extract", json=body))
+
+    def infer_schema(
+        self,
+        content: str,
+        *,
+        content_type: str | None = None,
+        hints: dict[str, Any] | None = None,
+        k: int = 5,
+        return_recommendations: bool = True,
+    ) -> InferenceResult:
+        """Infer a JSON Schema from raw content + optionally return
+        template recommendations that match. Costs `infer_min_credits`
+        per call (configured on the backend; defaults to 3-5)."""
+        body: dict[str, Any] = {
+            "content": content,
+            "k": k,
+            "return_recommendations": return_recommendations,
+        }
+        if content_type is not None:
+            body["content_type"] = content_type
+        if hints is not None:
+            body["hints"] = hints
+        return InferenceResult.model_validate(
+            self._request("POST", "/v1/schemas/infer", json=body)
+        )
+
+    def list_templates(self) -> list[Template]:
+        """Public template gallery."""
+        raw = self._request("GET", "/v1/schemas")
+        items = raw if isinstance(raw, list) else raw.get("templates", [])
+        return [Template.model_validate(t) for t in items]
+
+    def list_models(self) -> list[Model]:
+        """Available models. Most callers don't need this — the
+        backend's router picks per call."""
+        raw = self._request("GET", "/v1/models")
+        items = raw if isinstance(raw, list) else raw.get("models", [])
+        return [Model.model_validate(m) for m in items]
+
+    def usage(self) -> Usage:
+        """Current credit usage for the authenticated key."""
+        return Usage.model_validate(self._request("GET", "/v1/billing/usage"))
+
+
+# ── Async client ─────────────────────────────────────────────
+
+
+class AsyncStructX(_BaseClient):
+    """Asynchronous counterpart of `StructX`. Same surface, same
+    typed responses, same exception classes — only the I/O is async.
+
+    Example:
+        >>> from structx_sdk import AsyncStructX
+        >>> async with AsyncStructX(api_key="sx_...") as client:
+        ...     result = await client.extract(content="...", schema={...})
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        retry: RetryPolicy | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        _http: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key or os.environ.get("STRUCTX_API_KEY", ""),
+            base_url=base_url or os.environ.get("STRUCTX_BASE_URL", _DEFAULT_BASE_URL),
+            timeout=timeout,
+            retry=retry or RetryPolicy(),
+            default_headers=default_headers or {},
+        )
+        self._http = _http or httpx.AsyncClient(timeout=timeout)
+        self._owns_http = _http is None
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "AsyncStructX":
+        return cls(**overrides)
+
+    async def __aenter__(self) -> "AsyncStructX":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        for attempt in range(1, self.retry.max_attempts + 1):
+            try:
+                response = await self._http.request(
+                    method=method,
+                    url=self._url(path),
+                    headers=self._headers(headers),
+                    json=json,
+                    params=params,
+                )
+            except (httpx.TransportError, httpx.TimeoutException) as e:
+                last_exc = TransportError(f"{type(e).__name__}: {e}")
+                if attempt < self.retry.max_attempts:
+                    await asyncio.sleep(self.retry.backoff_for(attempt))
+                    continue
+                raise last_exc from e
+
+            if attempt < self.retry.max_attempts and self._is_retryable_response(
+                path, response.status_code
+            ):
+                retry_after = response.headers.get("retry-after")
+                try:
+                    ra = float(retry_after) if retry_after else None
+                except ValueError:
+                    ra = None
+                await asyncio.sleep(self.retry.backoff_for(attempt, retry_after=ra))
+                continue
+
+            return self._parse_response(response)
+
+        raise last_exc or StructXError("retry loop exhausted with no response")
+
+    async def extract(
+        self,
+        content: str,
+        *,
+        schema: dict[str, Any] | None = None,
+        template_slug: str | None = None,
+        tier: str = "required",
+        options: dict[str, Any] | None = None,
+    ) -> Extraction:
+        body: dict[str, Any] = {"content": content, "tier": tier}
+        if schema is not None:
+            body["schema"] = schema
+        if template_slug is not None:
+            body["template_slug"] = template_slug
+        if options is not None:
+            body["options"] = options
+        return Extraction.model_validate(
+            await self._request("POST", "/v1/extract", json=body)
+        )
+
+    async def infer_schema(
+        self,
+        content: str,
+        *,
+        content_type: str | None = None,
+        hints: dict[str, Any] | None = None,
+        k: int = 5,
+        return_recommendations: bool = True,
+    ) -> InferenceResult:
+        body: dict[str, Any] = {
+            "content": content,
+            "k": k,
+            "return_recommendations": return_recommendations,
+        }
+        if content_type is not None:
+            body["content_type"] = content_type
+        if hints is not None:
+            body["hints"] = hints
+        return InferenceResult.model_validate(
+            await self._request("POST", "/v1/schemas/infer", json=body)
+        )
+
+    async def list_templates(self) -> list[Template]:
+        raw = await self._request("GET", "/v1/schemas")
+        items = raw if isinstance(raw, list) else raw.get("templates", [])
+        return [Template.model_validate(t) for t in items]
+
+    async def list_models(self) -> list[Model]:
+        raw = await self._request("GET", "/v1/models")
+        items = raw if isinstance(raw, list) else raw.get("models", [])
+        return [Model.model_validate(m) for m in items]
+
+    async def usage(self) -> Usage:
+        return Usage.model_validate(await self._request("GET", "/v1/billing/usage"))

structx_sdk/_exceptions.py

@@ -0,0 +1,177 @@
+"""Typed exception hierarchy for the struct-x SDK.
+
+Every backend error response carries `{"error": str, "code": str}` (see
+backend/routers/*.py — convention). The SDK maps `code` (or, if absent,
+HTTP status) to a typed exception class so callers can `except
+RateLimitError` instead of inspecting status codes.
+
+Hierarchy is intentionally narrow — three categories that map to three
+call-site decisions:
+
+    StructXError                 base; matches anything from the SDK
+      ApiError                   server returned an error response
+        AuthenticationError      401 — fix your API key
+        PermissionDeniedError    403 — your key works but lacks scope
+        RateLimitError           429 — back off; carries credits info
+        ValidationError          400/422 — fix your input
+        NotFoundError            404 — wrong slug or id
+        ServerError              5xx — retry or contact support
+      TransportError             network/timeout failure, never reached the server
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class StructXError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class TransportError(StructXError):
+    """Network-level failure — the request never reached the API or the
+    response never made it back. Always safe to retry idempotent calls;
+    write calls (extract/infer) are *probably* safe but the backend may
+    have partially processed before the connection dropped."""
+
+
+# Keys whose VALUES are stripped from `response_body` before the body
+# is attached to the exception. Common sense + the platform's known
+# field names. Customer code that logs `repr(exc)` or pipes
+# exceptions to Sentry won't leak: API keys (`x-api-key`, `authorization`,
+# `apikey`), session credentials (`password`, `token`, `secret`), or
+# raw payload content (`content` — extraction inputs are often the
+# most sensitive thing in the request). Match is case-insensitive.
+_REDACTED_KEYS = frozenset({
+    "x-api-key", "authorization", "apikey", "api_key",
+    "password", "token", "secret", "private_key",
+    "content",
+})
+
+# Sentinel returned in place of the redacted value. The original
+# payload size is preserved (in chars) so debugging can see "this
+# field had data" without seeing what.
+def _redact(value: object) -> str:
+    if isinstance(value, str):
+        return f"<redacted {len(value)} chars>"
+    if isinstance(value, (bytes, bytearray)):
+        return f"<redacted {len(value)} bytes>"
+    return "<redacted>"
+
+
+def _redact_body(body: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Return a shallow copy of `body` with sensitive keys' values
+    replaced by a length-bounded redacted sentinel. Defends against
+    customer `repr(exc)` / Sentry captures of payloads that may
+    contain credentials or PII. Keys checked case-insensitively against
+    `_REDACTED_KEYS`."""
+    if not body:
+        return body
+    redacted: dict[str, Any] = {}
+    for k, v in body.items():
+        if isinstance(k, str) and k.lower() in _REDACTED_KEYS:
+            redacted[k] = _redact(v)
+        else:
+            redacted[k] = v
+    return redacted
+
+
+class ApiError(StructXError):
+    """Server responded with an error. Subclasses below are status/code-
+    typed; if none matches, raw `ApiError` is raised so callers can still
+    pattern-match `except ApiError`.
+
+    Privacy posture (Phase 5.5 / rho): `response_body` has sensitive
+    keys redacted at exception-construction time — see `_REDACTED_KEYS`.
+    Customer code that logs `repr(exc)` or routes exceptions to Sentry
+    will see `<redacted N chars>` instead of credentials / payload
+    content. `__repr__` ALSO omits the body entirely as a second layer
+    — pass `.response_body` explicitly if you need the (redacted)
+    dict for programmatic inspection.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        response_body: dict[str, Any] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        # Redact at construction time so any post-creation access
+        # (including third-party traceback formatters) sees the safe
+        # version, not the raw payload.
+        self.response_body = _redact_body(response_body)
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        # Intentionally does NOT include response_body — second layer
+        # of defense against `f"{exc!r}"` patterns in customer logs.
+        # The body is still accessible via `.response_body` for
+        # callers that need programmatic inspection.
+        bits = [f"status={self.status_code}"]
+        if self.code:
+            bits.append(f"code={self.code!r}")
+        if self.request_id:
+            bits.append(f"request_id={self.request_id!r}")
+        return f"{self.__class__.__name__}({self.message!r}, {', '.join(bits)})"
+
+
+class AuthenticationError(ApiError):
+    """401 — the API key is missing, malformed, or revoked."""
+
+
+class PermissionDeniedError(ApiError):
+    """403 — the API key is valid but doesn't have access to this
+    resource (e.g. admin-only endpoint)."""
+
+
+class NotFoundError(ApiError):
+    """404 — template slug, key id, or other resource doesn't exist."""
+
+
+class ValidationError(ApiError):
+    """400 / 422 — your request payload is malformed. Common cases:
+    schema isn't a JSON object, content is too large, template_slug
+    doesn't resolve."""
+
+
+class RateLimitError(ApiError):
+    """429 — you've hit the daily credit cap OR the per-window request
+    cap. The `retry_after` attribute (seconds) is populated from the
+    `Retry-After` response header when present. Credits are populated
+    from the response body when the backend supplied them (it does for
+    credit-exhaustion 429s; not for IP-based throttling)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        code: str | None = None,
+        response_body: dict[str, Any] | None = None,
+        request_id: str | None = None,
+        retry_after: float | None = None,
+        credits_used: int | None = None,
+        credits_remaining: int | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            code=code,
+            response_body=response_body,
+            request_id=request_id,
+        )
+        self.retry_after = retry_after
+        self.credits_used = credits_used
+        self.credits_remaining = credits_remaining
+
+
+class ServerError(ApiError):
+    """5xx — the backend returned a server-side failure. Retrying may
+    help for 502/503/504; 500 usually means a bug — report it with the
+    `request_id` attribute attached."""

structx_sdk/_models.py

@@ -0,0 +1,154 @@
+"""Pydantic response models — mirror backend/models/schemas.py response
+shapes but with SDK-idiomatic names. The backend's `ExtractionResponse`
+becomes `Extraction` here; the SDK doesn't need the "Response" suffix
+because the caller isn't dealing with HTTP-layer concerns.
+
+Stays in lockstep with the backend by accepting EXTRA fields silently
+(`model_config.extra = 'allow'`) — when the backend adds a new field,
+old SDK versions don't break, they just don't surface it as a typed
+attribute. Callers can still reach it via `obj.model_dump()` or
+`obj.__pydantic_extra__`.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+# ── Extraction ───────────────────────────────────────────────
+
+
+class FieldConfidence(_Base):
+    """Per-field confidence score returned by `/v1/extract`. The backend
+    populates `source_snippet` only when `include_citations=true` was
+    requested; otherwise it's None."""
+
+    field: str
+    confidence: float
+    source_snippet: str | None = None
+
+
+class TokenCounts(_Base):
+    input: int
+    output: int
+
+
+class Extraction(_Base):
+    """The result of a single `/v1/extract` call."""
+
+    data: dict[str, Any] | list[Any]
+    model_used: str
+    latency_ms: int
+    tokens: TokenCounts
+    credits_used: int
+    credits_remaining: int | None = None
+    confidence: float | None = None
+    field_confidences: list[FieldConfidence] = Field(default_factory=list)
+    cached: bool = False
+    extraction_id: str | None = None
+    warnings: list[str] = Field(default_factory=list)
+
+
+# ── Schema inference (recommender) ───────────────────────────
+
+
+class InferredField(_Base):
+    name: str
+    type: str
+    description: str
+    required: bool
+    rationale: str
+    confidence: float
+
+
+class InferredSchema(_Base):
+    """The inferred JSON Schema plus per-field rationale. Returned by
+    `/v1/schemas/infer`. `json_schema` is a valid JSON Schema dict the
+    caller can immediately pass back to `extract()`."""
+
+    json_schema: dict[str, Any]
+    fields: list[InferredField] = Field(default_factory=list)
+    overall_confidence: float
+    needs_review: bool = False
+
+
+class Recommendation(_Base):
+    """A template or user-schema candidate returned by the recommender."""
+
+    source_type: Literal["template", "user_schema", "inferred_draft"]
+    source_id: str
+    slug: str
+    name: str
+    score: float
+    json_schema: dict[str, Any]
+    score_breakdown: dict[str, float] = Field(default_factory=dict)
+
+
+class InferenceResult(_Base):
+    """The full payload from `/v1/schemas/infer` — the inferred schema,
+    optional template recommendations, and the `event_id` you'd echo
+    back to the feedback endpoint."""
+
+    event_id: str
+    inferred: InferredSchema
+    recommendations: list[Recommendation] = Field(default_factory=list)
+    credits_used: int
+    partial: bool = False
+
+
+# ── Templates ────────────────────────────────────────────────
+
+
+class Template(_Base):
+    """A row from the public template gallery (`/v1/schemas`).
+
+    Note: the JSON Schema field is named `schema_def` on the Python
+    object (with alias `"schema"` for the wire format). Pydantic v2
+    reserves `.schema` as a model-introspection method, so we can't
+    use the bare name — same convention the backend uses in
+    `backend/models/schemas.py:ExtractionRequest`.
+    """
+
+    slug: str
+    name: str
+    description: str | None = None
+    category: str | None = None
+    schema_def: dict[str, Any] = Field(default_factory=dict, alias="schema")
+    usage_count: int | None = None
+    acceptance_rate: float | None = None
+    avg_confidence: float | None = None
+
+
+# ── Models / routing info ────────────────────────────────────
+
+
+class Model(_Base):
+    """A model entry from `/v1/models`. The SDK exposes these for
+    introspection; callers normally don't pick a specific model and let
+    the backend's router decide."""
+
+    name: str
+    provider: str
+    capability: str | None = None
+    notes: str | None = None
+
+
+# ── Usage ────────────────────────────────────────────────────
+
+
+class Usage(_Base):
+    """Summary returned by `/v1/billing/usage` (or wherever the auth'd
+    `/auth/me`-style usage call lives in the deployment). Field set
+    intentionally minimal; extra backend fields surface via `extra=allow`."""
+
+    credits_used_today: int
+    credits_limit_daily: int
+    tier: str | None = None
+    period_start: datetime | None = None
+    period_end: datetime | None = None

structx_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

structx_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: structx-sdk
+Version: 0.2.0
+Summary: Official Python SDK (structx-sdk) for struct-x — agent-native structured extraction.
+Project-URL: Homepage, https://structx.ai
+Project-URL: Documentation, https://docs.structx.ai
+Project-URL: Repository, https://github.com/struct-x-ai/struct-x
+Project-URL: Issues, https://github.com/struct-x-ai/struct-x/issues
+Project-URL: Changelog, https://github.com/struct-x-ai/struct-x/blob/main/sdk/python/CHANGELOG.md
+Author-email: struct-x <support@structx.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,extraction,json-schema,llm,mcp,structured-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic<3.0,>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# structx-sdk — Python SDK for struct-x
+
+[![PyPI](https://img.shields.io/pypi/v/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python client for **[struct-x](https://structx.ai)** — the agent-native structured-extraction API. Send raw content and a JSON Schema, get back validated, typed JSON with per-field confidence scores.
+
+## Install
+
+```bash
+pip install structx-sdk
+```
+
+## Quickstart
+
+```python
+from structx_sdk import StructX
+
+client = StructX(api_key="sx_...")
+
+result = client.extract(
+    content="<div><h1>Aeron Chair</h1><span>$1,795.00</span></div>",
+    schema={
+        "type": "object",
+        "required": ["title", "price_cents"],
+        "properties": {
+            "title":       {"type": "string"},
+            "price_cents": {"type": "integer"},
+        },
+    },
+)
+
+print(result.data)
+# {'title': 'Aeron Chair', 'price_cents': 179500}
+
+print(result.field_confidences[0])
+# FieldConfidence(field='title', confidence=0.96, source_snippet=None)
+```
+
+## Use a catalog template instead of an inline schema
+
+```python
+result = client.extract(
+    content=stripe_webhook_payload,
+    template_slug="logs.stripe.event",   # latest published version
+)
+```
+
+Pin to a specific template version with `family_slug@version`:
+
+```python
+template_slug="logs.stripe.event@1.0.0"
+```
+
+## Don't have a schema yet? Let the API infer one
+
+```python
+inference = client.infer_schema(
+    content="<html>… some product page …</html>",
+    content_type="html",
+)
+
+print(inference.inferred.json_schema)   # ready to pass back to extract()
+for f in inference.inferred.fields:
+    print(f"{f.name} ({f.type}) — {f.rationale}")
+
+# Plus template recommendations, if any matched:
+for r in inference.recommendations:
+    print(f"{r.slug} (score={r.score:.2f})")
+```
+
+## Async
+
+Same surface, `await`-flavored:
+
+```python
+import asyncio
+from structx_sdk import AsyncStructX
+
+async def main():
+    async with AsyncStructX(api_key="sx_...") as client:
+        result = await client.extract(content="…", schema={…})
+        print(result.data)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Param          | Default                       | Notes                                                  |
+|----------------|-------------------------------|--------------------------------------------------------|
+| `api_key`      | `STRUCTX_API_KEY` env var     | Required.                                              |
+| `base_url`     | `STRUCTX_BASE_URL` env var, else `https://api.structx.ai` | Override for staging / self-hosted. |
+| `timeout`      | `30.0` seconds                | Applied per request.                                   |
+| `retry`        | `RetryPolicy(max_attempts=3, …)` | Tune via `RetryPolicy(...)`.                        |
+| `default_headers` | `{}`                       | Merged into every request — e.g., for tracing IDs.    |
+
+Pick up credentials from the environment with `StructX.from_env()`:
+
+```python
+import os
+os.environ["STRUCTX_API_KEY"] = "sx_..."
+
+from structx_sdk import StructX
+client = StructX.from_env()
+```
+
+## Errors
+
+All exceptions inherit from `StructXError`. Catch the specific class you care about:
+
+```python
+from structx_sdk import RateLimitError, ValidationError, ServerError
+
+try:
+    result = client.extract(content=…, schema=…)
+except RateLimitError as e:
+    # 429 — back off; e.retry_after, e.credits_used, e.credits_remaining are populated
+    print(f"Sleep {e.retry_after}s. Used {e.credits_used}/{e.credits_used + e.credits_remaining}.")
+except ValidationError as e:
+    # 400/422 — fix your input. e.code carries the machine-readable reason.
+    print(f"Bad input: {e.code} — {e.message}")
+except ServerError as e:
+    # 5xx — retry or contact support; e.request_id is your handle.
+    print(f"Server error (request_id={e.request_id})")
+```
+
+Full hierarchy:
+
+```
+StructXError
+├── TransportError              # network failure — request never reached the server
+└── ApiError                    # server responded with an error status
+    ├── AuthenticationError     # 401
+    ├── PermissionDeniedError   # 403
+    ├── NotFoundError           # 404
+    ├── ValidationError         # 400, 422
+    ├── RateLimitError          # 429  (carries retry_after, credits info)
+    └── ServerError             # 5xx
+```
+
+## Retries
+
+By default, **read** calls (`list_templates`, `list_models`, `usage`) auto-retry on transient 5xx and connection errors with exponential backoff.
+
+**Write** calls (`extract`, `infer_schema`) retry ONLY on transport errors, never on 5xx — because a 5xx after a partial backend run may have already billed the call.
+
+Customize via `RetryPolicy`:
+
+```python
+from structx_sdk import StructX, RetryPolicy
+
+client = StructX(
+    api_key="sx_...",
+    retry=RetryPolicy(
+        max_attempts=5,
+        initial_backoff=0.5,
+        max_backoff=60.0,
+        retry_on_5xx=True,
+        respect_retry_after=True,
+    ),
+)
+```
+
+## Forward compatibility
+
+Response models accept extra fields silently. When the API adds a new field, old SDK versions don't break — they just don't surface it as a typed attribute. Reach it via `result.model_dump()` or `result.__pydantic_extra__`.
+
+## Development
+
+```bash
+git clone https://github.com/struct-x-ai/struct-x
+cd struct-x/sdk/python
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

structx_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+structx_sdk/__init__.py,sha256=p5wf3CtJwDoR3wDImDgJetoq60MBIC1p_NN_D6fXLqM,1836
+structx_sdk/_client.py,sha256=XXcSo5OAs2nA6EufbdQKQzOPMdRMCJdDPvExCV43BBs,18807
+structx_sdk/_exceptions.py,sha256=1hjA4XjmIBsn8wY4tWSXju7oYWaSokLcp9Y32-XkZiI,6875
+structx_sdk/_models.py,sha256=etnuPXTXtqwz888CwLtBLUNLbkEPQJ-PTBpoOo7W64w,5059
+structx_sdk/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+structx_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structx_sdk-0.2.0.dist-info/METADATA,sha256=2LDCzFuypWzSyOPYZq6DSgE2npMJy-Kzn0FgMRSDDzg,7201
+structx_sdk-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+structx_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=sbvXdvix1vIUS5hCXHHwpeBylS2pLxG343RiI9zMU1E,1065
+structx_sdk-0.2.0.dist-info/RECORD,,

structx_sdk-0.2.0.dist-info/WHEEL

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

structx_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 struct-x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.