parserail 0.6.0__py3-none-any.whl

parserail/__init__.py

@@ -0,0 +1,663 @@
+"""Official Python SDK for ParseRail — the AI back-end for your product.
+
+    from parserail import ParseRail, ParseRailError
+
+    client = ParseRail(api_key="ksk_live_...")
+    doc = client.parse(file_url="https://.../invoice.pdf")
+    print(doc["totalAmount"], doc["usage"]["balanceRemaining"])
+
+Zero dependencies (stdlib only). Every method returns the endpoint result as a
+dict including a ``usage`` envelope; failures raise a typed ``ParseRailError`` and
+never burn credits. Get a key + 500 free credits every month at
+https://api.thecompound.tech.
+"""
+
+# Generated from the ParseRail endpoint catalog.
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from time import monotonic, sleep
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+__all__ = ["ParseRail", "ParseRailError", "__version__"]
+__version__ = "0.6.0"
+
+_DEFAULT_BASE_URL = "https://api.thecompound.tech"
+
+
+class ParseRailError(Exception):
+    """Raised for any non-2xx API response. Mirrors ``{"error": {"code", "message"}}``."""
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return f"ParseRailError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+def _document(file_url: Optional[str], text: Optional[str], file: Optional[Dict[str, str]]) -> Dict[str, Any]:
+    if file_url:
+        return {"fileUrl": file_url}
+    if file:
+        return {"file": file}
+    if text:
+        return {"text": text}
+    raise ValueError("Provide one of: file_url, text, or file={'data','mimeType'}.")
+
+
+class ParseRail:
+    """Synchronous client for the ParseRail API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "ParseRail: `api_key` is required. Mint one at https://parserail.thecompound.tech/dashboard."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # -- transport ---------------------------------------------------------
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Authorization": f"Bearer {self.api_key}", "User-Agent": f"parserail-python/{__version__}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = resp.read().decode("utf-8")
+                return json.loads(payload) if payload else {}
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8", errors="replace")
+            code, message = "unknown", f"Request failed with status {exc.code}."
+            try:
+                err = json.loads(raw).get("error") or {}
+                code = err.get("code", code)
+                message = err.get("message", message)
+            except (ValueError, AttributeError):
+                pass
+            raise ParseRailError(code, message, exc.code) from None
+        except urllib.error.URLError as exc:
+            raise ParseRailError("unknown", str(exc.reason), 0) from None
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        # Drop None values so optional params are omitted.
+        clean = {k: v for k, v in body.items() if v is not None}
+        return self._request("POST", path, clean)
+
+    # -- capabilities ------------------------------------------------------
+    def parse(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        doc_type: Optional[str] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Any invoice, receipt, EOB, ERA, or COI — PDF or image — into structured, validated JSON.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if doc_type is not None:
+            body["docType"] = doc_type
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/parse", body)
+
+    def extract(
+        self,
+        *,
+        text: str,
+        fields: List[str],
+        instructions: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Pull a field set you define out of any block of text. You name the fields; you get typed values with confidence."""
+        body: Dict[str, Any] = {"text": text, "fields": fields, "instructions": instructions}
+        return self._post("/v1/extract", body)
+
+    def classify(
+        self,
+        *,
+        text: str,
+        labels: List[str],
+        multi: Optional[bool] = None,
+        instructions: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Route or tag text against your own taxonomy — a label, a confidence, and a one-line rationale."""
+        body: Dict[str, Any] = {"text": text, "labels": labels, "multi": multi, "instructions": instructions}
+        return self._post("/v1/classify", body)
+
+    def summarize(
+        self,
+        *,
+        text: str,
+        length: Optional[str] = None,
+        action_items: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """A meeting transcript, thread, or report → a tight summary, key points, and extracted action items."""
+        body: Dict[str, Any] = {"text": text, "length": length, "actionItems": action_items}
+        return self._post("/v1/summarize", body)
+
+    def redact(
+        self,
+        *,
+        text: str,
+        types: Optional[List[str]] = None,
+        placeholder: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Detect and strip names, emails, phones, SSNs, cards, and PHI from text before you store or log it."""
+        body: Dict[str, Any] = {"text": text, "types": types, "placeholder": placeholder}
+        return self._post("/v1/redact", body)
+
+    def sentiment(
+        self,
+        *,
+        text: str,
+        aspects: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Turn a review or support message into a sentiment score, per-aspect breakdown, and the themes driving it."""
+        body: Dict[str, Any] = {"text": text, "aspects": aspects}
+        return self._post("/v1/sentiment", body)
+
+    def contract(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A contract → parties, effective date, term, renewal, governing law, obligations, and flagged risk clauses.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/contract", body)
+
+    def chargeback(
+        self,
+        *,
+        reason: str,
+        transaction: Dict[str, Any],
+        evidence: Optional[List[str]] = None,
+        context: Optional[str] = None,
+        network: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Dispute details → a representment narrative, an evidence checklist, the right reason code, and a win-likelihood."""
+        body: Dict[str, Any] = {"reason": reason, "transaction": transaction, "evidence": evidence, "context": context, "network": network}
+        return self._post("/v1/chargeback", body)
+
+    def enrich(
+        self,
+        *,
+        domain: Optional[str] = None,
+        email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A domain or work email → a structured company profile: name, description, industry, HQ, size, and links."""
+        body: Dict[str, Any] = {"domain": domain, "email": email}
+        return self._post("/v1/enrich", body)
+
+    def invoice(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """An invoice — PDF, photo, or text — into vendor, dates, PO refs, tax, totals, and clean line items.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/invoice", body)
+
+    def receipt(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A receipt into merchant, items, totals, payment method, and an expense category — built for expense flows.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/receipt", body)
+
+    def statement(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A bank or card statement into the account, the period, balances, and every transaction as a normalized row.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/statement", body)
+
+    def resume(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A resume or CV into a structured candidate profile: contact, skills, experience, education, and links.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/resume", body)
+
+    def tables(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Every table in a document — even scanned — as clean headers and rows, ready for your spreadsheet or DB.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/tables", body)
+
+    def split(
+        self,
+        *,
+        file_url: Optional[str] = None,
+        text: Optional[str] = None,
+        file: Optional[Dict[str, str]] = None,
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A multi-document scan bundle classified and split: what each document is, where it starts and ends, and a summary.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = _document(file_url, text, file)
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/split", body)
+
+    def compare(
+        self,
+        *,
+        a: Dict[str, Any],
+        b: Dict[str, Any],
+        async_: bool = False,
+        callback_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Two versions of a contract or document → every material change, what it means, and the risk it carries.
+
+        Pass ``async_=True`` to queue the work and get ``{"jobId", "status"}``
+        back instead of the result; poll it with ``get_job`` / ``wait_for_job``."""
+        body: Dict[str, Any] = {"a": a, "b": b}
+        if async_:
+            body["async"] = True
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        return self._post("/v1/compare", body)
+
+    def structure(
+        self,
+        *,
+        input: str,
+        schema: Dict[str, Any],
+        instructions: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Any messy input — text, HTML, an email — plus YOUR JSON schema → output shaped to it, validated against your required fields and property types, with an automatic corrective retry and a `valid` flag."""
+        body: Dict[str, Any] = {"input": input, "schema": schema, "instructions": instructions}
+        return self._post("/v1/structure", body)
+
+    def normalize(
+        self,
+        *,
+        records: List[Dict[str, Any]],
+        fields: Optional[List[str]] = None,
+        instructions: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A batch of messy records → clean canonical rows, with a change log of every fix (casing, formats, dedup-ready values)."""
+        body: Dict[str, Any] = {"records": records, "fields": fields, "instructions": instructions}
+        return self._post("/v1/normalize", body)
+
+    def match(
+        self,
+        *,
+        a: List[Dict[str, Any]],
+        b: List[Dict[str, Any]],
+        keys: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Two record sets → which rows are the same real-world thing, with confidence and reasoning. Fuzzy names, typos, aliases handled."""
+        body: Dict[str, Any] = {"a": a, "b": b, "keys": keys}
+        return self._post("/v1/match", body)
+
+    def categorize(
+        self,
+        *,
+        items: List[str],
+        taxonomy: List[str],
+        multi: Optional[bool] = None,
+        instructions: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Up to a hundred items against your taxonomy in one call — products, transactions, tickets — each with a confidence."""
+        body: Dict[str, Any] = {"items": items, "taxonomy": taxonomy, "multi": multi, "instructions": instructions}
+        return self._post("/v1/categorize", body)
+
+    def dunning(
+        self,
+        *,
+        invoice: Dict[str, Any],
+        customer: Dict[str, Any],
+        tone: Optional[str] = None,
+        channel: Optional[str] = None,
+        steps: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """An overdue invoice → a ready-to-send collection sequence, escalating at the right pace and tone for how late it is."""
+        body: Dict[str, Any] = {"invoice": invoice, "customer": customer, "tone": tone, "channel": channel, "steps": steps}
+        return self._post("/v1/dunning", body)
+
+    def po_match(
+        self,
+        *,
+        invoice: str,
+        purchase_order: str,
+        receipt: Optional[str] = None,
+        tolerance_pct: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Invoice vs purchase order vs receipt → matched, partial, or mismatched, with every discrepancy flagged and sized."""
+        body: Dict[str, Any] = {"invoice": invoice, "purchaseOrder": purchase_order, "receipt": receipt, "tolerancePct": tolerance_pct}
+        return self._post("/v1/po-match", body)
+
+    def quote(
+        self,
+        *,
+        job: str,
+        rates: Optional[str] = None,
+        past_quotes: Optional[str] = None,
+        currency: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A job description plus your rates → an itemized, professional quote with assumptions and scope notes spelled out."""
+        body: Dict[str, Any] = {"job": job, "rates": rates, "pastQuotes": past_quotes, "currency": currency}
+        return self._post("/v1/quote", body)
+
+    def fraud_flag(
+        self,
+        *,
+        order: Dict[str, Any],
+        context: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """An order or transaction in context → a risk score, the signals driving it, and the checks worth running before you ship."""
+        body: Dict[str, Any] = {"order": order, "context": context}
+        return self._post("/v1/fraud-flag", body)
+
+    def reply(
+        self,
+        *,
+        thread: str,
+        context: Optional[str] = None,
+        tone: Optional[str] = None,
+        goal: Optional[str] = None,
+        sender_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A customer thread plus your context → a ready-to-send reply in the right tone, with an internal note for the agent."""
+        body: Dict[str, Any] = {"thread": thread, "context": context, "tone": tone, "goal": goal, "senderName": sender_name}
+        return self._post("/v1/reply", body)
+
+    def triage(
+        self,
+        *,
+        ticket: str,
+        categories: Optional[List[str]] = None,
+        teams: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """A support ticket → priority, category, the team it belongs to, sentiment, SLA risk, and a suggested first response."""
+        body: Dict[str, Any] = {"ticket": ticket, "categories": categories, "teams": teams}
+        return self._post("/v1/triage", body)
+
+    def minutes(
+        self,
+        *,
+        transcript: str,
+        attendees: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """A meeting transcript → clean minutes: summary, decisions made, action items with owners, and open questions."""
+        body: Dict[str, Any] = {"transcript": transcript, "attendees": attendees}
+        return self._post("/v1/minutes", body)
+
+    def outreach(
+        self,
+        *,
+        lead: str,
+        product: str,
+        sender: Optional[Dict[str, Any]] = None,
+        channel: Optional[str] = None,
+        steps: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """An enriched lead plus what you sell → a personalized outreach sequence that references what actually makes them a fit."""
+        body: Dict[str, Any] = {"lead": lead, "product": product, "sender": sender, "channel": channel, "steps": steps}
+        return self._post("/v1/outreach", body)
+
+    def review_reply(
+        self,
+        *,
+        review: str,
+        rating: Optional[float] = None,
+        business: Optional[Dict[str, Any]] = None,
+        resolution: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A customer review → a brand-safe public response, the issues to log, and whether it needs human escalation."""
+        body: Dict[str, Any] = {"review": review, "rating": rating, "business": business, "resolution": resolution}
+        return self._post("/v1/review-reply", body)
+
+    def moderate(
+        self,
+        *,
+        text: Optional[str] = None,
+        image: Optional[Dict[str, Any]] = None,
+        image_url: Optional[str] = None,
+        policy: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Text or an image against YOUR policy → allow, review, or block, with the categories and excerpts that drove the call."""
+        body: Dict[str, Any] = {"text": text, "image": image, "imageUrl": image_url, "policy": policy}
+        return self._post("/v1/moderate", body)
+
+    def rewrite(
+        self,
+        *,
+        text: str,
+        voice: Optional[str] = None,
+        goal: Optional[str] = None,
+        audience: Optional[str] = None,
+        length: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Any copy → your brand voice. Describe the voice or paste a sample; get the rewrite and what changed."""
+        body: Dict[str, Any] = {"text": text, "voice": voice, "goal": goal, "audience": audience, "length": length}
+        return self._post("/v1/rewrite", body)
+
+    def product_copy(
+        self,
+        *,
+        product: Dict[str, Any],
+        channel: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Specs and an audience → listing-ready titles, bullets, a description, and SEO keywords — per channel."""
+        body: Dict[str, Any] = {"product": product, "channel": channel}
+        return self._post("/v1/product-copy", body)
+
+    def describe(
+        self,
+        *,
+        image: Optional[Dict[str, Any]] = None,
+        image_url: Optional[str] = None,
+        purpose: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """An image → accessible alt text, a caption, tags, and any text found inside it. Accessibility and catalogs in one call."""
+        body: Dict[str, Any] = {"image": image, "imageUrl": image_url, "purpose": purpose}
+        return self._post("/v1/describe", body)
+
+    def research(
+        self,
+        *,
+        query: str,
+        focus: Optional[str] = None,
+        depth: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A company or topic → a multi-source, citation-backed brief: what it is, what changed lately, and what matters. Real web work."""
+        body: Dict[str, Any] = {"query": query, "focus": focus, "depth": depth}
+        return self._post("/v1/research", body)
+
+    def screen(
+        self,
+        *,
+        lead: str,
+        criteria: str,
+    ) -> Dict[str, Any]:
+        """A lead plus your ICP criteria → a web-grounded qualification verdict with the evidence for and against."""
+        body: Dict[str, Any] = {"lead": lead, "criteria": criteria}
+        return self._post("/v1/screen", body)
+
+    def transcribe(
+        self,
+        *,
+        audio: Optional[Dict[str, Any]] = None,
+        audio_url: Optional[str] = None,
+        diarize: Optional[bool] = None,
+        language: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """An audio recording → accurate text with speakers and paragraph timestamps. Meetings, calls, voice notes."""
+        body: Dict[str, Any] = {"audio": audio, "audioUrl": audio_url, "diarize": diarize, "language": language}
+        return self._post("/v1/transcribe", body)
+
+    def memory(
+        self,
+        *,
+        op: str,
+        namespace: Optional[str] = None,
+        content: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+        id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Store, search, and forget memories for your agents — semantic recall on your own namespace, no vector DB to run."""
+        body: Dict[str, Any] = {"op": op, "namespace": namespace, "content": content, "metadata": metadata, "query": query, "limit": limit, "id": id}
+        return self._post("/v1/memory", body)
+
+    def image(
+        self,
+        *,
+        prompt: str,
+        style: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """A prompt → a production-ready image. Marketing visuals, product scenes, and consistent brand imagery."""
+        body: Dict[str, Any] = {"prompt": prompt, "style": style, "aspectRatio": aspect_ratio}
+        return self._post("/v1/image", body)
+
+    def speak(
+        self,
+        *,
+        text: str,
+        voice: Optional[str] = None,
+        pace: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Text → natural speech audio, ready to embed. Voice notes, IVR lines, narration."""
+        body: Dict[str, Any] = {"text": text, "voice": voice, "pace": pace}
+        return self._post("/v1/speak", body)
+
+    def account(self) -> Dict[str, Any]:
+        """Fetch the authenticated account's credit balance."""
+        return self._request("GET", "/v1/account")
+
+    # -- async jobs --------------------------------------------------------
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Read a job created with ``async_=True``. Never charges credits."""
+        return self._request("GET", f"/v1/jobs/{quote(job_id, safe='')}")
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        interval: float = 2.0,
+        timeout: float = 300.0,
+    ) -> Dict[str, Any]:
+        """Poll a job until it finishes, and return it.
+
+        Returns on ``"failed"`` as well as ``"succeeded"`` — check
+        ``job["status"]``. A failed job was never charged. Raises
+        ``TimeoutError`` only if the wait elapses; the job keeps running
+        server-side and can be polled again.
+        """
+        deadline = monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.get("status") in ("succeeded", "failed"):
+                return job
+            if monotonic() + interval >= deadline:
+                raise TimeoutError(
+                    f"Job {job_id} did not finish within {timeout}s. "
+                    "It is still running — poll get_job() to collect it."
+                )
+            sleep(interval)

parserail-0.6.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: parserail
+Version: 0.6.0
+Summary: Official Python SDK for ParseRail: parse documents, extract fields, redact PII, analyze contracts.
+Project-URL: Homepage, https://parserail.thecompound.tech
+Project-URL: Documentation, https://parserail.thecompound.tech/docs/sdk-python
+Author: Compound Labs
+License: MIT
+Keywords: ai,api,chargeback,contract,document-parsing,llm,ocr,parserail,pii
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# parserail
+
+Official Python SDK for **[ParseRail](https://parserail.thecompound.tech)** — the AI back-end for your product. Parse documents, extract fields, redact PII, analyze contracts, fight chargebacks, and enrich companies.
+
+```bash
+pip install parserail
+```
+
+## Quickstart
+
+```python
+from parserail import ParseRail
+
+client = ParseRail(api_key="ksk_live_...")
+
+doc = client.parse(file_url="https://.../invoice.pdf")
+print(doc["totalAmount"])              # 4820.5
+print(doc["usage"]["balanceRemaining"])  # 490
+```
+
+Get a key (and 500 free credits) at **[parserail.thecompound.tech](https://parserail.thecompound.tech)**. Zero dependencies — stdlib only, Python 3.8+.
+
+## Methods
+
+Every method returns the endpoint result as a dict, including a `usage` envelope. A non-2xx response raises a typed `ParseRailError` (and never burns credits).
+
+```python
+client.parse(file_url=...)                                  # documents → JSON
+client.extract(text=..., fields=["order", "total"])         # pull named fields
+client.classify(text=..., labels=["billing", "tech"])       # label text
+client.summarize(text=..., length="standard")               # summary + actions
+client.redact(text=...)                                      # strip PII/PHI
+client.sentiment(text=..., aspects=["product"])             # sentiment + aspects
+client.contract(file_url=...)                               # contract → terms + risks
+client.chargeback(reason=..., transaction={"amount": 129})  # representment packet
+client.enrich(email="sam@stripe.com")                       # company profile
+client.account()                                            # balance
+```
+
+## Async & webhooks
+
+A hundred-page contract doesn't fit in a request/response cycle. The document endpoints — `parse`, `invoice`, `receipt`, `statement`, `resume`, `tables`, `split`, `compare`, `contract` — take `async_=True` and hand you a job instead of a result. (`async` is a Python keyword, hence the trailing underscore; the wire field is `async`.)
+
+```python
+job = client.parse(file_url="https://.../contract.pdf", async_=True)
+done = client.wait_for_job(job["jobId"])
+
+if done["status"] == "succeeded":
+    print(done["result"]["totalAmount"])
+else:
+    print(done["error"])          # failed jobs are never charged
+```
+
+Use `client.get_job(job_id)` for a single poll if you'd rather drive the loop yourself.
+
+Every job reaches a terminal state. If the instance running yours dies mid-flight, it is marked `failed` with an explanation rather than left `running` forever — and you aren't billed for it. Nothing is silently retried; resubmit and you stay in control of the spend.
+
+### Webhooks
+
+Pass a `callback_url` (public https) and the finished job is POSTed to it, signed with your account's webhook secret from the [API keys page](https://parserail.thecompound.tech/dashboard/keys):
+
+```python
+client.parse(file_url=..., async_=True, callback_url="https://you.example/hooks/parserail")
+```
+
+```python
+import hmac, hashlib
+
+# X-ParseRail-Signature: sha256=<hex HMAC-SHA256 of the RAW body>
+def verify(raw_body: bytes, header: str, secret: str) -> bool:
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(header.removeprefix("sha256="), expected)
+```
+
+Delivery is best-effort and never retried — **polling is the source of truth**.
+
+## Error handling
+
+```python
+from parserail import ParseRail, ParseRailError
+
+client = ParseRail(api_key="ksk_live_...")
+try:
+    client.parse(file_url="https://.../invoice.pdf")
+except ParseRailError as err:
+    # err.code: "insufficient_credits" | "rate_limited" | "unauthorized" | ...
+    print(err.code, err.status, err.message)
+```
+
+MIT © ParseRail Studios

parserail-0.6.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+parserail/__init__.py,sha256=R4LDq0JQdHINyQiBLSOzKgtsHS3BCtJTr6Q4g6rg7TU,26573
+parserail-0.6.0.dist-info/METADATA,sha256=kirtqjXgOQLd-iOaLcJdo7DaQh4bhOjQbc4tDD9XmC8,4467
+parserail-0.6.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+parserail-0.6.0.dist-info/RECORD,,

parserail-0.6.0.dist-info/WHEEL

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