Metadata-Version: 2.1
Name: annotron
Version: 0.1.0
Summary: Annotron — French document parsing (Factur-X, KBis, RIB, paie, CERFA). Official Python SDK.
Author-email: Annotron <hello@annotron.com>
License: Apache-2.0
Project-URL: Homepage, https://annotron.com
Project-URL: Documentation, https://annotron.com/docs
Project-URL: Source, https://github.com/mahmoudsoua/annotron
Project-URL: Issues, https://github.com/mahmoudsoua/annotron/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.9

# annotron — Python SDK

Official Python client for the [Annotron](https://annotron.com) API —
French document parsing (Factur-X, KBis, RIB, paie, CERFA) returning
typed, validated fields.

```bash
pip install annotron
```

## Quickstart

```python
from annotron import Annotron

client = Annotron(api_key="sk_live_...")

result = client.parse("facture.pdf")

print(result.siret)         # "12345678900012"   (Luhn-valide)
print(result.iban)          # "FR12 3456 7890…"  (mod-97-valide)
print(result.total_ttc)     # "1 234,56 €"
print(result.invoice_date)  # "12/03/2026"
print(result.dirigeants)    # ["Jean MARTIN", "Marie DURAND"]
```

For everything not exposed as a property, use `result.items`:

```python
for it in result.items:
    print(it.type, it.content, it.confidence)
```

## Configuration

The client reads from two environment variables if not passed
explicitly:

```bash
export ANNOTRON_API_KEY=sk_live_...
export ANNOTRON_BASE_URL=https://api.annotron.com  # or your self-host
```

## Self-hosting

On the Team plan you can run the worker yourself. Point the SDK at
your endpoint:

```python
client = Annotron(api_key="...", base_url="https://annotron.intra.acme.com")
```

## Errors

```python
from annotron import Annotron, AnnotronError

try:
    r = client.parse("malformed.pdf")
except AnnotronError as e:
    print(f"HTTP {e.status_code}: {e}")
```

## Roadmap

- [x] Synchronous client
- [ ] Async client (`AnnotronAsync` — issue welcome)
- [ ] Batch endpoint (`client.parse_batch(files)`)
- [ ] Webhook signature verification helpers

PRs welcome. Apache-2.0.
