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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.22.3
+Version: 0.24.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.22.3 → docforge_sdk-0.24.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.22.3"
+__version__ = "0.24.0"

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

@@ -28,11 +28,14 @@ from .collections import (
     BulkReingestAccepted,
     BulkReingestRequest,
     CollectionContractSchemaResponse,
+    CollectionDescription,
     CollectionListItem,
     CollectionModel,
     CreateCollectionRequest,
+    FieldGuide,
     FieldSpec,
     ReingestJobHandle,
+    SearchTargetGuide,
     UpdateCollectionRequest,
 )
 
@@ -162,6 +165,7 @@ from .preview import (
 from .search import (
     BlockLocation,
     SearchHealthSummary,
+    SearchHint,
     SearchHit,
     SearchRequest,
     SearchResponse,
@@ -280,6 +284,7 @@ __all__ = [
     "SearchTarget",
     "SearchRequest",
     "BlockLocation",
+    "SearchHint",
     "SearchHit",
     "SearchResponse",
     "SearchHealthSummary",
@@ -342,6 +347,9 @@ __all__ = [
     "CollectionCost",
     # Discovery + introspection
     "CollectionContractSchemaResponse",
+    "CollectionDescription",
+    "FieldGuide",
+    "SearchTargetGuide",
     "WhoAmI",
     # Transfers
     "TransferAccepted",

{docforge_sdk-0.22.3 → docforge_sdk-0.24.0}/docforge_sdk/models/collections.py

@@ -31,6 +31,7 @@ class FieldSpec(BaseModel):
         enum_values (list[str] | None): Allowed values when ``field_type`` is enum.
         origin (FieldOrigin): user (declared at upload) or generated (metagen).
         scope (FieldScope): document or chunk level value.
+        description (str | None): What the field means (max 1000 chars).
     """
 
     field_name: str = Field(description="Unique field name within the collection.")
@@ -48,6 +49,11 @@ class FieldSpec(BaseModel):
     scope: FieldScope = Field(
         default=FieldScope.DOCUMENT, description="document or chunk level value."
     )
+    description: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="What the field means, in plain words — surfaced to search clients (max 1000).",
+    )
 
 
 class CollectionModel(BaseModel):
@@ -63,6 +69,7 @@ class CollectionModel(BaseModel):
             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.
+        title_field (str | None): Document-scope field used as the display title (None = parsed).
         pipeline (dict[str, Any]): The ingestion pipeline blob (the graph).
         search (dict[str, Any]): The search pipeline graph blob ({} = the stock default).
         fields (list[FieldSpec]): The metadata schema.
@@ -97,6 +104,11 @@ class CollectionModel(BaseModel):
     )
     needs_reindex: bool = Field(description="True when a config change requires reindexing.")
     created_at: datetime | None = Field(default=None, description="Creation timestamp.")
+    title_field: str | None = Field(
+        default=None,
+        description="Document-scope field whose value is each document's display title (None = the "
+        "parser-derived title).",
+    )
     pipeline: dict[str, Any] = Field(description="The ingestion pipeline blob (the graph).")
     search: dict[str, Any] = Field(
         description="The search pipeline graph blob ({} = use the stock default)."
@@ -134,6 +146,7 @@ class CreateCollectionRequest(BaseModel):
         max_file_size_bytes (int): Upload size ceiling, bytes.
         job_timeout_seconds (float | None): Per-collection whole-ingest-job wall-clock job timeout,
             seconds. None = inherit the worker's global WORKER_JOB_TIMEOUT_SECONDS default.
+        title_field (str | None): Document-scope field used as the display title.
         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.
     """
@@ -162,6 +175,11 @@ class CreateCollectionRequest(BaseModel):
             "WORKER_TRACE_MAX_VERBOSITY)."
         ),
     )
+    title_field: str | None = Field(
+        default=None,
+        description="Document-scope field whose value is each document's display title (must name a "
+        "document-scope field of the schema); None = the parser-derived title.",
+    )
     fields: list[FieldSpec] = Field(
         default_factory=list,
         description="The FULL schema, declared up front (vector space is fixed at creation).",
@@ -194,6 +212,7 @@ class UpdateCollectionRequest(BaseModel):
         max_file_size_bytes (int | None): New size ceiling, bytes.
         job_timeout_seconds (float | None): New per-collection whole-ingest-job wall-clock
             job timeout, seconds. Omitted = leave the current value unchanged.
+        title_field (str | None): Display-title field. Omitted = unchanged; explicit null = clear.
         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).
@@ -229,6 +248,12 @@ class UpdateCollectionRequest(BaseModel):
             "ceiling WORKER_TRACE_MAX_VERBOSITY."
         ),
     )
