Metadata-Version: 2.4
Name: nxtwaveai-ocr
Version: 1.0.0
Summary: Official Python SDK for OCR Agent — extract structured data from documents using AI
Project-URL: Homepage, https://ocr.nxtwaveai.com
Project-URL: Documentation, https://ocr.nxtwaveai.com/settings/api-docs
Project-URL: Repository, https://github.com/nxtwaveai/ocragent-python
Author-email: NxtwaveAI <hello@nxtwaveai.com>
License: MIT
Keywords: ai,document,extraction,invoice,nxtwaveai,ocr,pdf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: httpx>=0.24.0
Description-Content-Type: text/markdown

# ocragent

Official Python SDK for [OCR Agent](https://ocr.nxtwaveai.com) — extract structured data from documents using AI.

## Installation

```bash
pip install ocragent
```

## Quick Start

```python
from ocragent import OcrAgent

client = OcrAgent(api_key="sk_...")

# List your agents
agents = client.agents.list()

# Extract a document
with open("invoice.pdf", "rb") as f:
    result = client.extract(agent_id=agents[0]["id"], file=f)

print(result["data"])
# {"invoice_number": "INV-001", "total_amount": 4250, "due_date": "2025-04-15"}
```

## API

### `OcrAgent(api_key, ...)`

| Parameter | Default | Description |
|---|---|---|
| `api_key` | required | Your API key (`sk_...`) |
| `base_url` | production URL | Override the API base URL |
| `max_retries` | `3` | Retries on 429/5xx |
| `timeout` | `30.0` | Request timeout (seconds) |

### `client.agents`

```python
client.agents.list()
client.agents.get(agent_id)
client.agents.get_schema(agent_id)
client.agents.update_schema(agent_id, fields=[...])
client.agents.set_status(agent_id, "active" | "paused")
client.agents.delete(agent_id)
client.agents.results(agent_id, period="30d", page=1, limit=20)
client.agents.export_results(agent_id, format="csv")   # returns bytes
client.agents.stats(agent_id)
```

### `client.extract`

```python
# Single document
client.extract(agent_id, file, file_back=None, callback_url=None)

# Multiple documents
client.extract.batch(agent_id, files=[f1, f2, f3])

# Pre-upload an image
client.extract.upload_image(file)
```

### `client.jobs`

```python
client.jobs.list(status=None, page=1, limit=20)
client.jobs.get(job_id)
client.jobs.result(job_id)
client.jobs.download(job_id, format="json")  # returns bytes
client.jobs.delete(job_id)
```

### Error Handling

```python
from ocragent.errors import OcrAgentError, AuthError, RateLimitError

try:
    result = client.extract(agent_id="...", file=f)
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except OcrAgentError as e:
    print(e.status, e.code, e.message)
```

### Context manager

```python
with OcrAgent(api_key="sk_...") as client:
    agents = client.agents.list()
```

## License

MIT © [NxtwaveAI](https://nxtwaveai.com)
