retab 0.0.89__tar.gz → 0.0.91__tar.gz

{retab-0.0.89 → retab-0.0.91}/PKG-INFO

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

{retab-0.0.89 → retab-0.0.91}/retab/client.py

@@ -10,7 +10,7 @@ import backoff.types
 import httpx
 import truststore
 
-from .resources import documents, models, schemas, projects, extractions, edit, workflows
+from .resources import documents, models, schemas, projects, extractions, edit, workflows, jobs
 from .types.standards import PreparedRequest, FieldUnset
 
 
@@ -190,6 +190,7 @@ class Retab(BaseRetab):
         self.schemas = schemas.Schemas(client=self)
         self.edit = edit.Edit(client=self)
         self.workflows = workflows.Workflows(client=self)
+        self.jobs = jobs.Jobs(client=self)
     def _request(
         self,
         method: str,
@@ -488,6 +489,7 @@ class AsyncRetab(BaseRetab):
         self.schemas = schemas.AsyncSchemas(client=self)
         self.edit = edit.AsyncEdit(client=self)
         self.workflows = workflows.AsyncWorkflows(client=self)
+        self.jobs = jobs.AsyncJobs(client=self)
         
     def _parse_response(self, response: httpx.Response) -> Any:
         """Parse response based on content-type.

{retab-0.0.89 → retab-0.0.91}/retab/resources/documents/client.py

@@ -16,7 +16,8 @@ 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.documents.split import Subdocument, SplitRequest, SplitResponse
+from ...types.documents.classify import Category
 from ...types.documents.classify import ClassifyRequest, ClassifyResponse
 from ...types.mime import MIMEData
 from ...types.standards import PreparedRequest, FieldUnset
@@ -148,21 +149,21 @@ class BaseDocumentsMixin:
     def _prepare_split(
         self,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
-        categories: list[Category] | list[dict[str, str]],
+        subdocuments: list[Subdocument] | 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
+        # Convert dict subdocuments to Subdocument objects if needed
+        subdocument_objects = [
+            Subdocument(**subdoc) if isinstance(subdoc, dict) else subdoc
+            for subdoc in subdocuments
         ]
         
         request_dict: dict[str, Any] = {
             "document": mime_document,
-            "categories": category_objects,
+            "subdocuments": subdocument_objects,
             "model": model,
         }
 
@@ -644,20 +645,20 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
     def split(
         self,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
-        categories: list[Category] | list[dict[str, str]],
+        subdocuments: list[Subdocument] | list[dict[str, str]],
         model: str,
         **extra_body: Any,
     ) -> SplitResponse:
         """
-        Split a document into sections based on provided categories.
+        Split a document into sections based on provided subdocuments.
 
         This method analyzes a multi-page document and classifies pages into 
-        user-defined categories, returning the page ranges for each section.
+        user-defined subdocuments, 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.
+            subdocuments: List of subdocuments to split the document into. Each subdocument should have a 'name' and 'description'.
+                Can be Subdocument objects or dicts with 'name' and 'description' keys.
             model: The AI model to use for document splitting (e.g., "gemini-2.5-flash").
 
         Returns:
@@ -672,7 +673,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
             response = retab.documents.split(
                 document="invoice_batch.pdf",
                 model="gemini-2.5-flash",
-                categories=[
+                subdocuments=[
                     {"name": "invoice", "description": "Invoice documents with billing information"},
                     {"name": "receipt", "description": "Receipt documents for payments"},
                     {"name": "contract", "description": "Legal contract documents"},
@@ -684,7 +685,7 @@ class Documents(SyncAPIResource, BaseDocumentsMixin):
         """
         request = self._prepare_split(
             document=document,
-            categories=categories,
+            subdocuments=subdocuments,
             model=model,
             **extra_body,
         )
@@ -1039,20 +1040,20 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
     async def split(
         self,
         document: Path | str | IOBase | MIMEData | PIL.Image.Image | HttpUrl,
-        categories: list[Category] | list[dict[str, str]],
+        subdocuments: list[Subdocument] | list[dict[str, str]],
         model: str,
         **extra_body: Any,
     ) -> SplitResponse:
         """
-        Split a document into sections based on provided categories asynchronously.
+        Split a document into sections based on provided subdocuments asynchronously.
 
         This method analyzes a multi-page document and classifies pages into 
-        user-defined categories, returning the page ranges for each section.
+        user-defined subdocuments, 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.
+            subdocuments: List of subdocuments to split the document into. Each subdocument should have a 'name' and 'description'.
+                Can be Subdocument objects or dicts with 'name' and 'description' keys.
             model: The AI model to use for document splitting (e.g., "gemini-2.5-flash").
 
         Returns:
@@ -1067,7 +1068,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
             response = await retab.documents.split(
                 document="invoice_batch.pdf",
                 model="gemini-2.5-flash",
-                categories=[
+                subdocuments=[
                     {"name": "invoice", "description": "Invoice documents with billing information"},
                     {"name": "receipt", "description": "Receipt documents for payments"},
                     {"name": "contract", "description": "Legal contract documents"},
@@ -1079,7 +1080,7 @@ class AsyncDocuments(AsyncAPIResource, BaseDocumentsMixin):
         """
         request = self._prepare_split(
             document=document,
-            categories=categories,
+            subdocuments=subdocuments,
             model=model,
             **extra_body,
         )

retab-0.0.91/retab/resources/jobs/__init__.py

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

retab-0.0.91/retab/resources/jobs/client.py

@@ -0,0 +1,252 @@
+"""
+Jobs API Resource
+
+Provides synchronous and asynchronous clients for the Jobs API.
+"""
+
+from typing import Any
+
+from ..._resource import AsyncAPIResource, SyncAPIResource
+from ...types.jobs import Job, JobListResponse, JobStatus, SupportedEndpoint
+from ...types.standards import PreparedRequest
+
+
+class BaseJobsMixin:
+    """Shared methods for preparing Jobs API requests."""
+
+    def _prepare_create(
+        self,
+        endpoint: SupportedEndpoint,
+        request: dict[str, Any],
+        metadata: dict[str, str] | None = None,
+    ) -> PreparedRequest:
+        data = {
+            "endpoint": endpoint,
+            "request": request,
+        }
+        if metadata is not None:
+            data["metadata"] = metadata
+        return PreparedRequest(method="POST", url="/v1/jobs", data=data)
+
+    def _prepare_retrieve(self, job_id: str) -> PreparedRequest:
+        return PreparedRequest(method="GET", url=f"/v1/jobs/{job_id}")
+
+    def _prepare_cancel(self, job_id: str) -> PreparedRequest:
+        return PreparedRequest(method="POST", url=f"/v1/jobs/{job_id}/cancel")
+
+    def _prepare_list(
+        self,
+        after: str | None = None,
+        limit: int = 20,
+        status: JobStatus | None = None,
+    ) -> PreparedRequest:
+        params: dict[str, Any] = {"limit": limit}
+        if after is not None:
+            params["after"] = after
+        if status is not None:
+            params["status"] = status
+        return PreparedRequest(method="GET", url="/v1/jobs", params=params)
+
+
+class Jobs(SyncAPIResource, BaseJobsMixin):
+    """
+    Synchronous Jobs API client.
+
+    The Jobs API allows you to submit long-running extract or parse operations
+    asynchronously and poll for their results.
+
+    Example:
+        >>> from retab import Retab
+        >>> client = Retab(api_key="your-api-key")
+        >>>
+        >>> # Create an async extraction job
+        >>> job = client.jobs.create(
+        ...     endpoint="/v1/documents/extract",
+        ...     request={
+        ...         "document": {"content": "...", "mime_type": "application/pdf"},
+        ...         "json_schema": {"type": "object", ...},
+        ...         "model": "gpt-4o",
+        ...     }
+        ... )
+        >>>
+        >>> # Poll for completion
+        >>> while job.status not in ("completed", "failed", "cancelled"):
+        ...     import time
+        ...     time.sleep(5)
+        ...     job = client.jobs.retrieve(job.id)
+        >>>
+        >>> if job.status == "completed":
+        ...     print(job.response.body)
+    """
+
+    def create(
+        self,
+        endpoint: SupportedEndpoint,
+        request: dict[str, Any],
+        metadata: dict[str, str] | None = None,
+    ) -> Job:
+        """
+        Create a new asynchronous job.
+
+        Args:
+            endpoint: The API endpoint to call ("/v1/documents/extract" or "/v1/documents/parse")
+            request: The full request body for the target endpoint
+            metadata: Optional metadata (max 16 pairs; keys ≤64 chars, values ≤512 chars)
+
+        Returns:
+            Job: The created job with status "queued"
+        """
+        prepared = self._prepare_create(endpoint, request, metadata)
+        response = self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    def retrieve(self, job_id: str) -> Job:
+        """
+        Retrieve a job by ID.
+
+        Args:
+            job_id: The job ID to retrieve
+
+        Returns:
+            Job: The job with current status and result (if completed)
+        """
+        prepared = self._prepare_retrieve(job_id)
+        response = self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    def cancel(self, job_id: str) -> Job:
+        """
+        Cancel a queued or in-progress job.
+
+        Args:
+            job_id: The job ID to cancel
+
+        Returns:
+            Job: The updated job with status "cancelled"
+        """
+        prepared = self._prepare_cancel(job_id)
+        response = self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    def list(
+        self,
+        after: str | None = None,
+        limit: int = 20,
+        status: JobStatus | None = None,
+    ) -> JobListResponse:
+        """
+        List jobs with pagination and optional status filtering.
+
+        Args:
+            after: Pagination cursor (last ID from previous page)
+            limit: Number of jobs to return (1-100, default 20)
+            status: Filter by job status
+
+        Returns:
+            JobListResponse: List of jobs with pagination info
+        """
+        prepared = self._prepare_list(after, limit, status)
+        response = self._client._prepared_request(prepared)
+        return JobListResponse.model_validate(response)
+
+
+class AsyncJobs(AsyncAPIResource, BaseJobsMixin):
+    """
+    Asynchronous Jobs API client.
+
+    The Jobs API allows you to submit long-running extract or parse operations
+    asynchronously and poll for their results.
+
+    Example:
+        >>> from retab import AsyncRetab
+        >>> client = AsyncRetab(api_key="your-api-key")
+        >>>
+        >>> # Create an async extraction job
+        >>> job = await client.jobs.create(
+        ...     endpoint="/v1/documents/extract",
+        ...     request={
+        ...         "document": {"content": "...", "mime_type": "application/pdf"},
+        ...         "json_schema": {"type": "object", ...},
+        ...         "model": "gpt-4o",
+        ...     }
+        ... )
+        >>>
+        >>> # Poll for completion
+        >>> while job.status not in ("completed", "failed", "cancelled"):
+        ...     import asyncio
+        ...     await asyncio.sleep(5)
+        ...     job = await client.jobs.retrieve(job.id)
+        >>>
+        >>> if job.status == "completed":
+        ...     print(job.response.body)
+    """
+
+    async def create(
+        self,
+        endpoint: SupportedEndpoint,
+        request: dict[str, Any],
+        metadata: dict[str, str] | None = None,
+    ) -> Job:
+        """
+        Create a new asynchronous job.
+
+        Args:
+            endpoint: The API endpoint to call ("/v1/documents/extract" or "/v1/documents/parse")
+            request: The full request body for the target endpoint
+            metadata: Optional metadata (max 16 pairs; keys ≤64 chars, values ≤512 chars)
+
+        Returns:
+            Job: The created job with status "queued"
+        """
+        prepared = self._prepare_create(endpoint, request, metadata)
+        response = await self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    async def retrieve(self, job_id: str) -> Job:
+        """
+        Retrieve a job by ID.
+
+        Args:
+            job_id: The job ID to retrieve
+
+        Returns:
+            Job: The job with current status and result (if completed)
+        """
+        prepared = self._prepare_retrieve(job_id)
+        response = await self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    async def cancel(self, job_id: str) -> Job:
+        """
+        Cancel a queued or in-progress job.
+
+        Args:
+            job_id: The job ID to cancel
+
+        Returns:
+            Job: The updated job with status "cancelled"
+        """
+        prepared = self._prepare_cancel(job_id)
+        response = await self._client._prepared_request(prepared)
+        return Job.model_validate(response)
+
+    async def list(
+        self,
+        after: str | None = None,
+        limit: int = 20,
+        status: JobStatus | None = None,
+    ) -> JobListResponse:
+        """
+        List jobs with pagination and optional status filtering.
+
+        Args:
+            after: Pagination cursor (last ID from previous page)
+            limit: Number of jobs to return (1-100, default 20)
+            status: Filter by job status
+
+        Returns:
+            JobListResponse: List of jobs with pagination info
+        """
+        prepared = self._prepare_list(after, limit, status)
+        response = await self._client._prepared_request(prepared)
+        return JobListResponse.model_validate(response)

{retab-0.0.89 → retab-0.0.91}/retab/types/documents/__init__.py

@@ -1,12 +1,14 @@
 from .parse import ParseRequest, ParseResult, RetabUsage
-from .split import Category, SplitRequest, SplitResult, SplitResponse
-from .classify import ClassifyRequest, ClassifyResult, ClassifyResponse
+from .split import Subdocument, SplitRequest, SplitResult, SplitResponse
+from .classify import ClassifyRequest, ClassifyResult, ClassifyResponse, Category
+
 
 __all__ = [
     "ParseRequest", 
     "ParseResult", 
     "RetabUsage",
     "Category",
+    "Subdocument",
     "SplitRequest",
     "SplitResult",
     "SplitResponse",

{retab-0.0.89 → retab-0.0.91}/retab/types/documents/classify.py

@@ -1,13 +1,16 @@
 from pydantic import BaseModel, Field
 from ..mime import MIMEData
-from .split import Category
 
+class Category(BaseModel):
+    name: str = Field(..., description="The name of the category")
+    description: str = Field(..., description="The description of the category")
 
 class ClassifyRequest(BaseModel):
     document: MIMEData = Field(..., description="The document to classify")
     categories: list[Category] = Field(..., description="The categories to classify the document into")
     model: str = Field(default="retab-small", description="The model to use for classification")
     first_n_pages: int | None = Field(default=None, description="Only use the first N pages of the document for classification. Useful for large documents where classification can be determined from early pages.")
+    context: str | None = Field(default=None, description="Additional context for classification (e.g., iteration context from a loop)")
 
 
 class ClassifyResult(BaseModel):

{retab-0.0.89 → retab-0.0.91}/retab/types/documents/split.py

@@ -1,17 +1,17 @@
 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")
-    partition_key: str | None = Field(default=None, description="The key to partition the category")
+class Subdocument(BaseModel):
+    name: str = Field(..., description="The name of the subdocument")
+    description: str = Field(..., description="The description of the subdocument")
+    partition_key: str | None = Field(default=None, description="The key to partition the subdocument")
 
 
 class SplitRequest(BaseModel):
     document: MIMEData = Field(..., description="The document to split")
-    categories: list[Category] = Field(..., description="The categories to split the document into")
+    subdocuments: list[Subdocument] = Field(..., description="The subdocuments to split the document into")
     model: str = Field(default="retab-small", description="The model to use to split the document")
+    context: str | None = Field(default=None, description="Additional context for the split operation (e.g., iteration context from a loop)")
 
 
 class Partition(BaseModel):
@@ -21,9 +21,9 @@ class Partition(BaseModel):
     last_page_y_end: float = Field(default=1.0, description="The y coordinate of the last page of the partition")
 
 class SplitResult(BaseModel):
-    name: str = Field(..., description="The name of the category")
-    pages: list[int] = Field(..., description="The pages of the category (1-indexed)")
-    partitions: list[Partition] = Field(default_factory=list, description="The partitions of the category")
+    name: str = Field(..., description="The name of the subdocument")
+    pages: list[int] = Field(..., description="The pages of the subdocument (1-indexed)")
+    partitions: list[Partition] = Field(default_factory=list, description="The partitions of the subdocument")
 
 
 class SplitResponse(BaseModel):
@@ -32,14 +32,14 @@ class SplitResponse(BaseModel):
 
 class SplitOutputItem(BaseModel):
     """Internal schema item for LLM structured output validation."""
-    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)")
+    name: str = Field(..., description="The name of the subdocument")
+    start_page: int = Field(..., description="The start page of the subdocument (1-indexed)")
+    end_page: int = Field(..., description="The end page of the subdocument (1-indexed, inclusive)")
 
 
 class SplitOutputSchema(BaseModel):
     """Schema for LLM structured output."""
     splits: list[SplitOutputItem] = Field(
         ...,
-        description="List of document sections, each classified into one of the provided categories with their page ranges"
+        description="List of document sections, each classified into one of the provided subdocuments with their page ranges"
     )

retab-0.0.91/retab/types/jobs.py

@@ -0,0 +1,90 @@
+"""
+Jobs API Types
+
+Pydantic models for the asynchronous Jobs API.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+JobStatus = Literal[
+    "validating",
+    "queued",
+    "in_progress",
+    "completed",
+    "failed",
+    "cancelled",
+    "expired",
+]
+
+SupportedEndpoint = Literal[
+    "/v1/documents/extract",
+    "/v1/documents/parse",
+    "/v1/documents/split",
+    "/v1/documents/classify",
+    "/v1/schemas/generate",
+    "/v1/edit/agent/fill",
+    "/v1/edit/templates/fill",
+    "/v1/edit/templates/generate",
+    "/v1/projects/extract",  # Requires "project_id" in request body
+]
+
+
+class JobResponse(BaseModel):
+    """Response stored when job completes successfully."""
+    status_code: int
+    body: dict[str, Any]
+
+
+class JobError(BaseModel):
+    """Error details when job fails."""
+    code: str
+    message: str
+    details: dict[str, Any] | None = None
+
+
+class Job(BaseModel):
+    """
+    Job object representing an asynchronous operation.
+
+    Use this to track the status of long-running operations like extract, parse,
+    split, classify, schema generation, and template operations.
+    """
+    id: str
+    object: Literal["job"] = "job"
+    status: JobStatus
+    endpoint: SupportedEndpoint
+    request: dict[str, Any]
+    response: JobResponse | None = None
+    error: JobError | None = None
+
+    # Timestamps (Unix timestamps)
+    created_at: int
+    started_at: int | None = None
+    completed_at: int | None = None
+    expires_at: int
+
+    # User context
+    organization_id: str
+    metadata: dict[str, str] | None = None
+
+
+class CreateJobRequest(BaseModel):
+    """Request body for creating a new job."""
+    endpoint: SupportedEndpoint
+    request: dict[str, Any]
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description="Max 16 pairs; keys ≤64 chars, values ≤512 chars"
+    )
+
+
+class JobListResponse(BaseModel):
+    """Response for listing jobs."""
+    object: Literal["list"] = "list"
+    data: list[Job]
+    first_id: str | None = None
+    last_id: str | None = None
+    has_more: bool = False

{retab-0.0.89 → retab-0.0.91}/retab.egg-info/PKG-INFO

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

{retab-0.0.89 → retab-0.0.91}/retab.egg-info/SOURCES.txt

@@ -24,6 +24,8 @@ retab/resources/edit/templates/__init__.py
 retab/resources/edit/templates/client.py
 retab/resources/extractions/__init__.py
 retab/resources/extractions/client.py
+retab/resources/jobs/__init__.py
+retab/resources/jobs/client.py
 retab/resources/projects/__init__.py
 retab/resources/projects/client.py
 retab/resources/workflows/__init__.py
@@ -33,6 +35,7 @@ retab/resources/workflows/runs/client.py
 retab/types/__init__.py
 retab/types/chat.py
 retab/types/inference_settings.py
+retab/types/jobs.py
 retab/types/mime.py
 retab/types/modality.py
 retab/types/pagination.py

{retab-0.0.89 → retab-0.0.91}/setup.py

@@ -6,7 +6,7 @@ with open("requirements.txt") as f:
 
 setup(
     name="retab",
-    version="0.0.89",
+    version="0.0.91",
     author="Retab",
     author_email="contact@retab.com",
     description="Retab official python library",