localparse 0.1.0__py3-none-any.whl

localparse/__init__.py

@@ -0,0 +1,43 @@
+"""LocalParse — official Python client for the LocalParse document-parsing API.
+
+LocalParse is a LlamaParse-compatible parser with a deterministic accuracy layer
+(table-detection recovery + oracle-free financial-identity checks).
+
+    from localparse import LocalParse
+
+    client = LocalParse(api_key="lp-...")  # or set LOCALPARSE_API_KEY
+    result = client.parse("invoice.pdf", result_type="markdown")
+    print(result.markdown)
+"""
+
+from __future__ import annotations
+
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    JobFailedError,
+    JobTimeoutError,
+    LocalParseError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+)
+from ._models import Job, ParseResult
+from .client import LocalParse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "Job",
+    "JobFailedError",
+    "JobTimeoutError",
+    "LocalParse",
+    "LocalParseError",
+    "NotFoundError",
+    "ParseResult",
+    "QuotaExceededError",
+    "RateLimitError",
+    "__version__",
+]

localparse/_errors.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+
+class LocalParseError(Exception):
+    """Base class for every error raised by the LocalParse client."""
+
+
+class AuthenticationError(LocalParseError):
+    """The API key is missing, unknown, revoked, or expired (HTTP 401/403)."""
+
+
+class RateLimitError(LocalParseError):
+    """The key's per-minute rate limit was exceeded (HTTP 429).
+
+    ``retry_after`` is the server-suggested wait in seconds, when provided.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(LocalParseError):
+    """The key's monthly page quota is exhausted (HTTP 402)."""
+
+
+class NotFoundError(LocalParseError):
+    """The job/case doesn't exist or isn't visible to this key (HTTP 404)."""
+
+
+class APIError(LocalParseError):
+    """An otherwise-unclassified non-2xx response.
+
+    ``status_code`` is the HTTP status; ``body`` is the decoded response text.
+    """
+
+    def __init__(self, message: str, *, status_code: int, body: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class JobFailedError(LocalParseError):
+    """A parse job finished in a terminal non-success state (ERROR/CANCELED)."""
+
+    def __init__(self, message: str, *, job_id: str, status: str) -> None:
+        super().__init__(message)
+        self.job_id = job_id
+        self.status = status
+
+
+class JobTimeoutError(LocalParseError):
+    """A job did not reach a terminal state within ``max_wait`` seconds."""
+
+    def __init__(self, message: str, *, job_id: str) -> None:
+        super().__init__(message)
+        self.job_id = job_id

localparse/_models.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+#: Terminal job states (no further transitions).
+TERMINAL_STATUSES = frozenset({"SUCCESS", "ERROR", "CANCELED"})
+
+
+@dataclass
+class Job:
+    """A parse job handle returned by ``upload`` / ``get_job``.
+
+    Mirrors ``GET /api/parsing/job/{id}``: ``{"id", "status", "error_message"}``
+    where ``status`` is one of ``PENDING`` / ``SUCCESS`` / ``ERROR`` / ``CANCELED``.
+    """
+
+    id: str
+    status: str
+    error_message: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_done(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def is_success(self) -> bool:
+        return self.status == "SUCCESS"
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> Job:
+        return cls(
+            id=str(payload.get("id", "")),
+            status=str(payload.get("status", "")),
+            error_message=payload.get("error_message"),
+            raw=payload,
+        )
+
+
+@dataclass
+class ParseResult:
+    """The result of a successful parse, in the requested flavour.
+
+    ``data`` is the raw response from ``GET /api/parsing/job/{id}/result/{type}``.
+    For ``markdown``/``text`` it carries the string under ``.markdown``/``.text``;
+    for ``json``/``structured`` the structured payload is under ``.data``/``.pages``.
+    Every flavour also exposes ``job_metadata`` (and the LocalParse accuracy
+    extensions ``identity_check`` / ``recovered_tables`` / ``persisted``).
+    """
+
+    job_id: str
+    result_type: str
+    data: dict[str, Any]
+
+    @property
+    def markdown(self) -> str | None:
+        value = self.data.get("markdown")
+        return value if isinstance(value, str) else None
+
+    @property
+    def text(self) -> str | None:
+        value = self.data.get("text")
+        return value if isinstance(value, str) else None
+
+    @property
+    def pages(self) -> list[dict[str, Any]]:
+        value = self.data.get("pages")
+        return value if isinstance(value, list) else []
+
+    @property
+    def job_metadata(self) -> dict[str, Any]:
+        value = self.data.get("job_metadata")
+        return value if isinstance(value, dict) else {}
+
+    @property
+    def identity_check(self) -> dict[str, Any] | None:
+        """Oracle-free financial-identity summary (Totals that don't reconcile)."""
+        value = self.job_metadata.get("identity_check")
+        return value if isinstance(value, dict) else None
+
+    @property
+    def recovered_tables(self) -> int:
+        """Tables recovered by the detection-completeness (``detect_repair``) pass."""
+        value = self.job_metadata.get("recovered_tables")
+        return value if isinstance(value, int) else 0
+
+    @property
+    def persisted(self) -> dict[str, Any] | None:
+        """Where the doc landed when a ``case_id`` was supplied (else ``None``)."""
+        value = self.job_metadata.get("persisted")
+        return value if isinstance(value, dict) else None
+
+    def __str__(self) -> str:
+        if self.markdown is not None:
+            return self.markdown
+        if self.text is not None:
+            return self.text
+        return str(self.data)

localparse/client.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import IO, Any, Union
+
+import requests
+
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    JobFailedError,
+    JobTimeoutError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+)
+from ._models import Job, ParseResult
+
+__all__ = ["LocalParse"]
+
+DEFAULT_BASE_URL = "https://api.localparse.com"
+
+# A path on disk, or a (filename, file-like) pair for in-memory bytes/streams.
+FileInput = Union[str, "os.PathLike[str]", "tuple[str, IO[bytes]]"]
+
+#: Result flavours fetchable from ``/result/{type}``.
+_RESULT_TYPES = frozenset({"markdown", "md", "text", "txt", "json", "structured", "document"})
+
+#: Statuses in the case manifest that mean "already ingested, skip on resume".
+_RESUMABLE_STATUSES = frozenset({"ok", "needs_review"})
+
+
+class LocalParse:
+    """Client for the LocalParse document-parsing API.
+
+    LocalParse is a drop-in LlamaParse-compatible parser with a deterministic
+    accuracy layer (table-detection recovery + oracle-free financial-identity
+    checks). Typical use is the one-shot :meth:`parse`::
+
+        from localparse import LocalParse
+
+        client = LocalParse(api_key="lp-...")          # or set LOCALPARSE_API_KEY
+        result = client.parse("invoice.pdf", result_type="markdown")
+        print(result.markdown)
+
+    For long batches use :meth:`parse_folder` with a ``case_id`` (incremental
+    re-ingest skips unchanged files); for full control use the async-job
+    primitives :meth:`upload` / :meth:`get_job` / :meth:`get_result`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+        poll_interval: float = 2.0,
+        max_wait: float = 900.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("LOCALPARSE_API_KEY")
+        if not key:
+            raise AuthenticationError(
+                "An API key is required: pass api_key=... or set LOCALPARSE_API_KEY."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.poll_interval = poll_interval
+        self.max_wait = max_wait
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": "localparse-python/0.1.0",
+            }
+        )
+
+    # -- low-level HTTP ----------------------------------------------------- #
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        kwargs.setdefault("timeout", self.timeout)
+        try:
+            resp = self._session.request(method, self._url(path), **kwargs)
+        except requests.RequestException as exc:  # network/DNS/TLS failure
+            raise APIError(f"Request to {path} failed: {exc}", status_code=0) from exc
+        self._raise_for_status(resp)
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        if resp.status_code < 400:
+            return
+        detail = _detail(resp)
+        if resp.status_code in (401, 403):
+            raise AuthenticationError(detail)
+        if resp.status_code == 402:
+            raise QuotaExceededError(detail)
+        if resp.status_code == 404:
+            raise NotFoundError(detail)
+        if resp.status_code == 429:
+            retry_after = resp.headers.get("Retry-After")
+            raise RateLimitError(
+                detail, retry_after=float(retry_after) if retry_after else None
+            )
+        raise APIError(detail, status_code=resp.status_code, body=resp.text)
+
+    # -- async-job primitives ---------------------------------------------- #
+
+    def upload(
+        self,
+        file: FileInput,
+        *,
+        result_type: str = "markdown",
+        case_id: str | None = None,
+        source_path: str | None = None,
+        language: str | Iterable[str] | None = None,
+        target_pages: str | None = None,
+        max_pages: int | None = None,
+        detect_repair: bool | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> Job:
+        """Submit a document and return a :class:`Job` (non-blocking).
+
+        ``case_id`` persists the doc into a durable per-case store; ``source_path``
+        makes that identity folder-aware (so a re-ingest supersedes its own prior
+        version). ``extra`` passes through any other LlamaParse form field verbatim.
+        """
+        data: dict[str, str] = {"result_type": result_type}
+        if case_id is not None:
+            data["case_id"] = case_id
+        if source_path is not None:
+            data["source_path"] = source_path
+        if language is not None:
+            data["language"] = language if isinstance(language, str) else ",".join(language)
+        if target_pages is not None:
+            data["target_pages"] = target_pages
+        if max_pages is not None:
+            data["max_pages"] = str(max_pages)
+        if detect_repair is not None:
+            data["detect_repair"] = "true" if detect_repair else "false"
+        if extra:
+            data.update({k: str(v) for k, v in extra.items()})
+
+        opened: IO[bytes] | None = None
+        try:
+            if isinstance(file, tuple):
+                filename, stream = file
+                files = {"file": (filename, stream)}
+            else:
+                path = Path(file)
+                opened = path.open("rb")
+                files = {"file": (path.name, opened)}
+            payload = self._request(
+                "POST", "/api/parsing/upload", data=data, files=files
+            )
+        finally:
+            if opened is not None:
+                opened.close()
+        return Job.from_payload(payload or {})
+
+    def get_job(self, job_id: str) -> Job:
+        """Poll a job's current status."""
+        payload = self._request("GET", f"/api/parsing/job/{job_id}")
+        return Job.from_payload(payload or {})
+
+    def cancel(self, job_id: str) -> Job:
+        """Cancel a still-``PENDING`` job so a worker never spends the pod on it."""
+        payload = self._request("DELETE", f"/api/parsing/job/{job_id}")
+        return Job.from_payload(payload or {})
+
+    def get_result(self, job_id: str, result_type: str = "markdown") -> ParseResult:
+        """Fetch a finished job's result in the given flavour.
+
+        ``result_type`` ∈ ``markdown``/``md``, ``text``/``txt``, ``json``,
+        ``structured``/``document``.
+        """
+        if result_type not in _RESULT_TYPES:
+            raise ValueError(
+                f"Unknown result_type {result_type!r}; expected one of {sorted(_RESULT_TYPES)}."
+            )
+        payload = self._request("GET", f"/api/parsing/job/{job_id}/result/{result_type}")
+        data = payload if isinstance(payload, dict) else {"result": payload}
+        return ParseResult(job_id=job_id, result_type=result_type, data=data)
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float | None = None,
+        max_wait: float | None = None,
+    ) -> Job:
+        """Block until a job reaches a terminal state (or ``max_wait`` elapses)."""
+        interval = poll_interval if poll_interval is not None else self.poll_interval
+        deadline = time.monotonic() + (max_wait if max_wait is not None else self.max_wait)
+        while True:
+            job = self.get_job(job_id)
+            if job.is_done:
+                return job
+            if time.monotonic() >= deadline:
+                raise JobTimeoutError(
+                    f"Job {job_id} did not finish within the timeout.", job_id=job_id
+                )
+            time.sleep(interval)
+
+    # -- one-shot convenience ---------------------------------------------- #
+
+    def parse(
+        self,
+        file: FileInput,
+        *,
+        result_type: str = "markdown",
+        case_id: str | None = None,
+        source_path: str | None = None,
+        language: str | Iterable[str] | None = None,
+        target_pages: str | None = None,
+        max_pages: int | None = None,
+        detect_repair: bool | None = None,
+        poll_interval: float | None = None,
+        max_wait: float | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> ParseResult:
+        """Upload, wait for completion, and return the parsed result.
+
+        Raises :class:`~localparse.JobFailedError` if the parse ends in ERROR/
+        CANCELED, and :class:`~localparse.JobTimeoutError` if it doesn't finish
+        within ``max_wait``.
+        """
+        job = self.upload(
+            file,
+            result_type=result_type,
+            case_id=case_id,
+            source_path=source_path,
+            language=language,
+            target_pages=target_pages,
+            max_pages=max_pages,
+            detect_repair=detect_repair,
+            extra=extra,
+        )
+        job = self.wait(job.id, poll_interval=poll_interval, max_wait=max_wait)
+        if not job.is_success:
+            raise JobFailedError(
+                f"Job {job.id} ended as {job.status}: {job.error_message}",
+                job_id=job.id,
+                status=job.status,
+            )
+        return self.get_result(job.id, result_type=result_type)
+
+    # -- case / batch ------------------------------------------------------- #
+
+    def case_manifest(self, case_id: str) -> dict[str, Any]:
+        """List a case's already-ingested docs (content hash + status)."""
+        payload = self._request("GET", f"/api/parsing/case/{case_id}/manifest")
+        return payload if isinstance(payload, dict) else {}
+
+    def case_failures(self, case_id: str, *, include_resolved: bool = False) -> dict[str, Any]:
+        """List a case's failed documents (for monitoring / reingest)."""
+        params = {"include_resolved": "1"} if include_resolved else None
+        payload = self._request(
+            "GET", f"/api/parsing/case/{case_id}/failures", params=params
+        )
+        return payload if isinstance(payload, dict) else {}
+
+    def parse_folder(
+        self,
+        folder: str | os.PathLike[str],
+        *,
+        case_id: str,
+        result_type: str = "markdown",
+        resume: bool = True,
+        extensions: Iterable[str] | None = None,
+        detect_repair: bool | None = None,
+        language: str | Iterable[str] | None = None,
+        on_progress: Callable[[str, ParseResult | None], None] | None = None,
+    ) -> list[ParseResult]:
+        """Ingest every file in ``folder`` into ``case_id``, skipping unchanged ones.
+
+        Walks ``folder`` recursively, persisting each file under ``case_id`` with a
+        folder-relative ``source_path``. When ``resume`` is set (default), files
+        whose sha256 already appears in the case manifest with an ``ok``/
+        ``needs_review`` status are skipped, so a re-run only parses the delta.
+        ``on_progress(relative_path, result_or_None)`` is called per file (result
+        is ``None`` for a skipped file). Returns the results that were parsed.
+        """
+        root = Path(folder)
+        if not root.is_dir():
+            raise ValueError(f"{folder!r} is not a directory.")
+
+        exts = {e.lower().lstrip(".") for e in extensions} if extensions else None
+        already: set[str] = set()
+        if resume:
+            manifest = self.case_manifest(case_id)
+            for doc in manifest.get("documents", []) or []:
+                if isinstance(doc, dict) and doc.get("status") in _RESUMABLE_STATUSES:
+                    file_hash = doc.get("file_hash")
+                    if isinstance(file_hash, str):
+                        already.add(file_hash)
+
+        results: list[ParseResult] = []
+        for path in sorted(p for p in root.rglob("*") if p.is_file()):
+            if exts is not None and path.suffix.lower().lstrip(".") not in exts:
+                continue
+            rel = path.relative_to(root).as_posix()
+            if resume and _sha256(path) in already:
+                if on_progress:
+                    on_progress(rel, None)
+                continue
+            result = self.parse(
+                path,
+                result_type=result_type,
+                case_id=case_id,
+                source_path=rel,
+                detect_repair=detect_repair,
+                language=language,
+            )
+            results.append(result)
+            if on_progress:
+                on_progress(rel, result)
+        return results
+
+
+def _detail(resp: requests.Response) -> str:
+    """Best-effort human message from an error response."""
+    try:
+        body = resp.json()
+    except ValueError:
+        return f"HTTP {resp.status_code}: {resp.text[:200]}" if resp.text else f"HTTP {resp.status_code}"
+    if isinstance(body, dict):
+        message = body.get("detail") or body.get("message") or body.get("error")
+        if message:
+            return f"HTTP {resp.status_code}: {message}"
+    return f"HTTP {resp.status_code}"
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()

localparse-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: localparse
+Version: 0.1.0
+Summary: Official Python client for the LocalParse document-parsing API (LlamaParse-compatible).
+Project-URL: Homepage, https://localparse.com
+Project-URL: Documentation, https://localparse.com/docs
+Project-URL: Source, https://github.com/stevencoveta/Agent-ingestor
+Author: LocalParse
+License: MIT
+Keywords: document parsing,llamaparse,localparse,ocr,pdf,tables
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# LocalParse — Python client
+
+Official Python client for the [LocalParse](https://localparse.com) document-parsing
+API. LocalParse is a **drop-in LlamaParse-compatible** parser with a deterministic
+accuracy layer: table-detection recovery (catches tables a layout model misses)
+and oracle-free **financial-identity checks** (flags `Total`s that don't reconcile).
+
+## Install
+
+```bash
+pip install localparse
+```
+
+## Quickstart
+
+```python
+from localparse import LocalParse
+
+client = LocalParse(api_key="lp-...")          # or set LOCALPARSE_API_KEY
+
+result = client.parse("invoice.pdf", result_type="markdown")
+print(result.markdown)
+
+# Accuracy signal that plain OCR/LLM parsers don't give you:
+print(result.identity_check)     # {tables_checked, violations, ...} or None
+print(result.recovered_tables)   # tables recovered by detect_repair
+```
+
+Fetch JSON or the ingestion-ready structured contract instead:
+
+```python
+result = client.parse("10k.pdf", result_type="json")
+for page in result.pages:
+    ...
+
+structured = client.parse("10k.pdf", result_type="structured")
+```
+
+## Persist a whole folder (incremental)
+
+Ingest a data room into a named **case**; re-runs only parse new/changed files
+(unchanged files are skipped by content hash):
+
+```python
+results = client.parse_folder(
+    "./data-room",
+    case_id="acme",
+    resume=True,
+    on_progress=lambda path, res: print("parsed" if res else "skipped", path),
+)
+```
+
+## Full control (async jobs)
+
+```python
+job = client.upload("big.pdf", result_type="json", case_id="acme")
+job = client.wait(job.id)
+if job.is_success:
+    result = client.get_result(job.id, "json")
+```
+
+## Configuration
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `api_key` | `LOCALPARSE_API_KEY` env | Bearer token for the API. |
+| `base_url` | `https://api.localparse.com` | Point at a self-hosted instance if needed. |
+| `timeout` | `60` | Per-request HTTP timeout (seconds). |
+| `poll_interval` | `2.0` | Seconds between status polls in `parse`/`wait`. |
+| `max_wait` | `900` | Max seconds to wait for a job before `JobTimeoutError`. |
+
+## Errors
+
+`AuthenticationError` (401/403), `QuotaExceededError` (402), `NotFoundError` (404),
+`RateLimitError` (429, with `.retry_after`), `APIError` (other non-2xx),
+`JobFailedError` (job ended ERROR/CANCELED), `JobTimeoutError` — all subclass
+`LocalParseError`.

localparse-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+localparse/__init__.py,sha256=YBQvmZkziMqwIyziHLwY7JDVamKbQgU_BW8SCU1VfHE,1019
+localparse/_errors.py,sha256=Uv6TSayiDfeKUREV8n4uN4VNtSXoWZfvPyfI12Lmx5U,1739
+localparse/_models.py,sha256=-Kzb1gos1LInHaKDbSGTgAA-D_ekou7RN6pdaF3ItfE,3225
+localparse/client.py,sha256=SiX8TejX3xWs9eEmjj8J5Y7HOkovyGoeQvUlOPRIlAI,13512
+localparse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+localparse-0.1.0.dist-info/METADATA,sha256=NfxevZDQzjOOhFfhGRTNVHihTD0_AMugFWVKnw3k9n0,3037
+localparse-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+localparse-0.1.0.dist-info/RECORD,,

localparse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any