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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.26.0
+Version: 0.28.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.26.0 → docforge_sdk-0.28.0}/docforge_sdk/__init__.py

@@ -48,6 +48,7 @@ from .models.collections import (
     FieldSpec,
     ReingestJobHandle,
     UpdateCollectionRequest,
+    UpdateCollectionResponse,
 )
 
 # ------------------- Documents models ------------------- #
@@ -89,6 +90,9 @@ from .models.explorer import (
 # ------------------- Health models ------------------- #
 from .models.health import HealthStatus
 
+# ------------------- Index rebuild models ------------------- #
+from .models.index_rebuild import RebuildIndexAccepted
+
 # ------------------- IR models ------------------- #
 from .models.ir import (
     DocumentIRModel,
@@ -136,6 +140,19 @@ from .models.preview import (
     PreviewTraceNode,
 )
 
+# ------------------- Collection schema ops ------------------- #
+from .models.schema_ops import (
+    AddFieldOp,
+    FieldOp,
+    FieldPatch,
+    RemoveFieldOp,
+    RenameFieldOp,
+    SchemaDiff,
+    SchemaDiffModifiedField,
+    SchemaDiffRename,
+    UpdateFieldOp,
+)
+
 # ------------------- Search models ------------------- #
 from .models.search import (
     BlockLocation,
@@ -194,6 +211,16 @@ __all__ = [
     "CollectionModel",
     "CreateCollectionRequest",
     "UpdateCollectionRequest",
+    "UpdateCollectionResponse",
+    "FieldPatch",
+    "AddFieldOp",
+    "UpdateFieldOp",
+    "RemoveFieldOp",
+    "RenameFieldOp",
+    "FieldOp",
+    "SchemaDiff",
+    "SchemaDiffModifiedField",
+    "SchemaDiffRename",
     "BulkReingestRequest",
     "ReingestJobHandle",
     "BulkReingestAccepted",
@@ -284,6 +311,7 @@ __all__ = [
     "TransferStatus",
     # Trace payloads
     "TracePurgeResult",
+    "RebuildIndexAccepted",
     # Exceptions
     "DocForgeError",
     "APIConnectionError",

{docforge_sdk-0.26.0 → docforge_sdk-0.28.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.26.0"
+__version__ = "0.28.0"

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

@@ -37,6 +37,7 @@ from .collections import (
     ReingestJobHandle,
     SearchTargetGuide,
     UpdateCollectionRequest,
+    UpdateCollectionResponse,
 )
 
 # ------------------- Corpus filter + grid models ------------------- #
@@ -112,6 +113,9 @@ from .health import (
     SearchIndex,
 )
 
+# ------------------- Index rebuild models ------------------- #
+from .index_rebuild import RebuildIndexAccepted
+
 # ------------------- IR models ------------------- #
 from .ir import (
     DocumentIRModel,
@@ -145,6 +149,7 @@ from .jobs import (
 
 # ------------------- Pipelines models ------------------- #
 from .pipelines import (
+    CollectionStageApplyResponse,
     EditResponse,
     InspectResponse,
     PipelineDesignResponse,
@@ -166,6 +171,19 @@ from .preview import (
     PreviewTraceNode,
 )
 
+# ------------------- Collection schema ops ------------------- #
+from .schema_ops import (
+    AddFieldOp,
+    FieldOp,
+    FieldPatch,
+    RemoveFieldOp,
+    RenameFieldOp,
+    SchemaDiff,
+    SchemaDiffModifiedField,
+    SchemaDiffRename,
+    UpdateFieldOp,
+)
+
 # ------------------- Search models ------------------- #
 from .search import (
     BlockLocation,
@@ -239,6 +257,16 @@ __all__ = [
     "CollectionListItem",
     "CreateCollectionRequest",
     "UpdateCollectionRequest",
+    "UpdateCollectionResponse",
+    "FieldPatch",
+    "AddFieldOp",
+    "UpdateFieldOp",
+    "RemoveFieldOp",
+    "RenameFieldOp",
+    "FieldOp",
+    "SchemaDiff",
+    "SchemaDiffModifiedField",
+    "SchemaDiffRename",
     "BulkReingestRequest",
     "ReingestJobHandle",
     "BulkReingestAccepted",
@@ -331,6 +359,7 @@ __all__ = [
     "EditResponse",
     "StageViewResponse",
     "StageApplyResponse",
+    "CollectionStageApplyResponse",
     # Preview
     "PreviewIrSummary",
     "PreviewChunk",
@@ -370,4 +399,5 @@ __all__ = [
     "TransferStatus",
     # Trace payloads
     "TracePurgeResult",
+    "RebuildIndexAccepted",
 ]

{docforge_sdk-0.26.0 → docforge_sdk-0.28.0}/docforge_sdk/models/collections.py

@@ -13,47 +13,10 @@ from pydantic import BaseModel, Field
 # ====== Local Project Imports ======
 from ._shared import FieldOrigin, FieldScope, FieldType
 from .estimate import EstimateOverrides
+from .field_spec import FieldSpec
 from .health import CollectionHealthSummary
 from .reingest import ReingestJobHandle
-
-
-class FieldSpec(BaseModel):
-    """
-    One metadata field of the collection's contract (declared OR generated).
-
-    Attributes:
-        field_name (str): Unique field name within the collection.
-        field_type (FieldType): Value type — drives validation and storage.
-        required (bool): Upload refused without it (user fields).
-        filterable (bool): Present in the Qdrant payload (lean vector).
-        lexical (bool): Gets a sparse BM25 named vector.
-        semantic (bool): Gets a dense named vector.
-        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.")
-    field_type: FieldType = Field(description="Value type — drives validation and storage.")
-    required: bool = Field(default=False, description="Upload refused without it (user fields).")
-    filterable: bool = Field(default=False, description="Present in the Qdrant payload (lean).")
-    lexical: bool = Field(default=False, description="Gets a sparse BM25 named vector.")
-    semantic: bool = Field(default=False, description="Gets a dense named vector.")
-    enum_values: list[str] | None = Field(
-        default=None, description="Allowed values when field_type is enum."
-    )
-    origin: FieldOrigin = Field(
-        default=FieldOrigin.USER, description="user (declared at upload) or generated (metagen)."
-    )
-    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).",
-    )
+from .schema_ops import FieldOp, SchemaDiff
 
 
 class CollectionModel(BaseModel):
@@ -68,6 +31,8 @@ class CollectionModel(BaseModel):
         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.
         needs_reindex (bool): True when a config change requires reindexing.
+        missing_vectors (list[str] | None): Named vectors the schema's semantic/lexical fields need
+            but the vector store does not declare (an index rebuild is required); None on list rows.
         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).
@@ -103,6 +68,14 @@ class CollectionModel(BaseModel):
         ),
     )
     needs_reindex: bool = Field(description="True when a config change requires reindexing.")
+    missing_vectors: list[str] | None = Field(
+        default=None,
+        description="Named Qdrant vectors (meta_<slug>_dense / meta_<slug>_bm25) the schema's "
+        "semantic/lexical fields need but the vector store does not declare — those fields are not "
+        "searchable until the collection's index is rebuilt (a reingest cannot add them). Computed "
+        "on the single-collection read and the PATCH response ([] = aligned or never ingested); "
+        "null on the fleet list, which never reads the vector store.",
+    )
     created_at: datetime | None = Field(default=None, description="Creation timestamp.")
     title_field: str | None = Field(
         default=None,
@@ -213,7 +186,10 @@ class UpdateCollectionRequest(BaseModel):
         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).
+        fields (list[FieldSpec] | None): LEGACY full TARGET schema (omitted fields are removed).
+        field_ops (list[FieldOp] | None): Explicit add/update/remove/rename ops (exclusive with
+            ``fields``).
+        dry_run (bool): Preview only — the response's ``schema_diff`` is computed, nothing written.
         pipeline (dict[str, Any] | None): New pipeline blob (validated before storage).
         search (dict[str, Any] | None): New search graph blob ({} = stock default).
         estimate_overrides (EstimateOverrides | None): Partial cost-estimate overrides. Omitted =
@@ -256,7 +232,17 @@ class UpdateCollectionRequest(BaseModel):
     )
     fields: list[FieldSpec] | None = Field(
         default=None,
-        description="The TARGET schema (diffed by field name; omitted fields are removed).",
+        description="LEGACY full TARGET schema (omitted fields are REMOVED with their values). "
+        "Prefer field_ops. Mutually exclusive with field_ops.",
+    )
+    field_ops: list[FieldOp] | None = Field(
+        default=None,
+        description="Explicit schema operations applied in order (add / update / remove / rename). "
+        "Mutually exclusive with fields.",
+    )
+    dry_run: bool = Field(
+        default=False,
+        description="Validate and compute schema_diff only — nothing is written.",
     )
     pipeline: dict[str, Any] | None = Field(
         default=None, description="New pipeline blob (validated before being stored)."
@@ -273,6 +259,19 @@ class UpdateCollectionRequest(BaseModel):
     note: str | None = Field(default=None, description="Version note shown in the history.")
 
 
+class UpdateCollectionResponse(CollectionModel):
+    """
+    The PATCH result: the collection (unchanged under dry_run) plus its schema diff.
+
+    Attributes:
+        schema_diff (SchemaDiff): The schema change applied (or previewed); empty when untouched.
+        dry_run (bool): True when nothing was written.
+    """
+
+    schema_diff: SchemaDiff = Field(description="The metadata-schema change applied or previewed.")
+    dry_run: bool = Field(description="True when nothing was written (preview only).")
+
+
 class BulkReingestRequest(BaseModel):
     """
     The re-run request over a collection's corpus (a full-pipeline re-ingest).
@@ -431,6 +430,7 @@ __all__ = [
     "CollectionListItem",
     "CreateCollectionRequest",
     "UpdateCollectionRequest",
+    "UpdateCollectionResponse",
     "BulkReingestRequest",
     "ReingestJobHandle",
     "BulkReingestAccepted",

{docforge_sdk-0.26.0 → docforge_sdk-0.28.0}/docforge_sdk/models/estimate.py

@@ -323,8 +323,9 @@ class CostEstimate(BaseModel):
     """
     The full pre-hoc breakdown — an ESTIMATE, with its assumptions and caveats surfaced.
 
-    ``total_cost_usd`` sums only the stages with a known rate; ``cost_complete`` is False when any
-    enabled cost-incurring stage priced to null, so the total is understood as a lower bound.
+    ``total_cost_usd`` is None as soon as any enabled cost-incurring stage priced to null
+    (``cost_complete`` False); ``total_cost_lower_bound_usd`` then carries the priced sum, and a
+    caveat names each unpriced model + stage + the override path.
 
     Attributes:
         document_count (int): Documents the estimate covers.
@@ -332,8 +333,10 @@ class CostEstimate(BaseModel):
         volume (VolumeEstimate): Projected material volume.
         total_prompt_tokens (int): Summed projected prompt/input tokens.
         total_completion_tokens (int): Summed projected completion tokens.
-        total_cost_usd (float | None): Summed USD over priced stages (None only when NO stage could
-            be priced).
+        total_cost_usd (float | None): Total projected USD — None when any enabled cost-incurring
+            stage has no known rate.
+        total_cost_lower_bound_usd (float): Sum of the priced stages only (== the total when
+            complete, else a lower bound).
         cost_complete (bool): True when every enabled cost-incurring stage had a known rate.
         assumptions (EstimateAssumptions): The assumptions this estimate rests on.
         caveats (list[str]): Human-readable accuracy caveats for this estimate.
@@ -348,7 +351,13 @@ class CostEstimate(BaseModel):
     total_prompt_tokens: int = Field(description="Summed projected prompt/input tokens.")
     total_completion_tokens: int = Field(description="Summed projected completion tokens.")
     total_cost_usd: float | None = Field(
-        description="Summed USD over priced stages (None only when NO stage could be priced)."
+        description="Total projected USD — None when any enabled cost-incurring stage has no known "
+        "rate (see total_cost_lower_bound_usd and the caveats)."
+    )
+    total_cost_lower_bound_usd: float = Field(
+        default=0.0,
+        description="Sum of the PRICED stages only — equals total_cost_usd when the cost is "
+        "complete, else a lower bound of the true cost.",
     )
     cost_complete: bool = Field(
         description="True when every enabled cost-incurring stage had a known rate."

docforge_sdk-0.28.0/docforge_sdk/models/field_spec.py

@@ -0,0 +1,51 @@
+# ====== Code Summary ======
+# FieldSpec — one metadata field of a collection's contract, mirrored from the backend
+# ``FieldSpecModel``. Its own module so both the collections and the schema-ops models build on it.
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+# ====== Local Project Imports ======
+from ._shared import FieldOrigin, FieldScope, FieldType
+
+
+class FieldSpec(BaseModel):
+    """
+    One metadata field of the collection's contract (declared OR generated).
+
+    Attributes:
+        field_name (str): Unique field name within the collection.
+        field_type (FieldType): Value type — drives validation and storage.
+        required (bool): Upload refused without it (user fields).
+        filterable (bool): Present in the Qdrant payload (lean vector).
+        lexical (bool): Gets a sparse BM25 named vector.
+        semantic (bool): Gets a dense named vector.
+        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.")
+    field_type: FieldType = Field(description="Value type — drives validation and storage.")
+    required: bool = Field(default=False, description="Upload refused without it (user fields).")
+    filterable: bool = Field(default=False, description="Present in the Qdrant payload (lean).")
+    lexical: bool = Field(default=False, description="Gets a sparse BM25 named vector.")
+    semantic: bool = Field(default=False, description="Gets a dense named vector.")
+    enum_values: list[str] | None = Field(
+        default=None, description="Allowed values when field_type is enum."
+    )
+    origin: FieldOrigin = Field(
+        default=FieldOrigin.USER, description="user (declared at upload) or generated (metagen)."
+    )
+    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).",
+    )
+
+
+__all__ = ["FieldSpec"]

docforge_sdk-0.28.0/docforge_sdk/models/index_rebuild.py

@@ -0,0 +1,22 @@
+# ====== Code Summary ======
+# Response model for the collection index rebuild, mirrored field-for-field from the DocForge backend
+# (POST /collections/{collection_id}/rebuild-index → 202).
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class RebuildIndexAccepted(BaseModel):
+    """
+    A queued index rebuild — poll the job.
+
+    Attributes:
+        collection_id (str): The collection being rebuilt.
+        job_id (str): The tracked ``rebuild_index`` job (GET /jobs/{job_id}).
+    """
+
+    collection_id: str = Field(description="The collection whose index is being rebuilt.")
+    job_id: str = Field(description="The tracked rebuild_index job — poll GET /jobs/{job_id}.")
+
+
+__all__ = ["RebuildIndexAccepted"]

{docforge_sdk-0.26.0 → docforge_sdk-0.28.0}/docforge_sdk/models/jobs.py

@@ -17,12 +17,15 @@ class JobStatus(BaseModel):
 
     Attributes:
         job_id (str): The job row's UUID.
-        document_id (str): The document being ingested.
+        document_id (str | None): The document being ingested (None for a rebuild_index job).
         document_filename (str | None): The document's filename, joined at read (None if the
             document is gone).
         document_title (str | None): The document's metagen-generated title, joined at read — a
             nicer display label than the filename when present (None if none was generated or the
             document is gone; the UI falls back to document_filename).
+        display_title (str | None): The document's display title — the collection's
+            ``title_field`` value when configured and set, else the parsed title (None when
+            neither exists, the document is gone, or on the SSE stream).
         collection_id (str): Its collection.
         collection_name (str | None): The collection's name, joined at read (None if the
             collection is gone).
@@ -47,7 +50,9 @@ class JobStatus(BaseModel):
     """
 
     job_id: str = Field(description="The job row's UUID.")
-    document_id: str = Field(description="The document being ingested.")
+    document_id: str | None = Field(
+        description="The document being ingested; null for a collection-level job (rebuild_index)."
+    )
     document_filename: str | None = Field(
         default=None,
         description="The document's filename, joined at read (None if the document is gone).",
@@ -58,6 +63,14 @@ class JobStatus(BaseModel):
         "than the filename when present (None if none was generated or the document is gone; the UI "
         "falls back to document_filename).",
     )
+    display_title: str | None = Field(
+        default=None,
+        description="The document's DISPLAY title, resolved at read exactly like the document "
+        "list/grid/detail `display_title`: the value of the collection's `title_field` when one is "
+        "configured and set on this document, else the parsed title. None when neither exists, the "
+        "document is gone, or on the SSE stream (which re-reads only the job row). Prefer it over "
+        "document_title for labelling; fall back to document_filename.",
+    )
     collection_id: str = Field(description="Its collection.")
     collection_name: str | None = Field(
         default=None,
@@ -66,7 +79,8 @@ class JobStatus(BaseModel):
     status: str = Field(description="queued / running / done / failed / cancelled.")
     kind: str = Field(
         description="The kind of work this job tracks: 'ingest' (a full document pipeline run) or "
-        "'metadata_sync' (a lightweight per-document metadata re-embed after an in-place value edit). "
+        "'metadata_sync' (a lightweight per-document metadata re-embed after an in-place value edit) or "
+        "'rebuild_index' (a collection-level vector-store rebuild — document_id is null). "
         "Lets a client render a side-job distinctly from a full ingestion."
     )
     cancel_requested: bool = Field(

{docforge_sdk-0.26.0 → docforge_sdk-0.28.0}/docforge_sdk/models/pipelines.py

@@ -195,7 +195,48 @@ class StageApplyResponse(BaseModel):
     )
 
 
+class CollectionStageApplyResponse(BaseModel):
+    """
+    The outcome of a collection-scoped stage action (applied to the STORED pipeline, persisted if valid).
+
+    Attributes:
+        collection_id (str): The edited collection.
+        persisted (bool): True when the new pipeline was stored (a config version written).
+        needs_reindex (bool): The collection's derived reindex flag after the write.
+        stages (list[dict[str, Any]]): The redacted stage view of the result (opaque engine JSON).
+        valid (bool): True when the result built and has zero validation issues.
+        issues (list[dict[str, Any]]): Validation problems of the result.
+        notices (list[str]): Compiler notices plus the reason nothing was stored, if so.
+        build_error (str | None): Builder failure when the result cannot build (not persisted).
+    """
+
+    collection_id: str = Field(description="The edited collection.")
+    persisted: bool = Field(
+        description="True when the new pipeline was stored (a config version was written); false "
+        "when the result is invalid or the action changed nothing."
+    )
+    needs_reindex: bool = Field(
+        default=False,
+        description="The collection's derived reindex flag after the write (embed-space change).",
+    )
+    stages: list[dict[str, Any]] = Field(
+        description="The redacted stage view of the resulting pipeline, in run order."
+    )
+    valid: bool = Field(description="True when the result built and has zero validation issues.")
+    issues: list[dict[str, Any]] = Field(
+        default_factory=list, description="Validation problems of the result (empty when healthy)."
+    )
+    notices: list[str] = Field(
+        default_factory=list,
+        description="Compiler notices (cascades, ignored no-ops) and the reason nothing was stored.",
+    )
+    build_error: str | None = Field(
+        default=None, description="Builder failure when the result cannot build (not persisted)."
+    )
+
+
 __all__ = [
+    "CollectionStageApplyResponse",
     "PipelineSurface",
     "PipelineIndexResponse",
     "PipelineDesignResponse",

docforge_sdk-0.28.0/docforge_sdk/models/schema_ops.py

@@ -0,0 +1,132 @@
+# ====== Code Summary ======
+# Collection metadata-schema operations, mirrored from the DocForge backend: the ``field_ops``
+# discriminated union of a collection PATCH (add / update / remove / rename) and the ``SchemaDiff``
+# every PATCH response carries (applied, or previewed under ``dry_run``).
+
+# ====== Standard Library Imports ======
+from typing import Annotated, Literal
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+# ====== Local Project Imports ======
+from ._shared import FieldOrigin, FieldScope, FieldType
+from .field_spec import FieldSpec
+
+
+class FieldPatch(BaseModel):
+    """
+    The attributes an ``update`` op changes — only the keys set are sent (null clears).
+
+    Attributes:
+        field_type / required / filterable / lexical / semantic / enum_values / origin / scope /
+            description: The new value of each attribute to change.
+    """
+
+    field_type: FieldType | None = Field(default=None, description="New value type.")
+    required: bool | None = Field(default=None, description="New upload-required flag.")
+    filterable: bool | None = Field(default=None, description="New filterable flag.")
+    lexical: bool | None = Field(default=None, description="New lexical (BM25 vector) flag.")
+    semantic: bool | None = Field(default=None, description="New semantic (dense vector) flag.")
+    enum_values: list[str] | None = Field(
+        default=None, description="New allowed values (enum fields)."
+    )
+    origin: FieldOrigin | None = Field(default=None, description="New origin (user/generated).")
+    scope: FieldScope | None = Field(default=None, description="New scope (document/chunk).")
+    description: str | None = Field(
+        default=None, max_length=1000, description="New description (explicit null clears it)."
+    )
+
+
+class AddFieldOp(BaseModel):
+    """Add a new field (its name must not already exist)."""
+
+    op: Literal["add"] = Field(description="Operation tag.")
+    field: FieldSpec = Field(description="The full definition of the new field.")
+
+
+class UpdateFieldOp(BaseModel):
+    """Change some attributes of an existing field in place (its stored values are kept)."""
+
+    op: Literal["update"] = Field(description="Operation tag.")
+    field_name: str = Field(description="The existing field to update.")
+    changes: FieldPatch = Field(description="The attributes to change (only the keys set apply).")
+
+
+class RemoveFieldOp(BaseModel):
+    """Remove a field — DESTRUCTIVE: its stored document/chunk values are deleted with it."""
+
+    op: Literal["remove"] = Field(description="Operation tag.")
+    field_name: str = Field(description="The existing field to remove.")
+
+
+class RenameFieldOp(BaseModel):
+    """Rename a field in place — its stored values and a ``title_field`` pointing at it follow."""
+
+    op: Literal["rename"] = Field(description="Operation tag.")
+    field_name: str = Field(description="The existing field to rename.")
+    new_name: str = Field(min_length=1, description="Its new name (must not already exist).")
+
+
+FieldOp = Annotated[
+    AddFieldOp | UpdateFieldOp | RemoveFieldOp | RenameFieldOp,
+    Field(discriminator="op"),
+]
+
+
+class SchemaDiffModifiedField(BaseModel):
+    """One field updated in place, with the attributes that changed."""
+
+    field_name: str = Field(description="The field's (post-PATCH) name.")
+    changed_attrs: list[str] = Field(description="The attributes whose value changed.")
+
+
+class SchemaDiffRename(BaseModel):
+    """One field renamed in place (its values are kept)."""
+
+    from_name: str = Field(description="The field's previous name.")
+    to_name: str = Field(description="The field's new name.")
+
+
+class SchemaDiff(BaseModel):
+    """
+    The metadata-schema change of a collection PATCH (applied, or previewed under dry_run).
+
+    Attributes:
+        added (list[str]): Fields created.
+        modified (list[SchemaDiffModifiedField]): Fields updated in place (values kept).
+        removed (list[str]): Fields deleted with their stored values.
+        renamed (list[SchemaDiffRename]): Fields renamed in place (values kept).
+        values_lost (dict[str, int]): Removed field → stored document + chunk values deleted.
+        reindex_required_fields (list[str]): Fields needing a reindex before being searchable.
+    """
+
+    added: list[str] = Field(default_factory=list, description="Fields created.")
+    modified: list[SchemaDiffModifiedField] = Field(
+        default_factory=list, description="Fields updated in place (values kept)."
+    )
+    removed: list[str] = Field(
+        default_factory=list, description="Fields deleted with their stored values."
+    )
+    renamed: list[SchemaDiffRename] = Field(
+        default_factory=list, description="Fields renamed in place (values kept)."
+    )
+    values_lost: dict[str, int] = Field(
+        default_factory=dict, description="Removed field → stored values deleted with it."
+    )
+    reindex_required_fields: list[str] = Field(
+        default_factory=list, description="Fields whose change needs a reindex to be searchable."
+    )
+
+
+__all__ = [
+    "FieldPatch",
+    "AddFieldOp",
+    "UpdateFieldOp",
+    "RemoveFieldOp",
+    "RenameFieldOp",
+    "FieldOp",
+    "SchemaDiff",
+    "SchemaDiffModifiedField",
+    "SchemaDiffRename",
+]

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

@@ -240,16 +240,20 @@ class SearchCost(BaseModel):
 
 class SearchHint(BaseModel):
     """
-    An actionable explanation about one filter, attached to a (200) search response.
+    An actionable explanation attached to a (200) search response — a filter value no document
+    stores, the likely culprit of a filtered zero-hit search, a ``min_score`` that dropped every hit,
+    or a lexical metadata target the query gave no searchable term to.
 
     Attributes:
-        field (str): The filtered metadata field the hint is about.
+        field (str): What the hint is about: a filtered or targeted metadata field, or ``min_score``.
         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.")
+    field: str = Field(
+        description="What the hint is about: a filtered or targeted metadata field, or 'min_score'."
+    )
     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(
@@ -278,7 +282,9 @@ class SearchResponse(BaseModel):
         description="What every hit's ``score`` represents, so the UI labels it honestly: "
         "'rrf_fusion' (Reciprocal Rank Fusion of the dense+sparse branches — the default; "
         "rank-based, not a similarity), 'dbsf_fusion' (Distribution-Based Score Fusion), or "
-        "'cross_encoder_rerank' (a cross-encoder relevance score, when reranking is enabled).",
+        "'cross_encoder_rerank' (a cross-encoder relevance score, when reranking is enabled), "
+        "'raw_dense' (ONE dense vector queried, no fusion — a cosine similarity) or 'raw_sparse' "
+        "(ONE sparse vector — its raw sparse dot / BM25 score, unbounded).",
     )
     cost: SearchCost | None = Field(
         default=None,