docforge-sdk 0.21.2__tar.gz → 0.22.0__tar.gz

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.21.2
+Version: 0.22.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.21.2 → docforge_sdk-0.22.0}/docforge_sdk/__init__.py

@@ -51,7 +51,13 @@ from .models.collections import (
 )
 
 # ------------------- Documents models ------------------- #
-from .models.documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+from .models.documents import (
+    DocumentEnabledResponse,
+    EnabledPatch,
+    MetadataUpdateResponse,
+    MetadataValuesPatch,
+    UploadAccepted,
+)
 
 # ------------------- Estimate models ------------------- #
 from .models.estimate import (
@@ -188,6 +194,8 @@ __all__ = [
     "UploadAccepted",
     "EnabledPatch",
     "DocumentEnabledResponse",
+    "MetadataValuesPatch",
+    "MetadataUpdateResponse",
     # Estimate
     "CollectionEstimateRequest",
     "EstimateAssumptions",

{docforge_sdk-0.21.2 → docforge_sdk-0.22.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.21.2"
+__version__ = "0.22.0"

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/docforge_sdk/models/__init__.py

@@ -55,7 +55,14 @@ from .corpus import (
 )
 
 # ------------------- Documents models ------------------- #
-from .documents import DocumentEnabledResponse, DocumentView, EnabledPatch, UploadAccepted
+from .documents import (
+    DocumentEnabledResponse,
+    DocumentView,
+    EnabledPatch,
+    MetadataUpdateResponse,
+    MetadataValuesPatch,
+    UploadAccepted,
+)
 
 # ------------------- Estimate models ------------------- #
 from .estimate import (
@@ -228,6 +235,8 @@ __all__ = [
     "UploadAccepted",
     "EnabledPatch",
     "DocumentEnabledResponse",
+    "MetadataValuesPatch",
+    "MetadataUpdateResponse",
     "DocumentView",
     # Snippets
     "SNIPPET_FILE_EXTENSION",

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/docforge_sdk/models/documents.py

@@ -5,6 +5,9 @@
 # endpoints stream a raw text body with a Content-Type header rather than a JSON body, mirroring the
 # blobs resource's BlobContent wrapper.
 
+# ====== Standard Library Imports ======
+from typing import Any
+
 # ====== Third-Party Library Imports ======
 from pydantic import BaseModel, Field
 
@@ -49,6 +52,42 @@ class DocumentEnabledResponse(BaseModel):
     enabled: bool = Field(description="The new searchability state.")
 
 
+class MetadataValuesPatch(BaseModel):
+    """
+    The metadata VALUES to write on a document (field_name -> new value), the cheap value-edit.
+
+    Attributes:
+        values (dict[str, Any]): Map of metadata field name -> new value. DOCUMENT-scope USER or
+            GENERATED fields only; a chunk-scope or unknown field is rejected (422). A value's shape
+            must match its field type (scalar, or a list for the *_list types).
+    """
+
+    values: dict[str, Any] = Field(
+        min_length=1,
+        description="Map of metadata field name -> new value (document-scope fields only).",
+    )
+
+
+class MetadataUpdateResponse(BaseModel):
+    """
+    The result of a document metadata value edit.
+
+    Attributes:
+        updated_fields (list[str]): The field names whose values were written.
+        reembedding (bool): True when a changed field feeds a named vector (semantic/lexical) and a
+            re-embed job was enqueued.
+        reembed_fields (list[str]): The changed fields that need their metadata vectors re-embedded.
+        job_id (str | None): The enqueued re-embed job's id, or null when nothing needed re-embedding.
+    """
+
+    updated_fields: list[str] = Field(description="Field names whose values were written.")
+    reembedding: bool = Field(
+        description="A semantic/lexical field changed - a re-embed was queued."
+    )
+    reembed_fields: list[str] = Field(description="Changed fields needing a metadata re-embed.")
+    job_id: str | None = Field(default=None, description="The re-embed job's UUID, or null.")
+
+
 class DocumentView(BaseModel):
     """
     A rendered document view's raw text plus its server-declared media type.
@@ -62,4 +101,11 @@ class DocumentView(BaseModel):
     mime_type: str = Field(description="The media type the server declared for the view.")
 
 
-__all__ = ["UploadAccepted", "EnabledPatch", "DocumentEnabledResponse", "DocumentView"]
+__all__ = [
+    "UploadAccepted",
+    "EnabledPatch",
+    "DocumentEnabledResponse",
+    "MetadataValuesPatch",
+    "MetadataUpdateResponse",
+    "DocumentView",
+]

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/docforge_sdk/resources/documents.py

@@ -10,7 +10,14 @@ from typing import Any
 
 # ====== Local Project Imports ======
 from .._requestspec import RequestSpec
-from ..models.documents import DocumentEnabledResponse, DocumentView, EnabledPatch, UploadAccepted
+from ..models.documents import (
+    DocumentEnabledResponse,
+    DocumentView,
+    EnabledPatch,
+    MetadataUpdateResponse,
+    MetadataValuesPatch,
+    UploadAccepted,
+)
 from ..models.trace import TracePurgeResult
 from ._base import AsyncResource, SyncResource, _ResourceMixin
 
@@ -68,6 +75,14 @@ class _DocumentsSpecs(_ResourceMixin):
             json=EnabledPatch(enabled=enabled).model_dump(mode="json"),
         )
 
+    def _update_metadata_spec(self, document_id: str, values: dict[str, Any]) -> RequestSpec:
+        """A PATCH writing metadata VALUES (document-scope fields) onto one document in place."""
+        return RequestSpec(
+            "PATCH",
+            f"{self._DOCUMENTS_PATH}/{document_id}/metadata",
+            json=MetadataValuesPatch(values=values).model_dump(mode="json"),
+        )
+
     def _reingest_spec(self, document_id: str, force: bool) -> RequestSpec:
         """A POST re-running the full ingestion of one document (``force`` bypasses the doc cache)."""
         return RequestSpec(
@@ -143,6 +158,27 @@ class AsyncDocuments(AsyncResource, _DocumentsSpecs):
             self._set_enabled_spec(document_id, enabled), DocumentEnabledResponse
         )
 
+    async def update_metadata(
+        self, document_id: str, values: dict[str, Any]
+    ) -> MetadataUpdateResponse:
+        """
+        Update a document's metadata VALUES in place (document-scope fields only).
+
+        Filterable changes apply instantly; semantic/lexical changes enqueue a background re-embed
+        whose ``job_id`` can be polled. Unknown/chunk-scope fields or bad values raise a
+        ValidationError (422); an unknown document raises NotFound (404).
+
+        Args:
+            document_id (str): The document to edit.
+            values (dict[str, Any]): Map of metadata field name -> new value (at least one entry).
+
+        Returns:
+            MetadataUpdateResponse: Written fields, whether a re-embed was queued, and its job id.
+        """
+        return await self._transport.request(
+            self._update_metadata_spec(document_id, values), MetadataUpdateResponse
+        )
+
     async def reingest(self, document_id: str, force: bool = False) -> UploadAccepted:
         """
         Re-run the full ingestion of a single document.
@@ -251,6 +287,12 @@ class SyncDocuments(SyncResource, _DocumentsSpecs):
             self._set_enabled_spec(document_id, enabled), DocumentEnabledResponse
         )
 
+    def update_metadata(self, document_id: str, values: dict[str, Any]) -> MetadataUpdateResponse:
+        """Update a document's metadata VALUES in place (a semantic/lexical change queues a re-embed)."""
+        return self._transport.request(
+            self._update_metadata_spec(document_id, values), MetadataUpdateResponse
+        )
+
     def reingest(self, document_id: str, force: bool = False) -> UploadAccepted:
         """Re-run the full ingestion of a single document (``force`` bypasses the doc cache)."""
         return self._transport.request(self._reingest_spec(document_id, force), UploadAccepted)

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/tests/openapi_snapshot.json

@@ -1271,6 +1271,60 @@
                 }
             }
         },
+        "/api/v1/documents/{document_id}/metadata": {
+            "patch": {
+                "tags": [
+                    "documents"
+                ],
+                "summary": "Update Document Metadata",
+                "description": "Edit a document's metadata VALUES in place \u2014 no re-ingest, chunk content untouched.\n\nThe cheap per-document value edit: the new values are validated against the collection's schema,\nwritten to Postgres, and the filterable Qdrant payloads are repainted synchronously (instant, no\nembed). When a CHANGED field feeds a named vector (semantic/lexical), a lightweight worker job is\nenqueued to re-embed ONLY the short metadata values onto the document's points \u2014 the index\nsignature is unchanged, so this never triggers a reindex. Accepts DOCUMENT-scope USER and\nGENERATED fields (a GENERATED override is overwritten again on the next reingest/metagen);\nchunk-scope and unknown fields are rejected with 422.\n\nReturns:\n    MetadataUpdateResponse: The fields that actually changed, whether a re-embed was queued, and\n        the reconciliation job id (set when a semantic/lexical field changed or a filterable\n        repaint needs repair; null otherwise); 404 when the document is unknown.",
+                "operationId": "update_document_metadata_api_v1_documents__document_id__metadata_patch",
+                "parameters": [
+                    {
+                        "name": "document_id",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "uuid",
+                            "title": "Document Id"
+                        }
+                    }
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/MetadataValuesPatch"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/MetadataUpdateResponse"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/documents/{document_id}/trace-payloads/purge": {
             "post": {
                 "tags": [
@@ -9062,6 +9116,51 @@
                 "title": "MetadataFilter",
                 "description": "One dynamic document-metadata predicate, addressed by field name.\n\nAttributes:\n    field (str): The metadata field name (must exist in the collection schema + be filterable).\n    op (str): The comparison \u2014 ``eq``/``contains`` (string/text), ``in`` (membership; matches\n        any element for list-typed fields), ``gte``/``lte`` (int/float/datetime).\n    value (Any): The comparison value, typed by the field (a list for ``in``)."
             },
+            "MetadataUpdateResponse": {
+                "properties": {
+                    "updated_fields": {
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array",
+                        "title": "Updated Fields",
+                        "description": "Field names whose values were written."
+                    },
+                    "reembedding": {
+                        "type": "boolean",
+                        "title": "Reembedding",
+                        "description": "A semantic/lexical field changed \u2014 a re-embed was queued."
+                    },
+                    "reembed_fields": {
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array",
+                        "title": "Reembed Fields",
+                        "description": "Changed fields needing a metadata re-embed."
+                    },
+                    "job_id": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "title": "Job Id",
+                        "description": "The re-embed job's UUID, or null."
+                    }
+                },
+                "type": "object",
+                "required": [
+                    "updated_fields",
+                    "reembedding",
+                    "reembed_fields"
+                ],
+                "title": "MetadataUpdateResponse",
+                "description": "The result of a document metadata value edit.\n\nAttributes:\n    updated_fields (list[str]): The field names whose values were written.\n    reembedding (bool): True when a changed field feeds a named vector (semantic/lexical) and a\n        re-embed job was enqueued.\n    reembed_fields (list[str]): The changed fields that need their metadata vectors re-embedded.\n    job_id (str | None): The enqueued re-embed job's id, or null when nothing needed re-embedding."
+            },
             "MetadataValue": {
                 "properties": {
                     "field_name": {
@@ -9087,6 +9186,24 @@
                 "title": "MetadataValue",
                 "description": "One resolved metadata value \u2014 the field NAME (joined from the collection schema), the stored\nvalue, and the origin that actually filled THIS value (user upload / pipeline / metagen)."
             },
+            "MetadataValuesPatch": {
+                "properties": {
+                    "values": {
+                        "additionalProperties": true,
+                        "type": "object",
+                        "minProperties": 1,
+                        "title": "Values",
+                        "description": "Map of metadata field name \u2192 new value (document-scope fields only)."
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "required": [
+                    "values"
+                ],
+                "title": "MetadataValuesPatch",
+                "description": "The metadata VALUES to write on a document (field_name \u2192 new value), the cheap value-edit.\n\nAttributes:\n    values (dict[str, Any]): Map of metadata field name \u2192 new value. DOCUMENT-scope USER or\n        GENERATED fields only; a chunk-scope or unknown field is rejected (422). A value's shape\n        must match its field type (scalar, or a list for the *_list types)."
+            },
             "ModelRateOverride": {
                 "properties": {
                     "input": {

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/tests/parity_map.py

@@ -44,7 +44,13 @@ from docforge_sdk.models.corpus import (
     Pagination,
     TextFilter,
 )
-from docforge_sdk.models.documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+from docforge_sdk.models.documents import (
+    DocumentEnabledResponse,
+    EnabledPatch,
+    MetadataUpdateResponse,
+    MetadataValuesPatch,
+    UploadAccepted,
+)
 from docforge_sdk.models.estimate import (
     AssumptionOverrides,
     CollectionEstimateRequest,
@@ -197,6 +203,8 @@ MODELS: dict[str, type[BaseModel]] = {
     "UploadAccepted": UploadAccepted,
     "EnabledPatch": EnabledPatch,
     "DocumentEnabledResponse": DocumentEnabledResponse,
+    "MetadataValuesPatch": MetadataValuesPatch,
+    "MetadataUpdateResponse": MetadataUpdateResponse,
     # Corpus grid filters (also reused by CollectionEstimateRequest.filter below).
     "TextFilter": TextFilter,
     "NumberRange": NumberRange,

{docforge_sdk-0.21.2 → docforge_sdk-0.22.0}/tests/route_map.py

@@ -57,6 +57,7 @@ ROUTES: set[tuple[str, str]] = {
     # Documents (upload / toggle / reingest / rendered views) — resources/documents.py
     ("POST", "/api/v1/documents"),
     ("PATCH", "/api/v1/documents/{document_id}/enabled"),
+    ("PATCH", "/api/v1/documents/{document_id}/metadata"),
     ("POST", "/api/v1/documents/{document_id}/reingest"),
     ("POST", "/api/v1/documents/{document_id}/trace-payloads/purge"),
     ("GET", "/api/v1/documents/{document_id}/markdown"),