+    title_field: str | None = Field(
+        default=None,
+        description="Document-scope field shown as each document's display title. Omitted = leave "
+        "unchanged; explicit null = clear (back to the parsed title); a name must be a document-scope "
+        "field of the post-PATCH schema. Auto-cleared when that field is removed or renamed.",
+    )
     fields: list[FieldSpec] | None = Field(
         default=None,
         description="The TARGET schema (diffed by field name; omitted fields are removed).",
@@ -319,6 +344,87 @@ class CollectionContractSchemaResponse(BaseModel):
     )
 
 
+class FieldGuide(BaseModel):
+    """
+    One metadata field, described for a client that wants to filter or search on it.
+
+    Attributes:
+        name (str): The field name (the key used in ``filters`` / ``search_in``).
+        type (FieldType): The declared data type.
+        description (str | None): What the field means (None when the schema sets none).
+        scope (FieldScope): Where the value lives — one per document, or one per chunk.
+        origin (FieldOrigin): Who fills it.
+        filterable (bool): Usable as a ``filters`` key.
+        semantic (bool): Searchable on its dense vector.
+        lexical (bool): Searchable on its sparse vector.
+        required (bool): Required at upload.
+        enum_values (list[str] | None): The allowed values of an enum field.
+        example_values (list[str]): Up to 10 stored values, most frequent first.
+        distinct_count (int): Number of distinct stored values.
+        note (str | None): Why examples are omitted, when they are.
+    """
+
+    name: str = Field(description="The field name (key used in filters / search_in).")
+    type: FieldType = Field(description="The declared data type.")
+    description: str | None = Field(default=None, description="What the field means.")
+    scope: FieldScope = Field(description="One value per document, or one per chunk.")
+    origin: FieldOrigin = Field(description="Who fills the field.")
+    filterable: bool = Field(description="Usable as a filters key.")
+    semantic: bool = Field(description="Searchable on its dense vector.")
+    lexical: bool = Field(description="Searchable on its sparse vector.")
+    required: bool = Field(description="Required at upload.")
+    enum_values: list[str] | None = Field(default=None, description="Allowed values of an enum.")
+    example_values: list[str] = Field(
+        default_factory=list, description="Up to 10 stored values, most frequent first."
+    )
+    distinct_count: int = Field(description="Number of distinct stored values.")
+    note: str | None = Field(default=None, description="Why examples are omitted, when they are.")
+
+
+class SearchTargetGuide(BaseModel):
+    """
+    One valid ``search_in`` entry of the collection.
+
+    Attributes:
+        field (str): ``"content"`` (the chunk body) or a metadata field name.
+        semantic (bool): The field has a dense vector to query.
+        lexical (bool): The field has a sparse vector to query.
+    """
+
+    field: str = Field(description="'content' or a metadata field name.")
+    semantic: bool = Field(description="The field has a dense vector to query.")
+    lexical: bool = Field(description="The field has a sparse vector to query.")
+
+
+class CollectionDescription(BaseModel):
+    """
+    The lean agent guide to one collection — what is in it and how to query it.
+
+    Attributes:
+        collection_id (str): The collection id.
+        name (str): The collection name.
+        document_count (int): Number of documents in the collection.
+        title_field (str | None): The document-scope field used as each hit's display title.
+        page_numbering (str): How hits locate pages (which field to cite).
+        fields (list[FieldGuide]): Every metadata field of the schema.
+        searchable_targets (list[SearchTargetGuide]): The valid ``search_in`` entries.
+        filter_grammar (list[str]): The filter value forms the search route accepts.
+        example_requests (list[dict[str, Any]]): Ready-to-send search request bodies.
+    """
+
+    collection_id: str = Field(description="The collection id.")
+    name: str = Field(description="The collection name.")
+    document_count: int = Field(description="Number of documents in the collection.")
+    title_field: str | None = Field(default=None, description="Display-title field, if any.")
+    page_numbering: str = Field(description="How hits locate pages (which field to cite).")
+    fields: list[FieldGuide] = Field(description="Every metadata field of the schema.")
+    searchable_targets: list[SearchTargetGuide] = Field(description="Valid search_in entries.")
+    filter_grammar: list[str] = Field(description="The accepted filter value forms.")
+    example_requests: list[dict[str, Any]] = Field(
+        description="Ready-to-send search request bodies for this collection."
+    )
+
+
 __all__ = [
     "FieldSpec",
     "CollectionModel",
@@ -329,4 +435,7 @@ __all__ = [
     "ReingestJobHandle",
     "BulkReingestAccepted",
     "CollectionContractSchemaResponse",
+    "FieldGuide",
+    "SearchTargetGuide",
+    "CollectionDescription",
 ]

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

@@ -41,7 +41,8 @@ class DocumentListItem(BaseModel):
         page_count (int | None): Pages once parsed (None before).
         file_size (int): Original size in bytes.
         created_at (datetime | None): Admission timestamp.
-        title (str): Learned title ('' before parse).
+        title (str): Raw parsed title ('' before parse).
+        display_title (str): The title to display (title_field value, else the parsed title).
         language (str | None): Detected language (None before parse).
         enabled (bool): Document-level searchability toggle.
         chunk_count (int | None): Chunks persisted at ingestion (0 = empty; None = unknown/legacy).
@@ -55,7 +56,12 @@ class DocumentListItem(BaseModel):
     page_count: int | None = Field(default=None, description="Pages once parsed (None before).")
     file_size: int = Field(description="Original size in bytes.")
     created_at: datetime | None = Field(default=None, description="Admission timestamp.")
-    title: str = Field(description="Learned title ('' before parse).")
+    title: str = Field(description="Raw parsed title ('' before parse).")
+    display_title: str = Field(
+        default="",
+        description="The title to show: the collection's title_field value when set and present, "
+        "else the parsed title.",
+    )
     language: str | None = Field(default=None, description="Detected language (None before parse).")
     enabled: bool = Field(description="Document-level searchability toggle.")
     chunk_count: int | None = Field(
@@ -81,7 +87,8 @@ class DocumentDetail(BaseModel):
         file_size (int): Original size in bytes.
         page_count (int | None): Pages once parsed.
         language (str | None): Detected document language.
-        title (str): Learned title ('' before parse).
+        title (str): Raw parsed title ('' before parse).
+        display_title (str): The title to display (title_field value, else the parsed title).
         source_kind (SourceKind): Acquisition routing.
         status (DocumentStatus): Ingestion lifecycle state.
         source_hash (str): Content address of the original bytes (blob key).
@@ -105,7 +112,12 @@ class DocumentDetail(BaseModel):
     file_size: int = Field(description="Original size in bytes.")
     page_count: int | None = Field(default=None, description="Pages once parsed.")
     language: str | None = Field(default=None, description="Detected document language.")
-    title: str = Field(description="Learned title ('' before parse).")
+    title: str = Field(description="Raw parsed title ('' before parse).")
+    display_title: str = Field(
+        default="",
+        description="The title to show: the collection's title_field value when set and present, "
+        "else the parsed title.",
+    )
     source_kind: SourceKind = Field(description="Acquisition routing.")
     status: DocumentStatus = Field(description="Ingestion lifecycle state.")
     source_hash: str = Field(description="Content address of the original bytes (blob key).")
@@ -144,7 +156,8 @@ class PageInfo(BaseModel):
     One page's geometry, routing and its render blob reference.
 
     Attributes:
-        page_number (int): 0-based page index (first page = 0).
+        page_number (int): 0-based page INDEX (legacy; first page = 0).
+        page_label (int): 1-based page number as a reader counts it (cite this).
         width (float | None): Page width in points (None if unknown).
         height (float | None): Page height in points (None if unknown).
         is_scanned (bool): Whether this page was routed as image-only (OCR/VLM).
@@ -152,7 +165,16 @@ class PageInfo(BaseModel):
         render_blob_hash (str | None): Blob of the rasterized page (None when render was off).
     """
 
-    page_number: int = Field(description="0-based page index (first page = 0).")
+    page_number: int = Field(
+        description="0-based page INDEX (first page = 0) — NOT the reader's page number; use "
+        "page_label for that."
+    )
+    # Defaulted (not required) so this SDK still parses responses from pre-0.23 servers that
+    # don't send the field yet.
+    page_label: int | None = Field(
+        default=None,
+        description="1-based page number as a reader counts it (= page_number + 1).",
+    )
     width: float | None = Field(default=None, description="Page width in points (None if unknown).")
     height: float | None = Field(
         default=None, description="Page height in points (None if unknown)."
@@ -181,7 +203,8 @@ class ChunkInfo(BaseModel):
         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.
+        page (int | None): Page of the chunk's primary block (0-based); None when unlocated.
+        page_number (int | None): The same page, 1-based (as a reader counts it); None when unlocated.
     """
 
     id: str = Field(description="The chunk UUID (doubles as the Qdrant point id).")
@@ -205,7 +228,11 @@ class ChunkInfo(BaseModel):
     )
     page: int | None = Field(
         default=None,
-        description="Page of the chunk's primary block; None when it has no located block.",
+        description="Page of the chunk's primary block (0-based); None when it has no located block.",
+    )
+    page_number: int | None = Field(
+        default=None,
+        description="The same page, 1-based (as a reader counts it); None when unlocated.",
     )
 
 

{docforge_sdk-0.22.3 → docforge_sdk-0.24.0}/docforge_sdk/models/ir.py

@@ -22,6 +22,7 @@ class IRBlock(BaseModel):
         id (str): Document-namespaced block id.
         block_type (str): text / heading / list / table / figure / …
         page (int): 0-based page the block sits on (first page = 0).
+        page_number (int): 1-based page number as a reader counts it.
         bbox (list[float]): Bounding box [x0, y0, x1, y1] in page coordinates.
         reading_order (int): Global reading-order rank within the document.
         parent_id (str | None): Parent block in the heading tree.
@@ -34,6 +35,10 @@ class IRBlock(BaseModel):
     id: str = Field(description="Document-namespaced block id.")
     block_type: str = Field(description="text / heading / list / table / figure / …")
     page: int = Field(description="0-based page the block sits on (first page = 0).")
+    # Defaulted (not required) so this SDK still parses responses from pre-0.23 servers.
+    page_number: int | None = Field(
+        default=None, description="1-based page number as a reader counts it (= page + 1)."
+    )
     bbox: list[float] = Field(description="Bounding box [x0, y0, x1, y1] in page coordinates.")
     reading_order: int = Field(description="Global reading-order rank within the document.")
     parent_id: str | None = Field(default=None, description="Parent block in the heading tree.")

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

@@ -3,7 +3,7 @@
 # router models. ``filters`` and ``debug_info`` are opaque, server-shaped JSON and are typed as dicts.
 
 # ====== Standard Library Imports ======
-from typing import Any
+from typing import Any, Literal
 
 # ====== Third-Party Library Imports ======
 from pydantic import BaseModel, Field
@@ -41,6 +41,9 @@ 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.
+        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).
     """
 
     query: str = Field(min_length=1, description="The natural-language query to search for.")
@@ -54,6 +57,28 @@ class SearchRequest(BaseModel):
         description="Fields × modalities to search (content and/or metadata). None → content on "
         "both semantic and lexical (the unchanged default).",
     )
+    return_fields: list[str] | None = Field(
+        default=None,
+        max_length=64,
+        description="The hit fields to return (a lean response): any hit field name (chunk_id, "
+        "document_id, filename, document_title, heading_path, metadata, score, text, chunk_index, "
+        "token_count, block_ids, page, page_number, bbox, block_locations) or 'metadata.<field>' to "
+        "keep one metadata entry. chunk_id and document_id are ALWAYS returned. Omitted fields are "
+        "ABSENT from each hit (not null). None → the full hit. An unknown name → 422.",
+    )
+    group_by: Literal["document"] | None = Field(
+        default=None,
+        description="'document' → no document contributes more than max_per_document hits; the "
+        "ranking keeps its order and is filled with the next best hits of other documents. "
+        "None → no grouping.",
+    )
+    max_per_document: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="Per-document hit cap when group_by='document' (default 1). Only valid "
+        "together with group_by.",
+    )
 
 
 class BlockLocation(BaseModel):
@@ -68,7 +93,12 @@ class BlockLocation(BaseModel):
     """
 
     page: int | None = Field(
-        description="The page the block sits on; None for a page-less document (no page render)."
+        description="The page the block sits on (0-based); None for a page-less document (no page "
+        "render)."
+    )
+    page_number: int | None = Field(
+        default=None,
+        description="The same page, 1-based (as a reader counts it); None for a page-less document.",
     )
     bbox: list[float] = Field(
         description="Bounding box [x0, y0, x1, y1] NORMALISED to [0, 1] — multiply by the page "
@@ -88,9 +118,13 @@ class SearchHit(BaseModel):
         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.
+        page (int | None): The page of the chunk's primary (leading) block, 0-based.
+        page_number (int | None): The same page, 1-based — the one to cite.
         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).
