docforge-sdk 0.16.0__tar.gz → 0.16.2__tar.gz

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.16.0
+Version: 0.16.2
 Summary: Typed async + sync Python client for the DocForge REST API (standalone, zero server deps).
 Project-URL: Homepage, https://github.com/Florian-BARRE/docforge
 Project-URL: Repository, https://github.com/Florian-BARRE/docforge
@@ -304,7 +304,7 @@ with Client("http://localhost:10040", api_token="df_...") as client:
 ```
 
 Key `CreateCollectionRequest` fields beyond the schema: `max_file_size_bytes` (bytes) and
-`job_timeout_seconds` (`float | None`, seconds) — the whole-ingest-job wall-clock budget for that
+`job_timeout_seconds` (`float | None`, seconds) — the whole-ingest-job wall-clock job timeout for that
 collection; `None` (the default) inherits the worker's global job-timeout default. Same field, same
 semantics on `CollectionModel` (read) and `UpdateCollectionRequest` (write; there, omitting it
 leaves the current value unchanged, a set value overrides it).

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/README.md

@@ -281,7 +281,7 @@ with Client("http://localhost:10040", api_token="df_...") as client:
 ```
 
 Key `CreateCollectionRequest` fields beyond the schema: `max_file_size_bytes` (bytes) and
-`job_timeout_seconds` (`float | None`, seconds) — the whole-ingest-job wall-clock budget for that
+`job_timeout_seconds` (`float | None`, seconds) — the whole-ingest-job wall-clock job timeout for that
 collection; `None` (the default) inherits the worker's global job-timeout default. Same field, same
 semantics on `CollectionModel` (read) and `UpdateCollectionRequest` (write; there, omitting it
 leaves the current value unchanged, a set value overrides it).

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/__init__.py

@@ -36,6 +36,9 @@ from .models.auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest
 # ------------------- Blobs models ------------------- #
 from .models.blobs import BlobContent
 
