Metadata-Version: 2.4
Name: stratum-client
Version: 0.1.0
Summary: Official Python client for the Stratum document-chunking API.
Project-URL: Homepage, https://github.com/Pleias/stratum/tree/main/clients/python
Project-URL: Repository, https://github.com/Pleias/stratum
Project-URL: Issues, https://github.com/Pleias/stratum/issues
Author: Pleias
License: Apache-2.0
License-File: LICENSE
Keywords: api,chunking,client,documents,rag,stratum
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.25
Provides-Extra: test
Requires-Dist: pytest-httpx>=0.30; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# stratum-client (Python)

Official Python client for the Stratum document-chunking API.

```bash
pip install stratum-client
```

## Quick start

```python
from stratum_client import Client, JobConfig

client = Client(api_key="stratum_xxxxxxxx_...")  # or set STRATUM_API_KEY

job = client.submit_job(
    "report.pdf",
    config=JobConfig(target_size=500, enrichments=["summary"]),
)
result = client.wait_for_job(job.id)

for chunk in result["chunks"]:
    print(chunk["text"])
```

## Client

```python
Client(
    api_key: str | None = None,           # falls back to $STRATUM_API_KEY
    base_url: str = "https://api-stratum.pleias.dev",
    timeout: float = 60.0,
)
```

Methods:

| Method                                                             | Description                                                         |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `healthz()` / `readyz()`                                           | Liveness / readiness probes                                         |
| `submit_job(file, *, config=None, project_id=None)`                | Upload a document and create a job                                  |
| `get_job(job_id)`                                                  | Fetch a single job                                                  |
| `list_jobs(*, page=1, page_size=20, status=None, project_id=None)` | Paginated job list                                                  |
| `iter_jobs(*, page_size=50, status=None, project_id=None)`         | Iterate every job, auto-paging                                      |
| `get_job_result(job_id)`                                           | Download the chunker output (dict matching `docs/output-format.md`) |
| `cancel_job(job_id)`                                               | Delete a job and its storage artifacts                              |
| `wait_for_job(job_id, *, poll_interval=2.0, timeout=None)`         | Poll until done; returns the result                                 |

`Client` is also a context manager: `with Client(...) as c: ...`.

## Errors

All errors derive from `StratumError`:

- `AuthenticationError` (401/403)
- `NotFoundError` (404)
- `JobNotCompleteError` (409 — result requested before job finished)
- `ApiError` (other non-2xx)
- `JobFailedError` (raised by `wait_for_job` when the job ends in `failed`)
