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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.3.0
+Version: 0.7.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
@@ -189,6 +189,7 @@ are identical.
 | `create(CreateCollectionRequest)` | `CollectionModel` | Create a collection (contract). |
 | `update(collection_id, UpdateCollectionRequest)` | `CollectionModel` | Patch name / formats / fields / pipelines. |
 | `delete(collection_id)` | `None` | Delete a collection. |
+| `storage(collection_id)` | `CollectionStorageResponse` | Material storage footprint per store (S3 exact, Postgres/Qdrant estimated) + per-document breakdown. |
 
 ### `documents`
 | Method | Returns | Purpose |
@@ -220,6 +221,7 @@ are identical.
 | `get(job_id)` | `JobStatus` | One job's status + progress. |
 | `get_events(job_id)` | `JobTrace` | Per-stage event trace. |
 | `live_workers()` | `WorkersLive` | Currently active workers. |
+| `cancel(job_id, force=False)` | `CancelResult` | Stop a job — cooperative by default, immediate with `force=True`. |
 
 ### `blobs`
 | Method | Returns | Purpose |
@@ -271,6 +273,12 @@ with Client("http://localhost:10040", api_token="df_...") as client:
     print(collection.id)
 ```
 
+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
+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).
+
 ### Upload a document and wait for ingestion
 
 `upload` returns immediately with a `job_id`; ingestion runs asynchronously on the worker. Poll the
@@ -338,6 +346,20 @@ with Client("http://localhost:10040", api_token="df_...") as client:
     client.explorer.set_chunk_enabled(chunks[0].chunk_id, enabled=False)
 ```
 
+### Measure a collection's storage footprint
+
+`storage` reports the material footprint per store — S3 bytes are exact (deduped), Postgres/Qdrant
+bytes are estimates (each section flags this via its own `estimated`) — plus a per-document
+breakdown sorted heaviest first.
+
+```python
+with Client("http://localhost:10040", api_token="df_...") as client:
+    footprint = client.collections.storage(collection_id)
+    print(footprint.grand_total_bytes, footprint.s3.physical_unique_bytes)
+    for doc in footprint.documents[:5]:
+        print(doc.filename, doc.total_bytes)
+```
+
 ### Manage API keys
 
 Mint a scoped, expiring key (the plaintext is shown **once**, on creation):
