docforge-sdk 0.1.0__py3-none-any.whl

docforge_sdk/_transport_sync.py

@@ -0,0 +1,168 @@
+# ====== Code Summary ======
+# The synchronous HTTP transport (over httpx.Client). Inherits every pure helper from _TransportBase
+# and supplies only the sync 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 SyncTransport(_TransportBase):
+    """Synchronous transport backed by an ``httpx.Client``."""
+
+    def __init__(self, base_url: str, timeout: float, api_token: str = "") -> None:
+        """
+        Create the underlying sync 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.Client(timeout=timeout, headers=self._headers)
+
+    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 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
+
+    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 = 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)
+
+    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 = 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)
+
+    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 = self._send("POST", self._url(path), files=files, data=data)
+        self._raise_for_status(response)
+        return self._parse(response, model)
+
+    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 = self._send("GET", self._url(path))
+        self._raise_for_status(response)
+        return response.content
+
+    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 = 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
+
+    def close(self) -> None:
+        """Close the underlying httpx client and release its connections."""
+        self._client.close()
+
+
+__all__ = ["SyncTransport"]

docforge_sdk/_version.py

@@ -0,0 +1,5 @@
+# ====== Code Summary ======
+# Single source of truth for the package version. Hatchling reads ``__version__`` from this file to
+# populate the distribution metadata (see ``[tool.hatch.version]`` in pyproject.toml).
+
+__version__ = "0.1.0"

docforge_sdk/client.py

@@ -0,0 +1,131 @@
+# ====== Code Summary ======
+# The public entry points: AsyncClient and Client. Each owns a transport and wires every resource
+# group onto itself (auth, health, collections, documents, explorer, search, jobs, blobs, pipelines).
+# Both support context-manager use so the underlying httpx client is always closed.
+
+# ====== Standard Library Imports ======
+from types import TracebackType
+
+# ====== Local Project Imports ======
+from ._transport_async import AsyncTransport
+from ._transport_sync import SyncTransport
+from .resources.auth import AsyncAuth, SyncAuth
+from .resources.blobs import AsyncBlobs, SyncBlobs
+from .resources.collections import AsyncCollections, SyncCollections
+from .resources.documents import AsyncDocuments, SyncDocuments
+from .resources.explorer import AsyncExplorer, SyncExplorer
+from .resources.health import AsyncHealth, SyncHealth
+from .resources.jobs import AsyncJobs, SyncJobs
+from .resources.pipelines import AsyncPipelines, SyncPipelines
+from .resources.search import AsyncSearch, SyncSearch
+
+
+class AsyncClient:
+    """
+    Asynchronous DocForge API client.
+
+    Attributes:
+        auth (AsyncAuth): API-key management resource.
+        health (AsyncHealth): Liveness probe.
+        collections (AsyncCollections): Collection CRUD.
+        documents (AsyncDocuments): Document admission + searchability control.
+        explorer (AsyncExplorer): Document/chunk read surface + IR + toggles.
+        search (AsyncSearch): Hybrid search.
+        jobs (AsyncJobs): Ingestion-job monitoring.
+        blobs (AsyncBlobs): Content-addressed blob fetch.
+        pipelines (AsyncPipelines): Pipeline discovery + design.
+    """
+
+    def __init__(self, base_url: str, timeout: float = 30.0, api_token: str = "") -> None:
+        """
+        Create the client and wire its resource groups onto the shared transport.
+
+        Args:
+            base_url (str): The API origin, e.g. ``"http://localhost:10040"``.
+            timeout (float): Per-request timeout in seconds.
+            api_token (str): Bearer token; empty means unauthenticated requests.
+        """
+        self._transport = AsyncTransport(base_url, timeout, api_token)
+        self.auth = AsyncAuth(self._transport)
+        self.health = AsyncHealth(self._transport)
+        self.collections = AsyncCollections(self._transport)
+        self.documents = AsyncDocuments(self._transport)
+        self.explorer = AsyncExplorer(self._transport)
+        self.search = AsyncSearch(self._transport)
+        self.jobs = AsyncJobs(self._transport)
+        self.blobs = AsyncBlobs(self._transport)
+        self.pipelines = AsyncPipelines(self._transport)
+
+    async def __aenter__(self) -> "AsyncClient":
+        """Enter the async context, returning the client itself."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the client on context exit."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying transport and release its connections."""
+        await self._transport.aclose()
+
+
+class Client:
+    """
+    Synchronous DocForge API client.
+
+    Attributes:
+        auth (SyncAuth): API-key management resource.
+        health (SyncHealth): Liveness probe.
+        collections (SyncCollections): Collection CRUD.
+        documents (SyncDocuments): Document admission + searchability control.
+        explorer (SyncExplorer): Document/chunk read surface + IR + toggles.
+        search (SyncSearch): Hybrid search.
+        jobs (SyncJobs): Ingestion-job monitoring.
+        blobs (SyncBlobs): Content-addressed blob fetch.
+        pipelines (SyncPipelines): Pipeline discovery + design.
+    """
+
+    def __init__(self, base_url: str, timeout: float = 30.0, api_token: str = "") -> None:
+        """
+        Create the client and wire its resource groups onto the shared transport.
+
+        Args:
+            base_url (str): The API origin, e.g. ``"http://localhost:10040"``.
+            timeout (float): Per-request timeout in seconds.
+            api_token (str): Bearer token; empty means unauthenticated requests.
+        """
+        self._transport = SyncTransport(base_url, timeout, api_token)
+        self.auth = SyncAuth(self._transport)
+        self.health = SyncHealth(self._transport)
+        self.collections = SyncCollections(self._transport)
+        self.documents = SyncDocuments(self._transport)
+        self.explorer = SyncExplorer(self._transport)
+        self.search = SyncSearch(self._transport)
+        self.jobs = SyncJobs(self._transport)
+        self.blobs = SyncBlobs(self._transport)
+        self.pipelines = SyncPipelines(self._transport)
+
+    def __enter__(self) -> "Client":
+        """Enter the context, returning the client itself."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the client on context exit."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying transport and release its connections."""
+        self._transport.close()
+
+
+__all__ = ["AsyncClient", "Client"]

docforge_sdk/models/__init__.py

@@ -0,0 +1,132 @@
+# ------------------- Shared vocabulary ------------------- #
+from ._shared import (
+    Capability,
+    DocumentStatus,
+    EnrichmentKind,
+    EnrichmentStatus,
+    FieldOrigin,
+    FieldScope,
+    FieldType,
+    KeyPermissions,
+    SourceKind,
+)
+
+# ------------------- Auth models ------------------- #
+from .auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest
+
+# ------------------- Blobs models ------------------- #
+from .blobs import BlobContent
+
+# ------------------- Collections models ------------------- #
+from .collections import (
+    CollectionModel,
+    CreateCollectionRequest,
+    FieldSpec,
+    UpdateCollectionRequest,
+)
+
+# ------------------- Documents models ------------------- #
+from .documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+
+# ------------------- Explorer models ------------------- #
+from .explorer import (
+    BulkChunkEnabledPatch,
+    BulkChunkEnabledResponse,
+    ChunkEnabledPatch,
+    ChunkEnabledResult,
+    ChunkInfo,
+    DocumentDetail,
+    DocumentListItem,
+    MetadataValue,
+    PageInfo,
+)
+
+# ------------------- Health models ------------------- #
+from .health import HealthStatus
+
+# ------------------- IR models ------------------- #
+from .ir import DocumentIRModel, IRBlock, IREnrichment, IRFigure, IRTable
+
+# ------------------- Jobs models ------------------- #
+from .jobs import JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
+
+# ------------------- Pipelines models ------------------- #
+from .pipelines import (
+    EditResponse,
+    InspectResponse,
+    PipelineDesignResponse,
+    PipelineIndexResponse,
+    PipelineSurface,
+    StageApplyResponse,
+    StageViewResponse,
+)
+
+# ------------------- Search models ------------------- #
+from .search import SearchHit, SearchRequest, SearchResponse, SearchTarget
+
+# ------------------- Public API ------------------- #
+__all__ = [
+    # 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",
+]

docforge_sdk/models/_shared.py

@@ -0,0 +1,121 @@
+# ====== Code Summary ======
+# Vocabulary shared across resources, mirrored from the DocForge backend (never imported from it, to
+# keep the SDK standalone). Holds the authorization enum + per-key permission scope, the metadata
+# contract enums (FieldType/FieldOrigin/FieldScope), the document lifecycle enums (DocumentStatus/
+# SourceKind) and the IR enrichment enums (EnrichmentKind/EnrichmentStatus).
+
+# ====== Standard Library Imports ======
+from enum import StrEnum
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class Capability(StrEnum):
+    """A coarse action class an endpoint requires of the calling key."""
+
+    READ = "read"
+    WRITE = "write"
+    SEARCH = "search"
+    ADMIN = "admin"
+
+
+class FieldType(StrEnum):
+    """Data type of a metadata field — drives validation and storage."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOL = "bool"
+    KEYWORD_LIST = "keyword_list"
+    DATETIME = "datetime"
+    ENUM = "enum"
+    TEXT = "text"
+    INTEGER_LIST = "integer_list"
+    FLOAT_LIST = "float_list"
+    TEXT_LIST = "text_list"
+
+
+class FieldOrigin(StrEnum):
+    """Where a metadata field's value comes from — drives who may fill it."""
+
+    SYSTEM = "system"
+    USER = "user"
+    GENERATED = "generated"
+
+
+class FieldScope(StrEnum):
+    """At which granularity a field's value lives — one per document, or one per chunk."""
+
+    DOCUMENT = "document"
+    CHUNK = "chunk"
+
+
+class SourceKind(StrEnum):
+    """How a document's pages were acquired — routes parsing (text vs OCR/VLM)."""
+
+    DIGITAL_BORN = "digital_born"
+    SCANNED = "scanned"
+    MIXED = "mixed"
+
+
+class DocumentStatus(StrEnum):
+    """A document's ingestion lifecycle state."""
+
+    PENDING = "pending"
+    PROCESSING = "processing"
+    DONE = "done"
+    FAILED = "failed"
+
+
+class EnrichmentKind(StrEnum):
+    """What an IR block enrichment produced."""
+
+    CLASSIFY = "classify"
+    OCR = "ocr"
+    VLM = "vlm"
+    CHART_TO_DATA = "chart_to_data"
+    TABLE_SUMMARY = "table_summary"
+
+
+class EnrichmentStatus(StrEnum):
+    """The outcome of a block enrichment run."""
+
+    OK = "ok"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class KeyPermissions(BaseModel):
+    """
+    The per-key permission scope stored on an API key.
+
+    A key with ``null`` permissions is full access (root) and is represented as ``None`` at the call
+    site, never as an instance of this model — this model always describes a SCOPED key.
+
+    Attributes:
+        capabilities (list[Capability]): The action classes the key grants (an empty list = a key
+            that can authenticate but is authorized for nothing).
+        collections (list[str]): Either ``["*"]`` (every collection) or an explicit list of
+            collection UUID strings the key is scoped to.
+    """
+
+    capabilities: list[Capability] = Field(
+        description="The action classes this key grants (READ / WRITE / SEARCH / ADMIN)."
+    )
+    collections: list[str] = Field(
+        description="Collection scope: ['*'] for all, else explicit collection UUID strings."
+    )
+
+
+__all__ = [
+    "Capability",
+    "FieldType",
+    "FieldOrigin",
+    "FieldScope",
+    "SourceKind",
+    "DocumentStatus",
+    "EnrichmentKind",
+    "EnrichmentStatus",
+    "KeyPermissions",
+]

