extractforms 0.1.0__py3-none-any.whl

extractforms/__init__.py

@@ -0,0 +1,32 @@
+"""ExtractForms package."""
+
+from extractforms._bootstrap import logger
+from extractforms.async_runner import run_async
+from extractforms.exceptions import (
+    AsyncExecutionError,
+    BackendError,
+    DependencyError,
+    ExtractionError,
+    PackageError,
+    SettingsError,
+)
+from extractforms.logging import configure_logging, get_logger
+from extractforms.settings import Settings, get_settings
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncExecutionError",
+    "BackendError",
+    "DependencyError",
+    "ExtractionError",
+    "PackageError",
+    "Settings",
+    "SettingsError",
+    "__version__",
+    "configure_logging",
+    "get_logger",
+    "get_settings",
+    "logger",
+    "run_async",
+]

extractforms/_bootstrap.py

@@ -0,0 +1,10 @@
+"""Package bootstrap helpers."""
+
+from extractforms.dependencies import ensure_package_dependencies
+from extractforms.logging import get_logger
+
+ensure_package_dependencies()
+
+logger = get_logger("extractforms")
+
+__all__ = ["logger"]

extractforms/async_runner.py

@@ -0,0 +1,64 @@
+"""Helpers to run async operations from sync or async contexts."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from queue import Queue
+from typing import TYPE_CHECKING, Any
+
+from extractforms.exceptions import AsyncExecutionError
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+
+def _run_in_background_thread[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run a coroutine in a dedicated thread with its own event loop.
+
+    Args:
+        coro (Coroutine[Any, Any, T]): The coroutine to run.
+
+    Raises:
+        AsyncExecutionError: If the coroutine raises an exception.
+
+    Returns:
+        T: The result of the coroutine.
+    """
+    output: Queue[T | BaseException] = Queue(maxsize=1)
+
+    def _runner() -> None:
+        try:
+            output.put(asyncio.run(coro))
+        except BaseException as exc:
+            output.put(exc)
+
+    thread = threading.Thread(target=_runner, daemon=True)
+    thread.start()
+    thread.join()
+
+    result = output.get()
+    if isinstance(result, BaseException):
+        raise AsyncExecutionError(result=result) from result
+    return result
+
+
+def run_async[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine from both sync and async contexts.
+
+    If called from a sync context, the coroutine will be run in a dedicated thread
+    with its own event loop. If called from an async context, the coroutine will
+    be awaited directly.
+
+    Args:
+        coro (Coroutine[Any, Any, T]): The coroutine to run.
+
+    Returns:
+        T: The result of the coroutine.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    return _run_in_background_thread(coro)

extractforms/backends/__init__.py

@@ -0,0 +1,7 @@
+"""Extraction backends."""
+
+from extractforms.backends.multimodal_openai import MultimodalLLMBackend
+from extractforms.backends.ocr_document_intelligence import OCRBackend
+from extractforms.typing.protocol import ExtractorBackend, PageSource
+
+__all__ = ["ExtractorBackend", "MultimodalLLMBackend", "OCRBackend", "PageSource"]

extractforms/backends/multimodal_openai.py

@@ -0,0 +1,254 @@
+"""OpenAI-compatible multimodal backend."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, cast
+
+from openai import APIConnectionError, APIStatusError, APITimeoutError, AsyncOpenAI
+from pydantic import BaseModel, ConfigDict
+
+from extractforms import logger
+from extractforms.async_runner import run_async
+from extractforms.exceptions import BackendError
+from extractforms.prompts import (
+    build_schema_inference_prompt,
+    build_values_extraction_prompt,
+    schema_response_format,
+)
+from extractforms.typing.models import FieldValue, PricingCall, RenderedPage, SchemaField, SchemaSpec
+
+if TYPE_CHECKING:
+    from extractforms.settings import Settings
+
+
+class _SchemaResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    fields: list[SchemaField]
+
+
+class _ValuesResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    fields: list[FieldValue]
+
+
+class MultimodalLLMBackend:
+    """Multimodal extraction backend against OpenAI-compatible endpoints."""
+
+    def __init__(self, settings: Settings) -> None:
+        """Initialize backend.
+
+        Args:
+            settings (Settings): Runtime settings.
+        """
+        self._settings = settings
+
+    async def _apost_chat_completions(
+        self,
+        payload: dict[str, Any],
+    ) -> tuple[dict[str, Any], PricingCall | None]:
+        """Send one async completion request.
+
+        Args:
+            payload (dict[str, Any]): Request payload.
+
+        Raises:
+            BackendError: If request fails or endpoint is misconfigured.
+
+        Returns:
+            tuple[dict[str, Any], PricingCall | None]: Parsed payload and optional pricing call.
+        """
+        if not self._settings.openai_base_url:
+            raise BackendError(message="OPENAI_BASE_URL is required for multimodal backend")
+        if not self._settings.openai_api_key:
+            raise BackendError(message="OPENAI_API_KEY is required for multimodal backend")
+
+        client = self._settings.select_async_httpx_client(self._settings.openai_base_url)
+        if client is None:
+            raise BackendError(message="httpx clients are not initialized in settings")
+        http_client = cast("Any", client)
+        openai_client = AsyncOpenAI(
+            api_key=self._settings.openai_api_key,
+            base_url=self._settings.openai_base_url,
+            http_client=http_client,
+        )
+
+        try:
+            completion = await openai_client.chat.completions.create(**payload)
+            data = completion.model_dump(mode="json")
+        except APIStatusError as exc:
+            status_code = getattr(exc, "status_code", None)
+            raise BackendError(
+                message=f"Chat completion request failed with status {status_code}",
+            ) from exc
+        except APITimeoutError as exc:
+            raise BackendError(message="Chat completion request timed out") from exc
+        except APIConnectionError as exc:
+            raise BackendError(message=f"Chat completion request failed: {exc}") from exc
+        except Exception as exc:
+            raise BackendError(
+                message=f"Chat completion request failed: {exc}",
+            ) from exc
+
+        usage = data.get("usage", {})
+        pricing = PricingCall(
+            provider="openai-compatible",
+            model=self._settings.openai_model,
+            input_tokens=usage.get("prompt_tokens"),
+            output_tokens=usage.get("completion_tokens"),
+            total_cost_usd=None,
+        )
+
+        return data, pricing
+
+    def _post_chat_completions(self, payload: dict[str, Any]) -> tuple[dict[str, Any], PricingCall | None]:
+        """Send one completion request from sync call sites.
+
+        Args:
+            payload (dict[str, Any]): Request payload.
+
+        Returns:
+            tuple[dict[str, Any], PricingCall | None]: Parsed payload and optional pricing call.
+        """
+        return run_async(self._apost_chat_completions(payload))
+
+    @staticmethod
+    def _image_content(page: RenderedPage) -> dict[str, Any]:
+        """Build image content chunk.
+
+        Args:
+            page (RenderedPage): Rendered page.
+
+        Returns:
+            dict[str, Any]: OpenAI content block.
+        """
+        return {
+            "type": "image_url",
+            "image_url": {"url": f"data:{page.mime_type};base64,{page.data_base64}"},
+        }
+
+    async def ainfer_schema(self, pages: list[RenderedPage]) -> tuple[SchemaSpec, PricingCall | None]:
+        """Infer schema from rendered pages.
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+
+        Raises:
+            BackendError: If page list is empty.
+
+        Returns:
+            tuple[SchemaSpec, PricingCall | None]: Inferred schema and call pricing.
+        """
+        if not pages:
+            raise BackendError(message="Cannot infer schema from empty page list")
+
+        prompt = build_schema_inference_prompt()
+        response_format = schema_response_format("schema_response", _SchemaResponse.model_json_schema())
+
+        content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
+        content.extend(self._image_content(page) for page in pages)
+
+        payload = {
+            "model": self._settings.openai_model,
+            "messages": [{"role": "user", "content": content}],
+            "response_format": {
+                "type": "json_schema",
+                "json_schema": response_format.model_dump(mode="json", by_alias=True),
+            },
+        }
+
+        data, pricing = await self._apost_chat_completions(payload)
+        content_text = data["choices"][0]["message"]["content"]
+        parsed = _SchemaResponse.model_validate(json.loads(content_text))
+
+        schema = SchemaSpec(
+            id="",
+            name=parsed.name,
+            fingerprint="",
+            fields=parsed.fields,
+        )
+        logger.info("Schema inferred", extra={"fields": len(schema.fields)})
+        return schema, pricing
+
+    def infer_schema(self, pages: list[RenderedPage]) -> tuple[SchemaSpec, PricingCall | None]:
+        """Infer schema from rendered pages (sync wrapper).
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+
+        Returns:
+            tuple[SchemaSpec, PricingCall | None]: Inferred schema and call pricing.
+        """
+        return run_async(self.ainfer_schema(pages))
+
+    async def aextract_values(
+        self,
+        pages: list[RenderedPage],
+        keys: list[str],
+        *,
+        extra_instructions: str | None = None,
+    ) -> tuple[list[FieldValue], PricingCall | None]:
+        """Extract values for specific keys.
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+            keys (list[str]): Keys to extract.
+            extra_instructions (str | None): Optional prompt augmentation.
+
+        Raises:
+            BackendError: If page list is empty.
+
+        Returns:
+            tuple[list[FieldValue], PricingCall | None]: Extracted values and pricing.
+        """
+        if not pages:
+            raise BackendError(message="Cannot extract values from empty page list")
+
+        schema = SchemaSpec(
+            id="",
+            name="runtime",
+            fingerprint="",
+            fields=[SchemaField(key=k, label=k) for k in keys],
+        )
+        prompt = build_values_extraction_prompt(schema, extra_instructions=extra_instructions)
+        response_format = schema_response_format("values_response", _ValuesResponse.model_json_schema())
+
+        content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
+        content.extend(self._image_content(page) for page in pages)
+
+        payload = {
+            "model": self._settings.openai_model,
+            "messages": [{"role": "user", "content": content}],
+            "response_format": {
+                "type": "json_schema",
+                "json_schema": response_format.model_dump(mode="json", by_alias=True),
+            },
+        }
+
+        data, pricing = await self._apost_chat_completions(payload)
+        content_text = data["choices"][0]["message"]["content"]
+        parsed = _ValuesResponse.model_validate(json.loads(content_text))
+        logger.info("Values extracted", extra={"fields": len(parsed.fields)})
+        return parsed.fields, pricing
+
+    def extract_values(
+        self,
+        pages: list[RenderedPage],
+        keys: list[str],
+        *,
+        extra_instructions: str | None = None,
+    ) -> tuple[list[FieldValue], PricingCall | None]:
+        """Extract values for specific keys (sync wrapper).
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+            keys (list[str]): Keys to extract.
+            extra_instructions (str | None): Optional prompt augmentation.
+
+        Returns:
+            tuple[list[FieldValue], PricingCall | None]: Extracted values and pricing.
+        """
+        return run_async(self.aextract_values(pages, keys, extra_instructions=extra_instructions))

extractforms/backends/ocr_document_intelligence.py

@@ -0,0 +1,48 @@
+"""OCR backend stub for future Document Intelligence integration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from extractforms.exceptions import BackendError
+
+if TYPE_CHECKING:
+    from extractforms.typing.models import FieldValue, PricingCall, RenderedPage, SchemaSpec
+
+
+class OCRBackend:
+    """Placeholder OCR backend."""
+
+    @staticmethod
+    def infer_schema(
+        pages: list[RenderedPage],
+    ) -> tuple[SchemaSpec, PricingCall | None]:
+        """Infer schema with OCR backend.
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+
+        Raises:
+            BackendError: Always in MVP stub.
+
+        """
+        _ = pages
+        raise BackendError(message="OCR backend is not implemented yet")
+
+    @staticmethod
+    def extract_values(
+        pages: list[RenderedPage],
+        keys: list[str],
+    ) -> tuple[list[FieldValue], PricingCall | None]:
+        """Extract values with OCR backend.
+
+        Args:
+            pages (list[RenderedPage]): Rendered pages.
+            keys (list[str]): Keys to extract.
+
+        Raises:
+            BackendError: Always in MVP stub.
+
+        """
+        _ = (pages, keys)
+        raise BackendError(message="OCR backend is not implemented yet")

extractforms/cli.py

@@ -0,0 +1,150 @@
+"""CLI entry point for ExtractForms."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from extractforms import __version__, logger
+from extractforms.dependencies import ensure_cli_dependencies_for_extract
+from extractforms.exceptions import PackageError
+from extractforms.extractor import persist_result, run_extract
+from extractforms.logging import configure_logging
+from extractforms.settings import get_settings
+from extractforms.typing.enums import PassMode
+from extractforms.typing.models import ExtractRequest
+
+
+def _pass_mode_from_cli(value: str) -> PassMode:
+    """Convert `--passes` CLI value into pass mode.
+
+    Args:
+        value (str): CLI value (`1` or `2`).
+
+    Raises:
+        argparse.ArgumentTypeError: If value is not supported.
+
+    Returns:
+        PassMode: Selected pass mode.
+    """
+    mapping = {
+        "1": PassMode.ONE_PASS,
+        "2": PassMode.TWO_PASS,
+    }
+    if value not in mapping:
+        raise argparse.ArgumentTypeError("--passes must be one of: 1, 2")  # noqa: TRY003
+    return mapping[value]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the command-line parser.
+
+    Returns:
+        argparse.ArgumentParser: The configured argument parser.
+    """
+    parser = argparse.ArgumentParser(prog="extractforms")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    extract_parser = subparsers.add_parser("extract", help="Extract key/value fields from a PDF form")
+    extract_parser.add_argument("--input", required=True, type=Path, dest="input_path")
+    extract_parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path("results/result.json"),
+        dest="output_path",
+    )
+    extract_parser.add_argument("--passes", default="2", type=_pass_mode_from_cli, dest="mode")
+    extract_parser.add_argument("--no-cache", action="store_true", dest="no_cache")
+
+    extract_parser.add_argument("--dpi", type=int, default=200)
+    extract_parser.add_argument("--image-format", default="png", dest="image_format")
+    extract_parser.add_argument("--page-start", type=int, default=None, dest="page_start")
+    extract_parser.add_argument("--page-end", type=int, default=None, dest="page_end")
+    extract_parser.add_argument("--max-pages", type=int, default=None, dest="max_pages")
+
+    extract_parser.add_argument("--chunk-pages", type=int, default=1, dest="chunk_pages")
+    extract_parser.add_argument("--extra-instructions", default=None, dest="extra_instructions")
+
+    extract_parser.add_argument("--schema-id", default=None, dest="schema_id")
+    extract_parser.add_argument("--schema-path", type=Path, default=None, dest="schema_path")
+    extract_parser.add_argument("--match-schema", action="store_true", dest="match_schema")
+
+    return parser
+
+
+def _build_extract_request(args: argparse.Namespace) -> ExtractRequest:
+    """Build extraction request from CLI arguments.
+
+    Args:
+        args (argparse.Namespace): Parsed CLI args.
+
+    Returns:
+        ExtractRequest: Request object.
+    """
+    mode = args.mode
+    if args.schema_id or args.schema_path:
+        mode = PassMode.ONE_SCHEMA_PASS
+
+    return ExtractRequest(
+        input_path=args.input_path,
+        output_path=args.output_path,
+        mode=mode,
+        use_cache=not args.no_cache,
+        dpi=args.dpi,
+        image_format=args.image_format,
+        page_start=args.page_start,
+        page_end=args.page_end,
+        max_pages=args.max_pages,
+        chunk_pages=args.chunk_pages,
+        schema_id=args.schema_id,
+        schema_path=args.schema_path,
+        match_schema=args.match_schema,
+        extra_instructions=args.extra_instructions,
+    )
+
+
+def main() -> int:
+    """Run the CLI.
+
+    Returns:
+        int: Exit code (0 for success, 1 for error).
+    """
+    settings = get_settings()
+    configure_logging(settings=settings)
+
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command != "extract":
+        parser.print_help()
+        return 0
+
+    ensure_cli_dependencies_for_extract()
+    request = _build_extract_request(args)
+
+    try:
+        result = run_extract(request, settings)
+    except PackageError:
+        logger.exception("Extraction failed")
+        return 1
+    except KeyboardInterrupt:
+        logger.info("Extraction aborted by user")
+        return 130
+    except Exception:
+        logger.exception("Unexpected error during extraction")
+        return 1
+    finally:
+        settings.close_httpx_clients()
+
+    output_path = request.output_path
+    if output_path is None:
+        output_path = Path("results/result.json")
+    persist_result(result, output_path)
+    logger.info("Extraction completed", extra={"output_path": str(output_path)})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

