thresh-sdk 0.2.0__py3-none-any.whl

thresh/__init__.py

@@ -0,0 +1,217 @@
+"""Thresh — documents in, schema-conformant JSON out.
+
+    from thresh import Thresh
+
+    client = Thresh(api_key="th_live_...")
+    doc = client.upload("contract.pdf", fields=["purchase_price", "closing_date"],
+                        questions=["Is the contract contingent upon financing?"])
+    result = client.wait(doc.id)
+    print(result.fields["purchase_price"])
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO, Any, Optional, Union
+
+import httpx
+
+__all__ = ["Thresh", "Document", "Result", "ThreshError", "verify_webhook_signature"]
+
+# KEEP IN SYNC with the deployed domain (#50 changes this; bump the SDK version)
+DEFAULT_BASE_URL = "https://usethresh.com"
+DEFAULT_TIMEOUT_S = 30.0
+DEFAULT_POLL_INTERVAL_S = 4.0
+
+
+class ThreshError(Exception):
+    """API error with the envelope's type, message, and request id."""
+
+    def __init__(self, status: int, error_type: str, message: str, request_id: Optional[str]):
+        super().__init__(f"{error_type}: {message} (status {status}, request {request_id})")
+        self.status = status
+        self.error_type = error_type
+        self.request_id = request_id
+
+
+class ExtractionTimeout(ThreshError):
+    def __init__(self, document_id: str, waited_s: float):
+        Exception.__init__(  # bypass ThreshError.__init__: no HTTP envelope here
+            self, f"document {document_id} still processing after {waited_s:.0f}s"
+        )
+        self.status = 0
+        self.error_type = "timeout"
+        self.request_id = None
+
+
+@dataclass(frozen=True)
+class Document:
+    id: str
+    filename: str
+    status: str
+    created_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Result:
+    id: str
+    status: str
+    fields: dict = field(default_factory=dict)
+    tables: dict = field(default_factory=dict)
+    answers: list = field(default_factory=list)
+    error: Optional[str] = None
+    cost_usd: Optional[float] = None
+    latency_s: Optional[float] = None
+
+    def answer(self, question: str) -> Optional[str]:
+        """The answer for an exact question string, if present."""
+        for pair in self.answers:
+            if pair.get("question") == question:
+                return pair.get("answer")
+        return None
+
+
+def _raise_for(res: httpx.Response) -> None:
+    if res.is_success:
+        return
+    try:
+        err = res.json().get("error", {})
+    except ValueError:
+        err = {}
+    raise ThreshError(
+        res.status_code,
+        err.get("type", "api_error"),
+        err.get("message", res.text[:200] or res.reason_phrase),
+        err.get("request_id"),
+    )
+
+
+class Thresh:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        if not api_key.startswith("th_"):
+            raise ValueError("api_key should look like th_live_...")
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Thresh":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- documents -----------------------------------------------------------
+
+    def upload(
+        self,
+        file: Union[str, Path, IO[bytes]],
+        *,
+        fields: Optional[list] = None,
+        tables: Optional[list] = None,
+        questions: Optional[list] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Document:
+        """Upload a PDF with an extraction spec. Returns the queued document.
+
+        tables entries are {"name": ..., "columns": [...]}.
+        """
+        spec: dict[str, Any] = {
+            "fields": fields or [],
+            "tables": tables or [],
+            "questions": questions or [],
+        }
+        if not (spec["fields"] or spec["tables"] or spec["questions"]):
+            raise ValueError("request at least one field, table, or question")
+
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        if isinstance(file, (str, Path)):
+            path = Path(file)
+            with path.open("rb") as fh:
+                res = self._http.post(
+                    "/v1/documents",
+                    files={"file": (path.name, fh, "application/pdf")},
+                    data={"spec": json.dumps(spec)},
+                    headers=headers,
+                )
+        else:
+            res = self._http.post(
+                "/v1/documents",
+                files={"file": ("document.pdf", file, "application/pdf")},
+                data={"spec": json.dumps(spec)},
+                headers=headers,
+            )
+        _raise_for(res)
+        body = res.json()
+        return Document(
+            id=body["id"],
+            filename=body["filename"],
+            status=body["status"],
+            created_at=body.get("created_at"),
+        )
+
+    def result(self, document_id: str) -> Result:
+        """Current result snapshot; status tells you if it's done."""
+        res = self._http.get(f"/v1/documents/{document_id}/result")
+        if res.status_code not in (200, 202):
+            _raise_for(res)
+        body = res.json()
+        extracted = body.get("result") or {}
+        return Result(
+            id=body["id"],
+            status=body["status"],
+            fields=extracted.get("fields", {}),
+            tables=extracted.get("tables", {}),
+            answers=extracted.get("answers", []),
+            error=body.get("error"),
+            cost_usd=body.get("cost_usd"),
+            latency_s=body.get("latency_s"),
+        )
+
+    def wait(
+        self,
+        document_id: str,
+        timeout: float = 300.0,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_S,
+    ) -> Result:
+        """Poll until the document completes or fails."""
+        deadline = time.monotonic() + timeout
+        while True:
+            snapshot = self.result(document_id)
+            if snapshot.status in ("completed", "failed"):
+                return snapshot
+            if time.monotonic() >= deadline:
+                raise ExtractionTimeout(document_id, timeout)
+            time.sleep(poll_interval)
+
+
+def verify_webhook_signature(
+    secret: str, header: str, body: bytes, tolerance_s: int = 300
+) -> bool:
+    """Verify a Thresh-Signature header: t=<unix>,v1=<hmac-sha256(secret, t.body)>."""
+    try:
+        parts = dict(kv.split("=", 1) for kv in header.split(","))
+        t = int(parts["t"])
+        expected = parts["v1"]
+    except (KeyError, ValueError):
+        return False
+    if abs(time.time() - t) > tolerance_s:
+        return False
+    mac = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(mac, expected)

thresh_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: thresh-sdk
+Version: 0.2.0
+Summary: Official Python client for the Thresh document extraction API
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# thresh-sdk
+
+Official Python client for the [Thresh](https://github.com/Fillnull/thresh)
+document extraction API — documents in, schema-conformant JSON out.
+
+```python
+from thresh import Thresh
+
+client = Thresh(api_key="th_live_...")
+doc = client.upload(
+    "contract.pdf",
+    fields=["purchase_price", "closing_date", "buyer_name"],
+    tables=[{"name": "monthly_charges", "columns": ["item", "qty", "mrc"]}],
+    questions=["Is the contract contingent upon financing?"],
+)
+result = client.wait(doc.id)
+
+result.fields["purchase_price"]        # "399900"
+result.tables["monthly_charges"]       # [{"item": ..., "qty": ..., "mrc": ...}, ...]
+result.answer("Is the contract contingent upon financing?")  # "Yes"
+```
+
+- `upload(...)` accepts a path or a binary file object; pass `idempotency_key=`
+  to make retries safe.
+- `wait(id, timeout=300)` polls until `completed` or `failed` (failed results
+  return with `.error` set — no exception).
+- `verify_webhook_signature(secret, header, body)` validates
+  `Thresh-Signature` headers on webhook deliveries.
+- Errors raise `ThreshError` with `.status`, `.error_type`, and `.request_id`.
+
+Missing values come back as the string `"null"`; checkbox states as
+`"true"`/`"false"`.

thresh_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+thresh/__init__.py,sha256=rbHhOvqnodbzrQiq1l_4jFEEtsSBK6cX4N-qtv9p7Qs,7013
+thresh_sdk-0.2.0.dist-info/METADATA,sha256=MqkdcT5El8pqApdhgPSAC5U_AJWd4fVfFgWkePLPPlg,1445
+thresh_sdk-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thresh_sdk-0.2.0.dist-info/RECORD,,

thresh_sdk-0.2.0.dist-info/WHEEL

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