@@ -424,6 +446,7 @@ from docforge_sdk import (
     UpdateCollectionRequest,
     FieldSpec,
     FieldType,
+    CollectionStorageResponse,
     # documents / explorer
     UploadAccepted,
     DocumentDetail,
@@ -465,7 +488,7 @@ server's OpenAPI on every change, so a published version is coherent with the AP
 version in production:
 
 ```bash
-pip install "docforge-sdk==0.1.0"
+pip install "docforge-sdk==0.3.0"
 ```
 
 ## License

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

@@ -166,6 +166,7 @@ are identical.
 | `create(CreateCollectionRequest)` | `CollectionModel` | Create a collection (contract). |
 | `update(collection_id, UpdateCollectionRequest)` | `CollectionModel` | Patch name / formats / fields / pipelines. |
 | `delete(collection_id)` | `None` | Delete a collection. |
+| `storage(collection_id)` | `CollectionStorageResponse` | Material storage footprint per store (S3 exact, Postgres/Qdrant estimated) + per-document breakdown. |
 
 ### `documents`
 | Method | Returns | Purpose |
@@ -197,6 +198,7 @@ are identical.
 | `get(job_id)` | `JobStatus` | One job's status + progress. |
 | `get_events(job_id)` | `JobTrace` | Per-stage event trace. |
 | `live_workers()` | `WorkersLive` | Currently active workers. |
+| `cancel(job_id, force=False)` | `CancelResult` | Stop a job — cooperative by default, immediate with `force=True`. |
 
 ### `blobs`
 | Method | Returns | Purpose |
@@ -248,6 +250,12 @@ with Client("http://localhost:10040", api_token="df_...") as client:
     print(collection.id)
 ```
 
+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
+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).
+
 ### Upload a document and wait for ingestion
 
 `upload` returns immediately with a `job_id`; ingestion runs asynchronously on the worker. Poll the
@@ -315,6 +323,20 @@ with Client("http://localhost:10040", api_token="df_...") as client:
     client.explorer.set_chunk_enabled(chunks[0].chunk_id, enabled=False)
 ```
 
+### Measure a collection's storage footprint
+
+`storage` reports the material footprint per store — S3 bytes are exact (deduped), Postgres/Qdrant
+bytes are estimates (each section flags this via its own `estimated`) — plus a per-document
+breakdown sorted heaviest first.
+
+```python
+with Client("http://localhost:10040", api_token="df_...") as client:
+    footprint = client.collections.storage(collection_id)
+    print(footprint.grand_total_bytes, footprint.s3.physical_unique_bytes)
+    for doc in footprint.documents[:5]:
+        print(doc.filename, doc.total_bytes)
+```
+
 ### Manage API keys
 
 Mint a scoped, expiring key (the plaintext is shown **once**, on creation):
@@ -401,6 +423,7 @@ from docforge_sdk import (
     UpdateCollectionRequest,
     FieldSpec,
     FieldType,
+    CollectionStorageResponse,
     # documents / explorer
     UploadAccepted,
     DocumentDetail,
@@ -442,7 +465,7 @@ server's OpenAPI on every change, so a published version is coherent with the AP
 version in production:
 
 ```bash
-pip install "docforge-sdk==0.1.0"
+pip install "docforge-sdk==0.3.0"
 ```
 
 ## License

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

@@ -64,7 +64,7 @@ from .models.health import HealthStatus
 from .models.ir import DocumentIRModel, IRBlock, IREnrichment, IRFigure, IRTable
 
 # ------------------- Jobs models ------------------- #
-from .models.jobs import JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
+from .models.jobs import CancelResult, JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
 
 # ------------------- Pipelines models ------------------- #
 from .models.pipelines import (
@@ -80,6 +80,15 @@ from .models.pipelines import (
 # ------------------- Search models ------------------- #
 from .models.search import BlockLocation, SearchHit, SearchRequest, SearchResponse, SearchTarget
 
+# ------------------- Storage models ------------------- #
+from .models.storage import (
+    CollectionStorageResponse,
+    DocumentStorageModel,
+    PostgresFootprintModel,
+    QdrantFootprintModel,
+    S3FootprintModel,
+)
+
 # ------------------- Public API ------------------- #
 __all__ = [
     "__version__",
@@ -140,6 +149,7 @@ __all__ = [
     "JobTrace",
     "WorkerActivity",
     "WorkersLive",
+    "CancelResult",
     # Blobs
     "BlobContent",
     # Pipelines
@@ -150,6 +160,12 @@ __all__ = [
     "EditResponse",
     "StageViewResponse",
     "StageApplyResponse",
+    # Storage
+    "S3FootprintModel",
+    "PostgresFootprintModel",
+    "QdrantFootprintModel",
+    "DocumentStorageModel",
+    "CollectionStorageResponse",
     # Exceptions
     "DocForgeError",
     "APIConnectionError",

{docforge_sdk-0.3.0 → docforge_sdk-0.7.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.3.0"
+__version__ = "0.7.0"

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

@@ -48,7 +48,7 @@ from .health import HealthStatus
 from .ir import DocumentIRModel, IRBlock, IREnrichment, IRFigure, IRTable
 
 # ------------------- Jobs models ------------------- #
-from .jobs import JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
+from .jobs import CancelResult, JobEvent, JobStatus, JobTrace, WorkerActivity, WorkersLive
 
 # ------------------- Pipelines models ------------------- #
 from .pipelines import (
@@ -64,6 +64,15 @@ from .pipelines import (
 # ------------------- Search models ------------------- #
 from .search import BlockLocation, SearchHit, SearchRequest, SearchResponse, SearchTarget
 
+# ------------------- Storage models ------------------- #
+from .storage import (
+    CollectionStorageResponse,
+    DocumentStorageModel,
+    PostgresFootprintModel,
+    QdrantFootprintModel,
+    S3FootprintModel,
+)
+
 # ------------------- Public API ------------------- #
 __all__ = [
     # Shared vocabulary
@@ -120,6 +129,7 @@ __all__ = [
     "JobTrace",
     "WorkerActivity",
     "WorkersLive",
+    "CancelResult",
     # Blobs
     "BlobContent",
     # Pipelines
@@ -130,4 +140,10 @@ __all__ = [
     "EditResponse",
     "StageViewResponse",
     "StageApplyResponse",
+    # Storage
+    "S3FootprintModel",
+    "PostgresFootprintModel",
+    "QdrantFootprintModel",
+    "DocumentStorageModel",
+    "CollectionStorageResponse",
 ]

{docforge_sdk-0.3.0 → docforge_sdk-0.7.0}/docforge_sdk/models/jobs.py

@@ -17,8 +17,14 @@ class JobStatus(BaseModel):
     Attributes:
         job_id (str): The job row's UUID.
         document_id (str): The document being ingested.
+        document_filename (str | None): The document's filename, joined at read (None if the
+            document is gone).
         collection_id (str): Its collection.
-        status (str): queued / running / done / failed.
+        collection_name (str | None): The collection's name, joined at read (None if the
+            collection is gone).
+        status (str): queued / running / done / failed / cancelled.
+        cancel_requested (bool): A cooperative stop has been requested; the running job stops at
+            its next stage boundary (still 'running' until it does).
         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.
@@ -35,8 +41,21 @@ class JobStatus(BaseModel):
 
     job_id: str = Field(description="The job row's UUID.")
     document_id: str = Field(description="The document being ingested.")
+    document_filename: str | None = Field(
+        default=None,
+        description="The document's filename, joined at read (None if the document is gone).",
+    )
     collection_id: str = Field(description="Its collection.")
-    status: str = Field(description="queued / running / done / failed.")
+    collection_name: str | None = Field(
+        default=None,
+        description="The collection's name, joined at read (None if the collection is gone).",
+    )
+    status: str = Field(description="queued / running / done / failed / cancelled.")
+    cancel_requested: bool = Field(
+        default=False,
+        description="A cooperative stop has been requested; the running job stops at its next "
+        "stage boundary (still 'running' until it does).",
+    )
     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.")
@@ -130,6 +149,8 @@ class WorkerActivity(BaseModel):
 
     Attributes:
         worker_id (str): The worker's stable id (its hostname).
+        worker_name (str | None): Its friendly display name (WORKER_NAME, defaults to the
+            hostname); None only for a heartbeat row written before this column landed.
         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).
@@ -138,6 +159,11 @@ class WorkerActivity(BaseModel):
     """
 
     worker_id: str = Field(description="The worker's stable id (its hostname).")
+    worker_name: str | None = Field(
+        default=None,
+        description="Friendly display name (WORKER_NAME, defaults to hostname); None for a "
+        "pre-column row.",
+    )
     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(
@@ -162,4 +188,38 @@ class WorkersLive(BaseModel):
     )
 
 
-__all__ = ["JobStatus", "JobEvent", "JobTrace", "WorkerActivity", "WorkersLive"]
+class CancelResult(BaseModel):
+    """
+    The typed outcome of a cancel request — what the job's state is after the call.
+
+    Attributes:
+        job_id (str): The targeted job's UUID.
+        status (str): The job's status AFTER the call (cancelled / running).
+        cancel_requested (bool): Whether a cooperative stop is now pending (true only while a
+            running job is still winding down to the CANCELLED terminal state).
+        outcome (str): cancelled (now terminal) | cancellation_requested (running, will stop at
+            the next stage boundary).
+        detail (str): A human-readable description of what happened.
+    """
+
+    job_id: str = Field(description="The targeted job's UUID.")
+    status: str = Field(description="The job's status AFTER the call (cancelled / running).")
+    cancel_requested: bool = Field(
+        description="Whether a cooperative stop is now pending (true only while a running job is "
+        "still winding down to the CANCELLED terminal state)."
+    )
+    outcome: str = Field(
+        description="cancelled (now terminal) | cancellation_requested (running, will stop at "
+        "the next stage boundary)."
+    )
+    detail: str = Field(description="A human-readable description of what happened.")
+
+
+__all__ = [
+    "JobStatus",
+    "JobEvent",
+    "JobTrace",
+    "WorkerActivity",
+    "WorkersLive",
+    "CancelResult",
+]

docforge_sdk-0.7.0/docforge_sdk/models/storage.py

@@ -0,0 +1,149 @@
+# ====== Code Summary ======
+# Response models for the collection storage-footprint endpoint, mirrored field-for-field from the
+# DocForge backend router models (S3FootprintModel / PostgresFootprintModel / QdrantFootprintModel /
+# DocumentStorageModel / CollectionStorageResponse). S3 bytes are EXACT; Postgres and Qdrant bytes are
+# ESTIMATES — each section carries its own ``estimated`` flag.
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class S3FootprintModel(BaseModel):
+    """
+    EXACT S3 bytes from the content-addressed blob registry (``estimated`` is always false).
+
+    Attributes:
+        original_bytes (int): Uploaded source file bytes.
+        rendered_bytes (int): Derived-blob bytes (canonical PDF, page renders, crops).
+        total_bytes (int): Logical bytes (original + rendered).
+        physical_unique_bytes (int): Deduped disk cost — a blob shared across documents counts
+            once (<= total).
+        estimated (bool): Always false: S3 bytes are measured exactly.
+    """
+
+    original_bytes: int = Field(description="Uploaded source file bytes.")
+    rendered_bytes: int = Field(
+        description="Derived-blob bytes (canonical PDF, page renders, crops)."
+    )
+    total_bytes: int = Field(description="Logical bytes (original + rendered).")
+    physical_unique_bytes: int = Field(
+        description="Deduped disk cost — a blob shared across documents counts once (<= total)."
+    )
+    estimated: bool = Field(description="Always false: S3 bytes are measured exactly.")
+
+
+class PostgresFootprintModel(BaseModel):
+    """
+    ESTIMATED Postgres row bytes via ``pg_column_size`` (excludes index/TOAST/bloat).
+
+    Attributes:
+        documents_bytes (int): ``document`` + ``page`` rows.
+        ir_blocks_bytes (int): ``block`` + ``block_table`` + ``block_figure`` rows.
+        enrichment_bytes (int): ``block_enrichment`` + ``enrichment_attempt`` rows.
+        chunks_bytes (int): ``chunk`` + ``chunk_block`` + ``chunk_metadata`` + ``entity_mention`` rows.
+        metadata_bytes (int): ``document_metadata`` rows.
+        observability_bytes (int): ``job`` + ``job_stage_event`` rows.
+        total_bytes (int): Sum of every bucket.
+        estimated (bool): Always true: real row bytes, no index/TOAST/bloat.
+    """
+
+    documents_bytes: int = Field(description="``document`` + ``page`` rows.")
+    ir_blocks_bytes: int = Field(description="``block`` + ``block_table`` + ``block_figure`` rows.")
+    enrichment_bytes: int = Field(description="``block_enrichment`` + ``enrichment_attempt`` rows.")
+    chunks_bytes: int = Field(
+        description="``chunk`` + ``chunk_block`` + ``chunk_metadata`` + ``entity_mention`` rows."
+    )
+    metadata_bytes: int = Field(description="``document_metadata`` rows.")
+    observability_bytes: int = Field(description="``job`` + ``job_stage_event`` rows.")
+    total_bytes: int = Field(description="Sum of every bucket.")
+    estimated: bool = Field(description="Always true: real row bytes, no index/TOAST/bloat.")
+
+
+class QdrantFootprintModel(BaseModel):
+    """
+    ESTIMATED vector-store bytes (points x declared shape — excludes HNSW index overhead).
+
+    Attributes:
+        points (int): Point count (collection total, or a document's points).
+        dense_bytes (int): On-disk float32 dense bytes, summed per named vector weighted by its
+            carrier count. Excludes the int8 quantized RAM-resident copy — this is disk, not RAM.
+        sparse_bytes (int): ``points * avg_sparse_entries * 8`` (int32 index + float32 value).
+        payload_bytes (int): ``points * avg_payload_json_bytes``.
+        total_bytes (int): Sum of dense + sparse + payload.
+        estimated (bool): Always true: count-based, excludes index overhead.
+    """
+
+    points: int = Field(description="Point count (collection total, or a document's points).")
+    dense_bytes: int = Field(
+        description=(
+            "On-disk float32 dense bytes, summed per named vector weighted by its carrier count "
+            "(content_dense on every point, each meta vector only on its field's documents). "
+            "Excludes the int8 quantized RAM-resident copy — this is disk, not RAM."
+        )
+    )
+    sparse_bytes: int = Field(
+        description="``points x avg_sparse_entries x 8`` (int32 index + float32 value)."
+    )
+    payload_bytes: int = Field(description="``points x avg_payload_json_bytes``.")
+    total_bytes: int = Field(description="Sum of dense + sparse + payload.")
+    estimated: bool = Field(description="Always true: count-based, excludes index overhead.")
+
+
+class DocumentStorageModel(BaseModel):
+    """
+    One document's footprint across the three stores.
+
+    Attributes:
+        document_id (str): The document's UUID.
+        filename (str): The document's display name.
+        s3 (S3FootprintModel): EXACT S3 bytes.
+        postgres (PostgresFootprintModel): ESTIMATED Postgres row bytes.
+        qdrant (QdrantFootprintModel): ESTIMATED vector-store bytes.
+        total_bytes (int): S3 (logical) + Postgres + Qdrant.
+    """
+
+    document_id: str = Field(description="The document's UUID.")
+    filename: str = Field(description="The document's display name.")
+    s3: S3FootprintModel = Field(description="EXACT S3 bytes.")
+    postgres: PostgresFootprintModel = Field(description="ESTIMATED Postgres row bytes.")
+    qdrant: QdrantFootprintModel = Field(description="ESTIMATED vector-store bytes.")
+    total_bytes: int = Field(description="S3 (logical) + Postgres + Qdrant.")
+
+
+class CollectionStorageResponse(BaseModel):
+    """
+    A collection's material footprint per store, plus the per-document breakdown (heaviest first).
+
+    S3 bytes are EXACT; Postgres and Qdrant bytes are ESTIMATES (each section flags this via its own
+    ``estimated``). ``grand_total_bytes`` uses the DEDUPED S3 disk cost (``physical_unique_bytes``),
+    so it reflects real hardware rather than the logical per-document sum.
+
+    Attributes:
+        collection_id (str): The measured collection's UUID.
+        s3 (S3FootprintModel): EXACT S3 totals (logical + deduped physical).
+        postgres (PostgresFootprintModel): ESTIMATED Postgres row bytes.
+        qdrant (QdrantFootprintModel): ESTIMATED vector-store bytes.
+        grand_total_bytes (int): Material footprint — S3 physical_unique + Postgres + Qdrant.
+        documents (list[DocumentStorageModel]): Per-document breakdown, sorted by total bytes
+            descending (doubles as top-N).
+    """
+
+    collection_id: str = Field(description="The measured collection's UUID.")
+    s3: S3FootprintModel = Field(description="EXACT S3 totals (logical + deduped physical).")
+    postgres: PostgresFootprintModel = Field(description="ESTIMATED Postgres row bytes.")
+    qdrant: QdrantFootprintModel = Field(description="ESTIMATED vector-store bytes.")
+    grand_total_bytes: int = Field(
+        description="Material footprint — S3 physical_unique + Postgres + Qdrant."
+    )
+    documents: list[DocumentStorageModel] = Field(
+        description="Per-document breakdown, sorted by total bytes descending (doubles as top-N)."
+    )
+
+
+__all__ = [
+    "S3FootprintModel",
+    "PostgresFootprintModel",
+    "QdrantFootprintModel",
+    "DocumentStorageModel",
+    "CollectionStorageResponse",
+]

{docforge_sdk-0.3.0 → docforge_sdk-0.7.0}/docforge_sdk/resources/collections.py

@@ -10,6 +10,7 @@ from ..models.collections import (
     CreateCollectionRequest,
     UpdateCollectionRequest,
 )
+from ..models.storage import CollectionStorageResponse
 from ._base import AsyncResource, SyncResource, _ResourceMixin
 
 
@@ -80,6 +81,18 @@ class _CollectionsSpecs(_ResourceMixin):
         """
         return RequestSpec("DELETE", f"{self._COLLECTIONS_PATH}/{collection_id}")
 
+    def _storage_spec(self, collection_id: str) -> RequestSpec:
+        """
+        Build the spec for measuring a collection's material storage footprint.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            RequestSpec: A GET on the collection's storage sub-resource.
+        """
+        return RequestSpec("GET", f"{self._COLLECTIONS_PATH}/{collection_id}/storage")
+
 
 class AsyncCollections(AsyncResource, _CollectionsSpecs):
     """Asynchronous collection management (list / get / create / update / delete)."""
@@ -141,6 +154,20 @@ class AsyncCollections(AsyncResource, _CollectionsSpecs):
         """
         return await self._transport.request(self._delete_spec(collection_id), type(None))
 
+    async def storage(self, collection_id: str) -> CollectionStorageResponse:
+        """
+        Measure a collection's material footprint per store (S3 exact, Postgres/Qdrant estimated).
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionStorageResponse: Per-store totals + the per-document breakdown, heaviest first.
+        """
+        return await self._transport.request(
+            self._storage_spec(collection_id), CollectionStorageResponse
+        )
+
 
 class SyncCollections(SyncResource, _CollectionsSpecs):
     """Synchronous collection management (list / get / create / update / delete)."""
@@ -200,5 +227,17 @@ class SyncCollections(SyncResource, _CollectionsSpecs):
         """
         return self._transport.request(self._delete_spec(collection_id), type(None))
 
+    def storage(self, collection_id: str) -> CollectionStorageResponse:
+        """
+        Measure a collection's material footprint per store (S3 exact, Postgres/Qdrant estimated).
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionStorageResponse: Per-store totals + the per-document breakdown, heaviest first.
+        """
+        return self._transport.request(self._storage_spec(collection_id), CollectionStorageResponse)
+
 
 __all__ = ["AsyncCollections", "SyncCollections"]

{docforge_sdk-0.3.0 → docforge_sdk-0.7.0}/docforge_sdk/resources/jobs.py

@@ -5,7 +5,7 @@
 
 # ====== Local Project Imports ======
 from .._requestspec import RequestSpec
-from ..models.jobs import JobStatus, JobTrace, WorkersLive
+from ..models.jobs import CancelResult, JobStatus, JobTrace, WorkersLive
 from ._base import AsyncResource, SyncResource, _ResourceMixin
 
 
@@ -59,6 +59,20 @@ class _JobsSpecs(_ResourceMixin):
         """
         return RequestSpec("GET", f"{self._JOBS_PATH}/workers/live")
 
+    def _cancel_spec(self, job_id: str, force: bool) -> RequestSpec:
+        """
+        Build the spec for cancelling a job.
+
+        Args:
+            job_id (str): The job's UUID.
+            force (bool): Immediately terminate a running/wedged job instead of asking it to stop
+                cooperatively at its next stage boundary.
+
+        Returns:
+            RequestSpec: A POST on the job's ``/cancel`` route carrying ``force`` as a query param.
+        """
+        return RequestSpec("POST", f"{self._JOBS_PATH}/{job_id}/cancel", params={"force": force})
+
 
 class AsyncJobs(AsyncResource, _JobsSpecs):
     """Asynchronous ingestion-job monitoring."""
@@ -108,6 +122,22 @@ class AsyncJobs(AsyncResource, _JobsSpecs):
         """
         return await self._transport.request(self._live_workers_spec(), WorkersLive)
 
+    async def cancel(self, job_id: str, force: bool = False) -> CancelResult:
+        """
+        Cancel an ingestion job — cooperatively for a running job, immediately for a queued or
+        wedged one.
+
+        Args:
+            job_id (str): The job's UUID.
+            force (bool): Immediately terminate a running/wedged job regardless of worker state
+                instead of asking it to stop cooperatively at its next stage boundary.
+
+        Returns:
+            CancelResult: The job's post-call status, whether a cooperative stop is pending, and
+            the outcome.
+        """
+        return await self._transport.request(self._cancel_spec(job_id, force), CancelResult)
+
 
 class SyncJobs(SyncResource, _JobsSpecs):
     """Synchronous ingestion-job monitoring."""
@@ -157,5 +187,21 @@ class SyncJobs(SyncResource, _JobsSpecs):
         """
         return self._transport.request(self._live_workers_spec(), WorkersLive)
 
+    def cancel(self, job_id: str, force: bool = False) -> CancelResult:
+        """
+        Cancel an ingestion job — cooperatively for a running job, immediately for a queued or
+        wedged one.
+
+        Args:
+            job_id (str): The job's UUID.
+            force (bool): Immediately terminate a running/wedged job regardless of worker state
+                instead of asking it to stop cooperatively at its next stage boundary.
+
+        Returns:
+            CancelResult: The job's post-call status, whether a cooperative stop is pending, and
+            the outcome.
+        """
+        return self._transport.request(self._cancel_spec(job_id, force), CancelResult)
+
 
 __all__ = ["AsyncJobs", "SyncJobs"]