+# ------------------- Capabilities models ------------------- #
+from .models.capabilities import CapabilitiesResponse, CapabilityMatrix, ServiceInfo
+
 # ------------------- Collections models ------------------- #
 from .models.collections import (
     BulkReingestAccepted,
@@ -201,6 +204,9 @@ __all__ = [
     "CancelResult",
     # Blobs
     "BlobContent",
+    "CapabilitiesResponse",
+    "CapabilityMatrix",
+    "ServiceInfo",
     # Pipelines
     "PipelineSurface",
     "PipelineIndexResponse",

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/_version.py

@@ -2,4 +2,4 @@
 # 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.16.0"
+__version__ = "0.16.2"

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/client.py

@@ -12,6 +12,7 @@ from ._transport_sync import SyncTransport
 from .resources.audit import AsyncAudit, SyncAudit
 from .resources.auth import AsyncAuth, SyncAuth
 from .resources.blobs import AsyncBlobs, SyncBlobs
+from .resources.capabilities import AsyncCapabilities, SyncCapabilities
 from .resources.collections import AsyncCollections, SyncCollections
 from .resources.corpus import AsyncCorpus, SyncCorpus
 from .resources.documents import AsyncDocuments, SyncDocuments
@@ -31,6 +32,7 @@ class AsyncClient:
     Attributes:
         auth (AsyncAuth): API-key management resource.
         health (AsyncHealth): Liveness probe.
+        capabilities (AsyncCapabilities): Public deployment discovery.
         collections (AsyncCollections): Collection CRUD.
         documents (AsyncDocuments): Document admission + searchability control.
         explorer (AsyncExplorer): Document/chunk read surface + IR + toggles.
@@ -57,6 +59,7 @@ class AsyncClient:
         self.audit = AsyncAudit(self._transport)
         self.auth = AsyncAuth(self._transport)
         self.health = AsyncHealth(self._transport)
+        self.capabilities = AsyncCapabilities(self._transport)
         self.collections = AsyncCollections(self._transport)
         self.documents = AsyncDocuments(self._transport)
         self.explorer = AsyncExplorer(self._transport)
@@ -93,6 +96,7 @@ class Client:
     Attributes:
         auth (SyncAuth): API-key management resource.
         health (SyncHealth): Liveness probe.
+        capabilities (SyncCapabilities): Public deployment discovery.
         collections (SyncCollections): Collection CRUD.
         documents (SyncDocuments): Document admission + searchability control.
         explorer (SyncExplorer): Document/chunk read surface + IR + toggles.
@@ -119,6 +123,7 @@ class Client:
         self.audit = SyncAudit(self._transport)
         self.auth = SyncAuth(self._transport)
         self.health = SyncHealth(self._transport)
+        self.capabilities = SyncCapabilities(self._transport)
         self.collections = SyncCollections(self._transport)
         self.documents = SyncDocuments(self._transport)
         self.explorer = SyncExplorer(self._transport)

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/models/__init__.py

@@ -20,6 +20,9 @@ from .auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest, WhoAm
 # ------------------- Blobs models ------------------- #
 from .blobs import BlobContent
 
+# ------------------- Capabilities models ------------------- #
+from .capabilities import CapabilitiesResponse, CapabilityMatrix, ServiceInfo
+
 # ------------------- Collections models ------------------- #
 from .collections import (
     BulkReingestAccepted,
@@ -253,6 +256,9 @@ __all__ = [
     "CancelResult",
     # Blobs
     "BlobContent",
+    "CapabilitiesResponse",
+    "CapabilityMatrix",
+    "ServiceInfo",
     # Pipelines
     "PipelineSurface",
     "PipelineIndexResponse",

docforge_sdk-0.16.2/docforge_sdk/models/capabilities.py

@@ -0,0 +1,103 @@
+# ====== Code Summary ======
+# Response models for the capabilities resource, mirrored field-for-field from the DocForge backend
+# router models (app/backend/libs/capabilities/models.py): the deployment self-description served by
+# the public GET /capabilities — running version, auth state, derived GPU presence, the infra stores +
+# optional sidecars (reachability + what each unlocks) and the available pipeline kinds per family.
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class ServiceInfo(BaseModel):
+    """
+    One infra store or optional sidecar of the deployment.
+
+    Attributes:
+        name (str): Stable service name (compose service / network alias).
+        role (str): Short role label (e.g. ``"vector"``, ``"embed"``, ``"parse-ocr"``).
+        reachable (bool): Sidecar: its short-cached ``/health`` probe currently passes. Store:
+            configured (declared, not live-probed — see ``detail``).
+        device (str | None): The compute device the sidecar reports at ``/health`` when it exposes one;
+            ``None`` when unknown or not applicable (stores).
+        provides (list[str]): The capability ids (``"family:kind"``) this service enables — empty for
+            infra stores.
+        detail (str | None): Optional short status note.
+    """
+
+    name: str = Field(description="Stable service name (compose service / network alias).")
+    role: str = Field(description="Short role label (e.g. 'vector', 'embed', 'parse-ocr').")
+    reachable: bool = Field(
+        description="Sidecar: /health probe currently passes. Store: configured (declared, not probed)."
+    )
+    device: str | None = Field(
+        default=None,
+        description="Device the sidecar reports at /health ('cuda'/'cpu'); None when unknown.",
+    )
+    provides: list[str] = Field(
+        default_factory=list,
+        description="Capability ids ('family:kind') this service enables (empty for infra stores).",
+    )
+    detail: str | None = Field(default=None, description="Optional short status note.")
+
+
+class CapabilityMatrix(BaseModel):
+    """
+    The available pipeline kinds per family — 'what can this deployment do NOW'.
+
+    Each list holds the SELECTABLE kinds of that family whose requirement is satisfied: in-worker or
+    per-collection-key kinds are always listed; a sidecar-gated kind is listed only while its sidecar
+    is reachable. ``metagen`` delegates to the ``llm`` family, so it is legitimately empty.
+
+    Attributes:
+        parsers (list[str]): Available ``parser`` kinds.
+        ocr (list[str]): Available ``ocr`` kinds.
+        embed (list[str]): Available ``embed`` kinds.
+        chunkers (list[str]): Available ``chunker`` kinds.
+        vlm (list[str]): Available ``vlm`` kinds.
+        llm (list[str]): Available ``llm`` kinds.
+        rerank (list[str]): Available ``rerank`` kinds.
+        contextualize (list[str]): Available ``contextualize`` kinds.
+        metagen (list[str]): Available ``metagen`` kinds (delegates to ``llm``; usually empty).
+    """
+
+    parsers: list[str] = Field(default_factory=list, description="Available parser kinds.")
+    ocr: list[str] = Field(default_factory=list, description="Available ocr kinds.")
+    embed: list[str] = Field(default_factory=list, description="Available embed kinds.")
+    chunkers: list[str] = Field(default_factory=list, description="Available chunker kinds.")
+    vlm: list[str] = Field(default_factory=list, description="Available vlm kinds.")
+    llm: list[str] = Field(default_factory=list, description="Available llm kinds.")
+    rerank: list[str] = Field(default_factory=list, description="Available rerank kinds.")
+    contextualize: list[str] = Field(
+        default_factory=list, description="Available contextualize kinds."
+    )
+    metagen: list[str] = Field(default_factory=list, description="Available metagen kinds.")
+
+
+class CapabilitiesResponse(BaseModel):
+    """
+    The deployment capabilities snapshot returned by GET /capabilities.
+
+    Attributes:
+        version (str): The running app/image version (``FASTAPI_APP_VERSION`` / ``DOCFORGE_TAG``).
+        auth_enabled (bool): Whether API-key bearer auth gates ``/api/v1`` on this deployment.
+        gpu_present (bool | None): True when any reachable sidecar reports device ``"cuda"``; False when
+            reachable sidecars report only non-cuda devices; None when no device info is available.
+        services (list[ServiceInfo]): The infra stores + optional sidecars.
+        capabilities (CapabilityMatrix): The available pipeline kinds per family.
+    """
+
+    version: str = Field(
+        description="Running app/image version (FASTAPI_APP_VERSION / DOCFORGE_TAG)."
+    )
+    auth_enabled: bool = Field(description="Whether API-key bearer auth gates /api/v1.")
+    gpu_present: bool | None = Field(
+        default=None,
+        description="True if any reachable sidecar reports device 'cuda'; None when unknown.",
+    )
+    services: list[ServiceInfo] = Field(
+        default_factory=list, description="Infra stores + optional sidecars."
+    )
+    capabilities: CapabilityMatrix = Field(description="Available pipeline kinds per family.")
+
+
+__all__ = ["ServiceInfo", "CapabilityMatrix", "CapabilitiesResponse"]

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/models/collections.py

@@ -59,7 +59,7 @@ class CollectionModel(BaseModel):
         name (str): Unique human name.
         supported_formats (list[str]): Accepted upload extensions (e.g. pdf).
         max_file_size_bytes (int): Upload size ceiling, bytes.
-        job_timeout_seconds (float | None): Per-collection whole-ingest-job wall-clock budget,
+        job_timeout_seconds (float | None): Per-collection whole-ingest-job wall-clock job timeout,
             seconds. None = inherit the worker's global WORKER_JOB_TIMEOUT_SECONDS default.
         needs_reindex (bool): True when a config change requires reindexing.
         created_at (datetime | None): Creation timestamp.
@@ -82,7 +82,7 @@ class CollectionModel(BaseModel):
         default=None,
         gt=0,
         description=(
-            "Per-collection whole-ingest-job wall-clock budget, seconds. None = inherit the "
+            "Per-collection whole-ingest-job wall-clock job timeout, seconds. None = inherit the "
             "worker's global WORKER_JOB_TIMEOUT_SECONDS default."
         ),
     )
@@ -132,7 +132,7 @@ class CreateCollectionRequest(BaseModel):
         name (str): Unique human name.
         supported_formats (list[str]): Accepted upload extensions (e.g. pdf).
         max_file_size_bytes (int): Upload size ceiling, bytes.
-        job_timeout_seconds (float | None): Per-collection whole-ingest-job wall-clock budget,
+        job_timeout_seconds (float | None): Per-collection whole-ingest-job wall-clock job timeout,
             seconds. None = inherit the worker's global WORKER_JOB_TIMEOUT_SECONDS default.
         fields (list[FieldSpec]): The FULL schema, declared up front (vector space is fixed).
         pipeline (dict[str, Any] | None): The pipeline blob; omitted → the product default.
@@ -149,7 +149,7 @@ class CreateCollectionRequest(BaseModel):
         default=None,
         gt=0,
         description=(
-            "Per-collection whole-ingest-job wall-clock budget, seconds. None = inherit the "
+            "Per-collection whole-ingest-job wall-clock job timeout, seconds. None = inherit the "
             "worker's global WORKER_JOB_TIMEOUT_SECONDS default."
         ),
     )
@@ -186,7 +186,7 @@ class UpdateCollectionRequest(BaseModel):
         supported_formats (list[str] | None): New accepted upload extensions.
         max_file_size_bytes (int | None): New size ceiling, bytes.
         job_timeout_seconds (float | None): New per-collection whole-ingest-job wall-clock
-            budget, seconds. Omitted = leave the current value unchanged.
+            job timeout, seconds. Omitted = leave the current value unchanged.
         fields (list[FieldSpec] | None): The TARGET schema (diffed by field name).
         pipeline (dict[str, Any] | None): New pipeline blob (validated before storage).
         search (dict[str, Any] | None): New search graph blob ({} = stock default).
@@ -210,7 +210,7 @@ class UpdateCollectionRequest(BaseModel):
         default=None,
         gt=0,
         description=(
-            "New per-collection whole-ingest-job wall-clock budget, seconds. Omitted = leave the "
+            "New per-collection whole-ingest-job wall-clock job timeout, seconds. Omitted = leave the "
             "current value unchanged; a set value overrides the global WORKER_JOB_TIMEOUT_SECONDS."
         ),
     )

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/models/jobs.py

@@ -40,7 +40,10 @@ class JobStatus(BaseModel):
         failed_node_id (str | None): The deepest node that raised — only set on a failed job.
         failed_node_kind (str | None): That node's kind/family label — only set on a failed job.
         failed_item_index (int | None): The fan-out item index the failure sits in (None outside one).
-        error_type (str | None): The exception class name of the failure (e.g. "TimeoutError").
+        error_type (str | None): Structured cause of the failure — usually the raising exception's
+            class name (e.g. "TimeoutError"), plus the reaper's attributed "worker_killed" (process
+            lost — crash/OOM) and "job_timeout_exceeded" (a stage wedged past the job timeout on a
+            live worker).
     """
 
     job_id: str = Field(description="The job row's UUID.")
@@ -101,7 +104,13 @@ class JobStatus(BaseModel):
         default=None, description="Fan-out item index the failure sits in (None outside a fan-out)."
     )
     error_type: str | None = Field(
-        default=None, description="Exception class name of the failure (e.g. 'TimeoutError')."
+        default=None,
+        description=(
+            "Structured cause of the failure. Usually the raising exception's class name (e.g. "
+            "'TimeoutError'); the reaper also attributes 'worker_killed' (the worker process was "
+            "lost — crash/OOM-kill) and 'job_timeout_exceeded' (a stage wedged past the job's "
+            "timeout on a live worker). Set only on a failed job."
+        ),
     )
 
 

{docforge_sdk-0.16.0 → docforge_sdk-0.16.2}/docforge_sdk/resources/__init__.py

@@ -10,6 +10,9 @@ from .auth import AsyncAuth, SyncAuth
 # ------------------- Blobs resource ------------------- #
 from .blobs import AsyncBlobs, SyncBlobs
 
+# ------------------- Capabilities resource ------------------- #
+from .capabilities import AsyncCapabilities, SyncCapabilities
+
 # ------------------- Collections resource ------------------- #
 from .collections import AsyncCollections, SyncCollections
 
@@ -56,6 +59,8 @@ __all__ = [
     "SyncJobs",
     "AsyncBlobs",
     "SyncBlobs",
+    "AsyncCapabilities",
+    "SyncCapabilities",
     "AsyncPipelines",
     "SyncPipelines",
     "AsyncTransfers",

docforge_sdk-0.16.2/docforge_sdk/resources/capabilities.py

@@ -0,0 +1,54 @@
+# ====== Code Summary ======
+# The capabilities (deployment discovery) resource. Like /health, GET /capabilities lives at the BARE
+# origin (outside /api/v1), so both shells route through the transport's request_bare helper rather
+# than the versioned request. All URL logic lives once in the pure _CapabilitiesSpecs mixin; the
+# async/sync shells differ only by await.
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.capabilities import CapabilitiesResponse
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _CapabilitiesSpecs(_ResourceMixin):
+    """Pure ``RequestSpec`` builders for the capabilities endpoint — the single source of URL logic."""
+
+    _CAPABILITIES_PATH = "/capabilities"
+
+    def _describe_spec(self) -> RequestSpec:
+        """
+        Build the spec for the deployment discovery call.
+
+        Returns:
+            RequestSpec: A GET on the bare-root ``/capabilities`` route (outside ``/api/v1``).
+        """
+        return RequestSpec("GET", self._CAPABILITIES_PATH)
+
+
+class AsyncCapabilities(AsyncResource, _CapabilitiesSpecs):
+    """Asynchronous deployment discovery."""
+
+    async def capabilities(self) -> CapabilitiesResponse:
+        """
+        Discover what this deployment can do right now.
+
+        Returns:
+            CapabilitiesResponse: Version, auth state, GPU presence, the service list and the matrix.
+        """
+        return await self._transport.request_bare(self._describe_spec(), CapabilitiesResponse)
+
+
+class SyncCapabilities(SyncResource, _CapabilitiesSpecs):
+    """Synchronous deployment discovery."""
+
+    def capabilities(self) -> CapabilitiesResponse:
+        """
+        Discover what this deployment can do right now.
+
+        Returns:
+            CapabilitiesResponse: Version, auth state, GPU presence, the service list and the matrix.
+        """
+        return self._transport.request_bare(self._describe_spec(), CapabilitiesResponse)
+
+
+__all__ = ["AsyncCapabilities", "SyncCapabilities"]