docforge-sdk 0.1.0__py3-none-any.whl

docforge_sdk/__init__.py

@@ -0,0 +1,161 @@
+# ------------------- Exceptions ------------------- #
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthError,
+    ConflictError,
+    DocForgeError,
+    NotFoundError,
+    UnprocessableError,
+)
+from ._version import __version__
+
+# ------------------- Clients ------------------- #
+from .client import AsyncClient, Client
+
+# ------------------- Shared vocabulary ------------------- #
+from .models._shared import (
+    Capability,
+    DocumentStatus,
+    EnrichmentKind,
+    EnrichmentStatus,
+    FieldOrigin,
+    FieldScope,
+    FieldType,
+    KeyPermissions,
+    SourceKind,
+)
+
+# ------------------- Auth models ------------------- #
+from .models.auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest
+
+# ------------------- Blobs models ------------------- #
+from .models.blobs import BlobContent
+
+# ------------------- Collections models ------------------- #
+from .models.collections import (
+    CollectionModel,
+    CreateCollectionRequest,
+    FieldSpec,
+    UpdateCollectionRequest,
+)
+
+# ------------------- Documents models ------------------- #
+from .models.documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+
+# ------------------- Explorer models ------------------- #
+from .models.explorer import (
+    BulkChunkEnabledPatch,
+    BulkChunkEnabledResponse,
+    ChunkEnabledPatch,
+    ChunkEnabledResult,
+    ChunkInfo,
+    DocumentDetail,
+    DocumentListItem,
+    MetadataValue,
+    PageInfo,
+)
+
+# ------------------- Health models ------------------- #
+from .models.health import HealthStatus
+
+# ------------------- IR models ------------------- #
+from .models.ir import DocumentIRModel, IRBlock, IREnrichment, IRFigure, IRTable
+
+# ------------------- Jobs models ------------------- #
+from .models.jobs import JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
+
+# ------------------- Pipelines models ------------------- #
+from .models.pipelines import (
+    EditResponse,
+    InspectResponse,
+    PipelineDesignResponse,
+    PipelineIndexResponse,
+    PipelineSurface,
+    StageApplyResponse,
+    StageViewResponse,
+)
+
+# ------------------- Search models ------------------- #
+from .models.search import SearchHit, SearchRequest, SearchResponse, SearchTarget
+
+# ------------------- Public API ------------------- #
+__all__ = [
+    "__version__",
+    # Clients
+    "AsyncClient",
+    "Client",
+    # Shared vocabulary
+    "Capability",
+    "KeyPermissions",
+    "FieldType",
+    "FieldOrigin",
+    "FieldScope",
+    "SourceKind",
+    "DocumentStatus",
+    "EnrichmentKind",
+    "EnrichmentStatus",
+    # Auth
+    "CreateKeyRequest",
+    "RotateKeyRequest",
+    "CreatedKey",
+    "KeyInfo",
+    # Health
+    "HealthStatus",
+    # Collections
+    "FieldSpec",
+    "CollectionModel",
+    "CreateCollectionRequest",
+    "UpdateCollectionRequest",
+    # Documents
+    "UploadAccepted",
+    "EnabledPatch",
+    "DocumentEnabledResponse",
+    # Explorer
+    "MetadataValue",
+    "DocumentListItem",
+    "DocumentDetail",
+    "PageInfo",
+    "ChunkInfo",
+    "ChunkEnabledPatch",
+    "BulkChunkEnabledPatch",
+    "ChunkEnabledResult",
+    "BulkChunkEnabledResponse",
+    # IR
+    "IRBlock",
+    "IRTable",
+    "IRFigure",
+    "IREnrichment",
+    "DocumentIRModel",
+    # Search
+    "SearchTarget",
+    "SearchRequest",
+    "SearchHit",
+    "SearchResponse",
+    # Jobs
+    "JobStatus",
+    "JobEvent",
+    "JobTrace",
+    "WorkerActivity",
+    "WorkersLive",
+    # Blobs
+    "BlobContent",
+    # Pipelines
+    "PipelineSurface",
+    "PipelineIndexResponse",
+    "PipelineDesignResponse",
+    "InspectResponse",
+    "EditResponse",
+    "StageViewResponse",
+    "StageApplyResponse",
+    # Exceptions
+    "DocForgeError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableError",
+]

docforge_sdk/_exceptions.py

