docxtract-sdk 1.0.0__py3-none-any.whl

docxtract/__init__.py

@@ -0,0 +1,45 @@
+"""Official Python SDK for the DocXtract document extraction API.
+
+Date: 2026-08-23 | Author: Alok | File: __init__.py
+
+    from docxtract import DocXtract
+
+    dx = DocXtract(os.environ["DOCXTRACT_API_KEY"])
+    result = dx.extract("invoice.pdf", model="invoice")
+    print(result["vendor"])
+
+Standard library only — no runtime dependencies.
+"""
+
+from .client import DocXtract, __version__
+from .errors import (
+    AuthenticationError,
+    DocXtractError,
+    ExtractionFailedError,
+    JobError,
+    QuotaError,
+    RateLimitError,
+    RequestError,
+    ServerError,
+    TransportError,
+    to_error,
+)
+from .models import Chunk, ExtractionResult, SplitManifest
+
+__all__ = [
+    "DocXtract",
+    "ExtractionResult",
+    "SplitManifest",
+    "Chunk",
+    "DocXtractError",
+    "AuthenticationError",
+    "QuotaError",
+    "RateLimitError",
+    "RequestError",
+    "ExtractionFailedError",
+    "JobError",
+    "ServerError",
+    "TransportError",
+    "to_error",
+    "__version__",
+]

docxtract/_http.py

