retab 0.0.81__py3-none-any.whl → 0.0.83__py3-none-any.whl

retab/client.py

@@ -10,7 +10,7 @@ import backoff.types
 import httpx
 import truststore
 
-from .resources import documents, models, schemas, projects, extractions
+from .resources import documents, models, schemas, projects, extractions, edit
 from .types.standards import PreparedRequest, FieldUnset
 
 
@@ -188,6 +188,7 @@ class Retab(BaseRetab):
         self.documents = documents.Documents(client=self)
         self.models = models.Models(client=self)
         self.schemas = schemas.Schemas(client=self)
+        self.edit = edit.Edit(client=self)
 
     def _request(
         self,
@@ -485,6 +486,7 @@ class AsyncRetab(BaseRetab):
         self.documents = documents.AsyncDocuments(client=self)
         self.models = models.AsyncModels(client=self)
         self.schemas = schemas.AsyncSchemas(client=self)
+        self.edit = edit.AsyncEdit(client=self)
 
     def _parse_response(self, response: httpx.Response) -> Any:
         """Parse response based on content-type.

retab/resources/documents/client.py

@@ -119,14 +119,14 @@ class BaseDocumentsMixin:
 
     def _prepare_edit(
         self,
-        filling_instructions: str,
+        instructions: str,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
         model: str = FieldUnset,
         template_id: str | None = FieldUnset,
         **extra_body: Any,
     ) -> PreparedRequest:
         request_dict: dict[str, Any] = {
-            "filling_instructions": filling_instructions,
+            "instructions": instructions,
         }
         
         if document is not None:
@@ -598,7 +598,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
 
     def edit(
         self,
-        filling_instructions: str,
+        instructions: str,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
         model: str = FieldUnset,
         template_id: str | None = FieldUnset,
@@ -616,7 +616,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         Either `document` OR `template_id` must be provided, but not both.
 
         Args:
-            filling_instructions: Instructions describing how to fill the form fields.
+            instructions: Instructions describing how to fill the form fields.
             document: The document to edit. Can be a file path (Path or str), file-like object, MIMEData, PIL Image, or URL.
                 Mutually exclusive with template_id.
             model: The LLM model to use for inference. Defaults to "retab-small".
@@ -632,7 +632,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
             HTTPException: If the request fails.
         """
         request = self._prepare_edit(
-            filling_instructions=filling_instructions,
+            instructions=instructions,
             document=document,
             model=model,
             template_id=template_id,
@@ -993,7 +993,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
 
     async def edit(
         self,
-        filling_instructions: str,
+        instructions: str,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
         model: str = FieldUnset,
         template_id: str | None = FieldUnset,
@@ -1011,7 +1011,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         Either `document` OR `template_id` must be provided, but not both.
 
         Args:
-            filling_instructions: Instructions describing how to fill the form fields.
+            instructions: Instructions describing how to fill the form fields.
             document: The document to edit. Can be a file path (Path or str), file-like object, MIMEData, PIL Image, or URL.
                 Mutually exclusive with template_id.
             model: The LLM model to use for inference. Defaults to "gemini-2.5-pro".
@@ -1027,7 +1027,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
             HTTPException: If the request fails.
         """
         request = self._prepare_edit(
-            filling_instructions=filling_instructions,
+            instructions=instructions,
             document=document,
             model=model,
             template_id=template_id,

retab/resources/edit/__init__.py

@@ -0,0 +1,3 @@
+from .client import Edit, AsyncEdit
+
+__all__ = ["Edit", "AsyncEdit"]

retab/resources/edit/client.py

@@ -0,0 +1,176 @@
+"""
+Edit SDK client - Wrapper for document editing functionality.
+"""
+
+from io import IOBase
+from pathlib import Path
+from typing import Any
+
+import PIL.Image
+from pydantic import HttpUrl
+
+from ..._resource import AsyncAPIResource, SyncAPIResource
+from ...utils.mime import prepare_mime_document
+from ...types.documents.edit import (
+    EditRequest,
+    EditResponse,
+)
+from ...types.mime import MIMEData
+from ...types.standards import PreparedRequest, FieldUnset
+from .templates import Templates, AsyncTemplates
+
+
+class BaseEditMixin:
+    """Shared methods for preparing edit API requests."""
+
+    def _prepare_fill_document(
+        self,
+        instructions: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
+        model: str = FieldUnset,
+        template_id: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        request_dict: dict[str, Any] = {
+            "instructions": instructions,
+        }
+
+        if document is not None:
+            mime_document = prepare_mime_document(document)
+            request_dict["document"] = mime_document
+
+        if model is not FieldUnset:
+            request_dict["model"] = model
+        if template_id is not FieldUnset:
+            request_dict["template_id"] = template_id
+
+        # Merge any extra fields provided by the caller
+        if extra_body:
+            request_dict.update(extra_body)
+
+        edit_request = EditRequest(**request_dict)
+        return PreparedRequest(
+            method="POST",
+            url="/v1/edit/fill-document",
+            data=edit_request.model_dump(mode="json", exclude_unset=True),
+        )
+
+
+class Edit(SyncAPIResource, BaseEditMixin):
+    """Edit API wrapper for synchronous usage."""
+
+    def __init__(self, client: Any) -> None:
+        super().__init__(client=client)
+        self.templates = Templates(client=client)
+
+    def fill_document(
+        self,
+        instructions: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
+        model: str = FieldUnset,
+        template_id: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> EditResponse:
+        """
+        Edit a document by inferring form fields and filling them with provided instructions.
+
+        This method performs:
+        1. Detection to identify form field bounding boxes
+        2. LLM inference to name and describe detected fields
+        3. LLM-based form filling using the provided instructions
+        4. Returns the filled document with form field values populated
+
+        Either `document` OR `template_id` must be provided, but not both.
+
+        Args:
+            instructions: Instructions describing how to fill the form fields.
+            document: The document to edit. Can be a file path (Path or str), file-like object,
+                MIMEData, PIL Image, or URL. Mutually exclusive with template_id.
+            model: The LLM model to use for inference. Defaults to "retab-small".
+            template_id: Template ID to use for filling. When provided, uses the template's
+                pre-defined form fields and empty PDF. Only works for PDF documents.
+                Mutually exclusive with document.
+
+        Returns:
+            EditResponse: Response containing:
+                - form_data: List of form fields with filled values
+                - filled_document: Document with filled form values (MIMEData)
+
+        Raises:
+            HTTPException: If the request fails.
+
+        Supported document formats:
+            - PDF: Native form field detection and filling
+            - DOCX/DOC: Native editing to preserve styles and formatting
+            - PPTX/PPT: Native editing for presentations
+            - XLSX/XLS: Native editing for spreadsheets
+        """
+        request = self._prepare_fill_document(
+            instructions=instructions,
+            document=document,
+            model=model,
+            template_id=template_id,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return EditResponse.model_validate(response)
+
+
+class AsyncEdit(AsyncAPIResource, BaseEditMixin):
+    """Edit API wrapper for asynchronous usage."""
+
+    def __init__(self, client: Any) -> None:
+        super().__init__(client=client)
+        self.templates = AsyncTemplates(client=client)
+
+    async def fill_document(
+        self,
+        instructions: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl | None = None,
+        model: str = FieldUnset,
+        template_id: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> EditResponse:
+        """
+        Edit a document by inferring form fields and filling them with provided instructions asynchronously.
+
+        This method performs:
+        1. Detection to identify form field bounding boxes
+        2. LLM inference to name and describe detected fields
+        3. LLM-based form filling using the provided instructions
+        4. Returns the filled document with form field values populated
+
+        Either `document` OR `template_id` must be provided, but not both.
+
+        Args:
+            instructions: Instructions describing how to fill the form fields.
+            document: The document to edit. Can be a file path (Path or str), file-like object,
+                MIMEData, PIL Image, or URL. Mutually exclusive with template_id.
+            model: The LLM model to use for inference. Defaults to "retab-small".
+            template_id: Template ID to use for filling. When provided, uses the template's
+                pre-defined form fields and empty PDF. Only works for PDF documents.
+                Mutually exclusive with document.
+
+        Returns:
+            EditResponse: Response containing:
+                - form_data: List of form fields with filled values
+                - filled_document: Document with filled form values (MIMEData)
+
+        Raises:
+            HTTPException: If the request fails.
+
+        Supported document formats:
+            - PDF: Native form field detection and filling
+            - DOCX/DOC: Native editing to preserve styles and formatting
+            - PPTX/PPT: Native editing for presentations
+            - XLSX/XLS: Native editing for spreadsheets
+        """
+        request = self._prepare_fill_document(
+            instructions=instructions,
+            document=document,
+            model=model,
+            template_id=template_id,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return EditResponse.model_validate(response)

retab/resources/edit/templates/__init__.py

@@ -0,0 +1,4 @@
+from .client import Templates, AsyncTemplates
+
+__all__ = ["Templates", "AsyncTemplates"]
+

retab/resources/edit/templates/client.py

@@ -0,0 +1,620 @@
+"""
+Edit Templates SDK client - Wrapper for edit template management.
+"""
+
+from io import IOBase
+from pathlib import Path
+from typing import Any, Literal, List
+
+import PIL.Image
+from pydantic import HttpUrl
+
+from ...._resource import AsyncAPIResource, SyncAPIResource
+from ....utils.mime import prepare_mime_document
+from ....types.documents.edit import (
+    FormField,
+    InferFormSchemaRequest,
+    InferFormSchemaResponse,
+    EditResponse,
+)
+from ....types.edit.templates import EditTemplate, FillTemplateRequest
+from ....types.mime import MIMEData
+from ....types.standards import PreparedRequest, FieldUnset
+from ....types.pagination import PaginatedList
+
+
+class BaseTemplatesMixin:
+    """Shared methods for preparing template API requests."""
+
+    def _prepare_list(
+        self,
+        before: str | None = None,
+        after: str | None = None,
+        limit: int = 10,
+        order: Literal["asc", "desc"] = "desc",
+        filename: str | None = None,
+        mime_type: str | None = None,
+        **extra_params: Any,
+    ) -> PreparedRequest:
+        params: dict[str, Any] = {
+            "limit": limit,
+            "order": order,
+        }
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+        if filename:
+            params["filename"] = filename
+        if mime_type:
+            params["mime_type"] = mime_type
+        if extra_params:
+            params.update(extra_params)
+
+        return PreparedRequest(
+            method="GET",
+            url="/v1/edit/templates",
+            params=params,
+        )
+
+    def _prepare_get(self, template_id: str) -> PreparedRequest:
+        return PreparedRequest(
+            method="GET",
+            url=f"/v1/edit/templates/{template_id}",
+        )
+
+    def _prepare_create(
+        self,
+        name: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        form_fields: list[FormField],
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        mime_document = prepare_mime_document(document)
+        
+        request_dict: dict[str, Any] = {
+            "name": name,
+            "document": mime_document,
+            "form_fields": [f.model_dump() if hasattr(f, 'model_dump') else f for f in form_fields],
+        }
+        if extra_body:
+            request_dict.update(extra_body)
+
+        return PreparedRequest(
+            method="POST",
+            url="/v1/edit/templates",
+            data=request_dict,
+        )
+
+    def _prepare_update(
+        self,
+        template_id: str,
+        name: str | None = None,
+        form_fields: list[FormField] | None = None,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        request_dict: dict[str, Any] = {}
+        if name is not None:
+            request_dict["name"] = name
+        if form_fields is not None:
+            request_dict["form_fields"] = [f.model_dump() if hasattr(f, 'model_dump') else f for f in form_fields]
+        if extra_body:
+            request_dict.update(extra_body)
+
+        return PreparedRequest(
+            method="PATCH",
+            url=f"/v1/edit/templates/{template_id}",
+            data=request_dict,
+        )
+
+    def _prepare_delete(self, template_id: str) -> PreparedRequest:
+        return PreparedRequest(
+            method="DELETE",
+            url=f"/v1/edit/templates/{template_id}",
+        )
+
+    def _prepare_duplicate(
+        self,
+        template_id: str,
+        name: str | None = None,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        request_dict: dict[str, Any] = {}
+        if name is not None:
+            request_dict["name"] = name
+        if extra_body:
+            request_dict.update(extra_body)
+
+        return PreparedRequest(
+            method="POST",
+            url=f"/v1/edit/templates/{template_id}/duplicate",
+            data=request_dict,
+        )
+
+    def _prepare_generate(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        model: str = FieldUnset,
+        instructions: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        mime_document = prepare_mime_document(document)
+
+        request_dict: dict[str, Any] = {
+            "document": mime_document,
+        }
+
+        if model is not FieldUnset:
+            request_dict["model"] = model
+        if instructions is not FieldUnset:
+            request_dict["instructions"] = instructions
+        if extra_body:
+            request_dict.update(extra_body)
+
+        infer_request = InferFormSchemaRequest(**request_dict)
+        return PreparedRequest(
+            method="POST",
+            url="/v1/edit/templates/generate",
+            data=infer_request.model_dump(mode="json", exclude_unset=True),
+        )
+
+    def _prepare_fill(
+        self,
+        template_id: str,
+        instructions: str,
+        model: str = FieldUnset,
+        **extra_body: Any,
+    ) -> PreparedRequest:
+        request_dict: dict[str, Any] = {
+            "template_id": template_id,
+            "instructions": instructions,
+        }
+
+        if model is not FieldUnset:
+            request_dict["model"] = model
+        if extra_body:
+            request_dict.update(extra_body)
+
+        fill_request = FillTemplateRequest(**request_dict)
+        return PreparedRequest(
+            method="POST",
+            url="/v1/edit/templates/fill",
+            data=fill_request.model_dump(mode="json", exclude_unset=True),
+        )
+
+
+class Templates(SyncAPIResource, BaseTemplatesMixin):
+    """Templates API wrapper for synchronous usage."""
+
+    def __init__(self, client: Any) -> None:
+        super().__init__(client=client)
+
+    def list(
+        self,
+        before: str | None = None,
+        after: str | None = None,
+        limit: int = 10,
+        order: Literal["asc", "desc"] = "desc",
+        filename: str | None = None,
+        mime_type: str | None = None,
+        **extra_params: Any,
+    ) -> PaginatedList:
+        """
+        List edit templates with pagination and optional filtering.
+
+        Args:
+            before: Cursor for backward pagination
+            after: Cursor for forward pagination
+            limit: Number of items per page (1-100, default 10)
+            order: Sort order ("asc" or "desc", default "desc")
+            filename: Filter by filename (partial match)
+            mime_type: Filter by MIME type
+
+        Returns:
+            PaginatedList: Paginated list of templates (data contains EditTemplate objects)
+        """
+        request = self._prepare_list(
+            before=before,
+            after=after,
+            limit=limit,
+            order=order,
+            filename=filename,
+            mime_type=mime_type,
+            **extra_params,
+        )
+        response = self._client._prepared_request(request)
+        return PaginatedList.model_validate(response)
+
+    def get(self, template_id: str) -> EditTemplate:
+        """
+        Get a specific edit template by ID.
+
+        Args:
+            template_id: The template ID to retrieve
+
+        Returns:
+            EditTemplate: The template details
+        """
+        request = self._prepare_get(template_id)
+        response = self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    def create(
+        self,
+        name: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        form_fields: List[FormField],
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Create a new edit template.
+
+        Args:
+            name: Name of the template
+            document: The PDF document to use as the template
+            form_fields: List of form fields in the template
+
+        Returns:
+            EditTemplate: The created template
+        """
+        request = self._prepare_create(
+            name=name,
+            document=document,
+            form_fields=form_fields,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    def update(
+        self,
+        template_id: str,
+        name: str | None = None,
+        form_fields: List[FormField] | None = None,
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Update an existing edit template.
+
+        Args:
+            template_id: The template ID to update
+            name: New name for the template (optional)
+            form_fields: New form fields (optional)
+
+        Returns:
+            EditTemplate: The updated template
+        """
+        request = self._prepare_update(
+            template_id=template_id,
+            name=name,
+            form_fields=form_fields,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    def delete(self, template_id: str) -> None:
+        """
+        Delete an edit template.
+
+        Args:
+            template_id: The template ID to delete
+        """
+        request = self._prepare_delete(template_id)
+        self._client._prepared_request(request)
+
+    def duplicate(
+        self,
+        template_id: str,
+        name: str | None = None,
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Duplicate an existing edit template.
+
+        Args:
+            template_id: The template ID to duplicate
+            name: Name for the duplicated template (defaults to "<original> (copy)")
+
+        Returns:
+            EditTemplate: The duplicated template
+        """
+        request = self._prepare_duplicate(
+            template_id=template_id,
+            name=name,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    def generate(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        model: str = FieldUnset,
+        instructions: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> InferFormSchemaResponse:
+        """
+        Infer form schema from a PDF document.
+
+        This method combines computer vision for precise bounding box detection
+        with LLM for semantic field naming (key, description) and type classification.
+
+        Args:
+            document: The PDF document to analyze
+            model: The LLM model to use for field naming (default: "retab-small")
+            instructions: Optional instructions to guide form field detection
+
+        Returns:
+            InferFormSchemaResponse: Response containing:
+                - form_schema: The detected form schema
+                - annotated_pdf: PDF with bounding boxes for visual verification
+                - detection_count: Number of fields detected
+
+        Note:
+            Only PDF documents are supported for form schema inference.
+        """
+        request = self._prepare_generate(
+            document=document,
+            model=model,
+            instructions=instructions,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return InferFormSchemaResponse.model_validate(response)
+
+    def fill(
+        self,
+        template_id: str,
+        instructions: str,
+        model: str = FieldUnset,
+        **extra_body: Any,
+    ) -> EditResponse:
+        """
+        Fill a PDF form using a pre-defined template.
+
+        This method uses a template's pre-defined form fields to fill a PDF form,
+        skipping the field detection step for faster processing.
+
+        Args:
+            template_id: The template ID to use for filling
+            instructions: Instructions describing how to fill the form fields
+            model: The LLM model to use for inference (default: "retab-small")
+
+        Returns:
+            EditResponse: Response containing:
+                - form_data: List of form fields with filled values
+                - filled_document: The filled PDF document as MIMEData
+
+        Use cases:
+            - Batch processing of the same form with different data
+            - Faster form filling when field detection is already done
+            - Consistent field mapping across multiple fills
+        """
+        request = self._prepare_fill(
+            template_id=template_id,
+            instructions=instructions,
+            model=model,
+            **extra_body,
+        )
+        response = self._client._prepared_request(request)
+        return EditResponse.model_validate(response)
+
+
+class AsyncTemplates(AsyncAPIResource, BaseTemplatesMixin):
+    """Templates API wrapper for asynchronous usage."""
+
+    def __init__(self, client: Any) -> None:
+        super().__init__(client=client)
+
+    async def list(
+        self,
+        before: str | None = None,
+        after: str | None = None,
+        limit: int = 10,
+        order: Literal["asc", "desc"] = "desc",
+        filename: str | None = None,
+        mime_type: str | None = None,
+        **extra_params: Any,
+    ) -> PaginatedList:
+        """
+        List edit templates with pagination and optional filtering.
+
+        Args:
+            before: Cursor for backward pagination
+            after: Cursor for forward pagination
+            limit: Number of items per page (1-100, default 10)
+            order: Sort order ("asc" or "desc", default "desc")
+            filename: Filter by filename (partial match)
+            mime_type: Filter by MIME type
+
+        Returns:
+            PaginatedList: Paginated list of templates (data contains EditTemplate objects)
+        """
+        request = self._prepare_list(
+            before=before,
+            after=after,
+            limit=limit,
+            order=order,
+            filename=filename,
+            mime_type=mime_type,
+            **extra_params,
+        )
+        response = await self._client._prepared_request(request)
+        return PaginatedList.model_validate(response)
+
+    async def get(self, template_id: str) -> EditTemplate:
+        """
+        Get a specific edit template by ID.
+
+        Args:
+            template_id: The template ID to retrieve
+
+        Returns:
+            EditTemplate: The template details
+        """
+        request = self._prepare_get(template_id)
+        response = await self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    async def create(
+        self,
+        name: str,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        form_fields: List[FormField],
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Create a new edit template.
+
+        Args:
+            name: Name of the template
+            document: The PDF document to use as the template
+            form_fields: List of form fields in the template
+
+        Returns:
+            EditTemplate: The created template
+        """
+        request = self._prepare_create(
+            name=name,
+            document=document,
+            form_fields=form_fields,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    async def update(
+        self,
+        template_id: str,
+        name: str | None = None,
+        form_fields: List[FormField] | None = None,
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Update an existing edit template.
+
+        Args:
+            template_id: The template ID to update
+            name: New name for the template (optional)
+            form_fields: New form fields (optional)
+
+        Returns:
+            EditTemplate: The updated template
+        """
+        request = self._prepare_update(
+            template_id=template_id,
+            name=name,
+            form_fields=form_fields,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    async def delete(self, template_id: str) -> None:
+        """
+        Delete an edit template.
+
+        Args:
+            template_id: The template ID to delete
+        """
+        request = self._prepare_delete(template_id)
+        await self._client._prepared_request(request)
+
+    async def duplicate(
+        self,
+        template_id: str,
+        name: str | None = None,
+        **extra_body: Any,
+    ) -> EditTemplate:
+        """
+        Duplicate an existing edit template.
+
+        Args:
+            template_id: The template ID to duplicate
+            name: Name for the duplicated template (defaults to "<original> (copy)")
+
+        Returns:
+            EditTemplate: The duplicated template
+        """
+        request = self._prepare_duplicate(
+            template_id=template_id,
+            name=name,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return EditTemplate.model_validate(response)
+
+    async def generate(
+        self,
+        document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
+        model: str = FieldUnset,
+        instructions: str | None = FieldUnset,
+        **extra_body: Any,
+    ) -> InferFormSchemaResponse:
+        """
+        Infer form schema from a PDF document asynchronously.
+
+        This method combines computer vision for precise bounding box detection
+        with LLM for semantic field naming (key, description) and type classification.
+
+        Args:
+            document: The PDF document to analyze
+            model: The LLM model to use for field naming (default: "retab-small")
+            instructions: Optional instructions to guide form field detection
+
+        Returns:
+            InferFormSchemaResponse: Response containing:
+                - form_schema: The detected form schema
+                - annotated_pdf: PDF with bounding boxes for visual verification
+                - detection_count: Number of fields detected
+
+        Note:
+            Only PDF documents are supported for form schema inference.
+        """
+        request = self._prepare_generate(
+            document=document,
+            model=model,
+            instructions=instructions,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return InferFormSchemaResponse.model_validate(response)
+
+    async def fill(
+        self,
+        template_id: str,
+        instructions: str,
+        model: str = FieldUnset,
+        **extra_body: Any,
+    ) -> EditResponse:
+        """
+        Fill a PDF form using a pre-defined template asynchronously.
+
+        This method uses a template's pre-defined form fields to fill a PDF form,
+        skipping the field detection step for faster processing.
+
+        Args:
+            template_id: The template ID to use for filling
+            instructions: Instructions describing how to fill the form fields
+            model: The LLM model to use for inference (default: "retab-small")
+
+        Returns:
+            EditResponse: Response containing:
+                - form_data: List of form fields with filled values
+                - filled_document: The filled PDF document as MIMEData
+
+        Use cases:
+            - Batch processing of the same form with different data
+            - Faster form filling when field detection is already done
+            - Consistent field mapping across multiple fills
+        """
+        request = self._prepare_fill(
+            template_id=template_id,
+            instructions=instructions,
+            model=model,
+            **extra_body,
+        )
+        response = await self._client._prepared_request(request)
+        return EditResponse.model_validate(response)
+

retab/types/documents/edit.py

@@ -64,7 +64,7 @@ class BaseFormField(BaseModel):
         ...,
         description="Key of the field. This is used to identify the field in the form data.",
     )
-    
+
 
 class FormField(BaseFormField):
     """Single field in the form schema (text input, checkbox, etc.)."""
@@ -72,8 +72,8 @@ class FormField(BaseFormField):
     value: Optional[str] = Field(
         None,
         description=(
-            "Current or default value of the field as text. "
-            "May be null/None if no value is set."
+            "Filled value of the field as text. "
+            "May be null/None if no filled value is set."
         ),
     )
 
@@ -88,18 +88,6 @@ class FormSchema(BaseModel):
         ),
     )
 
-class FilledFormField(BaseFormField):
-    """Single field in the form schema (text input, checkbox, etc.)."""
-
-    value: Optional[str] = Field(
-        None,
-        description=(
-            "Filled value of the field as text. "
-            "May be null/None if no filled value is set."
-        ),
-    )
-
-
 class OCRTextElement(BaseModel):
     """A single OCR-detected text element with its bounding box."""
     
@@ -124,14 +112,6 @@ class InferFormSchemaRequest(BaseModel):
     instructions: Optional[str] = Field(default=None, description="Optional instructions to guide form field detection (e.g., which fields to focus on, specific areas to look for)")
 
 
-class InferFormSchemaResponse(BaseModel):
-    """Response containing the inferred form schema."""
-    
-    form_schema: FormSchema = Field(..., description="The inferred form schema")
-    ocr_result: OCRResult = Field(..., description="The OCR results used for inference")
-    form_fields_pdf: MIMEData = Field(..., description="PDF with form field bounding boxes")
-
-
 class EditRequest(BaseModel):
     """Request for the infer_and_fill_schema endpoint.
     
@@ -141,13 +121,13 @@ class EditRequest(BaseModel):
     """
     document: Optional[MIMEData] = Field(default=None, description="Input document (PDF or DOCX). DOCX files will be converted to PDF. Mutually exclusive with template_id.")
     model: str = Field(default="retab-small", description="LLM model to use for inference")
-    filling_instructions: str = Field(..., description="Instructions to fill the form")
+    instructions: str = Field(..., description="Instructions to fill the form")
     template_id: Optional[str] = Field(default=None, description="Template ID to use for filling. When provided, uses the template's pre-defined form fields and empty PDF. Only works for PDF documents. Mutually exclusive with document.")
 
 class EditResponse(BaseModel):
     """Response from the fill_form endpoint.
     """
-    form_data: list[FilledFormField] = Field(
+    form_data: list[FormField] = Field(
         ...,
         description=(
             "List of form fields (with positions, descriptions, and metadata) "
@@ -162,3 +142,11 @@ class ProcessOCRRequest(BaseModel):
     
     document: MIMEData = Field(..., description="Input document (PDF)")
 
+
+class InferFormSchemaResponse(BaseModel):
+    """Response from form schema inference."""
+    
+    form_schema: FormSchema = Field(..., description="Form schema with detected bounding boxes and field names")
+    annotated_pdf: MIMEData = Field(..., description="PDF with form field bounding boxes")
+    field_count: int = Field(..., description="Number of fields detected")
+

retab/types/edit/__init__.py

@@ -0,0 +1,16 @@
+from .templates import (
+    EditTemplate,
+    CreateEditTemplateRequest,
+    UpdateEditTemplateRequest,
+    DuplicateEditTemplateRequest,
+    FillTemplateRequest,
+)
+
+__all__ = [
+    "EditTemplate",
+    "CreateEditTemplateRequest",
+    "UpdateEditTemplateRequest",
+    "DuplicateEditTemplateRequest",
+    "FillTemplateRequest",
+]
+

retab/types/edit/templates.py

@@ -0,0 +1,50 @@
+"""Types for edit templates."""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+import datetime
+
+from ..mime import BaseMIMEData, MIMEData
+from ..documents.edit import FormField
+
+
+class EditTemplate(BaseModel):
+    """An edit template with pre-defined form fields."""
+    
+    id: str = Field(..., description="Unique identifier of the template")
+    name: str = Field(..., description="Name of the template")
+    file: BaseMIMEData = Field(..., description="File information for the empty PDF template")
+    form_fields: list[FormField] = Field(..., description="List of form fields in the template")
+    organization_id: Optional[str] = Field(default=None, description="Organization that owns this template")
+    created_at: datetime.datetime = Field(..., description="Timestamp of creation")
+    updated_at: datetime.datetime = Field(..., description="Timestamp of last update")
+
+
+class CreateEditTemplateRequest(BaseModel):
+    """Request model for creating an edit template."""
+    
+    name: str = Field(..., description="Name of the template")
+    document: MIMEData = Field(..., description="The PDF document to use as the template")
+    form_fields: list[FormField] = Field(..., description="List of form fields in the template")
+
+
+class UpdateEditTemplateRequest(BaseModel):
+    """Request model for updating an edit template."""
+    
+    name: Optional[str] = Field(default=None, description="Name of the template")
+    form_fields: Optional[list[FormField]] = Field(default=None, description="List of form fields")
+
+
+class DuplicateEditTemplateRequest(BaseModel):
+    """Request model for duplicating an edit template."""
+    
+    name: Optional[str] = Field(default=None, description="Name for the duplicated template")
+
+
+class FillTemplateRequest(BaseModel):
+    """Request for the fill endpoint.
+    Uses pre-defined form fields from the template (PDF only)
+    """
+    model: str = Field(default="retab-small", description="LLM model to use for inference")
+    instructions: str = Field(..., description="Instructions to fill the form")
+    template_id: str = Field(..., description="Template ID to use for filling. When provided, uses the template's pre-defined form fields and empty PDF. Only works for PDF documents. Mutually exclusive with document.")

{retab-0.0.81.dist-info → retab-0.0.83.dist-info}/METADATA

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

{retab-0.0.81.dist-info → retab-0.0.83.dist-info}/RECORD

@@ -1,13 +1,17 @@
 retab/__init__.py,sha256=s4GawWTRBYz4VY-CyAV5-ZdFtdw8V5oopGIYm9GgdSo,188
 retab/_resource.py,sha256=JfAU4UTa05ugWfbrpO7fsVr_pFewht99NkoIfK6kBQM,577
-retab/client.py,sha256=fP9dI9YLFRNCqhODB85Gzp_sxhBJ5KF9R3U0qogP0dc,30075
+retab/client.py,sha256=VrOzEtZQPR4uydO8QJJYkMOoAiC1TfPbkXmTnatSQ0w,30172
 retab/generate_types.py,sha256=cUu1IX65uU__MHivmEb_PZtzAi8DYsvppZvcY30hj90,8425
 retab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 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=E8v0aBF4-9ATYo5hkQ629OP5mm2AtodTzznlj2xRWtQ,49000
+retab/resources/documents/client.py,sha256=0ZOJojT4M9QZ53nheS_vuNZWcnmwTnKx3YqYyJ7_sGY,48912
+retab/resources/edit/__init__.py,sha256=yycIstpTSKsz2qXbrY3Buzd35UDcPWvb5hw6Eb2rLow,69
+retab/resources/edit/client.py,sha256=osWvuKj2SNH6-nQKsWcTYcm3jVENGlwGTvDnT45nDBY,6649
+retab/resources/edit/templates/__init__.py,sha256=n-zA_HXo7iGgeIclSwcsxmSueXJIRMo0iZjk_sax85I,90
+retab/resources/edit/templates/client.py,sha256=Eevzy5JaQmG5-hEshugQvrhgIBAjgZ8ZYZkpBSKEdBQ,19729
 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
@@ -25,10 +29,12 @@ retab/types/documents/__init__.py,sha256=t1jXdpYqi-zQMC_9uM0m7eA1hRU0MCROwUx89cc
 retab/types/documents/classify.py,sha256=Tb6d_7kuTlWLr7bPn782dHrjtUVBCvXV3o9zm7j2lmE,1128
 retab/types/documents/correct_orientation.py,sha256=e-ivsslI6L6Gl0YkcslXw_DH620xMGEYVp4tdeviXeM,261
 retab/types/documents/create_messages.py,sha256=Uym0SnVUGkyt1C5AOD37BsZ3puyeu_igR6X9SboojfA,7267
-retab/types/documents/edit.py,sha256=ZY-a_Q9Y76e4oojeJJsisoCZbNSU6gqwAgb9fq9S76w,5930
+retab/types/documents/edit.py,sha256=4VK9ed1CF179r8sU4pZXcJhKftorGhul9q-5BlM1Ik4,5606
 retab/types/documents/extract.py,sha256=x_59fm69-icsxxGRgpFd0NN-SLRoMYqbvfCZuG7zyGc,18033
 retab/types/documents/parse.py,sha256=MXe7zh3DusWQhGe0Sr95nPy6cB8DRX8MA4Hmjj_AP7E,1300
 retab/types/documents/split.py,sha256=xRdJ6IpSRAPi_ZtAG2FNqg5A-v5tzfb1QQkW5UfO2pY,1246
+retab/types/edit/__init__.py,sha256=M8hF97h7fX8RP9IsB6qpkw0eyvO0DFQvP6FmWL8caCQ,331
+retab/types/edit/templates.py,sha256=4ndnk-MlJE7roP_YktgxLpRSd68hdwNDWiqAFMy0Ddo,2291
 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
@@ -49,7 +55,7 @@ retab/utils/hashing.py,sha256=_BMVUvftOcJav68QL0rLkH2dbhW9RRJPzeGC2akR0fc,757
 retab/utils/json_schema.py,sha256=zP4pQLpVHBKWo_abCjb_dU4kA0azhHopd-1TFUgVEvc,20655
 retab/utils/mime.py,sha256=mTP_lqSPttOP5DYJxopiWaeFXrUCPjhwd7y53nCVGO4,6189
 retab/utils/stream_context_managers.py,sha256=gI1gVQSj3nWz6Mvjz7Ix5AiY0g6vSL-c2tPfuP04izo,2314
-retab-0.0.81.dist-info/METADATA,sha256=1dsE31zFzslvv3Up5BOM62auWgQNbLCie0hZ2NfwP5Y,4532
-retab-0.0.81.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-retab-0.0.81.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
-retab-0.0.81.dist-info/RECORD,,
+retab-0.0.83.dist-info/METADATA,sha256=2fC7uK_AP2G2o6m0-PDITV3A12TB-UMETQ-V51WwxB0,4532
+retab-0.0.83.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+retab-0.0.83.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
+retab-0.0.83.dist-info/RECORD,,