leapocr 0.0.1__py3-none-any.whl

leapocr/__init__.py

@@ -0,0 +1,91 @@
+"""LeapOCR Python SDK - Transform documents into structured data using AI-powered OCR.
+
+Example:
+    >>> import asyncio
+    >>> from leapocr import LeapOCR, ProcessOptions, Format
+    >>>
+    >>> async def main():
+    ...     async with LeapOCR("your-api-key") as client:
+    ...         result = await client.ocr.process_and_wait(
+    ...             "document.pdf",
+    ...             options=ProcessOptions(format=Format.MARKDOWN)
+    ...         )
+    ...         print(f"Processed {result.total_pages} pages")
+    >>>
+    >>> asyncio.run(main())
+"""
+
+__version__ = "0.1.0"
+
+# Core client
+from .client import LeapOCR
+
+# Configuration
+from .config import ClientConfig
+
+# Errors
+from .errors import (
+    APIError,
+    AuthenticationError,
+    FileError,
+    InsufficientCreditsError,
+    JobError,
+    JobFailedError,
+    JobTimeoutError,
+    LeapOCRError,
+    NetworkError,
+    RateLimitError,
+    ValidationError,
+)
+
+# Models and enums
+from .models import (
+    BatchResult,
+    Format,
+    JobResult,
+    JobStatus,
+    JobStatusType,
+    Model,
+    ModelInfo,
+    PageMetadata,
+    PageResult,
+    PaginationInfo,
+    PollOptions,
+    ProcessOptions,
+    ProcessResult,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Client
+    "LeapOCR",
+    # Configuration
+    "ClientConfig",
+    # Models
+    "Format",
+    "Model",
+    "JobStatusType",
+    "ProcessOptions",
+    "PollOptions",
+    "ProcessResult",
+    "JobStatus",
+    "JobResult",
+    "PageResult",
+    "PageMetadata",
+    "PaginationInfo",
+    "ModelInfo",
+    "BatchResult",
+    # Errors
+    "LeapOCRError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "FileError",
+    "JobError",
+    "JobFailedError",
+    "JobTimeoutError",
+    "NetworkError",
+    "APIError",
+    "InsufficientCreditsError",
+]

leapocr/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal utilities for LeapOCR SDK."""

leapocr/_internal/polling.py

@@ -0,0 +1,130 @@
+"""Status polling utilities for long-running OCR jobs."""
+
+import asyncio
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Callable
+
+from ..errors import JobFailedError, JobTimeoutError
+from ..models import JobStatusType, PollOptions
+
+if TYPE_CHECKING:
+    from ..models import JobStatus
+
+
+async def poll_until_done(
+    get_status_fn: Callable[[str], "JobStatus"],
+    job_id: str,
+    options: PollOptions | None = None,
+) -> None:
+    """Poll job status until completion or failure.
+
+    Args:
+        get_status_fn: Async function to get job status (takes job_id, returns JobStatus)
+        job_id: Job ID to poll
+        options: Polling options (interval, timeout, callbacks)
+
+    Raises:
+        JobTimeoutError: If job doesn't complete within max_wait
+        JobFailedError: If job processing fails
+    """
+    opts = options or PollOptions()
+    start_time = datetime.now()
+    max_wait_td = timedelta(seconds=opts.max_wait)
+
+    while True:
+        # Check timeout
+        elapsed = datetime.now() - start_time
+        if elapsed > max_wait_td:
+            raise JobTimeoutError(
+                f"Job {job_id} did not complete within {opts.max_wait} seconds",
+                job_id=job_id,
+            )
+
+        # Get current status
+        status = await get_status_fn(job_id)
+
+        # Call progress callback if provided
+        if opts.on_progress:
+            try:
+                opts.on_progress(status)
+            except Exception:
+                # Don't let callback errors stop polling
+                pass
+
+        # Check if job is complete
+        if status.status == JobStatusType.COMPLETED:
+            return
+
+        # Check if job failed
+        if status.status == JobStatusType.FAILED:
+            error_msg = status.error_message or "Job processing failed"
+            raise JobFailedError(error_msg, job_id=job_id, error_details=status.error_message)
+
+        # Wait before next poll
+        await asyncio.sleep(opts.poll_interval)
+
+
+async def poll_with_backoff(
+    get_status_fn: Callable[[str], "JobStatus"],
+    job_id: str,
+    initial_interval: float = 1.0,
+    max_interval: float = 30.0,
+    backoff_multiplier: float = 1.5,
+    max_wait: float = 300.0,
+    on_progress: Callable[["JobStatus"], None] | None = None,
+) -> None:
+    """Poll job status with exponential backoff.
+
+    Starts with short intervals and gradually increases delay to reduce
+    API load for long-running jobs.
+
+    Args:
+        get_status_fn: Async function to get job status
+        job_id: Job ID to poll
+        initial_interval: Starting poll interval in seconds (default: 1.0)
+        max_interval: Maximum poll interval in seconds (default: 30.0)
+        backoff_multiplier: Interval multiplier after each poll (default: 1.5)
+        max_wait: Maximum total wait time in seconds (default: 300.0)
+        on_progress: Optional callback for progress updates
+
+    Raises:
+        JobTimeoutError: If job doesn't complete within max_wait
+        JobFailedError: If job processing fails
+    """
+    start_time = datetime.now()
+    max_wait_td = timedelta(seconds=max_wait)
+    current_interval = initial_interval
+
+    while True:
+        # Check timeout
+        elapsed = datetime.now() - start_time
+        if elapsed > max_wait_td:
+            raise JobTimeoutError(
+                f"Job {job_id} did not complete within {max_wait} seconds",
+                job_id=job_id,
+            )
+
+        # Get current status
+        status = await get_status_fn(job_id)
+
+        # Call progress callback if provided
+        if on_progress:
+            try:
+                on_progress(status)
+            except Exception:
+                pass
+
+        # Check if job is complete
+        if status.status == JobStatusType.COMPLETED:
+            return
+
+        # Check if job failed
+        if status.status == JobStatusType.FAILED:
+            error_msg = status.error_message or "Job processing failed"
+            raise JobFailedError(error_msg, job_id=job_id, error_details=status.error_message)
+
+        # Wait with current interval
+        await asyncio.sleep(current_interval)
+
+        # Increase interval for next iteration (exponential backoff)
+        current_interval = min(current_interval * backoff_multiplier, max_interval)

leapocr/_internal/retry.py

@@ -0,0 +1,101 @@
+"""Retry logic with exponential backoff for LeapOCR SDK."""
+
+import asyncio
+from collections.abc import Awaitable
+from typing import Callable, TypeVar
+
+from ..errors import LeapOCRError, NetworkError, RateLimitError
+
+T = TypeVar("T")
+
+
+def is_retryable_error(error: Exception) -> bool:
+    """Check if an error should be retried.
+
+    Args:
+        error: Exception to check
+
+    Returns:
+        True if the error is retryable, False otherwise
+    """
+    # Rate limit errors are retryable
+    if isinstance(error, RateLimitError):
+        return True
+
+    # Network errors are retryable
+    if isinstance(error, NetworkError):
+        return True
+
+    # SDK errors with 5xx status codes are retryable
+    if isinstance(error, LeapOCRError):
+        if error.status_code and 500 <= error.status_code < 600:
+            return True
+
+    # Check for httpx errors
+    try:
+        import httpx
+
+        if isinstance(error, (httpx.TimeoutException, httpx.NetworkError)):
+            return True
+        if isinstance(error, httpx.HTTPStatusError):
+            return error.response.status_code >= 500
+    except ImportError:
+        pass
+
+    return False
+
+
+async def with_retry(
+    operation: Callable[[], Awaitable[T]],
+    max_retries: int = 3,
+    retry_delay: float = 1.0,
+    retry_multiplier: float = 2.0,
+    is_retryable: Callable[[Exception], bool] | None = None,
+) -> T:
+    """Execute an async operation with exponential backoff retry.
+
+    Args:
+        operation: Async function to execute
+        max_retries: Maximum number of retry attempts (default: 3)
+        retry_delay: Initial delay between retries in seconds (default: 1.0)
+        retry_multiplier: Multiplier for exponential backoff (default: 2.0)
+        is_retryable: Optional function to determine if error is retryable
+
+    Returns:
+        Result from the operation
+
+    Raises:
+        The last exception if all retries are exhausted
+    """
+    is_retryable_fn = is_retryable or is_retryable_error
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return await operation()
+        except Exception as error:
+            last_error = error
+
+            # Don't retry on last attempt
+            if attempt == max_retries:
+                raise
+
+            # Check if error is retryable
+            if not is_retryable_fn(error):
+                raise
+
+            # Calculate delay with exponential backoff
+            if isinstance(error, RateLimitError) and error.retry_after:
+                # Use server-provided retry-after if available
+                delay = float(error.retry_after)
+            else:
+                # Exponential backoff: delay * (multiplier ^ attempt)
+                delay = retry_delay * (retry_multiplier**attempt)
+
+            # Wait before retry
+            await asyncio.sleep(delay)
+
+    # Should never reach here, but just in case
+    if last_error:
+        raise last_error
+    raise RuntimeError("Retry loop completed without success or error")

leapocr/_internal/upload.py

@@ -0,0 +1,118 @@
+"""File upload utilities for multipart S3 uploads."""
+
+from typing import Any, BinaryIO
+
+import httpx
+
+from ..errors import FileError, NetworkError
+from .validation import get_file_size, guess_content_type
+
+
+class MultipartUploader:
+    """Handle multipart file uploads to S3 via presigned URLs.
+
+    This class manages the upload of file parts to S3 using presigned URLs
+    returned from the LeapOCR API.
+    """
+
+    def __init__(self, timeout: float = 300.0):
+        """Initialize the uploader.
+
+        Args:
+            timeout: Timeout for upload requests in seconds (default: 5 minutes)
+        """
+        # Separate HTTP client for S3 uploads (no auth needed, different domain)
+        self._s3_client = httpx.AsyncClient(timeout=timeout)
+
+    async def close(self) -> None:
+        """Close the S3 HTTP client."""
+        await self._s3_client.aclose()
+
+    async def __aenter__(self) -> "MultipartUploader":
+        """Context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        await self.close()
+
+    async def upload_multipart(
+        self, file: BinaryIO, parts: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Upload file parts to S3 presigned URLs and return ETags.
+
+        Args:
+            file: File-like object (must support seek/read)
+            parts: List of part dicts with part_number, start_byte, end_byte, upload_url
+
+        Returns:
+            List of dicts with part_number and etag for completion request
+
+        Raises:
+            FileError: If file reading fails
+            NetworkError: If upload fails
+        """
+        completed_parts: list[dict[str, Any]] = []
+
+        for part in parts:
+            part_number = part["part_number"]
+            upload_url = part["upload_url"]
+            start_byte = part["start_byte"]
+            end_byte = part["end_byte"]
+
+            # Calculate chunk size (end_byte is inclusive)
+            chunk_size = end_byte - start_byte + 1
+
+            # Read chunk from file
+            try:
+                file.seek(start_byte)
+                chunk_data = file.read(chunk_size)
+            except OSError as e:
+                raise FileError(
+                    f"Failed to read file chunk for part {part_number}: {e}",
+                    file_path=getattr(file, "name", None),
+                )
+
+            if len(chunk_data) != chunk_size:
+                raise FileError(
+                    f"Failed to read expected chunk size for part {part_number}: "
+                    f"got {len(chunk_data)} bytes, expected {chunk_size} bytes",
+                    file_path=getattr(file, "name", None),
+                )
+
+            # Upload to S3 via presigned URL (raw PUT, not multipart/form-data)
+            try:
+                response = await self._s3_client.put(
+                    upload_url,
+                    content=chunk_data,
+                    headers={
+                        "Content-Length": str(len(chunk_data)),
+                    },
+                )
+                response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 403:
+                    raise NetworkError(
+                        f"Presigned URL expired or invalid for part {part_number}",
+                        cause=e,
+                    )
+                raise NetworkError(
+                    f"Failed to upload part {part_number} to S3: HTTP {e.response.status_code}",
+                    cause=e,
+                )
+            except httpx.RequestError as e:
+                raise NetworkError(f"Network error uploading part {part_number}: {e}", cause=e)
+
+            # Extract ETag from response headers
+            # S3 returns ETag with quotes like: "9bb58f26192e4ba00f01e2e7b136bbd8"
+            etag = response.headers.get("ETag", "").strip('"')
+            if not etag:
+                raise NetworkError(f"Missing ETag in S3 response for part {part_number}")
+
+            completed_parts.append({"part_number": part_number, "etag": etag})
+
+        return completed_parts
+
+
+# Re-export utility functions
+__all__ = ["MultipartUploader", "get_file_size", "guess_content_type"]

leapocr/_internal/utils.py

@@ -0,0 +1,51 @@
+"""Common utility functions for LeapOCR SDK."""
+
+from datetime import datetime
+
+
+def parse_datetime(s: str | None) -> datetime:
+    """Parse RFC3339 datetime string.
+
+    Args:
+        s: RFC3339 datetime string (e.g., "2023-12-25T10:30:00Z")
+
+    Returns:
+        datetime object (defaults to epoch if parse fails)
+    """
+    if s is None:
+        # Return epoch as fallback
+        return datetime.fromtimestamp(0)
+
+    # Handle 'Z' timezone suffix by converting to +00:00
+    # Python's fromisoformat doesn't support 'Z' directly
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+
+    try:
+        return datetime.fromisoformat(s)
+    except ValueError:
+        # Fallback: try without timezone
+        try:
+            return datetime.fromisoformat(s.split("+")[0].split("Z")[0])
+        except ValueError:
+            # Return epoch as last resort
+            return datetime.fromtimestamp(0)
+
+
+def calculate_progress(status_data: dict) -> float:
+    """Calculate progress percentage from status data.
+
+    Args:
+        status_data: Dictionary with 'processed_pages' and 'total_pages'
+
+    Returns:
+        Progress percentage (0-100)
+    """
+    processed = status_data.get("processed_pages", 0)
+    total = status_data.get("total_pages", 0)
+
+    if total <= 0:
+        return 0.0
+
+    progress = (processed / total) * 100.0
+    return min(100.0, max(0.0, progress))

leapocr/_internal/validation.py

@@ -0,0 +1,172 @@
+"""Input validation utilities for LeapOCR SDK."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Union
+
+from ..errors import FileError
+
+# Maximum file size: 100MB
+MAX_FILE_SIZE = 100 * 1024 * 1024
+
+# Maximum instructions length
+MAX_INSTRUCTIONS_LENGTH = 10000
+
+# Supported file extensions
+SUPPORTED_EXTENSIONS = {
+    ".pdf",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".tiff",
+    ".tif",
+}
+
+
+@dataclass
+class ValidationResult:
+    """Result of file validation."""
+
+    valid: bool
+    error: str | None = None
+    warnings: list[str] | None = None
+
+
+def validate_file(
+    file_path: Union[str, Path],
+    max_size: int = MAX_FILE_SIZE,
+    allowed_types: set[str] | None = None,
+) -> ValidationResult:
+    """Validate a file before upload.
+
+    Args:
+        file_path: Path to the file to validate
+        max_size: Maximum file size in bytes (default: 100MB)
+        allowed_types: Set of allowed file extensions (default: SUPPORTED_EXTENSIONS)
+
+    Returns:
+        ValidationResult with validation status and any errors/warnings
+    """
+    path = Path(file_path)
+    allowed = allowed_types or SUPPORTED_EXTENSIONS
+    warnings: list[str] = []
+
+    # Check if file exists
+    if not path.exists():
+        return ValidationResult(valid=False, error=f"File not found: {path}")
+
+    # Check if it's a file (not a directory)
+    if not path.is_file():
+        return ValidationResult(valid=False, error=f"Not a file: {path}")
+
+    # Check if file is readable
+    if not os.access(path, os.R_OK):
+        return ValidationResult(valid=False, error=f"File not readable: {path}")
+
+    # Check file size
+    try:
+        file_size = path.stat().st_size
+    except OSError as e:
+        return ValidationResult(valid=False, error=f"Cannot stat file: {e}")
+
+    if file_size == 0:
+        return ValidationResult(valid=False, error="File is empty")
+
+    if file_size > max_size:
+        return ValidationResult(
+            valid=False,
+            error=f"File size ({file_size:,} bytes) exceeds maximum ({max_size:,} bytes)",
+        )
+
+    # Add warning for large files (>50MB will use multipart upload)
+    if file_size > 50 * 1024 * 1024:
+        warnings.append(f"Large file ({file_size:,} bytes) will use multipart upload")
+
+    # Check file extension
+    ext = path.suffix.lower()
+    if ext not in allowed:
+        return ValidationResult(
+            valid=False,
+            error=f"Unsupported file type: {ext}. Supported types: {', '.join(sorted(allowed))}",
+        )
+
+    return ValidationResult(valid=True, warnings=warnings or None)
+
+
+def get_file_size(file: Union[str, Path, BinaryIO]) -> int:
+    """Get file size in bytes.
+
+    Args:
+        file: File path or file-like object
+
+    Returns:
+        File size in bytes
+
+    Raises:
+        FileError: If file size cannot be determined
+    """
+    if isinstance(file, (str, Path)):
+        try:
+            return Path(file).stat().st_size
+        except OSError as e:
+            raise FileError(f"Cannot determine file size: {e}", file_path=str(file))
+
+    # File-like object
+    if hasattr(file, "seek") and hasattr(file, "tell"):
+        try:
+            # Save current position
+            current_pos = file.tell()
+            # Seek to end
+            file.seek(0, 2)
+            size = file.tell()
+            # Restore position
+            file.seek(current_pos)
+            return size
+        except OSError as e:
+            raise FileError(f"Cannot determine file size: {e}")
+
+    raise FileError("Cannot determine file size - unsupported file type")
+
+
+def guess_content_type(filename: str) -> str:
+    """Guess content type from filename extension.
+
+    Args:
+        filename: Filename to analyze
+
+    Returns:
+        MIME type string
+    """
+    ext = Path(filename).suffix.lower()
+    content_types = {
+        ".pdf": "application/pdf",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".tiff": "image/tiff",
+        ".tif": "image/tiff",
+    }
+    return content_types.get(ext, "application/octet-stream")
+
+
+def validate_instructions(instructions: str) -> ValidationResult:
+    """Validate processing instructions.
+
+    Args:
+        instructions: Instructions text to validate
+
+    Returns:
+        ValidationResult with validation status
+    """
+    if not instructions:
+        return ValidationResult(valid=True)
+
+    if len(instructions) > MAX_INSTRUCTIONS_LENGTH:
+        return ValidationResult(
+            valid=False,
+            error=f"Instructions too long ({len(instructions)} characters). "
+            f"Maximum allowed is {MAX_INSTRUCTIONS_LENGTH} characters.",
+        )
+
+    return ValidationResult(valid=True)