emberleaf 0.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -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
+ ]
emberleaf/client.py ADDED
@@ -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
emberleaf/errors.py ADDED
@@ -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)
emberleaf/py.typed ADDED
File without changes
@@ -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,8 @@
1
+ emberleaf/__init__.py,sha256=90BIRvLJTPsb7flGYTHCib5Wi4Q5ZM1kNf4Wrb9yFsc,711
2
+ emberleaf/client.py,sha256=tGP0wcviT1bt9QuaaT1cMG-PpGfMvO0s80RilAAdGFM,12140
3
+ emberleaf/errors.py,sha256=hGUqHhqZ1bDdQ9JX0FjOOWhg-zVyRrB-nmVdRhKogzg,4613
4
+ emberleaf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ emberleaf-0.1.0.dist-info/METADATA,sha256=ltzSxa_sWVDnsdKAJ1MRyjCGu3vgBMU4y5OoB0oznVI,6974
6
+ emberleaf-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
7
+ emberleaf-0.1.0.dist-info/licenses/LICENSE,sha256=QjJ0HP0wqrtYQxcp5TmS18hY0Us_Gmqt4U_iIiPZin4,1066
8
+ emberleaf-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.27.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.