pageindex-extract 0.1.0__tar.gz

pageindex_extract-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+.venv-*/
+uv.lock

pageindex_extract-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vectify AI
+
+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.

pageindex_extract-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: pageindex-extract
+Version: 0.1.0
+Summary: Python client for Page Extract API by PageIndex: turn a PDF into JSON that fits your schema.
+Project-URL: Homepage, https://extract.pageindex.ai
+Project-URL: Documentation, https://extract.pageindex.ai/docs
+Project-URL: Repository, https://github.com/VectifyAI/pageindex-extract-python
+Project-URL: Issues, https://github.com/VectifyAI/pageindex-extract-python/issues
+Author-email: PageIndex <support@pageindex.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: extract,extraction,json-schema,llm,pageindex,pdf,structured-output
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pageindex-search>=0.14
+Description-Content-Type: text/markdown
+
+# Page Extract Python SDK
+
+Python client for [Page Extract](https://extract.pageindex.ai) by PageIndex: turn a PDF into JSON that fits your schema.
+
+```bash
+pip install pageindex-extract
+```
+
+Create an API key in the [console](https://search.pageindex.ai/console/keys). Page Extract and Page Search share one key, one credit balance and one set of documents.
+
+```bash
+export PAGEINDEX_SEARCH_API_KEY=pis_live_...
+```
+
+## Extract
+
+```python
+from pageindex_extract import PageExtract
+
+client = PageExtract()
+
+schema = {
+    "type": "object",
+    "properties": {
+        "invoice_number": {"type": "string"},
+        "total": {"type": "number", "description": "Amount due, in dollars, without the currency sign"},
+        "lines": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {"item": {"type": "string"}, "amount": {"type": "number"}},
+            },
+        },
+    },
+}
+
+job = client.extract("invoice.pdf", schema)
+print(job.result)
+```
+
+`extract` uploads the file (a file uploaded before is not uploaded again), waits for the extraction and returns it. `job.result` is JSON that fits your schema; a field the document does not give is `null`.
+
+The schema can also be a Pydantic model:
+
+```python
+from pydantic import BaseModel
+
+class Line(BaseModel):
+    item: str
+    amount: float
+
+class Invoice(BaseModel):
+    invoice_number: str
+    total: float
+    lines: list[Line]
+
+job = client.extract("invoice.pdf", Invoice)
+invoice = job.parse(Invoice)
+```
+
+### Options
+
+```python
+job = client.extract(
+    "report.pdf",
+    schema,
+    tier="pro",            # "standard" ($0.03 a page) or "pro" ($0.05 a page)
+    pages="3-9",           # only these pages, and only they are charged; also (3, 9) or 3
+    cite_sources=True,     # the page each list item is on: job.sources
+    system_prompt="Amounts are in thousands of dollars.",
+)
+print(job.usage.pages, job.usage.credits)
+```
+
+`document` can be a path, bytes, an open binary file, an uploaded document, or a document id (`"doc_..."`).
+
+You pay only for extractions that complete. A failed extraction raises `PageExtractError` (its `job` holds the job) and costs nothing.
+
+## Jobs
+
+Extractions run in the background. To start one and come back for it later:
+
+```python
+job = client.extract("report.pdf", schema, wait=False)   # PENDING
+job = client.jobs.wait(job)                              # COMPLETED, or raises
+
+client.jobs.get(job.id)          # the job, with its result once COMPLETED
+client.jobs.cancel(job.id)       # stop it; nothing is charged
+client.jobs.delete(job.id)       # delete it and its result
+
+for job in client.jobs.list():   # every extraction, newest first
+    print(job.id, job.status)
+```
+
+## Documents
+
+`client.documents` is the Page Search client's, with the same key:
+
+```python
+doc = client.documents.upload("report.pdf")
+job = client.extract(doc, schema)
+```
+
+## Errors
+
+Errors raise `PageExtractError` with `status`, `code`, `message` and `request_id`.
+
+| Code | When |
+| --- | --- |
+| `unauthorized` | The API key is missing or not valid. |
+| `insufficient_credit` | Your credit does not cover the pages. Add credit in the console. |
+| `invalid_schema` | The schema is not valid JSON Schema, or its top is not an object. |
+| `schema_too_large` | The schema is larger than 1 MB. |
+| `invalid_target_pages` | `pages` is not within the document. |
+| `document_not_found` | No such document. |
+| `job_not_found` | No such job. |
+| `job_failed` / `job_cancelled` | The extraction failed or was cancelled. Nothing is charged. |
+| `timeout` | `wait` gave up; the job goes on running. |
+
+## Links
+
+- [Page Extract](https://extract.pageindex.ai)
+- [API docs](https://extract.pageindex.ai/docs)
+- [Page Search Python SDK](https://github.com/VectifyAI/pageindex-search-python)
+
+## License
+
+MIT

pageindex_extract-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Page Extract Python SDK
+
+Python client for [Page Extract](https://extract.pageindex.ai) by PageIndex: turn a PDF into JSON that fits your schema.
+
+```bash
+pip install pageindex-extract
+```
+
+Create an API key in the [console](https://search.pageindex.ai/console/keys). Page Extract and Page Search share one key, one credit balance and one set of documents.
+
+```bash
+export PAGEINDEX_SEARCH_API_KEY=pis_live_...
+```
+
+## Extract
+
+```python
+from pageindex_extract import PageExtract
+
+client = PageExtract()
+
+schema = {
+    "type": "object",
+    "properties": {
+        "invoice_number": {"type": "string"},
+        "total": {"type": "number", "description": "Amount due, in dollars, without the currency sign"},
+        "lines": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {"item": {"type": "string"}, "amount": {"type": "number"}},
+            },
+        },
+    },
+}
+
+job = client.extract("invoice.pdf", schema)
+print(job.result)
+```
+
+`extract` uploads the file (a file uploaded before is not uploaded again), waits for the extraction and returns it. `job.result` is JSON that fits your schema; a field the document does not give is `null`.
+
+The schema can also be a Pydantic model:
+
+```python
+from pydantic import BaseModel
+
+class Line(BaseModel):
+    item: str
+    amount: float
+
+class Invoice(BaseModel):
+    invoice_number: str
+    total: float
+    lines: list[Line]
+
+job = client.extract("invoice.pdf", Invoice)
+invoice = job.parse(Invoice)
+```
+
+### Options
+
+```python
+job = client.extract(
+    "report.pdf",
+    schema,
+    tier="pro",            # "standard" ($0.03 a page) or "pro" ($0.05 a page)
+    pages="3-9",           # only these pages, and only they are charged; also (3, 9) or 3
+    cite_sources=True,     # the page each list item is on: job.sources
+    system_prompt="Amounts are in thousands of dollars.",
+)
+print(job.usage.pages, job.usage.credits)
+```
+
+`document` can be a path, bytes, an open binary file, an uploaded document, or a document id (`"doc_..."`).
+
+You pay only for extractions that complete. A failed extraction raises `PageExtractError` (its `job` holds the job) and costs nothing.
+
+## Jobs
+
+Extractions run in the background. To start one and come back for it later:
+
+```python
+job = client.extract("report.pdf", schema, wait=False)   # PENDING
+job = client.jobs.wait(job)                              # COMPLETED, or raises
+
+client.jobs.get(job.id)          # the job, with its result once COMPLETED
+client.jobs.cancel(job.id)       # stop it; nothing is charged
+client.jobs.delete(job.id)       # delete it and its result
+
+for job in client.jobs.list():   # every extraction, newest first
+    print(job.id, job.status)
+```
+
+## Documents
+
+`client.documents` is the Page Search client's, with the same key:
+
+```python
+doc = client.documents.upload("report.pdf")
+job = client.extract(doc, schema)
+```
+
+## Errors
+
+Errors raise `PageExtractError` with `status`, `code`, `message` and `request_id`.
+
+| Code | When |
+| --- | --- |
+| `unauthorized` | The API key is missing or not valid. |
+| `insufficient_credit` | Your credit does not cover the pages. Add credit in the console. |
+| `invalid_schema` | The schema is not valid JSON Schema, or its top is not an object. |
+| `schema_too_large` | The schema is larger than 1 MB. |
+| `invalid_target_pages` | `pages` is not within the document. |
+| `document_not_found` | No such document. |
+| `job_not_found` | No such job. |
+| `job_failed` / `job_cancelled` | The extraction failed or was cancelled. Nothing is charged. |
+| `timeout` | `wait` gave up; the job goes on running. |
+
+## Links
+
+- [Page Extract](https://extract.pageindex.ai)
+- [API docs](https://extract.pageindex.ai/docs)
+- [Page Search Python SDK](https://github.com/VectifyAI/pageindex-search-python)
+
+## License
+
+MIT

pageindex_extract-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pageindex-extract"
+dynamic = ["version"]
+description = "Python client for Page Extract API by PageIndex: turn a PDF into JSON that fits your schema."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "PageIndex", email = "support@pageindex.ai" }]
+dependencies = ["httpx>=0.24", "pageindex-search>=0.14"]
+keywords = ["pageindex", "extract", "extraction", "pdf", "json-schema", "llm", "structured-output"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://extract.pageindex.ai"
+Documentation = "https://extract.pageindex.ai/docs"
+Repository = "https://github.com/VectifyAI/pageindex-extract-python"
+Issues = "https://github.com/VectifyAI/pageindex-extract-python/issues"
+
+[tool.hatch.version]
+path = "src/pageindex_extract/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pageindex_extract"]

pageindex_extract-0.1.0/src/pageindex_extract/__init__.py

@@ -0,0 +1,9 @@
+"""Page Extract API by PageIndex: turn a PDF into JSON that fits your schema."""
+
+from pageindex_search import Document
+
+from ._client import ExtractJob, JobPage, Jobs, PageExtract, PageExtractError, Usage, schema_of
+from ._version import __version__
+
+__all__ = ["PageExtract", "PageExtractError", "ExtractJob", "JobPage", "Jobs", "Usage", "Document", "schema_of",
+           "__version__"]

pageindex_extract-0.1.0/src/pageindex_extract/_client.py

@@ -0,0 +1,304 @@
+"""The Page Extract API client: turn a PDF into JSON that fits your schema."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any, BinaryIO, Iterator, Union
+
+import httpx
+from pageindex_search import Document, PageSearch
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.extract.pageindex.ai/v1"
+API_KEY_ENV = "PAGEINDEX_SEARCH_API_KEY"  # one key for Page Search and Page Extract
+# Retried, after a short wait that doubles: the server was busy or briefly unreachable.
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+# Starting an extraction is retried only when the request surely did not start one: it was turned away before it
+# reached the service, so a retry cannot run (or charge) the same extraction twice.
+CREATE_RETRY_STATUSES = {429, 502, 503}
+FINISHED = ("COMPLETED", "FAILED", "CANCELLED")
+
+FileInput = Union[str, os.PathLike, bytes, BinaryIO]
+DocumentInput = Union[FileInput, Document]
+
+
+class PageExtractError(Exception):
+    """An error the API returned, or an extraction that failed or was cancelled (then job holds it)."""
+
+    def __init__(self, message: str, *, status: int | None = None, code: str | None = None,
+                 request_id: str | None = None, job: "ExtractJob | None" = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.job = job
+
+    def __str__(self) -> str:
+        parts = [f"{self.code}: {self.message}" if self.code else self.message]
+        if self.status:
+            parts.append(f"(HTTP {self.status})")
+        if self.request_id:
+            parts.append(f"[{self.request_id}]")
+        return " ".join(parts)
+
+
+def _make(cls, data: dict[str, Any]):
+    """A dataclass from a response, ignoring fields this version does not know."""
+    known = {f.name for f in fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class Usage:
+    pages: int  # pages extracted
+    credits: float  # US dollars charged
+
+
+@dataclass
+class ExtractJob:
+    id: str
+    status: str  # "PENDING", "RUNNING", "COMPLETED", "FAILED" or "CANCELLED"
+    document: str  # the document's id
+    configuration: dict[str, Any] = field(default_factory=dict)  # data_schema, tier, target_pages, ...
+    created_at: str | None = None
+    updated_at: str | None = None
+    result: Any = None  # the JSON that fits the schema, once COMPLETED
+    # With cite_sources: the page each list item is on, by its JSON Pointer ("/rows/0": {"page": 3})
+    sources: dict[str, dict[str, Any]] = field(default_factory=dict)
+    usage: Usage | None = None  # once COMPLETED: what was charged
+    error: str | None = None  # why it FAILED
+
+    @property
+    def done(self) -> bool:
+        return self.status in FINISHED
+
+    def parse(self, model: Any) -> Any:
+        """The result as an instance of a Pydantic model (model.model_validate(result))."""
+        if self.status != "COMPLETED":
+            raise PageExtractError(f"Extract job {self.id} is {self.status}, not COMPLETED.", job=self)
+        return model.model_validate(self.result)
+
+    @classmethod
+    def _from(cls, data: dict[str, Any]) -> "ExtractJob":
+        out = _make(cls, data)
+        out.result = data.get("extract_result")
+        out.sources = (data.get("extract_metadata") or {}).get("field_metadata") or {}
+        out.usage = _make(Usage, data["usage"]) if data.get("usage") else None
+        out.error = data.get("error_message")
+        return out
+
+
+class JobPage:
+    """One page of your extractions, newest first: data and next (the id to pass as after for the page after it).
+    Iterating it goes on through the pages after it, so a for loop over client.jobs.list() sees every extraction.
+    Listed jobs come without their results: get(id) for one's result."""
+
+    def __init__(self, jobs: "Jobs", data: list[ExtractJob], next: str | None, limit: int):
+        self._jobs, self.data, self.next, self._limit = jobs, data, next, limit
+
+    @property
+    def has_more(self) -> bool:
+        return self.next is not None
+
+    def next_page(self) -> JobPage | None:
+        return self._jobs.list(limit=self._limit, after=self.next) if self.next else None
+
+    def __iter__(self) -> Iterator[ExtractJob]:
+        page: JobPage | None = self
+        while page is not None:
+            yield from page.data
+            page = page.next_page()
+
+
+def schema_of(schema: Any) -> dict[str, Any]:
+    """A JSON Schema from a dict, or from a Pydantic model (its model_json_schema())."""
+    if isinstance(schema, dict):
+        return schema
+    if hasattr(schema, "model_json_schema"):
+        return schema.model_json_schema()
+    raise TypeError("schema is a JSON Schema (a dict) or a Pydantic model")
+
+
+def _pages(pages: str | int | tuple[int, int] | None) -> str | None:
+    """target_pages as the API takes it: "3", or "3-9"."""
+    if pages is None or isinstance(pages, str):
+        return pages
+    if isinstance(pages, int):
+        return str(pages)
+    first, last = pages
+    return f"{first}-{last}"
+
+
+class Jobs:
+    """Your extractions: client.jobs.create(document, schema), .get(id), .list(), .wait(job), .cancel(job),
+    .delete(job)."""
+
+    def __init__(self, client: "PageExtract"):
+        self._client = client
+
+    def create(self, document: Document | str, schema: Any, *, tier: str = "standard",
+               pages: str | int | tuple[int, int] | None = None, cite_sources: bool = False,
+               system_prompt: str | None = None) -> ExtractJob:
+        """Start extracting from an uploaded document (or its id); returns at once, PENDING. client.extract() also
+        uploads a file and waits for the result."""
+        configuration: dict[str, Any] = {"data_schema": schema_of(schema), "tier": tier}
+        if pages is not None:
+            configuration["target_pages"] = _pages(pages)
+        if cite_sources:
+            configuration["cite_sources"] = True
+        if system_prompt:
+            configuration["system_prompt"] = system_prompt
+        body = {"document": _id(document), "configuration": configuration}
+        return ExtractJob._from(self._client._request("POST", "/extract", json=body, retry=CREATE_RETRY_STATUSES))
+
+    def get(self, job: ExtractJob | str) -> ExtractJob:
+        return ExtractJob._from(self._client._request("GET", f"/extract/{_id(job)}"))
+
+    def list(self, *, limit: int = 20, after: str | None = None) -> JobPage:
+        """Your extractions, newest first: limit (1 to 100) of them, after the job whose id is after.
+
+            for job in client.jobs.list():    # every extraction, a page at a time
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if after:
+            params["after"] = after
+        page = self._client._request("GET", "/extract", params=params)
+        return JobPage(self, [ExtractJob._from(j) for j in page["jobs"]], page.get("next"), limit)
+
+    def wait(self, job: ExtractJob | str, *, timeout: float = 3600.0, interval: float = 3.0) -> ExtractJob:
+        """The job once COMPLETED. Raises PageExtractError if it failed, was cancelled, or is not done within
+        timeout (it goes on running then: wait again, or cancel it)."""
+        current = job if isinstance(job, ExtractJob) else self.get(job)
+        deadline = time.monotonic() + timeout
+        while not current.done:
+            if time.monotonic() > deadline:
+                raise PageExtractError(f"Extract job {current.id} is still {current.status} after {timeout:.0f} s.",
+                                       code="timeout", job=current)
+            time.sleep(interval)
+            current = self.get(current.id)
+        if current.status != "COMPLETED":
+            message = current.error or f"Extract job {current.id} was {current.status.lower()}."
+            raise PageExtractError(message, code=f"job_{current.status.lower()}", job=current)
+        return current
+
+    def cancel(self, job: ExtractJob | str) -> ExtractJob:
+        """Stop a job that is PENDING or RUNNING; nothing is charged."""
+        return ExtractJob._from(self._client._request("POST", f"/extract/{_id(job)}/cancel"))
+
+    def delete(self, job: ExtractJob | str) -> None:
+        """Delete a job and its result."""
+        self._client._request("DELETE", f"/extract/{_id(job)}")
+
+
+class PageExtract:
+    """A client for the Page Extract API.
+
+        client = PageExtract()  # reads PAGEINDEX_SEARCH_API_KEY: the same key as Page Search
+        job = client.extract("invoice.pdf", schema)  # a JSON Schema, or a Pydantic model
+        print(job.result)
+
+    Documents are Page Search's: client.documents is a Page Search client's, with the same key.
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, timeout: float = 120.0,
+                 max_retries: int = 2, http_client: httpx.Client | None = None, search: PageSearch | None = None):
+        api_key = api_key or os.environ.get(API_KEY_ENV)
+        if not api_key:
+            raise PageExtractError(f"No API key: pass api_key or set {API_KEY_ENV}. "
+                                   "Create one at https://search.pageindex.ai/console/keys.")
+        self.base_url = (base_url or os.environ.get("PAGEINDEX_EXTRACT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._headers = {"Authorization": f"Bearer {api_key}", "User-Agent": f"pageindex-extract-python/{__version__}"}
+        self.search = search or PageSearch(api_key, timeout=timeout, max_retries=max_retries)
+        self.documents = self.search.documents
+        self.jobs = Jobs(self)
+
+    def extract(self, document: DocumentInput, schema: Any, *, tier: str = "standard",
+                pages: str | int | tuple[int, int] | None = None, cite_sources: bool = False,
+                system_prompt: str | None = None, wait: bool = True, timeout: float = 3600.0) -> ExtractJob:
+        """Extract JSON that fits schema (a JSON Schema, or a Pydantic model) from a PDF.
+
+        document is a file (a path, bytes or an open binary file), uploaded first (a file uploaded before is not
+        uploaded again), or an uploaded document or its id ("doc_..."). tier is "standard" or "pro"; pages keeps
+        the extraction to some pages ("3-9", (3, 9) or 3), and only they are charged; cite_sources gives the page
+        each list item is on (job.sources); system_prompt adds your own instructions.
+
+        With wait (the default), returns the job once COMPLETED (job.result), or raises PageExtractError if it
+        failed; without it, returns the job at once, PENDING: client.jobs.wait(job) for its result.
+        """
+        doc = self._document(document)
+        for _ in range(60):  # a document just uploaded elsewhere may still be processing
+            try:
+                job = self.jobs.create(doc, schema, tier=tier, pages=pages, cite_sources=cite_sources,
+                                       system_prompt=system_prompt)
+                break
+            except PageExtractError as error:
+                if error.code != "document_not_ready":
+                    raise
+                doc = self.documents.wait(_id(doc))
+        else:
+            raise PageExtractError(f"Document {_id(doc)} is not ready.", code="document_not_ready")
+        return self.jobs.wait(job, timeout=timeout) if wait else job
+
+    def _document(self, document: DocumentInput) -> Document | str:
+        """An uploaded document, or an id: a file is uploaded (and waited for)."""
+        if isinstance(document, Document):
+            return document
+        if isinstance(document, str) and not os.path.exists(document) and not document.lower().endswith(".pdf"):
+            return document  # an id
+        if isinstance(document, (str, os.PathLike)) and not Path(document).exists():
+            raise FileNotFoundError(str(document))
+        return self.documents.upload(document)
+
+    # Plumbing
+
+    def _request(self, method: str, path: str, *, retry: set[int] = RETRY_STATUSES, **kwargs: Any) -> Any:
+        """The response's JSON. An error raises PageExtractError."""
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(method, self.base_url + path, headers=self._headers, **kwargs)
+            except httpx.TransportError as error:
+                # Starting a job is retried only when the request surely was not sent.
+                unsent = isinstance(error, (httpx.ConnectError, httpx.ConnectTimeout))
+                if attempt == self.max_retries or (method == "POST" and path == "/extract" and not unsent):
+                    raise PageExtractError(f"Could not reach the API: {error}") from error
+            else:
+                if response.status_code not in retry or attempt == self.max_retries:
+                    return _json(response)
+            time.sleep(0.5 * 2 ** attempt)
+        raise AssertionError("unreachable")
+
+    def close(self) -> None:
+        self._http.close()
+        self.search.close()
+
+    def __enter__(self) -> "PageExtract":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _id(item: Any) -> str:
+    return item if isinstance(item, str) else item.id
+
+
+def _json(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+    if response.is_success and isinstance(data, dict):
+        return data
+    request_id = response.headers.get("x-request-id")
+    error = data.get("error") if isinstance(data, dict) else None
+    error = error if isinstance(error, dict) else {}
+    raise PageExtractError(error.get("message") or response.text[:200] or response.reason_phrase,
+                           status=response.status_code, code=error.get("code"),
+                           request_id=error.get("request_id") or request_id)

pageindex_extract-0.1.0/src/pageindex_extract/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pageindex_extract-0.1.0/tests/test_client.py

@@ -0,0 +1,188 @@
+"""The client against a stand-in for the API. test_live.py runs it against the real one."""
+import json
+
+import httpx
+import pytest
+from pageindex_search import PageSearch
+
+from pageindex_extract import ExtractJob, PageExtract, PageExtractError
+
+SCHEMA = {"type": "object", "properties": {"total": {"type": "number"}}}
+
+
+def job(status="PENDING", **extra):
+    return {"id": "ext_1", "status": status, "document": "doc_1", "configuration": {"data_schema": SCHEMA},
+            "created_at": "2026-11-08T00:00:00+00:00", "updated_at": "2026-11-08T00:00:01+00:00", **extra}
+
+
+def client(handler, search_handler=None) -> PageExtract:
+    search = PageSearch(api_key="pis_live_x", max_retries=0,
+                        http_client=httpx.Client(transport=httpx.MockTransport(search_handler or handler)))
+    return PageExtract(api_key="pis_live_x", max_retries=2, search=search,
+                       http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+
+@pytest.fixture(autouse=True)
+def no_sleep(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+
+
+def test_extract_by_id_waits_for_the_result():
+    seen = []
+
+    def handler(request):
+        seen.append((request.method, request.url.path))
+        if request.method == "POST":
+            body = json.loads(request.content)
+            assert body == {"document": "doc_1", "configuration": {
+                "data_schema": SCHEMA, "tier": "pro", "target_pages": "3-9", "cite_sources": True}}
+            assert request.headers["authorization"] == "Bearer pis_live_x"
+            return httpx.Response(200, json=job())
+        if len(seen) < 4:
+            return httpx.Response(200, json=job("RUNNING"))
+        return httpx.Response(200, json=job("COMPLETED", extract_result={"total": 12.5},
+                                            extract_metadata={"field_metadata": {"/rows/0": {"page": 3}}},
+                                            usage={"pages": 7, "credits": 0.35}))
+
+    out = client(handler).extract("doc_1", SCHEMA, tier="pro", pages=(3, 9), cite_sources=True)
+    assert out.status == "COMPLETED" and out.result == {"total": 12.5}
+    assert out.sources == {"/rows/0": {"page": 3}} and out.usage.pages == 7 and out.usage.credits == 0.35
+    assert seen[0] == ("POST", "/v1/extract") and seen[-1] == ("GET", "/v1/extract/ext_1")
+
+
+def test_failed_job_raises_with_the_job():
+    def handler(request):
+        if request.method == "POST":
+            return httpx.Response(200, json=job())
+        return httpx.Response(200, json=job("FAILED", error_message="The document could not be finished."))
+
+    with pytest.raises(PageExtractError) as error:
+        client(handler).extract("doc_1", SCHEMA)
+    assert error.value.code == "job_failed" and error.value.job.status == "FAILED"
+    assert error.value.message == "The document could not be finished."
+
+
+def test_no_wait_returns_at_once():
+    out = client(lambda request: httpx.Response(200, json=job())).extract("doc_1", SCHEMA, wait=False)
+    assert out.status == "PENDING" and not out.done
+
+
+def test_api_error_raises():
+    body = {"error": {"code": "insufficient_credit", "message": "Extracting 9 pages takes $0.45 of credit."}}
+    with pytest.raises(PageExtractError) as error:
+        client(lambda request: httpx.Response(402, json=body)).jobs.create("doc_1", SCHEMA)
+    assert (error.value.status, error.value.code) == (402, "insufficient_credit")
+
+
+def test_create_is_not_retried_after_it_may_have_started():
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return httpx.Response(500, json={"error": {"code": "error", "message": "boom"}})
+
+    with pytest.raises(PageExtractError):
+        client(handler).jobs.create("doc_1", SCHEMA)
+    assert len(calls) == 1  # a 500 may have started the job: retrying could run it twice
+
+
+def test_create_is_retried_when_turned_away():
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return httpx.Response(503) if len(calls) == 1 else httpx.Response(200, json=job())
+
+    assert client(handler).jobs.create("doc_1", SCHEMA).id == "ext_1" and len(calls) == 2
+
+
+def test_get_is_retried():
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return httpx.Response(500) if len(calls) == 1 else httpx.Response(200, json=job("RUNNING"))
+
+    assert client(handler).jobs.get("ext_1").status == "RUNNING" and len(calls) == 2
+
+
+def test_file_is_uploaded_then_extracted(tmp_path):
+    pdf = tmp_path / "invoice.pdf"
+    pdf.write_bytes(b"%PDF-1.4")
+
+    def search(request):
+        assert request.method == "POST" and request.url.path == "/v1/documents"
+        return httpx.Response(200, json={"id": "doc_7", "status": "ready", "filename": "invoice.pdf", "pages": 2})
+
+    def extract(request):
+        assert json.loads(request.content)["document"] == "doc_7"
+        return httpx.Response(200, json=job())
+
+    assert client(extract, search).extract(str(pdf), SCHEMA, wait=False).id == "ext_1"
+
+
+def test_missing_file_raises(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        client(lambda request: httpx.Response(200, json=job())).extract(str(tmp_path / "nope.pdf"), SCHEMA)
+
+
+def test_document_not_ready_waits_then_retries():
+    calls = []
+
+    def extract(request):
+        calls.append(request.method)
+        if request.method == "POST" and calls.count("POST") == 1:
+            return httpx.Response(409, json={"error": {"code": "document_not_ready", "message": "processing"}})
+        return httpx.Response(200, json=job())
+
+    def search(request):
+        return httpx.Response(200, json={"id": "doc_1", "status": "ready"})
+
+    assert client(extract, search).extract("doc_1", SCHEMA, wait=False).id == "ext_1" and calls.count("POST") == 2
+
+
+def test_pydantic_schema_and_parse():
+    pydantic = pytest.importorskip("pydantic")
+
+    class Invoice(pydantic.BaseModel):
+        total: float
+
+    def handler(request):
+        if request.method == "POST":
+            assert json.loads(request.content)["configuration"]["data_schema"]["properties"]["total"]["type"] == "number"
+            return httpx.Response(200, json=job())
+        return httpx.Response(200, json=job("COMPLETED", extract_result={"total": 3}))
+
+    assert client(handler).extract("doc_1", Invoice).parse(Invoice) == Invoice(total=3)
+
+
+def test_list_pages_through_every_job():
+    def handler(request):
+        after = request.url.params.get("after")
+        if after is None:
+            return httpx.Response(200, json={"jobs": [job(id="ext_1"), job(id="ext_2")], "next": "ext_2"})
+        return httpx.Response(200, json={"jobs": [job(id="ext_3")], "next": None})
+
+    page = client(handler).jobs.list(limit=2)
+    assert page.has_more and [j.id for j in page] == ["ext_1", "ext_2", "ext_3"]
+
+
+def test_cancel_and_delete():
+    seen = []
+
+    def handler(request):
+        seen.append((request.method, request.url.path))
+        if request.method == "DELETE":
+            return httpx.Response(200, json={"id": "ext_1", "deleted": True})
+        return httpx.Response(200, json=job("CANCELLED"))
+
+    c = client(handler)
+    assert c.jobs.cancel("ext_1").status == "CANCELLED"
+    c.jobs.delete(ExtractJob._from(job()))
+    assert seen == [("POST", "/v1/extract/ext_1/cancel"), ("DELETE", "/v1/extract/ext_1")]
+
+
+def test_no_key_raises(monkeypatch):
+    monkeypatch.delenv("PAGEINDEX_SEARCH_API_KEY", raising=False)
+    with pytest.raises(PageExtractError):
+        PageExtract()

pageindex_extract-0.1.0/tests/test_live.py

@@ -0,0 +1,31 @@
+"""Against the real API, when PAGEINDEX_SEARCH_API_KEY and PAGE_EXTRACT_LIVE_PDF are set: one page, standard tier
+(about $0.03). The PDF is uploaded (or found, if uploaded before) and left in place."""
+import os
+
+import pytest
+
+from pageindex_extract import PageExtract, PageExtractError
+
+PDF = os.environ.get("PAGE_EXTRACT_LIVE_PDF")
+pytestmark = pytest.mark.skipif(not (PDF and os.environ.get("PAGEINDEX_SEARCH_API_KEY")),
+                                reason="set PAGEINDEX_SEARCH_API_KEY and PAGE_EXTRACT_LIVE_PDF")
+
+SCHEMA = {"type": "object", "properties": {
+    "title": {"type": ["string", "null"], "description": "The document's title, as printed on its first page"},
+    "page_count_printed": {"type": ["integer", "null"], "description": "Total pages, if the page says (Page 1 of N)"},
+}}
+
+
+def test_extract_one_page():
+    with PageExtract() as client:
+        job = client.extract(PDF, SCHEMA, pages=1)
+        assert job.status == "COMPLETED" and set(job.result) == {"title", "page_count_printed"}
+        assert job.usage.pages == 1
+        assert client.jobs.get(job.id).result == job.result
+        assert any(j.id == job.id for j in client.jobs.list(limit=10))
+
+
+def test_bad_schema_is_refused():
+    with PageExtract() as client, pytest.raises(PageExtractError) as error:
+        client.jobs.create("doc_does_not_matter", {"type": "string"})
+    assert error.value.status == 400 and error.value.code == "invalid_schema"