@@ -0,0 +1,141 @@
+"""HTTP transport built on urllib — no third-party dependency.
+
+Date: 2026-08-23 | Author: Alok | File: _http.py
+Multipart bodies are encoded by hand because urllib has no equivalent of requests' `files=`.
+Keeping the SDK dependency-free means `pip install docxtract` cannot conflict with a
+project's pinned requests/httpx.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, Optional, Tuple
+
+from .errors import TransportError, to_error
+
+
+def encode_multipart(
+    fields: Dict[str, str],
+    file: Optional[Tuple[str, bytes, str]] = None,
+) -> Tuple[bytes, str]:
+    """Encode a multipart/form-data body.
+
+    ``file`` is ``(field_name, contents, filename)``. Returns ``(body, content_type)``.
+    """
+    boundary = uuid.uuid4().hex
+    parts: list[bytes] = []
+
+    for name, value in fields.items():
+        parts += [
+            f"--{boundary}\r\n".encode(),
+            f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
+            f"{value}\r\n".encode(),
+        ]
+
+    if file is not None:
+        name, content, filename = file
+        ctype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        parts += [
+            f"--{boundary}\r\n".encode(),
+            f'Content-Disposition: form-data; name="{name}"; filename="{os.path.basename(filename)}"\r\n'.encode(),
+            f"Content-Type: {ctype}\r\n\r\n".encode(),
+            content,
+            b"\r\n",
+        ]
+
+    parts.append(f"--{boundary}--\r\n".encode())
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+class Transport:
+    def __init__(self, api_key: str, base_url: str, timeout: int, user_agent: str) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+    ) -> Tuple[int, Dict[str, Any], Dict[str, str]]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        if query:
+            clean = {k: str(v) for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        req = urllib.request.Request(url, data=body, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Accept", "application/json")
+        # urllib's default UA is "Python-urllib/3.x", which WAFs treat as suspicious and
+        # which tells you nothing in server logs.
+        req.add_header("User-Agent", self.user_agent)
+        if content_type:
+            req.add_header("Content-Type", content_type)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status, raw, headers = resp.status, resp.read(), dict(resp.headers)
+        except urllib.error.HTTPError as exc:
+            # 4xx/5xx still carry a JSON body we want.
+            status, raw, headers = exc.code, exc.read(), dict(exc.headers or {})
+        except urllib.error.URLError as exc:
+            raise TransportError(
+                f"Request to {url} failed: {exc.reason}", code="transport_error"
+            ) from exc
+        except TimeoutError as exc:
+            raise TransportError(
+                f"Request to {url} timed out after {self.timeout}s", code="transport_error"
+            ) from exc
+
+        try:
+            parsed = json.loads(raw.decode("utf-8", "replace"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            snippet = raw.decode("utf-8", "replace").strip()[:120] or "an empty body"
+            raise TransportError(
+                f"Expected JSON from {url} but got {snippet} (HTTP {status}). "
+                "Check the base URL — note there is no /api prefix.",
+                code="transport_error",
+                status=status,
+            ) from exc
+
+        if not isinstance(parsed, dict):
+            raise TransportError(
+                f"Expected a JSON object from {url}, got {type(parsed).__name__}.",
+                code="transport_error",
+                status=status,
+            )
+
+        if parsed.get("success") is False or status >= 400:
+            err = parsed.get("error") or {}
+            reset = _header_int(headers, "X-RateLimit-Reset")
+            raise to_error(
+                err.get("message") or f"Request failed with HTTP {status}",
+                err.get("code") or "server_error",
+                status,
+                err.get("details") or {},
+                reset,
+            )
+
+        return status, parsed, headers
+
+
+def _header_int(headers: Dict[str, str], name: str) -> Optional[int]:
+    """Header lookup that is case-insensitive, since servers vary."""
+    for key, value in headers.items():
+        if key.lower() == name.lower():
+            try:
+                return int(value)
+            except (TypeError, ValueError):
+                return None
+    return None

docxtract/client.py

@@ -0,0 +1,242 @@
+"""DocXtract API client.
+
+Date: 2026-08-23 | Author: Alok | File: client.py
+``extract()`` is transparent over the sync and multi-page paths; the raw three calls stay
+public for callers who want to drive the flow themselves.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import time
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from ._http import Transport, encode_multipart
+from .errors import DocXtractError, JobError, RateLimitError, RequestError
+from .models import ExtractionResult, SplitManifest
+
+__version__ = "1.0.0"
+
+# Mirrors the server's ALLOWED_FILE_TYPES so a bad file fails before the network call.
+_ACCEPTED = frozenset({"application/pdf", "image/jpeg", "image/png"})
+_MAX_BYTES = 10 * 1024 * 1024
+
+ProgressCallback = Callable[[int, int, str], None]
+
+
+class DocXtract:
+    """Client for the DocXtract v3.1 API.
+
+    ``base_path`` defaults to ``/v3.1``. Set ``/v3`` only if pinned to the older version —
+    it has no ``models`` and no multi-page support, and accepts PDF only.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.docxtract.io",
+        base_path: str = "/v3.1",
+        timeout: int = 120,
+        max_retries: int = 3,
+        chunk_pause_ms: int = 0,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        if not api_key:
+            raise RequestError("An api_key is required.", code="invalid_api_key")
+        if api_key.startswith("sk-"):
+            # One-character mistake that would otherwise surface as an opaque 401. Several
+            # other API providers use the sk- form.
+            raise RequestError(
+                "DocXtract keys start with an underscore: sk_... The value given uses a "
+                "hyphen, so it belongs to a different provider.",
+                code="invalid_api_key",
+            )
+
+        self.base_path = base_path.rstrip("/")
+        self.max_retries = max(0, max_retries)
+        self.chunk_pause_ms = chunk_pause_ms
+        self._http = Transport(
+            api_key,
+            base_url,
+            timeout,
+            user_agent or f"docxtract-python/{__version__} (+https://docxtract.io)",
+        )
+
+    # ── the one call most integrations need ───────────────────────────────────
+
+    def extract(
+        self,
+        file: str,
+        model: Optional[str] = None,
+        on_progress: Optional[ProgressCallback] = None,
+        **options: Any,
+    ) -> ExtractionResult:
+        """Extract a document, transparently handling the multi-page split.
+
+        A PDF over the server's page threshold is split into chunks by the API; this method
+        processes every chunk and returns the stitched result, so one call works at any page
+        count.
+        """
+        opts = self._options(model, options)
+        status, body, _ = self._upload(file, opts)
+
+        if status != 202:
+            if on_progress:
+                on_progress(1, 1, "complete")
+            return ExtractionResult.from_body(body)
+
+        manifest = SplitManifest.from_body(body)
+        self.process_manifest(manifest, model=model, on_progress=on_progress, **options)
+        return self.collect_result(manifest.job_id)
+
+    # ── raw three-call path ───────────────────────────────────────────────────
+
+    def split_document(self, file: str, model: Optional[str] = None, **options: Any) -> SplitManifest:
+        """POST documents and require the split branch."""
+        status, body, _ = self._upload(file, self._options(model, options))
+        if status != 202:
+            raise RequestError(
+                "Document was processed synchronously (under the page threshold) and produced "
+                "no split manifest. Use extract().",
+                code="invalid_request",
+                status=status,
+            )
+        return SplitManifest.from_body(body)
+
+    def process_chunk(self, chunk_job_id: str, model: Optional[str] = None, **options: Any) -> Dict[str, Any]:
+        """POST process for one chunk.
+
+        Idempotent — replaying a completed chunk is neither an error nor charged again.
+        """
+        body, ctype = encode_multipart({"options": json.dumps(self._options(model, options))})
+        _, parsed, _ = self._http.request(
+            "POST", self._path("process"),
+            query={"job_id": chunk_job_id}, body=body, content_type=ctype,
+        )
+        return {k: v for k, v in parsed.items() if k not in ("success", "data")}
+
+    def collect_result(self, job_id: str, finalize: bool = False) -> ExtractionResult:
+        """GET result for the parent job.
+
+        ``finalize=True`` is IRREVERSIBLE: it permanently deletes all extracted data for the
+        job after responding. Only pass it once the result is stored on your side.
+        """
+        query: Dict[str, Any] = {"job_id": job_id}
+        if finalize:
+            query["finalize"] = "true"
+        _, body, _ = self._http.request("GET", self._path("result"), query=query)
+        return ExtractionResult.from_body(body)
+
+    def process_manifest(
+        self,
+        manifest: SplitManifest,
+        model: Optional[str] = None,
+        on_progress: Optional[ProgressCallback] = None,
+        **options: Any,
+    ) -> None:
+        """Process every chunk in page order, with retry.
+
+        Sequential by design: the API's default limit is 10 requests/minute, so parallel
+        chunk calls do not finish sooner — they turn the work into 429s. Use
+        ``chunk_pause_ms`` to pace calls on a tighter key.
+        """
+        total = manifest.chunk_count
+
+        for i, chunk in enumerate(manifest.chunks):
+            if manifest.expired:
+                raise JobError(
+                    f"Job {manifest.job_id} expired before all chunks were processed "
+                    f"({i} of {total} done). Re-upload the document.",
+                    code="job_expired",
+                    status=410,
+                    details={"job_id": manifest.job_id, "chunks_done": i, "chunks_total": total},
+                )
+
+            self._with_retry(lambda c=chunk: self.process_chunk(c.job_id, model, **options))
+            if on_progress:
+                on_progress(i + 1, total, "chunk")
+
+            if self.chunk_pause_ms > 0 and i + 1 < total:
+                time.sleep(self.chunk_pause_ms / 1000)
+
+    # ── discovery ─────────────────────────────────────────────────────────────
+
+    def models(self) -> List[Any]:
+        """Document types this key may use. Costs no credits — safe to call freely."""
+        if self.base_path != "/v3.1":
+            raise RequestError(
+                "models exists only in v3.1. Remove the base_path override to use it.",
+                code="method_not_allowed",
+            )
+        _, body, _ = self._http.request("GET", self._path("models"))
+        return list((body.get("data") or {}).get("models") or [])
+
+    def health(self) -> Dict[str, Any]:
+        _, body, _ = self._http.request("GET", self._path("health"))
+        return body
+
+    def authorised(self) -> bool:
+        """Whether the configured key is currently active."""
+        try:
+            _, body, _ = self._http.request("GET", self._path("authorised"))
+            return body.get("success") is True
+        except DocXtractError:
+            return False
+
+    # ── internals ─────────────────────────────────────────────────────────────
+
+    def _path(self, endpoint: str) -> str:
+        return f"{self.base_path}/{endpoint}"
+
+    @staticmethod
+    def _options(model: Optional[str], extra: Dict[str, Any]) -> Dict[str, Any]:
+        opts = dict(extra)
+        if model:
+            opts["model"] = model
+        return opts
+
+    def _upload(self, file: str, options: Dict[str, Any]):
+        content, filename = self._read_file(file)
+        body, ctype = encode_multipart(
+            {"options": json.dumps(options)}, ("file", content, filename)
+        )
+        return self._http.request(
+            "POST", self._path("documents"), body=body, content_type=ctype
+        )
+
+    def _read_file(self, file: str):
+        """Validate locally so an unsupported file never costs a round trip."""
+        if not os.path.isfile(file):
+            raise RequestError(f"File not found or not readable: {file}", code="invalid_file")
+
+        size = os.path.getsize(file)
+        if size > _MAX_BYTES:
+            raise RequestError(
+                f"File is {size / 1048576:.1f} MB; the limit is {_MAX_BYTES // 1048576} MB.",
+                code="file_too_large",
+                details={"size": size},
+            )
+
+        guessed = mimetypes.guess_type(file)[0]
+        if guessed not in _ACCEPTED:
+            raise RequestError(
+                f"Unsupported file type {guessed or 'unknown'!r}. Accepted: PDF, JPG, PNG.",
+                code="invalid_file_type",
+                details={"uploaded_type": guessed, "accepted_types": sorted(_ACCEPTED)},
+            )
+
+        with open(file, "rb") as fh:
+            return fh.read(), file
+
+    def _with_retry(self, call: Callable[[], Any]) -> Any:
+        """Retry retryable failures, honouring X-RateLimit-Reset over a guessed backoff."""
+        for attempt in range(self.max_retries + 1):
+            try:
+                return call()
+            except DocXtractError as exc:
+                if attempt >= self.max_retries or not exc.retryable:
+                    raise
+                wait = exc.retry_after if isinstance(exc, RateLimitError) and exc.retry_after is not None else 2 ** attempt
+                time.sleep(min(wait, 60))

docxtract/errors.py

@@ -0,0 +1,140 @@
+"""Typed exceptions mirroring the API's stable error codes.
+
+Date: 2026-08-23 | Author: Alok | File: errors.py
+Branch on the exception class or ``code``, never on the message — wording is not stable.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional, Type
+
+# Retrying these could plausibly succeed. Deliberately conservative: caller input errors,
+# dead jobs and exhausted credits are excluded.
+_RETRYABLE = frozenset({
+    "rate_limit_exceeded",
+    "chunk_in_progress",
+    "extraction_failed",
+    "persist_failed",
+    "server_error",
+    "server_busy",
+})
+
+
+class DocXtractError(Exception):
+    """Base for every API error."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "server_error",
+        status: int = 0,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.details = details or {}
+
+    @property
+    def retryable(self) -> bool:
+        return self.code in _RETRYABLE
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+class AuthenticationError(DocXtractError):
+    """invalid_api_key, expired_api_key (401)."""
+
+
+class QuotaError(DocXtractError):
+    """usage_limit_exceeded, insufficient_credits (402)."""
+
+
+class RequestError(DocXtractError):
+    """Caller input: invalid_request, invalid_file, invalid_file_type, file_too_large,
+    invalid_options, unknown_model, page_limit_exceeded, method_not_allowed."""
+
+
+class ExtractionFailedError(DocXtractError):
+    """extraction_failed (422). Note this is billed on the synchronous path."""
+
+
+class JobError(DocXtractError):
+    """job_not_found, job_expired, chunk_in_progress, chunk_source_lost."""
+
+
+class ServerError(DocXtractError):
+    """server_error, persist_failed, server_busy (5xx)."""
+
+
+class RateLimitError(DocXtractError):
+    """rate_limit_exceeded, too_many_open_jobs (429)."""
+
+    def __init__(self, *args: Any, reset_at: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.reset_at = reset_at
+
+    @property
+    def retry_after(self) -> Optional[int]:
+        """Seconds to wait, or None when the server sent no reset header.
+
+        Returns None rather than a guess so callers use their own backoff knowingly.
+        """
+        if self.reset_at is None:
+            return None
+        return max(0, self.reset_at - int(time.time()))
+
+
+class TransportError(DocXtractError):
+    """Network-level failure or a non-JSON body — the API never answered."""
+
+    @property
+    def retryable(self) -> bool:
+        return True
+
+
+_MAP: Dict[str, Type[DocXtractError]] = {
+    "invalid_api_key": AuthenticationError,
+    "expired_api_key": AuthenticationError,
+    "usage_limit_exceeded": QuotaError,
+    "insufficient_credits": QuotaError,
+    "rate_limit_exceeded": RateLimitError,
+    "too_many_open_jobs": RateLimitError,
+    "invalid_request": RequestError,
+    "invalid_file": RequestError,
+    "invalid_file_type": RequestError,
+    "file_too_large": RequestError,
+    "invalid_options": RequestError,
+    "unknown_model": RequestError,
+    "page_limit_exceeded": RequestError,
+    "method_not_allowed": RequestError,
+    "extraction_failed": ExtractionFailedError,
+    "job_not_found": JobError,
+    "job_expired": JobError,
+    "chunk_in_progress": JobError,
+    "chunk_source_lost": JobError,
+    "server_error": ServerError,
+    "persist_failed": ServerError,
+    "server_busy": ServerError,
+}
+
+
+def to_error(
+    message: str,
+    code: str,
+    status: int,
+    details: Optional[Dict[str, Any]] = None,
+    reset_at: Optional[int] = None,
+) -> DocXtractError:
+    """Build the typed exception for an API error code.
+
+    An unrecognised code falls back to the base class rather than raising, so a new
+    server-side code cannot break a deployed copy of this SDK.
+    """
+    cls = _MAP.get(code, DocXtractError)
+    if cls is RateLimitError:
+        return RateLimitError(message, code=code, status=status, details=details, reset_at=reset_at)
+    return cls(message, code=code, status=status, details=details)

docxtract/models.py

@@ -0,0 +1,188 @@
+"""Result and manifest wrappers.
+
+Date: 2026-08-23 | Author: Alok | File: models.py
+The API places metadata at the root level beside ``data``, so both are exposed without
+pretending ``data`` has a fixed schema — its shape varies by document type.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+class ExtractionResult:
+    """An extraction result — covers both the sync response and the stitched multi-page one."""
+
+    def __init__(self, data: Dict[str, Any], meta: Optional[Dict[str, Any]] = None) -> None:
+        self.data = data
+        self.meta = meta or {}
+
+    @classmethod
+    def from_body(cls, body: Dict[str, Any]) -> "ExtractionResult":
+        meta = {k: v for k, v in body.items() if k not in ("data", "success")}
+        data = body.get("data") or {}
+        if not isinstance(data, dict):
+            data = {"value": data}
+        return cls(data, meta)
+
+    def get(self, path: str, default: Any = None) -> Any:
+        """Dot-path read: get('Header.pages'), get('line_items.0.hsn')."""
+        node: Any = self.data
+        for seg in path.split("."):
+            if isinstance(node, dict) and seg in node:
+                node = node[seg]
+            elif isinstance(node, list) and seg.isdigit() and int(seg) < len(node):
+                node = node[int(seg)]
+            else:
+                return default
+        return node
+
+    # ── metadata ──────────────────────────────────────────────────────────────
+    @property
+    def pages(self) -> Optional[int]:
+        return self.meta.get("pages")
+
+    @property
+    def processing_time_ms(self) -> Optional[int]:
+        return self.meta.get("processing_time_ms")
+
+    @property
+    def model_used(self) -> Optional[str]:
+        return self.meta.get("model_used")
+
+    @property
+    def extraction_id(self) -> Optional[str]:
+        """Present only when store_db was true, which is not the default server-side."""
+        return self.meta.get("extraction_id")
+
+    # ── multi-page ────────────────────────────────────────────────────────────
+    @property
+    def job_id(self) -> Optional[str]:
+        return self.meta.get("job_id")
+
+    @property
+    def complete(self) -> bool:
+        """A synchronous result is complete by definition; only a partial collect says no."""
+        return self.meta.get("status", "complete") == "complete"
+
+    @property
+    def pending_pages(self) -> List[int]:
+        return list(self.meta.get("pending_pages") or [])
+
+    @property
+    def failed_pages(self) -> List[int]:
+        return list(self.meta.get("failed_pages") or [])
+
+    @property
+    def warnings(self) -> List[str]:
+        return list(self.meta.get("warnings") or [])
+
+    @property
+    def credits_used(self) -> Optional[int]:
+        return self.meta.get("credits_used")
+
+    # ── convenience ───────────────────────────────────────────────────────────
+    def __getitem__(self, key: str) -> Any:
+        return self.data[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.data
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"data": self.data, **self.meta}
+
+    def to_dataframe(self, path: Optional[str] = None):
+        """Row-shaped extractions (invoice line items, bank statement rows) as a DataFrame.
+
+        Requires pandas: ``pip install 'docxtract[pandas]'``. Pass ``path`` to point at the
+        list, or leave it out to use the first list of dicts found in ``data``.
+        """
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover - depends on the environment
+            raise ImportError(
+                "to_dataframe() needs pandas. Install with: pip install 'docxtract[pandas]'"
+            ) from exc
+
+        rows = self.get(path) if path else None
+        if rows is None:
+            rows = next(
+                (v for v in self.data.values()
+                 if isinstance(v, list) and v and isinstance(v[0], dict)),
+                None,
+            )
+        if rows is None:
+            raise ValueError(
+                "No row-shaped list found in the extracted data. Pass an explicit path, "
+                "e.g. to_dataframe('line_items')."
+            )
+        return pd.DataFrame(rows)
+
+    def __repr__(self) -> str:
+        return f"ExtractionResult(fields={len(self.data)}, complete={self.complete})"
+
+
+class Chunk:
+    """One entry from the 202 split manifest."""
+
+    __slots__ = ("job_id", "pages")
+
+    def __init__(self, job_id: str, pages: str) -> None:
+        self.job_id = job_id
+        self.pages = pages
+
+    def __repr__(self) -> str:
+        return f"Chunk(job_id={self.job_id!r}, pages={self.pages!r})"
+
+
+class SplitManifest:
+    """The 202 response when a PDF exceeds the server's page threshold."""
+
+    def __init__(self, job_id: str, pages: int, chunks: List[Chunk], expires_at: Optional[str]) -> None:
+        self.job_id = job_id
+        self.pages = pages
+        self.chunks = chunks
+        self.expires_at = expires_at
+
+    @classmethod
+    def from_body(cls, body: Dict[str, Any]) -> "SplitManifest":
+        raw = body.get("data") or []
+        chunks = [
+            Chunk(str(c.get("job_id", "")), str(c.get("pages", "")))
+            for c in raw
+            if isinstance(c, dict)
+        ]
+        return cls(
+            str(body.get("job_id", "")),
+            int(body.get("pages") or 0),
+            chunks,
+            body.get("expires_at"),
+        )
+
+    @property
+    def expires_at_unix(self) -> Optional[int]:
+        if not self.expires_at:
+            return None
+        try:
+            dt = datetime.fromisoformat(str(self.expires_at).replace("Z", "+00:00"))
+        except ValueError:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+
+    @property
+    def expired(self) -> bool:
+        """An absent expiry must not read as expired — that would abandon a valid job."""
+        ts = self.expires_at_unix
+        if ts is None:
+            return False
+        return datetime.now(timezone.utc).timestamp() >= ts
+
+    @property
+    def chunk_count(self) -> int:
+        return len(self.chunks)
+
+    def __repr__(self) -> str:
+        return f"SplitManifest(job_id={self.job_id!r}, pages={self.pages}, chunks={self.chunk_count})"