docforge_sdk/models/auth.py

@@ -0,0 +1,130 @@
+# ====== Code Summary ======
+# Request/response models for the auth (API-key management) resource, mirrored field-for-field from the
+# DocForge backend router models. The response ``permissions`` field is the opaque JSONB blob the server
+# stores, so it is typed as a plain dict rather than the structured KeyPermissions.
+
+# ====== Standard Library Imports ======
+from datetime import datetime
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+# ====== Local Project Imports ======
+from ._shared import KeyPermissions
+
+
+class CreateKeyRequest(BaseModel):
+    """
+    Body of a create-key request.
+
+    Attributes:
+        name (str): Human-readable label for the key.
+        permissions (KeyPermissions | None): Per-key capability + collection scope; ``None`` = full
+            access (root).
+        expires_at (datetime | None): Absolute expiry instant; ``None`` = never expires.
+    """
+
+    name: str = Field(min_length=1, description="Human-readable label for the key.")
+    permissions: KeyPermissions | None = Field(
+        default=None,
+        description="Per-key capability + collection scope; null = full access (root).",
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        description="Absolute expiry instant; null = never expires.",
+    )
+
+
+class RotateKeyRequest(BaseModel):
+    """
+    Body of a rotate-key request — every field optional so absence clones from the source key.
+
+    Serialization is CRUCIAL here: the backend distinguishes "field absent" (clone the source key's
+    value) from "field present but null" (a meaningful value — ``permissions=null`` means full access,
+    ``expires_at=null`` means never expires). Callers must therefore dump this model with
+    ``exclude_unset=True`` so a field that was never set is omitted from the body, while an explicitly
+    provided ``None`` is sent as JSON ``null``. The auth resource does this for you.
+
+    Attributes:
+        name (str | None): New label; absent = keep the source name.
+        permissions (KeyPermissions | None): New scope; absent = keep the source blob, null = full
+            access.
+        expires_at (datetime | None): New expiry; absent = keep the source expiry, null = never
+            expires.
+    """
+
+    name: str | None = Field(
+        default=None, min_length=1, description="New label; absent = keep the source name."
+    )
+    permissions: KeyPermissions | None = Field(
+        default=None,
+        description="New scope; absent = keep the source blob, null = full access.",
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        description="New expiry instant; absent = keep the source expiry, null = never expires.",
+    )
+
+
+class CreatedKey(BaseModel):
+    """
+    The create/rotate response — the ONLY place the plaintext key is ever returned.
+
+    Attributes:
+        id (str): The key row's UUID.
+        name (str): The label given at creation.
+        prefix (str): The stored display prefix (safe to show; not a secret on its own).
+        permissions (dict[str, Any] | None): The opaque per-scope JSONB blob; ``None`` = full access.
+        created_at (datetime): When the key was created.
+        expires_at (datetime | None): The absolute expiry instant; ``None`` = never expires.
+        key (str): The plaintext key — shown ONCE here, never stored or returned again.
+    """
+
+    id: str = Field(description="The key row's UUID.")
+    name: str = Field(description="The label given at creation.")
+    prefix: str = Field(description="The stored display prefix.")
+    permissions: dict[str, Any] | None = Field(
+        default=None, description="Per-scope blob; null = full access."
+    )
+    created_at: datetime = Field(description="When the key was created.")
+    expires_at: datetime | None = Field(
+        default=None, description="Absolute expiry instant; null = never expires."
+    )
+    key: str = Field(description="Plaintext key — shown ONCE, never recoverable afterwards.")
+
+
+class KeyInfo(BaseModel):
+    """
+    A key as listed — metadata only, never the hash or the plaintext.
+
+    Attributes:
+        id (str): The key row's UUID.
+        name (str): The label given at creation.
+        prefix (str): The stored display prefix.
+        permissions (dict[str, Any] | None): The opaque per-scope JSONB blob; ``None`` = full access.
+        created_at (datetime): When the key was created.
+        expires_at (datetime | None): The absolute expiry instant; ``None`` = never expires.
+        last_used_at (datetime | None): Last successful authentication instant; ``None`` = never used.
+        revoked_at (datetime | None): Soft-revocation timestamp; ``None`` when the key is active.
+    """
+
+    id: str = Field(description="The key row's UUID.")
+    name: str = Field(description="The label given at creation.")
+    prefix: str = Field(description="The stored display prefix.")
+    permissions: dict[str, Any] | None = Field(
+        default=None, description="Per-scope blob; null = full access."
+    )
+    created_at: datetime = Field(description="When the key was created.")
+    expires_at: datetime | None = Field(
+        default=None, description="Absolute expiry instant; null = never expires."
+    )
+    last_used_at: datetime | None = Field(
+        default=None, description="Last successful authentication instant; null = never used."
+    )
+    revoked_at: datetime | None = Field(
+        default=None, description="Soft-revocation timestamp; null when the key is active."
+    )
+
+
+__all__ = ["CreateKeyRequest", "RotateKeyRequest", "CreatedKey", "KeyInfo"]