docforge-sdk 0.1.0__py3-none-any.whl

docforge_sdk/models/jobs.py

@@ -0,0 +1,100 @@
+# ====== Code Summary ======
+# Response models for the jobs resource, mirrored field-for-field from the DocForge backend router
+# models: the live ingestion status, one node of the execution trace, the full trace, and the live
+# per-worker activity view.
+
+# ====== Standard Library Imports ======
+from datetime import datetime
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class JobStatus(BaseModel):
+    """
+    One ingestion job's live state — written by the worker, only read here.
+
+    Attributes:
+        job_id (str): The job row's UUID.
+        document_id (str): The document being ingested.
+        collection_id (str): Its collection.
+        status (str): queued / running / done / failed.
+        progress (int): 0–100 (completed pipeline nodes over total).
+        current_stage (str | None): The node currently (or last) executed.
+        error (str | None): The failure, verbatim — only set when status is failed.
+        attempt (int): arq retry attempt (1 = first run).
+        started_at (datetime | None): When the worker picked it up.
+        finished_at (datetime | None): When it ended (done or failed).
+    """
+
+    job_id: str = Field(description="The job row's UUID.")
+    document_id: str = Field(description="The document being ingested.")
+    collection_id: str = Field(description="Its collection.")
+    status: str = Field(description="queued / running / done / failed.")
+    progress: int = Field(description="0-100, completed pipeline nodes over total.")
+    current_stage: str | None = Field(default=None, description="Node currently/last executed.")
+    error: str | None = Field(default=None, description="Failure detail when status=failed.")
+    attempt: int = Field(description="arq retry attempt (1 = first run).")
+    started_at: datetime | None = Field(default=None, description="Picked up by the worker at.")
+    finished_at: datetime | None = Field(default=None, description="Ended (done or failed) at.")
+
+
+class JobEvent(BaseModel):
+    """
+    One node of the job's execution trace — written by the worker at each stage end.
+
+    Attributes:
+        stage (str): The pipeline node id.
+        status (str): success / failed / skipped.
+        started_at (datetime | None): Node start.
+        finished_at (datetime | None): Node end.
+        detail (str | None): Duration, or the error when failed.
+    """
+
+    stage: str = Field(description="The pipeline node id.")
+    status: str = Field(description="success / failed / skipped.")
+    started_at: datetime | None = Field(default=None, description="Node start.")
+    finished_at: datetime | None = Field(default=None, description="Node end.")
+    detail: str | None = Field(default=None, description="Duration, or the error when failed.")
+
+
+class JobTrace(BaseModel):
+    """
+    A job's full per-node trace, in execution order.
+
+    Attributes:
+        job_id (str): The traced job.
+        events (list[JobEvent]): One entry per stage run.
+    """
+
+    job_id: str = Field(description="The traced job.")
+    events: list[JobEvent] = Field(default_factory=list, description="One entry per stage run.")
+
+
+class WorkerActivity(BaseModel):
+    """
+    One worker's live activity — derived from its RUNNING jobs (no extra heartbeat).
+
+    Attributes:
+        worker_id (str): The worker's hostname.
+        jobs (list[JobStatus]): Its running jobs, live.
+    """
+
+    worker_id: str = Field(description="The worker's hostname.")
+    jobs: list[JobStatus] = Field(default_factory=list, description="Its running jobs, live.")
+
+
+class WorkersLive(BaseModel):
+    """
+    Everything running right now, grouped by worker — the monitoring view.
+
+    Attributes:
+        workers (list[WorkerActivity]): One entry per active worker.
+    """
+
+    workers: list[WorkerActivity] = Field(
+        default_factory=list, description="One entry per active worker."
+    )
+
+
+__all__ = ["JobStatus", "JobEvent", "JobTrace", "WorkerActivity", "WorkersLive"]

docforge_sdk/models/pipelines.py

