Metadata-Version: 2.4
Name: docpeel
Version: 0.2.0
Summary: Official Python SDK for the DocPeel document AI API.
Project-URL: Homepage, https://docpeel.com
Project-URL: Documentation, https://docpeel.com/docs/sdk/python
Project-URL: Repository, https://github.com/docpeel/docpeel-python
Project-URL: Issues, https://github.com/docpeel/docpeel-python/issues
Author-email: DocPeel <support@docpeel.com>
License: MIT
License-File: LICENSE
Keywords: ai document processing,api client,docpeel,document ai,document extraction,invoice parser,ocr,pdf to json,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# docpeel — Python SDK

[![PyPI version](https://img.shields.io/pypi/v/docpeel.svg)](https://pypi.org/project/docpeel/)
[![Python versions](https://img.shields.io/pypi/pyversions/docpeel.svg)](https://pypi.org/project/docpeel/)

Official Python SDK for the [DocPeel](https://docpeel.com) document AI API. Extract
structured JSON from invoices, receipts, contracts, IDs, bank statements, and any
other document — in a few lines of Python.

## Install

```bash
pip install docpeel
```

Requires Python 3.8+.

## Quickstart

```python
import base64
from docpeel import DocPeel

client = DocPeel(api_key="dpk_live_...")  # or set DOCPEEL_API_KEY env var

# DocPeel takes documents as base64 in a JSON body.
with open("invoice.pdf", "rb") as f:
    file_b64 = base64.b64encode(f.read()).decode("ascii")

extraction = client.extractions.create(
    file_b64=file_b64,
    file_name="invoice.pdf",
    template_id="tpl_invoice",  # optional
)

for f in extraction.fields:
    print(f.field, "=", f.value, f"({f.confidence}% confidence)")

# → Invoice Number = INV-2024-081 (98% confidence)
# → Total          = $1,240.00     (97% confidence)
```

Prefer to let the SDK encode for you? Pass a path, `bytes`, or a binary
file-like as `file` and the SDK base64-encodes it before sending:

```python
ext = client.extractions.create("invoice.pdf")  # path — SDK reads + encodes
```

## Authentication

Pass your API key directly or set the `DOCPEEL_API_KEY` environment variable:

```python
import os
os.environ["DOCPEEL_API_KEY"] = "dpk_live_..."
client = DocPeel()
```

Generate keys in your [DocPeel dashboard](https://docpeel.com/dashboard/developers/api-keys).

## API reference

### `client.ping()`

Verify the API key. Returns a dict with key + workspace metadata.

```python
me = client.ping()
# {'api_key': {'id': ..., 'name': ..., 'scopes': [...]}, 'request_id': ...}
```

### `client.extractions.create(file=None, *, file_b64=None, file_name=None, content_type=None, template_id=None)`

Submit a document. Pass **either**:

- `file_b64` — a pre-encoded base64 string (recommended; the SDK passes it
  through untouched). A `data:` URI prefix is allowed and stripped.
  Requires `file_name`.
- `file` — the SDK reads it, base64-encodes it, then sends it. Accepts:
  - A **path** (`str` or `os.PathLike`)
  - Raw **bytes** — requires `file_name`
  - A **binary file-like** object — e.g. `open(path, "rb")` / `io.BytesIO`

Either way the wire format is `application/json` with the body{' '}
`{ "file": <base64>, "file_name": ..., "content_type": ..., "template_id": ... }` —
no multipart upload is ever sent.

Returns an `Extraction` dataclass.

```python
import base64
with open("receipt.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("ascii")
    ext = client.extractions.create(file_b64=b64, file_name="receipt.jpg")
```

### `client.extractions.retrieve(extraction_id)`

```python
ext = client.extractions.retrieve("ext_01HZX...")
```

## Errors

All HTTP errors raise `DocPeelError` with `.status`, `.code`, `.message`, and
`.request_id`:

```python
from docpeel import DocPeel, DocPeelError

try:
    client.extractions.create("invoice.pdf")
except DocPeelError as err:
    if err.code == "rate_limited":
        time.sleep(1)
    else:
        raise
```

## Configuration

```python
client = DocPeel(
    api_key="dpk_live_...",
    base_url="https://api.docpeel.com",  # override for staging
    timeout=60,                          # seconds, default 120
)
```

To customise retries or adapters, pass your own `requests.Session`:

```python
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=Retry(total=3, backoff_factor=0.5)))

client = DocPeel(api_key="dpk_live_...", session=session)
```

## Documentation

- Full docs: <https://docpeel.com/docs>
- Python SDK guide: <https://docpeel.com/docs/sdk/python>
- REST API reference: <https://docpeel.com/docs/api/endpoints>

## License

MIT