+
+    Only ``chunk_id`` and ``document_id`` are always present: a request's ``return_fields`` omits the
+    unrequested keys (absent, not null), so ``model_fields_set`` tells what the server really sent.
     """
 
     chunk_id: str = Field(description="The chunk's UUID.")
@@ -112,18 +146,22 @@ class SearchHit(BaseModel):
         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.")
+    score: float = Field(default=0.0, description="Fused RRF score (higher is better).")
+    text: str = Field(default="", description="The chunk's enriched text.")
+    chunk_index: int = Field(default=0, description="Ordinal within the document.")
+    token_count: int = Field(default=0, 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.",
+        description="The page of the chunk's primary (leading) block, 0-based — where to draw the "
+        "box. None when the chunk carries no block location.",
+    )
+    page_number: int | None = Field(
+        default=None,
+        description="The same page, 1-based (as a reader counts it) — cite this. None when unlocated.",
     )
     bbox: list[float] | None = Field(
         default=None,
@@ -158,6 +196,26 @@ class SearchCost(BaseModel):
     )
 
 
+class SearchHint(BaseModel):
+    """
+    An actionable explanation about one filter, attached to a (200) search response.
+
+    Attributes:
+        field (str): The filtered metadata field the hint is about.
+        value (Any): The filter value as sent.
+        message (str): Human/agent-readable explanation.
+        suggestions (list[str]): Closest stored values to retry with, best first (may be empty).
+    """
+
+    field: str = Field(description="The filtered metadata field the hint is about.")
+    value: Any = Field(description="The filter value as sent (one list item, or the whole value).")
+    message: str = Field(description="Human/agent-readable explanation of the problem.")
+    suggestions: list[str] = Field(
+        default_factory=list,
+        description="Closest stored values of the field to retry with, best first (may be empty).",
+    )
+
+
 class SearchResponse(BaseModel):
     """
     The result of a hybrid search — the echoed query and its ranked hits.
@@ -168,6 +226,7 @@ class SearchResponse(BaseModel):
         score_kind (str): What each hit's ``score`` represents — so the UI can label it correctly.
         cost (SearchCost | None): The run's priced paid-LLM spend, or None when no paid call was made.
         debug_info (dict[str, Any] | None): Non-fatal diagnostics; None when there is nothing to report.
+        hints (list[SearchHint]): Actionable filter explanations (unknown value + closest stored values).
     """
 
     query: str = Field(description="The query that was searched.")
@@ -188,6 +247,11 @@ class SearchResponse(BaseModel):
         default=None,
         description="Non-fatal diagnostics about how the search ran. None when empty.",
     )
+    hints: list[SearchHint] = Field(
+        default_factory=list,
+        description="Actionable filter explanations: a filter value no document stores, with the "
+        "closest stored values to retry with. Read these before concluding nothing exists.",
+    )
 
 
 class SearchHealthSummary(BaseModel):
@@ -231,6 +295,7 @@ __all__ = [
     "BlockLocation",
     "SearchHit",
     "SearchCost",
+    "SearchHint",
     "SearchResponse",
     "SearchHealthSummary",
 ]

{docforge_sdk-0.22.3 → docforge_sdk-0.24.0}/docforge_sdk/resources/collections.py

@@ -21,6 +21,7 @@ from ..models.collections import (
     BulkReingestAccepted,
     BulkReingestRequest,
     CollectionContractSchemaResponse,
+    CollectionDescription,
     CollectionListItem,
     CollectionModel,
     CreateCollectionRequest,
@@ -114,6 +115,18 @@ class _CollectionsSpecs(_ResourceMixin):
         """
         return RequestSpec("GET", f"{self._COLLECTIONS_PATH}/{collection_id}/health")
 
