retab 0.0.89__py3-none-any.whl → 0.0.90__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, 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/resources/jobs/__init__.py

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

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/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.dist-info → retab-0.0.90.dist-info}/METADATA

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

{retab-0.0.89.dist-info → retab-0.0.90.dist-info}/RECORD

@@ -1,6 +1,6 @@
 retab/__init__.py,sha256=s4GawWTRBYz4VY-CyAV5-ZdFtdw8V5oopGIYm9GgdSo,188
 retab/_resource.py,sha256=JfAU4UTa05ugWfbrpO7fsVr_pFewht99NkoIfK6kBQM,577
-retab/client.py,sha256=ExQLR-xwFKIwqA1DoH3JxI1BU2RB7kWAiMbwR073w1c,30311
+retab/client.py,sha256=Ds-Sy3ynN9GusN5rDrc2ogX3ATv-Dq1MuiZeDnLOWGk,30408
 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
@@ -16,6 +16,8 @@ retab/resources/edit/templates/__init__.py,sha256=n-zA_HXo7iGgeIclSwcsxmSueXJIRM
 retab/resources/edit/templates/client.py,sha256=kEyqat5I84_QBeWSjptteSwvlMGRZ1UF9KDzH7p0f9s,20173
 retab/resources/extractions/__init__.py,sha256=2H1ezUG8hI5SmTRy6NFzXdYLOdGFFsFrI60uzkitV20,97
 retab/resources/extractions/client.py,sha256=sEoNjOgX91FTOgoJUV-I1A9A9xl1ciCdPlhYwjhEjbA,11035
+retab/resources/jobs/__init__.py,sha256=g7WnNAw69CExMSyfxU9ROcSj-KODjxeLe2YlUqi8l0c,69
+retab/resources/jobs/client.py,sha256=Cf7bafUzECqCXbCeKW396Q4fRFOMgjKDtgQ3e_ThIQY,8115
 retab/resources/projects/__init__.py,sha256=tPR3_3tr7bsoYd618qmGjnYN2R23PmF5oCFd7Z5_HGY,85
 retab/resources/projects/client.py,sha256=5LPAhJt5-nqBP4VWYvo0k7cW6HLGF6K9xMiHKQzIXho,15593
 retab/resources/workflows/__init__.py,sha256=-I0QNX7XKEr8ZJTV4-awMyKxZqGlSkKMdibiHiB7cZ0,89
@@ -25,6 +27,7 @@ retab/resources/workflows/runs/client.py,sha256=GopedV363XnGl0mL3bZHWaOay12uAeTq
 retab/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 retab/types/chat.py,sha256=x9VbtPMa4w6Gc0HrFC3ILl6cCnfEn5ytDnwJtZmlcys,1436
 retab/types/inference_settings.py,sha256=wIivYffvEE7v6lhbjbhAZGssK4uYr64Oq6cZKxzY5_M,1131
+retab/types/jobs.py,sha256=iVCl2EmlvvgvdO217gOGqvkuX-38le89C9XR7gnEb3E,2086
 retab/types/mime.py,sha256=ZLNCD3pvgn5cbGfJwzrdkjgB9dMHCbN67YEV9bx47zE,10063
 retab/types/modality.py,sha256=4B8LctdUBZVgIjtS2FjrJpljn2Eyse0XE1bpFsGb9O4,131
 retab/types/pagination.py,sha256=A0Fw06baPTfEaYwo3kvNs4vaupzlqylBc6tQH-2DFuY,279
@@ -59,7 +62,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.89.dist-info/METADATA,sha256=1ppp_sgtdC53grfu4xxD91N_-BDa7FBdofWz_Vd1WTw,4532
-retab-0.0.89.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-retab-0.0.89.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
-retab-0.0.89.dist-info/RECORD,,
+retab-0.0.90.dist-info/METADATA,sha256=ea40JF37wk3xxuQRUv17mvliwsqiOHP8ufyna9ScpyY,4532
+retab-0.0.90.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+retab-0.0.90.dist-info/top_level.txt,sha256=waQR0EGdhLIQtztoE3AXg7ik5ONQ9q_bsKVpyFuJdq0,6
+retab-0.0.90.dist-info/RECORD,,