thresh-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{thresh_sdk-0.2.0 → thresh_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thresh-sdk
-Version: 0.2.0
+Version: 0.4.0
 Summary: Official Python client for the Thresh document extraction API
 Requires-Python: >=3.9
 Requires-Dist: httpx>=0.27
@@ -30,6 +30,10 @@ 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.
+- No schema? `client.upload("contract.pdf")` runs auto-extraction: the engine
+  discovers and names the fields and tables itself. Refine what it found, then
+  `client.create_template("sale-contract", fields=[...])` and reuse it with
+  `client.upload("next.pdf", template="sale-contract")`.
 - `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_sdk-0.2.0 → thresh_sdk-0.4.0}/README.md

@@ -22,6 +22,10 @@ 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.
+- No schema? `client.upload("contract.pdf")` runs auto-extraction: the engine
+  discovers and names the fields and tables itself. Refine what it found, then
+  `client.create_template("sale-contract", fields=[...])` and reuse it with
+  `client.upload("next.pdf", template="sale-contract")`.
 - `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_sdk-0.2.0 → thresh_sdk-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "thresh-sdk"
-version = "0.2.0"
+version = "0.4.0"
 description = "Official Python client for the Thresh document extraction API"
 readme = "README.md"
 requires-python = ">=3.9"

{thresh_sdk-0.2.0 → thresh_sdk-0.4.0}/src/thresh/__init__.py

@@ -17,7 +17,7 @@ import json
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import IO, Any, Optional, Union
+from typing import IO, Optional, Union
 
 import httpx
 
@@ -62,6 +62,8 @@ class Result:
     id: str
     status: str
     fields: dict = field(default_factory=dict)
+    # per-field provenance: name -> {"page": int|None, "confidence": "high"|"low"}
+    field_meta: dict = field(default_factory=dict)
     tables: dict = field(default_factory=dict)
     answers: list = field(default_factory=list)
     error: Optional[str] = None
@@ -126,19 +128,27 @@ class Thresh:
         fields: Optional[list] = None,
         tables: Optional[list] = None,
         questions: Optional[list] = None,
+        template: Optional[str] = None,
         idempotency_key: Optional[str] = None,
     ) -> Document:
-        """Upload a PDF with an extraction spec. Returns the queued document.
+        """Upload a PDF. Returns the queued document.
 
-        tables entries are {"name": ..., "columns": [...]}.
+        Three modes: pass fields/tables/questions for a spec'd extraction,
+        template= to reuse a saved template by name, or neither to let the
+        engine discover the schema (auto-extraction). 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")
+        has_spec = bool(fields or tables or questions)
+        if has_spec and template:
+            raise ValueError("pass a spec or template=, not both")
+        data: dict[str, str] = {}
+        if has_spec:
+            data["spec"] = json.dumps(
+                {"fields": fields or [], "tables": tables or [], "questions": questions or []}
+            )
+        elif template:
+            data["template"] = template
+        # neither: auto-extraction discovers the schema
 
         headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
         if isinstance(file, (str, Path)):
@@ -147,14 +157,14 @@ class Thresh:
                 res = self._http.post(
                     "/v1/documents",
                     files={"file": (path.name, fh, "application/pdf")},
-                    data={"spec": json.dumps(spec)},
+                    data=data,
                     headers=headers,
                 )
         else:
             res = self._http.post(
                 "/v1/documents",
                 files={"file": ("document.pdf", file, "application/pdf")},
-                data={"spec": json.dumps(spec)},
+                data=data,
                 headers=headers,
             )
         _raise_for(res)
@@ -166,6 +176,39 @@ class Thresh:
             created_at=body.get("created_at"),
         )
 
+    def create_template(
+        self,
+        name: str,
+        *,
+        fields: Optional[list] = None,
+        tables: Optional[list] = None,
+        questions: Optional[list] = None,
+    ) -> dict:
+        """Save an extraction spec as a named template for reuse via upload(template=...)."""
+        res = self._http.post(
+            "/v1/templates",
+            json={
+                "name": name,
+                "spec": {
+                    "fields": fields or [],
+                    "tables": tables or [],
+                    "questions": questions or [],
+                },
+            },
+        )
+        _raise_for(res)
+        return res.json()
+
+    def templates(self) -> list:
+        """List this workspace's saved templates."""
+        res = self._http.get("/v1/templates")
+        _raise_for(res)
+        return res.json()["data"]
+
+    def delete_template(self, template_id: str) -> None:
+        res = self._http.delete(f"/v1/templates/{template_id}")
+        _raise_for(res)
+
     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")