extractforms/dependencies.py

@@ -0,0 +1,66 @@
+"""Runtime dependency checks for CLI commands."""
+
+from __future__ import annotations
+
+import importlib.util
+
+from extractforms.exceptions import DependencyError
+
+
+def _is_module_available(module_name: str) -> bool:
+    """Check whether a module can be imported.
+
+    Args:
+        module_name (str): Python module name.
+
+    Returns:
+        bool: True if import spec exists.
+    """
+    return importlib.util.find_spec(module_name) is not None
+
+
+def _collect_missing_dependencies(modules_by_package: dict[str, str]) -> list[str]:
+    """Collect missing packages for a module mapping.
+
+    Args:
+        modules_by_package (Mapping[str, str]): Mapping of package name -> import module.
+
+    Returns:
+        list[str]: Missing package names.
+    """
+    return [package for package, module in modules_by_package.items() if not _is_module_available(module)]
+
+
+def ensure_package_dependencies() -> None:
+    """Validate required dependencies at package import time.
+
+    Raises:
+        DependencyError: If required runtime dependencies are missing.
+    """
+    missing = _collect_missing_dependencies(
+        {
+            "httpx": "httpx",
+            "openai": "openai",
+            "certifi": "certifi",
+        },
+    )
+    if missing:
+        raise DependencyError(missing_package=missing, message="package import")
+
+
+def ensure_cli_dependencies_for_extract() -> None:
+    """Validate required runtime dependencies for `extractforms extract`.
+
+    Raises:
+        DependencyError: If one or more required modules are missing.
+    """
+    missing = _collect_missing_dependencies(
+        {
+            "pymupdf": "fitz",
+            "httpx": "httpx",
+            "openai": "openai",
+        },
+    )
+
+    if missing:
+        raise DependencyError(missing_package=missing, message="extract")