docxtract-sdk 1.0.0__tar.gz

docxtract_sdk-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+/dist/
+/build/
+*.egg-info/
+.venv/

docxtract_sdk-1.0.0/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.

docxtract_sdk-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,209 @@
+# 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/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# Distribution name is docxtract-sdk: plain `docxtract` was already taken on PyPI
+# (an unrelated DOCX text extractor, v0.1.0, 2025). The import name stays `docxtract`.
+name = "docxtract-sdk"
+version = "1.0.0"
+description = "Official Python SDK for the DocXtract document extraction API"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "RPATech" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["docxtract", "document-extraction", "idp", "ocr", "invoice", "kyc"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing",
+    "Typing :: Typed",
+]
+# No runtime dependencies: the SDK uses only the standard library, so `pip install docxtract`
+# pulls nothing and cannot conflict with a project's pinned requests/httpx.
+dependencies = []
+
+[project.urls]
+Homepage = "https://docxtract.io"
+Documentation = "https://docs.docxtract.io"
+Source = "https://github.com/docxtractio/python-sdk"
+Issues = "https://github.com/docxtractio/python-sdk/issues"
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docxtract"]

docxtract_sdk-1.0.0/src/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_sdk-1.0.0/src/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