@@ -0,0 +1,182 @@
+# ====== Code Summary ======
+# Response models for the pipeline design surface, mirrored field-for-field from the DocForge backend
+# router models. The graph JSON is OPAQUE to the SDK: every payload the engine owns (blob, palette,
+# explored tree, issues, stages) is typed as ``dict``/``list[dict]``; only the stable ENVELOPE fields
+# (valid / build_error / notices / the surface URLs) carry precise types.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class PipelineSurface(BaseModel):
+    """
+    One available pipeline design surface — the discovery unit a zero-hardcode UI starts from.
+
+    Attributes:
+        key (str): Stable pipeline identifier (e.g. ``"ingest"``).
+        title (str): Human label.
+        description (str): What this pipeline does.
+        design_url (str): GET — the lean design payload.
+        inspect_url (str): POST — blob in, validity + issues + described tree out.
+        edit_url (str): POST — apply graph operations server-side.
+        stages_view_url (str | None): POST — the stage view of a blob (None when unsupported).
+        stages_apply_url (str | None): POST — compile a stage action (None when unsupported).
+    """
+
+    key: str = Field(description="Stable pipeline identifier (e.g. 'ingest').")
+    title: str = Field(description="Human label.")
+    description: str = Field(description="What this pipeline does.")
+    design_url: str = Field(description="GET — the lean design payload.")
+    inspect_url: str = Field(description="POST — validity + issues + described tree.")
+    edit_url: str = Field(description="POST — apply graph operations server-side.")
+    stages_view_url: str | None = Field(
+        default=None, description="POST — the stage view of a blob (None when unsupported)."
+    )
+    stages_apply_url: str | None = Field(
+        default=None, description="POST — compile a stage action (None when unsupported)."
+    )
+
+
+class PipelineIndexResponse(BaseModel):
+    """
+    The pipelines the backend serves — the UI's single bootstrap call.
+
+    Attributes:
+        pipelines (list[PipelineSurface]): One entry per available design surface.
+    """
+
+    pipelines: list[PipelineSurface] = Field(
+        default_factory=list, description="One entry per available design surface."
+    )
+
+
+class PipelineDesignResponse(BaseModel):
+    """
+    Everything the product UI needs to open the design surface in one call.
+
+    Attributes:
+        palette (dict[str, Any]): Every available block (per family); OPAQUE engine JSON.
+        blob (dict[str, Any]): The editable pipeline graph; OPAQUE engine JSON.
+        issues (list[dict[str, Any]]): Validation problems of the blob (empty when healthy).
+    """
+
+    palette: dict[str, Any] = Field(description="Available blocks per family (opaque engine JSON).")
+    blob: dict[str, Any] = Field(description="The editable pipeline graph (opaque engine JSON).")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Validation problems of the blob (opaque; empty = healthy).",
+    )
+
+
+class InspectResponse(BaseModel):
+    """
+    The described mirror of an edited pipeline.
+
+    Attributes:
+        valid (bool): True when the graph built and has zero validation issues.
+        issues (list[dict[str, Any]]): Every problem found (opaque engine JSON).
+        explored (dict[str, Any] | None): The described tree; None when the build failed.
+        build_error (str | None): Precise builder failure (unknown kind, invalid config…).
+    """
+
+    valid: bool = Field(description="True when the graph built and has zero validation issues.")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list, description="Every problem found (opaque engine JSON)."
+    )
+    explored: dict[str, Any] | None = Field(
+        default=None, description="The described tree (opaque); None when the build failed."
+    )
+    build_error: str | None = Field(
+        default=None, description="Precise builder failure (unknown kind, invalid config…)."
+    )
+
+
+class EditResponse(BaseModel):
+    """
+    The result of applying edit operations, then building + validating + describing the result.
+
+    Attributes:
+        blob (dict[str, Any]): The edited blob (or the original when an operation was impossible).
+        valid (bool): True when the edited blob built and has zero validation issues.
+        issues (list[dict[str, Any]]): Every validation problem found (opaque engine JSON).
+        explored (dict[str, Any] | None): The described tree; None when apply or build failed.
+        edit_error (str | None): Set when an operation was impossible or the result was unbuildable.
+    """
+
+    blob: dict[str, Any] = Field(description="The edited blob (opaque engine JSON).")
+    valid: bool = Field(description="True when the edited blob built and has zero issues.")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list, description="Every validation problem found (opaque engine JSON)."
+    )
+    explored: dict[str, Any] | None = Field(
+        default=None, description="The described tree (opaque); None when apply/build failed."
+    )
+    edit_error: str | None = Field(
+        default=None, description="Set when an operation was impossible or the result unbuildable."
+    )
+
+
+class StageViewResponse(BaseModel):
+    """
+    The stage view of a blob — the full ordered skeleton PLUS its validity verdict.
+
+    Attributes:
+        stages (list[dict[str, Any]]): The canonical stages in run order (opaque engine JSON).
+        valid (bool): True when the blob built and has zero validation issues.
+        issues (list[dict[str, Any]]): Every validation problem found (opaque engine JSON).
+        build_error (str | None): Precise builder failure when the blob cannot even be built.
+    """
+
+    stages: list[dict[str, Any]] = Field(
+        description="The canonical stages in run order (opaque engine JSON)."
+    )
+    valid: bool = Field(description="True when the blob built and has zero validation issues.")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list, description="Every validation problem found (opaque engine JSON)."
+    )
+    build_error: str | None = Field(
+        default=None, description="Precise builder failure when the blob cannot even be built."
+    )
+
+
+class StageApplyResponse(BaseModel):
+    """
+    The result of compiling a stage action: the new blob, its stage view, validity and notices.
+
+    Attributes:
+        blob (dict[str, Any]): The recompiled blob (always buildable; opaque engine JSON).
+        stages (list[dict[str, Any]]): The stage view of the recompiled blob, in run order.
+        valid (bool): True when the blob built and has zero validation issues.
+        issues (list[dict[str, Any]]): Validation problems — expected and shown, never fatal.
+        notices (list[str]): What the compiler did beyond the literal action.
+        build_error (str | None): Set when the recompiled blob cannot build — fix-in-place data.
+    """
+
+    blob: dict[str, Any] = Field(description="The recompiled blob (opaque engine JSON).")
+    stages: list[dict[str, Any]] = Field(
+        description="The stage view of the recompiled blob, in run order (opaque engine JSON)."
+    )
+    valid: bool = Field(description="True when the blob built and has zero validation issues.")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list, description="Validation problems — expected and shown, never fatal."
+    )
+    notices: list[str] = Field(
+        default_factory=list, description="What the compiler did beyond the literal action."
+    )
+    build_error: str | None = Field(
+        default=None, description="Set when the recompiled blob cannot build — fix-in-place data."
+    )
+
+
+__all__ = [
+    "PipelineSurface",
+    "PipelineIndexResponse",
+    "PipelineDesignResponse",
+    "InspectResponse",
+    "EditResponse",
+    "StageViewResponse",
+    "StageApplyResponse",
+]

