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.
@@ -0,0 +1,18 @@
1
+ # Secrets: never commit keys
2
+ *.env
3
+ .env
4
+ .env.*
5
+ !.env.example
6
+ *.local
7
+ *api key*.txt
8
+ *secret*.txt
9
+
10
+ # OS / editors
11
+ .DS_Store
12
+ Thumbs.db
13
+ .vscode/
14
+ .idea/
15
+
16
+ # Local tooling
17
+ .claude/
18
+ node_modules/
@@ -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.
@@ -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()