docforge-sdk 0.1.2__tar.gz → 0.3.0__tar.gz

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/.gitignore

@@ -84,8 +84,16 @@ htmlcov/
 !src/docforge/tests/units/build/**
 src/docforge/app/frontend/scripts/node_modules/
 
+# UI-screenshot dev tooling — internal, kept private like .claude/ (Playwright-via-Docker recipe).
+src/docforge/app/frontend/scripts/ui-shot.mjs
+src/docforge/app/frontend/scripts/*.png
+src/docforge/app/frontend/UI-SCREENSHOT.md
+
 # Retired AI agent-memory snapshots — internal, not part of the public docs.
 docs/archive/agent-memory-legacy/
 
 # Root AI project instructions — local dev tooling, kept private (like .claude/).
 /CLAUDE.md
+
+# Docker Compose interpolation vars (copied from .env.example) — may hold local pins
+/.env

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docforge-sdk
-Version: 0.1.2
+Version: 0.3.0
 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
@@ -322,8 +322,7 @@ with Client("http://localhost:10040", api_token="df_...") as client:
 ```
 
 Key `SearchRequest` fields: `query` (required), `limit` (1–100, default 10), `filters`
-(`dict[str, Any]`), `search_in` (`list[SearchTarget]` to pick which vectors to query),
-`use_late_interaction`, `rescore_pool_size`.
+(`dict[str, Any]`), `search_in` (`list[SearchTarget]` to pick which vectors to query).
 
 ### Explore a document (pages, IR, chunks)
 

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/README.md

@@ -299,8 +299,7 @@ with Client("http://localhost:10040", api_token="df_...") as client:
 ```
 
 Key `SearchRequest` fields: `query` (required), `limit` (1–100, default 10), `filters`
-(`dict[str, Any]`), `search_in` (`list[SearchTarget]` to pick which vectors to query),
-`use_late_interaction`, `rescore_pool_size`.
+(`dict[str, Any]`), `search_in` (`list[SearchTarget]` to pick which vectors to query).
 
 ### Explore a document (pages, IR, chunks)
 

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/docforge_sdk/__init__.py

@@ -78,7 +78,7 @@ from .models.pipelines import (
 )
 
 # ------------------- Search models ------------------- #
-from .models.search import SearchHit, SearchRequest, SearchResponse, SearchTarget
+from .models.search import BlockLocation, SearchHit, SearchRequest, SearchResponse, SearchTarget
 
 # ------------------- Public API ------------------- #
 __all__ = [
@@ -131,6 +131,7 @@ __all__ = [
     # Search
     "SearchTarget",
     "SearchRequest",
+    "BlockLocation",
     "SearchHit",
     "SearchResponse",
     # Jobs

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/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.1.2"
+__version__ = "0.3.0"

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/docforge_sdk/models/__init__.py

@@ -62,7 +62,7 @@ from .pipelines import (
 )
 
 # ------------------- Search models ------------------- #
-from .search import SearchHit, SearchRequest, SearchResponse, SearchTarget
+from .search import BlockLocation, SearchHit, SearchRequest, SearchResponse, SearchTarget
 
 # ------------------- Public API ------------------- #
 __all__ = [
@@ -111,6 +111,7 @@ __all__ = [
     # Search
     "SearchTarget",
     "SearchRequest",
+    "BlockLocation",
     "SearchHit",
     "SearchResponse",
     # Jobs

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/docforge_sdk/models/collections.py

@@ -5,7 +5,7 @@
 
 # ====== Standard Library Imports ======
 from datetime import datetime
-from typing import Any
+from typing import Any, Literal
 
 # ====== Third-Party Library Imports ======
 from pydantic import BaseModel, Field
@@ -56,6 +56,8 @@ 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,
+            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.
         pipeline (dict[str, Any]): The ingestion pipeline blob (the graph).
@@ -67,6 +69,14 @@ class CollectionModel(BaseModel):
     name: str = Field(description="Unique human name.")
     supported_formats: list[str] = Field(description="Accepted upload extensions (e.g. pdf).")
     max_file_size_bytes: int = Field(description="Upload size ceiling, bytes.")
+    job_timeout_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Per-collection whole-ingest-job wall-clock budget, seconds. None = inherit the "
+            "worker's global WORKER_JOB_TIMEOUT_SECONDS default."
+        ),
+    )
     needs_reindex: bool = Field(description="True when a config change requires reindexing.")
     created_at: datetime | None = Field(default=None, description="Creation timestamp.")
     pipeline: dict[str, Any] = Field(description="The ingestion pipeline blob (the graph).")
@@ -84,6 +94,8 @@ 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,
+            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.
     """
@@ -91,6 +103,14 @@ class CreateCollectionRequest(BaseModel):
     name: str = Field(description="Unique human name.")
     supported_formats: list[str] = Field(description="Accepted upload extensions (e.g. pdf).")
     max_file_size_bytes: int = Field(description="Upload size ceiling, bytes.")
+    job_timeout_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Per-collection whole-ingest-job wall-clock budget, seconds. None = inherit the "
+            "worker's global WORKER_JOB_TIMEOUT_SECONDS default."
+        ),
+    )
     fields: list[FieldSpec] = Field(
         default_factory=list,
         description="The FULL schema, declared up front (vector space is fixed at creation).",
@@ -99,6 +119,11 @@ class CreateCollectionRequest(BaseModel):
         default=None,
         description="The pipeline blob; omitted → the product default (all stages wired).",
     )
+    preset: Literal["standard", "light"] | None = Field(
+        default=None,
+        description="Stock-blob selector (ignored when pipeline is set); 'light' = fast, "
+        "enrichment-free core.",
+    )
 
 
 class UpdateCollectionRequest(BaseModel):
@@ -109,6 +134,8 @@ class UpdateCollectionRequest(BaseModel):
         name (str | None): New unique name.
         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.
         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).
@@ -120,6 +147,14 @@ class UpdateCollectionRequest(BaseModel):
         default=None, description="New accepted upload extensions."
     )
     max_file_size_bytes: int | None = Field(default=None, description="New size ceiling, bytes.")
+    job_timeout_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "New per-collection whole-ingest-job wall-clock budget, seconds. Omitted = leave the "
+            "current value unchanged; a set value overrides the global WORKER_JOB_TIMEOUT_SECONDS."
+        ),
+    )
     fields: list[FieldSpec] | None = Field(
         default=None,
         description="The TARGET schema (diffed by field name; omitted fields are removed).",

{docforge_sdk-0.1.2 → docforge_sdk-0.3.0}/docforge_sdk/models/explorer.py

@@ -148,6 +148,8 @@ class ChunkInfo(BaseModel):
         parent_id (str | None): Parent chunk (hierarchical chunking).
         block_ids (list[str]): Composing IR block ids, in assembly order.
         metadata (list[MetadataValue]): Per-chunk generated metadata values.
+        heading_path (list[str]): The chunk's section breadcrumb (outer→inner headings).
+        page (int | None): Page of the chunk's primary block; None when it has no located block.
     """
 
     id: str = Field(description="The chunk UUID (doubles as the Qdrant point id).")
@@ -165,6 +167,14 @@ class ChunkInfo(BaseModel):
     metadata: list[MetadataValue] = Field(
         default_factory=list, description="Per-chunk generated metadata values."
     )
+    heading_path: list[str] = Field(
+        default_factory=list,
+        description="The chunk's section breadcrumb (outer→inner headings); [] when none.",
+    )
+    page: int | None = Field(
+        default=None,
+        description="Page of the chunk's primary block; None when it has no located block.",
+    )
 
 
 class ChunkEnabledPatch(BaseModel):

docforge_sdk-0.3.0/docforge_sdk/models/jobs.py

@@ -0,0 +1,165 @@
+# ====== 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).
+        items_done (int | None): Child items finished in the current fan-out stage (None off it).
+        items_total (int | None): The current fan-out stage's width (None when not in a fan-out).
+        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").
+    """
+
+    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.")
+    updated_at: datetime = Field(description="Last progress/lifecycle write (freezes on a wedge).")
+    stalled: bool = Field(
+        description="A RUNNING job idle past the stall threshold — an early wedge warning."
+    )
+    total_prompt_tokens: int = Field(
+        description="Prompt tokens billed across this job's paid text-gen calls."
+    )
+    total_completion_tokens: int = Field(
+        description="Completion tokens billed across this job's paid text-gen calls."
+    )
+    cost_usd: float = Field(
+        description="USD cost of this job's paid calls (0 when nothing priceable)."
+    )
+    items_done: int | None = Field(
+        default=None, description="Child items finished in the current fan-out stage (None off it)."
+    )
+    items_total: int | None = Field(
+        default=None, description="The current fan-out stage's width (None when not in a fan-out)."
+    )
+    failed_node_id: str | None = Field(
+        default=None, description="Deepest node that raised — only set on a failed job."
+    )
+    failed_node_kind: str | None = Field(
+        default=None, description="That node's kind/family label — only set on a failed job."
+    )
+    failed_item_index: int | None = Field(
+        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')."
+    )
+
+
+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.
+        node_kind (str | None): The stage's structural kind (action/group/foreach) or the node's
+            concrete kind — None for rows written before this column landed.
+        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.")
+    node_kind: str | None = Field(
+        default=None,
+        description="The stage's structural kind (action/group/foreach) or the node's concrete "
+        "kind — None for rows written before this column landed.",
+    )
+    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.")
+    prompt_tokens: int | None = Field(
+        default=None, description="Prompt tokens billed by this stage; null when it made none."
+    )
+    completion_tokens: int | None = Field(
+        default=None, description="Completion tokens billed by this stage; null when none."
+    )
+    cost_usd: float | None = Field(
+        default=None, description="USD cost of this stage; null when no usage or unknown price."
+    )
+
+
+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 — its heartbeat-derived liveness plus any RUNNING jobs it owns.
+
+    Attributes:
+        worker_id (str): The worker's stable id (its hostname).
+        alive (bool): Its heartbeat is fresher than the liveness threshold.
+        busy (bool): It currently owns at least one RUNNING job.
+        last_seen (datetime | None): Its last heartbeat tick (None when no heartbeat row exists).
+        started_at (datetime | None): When the worker process registered (None when no heartbeat).
+        jobs (list[JobStatus]): Its running jobs, live.
+    """
+
+    worker_id: str = Field(description="The worker's stable id (its hostname).")
+    alive: bool = Field(description="Heartbeat fresher than the liveness threshold.")
+    busy: bool = Field(description="Owns at least one RUNNING job right now.")
+    last_seen: datetime | None = Field(
+        default=None, description="Last heartbeat tick (None when the worker has no heartbeat row)."
+    )
+    started_at: datetime | None = Field(
+        default=None, description="When the worker process registered (None when no heartbeat)."
+    )
+    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-0.1.2 → docforge_sdk-0.3.0}/docforge_sdk/models/search.py

@@ -41,8 +41,6 @@ class SearchRequest(BaseModel):
         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.")
@@ -56,15 +54,25 @@ class SearchRequest(BaseModel):
         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.",
+
+
+class BlockLocation(BaseModel):
+    """
+    One source block's location on the page — enough for a UI to draw a box over the hit.
+
+    Attributes:
+        page (int | None): The page the block sits on. None for a page-less document (no page
+            render) — distinct from a genuine 0-based page index 0.
+        bbox (list[float]): The block's bounding box ``[x0, y0, x1, y1]``, NORMALISED to [0, 1] —
+            multiply each component by the page image's width/height to draw it in pixels.
+    """
+
+    page: int | None = Field(
+        description="The page the block sits on; None for a page-less document (no page render)."
     )
-    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.",
+    bbox: list[float] = Field(
+        description="Bounding box [x0, y0, x1, y1] NORMALISED to [0, 1] — multiply by the page "
+        "image width/height to draw it in pixels.",
     )
 
 
@@ -79,14 +87,53 @@ class SearchHit(BaseModel):
         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.
+        block_ids (list[str]): The IR block ids the chunk was assembled from (assembly order).
+        page (int | None): The page of the chunk's primary (leading) block — draw the box here.
+        bbox (list[float] | None): The primary block's NORMALISED [0, 1] bounding box.
+        block_locations (list[BlockLocation]): Every source block's page + bbox (draw them all).
     """
 
     chunk_id: str = Field(description="The chunk's UUID.")
     document_id: str = Field(description="The owning document's UUID.")
+    filename: str | None = Field(
+        default=None, description="The source document's filename — the hit's human identity."
+    )
+    document_title: str | None = Field(
+        default=None, description="The source document's title (empty parsed titles → null)."
+    )
+    heading_path: list[str] = Field(
+        default_factory=list,
+        description="The chunk's section ancestry, top-down (e.g. ['Article 7 — Audit rights']) — "
+        "so a hit self-cites the section/clause it came from. Empty when the chunk sits under no "
+        "section.",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="The document's filterable metadata (field → value) — so a hit self-cites "
+        "without a second GET /documents/{id}.",
+    )
     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.")
+    block_ids: list[str] = Field(
+        default_factory=list,
+        description="The IR block ids the chunk was assembled from, in assembly order.",
+    )
+    page: int | None = Field(
+        default=None,
+        description="The page of the chunk's primary (leading) block — where to draw the box. "
+        "None when the chunk carries no block location.",
+    )
+    bbox: list[float] | None = Field(
+        default=None,
+        description="The primary block's bounding box [x0, y0, x1, y1], NORMALISED to [0, 1] — "
+        "multiply by the page image width/height to draw it. None when unlocated.",
+    )
+    block_locations: list[BlockLocation] = Field(
+        default_factory=list,
+        description="Every source block's page + NORMALISED bbox — draw one box per block.",
+    )
 
 
 class SearchResponse(BaseModel):
@@ -103,8 +150,8 @@ class SearchResponse(BaseModel):
     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.",
+        description="Non-fatal diagnostics about how the search ran. None when empty.",
     )
 
 
-__all__ = ["SearchTarget", "SearchRequest", "SearchHit", "SearchResponse"]
+__all__ = ["SearchTarget", "SearchRequest", "BlockLocation", "SearchHit", "SearchResponse"]