docforge_sdk/models/search.py

@@ -0,0 +1,110 @@
+# ====== Code Summary ======
+# Request/response models for the search resource, mirrored field-for-field from the DocForge backend
+# router models. ``filters`` and ``debug_info`` are opaque, server-shaped JSON and are typed as dicts.
+
+# ====== Standard Library Imports ======
+from typing import Any
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class SearchTarget(BaseModel):
+    """
+    One field to search and the modalities to search it on.
+
+    Attributes:
+        field (str): The field to search — ``"content"`` (the chunk body) or a metadata field name.
+        semantic (bool): Query the field's dense vector (semantic similarity).
+        lexical (bool): Query the field's sparse BM25 vector (lexical match).
+    """
+
+    field: str = Field(
+        default="content",
+        min_length=1,
+        description="Field to search — 'content' (chunk body) or a metadata field name.",
+    )
+    semantic: bool = Field(
+        default=False, description="Query the field's dense vector (semantic similarity)."
+    )
+    lexical: bool = Field(
+        default=False, description="Query the field's sparse BM25 vector (lexical match)."
+    )
+
+
+class SearchRequest(BaseModel):
+    """
+    A hybrid search over one collection.
+
+    Attributes:
+        query (str): The natural-language query, embedded with the collection's own embedder.
+        limit (int): Number of fused results to return.
+        filters (dict[str, Any] | None): Exact/any-of constraints on the FILTERABLE fields.
+        search_in (list[SearchTarget] | None): Fields × modalities to search. None → content on both.
+        use_late_interaction (bool | None): Opt into the ColBERT re-score. None → off for this query.
+        rescore_pool_size (int | None): Size of the fused candidate pool the ColBERT stage re-scores.
+    """
+
+    query: str = Field(min_length=1, description="The natural-language query to search for.")
+    limit: int = Field(default=10, ge=1, le=100, description="Number of fused results.")
+    filters: dict[str, Any] | None = Field(
+        default=None,
+        description="Constraints on the FILTERABLE metadata fields (field → value or [values]).",
+    )
+    search_in: list[SearchTarget] | None = Field(
+        default=None,
+        description="Fields × modalities to search (content and/or metadata). None → content on "
+        "both semantic and lexical (the unchanged default).",
+    )
+    use_late_interaction: bool | None = Field(
+        default=None,
+        description="Opt into the ColBERT late-interaction re-score for this query. None → off.",
+    )
+    rescore_pool_size: int | None = Field(
+        default=None,
+        ge=1,
+        le=1000,
+        description="Fused candidate pool size the ColBERT stage re-scores. None → node/store default.",
+    )
+
+
+class SearchHit(BaseModel):
+    """
+    One ranked search result — the flat view of a hydrated chunk hit.
+
+    Attributes:
+        chunk_id (str): The chunk's UUID (doubles as its Qdrant point id).
+        document_id (str): The document the chunk belongs to.
+        score (float): The fused RRF score (higher is better).
+        text (str): The chunk's enriched text.
+        chunk_index (int): The chunk's ordinal within its document.
+        token_count (int): The chunk's token count.
+    """
+
+    chunk_id: str = Field(description="The chunk's UUID.")
+    document_id: str = Field(description="The owning document's UUID.")
+    score: float = Field(description="Fused RRF score (higher is better).")
+    text: str = Field(description="The chunk's enriched text.")
+    chunk_index: int = Field(description="Ordinal within the document.")
+    token_count: int = Field(description="Token count of the chunk.")
+
+
+class SearchResponse(BaseModel):
+    """
+    The result of a hybrid search — the echoed query and its ranked hits.
+
+    Attributes:
+        query (str): The query that was searched (echoed for the client).
+        hits (list[SearchHit]): The hydrated hits, best first.
+        debug_info (dict[str, Any] | None): Non-fatal diagnostics; None when there is nothing to report.
+    """
+
+    query: str = Field(description="The query that was searched.")
+    hits: list[SearchHit] = Field(default_factory=list, description="Ranked hits, best first.")
+    debug_info: dict[str, Any] | None = Field(
+        default=None,
+        description="Non-fatal diagnostics (e.g. late_interaction_skipped). None when empty.",
+    )
+
+
+__all__ = ["SearchTarget", "SearchRequest", "SearchHit", "SearchResponse"]