+    def _describe_spec(self, collection_id: str) -> RequestSpec:
+        """
+        Build the spec for the lean agent-oriented collection guide.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            RequestSpec: A GET on the collection's describe sub-resource.
+        """
+        return RequestSpec("GET", f"{self._COLLECTIONS_PATH}/{collection_id}/describe")
+
     def _storage_spec(self, collection_id: str) -> RequestSpec:
         """
         Build the spec for measuring a collection's material storage footprint.
@@ -308,6 +321,21 @@ class AsyncCollections(AsyncResource, _CollectionsSpecs):
             self._health_spec(collection_id), CollectionHealthResponse
         )
 
+    async def describe(self, collection_id: str) -> CollectionDescription:
+        """
+        Fetch the agent guide: fields (meaning, type, example values), valid search targets, the
+        filter grammar and ready-to-send example requests. Never includes pipeline/search config.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionDescription: The lean guide to query this collection.
+        """
+        return await self._transport.request(
+            self._describe_spec(collection_id), CollectionDescription
+        )
+
     async def storage(self, collection_id: str) -> CollectionStorageResponse:
         """
         Measure a collection's material footprint per store (S3 exact, Postgres/Qdrant estimated).
@@ -562,6 +590,19 @@ class SyncCollections(SyncResource, _CollectionsSpecs):
         """
         return self._transport.request(self._health_spec(collection_id), CollectionHealthResponse)
 
+    def describe(self, collection_id: str) -> CollectionDescription:
+        """
+        Fetch the agent guide: fields (meaning, type, example values), valid search targets, the
+        filter grammar and ready-to-send example requests. Never includes pipeline/search config.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionDescription: The lean guide to query this collection.
+        """
+        return self._transport.request(self._describe_spec(collection_id), CollectionDescription)
+
     def storage(self, collection_id: str) -> CollectionStorageResponse:
         """
         Measure a collection's material footprint per store (S3 exact, Postgres/Qdrant estimated).