@@ -177,6 +220,7 @@ class Thresh:
             id=body["id"],
             status=body["status"],
             fields=extracted.get("fields", {}),
+            field_meta=extracted.get("field_meta", {}),
             tables=extracted.get("tables", {}),
             answers=extracted.get("answers", []),
             error=body.get("error"),

{thresh_sdk-0.2.0 → thresh_sdk-0.4.0}/tests/test_sdk.py

@@ -1,3 +1,4 @@
+import json
 import io
 import time
 
@@ -42,11 +43,21 @@ def test_upload_sends_spec_and_parses(tmp_path):
     assert seen == {"auth": "Bearer th_live_test", "idem": "abc", "has_spec": True}
 
 
-def test_upload_requires_nonempty_spec(tmp_path):
+def test_upload_without_spec_is_auto(tmp_path):
     pdf = tmp_path / "c.pdf"
     pdf.write_bytes(b"%PDF")
-    with pytest.raises(ValueError):
-        make_client(lambda r: httpx.Response(500)).upload(pdf)
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = request.read()
+        return httpx.Response(
+            202, json={"id": "d1", "object": "document", "filename": "c.pdf",
+                       "status": "queued", "created_at": "2026-07-17T00:00:00"}
+        )
+
+    doc = make_client(handler).upload(pdf)
+    assert doc.id == "d1"
+    assert b'name="spec"' not in seen["body"]
 
 
 def test_upload_accepts_file_object():
@@ -127,3 +138,69 @@ def test_webhook_signature_roundtrip():
     assert not verify_webhook_signature("whsec_s", header, b'{"a":2}')
     assert not verify_webhook_signature("whsec_other", header, body)
     assert not verify_webhook_signature("whsec_s", "junk", body)
+
+
+def test_upload_auto_and_template_modes():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["content_type"] = request.headers.get("content-type", "")
+        seen["body"] = request.read()
+        return httpx.Response(
+            202, json={"id": "d1", "object": "document", "filename": "f", "status": "queued",
+                       "created_at": "2026-07-17T00:00:00"}
+        )
+
+    client = Thresh(api_key="th_live_x", transport=httpx.MockTransport(handler))
+    client.upload(io.BytesIO(b"%PDF"))  # auto: no spec, no template form fields
+    assert b'name="spec"' not in seen["body"] and b'name="template"' not in seen["body"]
+
+    client.upload(io.BytesIO(b"%PDF"), template="contract")
+    assert b'name="template"' in seen["body"] and b"contract" in seen["body"]
+    assert b'name="spec"' not in seen["body"]
+
+    with pytest.raises(ValueError):
+        client.upload(io.BytesIO(b"%PDF"), fields=["x"], template="contract")
+
+
+def test_template_crud_helpers():
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, request.url.path))
+        if request.method == "POST":
+            body = json.loads(request.read())
+            assert body["name"] == "contract" and body["spec"]["fields"] == ["price"]
+            return httpx.Response(201, json={"id": "t1", "name": "contract", "spec": body["spec"]})
+        if request.method == "GET":
+            return httpx.Response(200, json={"data": [{"id": "t1", "name": "contract"}]})
+        return httpx.Response(204)
+
+    client = Thresh(api_key="th_live_x", transport=httpx.MockTransport(handler))
+    created = client.create_template("contract", fields=["price"])
+    assert created["id"] == "t1"
+    assert client.templates()[0]["name"] == "contract"
+    client.delete_template("t1")
+    assert calls == [
+        ("POST", "/v1/templates"),
+        ("GET", "/v1/templates"),
+        ("DELETE", "/v1/templates/t1"),
+    ]
+
+
+def test_result_carries_field_meta():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={
+            "id": "d1", "object": "document", "filename": "f", "status": "completed",
+            "created_at": "2026-07-19T00:00:00",
+            "result": {
+                "fields": {"price": "100"},
+                "field_meta": {"price": {"page": 3, "confidence": "low"}},
+                "tables": {}, "answers": [],
+            },
+        })
+
+    client = Thresh(api_key="th_live_x", transport=httpx.MockTransport(handler))
+    result = client.result("d1")
+    assert result.fields["price"] == "100"
+    assert result.field_meta["price"] == {"page": 3, "confidence": "low"}

{thresh_sdk-0.2.0 → thresh_sdk-0.4.0}/uv.lock

@@ -237,7 +237,7 @@ wheels = [
 
 [[package]]
 name = "thresh-sdk"
-version = "0.1.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },