docforge-sdk 0.24.0__tar.gz → 0.26.0__tar.gz

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.24.0
+Version: 0.26.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

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/__init__.py

@@ -72,12 +72,17 @@ from .models.estimate import (
 from .models.explorer import (
     BulkChunkEnabledPatch,
     BulkChunkEnabledResponse,
+    ChunkContext,
     ChunkEnabledPatch,
     ChunkEnabledResult,
     ChunkInfo,
+    ChunkPage,
+    ContextChunk,
     DocumentDetail,
     DocumentListItem,
+    DocumentOutline,
     MetadataValue,
+    OutlineHeading,
     PageInfo,
 )
 
@@ -134,6 +139,8 @@ from .models.preview import (
 # ------------------- Search models ------------------- #
 from .models.search import (
     BlockLocation,
+    ChunkBrowseRequest,
+    ChunkBrowseResponse,
     SearchHealthSummary,
     SearchHit,
     SearchRequest,
@@ -208,6 +215,11 @@ __all__ = [
     "DocumentDetail",
     "PageInfo",
     "ChunkInfo",
+    "ChunkPage",
+    "ChunkContext",
+    "ContextChunk",
+    "DocumentOutline",
+    "OutlineHeading",
     "ChunkEnabledPatch",
     "BulkChunkEnabledPatch",
     "ChunkEnabledResult",
@@ -225,6 +237,8 @@ __all__ = [
     "BlockLocation",
     "SearchHit",
     "SearchResponse",
+    "ChunkBrowseRequest",
+    "ChunkBrowseResponse",
     "SearchHealthSummary",
     # Preview
     "PreviewIrSummary",

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/_transport_async.py

@@ -91,6 +91,30 @@ class AsyncTransport(_TransportBase):
         self._raise_for_status(response)
         return self._parse(response, model)
 
+    async def request_with_total(self, spec: RequestSpec, model: type[T]) -> tuple[T, int | None]:
+        """
+        Execute a request spec and also return the ``X-Total-Count`` header it carried.
+
+        Args:
+            spec (RequestSpec): The request description.
+            model (type[T]): The target type to validate the response into.
+
+        Returns:
+            tuple[T, int | None]: The validated body and the integer total, or None when the
+            header is absent or not an integer (older servers).
+        """
+        response = await self._send(
+            spec.method,
+            self._url(spec.path),
+            params=self._clean(spec.params),
+            json=spec.json,
+            files=spec.files,
+        )
+        self._raise_for_status(response)
+        raw_total = response.headers.get("x-total-count", "")
+        total = int(raw_total) if raw_total.isdigit() else None
+        return self._parse(response, model), total
+
     async def request_bare(self, spec: RequestSpec, model: type[T]) -> T:
         """
         Execute a request spec against the BARE origin (outside ``/api/v1``) and parse it.

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/_transport_sync.py

@@ -91,6 +91,30 @@ class SyncTransport(_TransportBase):
         self._raise_for_status(response)
         return self._parse(response, model)
 
+    def request_with_total(self, spec: RequestSpec, model: type[T]) -> tuple[T, int | None]:
+        """
+        Execute a request spec and also return the ``X-Total-Count`` header it carried.
+
+        Args:
+            spec (RequestSpec): The request description.
+            model (type[T]): The target type to validate the response into.
+
+        Returns:
+            tuple[T, int | None]: The validated body and the integer total, or None when the
+            header is absent or not an integer (older servers).
+        """
+        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)
+        raw_total = response.headers.get("x-total-count", "")
+        total = int(raw_total) if raw_total.isdigit() else None
+        return self._parse(response, model), total
+
     def request_bare(self, spec: RequestSpec, model: type[T]) -> T:
         """
         Execute a request spec against the BARE origin (outside ``/api/v1``) and parse it.

{docforge_sdk-0.24.0 → docforge_sdk-0.26.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.24.0"
+__version__ = "0.26.0"

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/models/__init__.py

@@ -84,12 +84,17 @@ from .estimate import (
 from .explorer import (
     BulkChunkEnabledPatch,
     BulkChunkEnabledResponse,
+    ChunkContext,
     ChunkEnabledPatch,
     ChunkEnabledResult,
     ChunkInfo,
+    ChunkPage,
+    ContextChunk,
     DocumentDetail,
     DocumentListItem,
+    DocumentOutline,
     MetadataValue,
+    OutlineHeading,
     PageInfo,
 )
 
@@ -164,6 +169,8 @@ from .preview import (
 # ------------------- Search models ------------------- #
 from .search import (
     BlockLocation,
+    ChunkBrowseRequest,
+    ChunkBrowseResponse,
     SearchHealthSummary,
     SearchHint,
     SearchHit,
@@ -269,6 +276,11 @@ __all__ = [
     "DocumentDetail",
     "PageInfo",
     "ChunkInfo",
+    "ChunkPage",
+    "ChunkContext",
+    "ContextChunk",
+    "DocumentOutline",
+    "OutlineHeading",
     "ChunkEnabledPatch",
     "BulkChunkEnabledPatch",
     "ChunkEnabledResult",
@@ -287,6 +299,8 @@ __all__ = [
     "SearchHint",
     "SearchHit",
     "SearchResponse",
+    "ChunkBrowseRequest",
+    "ChunkBrowseResponse",
     "SearchHealthSummary",
     # Jobs
     "JobStatus",

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/models/explorer.py

@@ -236,6 +236,107 @@ class ChunkInfo(BaseModel):
     )
 
 
+class ChunkPage(BaseModel):
+    """
+    One page of a document's chunks together with the document's total chunk count.
+
+    SDK-only wrapper (not an OpenAPI schema): the REST body is a bare chunk array and the total
+    travels in the ``X-Total-Count`` response header.
+
+    Attributes:
+        items (list[ChunkInfo]): The chunks of this page, in chunk_index order.
+        total (int | None): The document's total chunk count; None against a server that predates
+            the header.
+    """
+
+    items: list[ChunkInfo] = Field(description="The chunks of this page, in chunk_index order.")
+    total: int | None = Field(
+        default=None, description="The document's total chunk count (X-Total-Count header)."
+    )
+
+
+class OutlineHeading(BaseModel):
+    """
+    One heading of a document's table of contents.
+
+    Attributes:
+        level (int): Heading depth (1 = top level).
+        text (str): The heading text.
+        page_number (int | None): 1-based page the heading sits on; None for page-less documents.
+        chunk_id (str | None): The first chunk of this section; None when no chunk carries it.
+    """
+
+    level: int = Field(description="Heading depth (1 = top level; 1 when the parser set none).")
+    text: str = Field(description="The heading text.")
+    page_number: int | None = Field(
+        default=None, description="1-based page the heading sits on; null for a page-less document."
+    )
+    chunk_id: str | None = Field(
+        default=None, description="The first chunk of this section; null when none carries it."
+    )
+
+
+class DocumentOutline(BaseModel):
+    """
+    A document's heading tree - the cheap table of contents to read before fetching content.
+
+    Attributes:
+        document_id (str): The document's UUID.
+        display_title (str): The title to show ('' when none).
+        page_count (int | None): Pages of the document; None before parse / for page-less formats.
+        headings (list[OutlineHeading]): Every heading, in reading order.
+    """
+
+    document_id: str = Field(description="The document's UUID.")
+    display_title: str = Field(description="The title to show ('' when none).")
+    page_count: int | None = Field(default=None, description="Pages of the document.")
+    headings: list[OutlineHeading] = Field(
+        default_factory=list, description="Every heading, in reading order ([] when none)."
+    )
+
+
+class ContextChunk(BaseModel):
+    """
+    One chunk of a context window (lean projection of a chunk).
+
+    Attributes:
+        chunk_id (str): The chunk UUID.
+        chunk_index (int): Position of the chunk within its document.
+        text (str): The chunk's (enriched) text.
+        page_number (int | None): 1-based page of the chunk's leading block; None when unlocated.
+        heading_path (list[str]): The chunk's section breadcrumb (outer to inner).
+        token_count (int): Token length of the text.
+        is_target (bool): True for the chunk the window was requested around.
+    """
+
+    chunk_id: str = Field(description="The chunk UUID.")
+    chunk_index: int = Field(description="Position of the chunk within its document.")
+    text: str = Field(description="The chunk's (enriched) text.")
+    page_number: int | None = Field(default=None, description="1-based page; null when unlocated.")
+    heading_path: list[str] = Field(
+        default_factory=list, description="The chunk's section breadcrumb (outer to inner)."
+    )
+    token_count: int = Field(description="Token length of the text.")
+    is_target: bool = Field(description="True for the chunk the window was requested around.")
+
+
+class ChunkContext(BaseModel):
+    """
+    A chunk and its neighbours within the same document (a reading window around a search hit).
+
+    Attributes:
+        document_id (str): The owning document's UUID.
+        display_title (str): The owning document's display title.
+        chunks (list[ContextChunk]): The window in chunk_index order, the target flagged.
+    """
+
+    document_id: str = Field(description="The owning document's UUID.")
+    display_title: str = Field(description="The owning document's display title.")
+    chunks: list[ContextChunk] = Field(
+        description="The window in chunk_index order, the target flagged is_target."
+    )
+
+
 class ChunkEnabledPatch(BaseModel):
     """
     The desired searchability state for one chunk (its enabled_override).
@@ -321,6 +422,11 @@ __all__ = [
     "DocumentDetail",
     "PageInfo",
     "ChunkInfo",
+    "ChunkPage",
+    "OutlineHeading",
+    "DocumentOutline",
+    "ContextChunk",
+    "ChunkContext",
     "ChunkEnabledPatch",
     "BulkChunkEnabledPatch",
     "ChunkEnabledResult",

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/models/search.py

@@ -44,13 +44,25 @@ class SearchRequest(BaseModel):
         return_fields (list[str] | None): Hit fields to return (lean response). None → the full hit.
         group_by (Literal["document"] | None): ``"document"`` caps hits per document.
         max_per_document (int): The per-document cap under ``group_by`` (1-10).
+        min_score (float | None): Drop hits scoring below this (scale = the response's score_kind).
+        rerank (bool | None): Per-request override of the rerank stage (None = the pipeline decides).
+        fusion (Literal["rrf", "dbsf"] | None): Per-request override of the dense/sparse fusion.
+        debug (bool): Add each hit's ``fusion_score`` / ``rerank_score``.
     """
 
     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]).",
+        description="Metadata filters, ANDed across fields: {field: value}. A scalar = equality "
+        "(string/enum/keyword_list match case-insensitively); a list = any-of (max 100); an object "
+        '= ONE operator: {"eq": v}, {"in": [..]}, {"not": v}, {"not_in": [..]}, '
+        '{"contains": "sub"} / {"prefix": "pre"} (string-ish fields: case-insensitive '
+        'match against stored values; text fields: contains = full-text), {"exists": true|false}, '
+        'or range bounds {"gte","gt","lte","lt"} on integer/float/datetime fields '
+        "(datetime bounds = ISO-8601 strings). Only filterable fields; an operator not valid for the "
+        "field type -> 422 listing the valid ones. A value no document stores yields a response hint "
+        "with the closest stored values.",
     )
     search_in: list[SearchTarget] | None = Field(
         default=None,
@@ -79,6 +91,26 @@ class SearchRequest(BaseModel):
         description="Per-document hit cap when group_by='document' (default 1). Only valid "
         "together with group_by.",
     )
+    min_score: float | None = Field(
+        default=None,
+        ge=0.0,
+        description="Drop hits whose final score is below this threshold (on the scale named by "
+        "the response's score_kind). None -> no threshold.",
+    )
+    rerank: bool | None = Field(
+        default=None,
+        description="Override the collection's rerank stage for this request: false skips it, "
+        "true requires it (422 when the search pipeline has none). None -> the pipeline decides.",
+    )
+    fusion: Literal["rrf", "dbsf"] | None = Field(
+        default=None,
+        description="Override how the dense and sparse branches are fused for this request: 'rrf' "
+        "(rank-based) or 'dbsf' (distribution-based). None -> the collection's configured fusion.",
+    )
+    debug: bool = Field(
+        default=False,
+        description="True -> each hit also carries fusion_score and, when reranked, rerank_score.",
+    )
 
 
 class BlockLocation(BaseModel):
@@ -172,6 +204,16 @@ class SearchHit(BaseModel):
         default_factory=list,
         description="Every source block's page + NORMALISED bbox — draw one box per block.",
     )
+    fusion_score: float | None = Field(
+        default=None,
+        description="The retrieval fusion score before any rerank (only when the request set "
+        "debug=true).",
+    )
+    rerank_score: float | None = Field(
+        default=None,
+        description="The cross-encoder rerank score (only when debug=true and a rerank stage "
+        "re-scored the hit).",
+    )
 
 
 class SearchCost(BaseModel):
@@ -254,6 +296,56 @@ class SearchResponse(BaseModel):
     )
 
 
+class ChunkBrowseRequest(BaseModel):
+    """
+    List a collection's chunks by filter, without a query.
+
+    Attributes:
+        filters (dict[str, Any] | None): The same filter map as search; None -> every chunk.
+        limit (int): Page size (1-200).
+        cursor (str | None): The previous page's ``next_cursor``; None -> the first page.
+        return_fields (list[str] | None): Chunk fields to return (as search; ``score`` is not one).
+    """
+
+    filters: dict[str, Any] | None = Field(
+        default=None,
+        description="Constraints on the FILTERABLE metadata fields - exactly the grammar of search "
+        "`filters`. None -> every searchable chunk of the collection.",
+    )
+    limit: int = Field(default=20, ge=1, le=200, description="Chunks per page (1-200).")
+    cursor: str | None = Field(
+        default=None,
+        description="Opaque cursor: the previous page's `next_cursor`, sent back unchanged with the "
+        "SAME filters. None -> the first page.",
+    )
+    return_fields: list[str] | None = Field(
+        default=None,
+        max_length=64,
+        description="The chunk fields to return - any search hit field except score, or "
+        "'metadata.<field>'. chunk_id and document_id are ALWAYS returned. None -> every field "
+        "except geometry (page_number is kept). Omitted fields are absent (not null).",
+    )
+
+
+class ChunkBrowseResponse(BaseModel):
+    """
+    One page of browsed chunks.
+
+    Attributes:
+        chunks (list[SearchHit]): The page, ordered by document id then chunk_index (no score).
+        next_cursor (str | None): Pass back as ``cursor`` for the next page; None on the last page.
+        hints (list[SearchHint]): Filter hints (a value nothing stores; the culprit of an empty page).
+    """
+
+    chunks: list[SearchHit] = Field(
+        default_factory=list, description="The page's chunks in browse order."
+    )
+    next_cursor: str | None = Field(
+        default=None, description="Cursor of the next page; null on the last page."
+    )
+    hints: list[SearchHint] = Field(default_factory=list, description="Filter hints, as search.")
+
+
 class SearchHealthSummary(BaseModel):
     """
     A compact, tile-friendly roll-up of search-runtime health for the deployment cockpit.
@@ -297,5 +389,7 @@ __all__ = [
     "SearchCost",
     "SearchHint",
     "SearchResponse",
+    "ChunkBrowseRequest",
+    "ChunkBrowseResponse",
     "SearchHealthSummary",
 ]

{docforge_sdk-0.24.0 → docforge_sdk-0.26.0}/docforge_sdk/resources/documents.py

@@ -212,7 +212,9 @@ class AsyncDocuments(AsyncResource, _DocumentsSpecs):
             self._purge_trace_payloads_spec(document_id), TracePurgeResult
         )
 
-    async def get_markdown(self, document_id: str, download: bool = False) -> DocumentView:
+    async def get_markdown(
+        self, document_id: str, download: bool = False, pages: str | None = None
+    ) -> DocumentView:
         """
         Render a document as an on-the-fly markdown view generated from the canonical IR.
 
@@ -220,16 +222,20 @@ class AsyncDocuments(AsyncResource, _DocumentsSpecs):
             document_id (str): The document to render.
             download (bool): When true, ask the server for the attachment-style response (the caller
                 still only gets the text back; the flag only affects the server-side response header).
+            pages (str | None): Render only these 1-based pages ('5', '5-7', '5,7-9'); the whole
+                document when None (the parameter is then not sent at all).
 
         Returns:
             DocumentView: The rendered markdown body and its ``text/markdown`` content type.
         """
         content, mime_type = await self._transport.get_text_typed(
-            self._markdown_path(document_id), params={"download": download}
+            self._markdown_path(document_id), params={"download": download, "pages": pages}
         )
         return DocumentView(content=content, mime_type=mime_type)
 
-    async def get_html(self, document_id: str, download: bool = False) -> DocumentView:
+    async def get_html(
+        self, document_id: str, download: bool = False, pages: str | None = None
+    ) -> DocumentView:
         """
         Render a document as an on-the-fly HTML view generated from the canonical IR.
 
@@ -237,12 +243,14 @@ class AsyncDocuments(AsyncResource, _DocumentsSpecs):
             document_id (str): The document to render.
             download (bool): When true, ask the server for the attachment-style response (the caller
                 still only gets the text back; the flag only affects the server-side response header).
+            pages (str | None): Render only these 1-based pages ('5', '5-7', '5,7-9'); the whole
+                document when None (the parameter is then not sent at all).
 
         Returns:
             DocumentView: The rendered HTML body and its ``text/html`` content type.
         """
         content, mime_type = await self._transport.get_text_typed(
-            self._html_path(document_id), params={"download": download}
+            self._html_path(document_id), params={"download": download, "pages": pages}
         )
         return DocumentView(content=content, mime_type=mime_type)
 
@@ -303,7 +311,9 @@ class SyncDocuments(SyncResource, _DocumentsSpecs):
             self._purge_trace_payloads_spec(document_id), TracePurgeResult
         )
 
-    def get_markdown(self, document_id: str, download: bool = False) -> DocumentView:
+    def get_markdown(
+        self, document_id: str, download: bool = False, pages: str | None = None
+    ) -> DocumentView:
         """
         Render a document as an on-the-fly markdown view generated from the canonical IR.
 
@@ -311,16 +321,20 @@ class SyncDocuments(SyncResource, _DocumentsSpecs):
             document_id (str): The document to render.
             download (bool): When true, ask the server for the attachment-style response (the caller
                 still only gets the text back; the flag only affects the server-side response header).
+            pages (str | None): Render only these 1-based pages ('5', '5-7', '5,7-9'); the whole
+                document when None (the parameter is then not sent at all).
 
         Returns:
             DocumentView: The rendered markdown body and its ``text/markdown`` content type.
         """
         content, mime_type = self._transport.get_text_typed(
-            self._markdown_path(document_id), params={"download": download}
+            self._markdown_path(document_id), params={"download": download, "pages": pages}
         )
         return DocumentView(content=content, mime_type=mime_type)
 
-    def get_html(self, document_id: str, download: bool = False) -> DocumentView:
+    def get_html(
+        self, document_id: str, download: bool = False, pages: str | None = None
+    ) -> DocumentView:
         """
         Render a document as an on-the-fly HTML view generated from the canonical IR.
 
@@ -328,12 +342,14 @@ class SyncDocuments(SyncResource, _DocumentsSpecs):
             document_id (str): The document to render.
             download (bool): When true, ask the server for the attachment-style response (the caller
                 still only gets the text back; the flag only affects the server-side response header).
+            pages (str | None): Render only these 1-based pages ('5', '5-7', '5,7-9'); the whole
+                document when None (the parameter is then not sent at all).
 
         Returns:
             DocumentView: The rendered HTML body and its ``text/html`` content type.
         """
         content, mime_type = self._transport.get_text_typed(
-            self._html_path(document_id), params={"download": download}
+            self._html_path(document_id), params={"download": download, "pages": pages}
         )
         return DocumentView(content=content, mime_type=mime_type)