docslight-lite 0.1.0__py3-none-any.whl

docslight/__init__.py

@@ -0,0 +1,41 @@
+"""Lightweight ComPDF document parsing and extraction SDK."""
+
+from docslight.client import DocSlight
+from docslight.config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CONFIG_PATH,
+    VALID_MODES,
+    DocSlightConfig,
+)
+from docslight.exceptions import (
+    AuthenticationError,
+    CloudAPIError,
+    ConfigurationError,
+    DependencyMissingError,
+    DocSlightError,
+    LocalProcessingError,
+    RateLimitError,
+    UnsupportedFormatError,
+)
+from docslight.result import ExtractResult, ParseResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthenticationError",
+    "CloudAPIError",
+    "ConfigurationError",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_CONFIG_PATH",
+    "DependencyMissingError",
+    "DocSlight",
+    "DocSlightConfig",
+    "DocSlightError",
+    "ExtractResult",
+    "LocalProcessingError",
+    "ParseResult",
+    "RateLimitError",
+    "UnsupportedFormatError",
+    "VALID_MODES",
+    "__version__",
+]

docslight/cli.py

@@ -0,0 +1,215 @@
+"""Command line interface for docslight."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.util
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, cast
+
+from docslight import DocSlight
+from docslight.schemas import normalize_fields
+from docslight.standard_json import convert_parse_payload
+
+WEB_EXTRA_ERROR = "Install docslight-lite[web] to use the web command."
+
+
+class CLIUsageError(Exception):
+    """Expected command line usage error."""
+
+
+def _add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--mode", choices=("cloud", "local"))
+    parser.add_argument("--api-key")
+    parser.add_argument("--base-url")
+    parser.add_argument("--local-parser")
+    parser.add_argument("--local-llm-provider")
+    parser.add_argument("--local-llm-model")
+    parser.add_argument("--local-llm-base-url")
+    parser.add_argument("--local-llm-api-key")
+
+
+def _load_json_file(path: str | None, label: str) -> Any:
+    if path is None:
+        return None
+    try:
+        with Path(path).open(encoding="utf-8") as file:
+            return json.load(file)
+    except FileNotFoundError as exc:
+        raise CLIUsageError(f"{label} file not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise CLIUsageError(f"Invalid JSON in {label} file {path}: {exc.msg}") from exc
+    except UnicodeDecodeError as exc:
+        raise CLIUsageError(f"Cannot read {label} file {path}: {exc}") from exc
+
+
+def _load_document_types(path: str | None) -> list[Any] | None:
+    document_types = _load_json_file(path, "document-types")
+    if document_types is None:
+        return None
+    if not isinstance(document_types, list):
+        raise CLIUsageError("document-types JSON must be a list")
+    return document_types
+
+
+def _local_llm_from_args(args: argparse.Namespace) -> dict[str, str] | None:
+    values = {
+        "provider": args.local_llm_provider,
+        "model": args.local_llm_model,
+        "base_url": args.local_llm_base_url,
+        "api_key": args.local_llm_api_key,
+    }
+    if not any(values.values()):
+        return None
+    if values["provider"] is None:
+        values["provider"] = "ollama"
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _client_from_args(args: argparse.Namespace) -> DocSlight:
+    return DocSlight(
+        mode=args.mode,
+        api_key=args.api_key,
+        base_url=args.base_url,
+        local_parser=args.local_parser,
+        local_llm=_local_llm_from_args(args),
+    )
+
+
+def _write_output(content: str, output_path: str | None) -> None:
+    if output_path is None:
+        sys.stdout.write(content)
+        if not content.endswith("\n"):
+            sys.stdout.write("\n")
+        return
+    Path(output_path).write_text(content, encoding="utf-8")
+
+
+def _to_pretty_json(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def run_web_app(host: str, port: int, debug: bool) -> None:
+    """Run the optional Flask web application."""
+    if importlib.util.find_spec("docslight.web_app") is None:
+        raise CLIUsageError(WEB_EXTRA_ERROR)
+
+    try:
+        web_app = importlib.import_module("docslight.web_app")
+    except ModuleNotFoundError as exc:
+        if exc.name in {"flask", "werkzeug"}:
+            raise CLIUsageError(WEB_EXTRA_ERROR) from exc
+        raise
+    _run_web_app = web_app.run_web_app
+    _run_web_app(host, port, debug)
+
+
+def _print_cli_error(error: Exception) -> int:
+    sys.stderr.write(f"docslight: error: {error}\n")
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the docslight command line parser."""
+    parser = argparse.ArgumentParser(
+        prog="docslight",
+        description="Lightweight ComPDF document parsing and extraction SDK.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    parse_parser = subparsers.add_parser("parse", help="Parse a document")
+    parse_parser.add_argument("input")
+    parse_parser.add_argument("--output", "-o")
+    parse_parser.add_argument(
+        "--format",
+        choices=("markdown", "json", "standard-json"),
+        default="markdown",
+    )
+    _add_common_options(parse_parser)
+    parse_parser.set_defaults(func=_run_parse)
+
+    convert_parser = subparsers.add_parser(
+        "convert-parse-json",
+        help="Convert local parse JSON to the standard parse JSON schema",
+    )
+    convert_parser.add_argument("input")
+    convert_parser.add_argument("--output", "-o")
+    convert_parser.set_defaults(func=_run_convert_parse_json)
+
+    extract_parser = subparsers.add_parser("extract", help="Extract structured data")
+    extract_parser.add_argument("input")
+    extract_parser.add_argument("--output", "-o")
+    extract_parser.add_argument("--fields")
+    extract_parser.add_argument("--schema")
+    extract_parser.add_argument("--document-types")
+    _add_common_options(extract_parser)
+    extract_parser.set_defaults(func=_run_extract)
+
+    web_parser = subparsers.add_parser("web", help="Run the web application")
+    web_parser.add_argument("--host", default="127.0.0.1")
+    web_parser.add_argument("--port", type=int, default=8000)
+    web_parser.add_argument("--debug", action="store_true")
+    web_parser.set_defaults(func=_run_web)
+
+    return parser
+
+
+def _run_parse(args: argparse.Namespace) -> int:
+    parse_output = "json" if args.format == "standard-json" else args.format
+    result = _client_from_args(args).parse(args.input, output=parse_output)
+    if args.format == "json":
+        content = _to_pretty_json(result.to_json())
+    elif args.format == "standard-json":
+        content = _to_pretty_json(result.to_standard_json())
+    else:
+        content = result.to_markdown()
+    _write_output(content, args.output)
+    return 0
+
+
+def _run_convert_parse_json(args: argparse.Namespace) -> int:
+    payload = _load_json_file(args.input, "parse-json")
+    if not isinstance(payload, dict):
+        raise CLIUsageError("parse-json JSON must be an object")
+    _write_output(_to_pretty_json(convert_parse_payload(payload)), args.output)
+    return 0
+
+
+def _run_extract(args: argparse.Namespace) -> int:
+    extract_options: dict[str, Any] = {}
+    fields = normalize_fields(args.fields)
+    if fields is not None:
+        extract_options["fields"] = fields
+    schema = _load_json_file(args.schema, "schema")
+    if schema is not None:
+        extract_options["schema"] = schema
+    document_types = _load_document_types(args.document_types)
+    if document_types is not None:
+        extract_options["document_types"] = document_types
+
+    result = _client_from_args(args).extract(args.input, **extract_options)
+    _write_output(_to_pretty_json(result.to_json()), args.output)
+    return 0
+
+
+def _run_web(args: argparse.Namespace) -> int:
+    run_web_app(args.host, args.port, args.debug)
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the docslight command line interface."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return cast(int, args.func(args))
+    except CLIUsageError as exc:
+        return _print_cli_error(exc)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docslight/client.py

@@ -0,0 +1,92 @@
+"""Public SDK router for document parsing and extraction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from docslight.cloud import CloudClient
+from docslight.config import DocSlightConfig
+from docslight.result import ExtractResult, ParseResult
+from docslight.schemas import build_extract_schema, normalize_fields
+
+
+class DocSlight:
+    """Route SDK calls to cloud or local document processors."""
+
+    def __init__(
+        self,
+        mode: str | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        local_parser: str | None = None,
+        local_llm: dict[str, Any] | None = None,
+        cloud_client: Any = None,
+        local_pipeline: Any = None,
+    ) -> None:
+        self.config = DocSlightConfig.from_sources(
+            mode=mode,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            local_parser=local_parser,
+            local_llm=local_llm,
+        )
+        self._cloud_client = cloud_client
+        self._local_pipeline = local_pipeline
+
+    def parse(self, path: Path | str, output: str = "markdown", **options: Any) -> ParseResult:
+        """Parse a document into markdown by default."""
+        if output != "markdown":
+            options["output"] = output
+        return cast(ParseResult, self._processor().parse(path, **options))
+
+    def extract(
+        self,
+        path: Path | str,
+        fields: list[str] | str | dict[str, Any] | None = None,
+        schema: dict[str, Any] | None = None,
+        document_types: list[str] | None = None,
+        **options: Any,
+    ) -> ExtractResult:
+        """Extract structured data from a document."""
+        normalized_fields = normalize_fields(fields)
+        extract_kwargs = dict(options)
+        if normalized_fields is not None:
+            extract_kwargs["fields"] = normalized_fields
+            derived_schema = build_extract_schema(normalized_fields)
+            if schema is None and derived_schema is not None:
+                extract_kwargs["schema"] = derived_schema
+        if schema is not None:
+            extract_kwargs["schema"] = schema
+        if document_types is not None:
+            extract_kwargs["document_types"] = document_types
+        return cast(ExtractResult, self._processor().extract(path, **extract_kwargs))
+
+    def parse_batch(self, paths: list[Path | str], **options: Any) -> list[ParseResult]:
+        """Parse documents sequentially."""
+        return [self.parse(path, **options) for path in paths]
+
+    def extract_batch(self, paths: list[Path | str], **options: Any) -> list[ExtractResult]:
+        """Extract data from documents sequentially."""
+        return [self.extract(path, **options) for path in paths]
+
+    def _processor(self) -> Any:
+        if self.config.mode == "local":
+            if self._local_pipeline is None:
+                self._local_pipeline = self._build_local_pipeline()
+            return self._local_pipeline
+
+        if self._cloud_client is None:
+            self._cloud_client = CloudClient(
+                self.config.api_key,
+                self.config.base_url,
+                self.config.timeout,
+            )
+        return self._cloud_client
+
+    def _build_local_pipeline(self) -> Any:
+        from docslight.local.pipeline import LocalPipeline
+
+        return LocalPipeline.from_config(self.config)

docslight/cloud/__init__.py

@@ -0,0 +1,5 @@
+"""Cloud document parsing integrations."""
+
+from docslight.cloud.client import CloudClient
+
+__all__ = ["CloudClient"]