@@ -0,0 +1,108 @@
+# ====== Code Summary ======
+# The public exception hierarchy for the SDK. Every failure a caller can catch descends from
+# ``DocForgeError``. Transport-level failures (no connection, timeout) and HTTP error statuses map to
+# dedicated subclasses so callers can branch on failure kind without inspecting raw httpx objects.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+import httpx
+
+
+class DocForgeError(Exception):
+    """Base class for every error raised by the DocForge SDK."""
+
+
+class APIConnectionError(DocForgeError):
+    """Raised when the API could not be reached (DNS, refused connection, network drop)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """Raised when a request exceeded the configured timeout before a response arrived."""
+
+
+class APIStatusError(DocForgeError):
+    """
+    Raised when the API returned a 4xx/5xx HTTP status.
+
+    Attributes:
+        status_code (int): The HTTP status code returned by the API.
+        body (Any): The parsed response body (JSON when decodable, else raw text) — an opaque,
+            server-shaped error payload.
+    """
+
+    def __init__(self, message: str, *, status_code: int, body: Any) -> None:
+        """
+        Initialize the status error with the failing code and response body.
+
+        Args:
+            message (str): Human-readable summary of the failure.
+            status_code (int): The HTTP status code returned by the API.
+            body (Any): The parsed response body (opaque server error payload).
+        """
+        super().__init__(message)
+        self.status_code: int = status_code
+        self.body: Any = body
+
+
+class AuthError(APIStatusError):
+    """Raised on 401 (unauthenticated) or 403 (unauthorized) responses."""
+
+
+class NotFoundError(APIStatusError):
+    """Raised on 404 responses (the target resource does not exist)."""
+
+
+class ConflictError(APIStatusError):
+    """Raised on 409 responses (the request conflicts with the resource's current state)."""
+
+
+class UnprocessableError(APIStatusError):
+    """Raised on 422 responses (the request body failed server-side validation)."""
+
+
+# Maps an HTTP status code to the most specific exception class for it.
+_STATUS_TO_EXCEPTION: dict[int, type[APIStatusError]] = {
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableError,
+}
+
+
+def exception_from_response(response: httpx.Response) -> APIStatusError:
+    """
+    Build the most specific ``APIStatusError`` for an errored HTTP response.
+
+    Args:
+        response (httpx.Response): The response whose status is 4xx/5xx.
+
+    Returns:
+        APIStatusError: A ``NotFoundError`` / ``AuthError`` / ``ConflictError`` /
+        ``UnprocessableError`` when the status is recognised, else a plain ``APIStatusError``.
+    """
+    # 1. Decode the body as JSON when possible; fall back to raw text for non-JSON errors.
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = response.text
+
+    # 2. Pick the dedicated subclass for this status, defaulting to the generic status error.
+    exception_class = _STATUS_TO_EXCEPTION.get(response.status_code, APIStatusError)
+    message = f"API request failed with status {response.status_code}"
+    return exception_class(message, status_code=response.status_code, body=body)
+
+
+__all__ = [
+    "DocForgeError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableError",
+    "exception_from_response",
+]

docforge_sdk/_requestspec.py

@@ -0,0 +1,34 @@
+# ====== Code Summary ======
+# The immutable description of a single HTTP call. A RequestSpec is pure data — it carries the method,
+# API-relative path and payload, and performs no I/O. Resource classes build specs; transports execute
+# them. Centralising URL/body shape here keeps it out of the async/sync transport bodies.
+
+# ====== Standard Library Imports ======
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RequestSpec:
+    """
+    An immutable, I/O-free description of one API request.
+
+    The ``json`` and ``files`` payloads are typed ``Any`` because they are opaque, endpoint-shaped
+    bodies already serialised by the calling resource (a model dump or an httpx multipart mapping).
+
+    Attributes:
+        method (str): The HTTP method (e.g. ``"GET"``, ``"POST"``, ``"DELETE"``).
+        path (str): The path relative to the API root (e.g. ``"/auth/keys"``).
+        params (dict[str, Any] | None): Query parameters; ``None`` values are dropped at execution.
+        json (Any): The JSON request body, or ``None`` for bodyless requests.
+        files (Any): The multipart file mapping for uploads, or ``None``.
+    """
+
+    method: str
+    path: str
+    params: dict[str, Any] | None = None
+    json: Any = None
+    files: Any = None
+
+
+__all__ = ["RequestSpec"]

docforge_sdk/_transport_async.py

@@ -0,0 +1,168 @@
+# ====== Code Summary ======
+# The asynchronous HTTP transport (over httpx.AsyncClient). Inherits every pure helper from
+# _TransportBase and supplies only the async I/O primitive (_send); spec execution, upload and raw
+# byte fetch route through that single chokepoint, so no endpoint hand-rolls its own parsing.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+import httpx
+
+# ====== Local Project Imports ======
+from ._exceptions import APIConnectionError, APITimeoutError
+from ._requestspec import RequestSpec
+from ._transport_base import T, _TransportBase
+
+
+class AsyncTransport(_TransportBase):
+    """Asynchronous transport backed by an ``httpx.AsyncClient``."""
+
+    def __init__(self, base_url: str, timeout: float, api_token: str = "") -> None:
+        """
+        Create the underlying async httpx client with the resolved headers and timeout.
+
+        Args:
+            base_url (str): The API origin.
+            timeout (float): Per-request timeout in seconds.
+            api_token (str): Bearer token; empty means unauthenticated.
+        """
+        super().__init__(base_url, timeout, api_token)
+        self._client = httpx.AsyncClient(timeout=timeout, headers=self._headers)
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+    ) -> httpx.Response:
+        """
+        Execute a single httpx call, mapping transport failures to SDK exceptions.
+
+        Args:
+            method (str): The HTTP method.
+            url (str): The absolute request URL.
+            params (dict[str, Any] | None): Cleaned query parameters.
+            json (Any): The JSON body, if any.
+            data (Any): The form body for multipart uploads, if any.
+            files (Any): The multipart file mapping, if any.
+
+        Returns:
+            httpx.Response: The raw response (status not yet checked).
+
+        Raises:
+            APITimeoutError: When the request timed out.
+            APIConnectionError: When the API could not be reached.
+        """
+        # 1. A timeout is a specific connection failure — catch it before the broader transport error.
+        try:
+            return await self._client.request(
+                method, url, params=params, json=json, data=data, files=files
+            )
+        except httpx.TimeoutException as error:
+            raise APITimeoutError(str(error)) from error
+        except httpx.TransportError as error:
+            raise APIConnectionError(str(error)) from error
+
+    async def request(self, spec: RequestSpec, model: type[T]) -> T:
+        """
+        Execute a request spec and validate its response into the target model.
+
+        Args:
+            spec (RequestSpec): The request description.
+            model (type[T]): The target type to validate the response into.
+
+        Returns:
+            T: The validated response model.
+        """
+        # 1. Execute, 2. surface any error status, 3. parse — the single per-transport pipeline.
+        response = await self._send(
+            spec.method,
+            self._url(spec.path),
+            params=self._clean(spec.params),
+            json=spec.json,
+            files=spec.files,
+        )
+        self._raise_for_status(response)
+        return self._parse(response, model)
+
+    async def request_bare(self, spec: RequestSpec, model: type[T]) -> T:
+        """
+        Execute a request spec against the BARE origin (outside ``/api/v1``) and parse it.
+
+        Mirrors ``request`` but targets an un-versioned route (e.g. the public ``/health`` probe).
+
+        Args:
+            spec (RequestSpec): The request description (its path is origin-relative).
+            model (type[T]): The target type to validate the response into.
+
+        Returns:
+            T: The validated response model.
+        """
+        response = await self._send(
+            spec.method,
+            self._bare_url(spec.path),
+            params=self._clean(spec.params),
+            json=spec.json,
+            files=spec.files,
+        )
+        self._raise_for_status(response)
+        return self._parse(response, model)
+
+    async def upload(self, path: str, files: Any, data: Any, model: type[T]) -> T:
+        """
+        Send a multipart upload and validate the response into the target model.
+
+        Args:
+            path (str): The API-relative path.
+            files (Any): The multipart file mapping.
+            data (Any): The accompanying form fields, if any.
+            model (type[T]): The target response type.
+
+        Returns:
+            T: The validated response model.
+        """
+        response = await self._send("POST", self._url(path), files=files, data=data)
+        self._raise_for_status(response)
+        return self._parse(response, model)
+
+    async def get_bytes(self, path: str) -> bytes:
+        """
+        Fetch a raw binary body (e.g. a stored blob) without JSON parsing.
+
+        Args:
+            path (str): The API-relative path.
+
+        Returns:
+            bytes: The raw response content.
+        """
+        response = await self._send("GET", self._url(path))
+        self._raise_for_status(response)
+        return response.content
+
+    async def get_bytes_typed(self, path: str) -> tuple[bytes, str]:
+        """
+        Fetch a raw binary body together with its server-declared media type.
+
+        Args:
+            path (str): The API-relative path.
+
+        Returns:
+            tuple[bytes, str]: The raw content and its ``Content-Type`` (a generic octet-stream
+            fallback when the header is absent).
+        """
+        response = await self._send("GET", self._url(path))
+        self._raise_for_status(response)
+        mime_type = response.headers.get("content-type", "application/octet-stream")
+        return response.content, mime_type
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client and release its connections."""
+        await self._client.aclose()
+
+
+__all__ = ["AsyncTransport"]

docforge_sdk/_transport_base.py

@@ -0,0 +1,141 @@
+# ====== Code Summary ======
+# The shared, I/O-free transport core. _TransportBase holds the resolved URL roots, the default
+# headers and every pure helper (param cleaning, status→exception mapping, response parsing). The
+# AsyncTransport and SyncTransport subclasses (in _transport_async / _transport_sync) inherit all of
+# this and only supply the actual httpx call, so no endpoint ever hand-rolls its own parsing.
+
+# ====== Standard Library Imports ======
+from typing import Any, TypeVar
+
+# ====== Third-Party Library Imports ======
+import httpx
+from pydantic import TypeAdapter
+
+# ====== Local Project Imports ======
+from ._exceptions import exception_from_response
+
+# The type of the model a request is validated into (a BaseModel subclass, ``list[...]`` or ``None``).
+T = TypeVar("T")
+
+# The API version prefix every resource path is mounted under.
+_API_PREFIX = "/api/v1"
+
+
+class _TransportBase:
+    """
+    Shared, I/O-free behaviour for both transports.
+
+    Holds the resolved URL roots, the default headers and the pure helpers (param cleaning, status
+    mapping, response parsing) so the async and sync subclasses only differ by the actual httpx call.
+    """
+
+    def __init__(self, base_url: str, timeout: float, api_token: str = "") -> None:
+        """
+        Resolve the URL roots and build the default headers.
+
+        Args:
+            base_url (str): The API origin, e.g. ``"http://localhost:10040"``.
+            timeout (float): Per-request timeout in seconds.
+            api_token (str): Bearer token; when empty, no Authorization header is sent.
+        """
+        # 1. Keep both a bare origin (for un-versioned routes like /health) and the versioned root.
+        self._root: str = base_url.rstrip("/")
+        self._api_root: str = f"{self._root}{_API_PREFIX}"
+        self._timeout: float = timeout
+        self._headers: dict[str, str] = self._build_headers(api_token)
+
+    @staticmethod
+    def _build_headers(api_token: str) -> dict[str, str]:
+        """
+        Build the default request headers, adding Authorization only when a token is present.
+
+        Args:
+            api_token (str): The bearer token, possibly empty.
+
+        Returns:
+            dict[str, str]: The default headers for every request.
+        """
+        # 1. Always accept JSON; only attach the bearer credential when one was configured.
+        headers = {"Accept": "application/json"}
+        if api_token:
+            headers["Authorization"] = f"Bearer {api_token}"
+        return headers
+
+    @staticmethod
+    def _clean(params: dict[str, Any] | None) -> dict[str, Any] | None:
+        """
+        Drop ``None``-valued query parameters so they are never serialised into the URL.
+
+        Args:
+            params (dict[str, Any] | None): The raw query parameters.
+
+        Returns:
+            dict[str, Any] | None: The params without any ``None`` values, or ``None``.
+        """
+        # 1. Nothing to clean when no params were supplied.
+        if params is None:
+            return None
+        return {key: value for key, value in params.items() if value is not None}
+
+    def _url(self, path: str) -> str:
+        """
+        Build the absolute URL for an API-relative path.
+
+        Args:
+            path (str): The path relative to the API root (leading slash included).
+
+        Returns:
+            str: The fully-qualified request URL.
+        """
+        return f"{self._api_root}{path}"
+
+    def _bare_url(self, path: str) -> str:
+        """
+        Build the absolute URL for a path mounted at the bare origin (outside ``/api/v1``).
+
+        Used only by the public, un-versioned routes such as ``/health``.
+
+        Args:
+            path (str): The path relative to the origin (leading slash included).
+
+        Returns:
+            str: The fully-qualified request URL, without the API version prefix.
+        """
+        return f"{self._root}{path}"
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """
+        Map any 4xx/5xx response to the matching SDK exception.
+
+        Args:
+            response (httpx.Response): The response to inspect.
+
+        Raises:
+            APIStatusError: (or a subclass) when the status code is >= 400.
+        """
+        # 1. Success statuses pass through untouched.
+        if response.status_code >= 400:
+            raise exception_from_response(response)
+
+    def _parse(self, response: httpx.Response, model: type[T]) -> T:
+        """
+        Validate a response body into the target model.
+
+        Args:
+            response (httpx.Response): The successful response to parse.
+            model (type[T]): The target type — a ``BaseModel`` subclass, a ``list[...]`` alias, or
+                ``type(None)`` for bodyless (204) responses.
+
+        Returns:
+            T: The validated model instance (or ``None`` for a bodyless response).
+        """
+        # 1. A no-content endpoint (e.g. 204 on delete) has no body to validate. In this branch the
+        #    target type is narrowed to ``None``, so returning None satisfies the declared T.
+        if model is type(None):
+            return None
+
+        # 2. TypeAdapter handles single models AND ``list[...]`` aliases with one code path.
+        return TypeAdapter(model).validate_python(response.json())
+
+
+__all__ = ["T", "_TransportBase"]