retab 0.0.76__py3-none-any.whl → 0.0.77__py3-none-any.whl

retab/resources/documents/client.py

@@ -16,6 +16,7 @@ from ...types.chat import ChatCompletionRetabMessage
 from ...types.documents.edit import EditRequest, EditResponse
 from ...types.documents.extract import DocumentExtractRequest, RetabParsedChatCompletion, RetabParsedChatCompletionChunk, RetabParsedChoice, maybe_parse_to_pydantic
 from ...types.documents.parse import ParseRequest, ParseResult, TableParsingFormat
+from ...types.documents.split import Category, SplitRequest, SplitResponse
 from ...types.mime import MIMEData
 from ...types.standards import PreparedRequest, FieldUnset
 from ...utils.json_schema import load_json_schema, unflatten_dict
@@ -138,11 +139,39 @@ class BaseDocumentsMixin:
         edit_request = EditRequest(**request_dict)
         return PreparedRequest(method="POST", url="/v1/documents/edit", data=edit_request.model_dump(mode="json", exclude_unset=True))
 
+    def _prepare_split(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        categories: list[Category] | list[dict[str, str]],
+        model: str,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        mime_document = prepare_mime_document(document)
+        
+        # Convert dict categories to Category objects if needed
+        category_objects = [
+            Category(**cat) if isinstance(cat, dict) else cat
+            for cat in categories
+        ]
+        
+        request_dict: dict[str, Any] = {
+            "document": mime_document,
+            "categories": category_objects,
+            "model": model,
+        }
+
+        # Merge any extra fields provided by the caller
+        if extra_body:
+            request_dict.update(extra_body)
+
+        split_request = SplitRequest(**request_dict)
+        return PreparedRequest(method="POST", url="/v1/documents/split", data=split_request.model_dump(mode="json", exclude_unset=True))
+
     def _prepare_extract(
         self,
         json_schema: dict[str, Any] | Path | str,
         model: str,
-        document: Path | str | IOBase | HttpUrl,
+        document: Path | str | IOBase | HttpUrl | MIMEData,
         image_resolution_dpi: int = FieldUnset,
         temperature: float = FieldUnset,
         reasoning_effort: ChatCompletionReasoningEffort = FieldUnset,
@@ -261,7 +290,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         self,
         json_schema: dict[str, Any] | Path | str,
         model: str,
-        document: Path | str | IOBase | HttpUrl,
+        document: Path | str | IOBase | HttpUrl | MIMEData,
         image_resolution_dpi: int = FieldUnset,
         temperature: float = FieldUnset,
         reasoning_effort: ChatCompletionReasoningEffort = FieldUnset,
@@ -279,7 +308,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         Args:
             json_schema: JSON schema defining the expected data structure
             model: The AI model to use for processing
-            document: Document to process (file path, URL, or file-like object)
+            document: Document to process (file path, URL, file-like object, or MIMEData)
             image_resolution_dpi: Optional image resolution DPI
             temperature: Model temperature setting (0-1)
             reasoning_effort: The effort level for the model to reason about the input data
@@ -405,7 +434,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         self,
         json_schema: dict[str, Any] | Path | str,
         model: str,
-        document: Path | str | IOBase | HttpUrl,
+        document: Path | str | IOBase | HttpUrl | MIMEData,
         image_resolution_dpi: int = FieldUnset,
         temperature: float = FieldUnset,
         reasoning_effort: ChatCompletionReasoningEffort = FieldUnset,
@@ -571,6 +600,56 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         response = self._client._prepared_request(request)
         return EditResponse.model_validate(response)
 
+    def split(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        categories: list[Category] | list[dict[str, str]],
+        model: str,
+        **extra_body: Any,
+    ) -> SplitResponse:
+        """
+        Split a document into sections based on provided categories.
+
+        This method analyzes a multi-page document and classifies pages into 
+        user-defined categories, returning the page ranges for each section.
+
+        Args:
+            document: The document to split. Can be a file path (Path or str), file-like object, MIMEData, PIL Image, or URL.
+            categories: List of categories to split the document into. Each category should have a 'name' and 'description'.
+                Can be Category objects or dicts with 'name' and 'description' keys.
+            model: The AI model to use for document splitting (e.g., "gemini-2.5-flash").
+
+        Returns:
+            SplitResponse: Response containing:
+                - splits: List of SplitResult objects with name, start_page, and end_page for each section.
+
+        Raises:
+            HTTPException: If the request fails.
+
+        Example:
+            ```python
+            response = retab.documents.split(
+                document="invoice_batch.pdf",
+                model="gemini-2.5-flash",
+                categories=[
+                    {"name": "invoice", "description": "Invoice documents with billing information"},
+                    {"name": "receipt", "description": "Receipt documents for payments"},
+                    {"name": "contract", "description": "Legal contract documents"},
+                ]
+            )
+            for split in response.splits:
+                print(f"{split.name}: pages {split.start_page}-{split.end_page}")
+            ```
+        """
+        request = self._prepare_split(
+            document=document,
+            categories=categories,
+            model=model,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return SplitResponse.model_validate(response)
+
 
 class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
     """Documents API wrapper for asynchronous usage."""
@@ -637,7 +716,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         self,
         json_schema: dict[str, Any] | Path | str,
         model: str,
-        document: Path | str | IOBase | HttpUrl,
+        document: Path | str | IOBase | HttpUrl | MIMEData,
         image_resolution_dpi: int = FieldUnset,
         temperature: float = FieldUnset,
         reasoning_effort: ChatCompletionReasoningEffort = FieldUnset,
@@ -655,7 +734,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         Args:
             json_schema: JSON schema defining the expected data structure
             model: The AI model to use for processing
-            document: Document to process (file path, URL, or file-like object)
+            document: Document to process (file path, URL, file-like object, or MIMEData)
             image_resolution_dpi: Optional image resolution DPI
             temperature: Model temperature setting (0-1)
             reasoning_effort: The effort level for the model to reason about the input data
@@ -693,7 +772,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         self,
         json_schema: dict[str, Any] | Path | str,
         model: str,
-        document: Path | str | IOBase | HttpUrl,
+        document: Path | str | IOBase | HttpUrl | MIMEData,
         image_resolution_dpi: int = FieldUnset,
         temperature: float = FieldUnset,
         reasoning_effort: ChatCompletionReasoningEffort = FieldUnset,
@@ -709,7 +788,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         Args:
             json_schema: JSON schema defining the expected data structure.
             model: The AI model to use.
-            document: Document to process (file path, URL, or file-like object)
+            document: Document to process (file path, URL, file-like object, or MIMEData)
             image_resolution_dpi: Optional image resolution DPI.
             temperature: Model temperature setting (0-1).
             reasoning_effort: The effort level for the model to reason about the input data.
@@ -857,3 +936,53 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         )
         response = await self._client._prepared_request(request)
         return EditResponse.model_validate(response)
+
+    async def split(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        categories: list[Category] | list[dict[str, str]],
+        model: str,
+        **extra_body: Any,
+    ) -> SplitResponse:
+        """
+        Split a document into sections based on provided categories asynchronously.
+
+        This method analyzes a multi-page document and classifies pages into 
+        user-defined categories, returning the page ranges for each section.
+
+        Args:
+            document: The document to split. Can be a file path (Path or str), file-like object, MIMEData, PIL Image, or URL.
+            categories: List of categories to split the document into. Each category should have a 'name' and 'description'.
+                Can be Category objects or dicts with 'name' and 'description' keys.
+            model: The AI model to use for document splitting (e.g., "gemini-2.5-flash").
+
+        Returns:
+            SplitResponse: Response containing:
+                - splits: List of SplitResult objects with name, start_page, and end_page for each section.
+
+        Raises:
+            HTTPException: If the request fails.
+
+        Example:
+            ```python
+            response = await retab.documents.split(
+                document="invoice_batch.pdf",
+                model="gemini-2.5-flash",
+                categories=[
+                    {"name": "invoice", "description": "Invoice documents with billing information"},
+                    {"name": "receipt", "description": "Receipt documents for payments"},
+                    {"name": "contract", "description": "Legal contract documents"},
+                ]
+            )
+            for split in response.splits:
+                print(f"{split.name}: pages {split.start_page}-{split.end_page}")
+            ```
+        """
+        request = self._prepare_split(
+            document=document,
+            categories=categories,
+            model=model,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return SplitResponse.model_validate(response)

retab/types/documents/__init__.py

@@ -1,3 +1,12 @@
 from .parse import ParseRequest, ParseResult, RetabUsage
+from .split import Category, SplitRequest, SplitResult, SplitResponse
 
-__all__ = ["ParseRequest", "ParseResult", "RetabUsage"]
+__all__ = [
+    "ParseRequest", 
+    "ParseResult", 
+    "RetabUsage",
+    "Category",
+    "SplitRequest",
+    "SplitResult",
+    "SplitResponse",
+]

retab/types/documents/split.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, Field
+from ..mime import MIMEData
+
+
+class Category(BaseModel):
+    name: str = Field(..., description="The name of the category")
+    description: str = Field(..., description="The description of the category")
+
+
+class SplitRequest(BaseModel):
+    document: MIMEData = Field(..., description="The document to split")
+    categories: list[Category] = Field(..., description="The categories to split the document into")
+    model: str = Field(..., description="The model to use to split the document")
+
+
+class SplitResult(BaseModel):
+    name: str = Field(..., description="The name of the category")
+    start_page: int = Field(..., description="The start page of the category (1-indexed)")
+    end_page: int = Field(..., description="The end page of the category (1-indexed, inclusive)")
+
+
+class SplitResponse(BaseModel):
+    splits: list[SplitResult] = Field(..., description="The list of document splits with their page ranges")
+
+
+
+class SplitOutputSchema(BaseModel):
+    """Schema for LLM structured output."""
+    splits: list[SplitResult] = Field(
+        ..., 
+        description="List of document sections, each classified into one of the provided categories with their page ranges"
+    )

retab/types/schemas/model.py

@@ -103,7 +103,57 @@ def _insert_reasoning_fields_inner(schema: dict[str, Any]) -> tuple[dict[str, An
     return schema, reasoning_desc
 
 
-def filter_auxiliary_fields(data: dict[str, Any], prefixes: list[str] = ["reasoning___"]) -> dict[str, Any]:
+def _insert_quote_fields_inner(schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Inner function that processes a schema and adds source___ fields for leaf nodes with X-SourceQuote: true.
+    Only applies to leaf fields, never to the root.
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    # Create a copy to avoid modifying the original
+    new_schema = copy.deepcopy(schema)
+
+    # Process children recursively
+    if "properties" in new_schema and isinstance(new_schema["properties"], dict):
+        new_props = {}
+        for property_key, property_value in new_schema["properties"].items():
+            updated_prop_schema_value = _insert_quote_fields_inner(property_value)
+            has_quote_field = updated_prop_schema_value.get("X-SourceQuote") is True
+
+            # Check if this property is a leaf with X-SourceQuote: true
+            if has_quote_field:
+                # Add the quote field
+                quote_key = f"source___{property_key}"
+                new_props[quote_key] = {"type": "string", "description": f"The exact quote from the source document that supports the extracted value for '{property_key}'."}
+
+                # Add the quote field to required if the property is required
+                if "required" in new_schema and property_key in new_schema["required"]:
+                    # add the quote field to required just before the property_key
+                    new_schema["required"].insert(new_schema["required"].index(property_key), quote_key)
+
+                # Remove the X-SourceQuote field
+                updated_prop_schema_value.pop("X-SourceQuote", None)
+
+            new_props[property_key] = updated_prop_schema_value
+        new_schema["properties"] = new_props
+
+    elif "items" in new_schema:
+        # Recurse into items if present
+        updated_items = _insert_quote_fields_inner(new_schema["items"])
+        new_schema["items"] = updated_items
+
+    # Process $defs as well
+    if "$defs" in new_schema and isinstance(new_schema["$defs"], dict):
+        new_defs = {}
+        for dk, dv in new_schema["$defs"].items():
+            new_defs[dk] = _insert_quote_fields_inner(dv)
+        new_schema["$defs"] = new_defs
+
+    return new_schema
+
+
+def filter_auxiliary_fields(data: dict[str, Any], prefixes: list[str] = ["reasoning___", "source___"]) -> dict[str, Any]:
     """
     Recursively filters out fields that start with any of the prefixes in `prefixes` from the input data.
     """
@@ -142,6 +192,9 @@ def create_reasoning_schema_without_ref_expansion(json_schema: dict[str, Any]) -
         if "required" in updated_schema:
             updated_schema["required"].append("reasoning___root")
 
+    # Insert quote fields for leaf nodes with X-SourceQuote: true
+    updated_schema = _insert_quote_fields_inner(updated_schema)
+
     # Clean the schema (remove defaults, etc)
     updated_schema = clean_schema(updated_schema, remove_custom_fields=True)
     return updated_schema
@@ -167,6 +220,9 @@ def create_reasoning_schema(json_schema: dict[str, Any]) -> dict[str, Any]:
         if "required" in updated_schema:
             updated_schema["required"].append("reasoning___root")
 
+    # Insert quote fields for leaf nodes with X-SourceQuote: true
+    updated_schema = _insert_quote_fields_inner(updated_schema)
+
     # Clean the schema (remove defaults, etc)
     updated_schema = clean_schema(updated_schema, remove_custom_fields=True)
     return updated_schema
@@ -1118,6 +1174,30 @@ No ambiguities."
 
 ---
 
+## Source Quote Fields
+
+The schema may include source quote fields (`source___*`) for capturing exact quotes from the document that support extracted values. These fields appear as siblings to the fields they document.
+
+Naming:
+- `source___[fieldname]` for each field marked with X-SourceQuote in the schema
+
+Guidelines:
+- Extract the exact verbatim text from the document that supports the extracted value.
+- Include surrounding context when helpful for verification.
+- For missing data, use an empty string `""`.
+- These fields are internal and omitted from final outputs.
+
+### Example
+If extracting a company name with source quote:
+```json
+{
+  "source___company_name": "Registered Office: ACME Corporation Ltd",
+  "company_name": "ACME Corporation Ltd"
+}
+```
+
+---
+
 ## Extraction Principles
 
 - **Transparency**: Justify every decision with evidence.

retab/utils/json_schema.py

@@ -368,7 +368,7 @@ def convert_basemodel_to_partial_basemodel(base_model: Type[BaseModel]) -> Type[
 
 
 
-def filter_auxiliary_fields(data: dict[str, Any], prefixes: list[str] = ["reasoning___", "quote___"]) -> dict[str, Any]:
+def filter_auxiliary_fields(data: dict[str, Any], prefixes: list[str] = ["reasoning___", "source___"]) -> dict[str, Any]:
     """
     Recursively filters out fields that start with any of the prefixes in `prefixes` from the input data.
     """
@@ -388,7 +388,7 @@ def filter_auxiliary_fields(data: dict[str, Any], prefixes: list[str] = ["reason
     return filtered
 
 
-def filter_auxiliary_fields_json(data: str, prefixes: list[str] = ["reasoning___", "quote___"]) -> dict[str, Any]:
+def filter_auxiliary_fields_json(data: str, prefixes: list[str] = ["reasoning___", "source___"]) -> dict[str, Any]:
     """
     Recursively filters out fields that start with any of the prefixes in `prefixes` from the input JSON data.
     """

{retab-0.0.76.dist-info → retab-0.0.77.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: retab
-Version: 0.0.76
+Version: 0.0.77
 Summary: Retab official python library
 Home-page: https://github.com/retab-dev/retab
 Author: Retab

{retab-0.0.76.dist-info → retab-0.0.77.dist-info}/RECORD

@@ -7,7 +7,7 @@ retab/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 retab/resources/models.py,sha256=4WidFBnTGZEA65DSn2pLP2SRnCVXkMTw7o_m8xVCFC4,2469
 retab/resources/schemas.py,sha256=rZ6OzfmoYv-mGaRVzvXjO09dD-KxP74mZhOO8sMgcDQ,4632
 retab/resources/documents/__init__.py,sha256=OjXmngFN0RKqO4SI-mJBNzr6Ex6rMxfq0DxaqzP0RQs,89
-retab/resources/documents/client.py,sha256=Dd5xfuwNaF2T-K1I4jx5sBiZdzfg0n_hgWYB76mQXF8,37106
+retab/resources/documents/client.py,sha256=xiHZPvaxETqZGXanOzp1zFQBcSB7WlgiXGtiv6Ys1dQ,42496
 retab/resources/extractions/__init__.py,sha256=2H1ezUG8hI5SmTRy6NFzXdYLOdGFFsFrI60uzkitV20,97
 retab/resources/extractions/client.py,sha256=sEoNjOgX91FTOgoJUV-I1A9A9xl1ciCdPlhYwjhEjbA,11035
 retab/resources/projects/__init__.py,sha256=tPR3_3tr7bsoYd618qmGjnYN2R23PmF5oCFd7Z5_HGY,85
@@ -19,12 +19,13 @@ retab/types/mime.py,sha256=ZLNCD3pvgn5cbGfJwzrdkjgB9dMHCbN67YEV9bx47zE,10063
 retab/types/modality.py,sha256=4B8LctdUBZVgIjtS2FjrJpljn2Eyse0XE1bpFsGb9O4,131
 retab/types/pagination.py,sha256=A0Fw06baPTfEaYwo3kvNs4vaupzlqylBc6tQH-2DFuY,279
 retab/types/standards.py,sha256=7aGtuvzzkKidvqY8JB2Cjfn43V80FeKwrTtp162kjKc,1477
-retab/types/documents/__init__.py,sha256=RaD6PnvRJw7QEVTh_PYNX6gckpLcxUJH7FKaopRKJzY,114
+retab/types/documents/__init__.py,sha256=YDsvsmwkS5lfGXk5aBqSqmFh6LKX3dM6q_cUo5oIydU,277
 retab/types/documents/correct_orientation.py,sha256=e-ivsslI6L6Gl0YkcslXw_DH620xMGEYVp4tdeviXeM,261
 retab/types/documents/create_messages.py,sha256=Cox0QgIyLhTXIvw1Nzd2BCnB9-5KAYgw_gads5eTaDw,7272
 retab/types/documents/edit.py,sha256=HjDjhHlj08Kks7ABVohTrAJ9QngDgwVj32AxXitjrv0,4804
 retab/types/documents/extract.py,sha256=DhS9jm0lUgXVLObKm2CnSJQ2eqMmsBfttO0K9TndfIw,16728
 retab/types/documents/parse.py,sha256=Jd6i-1UXhAtgntRBZItEHGHeevyLdLmbTQa1-HNrico,1305
+retab/types/documents/split.py,sha256=Sjp2u7Ob6nBRQL23RlgiabgyUmoyf8aEyr7zdvUdU-M,1228
 retab/types/extractions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 retab/types/extractions/types.py,sha256=mnCYSfJoEKsXN2eG-PrahnnQyR6RDjP5VO9sHC1Opmg,102
 retab/types/projects/__init__.py,sha256=I7P_dems5_LOLgYQ-4Bzt9B6P6jRlQwP-D_9GxRDhVk,155
@@ -35,17 +36,15 @@ retab/types/schemas/__init__.py,sha256=9ODWiC_4pUVKxoIKglYZjvRjRyd1ZCVxG8GBdQgHN
 retab/types/schemas/chat.py,sha256=ppTidxsNslTKE5aBva04i9IxeARMqYpXYLjtR7V6pBc,21219
 retab/types/schemas/generate.py,sha256=8c9LzFgsG9BpteKzjPaLJEneEHsjCyYvGo1jdko-DI4,743
 retab/types/schemas/layout.py,sha256=JLPwQGIWfPBoe1Y5r-MhiNDJigzZ-yKZnVGgox0uqMk,1487
-retab/types/schemas/model.py,sha256=MwiSrck_5NCDvxjDSqgiDtmenGowXnfoOZ7KTINKW34,69588
+retab/types/schemas/model.py,sha256=kIMB1C_q7YjYJeVV3y06n3m_ebCGSLXyjDs34Ye-oes,72863
 retab/types/schemas/templates.py,sha256=XihWTHi6t_6QjxN07n_1dee5KdhHiuoHAYfmKwI7gQg,1708
 retab/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 retab/utils/display.py,sha256=ZFPbiBnwEWGR-suS8e9Xilz9OqyYRDwsKYWfbFSJPJM,18868
 retab/utils/hashing.py,sha256=_BMVUvftOcJav68QL0rLkH2dbhW9RRJPzeGC2akR0fc,757
-retab/utils/json_schema.py,sha256=IKG0-i6pCxoLb1hrx4yDsKUQCACeA9a_m5zkaChjqJI,19581
+retab/utils/json_schema.py,sha256=F3MLNGskpfPh1IkXHPLp60ceOEFD79GyL8mVvr0OiVM,19583
 retab/utils/mime.py,sha256=mTP_lqSPttOP5DYJxopiWaeFXrUCPjhwd7y53nCVGO4,6189
 retab/utils/stream_context_managers.py,sha256=gI1gVQSj3nWz6Mvjz7Ix5AiY0g6vSL-c2tPfuP04izo,2314
-retab/utils/usage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-retab/utils/usage/json_schema.py,sha256=kRbL5E5OStlhlNlBXlxHNwaVHKd6MVhyqIb0y4aj8JA,84322
-retab-0.0.76.dist-info/METADATA,sha256=IiRP1ihP1AumbF8koszJ8ock6hSgE1FbHv6lJPmiib0,4532
-retab-0.0.76.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-retab-0.0.76.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
-retab-0.0.76.dist-info/RECORD,,
+retab-0.0.77.dist-info/METADATA,sha256=F2-lc5_Am2m8rqSaVLrlsp0Uwdhe1pLZmiwcplBM9KA,4532
+retab-0.0.77.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+retab-0.0.77.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
+retab-0.0.77.dist-info/RECORD,,