{docforge_sdk-0.22.3 → docforge_sdk-0.24.0}/docforge_sdk/resources/search.py

@@ -21,16 +21,23 @@ class _SearchSpecs(_ResourceMixin):
 
         Args:
             collection_id (str): The collection to search.
-            request (SearchRequest): The query, filters and target modalities.
+            request (SearchRequest): The query, filters, target modalities and the optional
+                ``return_fields`` / ``group_by`` / ``max_per_document`` shaping.
 
         Returns:
             RequestSpec: A POST to the collection's ``/search`` route carrying the query body.
         """
-        return RequestSpec(
-            "POST",
-            f"{self._COLLECTIONS_PATH}/{collection_id}/search",
-            json=request.model_dump(mode="json"),
-        )
+        # 1. Dump the body, sending the response-shaping knobs only when used: a pre-0.24 server's
+        #    SearchRequest forbids unknown keys (even a null return_fields/group_by would 422 every
+        #    plain search), and the backend 422s a max_per_document sent without group_by — so the
+        #    untouched default (1) is dropped unless grouping is on or the caller set it explicitly.
+        body = request.model_dump(mode="json")
+        for knob in ("return_fields", "group_by"):
+            if body.get(knob) is None:
+                body.pop(knob, None)
+        if request.group_by is None and "max_per_document" not in request.model_fields_set:
+            body.pop("max_per_document")
+        return RequestSpec("POST", f"{self._COLLECTIONS_PATH}/{collection_id}/search", json=body)
 
     def _search_health_spec(self) -> RequestSpec:
         """
@@ -51,7 +58,8 @@ class AsyncSearch(AsyncResource, _SearchSpecs):
 
         Args:
             collection_id (str): The collection to search.
-            request (SearchRequest): The query, filters and target modalities.
+            request (SearchRequest): The query, filters, target modalities and the optional
+                ``return_fields`` / ``group_by`` / ``max_per_document`` shaping.
 
         Returns:
             SearchResponse: The echoed query and its hits, best first.
@@ -79,7 +87,8 @@ class SyncSearch(SyncResource, _SearchSpecs):
 
         Args:
             collection_id (str): The collection to search.
-            request (SearchRequest): The query, filters and target modalities.
+            request (SearchRequest): The query, filters, target modalities and the optional
+                ``return_fields`` / ``group_by`` / ``max_per_document`` shaping.
 
         Returns:
             SearchResponse: The echoed query and its hits, best first.