emberleaf 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- emberleaf-0.1.0/.gitignore +18 -0
- emberleaf-0.1.0/LICENSE +21 -0
- emberleaf-0.1.0/PKG-INFO +171 -0
- emberleaf-0.1.0/README.md +149 -0
- emberleaf-0.1.0/pyproject.toml +32 -0
- emberleaf-0.1.0/src/emberleaf/__init__.py +31 -0
- emberleaf-0.1.0/src/emberleaf/client.py +301 -0
- emberleaf-0.1.0/src/emberleaf/errors.py +132 -0
- emberleaf-0.1.0/src/emberleaf/py.typed +0 -0
- emberleaf-0.1.0/tests/test_against_api.py +136 -0
emberleaf-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Emberleaf
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
emberleaf-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: emberleaf
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the Emberleaf API: extract JSON from invoices, contracts and scans; parse, split and classify documents.
|
|
5
|
+
Project-URL: Homepage, https://tryemberleaf.app
|
|
6
|
+
Project-URL: Documentation, https://tryemberleaf.app/docs
|
|
7
|
+
Project-URL: Source, https://github.com/eskamine678-afk/Doc-parser/tree/main/sdk/python
|
|
8
|
+
Author-email: Emberleaf <support@tryemberleaf.app>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: data extraction,document parsing,emberleaf,invoice,llm,ocr,pdf
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Office/Business
|
|
17
|
+
Classifier: Topic :: Text Processing
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Requires-Dist: httpx<1,>=0.25
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Emberleaf Python SDK
|
|
24
|
+
|
|
25
|
+
Turn invoices, contracts, scans and spreadsheets into clean JSON with the [Emberleaf API](https://tryemberleaf.app).
|
|
26
|
+
Every value comes back with the page and box it was read from, so a person can check it in one glance.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pip install emberleaf
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
from emberleaf import Emberleaf
|
|
34
|
+
|
|
35
|
+
client = Emberleaf(api_key="ef_live_…") # or set EMBERLEAF_API_KEY
|
|
36
|
+
result = client.extract("invoice.pdf", schema={"invoice_number": "string", "total": "number"})
|
|
37
|
+
print(result["extracted_data"]) # {'invoice_number': 'INV-2026-0418', 'total': 28644.0}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Get a key in the dashboard: **[tryemberleaf.app](https://tryemberleaf.app) → API keys**. New accounts get 150 free credits.
|
|
41
|
+
|
|
42
|
+
## Quick start without the SDK
|
|
43
|
+
|
|
44
|
+
The API is plain `multipart/form-data` over HTTPS. Send your key as `X-API-Key: ef_live_…` or `Authorization: Bearer ef_live_…`.
|
|
45
|
+
|
|
46
|
+
### cURL
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
curl -X POST https://api.tryemberleaf.app/api/v1/extract \
|
|
50
|
+
-H "Authorization: Bearer $EMBERLEAF_API_KEY" \
|
|
51
|
+
-F "file=@invoice.pdf" \
|
|
52
|
+
-F 'json_schema={"invoice_number":"string","invoice_date":"date","total":"number","line_items":[{"description":"string","amount":"number"}]}'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
A document behind a link? Send `-F "file_url=https://…/invoice.pdf"` instead of `file`.
|
|
56
|
+
|
|
57
|
+
### Node.js (18+, no dependencies)
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { readFile } from 'node:fs/promises';
|
|
61
|
+
|
|
62
|
+
const form = new FormData();
|
|
63
|
+
form.append('file', new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }), 'invoice.pdf');
|
|
64
|
+
form.append('json_schema', JSON.stringify({ invoice_number: 'string', total: 'number' }));
|
|
65
|
+
|
|
66
|
+
const res = await fetch('https://api.tryemberleaf.app/api/v1/extract', {
|
|
67
|
+
method: 'POST',
|
|
68
|
+
headers: { Authorization: `Bearer ${process.env.EMBERLEAF_API_KEY}` },
|
|
69
|
+
body: form,
|
|
70
|
+
signal: AbortSignal.timeout(120_000), // documents usually take 5–30 s
|
|
71
|
+
});
|
|
72
|
+
const body = await res.json();
|
|
73
|
+
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
|
|
74
|
+
console.log(body.extracted_data);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## What the client does
|
|
78
|
+
|
|
79
|
+
| Method | Endpoint | Returns |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `extract(doc, schema=…)` | `/extract` | `extracted_data`, `citations` (page + bbox per field), `job_id` |
|
|
82
|
+
| `parse(doc)` | `/parse` | `markdown`, `blocks` with `bbox: [ymin, xmin, ymax, xmax]` (0–1000), `job_id` |
|
|
83
|
+
| `split(doc, sections=…)` | `/split` | `documents: [{name, start_page, end_page, confidence}]` |
|
|
84
|
+
| `classify(doc, labels=…)` | `/classify` | `results: [{page, label, confidence_score, needs_human_review}]` |
|
|
85
|
+
| `account()` | `/account` | credits left on the account and on this key (free) |
|
|
86
|
+
| `get_task(id)` / `wait(id)` | `/tasks/{id}` | status / finished result of an async task |
|
|
87
|
+
|
|
88
|
+
`doc` can be a file path, an `http(s)` URL (sent as `file_url`), `bytes` (pass `filename=`), or an open binary file.
|
|
89
|
+
|
|
90
|
+
### Read once, ask many times
|
|
91
|
+
|
|
92
|
+
Every call returns a `job_id`. Reuse it for 24 hours instead of the file: the document is not read (or charged) again.
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
parsed = client.parse("contract.pdf")
|
|
96
|
+
parties = client.extract(job_id=parsed["job_id"], schema={"buyer": "string", "seller": "string"})
|
|
97
|
+
kind = client.classify(job_id=parsed["job_id"], labels={"nda": "Non-disclosure agreement", "msa": "Master services agreement"})
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Schemas
|
|
101
|
+
|
|
102
|
+
Shorthand types: `string`, `number`, `integer`, `boolean`, `date` (YYYY-MM-DD), `datetime`. A list of objects is a table:
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
schema = {
|
|
106
|
+
"invoice_number": "string",
|
|
107
|
+
"due_date": "date",
|
|
108
|
+
"line_items": [{"description": "string", "quantity": "number", "amount": "number"}],
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
A full JSON Schema (`{"type": "object", "properties": {…}}`) works too.
|
|
113
|
+
|
|
114
|
+
## Long documents, timeouts and retries
|
|
115
|
+
|
|
116
|
+
Processing takes 5–30 seconds for most documents and longer for big scans. The client never holds one
|
|
117
|
+
HTTP request open for that long: it sends each call as an async task and polls `GET /tasks/{id}`.
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
client = Emberleaf(
|
|
121
|
+
timeout=120, # seconds per HTTP request (upload, status check)
|
|
122
|
+
wait_timeout=600, # seconds to wait for a document to finish
|
|
123
|
+
poll_interval=2, # seconds between status checks
|
|
124
|
+
max_retries=2, # connection errors and 429/502/503/504, with backoff
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
task = client.parse("big-scan.pdf", wait=False) # returns at once with task["task_id"]
|
|
128
|
+
result = client.wait(task["task_id"]) # later, or in another process
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Uploads are never retried after they may have reached the server, so a document is not charged twice.
|
|
132
|
+
|
|
133
|
+
## Errors
|
|
134
|
+
|
|
135
|
+
Every API error has the HTTP status, the stable `code` and the message from `{"error": {"code", "message"}}`.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
from emberleaf import AuthenticationError, BadRequestError, InsufficientCreditsError, TaskTimeoutError
|
|
139
|
+
|
|
140
|
+
try:
|
|
141
|
+
result = client.extract("invoice.pdf", schema={"total": "number"})
|
|
142
|
+
except AuthenticationError:
|
|
143
|
+
... # 401: wrong or revoked key
|
|
144
|
+
except InsufficientCreditsError as exc:
|
|
145
|
+
... # 402: exc.code is "insufficient_credits" or "key_limit_reached"
|
|
146
|
+
except BadRequestError as exc:
|
|
147
|
+
... # 400/413/415/422: exc.code tells what to fix, e.g. "unsupported_file_type"
|
|
148
|
+
except TaskTimeoutError as exc:
|
|
149
|
+
result = client.wait(exc.task_id) # still running on the server: wait longer
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
| Class | When |
|
|
153
|
+
|---|---|
|
|
154
|
+
| `AuthenticationError` | 401 |
|
|
155
|
+
| `InsufficientCreditsError` | 402 (`insufficient_credits`, `key_limit_reached`) |
|
|
156
|
+
| `BadRequestError` | 400, 413, 415, 422 |
|
|
157
|
+
| `NotFoundError` | 404 (`job_not_found`, `task_not_found`) |
|
|
158
|
+
| `ServerError` | 5xx (`parser_failed`, `llm_unavailable`, `file_url_timeout`…) |
|
|
159
|
+
| `TaskFailedError` | also raised (with the class above) when a task ends as failed; has `task_id` |
|
|
160
|
+
| `TaskTimeoutError` | `wait_timeout` passed; the task may still finish |
|
|
161
|
+
| `ConnectionFailedError` | the API could not be reached after the retries |
|
|
162
|
+
|
|
163
|
+
All of them inherit from `EmberleafError`.
|
|
164
|
+
|
|
165
|
+
## More
|
|
166
|
+
|
|
167
|
+
- API reference and OpenAPI: [tryemberleaf.app/docs](https://tryemberleaf.app/docs) · [`/openapi.yaml`](https://api.tryemberleaf.app/openapi.yaml)
|
|
168
|
+
- n8n: install the community node `n8n-nodes-emberleaf`
|
|
169
|
+
- Support: support@tryemberleaf.app
|
|
170
|
+
|
|
171
|
+
MIT License.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Emberleaf Python SDK
|
|
2
|
+
|
|
3
|
+
Turn invoices, contracts, scans and spreadsheets into clean JSON with the [Emberleaf API](https://tryemberleaf.app).
|
|
4
|
+
Every value comes back with the page and box it was read from, so a person can check it in one glance.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
pip install emberleaf
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
```python
|
|
11
|
+
from emberleaf import Emberleaf
|
|
12
|
+
|
|
13
|
+
client = Emberleaf(api_key="ef_live_…") # or set EMBERLEAF_API_KEY
|
|
14
|
+
result = client.extract("invoice.pdf", schema={"invoice_number": "string", "total": "number"})
|
|
15
|
+
print(result["extracted_data"]) # {'invoice_number': 'INV-2026-0418', 'total': 28644.0}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Get a key in the dashboard: **[tryemberleaf.app](https://tryemberleaf.app) → API keys**. New accounts get 150 free credits.
|
|
19
|
+
|
|
20
|
+
## Quick start without the SDK
|
|
21
|
+
|
|
22
|
+
The API is plain `multipart/form-data` over HTTPS. Send your key as `X-API-Key: ef_live_…` or `Authorization: Bearer ef_live_…`.
|
|
23
|
+
|
|
24
|
+
### cURL
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
curl -X POST https://api.tryemberleaf.app/api/v1/extract \
|
|
28
|
+
-H "Authorization: Bearer $EMBERLEAF_API_KEY" \
|
|
29
|
+
-F "file=@invoice.pdf" \
|
|
30
|
+
-F 'json_schema={"invoice_number":"string","invoice_date":"date","total":"number","line_items":[{"description":"string","amount":"number"}]}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
A document behind a link? Send `-F "file_url=https://…/invoice.pdf"` instead of `file`.
|
|
34
|
+
|
|
35
|
+
### Node.js (18+, no dependencies)
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
import { readFile } from 'node:fs/promises';
|
|
39
|
+
|
|
40
|
+
const form = new FormData();
|
|
41
|
+
form.append('file', new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }), 'invoice.pdf');
|
|
42
|
+
form.append('json_schema', JSON.stringify({ invoice_number: 'string', total: 'number' }));
|
|
43
|
+
|
|
44
|
+
const res = await fetch('https://api.tryemberleaf.app/api/v1/extract', {
|
|
45
|
+
method: 'POST',
|
|
46
|
+
headers: { Authorization: `Bearer ${process.env.EMBERLEAF_API_KEY}` },
|
|
47
|
+
body: form,
|
|
48
|
+
signal: AbortSignal.timeout(120_000), // documents usually take 5–30 s
|
|
49
|
+
});
|
|
50
|
+
const body = await res.json();
|
|
51
|
+
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
|
|
52
|
+
console.log(body.extracted_data);
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## What the client does
|
|
56
|
+
|
|
57
|
+
| Method | Endpoint | Returns |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `extract(doc, schema=…)` | `/extract` | `extracted_data`, `citations` (page + bbox per field), `job_id` |
|
|
60
|
+
| `parse(doc)` | `/parse` | `markdown`, `blocks` with `bbox: [ymin, xmin, ymax, xmax]` (0–1000), `job_id` |
|
|
61
|
+
| `split(doc, sections=…)` | `/split` | `documents: [{name, start_page, end_page, confidence}]` |
|
|
62
|
+
| `classify(doc, labels=…)` | `/classify` | `results: [{page, label, confidence_score, needs_human_review}]` |
|
|
63
|
+
| `account()` | `/account` | credits left on the account and on this key (free) |
|
|
64
|
+
| `get_task(id)` / `wait(id)` | `/tasks/{id}` | status / finished result of an async task |
|
|
65
|
+
|
|
66
|
+
`doc` can be a file path, an `http(s)` URL (sent as `file_url`), `bytes` (pass `filename=`), or an open binary file.
|
|
67
|
+
|
|
68
|
+
### Read once, ask many times
|
|
69
|
+
|
|
70
|
+
Every call returns a `job_id`. Reuse it for 24 hours instead of the file: the document is not read (or charged) again.
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
parsed = client.parse("contract.pdf")
|
|
74
|
+
parties = client.extract(job_id=parsed["job_id"], schema={"buyer": "string", "seller": "string"})
|
|
75
|
+
kind = client.classify(job_id=parsed["job_id"], labels={"nda": "Non-disclosure agreement", "msa": "Master services agreement"})
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Schemas
|
|
79
|
+
|
|
80
|
+
Shorthand types: `string`, `number`, `integer`, `boolean`, `date` (YYYY-MM-DD), `datetime`. A list of objects is a table:
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
schema = {
|
|
84
|
+
"invoice_number": "string",
|
|
85
|
+
"due_date": "date",
|
|
86
|
+
"line_items": [{"description": "string", "quantity": "number", "amount": "number"}],
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
A full JSON Schema (`{"type": "object", "properties": {…}}`) works too.
|
|
91
|
+
|
|
92
|
+
## Long documents, timeouts and retries
|
|
93
|
+
|
|
94
|
+
Processing takes 5–30 seconds for most documents and longer for big scans. The client never holds one
|
|
95
|
+
HTTP request open for that long: it sends each call as an async task and polls `GET /tasks/{id}`.
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
client = Emberleaf(
|
|
99
|
+
timeout=120, # seconds per HTTP request (upload, status check)
|
|
100
|
+
wait_timeout=600, # seconds to wait for a document to finish
|
|
101
|
+
poll_interval=2, # seconds between status checks
|
|
102
|
+
max_retries=2, # connection errors and 429/502/503/504, with backoff
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
task = client.parse("big-scan.pdf", wait=False) # returns at once with task["task_id"]
|
|
106
|
+
result = client.wait(task["task_id"]) # later, or in another process
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Uploads are never retried after they may have reached the server, so a document is not charged twice.
|
|
110
|
+
|
|
111
|
+
## Errors
|
|
112
|
+
|
|
113
|
+
Every API error has the HTTP status, the stable `code` and the message from `{"error": {"code", "message"}}`.
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from emberleaf import AuthenticationError, BadRequestError, InsufficientCreditsError, TaskTimeoutError
|
|
117
|
+
|
|
118
|
+
try:
|
|
119
|
+
result = client.extract("invoice.pdf", schema={"total": "number"})
|
|
120
|
+
except AuthenticationError:
|
|
121
|
+
... # 401: wrong or revoked key
|
|
122
|
+
except InsufficientCreditsError as exc:
|
|
123
|
+
... # 402: exc.code is "insufficient_credits" or "key_limit_reached"
|
|
124
|
+
except BadRequestError as exc:
|
|
125
|
+
... # 400/413/415/422: exc.code tells what to fix, e.g. "unsupported_file_type"
|
|
126
|
+
except TaskTimeoutError as exc:
|
|
127
|
+
result = client.wait(exc.task_id) # still running on the server: wait longer
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
| Class | When |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `AuthenticationError` | 401 |
|
|
133
|
+
| `InsufficientCreditsError` | 402 (`insufficient_credits`, `key_limit_reached`) |
|
|
134
|
+
| `BadRequestError` | 400, 413, 415, 422 |
|
|
135
|
+
| `NotFoundError` | 404 (`job_not_found`, `task_not_found`) |
|
|
136
|
+
| `ServerError` | 5xx (`parser_failed`, `llm_unavailable`, `file_url_timeout`…) |
|
|
137
|
+
| `TaskFailedError` | also raised (with the class above) when a task ends as failed; has `task_id` |
|
|
138
|
+
| `TaskTimeoutError` | `wait_timeout` passed; the task may still finish |
|
|
139
|
+
| `ConnectionFailedError` | the API could not be reached after the retries |
|
|
140
|
+
|
|
141
|
+
All of them inherit from `EmberleafError`.
|
|
142
|
+
|
|
143
|
+
## More
|
|
144
|
+
|
|
145
|
+
- API reference and OpenAPI: [tryemberleaf.app/docs](https://tryemberleaf.app/docs) · [`/openapi.yaml`](https://api.tryemberleaf.app/openapi.yaml)
|
|
146
|
+
- n8n: install the community node `n8n-nodes-emberleaf`
|
|
147
|
+
- Support: support@tryemberleaf.app
|
|
148
|
+
|
|
149
|
+
MIT License.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27,<1.28"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "emberleaf"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Python client for the Emberleaf API: extract JSON from invoices, contracts and scans; parse, split and classify documents."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
authors = [{ name = "Emberleaf", email = "support@tryemberleaf.app" }]
|
|
14
|
+
keywords = ["emberleaf", "document parsing", "data extraction", "ocr", "pdf", "invoice", "llm"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Topic :: Office/Business",
|
|
21
|
+
"Topic :: Text Processing",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
dependencies = ["httpx>=0.25,<1"]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://tryemberleaf.app"
|
|
28
|
+
Documentation = "https://tryemberleaf.app/docs"
|
|
29
|
+
Source = "https://github.com/eskamine678-afk/Doc-parser/tree/main/sdk/python"
|
|
30
|
+
|
|
31
|
+
[tool.hatch.build.targets.wheel]
|
|
32
|
+
packages = ["src/emberleaf"]
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Python client for the Emberleaf document API: parse, extract, split and classify documents."""
|
|
2
|
+
|
|
3
|
+
from .client import DEFAULT_BASE_URL, Emberleaf, __version__
|
|
4
|
+
from .errors import (
|
|
5
|
+
APIError,
|
|
6
|
+
AuthenticationError,
|
|
7
|
+
BadRequestError,
|
|
8
|
+
ConnectionFailedError,
|
|
9
|
+
EmberleafError,
|
|
10
|
+
InsufficientCreditsError,
|
|
11
|
+
NotFoundError,
|
|
12
|
+
ServerError,
|
|
13
|
+
TaskFailedError,
|
|
14
|
+
TaskTimeoutError,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"DEFAULT_BASE_URL",
|
|
19
|
+
"Emberleaf",
|
|
20
|
+
"__version__",
|
|
21
|
+
"APIError",
|
|
22
|
+
"AuthenticationError",
|
|
23
|
+
"BadRequestError",
|
|
24
|
+
"ConnectionFailedError",
|
|
25
|
+
"EmberleafError",
|
|
26
|
+
"InsufficientCreditsError",
|
|
27
|
+
"NotFoundError",
|
|
28
|
+
"ServerError",
|
|
29
|
+
"TaskFailedError",
|
|
30
|
+
"TaskTimeoutError",
|
|
31
|
+
]
|
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
"""Small, dependable client for the Emberleaf API.
|
|
2
|
+
|
|
3
|
+
from emberleaf import Emberleaf
|
|
4
|
+
|
|
5
|
+
client = Emberleaf() # reads EMBERLEAF_API_KEY
|
|
6
|
+
result = client.extract("invoice.pdf", schema={"invoice_number": "string", "total": "number"})
|
|
7
|
+
print(result["extracted_data"])
|
|
8
|
+
|
|
9
|
+
Documents can take 10–30 seconds (longer for big scans), so by default every call is sent as an
|
|
10
|
+
async task and the client polls until it finishes; no HTTP request has to stay open that long.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import json
|
|
16
|
+
import mimetypes
|
|
17
|
+
import os
|
|
18
|
+
import time
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import IO, Any, Literal, Mapping, Sequence, Union
|
|
21
|
+
|
|
22
|
+
import httpx
|
|
23
|
+
|
|
24
|
+
from .errors import (
|
|
25
|
+
ConnectionFailedError,
|
|
26
|
+
EmberleafError,
|
|
27
|
+
TaskTimeoutError,
|
|
28
|
+
error_for,
|
|
29
|
+
task_error,
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
__version__ = "0.1.0"
|
|
33
|
+
|
|
34
|
+
DEFAULT_BASE_URL = "https://api.tryemberleaf.app"
|
|
35
|
+
|
|
36
|
+
Document = Union[str, os.PathLike, bytes, IO[bytes]]
|
|
37
|
+
"""A file path, a public/signed http(s) URL, raw bytes or an open binary file."""
|
|
38
|
+
|
|
39
|
+
Named = Union[Mapping[str, str], Sequence[Mapping[str, str]]]
|
|
40
|
+
"""Sections or labels: {"invoice": "Commercial invoice"} or [{"name": ..., "description": ...}]."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class Emberleaf:
|
|
44
|
+
"""Synchronous client. Thread-safe; reuse one instance (it keeps a connection pool).
|
|
45
|
+
|
|
46
|
+
Args:
|
|
47
|
+
api_key: Your key (ef_live_…). Defaults to the EMBERLEAF_API_KEY environment variable.
|
|
48
|
+
base_url: API origin. Defaults to EMBERLEAF_BASE_URL or https://api.tryemberleaf.app.
|
|
49
|
+
timeout: Seconds for one HTTP request (uploads and status checks), not for the whole job.
|
|
50
|
+
max_retries: Retries for connection errors and 429/502/503/504 answers, with backoff.
|
|
51
|
+
wait_timeout: Default seconds to wait for a document to finish.
|
|
52
|
+
poll_interval: Seconds between task status checks.
|
|
53
|
+
http_client: Bring your own httpx.Client (proxies, custom TLS, tests).
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
def __init__(
|
|
57
|
+
self,
|
|
58
|
+
api_key: str | None = None,
|
|
59
|
+
*,
|
|
60
|
+
base_url: str | None = None,
|
|
61
|
+
timeout: float = 120.0,
|
|
62
|
+
max_retries: int = 2,
|
|
63
|
+
wait_timeout: float = 300.0,
|
|
64
|
+
poll_interval: float = 2.0,
|
|
65
|
+
http_client: httpx.Client | None = None,
|
|
66
|
+
) -> None:
|
|
67
|
+
key = api_key or os.environ.get("EMBERLEAF_API_KEY")
|
|
68
|
+
if not key:
|
|
69
|
+
raise EmberleafError("No API key: pass api_key=... or set EMBERLEAF_API_KEY.")
|
|
70
|
+
self.base_url = (base_url or os.environ.get("EMBERLEAF_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
|
|
71
|
+
self.max_retries = max(0, max_retries)
|
|
72
|
+
self.wait_timeout = wait_timeout
|
|
73
|
+
self.poll_interval = max(0.2, poll_interval)
|
|
74
|
+
self._owns_client = http_client is None
|
|
75
|
+
self._http = http_client or httpx.Client(timeout=httpx.Timeout(timeout, connect=10.0))
|
|
76
|
+
self._headers = {
|
|
77
|
+
"Authorization": f"Bearer {key}",
|
|
78
|
+
"User-Agent": f"emberleaf-python/{__version__}",
|
|
79
|
+
"Accept": "application/json",
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
# ------------------------------------------------------------------ lifecycle
|
|
83
|
+
|
|
84
|
+
def close(self) -> None:
|
|
85
|
+
if self._owns_client:
|
|
86
|
+
self._http.close()
|
|
87
|
+
|
|
88
|
+
def __enter__(self) -> "Emberleaf":
|
|
89
|
+
return self
|
|
90
|
+
|
|
91
|
+
def __exit__(self, *_: object) -> None:
|
|
92
|
+
self.close()
|
|
93
|
+
|
|
94
|
+
# ------------------------------------------------------------------ endpoints
|
|
95
|
+
|
|
96
|
+
def extract(
|
|
97
|
+
self,
|
|
98
|
+
document: Document | None = None,
|
|
99
|
+
*,
|
|
100
|
+
schema: Mapping[str, Any],
|
|
101
|
+
job_id: str | None = None,
|
|
102
|
+
instructions: str | None = None,
|
|
103
|
+
filename: str | None = None,
|
|
104
|
+
wait: bool = True,
|
|
105
|
+
timeout: float | None = None,
|
|
106
|
+
) -> dict[str, Any]:
|
|
107
|
+
"""Extract the fields of `schema` (JSON Schema or shorthand like {"total": "number"}).
|
|
108
|
+
|
|
109
|
+
Returns the API response: `extracted_data`, `citations` (page and bbox per field), `job_id`,
|
|
110
|
+
`usage`, `credits_used`, `credits_remaining`.
|
|
111
|
+
"""
|
|
112
|
+
if not schema:
|
|
113
|
+
raise EmberleafError("schema must be a non-empty mapping.")
|
|
114
|
+
fields: dict[str, Any] = {"json_schema": json.dumps(schema)}
|
|
115
|
+
if instructions:
|
|
116
|
+
fields["instructions"] = instructions
|
|
117
|
+
return self._run("extract", document, job_id, filename, fields, wait, timeout)
|
|
118
|
+
|
|
119
|
+
def parse(
|
|
120
|
+
self,
|
|
121
|
+
document: Document | None = None,
|
|
122
|
+
*,
|
|
123
|
+
job_id: str | None = None,
|
|
124
|
+
precision: Literal["auto", "high"] = "auto",
|
|
125
|
+
include_page_images: bool = False,
|
|
126
|
+
filename: str | None = None,
|
|
127
|
+
wait: bool = True,
|
|
128
|
+
timeout: float | None = None,
|
|
129
|
+
) -> dict[str, Any]:
|
|
130
|
+
"""Markdown, typed blocks with bbox [ymin, xmin, ymax, xmax] (0–1000) and a reusable job_id."""
|
|
131
|
+
fields: dict[str, Any] = {"precision": precision}
|
|
132
|
+
if include_page_images:
|
|
133
|
+
fields["include_page_images"] = "true"
|
|
134
|
+
return self._run("parse", document, job_id, filename, fields, wait, timeout)
|
|
135
|
+
|
|
136
|
+
def split(
|
|
137
|
+
self,
|
|
138
|
+
document: Document | None = None,
|
|
139
|
+
*,
|
|
140
|
+
sections: Named,
|
|
141
|
+
job_id: str | None = None,
|
|
142
|
+
filename: str | None = None,
|
|
143
|
+
wait: bool = True,
|
|
144
|
+
timeout: float | None = None,
|
|
145
|
+
) -> dict[str, Any]:
|
|
146
|
+
"""Page ranges of each document inside a package: `documents: [{name, start_page, end_page, confidence}]`."""
|
|
147
|
+
fields = {"sections": json.dumps(_named(sections, "sections"))}
|
|
148
|
+
return self._run("split", document, job_id, filename, fields, wait, timeout)
|
|
149
|
+
|
|
150
|
+
def classify(
|
|
151
|
+
self,
|
|
152
|
+
document: Document | None = None,
|
|
153
|
+
*,
|
|
154
|
+
labels: Named,
|
|
155
|
+
granularity: Literal["file", "page"] = "file",
|
|
156
|
+
job_id: str | None = None,
|
|
157
|
+
filename: str | None = None,
|
|
158
|
+
wait: bool = True,
|
|
159
|
+
timeout: float | None = None,
|
|
160
|
+
) -> dict[str, Any]:
|
|
161
|
+
"""Zero-shot labels: `results: [{page, label, confidence_score, needs_human_review}]`."""
|
|
162
|
+
fields = {"labels": json.dumps(_named(labels, "labels")), "granularity": granularity}
|
|
163
|
+
return self._run("classify", document, job_id, filename, fields, wait, timeout)
|
|
164
|
+
|
|
165
|
+
def account(self) -> dict[str, Any]:
|
|
166
|
+
"""Check the key (free): account id and credits left, overall and for this key this month."""
|
|
167
|
+
return self._request("GET", "/api/v1/account")
|
|
168
|
+
|
|
169
|
+
def get_task(self, task_id: str) -> dict[str, Any]:
|
|
170
|
+
"""Status of an async task: queued, processing, completed (with `result`) or failed (with `error`)."""
|
|
171
|
+
return self._request("GET", f"/api/v1/tasks/{task_id}")
|
|
172
|
+
|
|
173
|
+
def wait(self, task_id: str, *, timeout: float | None = None) -> dict[str, Any]:
|
|
174
|
+
"""Poll a task until it completes and return its result (the same body as a synchronous call)."""
|
|
175
|
+
limit = self.wait_timeout if timeout is None else timeout
|
|
176
|
+
deadline = time.monotonic() + limit
|
|
177
|
+
delay = min(1.0, self.poll_interval)
|
|
178
|
+
while True:
|
|
179
|
+
task = self.get_task(task_id)
|
|
180
|
+
status = task.get("status")
|
|
181
|
+
if status == "completed":
|
|
182
|
+
return task.get("result") or {}
|
|
183
|
+
if status == "failed":
|
|
184
|
+
raise task_error(task_id, task.get("error"))
|
|
185
|
+
if time.monotonic() + delay > deadline:
|
|
186
|
+
raise TaskTimeoutError(task_id, limit)
|
|
187
|
+
time.sleep(delay)
|
|
188
|
+
delay = self.poll_interval
|
|
189
|
+
|
|
190
|
+
# ------------------------------------------------------------------ internals
|
|
191
|
+
|
|
192
|
+
def _run(
|
|
193
|
+
self,
|
|
194
|
+
endpoint: str,
|
|
195
|
+
document: Document | None,
|
|
196
|
+
job_id: str | None,
|
|
197
|
+
filename: str | None,
|
|
198
|
+
fields: dict[str, Any],
|
|
199
|
+
wait: bool,
|
|
200
|
+
timeout: float | None,
|
|
201
|
+
) -> dict[str, Any]:
|
|
202
|
+
data = dict(fields)
|
|
203
|
+
files: dict[str, tuple[str, Any, str]] | None = None
|
|
204
|
+
handle: IO[bytes] | None = None
|
|
205
|
+
if job_id:
|
|
206
|
+
if document is not None:
|
|
207
|
+
raise EmberleafError("Pass either a document or job_id, not both.")
|
|
208
|
+
data["job_id"] = job_id
|
|
209
|
+
elif document is None:
|
|
210
|
+
raise EmberleafError("Pass a document (path, URL, bytes or file) or job_id.")
|
|
211
|
+
elif isinstance(document, str) and document.startswith(("https://", "http://")):
|
|
212
|
+
data["file_url"] = document
|
|
213
|
+
else:
|
|
214
|
+
name, content, handle = _open(document, filename)
|
|
215
|
+
files = {"file": (name, content, mimetypes.guess_type(name)[0] or "application/octet-stream")}
|
|
216
|
+
data["async"] = "true"
|
|
217
|
+
try:
|
|
218
|
+
accepted = self._request("POST", f"/api/v1/{endpoint}", data=data, files=files)
|
|
219
|
+
finally:
|
|
220
|
+
if handle is not None:
|
|
221
|
+
handle.close()
|
|
222
|
+
task_id = accepted.get("task_id")
|
|
223
|
+
if not wait or not task_id:
|
|
224
|
+
return accepted
|
|
225
|
+
return self.wait(str(task_id), timeout=timeout)
|
|
226
|
+
|
|
227
|
+
def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
|
|
228
|
+
url = f"{self.base_url}{path}"
|
|
229
|
+
retryable_status = {429, 502, 503, 504} if method == "GET" else {429}
|
|
230
|
+
attempt = 0
|
|
231
|
+
while True:
|
|
232
|
+
try:
|
|
233
|
+
response = self._http.request(method, url, headers=self._headers, **kwargs)
|
|
234
|
+
except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout, httpx.RemoteProtocolError) as exc:
|
|
235
|
+
# A POST that may have reached the server is not repeated (it could be charged twice).
|
|
236
|
+
safe = method == "GET" or isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout))
|
|
237
|
+
if not safe or attempt >= self.max_retries:
|
|
238
|
+
raise ConnectionFailedError(f"Could not reach {self.base_url}: {exc.__class__.__name__}: {exc}") from exc
|
|
239
|
+
attempt += 1
|
|
240
|
+
time.sleep(_backoff(attempt))
|
|
241
|
+
_rewind(kwargs.get("files"))
|
|
242
|
+
continue
|
|
243
|
+
if response.status_code in retryable_status and attempt < self.max_retries:
|
|
244
|
+
attempt += 1
|
|
245
|
+
time.sleep(_retry_after(response) or _backoff(attempt))
|
|
246
|
+
_rewind(kwargs.get("files"))
|
|
247
|
+
continue
|
|
248
|
+
return _body(response)
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _body(response: httpx.Response) -> dict[str, Any]:
|
|
252
|
+
try:
|
|
253
|
+
body: Any = response.json()
|
|
254
|
+
except ValueError:
|
|
255
|
+
body = response.text
|
|
256
|
+
if response.status_code >= 400:
|
|
257
|
+
raise error_for(response.status_code, body, response.headers.get("x-request-id"))
|
|
258
|
+
if not isinstance(body, dict):
|
|
259
|
+
raise EmberleafError(f"Unexpected response from the API: {str(body)[:200]}")
|
|
260
|
+
return body
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def _open(document: Document, filename: str | None) -> tuple[str, Any, IO[bytes] | None]:
|
|
264
|
+
"""(name, content, handle to close) for a path, bytes or file object."""
|
|
265
|
+
if isinstance(document, (bytes, bytearray)):
|
|
266
|
+
return filename or "document.pdf", bytes(document), None
|
|
267
|
+
if isinstance(document, (str, os.PathLike)):
|
|
268
|
+
path = Path(document)
|
|
269
|
+
if not path.is_file():
|
|
270
|
+
raise EmberleafError(f"File not found: {path}")
|
|
271
|
+
handle = path.open("rb")
|
|
272
|
+
return filename or path.name, handle, handle
|
|
273
|
+
if hasattr(document, "read"):
|
|
274
|
+
name = filename or Path(getattr(document, "name", "") or "document.pdf").name
|
|
275
|
+
return name, document, None
|
|
276
|
+
raise EmberleafError("document must be a path, an http(s) URL, bytes or a binary file object.")
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def _rewind(files: Any) -> None:
|
|
280
|
+
"""Retried uploads must send the file from the start again."""
|
|
281
|
+
if not files:
|
|
282
|
+
return
|
|
283
|
+
for _, content, _ in files.values():
|
|
284
|
+
if hasattr(content, "seek"):
|
|
285
|
+
content.seek(0)
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _named(value: Named, what: str) -> list[dict[str, str]]:
|
|
289
|
+
items = [{"name": k, "description": v} for k, v in value.items()] if isinstance(value, Mapping) else [dict(v) for v in value]
|
|
290
|
+
if not items or not all(item.get("name") for item in items):
|
|
291
|
+
raise EmberleafError(f"{what} needs at least one item, each with a name.")
|
|
292
|
+
return items
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def _backoff(attempt: int) -> float:
|
|
296
|
+
return min(8.0, 0.5 * 2**attempt)
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
def _retry_after(response: httpx.Response) -> float | None:
|
|
300
|
+
value = response.headers.get("retry-after", "")
|
|
301
|
+
return min(30.0, float(value)) if value.replace(".", "", 1).isdigit() else None
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
"""Errors raised by the Emberleaf client. Every API error carries the `code` from
|
|
2
|
+
`{"error": {"code", "message", "details"}}`, the HTTP status and the request id."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class EmberleafError(Exception):
|
|
10
|
+
"""Base class for everything this package raises."""
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class APIError(EmberleafError):
|
|
14
|
+
"""The API answered with an error."""
|
|
15
|
+
|
|
16
|
+
def __init__(
|
|
17
|
+
self,
|
|
18
|
+
message: str,
|
|
19
|
+
*,
|
|
20
|
+
status_code: int,
|
|
21
|
+
code: str = "unknown_error",
|
|
22
|
+
details: Any = None,
|
|
23
|
+
request_id: str | None = None,
|
|
24
|
+
) -> None:
|
|
25
|
+
super().__init__(f"[{status_code} {code}] {message}")
|
|
26
|
+
self.message = message
|
|
27
|
+
self.status_code = status_code
|
|
28
|
+
self.code = code
|
|
29
|
+
self.details = details
|
|
30
|
+
self.request_id = request_id
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class BadRequestError(APIError):
|
|
34
|
+
"""400 / 413 / 415 / 422: the request itself is wrong (missing file, bad schema, too large)."""
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class AuthenticationError(APIError):
|
|
38
|
+
"""401: the API key is missing, wrong or revoked."""
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class InsufficientCreditsError(APIError):
|
|
42
|
+
"""402: not enough credits, or the key's monthly limit is reached (`code == "key_limit_reached"`)."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class NotFoundError(APIError):
|
|
46
|
+
"""404: unknown or expired job_id, task or template."""
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class ServerError(APIError):
|
|
50
|
+
"""5xx: an engine or the API failed. Safe to retry later."""
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class TaskFailedError(APIError):
|
|
54
|
+
"""An async task finished with status "failed".
|
|
55
|
+
|
|
56
|
+
Raised together with the matching class: a missing job_id is both NotFoundError and
|
|
57
|
+
TaskFailedError, so either except clause catches it. `status_code` is the HTTP status the
|
|
58
|
+
same error would have had on a synchronous call.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
task_id: str = ""
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class TaskTimeoutError(EmberleafError):
|
|
65
|
+
"""The task did not finish within the wait timeout; it may still complete on the server."""
|
|
66
|
+
|
|
67
|
+
def __init__(self, task_id: str, timeout: float) -> None:
|
|
68
|
+
super().__init__(f"Task {task_id} did not finish within {timeout:.0f} s. Call client.wait(task_id) again later.")
|
|
69
|
+
self.task_id = task_id
|
|
70
|
+
self.timeout = timeout
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class ConnectionFailedError(EmberleafError):
|
|
74
|
+
"""The API could not be reached (DNS, TLS, timeout) after the retries."""
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
# HTTP status of error codes that are reported inside a finished task.
|
|
78
|
+
_TASK_STATUS = {
|
|
79
|
+
"job_not_found": 404,
|
|
80
|
+
"task_not_found": 404,
|
|
81
|
+
"template_not_found": 404,
|
|
82
|
+
"unsupported_file_type": 415,
|
|
83
|
+
"file_too_large": 413,
|
|
84
|
+
"insufficient_credits": 402,
|
|
85
|
+
"key_limit_reached": 402,
|
|
86
|
+
"parser_unavailable": 503,
|
|
87
|
+
"llm_unavailable": 503,
|
|
88
|
+
"email_unavailable": 503,
|
|
89
|
+
"parser_failed": 502,
|
|
90
|
+
"llm_failed": 502,
|
|
91
|
+
"file_url_failed": 502,
|
|
92
|
+
"file_url_timeout": 504,
|
|
93
|
+
}
|
|
94
|
+
_task_classes: dict[type, type] = {}
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def task_error(task_id: str, error: Any) -> APIError:
|
|
98
|
+
"""The error of a failed task, as the specific class (NotFoundError, …) and TaskFailedError."""
|
|
99
|
+
detail = error if isinstance(error, dict) else {}
|
|
100
|
+
code = str(detail.get("code") or "task_failed")
|
|
101
|
+
status = _TASK_STATUS.get(code) or (400 if code.startswith(("invalid", "missing", "empty", "conflicting")) else 500)
|
|
102
|
+
base = type(error_for(status, {"error": detail}, None))
|
|
103
|
+
cls = _task_classes.get(base)
|
|
104
|
+
if cls is None:
|
|
105
|
+
cls = type(f"Task{base.__name__}", (base, TaskFailedError), {})
|
|
106
|
+
_task_classes[base] = cls
|
|
107
|
+
message = str(detail.get("message") or "The task failed.")
|
|
108
|
+
exc = cls(f"{message} (task {task_id})", status_code=status, code=code, details=detail.get("details"))
|
|
109
|
+
exc.task_id = task_id
|
|
110
|
+
return exc
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def error_for(status_code: int, body: Any, request_id: str | None) -> APIError:
|
|
114
|
+
"""Build the most specific error for a response."""
|
|
115
|
+
error = body.get("error") if isinstance(body, dict) else None
|
|
116
|
+
code = str(error.get("code") or "unknown_error") if isinstance(error, dict) else "unknown_error"
|
|
117
|
+
message = str(error.get("message") or "") if isinstance(error, dict) else ""
|
|
118
|
+
details = error.get("details") if isinstance(error, dict) else None
|
|
119
|
+
message = message or (body if isinstance(body, str) and body else f"HTTP {status_code}")
|
|
120
|
+
if status_code == 401:
|
|
121
|
+
cls: type[APIError] = AuthenticationError
|
|
122
|
+
elif status_code == 402:
|
|
123
|
+
cls = InsufficientCreditsError
|
|
124
|
+
elif status_code == 404:
|
|
125
|
+
cls = NotFoundError
|
|
126
|
+
elif status_code >= 500:
|
|
127
|
+
cls = ServerError
|
|
128
|
+
elif status_code >= 400:
|
|
129
|
+
cls = BadRequestError
|
|
130
|
+
else:
|
|
131
|
+
cls = APIError
|
|
132
|
+
return cls(message, status_code=status_code, code=code, details=details, request_id=request_id)
|
|
File without changes
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""End-to-end check of the SDK against the real FastAPI app (local mode, no network, no keys).
|
|
2
|
+
|
|
3
|
+
Run from the repository root inside the backend image:
|
|
4
|
+
|
|
5
|
+
docker run --rm -v "$PWD:/repo" -w /repo/backend -e ENVIRONMENT=dev docparser-api \
|
|
6
|
+
python ../sdk/python/tests/test_against_api.py
|
|
7
|
+
|
|
8
|
+
Uses Starlette's TestClient (an httpx.Client) as the SDK's transport, so every request goes
|
|
9
|
+
through the same routing, auth, validation and async task runner as production.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import io
|
|
15
|
+
import os
|
|
16
|
+
import sys
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
|
|
19
|
+
REPO = Path(__file__).resolve().parents[3]
|
|
20
|
+
sys.path.insert(0, str(REPO / "backend"))
|
|
21
|
+
sys.path.insert(0, str(REPO / "sdk" / "python" / "src"))
|
|
22
|
+
os.environ.setdefault("ENVIRONMENT", "dev")
|
|
23
|
+
for key in ("REDUCTO_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY", "SUPABASE_URL", "SUPABASE_SERVICE_KEY"):
|
|
24
|
+
os.environ[key] = ""
|
|
25
|
+
|
|
26
|
+
import httpx # noqa: E402
|
|
27
|
+
from fastapi.testclient import TestClient # noqa: E402
|
|
28
|
+
|
|
29
|
+
from emberleaf import ( # noqa: E402
|
|
30
|
+
BadRequestError,
|
|
31
|
+
ConnectionFailedError,
|
|
32
|
+
Emberleaf,
|
|
33
|
+
EmberleafError,
|
|
34
|
+
NotFoundError,
|
|
35
|
+
TaskFailedError,
|
|
36
|
+
)
|
|
37
|
+
from main import app # noqa: E402
|
|
38
|
+
from services.documents import _html_to_pdf # noqa: E402
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def make_pdf() -> bytes:
|
|
42
|
+
"""A digital (text-layer) invoice, read locally without any engine key."""
|
|
43
|
+
html = (
|
|
44
|
+
"<h1>INVOICE INV-2026-0418</h1>"
|
|
45
|
+
"<p>Northwind Analytics Inc., 1200 Market Street, Suite 400, San Francisco, CA 94103. "
|
|
46
|
+
"Bill to Helios Retail Group Ltd., 48 Harbour Road, London EC2V 7HH, United Kingdom.</p>"
|
|
47
|
+
"<p>Issue date: 2026-11-14. Due date: 2026-12-14. Payment terms: Net 30.</p>"
|
|
48
|
+
"<p>Subtotal 26,400.00. Tax (8.5%) 2,244.00. Total due USD 28,644.00.</p>"
|
|
49
|
+
)
|
|
50
|
+
return _html_to_pdf(html)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def main() -> None:
|
|
54
|
+
pdf = make_pdf()
|
|
55
|
+
results: list[str] = []
|
|
56
|
+
with TestClient(app) as http:
|
|
57
|
+
client = Emberleaf(api_key="ef_live_test", base_url="http://testserver", http_client=http, poll_interval=0.2)
|
|
58
|
+
|
|
59
|
+
account = client.account()
|
|
60
|
+
assert account["auth"] == "local", account
|
|
61
|
+
results.append("account")
|
|
62
|
+
|
|
63
|
+
parsed = client.parse(pdf, filename="invoice.pdf")
|
|
64
|
+
assert parsed["pages_count"] == 1 and "INV-2026-0418" in parsed["markdown"], parsed.get("markdown")
|
|
65
|
+
job_id = parsed["job_id"]
|
|
66
|
+
results.append("parse: bytes, async task polled to completion")
|
|
67
|
+
|
|
68
|
+
tmp = Path("/tmp/emberleaf-sdk-test.pdf")
|
|
69
|
+
tmp.write_bytes(pdf)
|
|
70
|
+
assert client.parse(tmp)["pages_count"] == 1
|
|
71
|
+
assert client.parse(io.BytesIO(pdf), filename="invoice.pdf")["pages_count"] == 1
|
|
72
|
+
assert client.parse(job_id=job_id)["cached"] is True
|
|
73
|
+
results.append("parse: path, file object, job_id")
|
|
74
|
+
|
|
75
|
+
accepted = client.parse(pdf, filename="invoice.pdf", wait=False)
|
|
76
|
+
assert accepted["status"] in {"queued", "processing", "completed"} and accepted["task_id"], accepted
|
|
77
|
+
assert client.wait(accepted["task_id"])["pages_count"] == 1
|
|
78
|
+
results.append("wait=False then wait(task_id)")
|
|
79
|
+
|
|
80
|
+
# File contents are checked inside the task, so the error arrives as TaskFailedError.
|
|
81
|
+
try:
|
|
82
|
+
client.parse(b"not a document", filename="notes.txt")
|
|
83
|
+
raise AssertionError("an unsupported file was accepted")
|
|
84
|
+
except BadRequestError as exc:
|
|
85
|
+
assert isinstance(exc, TaskFailedError) and exc.status_code == 415 and exc.code == "unsupported_file_type", exc
|
|
86
|
+
# Wrong parameters are rejected before a task exists: a plain API error with its status.
|
|
87
|
+
try:
|
|
88
|
+
client.parse(pdf, filename="invoice.pdf", precision="ultra") # type: ignore[arg-type]
|
|
89
|
+
raise AssertionError("an unknown precision was accepted")
|
|
90
|
+
except BadRequestError as exc:
|
|
91
|
+
assert exc.status_code == 422 and exc.code == "invalid_request", exc
|
|
92
|
+
try:
|
|
93
|
+
client.parse(job_id="job_does_not_exist")
|
|
94
|
+
raise AssertionError("a missing job was found")
|
|
95
|
+
except NotFoundError as exc:
|
|
96
|
+
assert exc.code == "job_not_found" and isinstance(exc, TaskFailedError) and exc.task_id, exc
|
|
97
|
+
for bad in ({"document": pdf, "job_id": job_id}, {}):
|
|
98
|
+
try:
|
|
99
|
+
client.parse(**bad) # type: ignore[arg-type]
|
|
100
|
+
raise AssertionError(f"accepted {list(bad)}")
|
|
101
|
+
except EmberleafError:
|
|
102
|
+
pass
|
|
103
|
+
results.append("errors: TaskFailedError, 422, 404, bad arguments")
|
|
104
|
+
|
|
105
|
+
# Without model keys, extract answers 503 llm_unavailable synchronously (before any task).
|
|
106
|
+
try:
|
|
107
|
+
client.extract(pdf, schema={"total": "number"}, filename="invoice.pdf")
|
|
108
|
+
raise AssertionError("extract ran without a model")
|
|
109
|
+
except EmberleafError as exc:
|
|
110
|
+
assert getattr(exc, "status_code", None) == 503 and getattr(exc, "code", "") == "llm_unavailable", exc
|
|
111
|
+
results.append("extract: error contract when no model is configured")
|
|
112
|
+
|
|
113
|
+
def refuse(request: httpx.Request) -> httpx.Response:
|
|
114
|
+
raise httpx.ConnectError("connection refused", request=request)
|
|
115
|
+
|
|
116
|
+
offline = Emberleaf(api_key="k", base_url="http://offline", http_client=httpx.Client(transport=httpx.MockTransport(refuse)), max_retries=1)
|
|
117
|
+
try:
|
|
118
|
+
offline.account()
|
|
119
|
+
raise AssertionError("no error while offline")
|
|
120
|
+
except ConnectionFailedError:
|
|
121
|
+
results.append("connection errors retried, then ConnectionFailedError")
|
|
122
|
+
|
|
123
|
+
os.environ.pop("EMBERLEAF_API_KEY", None)
|
|
124
|
+
try:
|
|
125
|
+
Emberleaf()
|
|
126
|
+
raise AssertionError("created a client without a key")
|
|
127
|
+
except EmberleafError:
|
|
128
|
+
results.append("missing key is reported at once")
|
|
129
|
+
|
|
130
|
+
for line in results:
|
|
131
|
+
print(f" PASS {line}")
|
|
132
|
+
print(f"\n{len(results)}/{len(results)} SDK checks passed")
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
if __name__ == "__main__":
|
|
136
|
+
main()
|