docxtract_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: docxtract-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the DocXtract document extraction API
+Project-URL: Homepage, https://docxtract.io
+Project-URL: Documentation, https://docs.docxtract.io
+Project-URL: Source, https://github.com/docxtractio/python-sdk
+Project-URL: Issues, https://github.com/docxtractio/python-sdk/issues
+Author: RPATech
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document-extraction,docxtract,idp,invoice,kyc,ocr
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# docxtract
+
+Official Python client for the [DocXtract](https://docxtract.io) document extraction API.
+
+## Requirements
+
+Python 3.9+. **No dependencies** — standard library only (`urllib`), so `pip install
+docxtract` pulls nothing and cannot conflict with your project's pinned `requests` or
+`httpx`.
+
+## Install
+
+```bash
+pip install docxtract-sdk
+```
+
+> **Note** — the package is `docxtract-sdk` but the import is `docxtract`. The shorter name
+> was already taken on PyPI by an unrelated DOCX text extractor.
+
+## Get an API key
+
+The SDK is free and open source. The API it talks to needs an account.
+
+1. Go to **[docxtract.io](https://docxtract.io)** and choose **Start Free Trial**
+2. Credentials arrive by email — no card required, no sales call
+3. Sign in at **[app.docxtract.io](https://app.docxtract.io)** and copy your key from **Settings**
+
+Keep the key in an environment variable, never in source control:
+
+```bash
+export DOCXTRACT_API_KEY=sk_your_api_key
+```
+
+Two calls cost no credits, so you can confirm setup before spending anything:
+
+```python
+dx.authorised()   # is the key active?
+dx.models()       # which document types may it use?
+```
+
+Need higher limits, more credits, or a custom document type? support@docxtract.io.
+
+## Quickstart
+
+```python
+import os
+from docxtract import DocXtract
+
+dx = DocXtract(os.environ["DOCXTRACT_API_KEY"])
+
+result = dx.extract("invoice.pdf", model="invoice")
+
+print(result["vendor"])
+print(result.get("line_items.0.hsn"))   # dot paths for nested values
+print(result.pages, result.extraction_id)
+```
+
+> DocXtract keys use an **underscore** (`sk_`). A hyphen after `sk` means the key belongs to
+> a different API provider — the SDK rejects it up front rather than letting you debug a 401.
+
+## Large PDFs are the point of this SDK
+
+The API does not process a PDF over 3 pages synchronously. It splits the document and returns
+`202` with a chunk manifest; you then call `process` per chunk and `result` to
+collect, handling retries, single-flight conflicts, a 2-hour job TTL, and partial results.
+
+`extract()` does all of it:
+
+```python
+result = dx.extract("500-page-statement.pdf", model="bank_statement")
+```
+
+Same call, any page count. With progress:
+
+```python
+dx.extract("big.pdf", model="invoice",
+           on_progress=lambda done, total, stage: print(f"{done}/{total}"))
+```
+
+### Why chunks run sequentially
+
+The API's default rate limit is 10 requests per minute, so parallel chunk calls do not finish
+sooner — they turn the work into `429`s. Pace them if your key is tighter:
+
+```python
+dx = DocXtract(key, chunk_pause_ms=500)
+```
+
+### Manual control
+
+```python
+manifest = dx.split_document("big.pdf", model="invoice")
+
+for chunk in manifest.chunks:
+    dx.process_chunk(chunk.job_id, model="invoice")   # safe to retry
+
+result = dx.collect_result(manifest.job_id)
+
+if not result.complete:
+    print(result.failed_pages, result.pending_pages)
+```
+
+`collect_result()` is a pure read, re-fetchable within the TTL — usable as a progress poll
+from a separate worker.
+
+> **`collect_result(job_id, finalize=True)` is irreversible.** It permanently deletes the
+> job's extracted data. Only pass it once the result is stored on your side.
+
+## Tabular extractions
+
+Invoice line items and bank statement rows come back as lists of dicts:
+
+```python
+df = result.to_dataframe("line_items")   # needs: pip install 'docxtract-sdk[pandas]'
+```
+
+With no argument it uses the first row-shaped list it finds in the data.
+
+## Discovering document types
+
+```python
+dx.models()   # costs no credits — safe to call freely
+```
+
+## Error handling
+
+```python
+from docxtract import DocXtractError, RateLimitError, QuotaError
+
+try:
+    dx.extract("invoice.pdf", model="invoice")
+except RateLimitError as exc:
+    time.sleep(exc.retry_after or 30)     # from X-RateLimit-Reset
+except QuotaError:
+    pass                                   # out of credits — do not retry
+except DocXtractError as exc:
+    if exc.retryable:
+        requeue()
+    else:
+        raise
+```
+
+Or branch on the code:
+
+```python
+except DocXtractError as exc:
+    match exc.code:
+        case "insufficient_credits": notify_billing()
+        case "unknown_model":        report_bad_model(exc.details)
+        case _:
+            if not exc.retryable:
+                raise
+```
+
+| Exception | Codes |
+|---|---|
+| `AuthenticationError` | `invalid_api_key`, `expired_api_key` |
+| `QuotaError` | `usage_limit_exceeded`, `insufficient_credits` |
+| `RateLimitError` | `rate_limit_exceeded`, `too_many_open_jobs` |
+| `RequestError` | `invalid_request`, `invalid_file`, `invalid_file_type`, `file_too_large`, `invalid_options`, `unknown_model`, `page_limit_exceeded`, `method_not_allowed` |
+| `ExtractionFailedError` | `extraction_failed` |
+| `JobError` | `job_not_found`, `job_expired`, `chunk_in_progress`, `chunk_source_lost` |
+| `ServerError` | `server_error`, `persist_failed`, `server_busy` |
+| `TransportError` | network failure — the API never answered |
+
+An unrecognised code falls back to `DocXtractError` rather than raising, so a new server-side
+code cannot break a deployed copy.
+
+> **Billing note.** `extraction_failed` on the synchronous path **still deducts 1 credit**. On
+> the multi-page path the chunk stays available and is not charged until it succeeds.
+> `persist_failed` charges nothing.
+
+## Configuration
+
+```python
+dx = DocXtract(
+    api_key=os.environ["DOCXTRACT_API_KEY"],
+    base_url="https://api.docxtract.io",   # default — no /api prefix
+    base_path="/v3.1",                     # default
+    timeout=120,                           # seconds
+    max_retries=3,
+    chunk_pause_ms=0,
+)
+```
+
+> If you see a `TransportError` about non-JSON output, the base URL is usually wrong. `/api`
+> is the server's docroot, not part of the public path.
+
+`base_path="/v3"` exists for customers still pinned to the old version. v3 has no
+`models` and no multi-page support; `models()` raises a clear error rather than a
+confusing 404.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Offline: no API key or network needed.
+
+## Links
+
+- Documentation — https://docs.docxtract.io
+- Interactive API reference — https://app.docxtract.io/api-reference.php
+- Support — support@docxtract.io
+
+---
+
+**Built by RPATech** | [docxtract.io](https://docxtract.io)

docxtract_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+docxtract/__init__.py,sha256=YuW6hV62zBER6pT5EjLeOw-DlmAI1RzVz4SsIDFAvP4,987
+docxtract/_http.py,sha256=c8IvqC6UQ4N1dtnp3NlCzOrhyAm7_d3GKPWoXwHYG2U,5179
+docxtract/client.py,sha256=Khv3lEp4eDQlehX4EgRQky1FSk-Ei5wZGw7sx656Gc8,9973
+docxtract/errors.py,sha256=yWYo0WH4LbtjO_rIDXNJJZFNs2AOOV06xDUMkNbrbg4,4261
+docxtract/models.py,sha256=q89byoURzy6pOKXGw71vB82QG7VK-wF430vpM0xl79E,6738
+docxtract/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docxtract_sdk-1.0.0.dist-info/METADATA,sha256=MGA2PCC5P7eM6qBy5_96wFlbAPeiiZRmqq7RkwrczU0,7182
+docxtract_sdk-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+docxtract_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=dWyRX2BAzXjLwqp3epPqXGvFarLWzY3vgDKvsaR0Uyg,1064
+docxtract_sdk-1.0.0.dist-info/RECORD,,

docxtract_sdk-1.0.0.dist-info/WHEEL

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

docxtract_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RPATech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.