docforge_sdk/resources/__init__.py

@@ -0,0 +1,53 @@
+# ------------------- Bases ------------------- #
+from ._base import AsyncResource, SyncResource
+
+# ------------------- Auth resource ------------------- #
+from .auth import AsyncAuth, SyncAuth
+
+# ------------------- Blobs resource ------------------- #
+from .blobs import AsyncBlobs, SyncBlobs
+
+# ------------------- Collections resource ------------------- #
+from .collections import AsyncCollections, SyncCollections
+
+# ------------------- Documents resource ------------------- #
+from .documents import AsyncDocuments, SyncDocuments
+
+# ------------------- Explorer resource ------------------- #
+from .explorer import AsyncExplorer, SyncExplorer
+
+# ------------------- Health resource ------------------- #
+from .health import AsyncHealth, SyncHealth
+
+# ------------------- Jobs resource ------------------- #
+from .jobs import AsyncJobs, SyncJobs
+
+# ------------------- Pipelines resource ------------------- #
+from .pipelines import AsyncPipelines, SyncPipelines
+
+# ------------------- Search resource ------------------- #
+from .search import AsyncSearch, SyncSearch
+
+# ------------------- Public API ------------------- #
+__all__ = [
+    "AsyncResource",
+    "SyncResource",
+    "AsyncAuth",
+    "SyncAuth",
+    "AsyncHealth",
+    "SyncHealth",
+    "AsyncCollections",
+    "SyncCollections",
+    "AsyncDocuments",
+    "SyncDocuments",
+    "AsyncExplorer",
+    "SyncExplorer",
+    "AsyncSearch",
+    "SyncSearch",
+    "AsyncJobs",
+    "SyncJobs",
+    "AsyncBlobs",
+    "SyncBlobs",
+    "AsyncPipelines",
+    "SyncPipelines",
+]

docforge_sdk/resources/_base.py

@@ -0,0 +1,46 @@
+# ====== Code Summary ======
+# Base classes for resource groups. A resource holds only a reference to its transport; the async and
+# sync bases exist so a resource can bind to the matching transport type while sharing the pure
+# spec-building logic contributed by per-resource mixins (e.g. _AuthSpecs).
+
+# ====== Local Project Imports ======
+from .._transport_async import AsyncTransport
+from .._transport_sync import SyncTransport
+
+
+class _ResourceMixin:
+    """
+    Marker base for the pure spec-builder mixins.
+
+    Spec-builder mixins carry no state and no I/O — only methods returning ``RequestSpec`` — so the
+    async and sync resources can share them verbatim.
+    """
+
+
+class AsyncResource:
+    """Base for asynchronous resource groups; holds the async transport."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        """
+        Bind the resource to its async transport.
+
+        Args:
+            transport (AsyncTransport): The transport used to execute this resource's requests.
+        """
+        self._transport = transport
+
+
+class SyncResource:
+    """Base for synchronous resource groups; holds the sync transport."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        """
+        Bind the resource to its sync transport.
+
+        Args:
+            transport (SyncTransport): The transport used to execute this resource's requests.
+        """
+        self._transport = transport
+
+
+__all__ = ["_ResourceMixin", "AsyncResource", "SyncResource"]