Metadata-Version: 2.5
Name: kes-tools-sdk
Version: 0.1.1
Summary: Python SDK for kes-tools: turn PDFs and Kurzweil 3000 .kes files into .kes files with Datalab OCR
Project-URL: Website, https://dbqmri38t4eq6.cloudfront.net
Project-URL: Documentation, https://dbqmri38t4eq6.cloudfront.net/developers
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: keyring
Requires-Dist: keyring>=24; extra == 'keyring'
Description-Content-Type: text/markdown

# kes-tools-sdk

Python SDK for the [kes-tools website](https://dbqmri38t4eq6.cloudfront.net), which turns PDFs and Kurzweil 3000 `.kes` files into `.kes` files with OCR, layout and reading order from [Datalab](https://www.datalab.to), tuned so Kurzweil reads whole sentences.

Conversions run on the kes-tools website with your account and the Datalab API key you set up there, so they are billed to your Datalab account. For the command line, install [kes-tools](https://pypi.org/project/kes-tools/) instead, which is built on this package.

## Install

```bash
pip install kes-tools-sdk                 # or: uv add kes-tools-sdk
pip install 'kes-tools-sdk[keyring]'      # to store a sign-in in the system keychain with Client.login()
```

Python 3.9 or newer, on Windows, macOS and Linux. Only depends on `httpx`.

## Sign in

The SDK needs a kes-tools sign-in, as a refresh token:

- If you use the CLI, `kes-tools login` stores one in the system keychain, and `Client()` finds it there (with the `keyring` extra installed).
- On servers and in CI, set `KES_TOOLS_REFRESH_TOKEN` (from `kes-tools login --export`) or pass `Client(refresh_token=...)`. This needs no keyring.
- `Client().login()` signs in from Python through the browser and stores the result in the keychain.

## Use

```python
from kes_tools import Client

with Client() as client:
    for result in client.convert(["book.pdf", "chapter.kes"], output="converted"):
        print(result.file, "->", result.output if result.ok else result.error)
```

`Client()` uses the sign-in from `kes-tools login` (or `$KES_TOOLS_REFRESH_TOKEN`); pass `refresh_token=` to use another one, and `url=` for another deployment. `client.login()` signs in from Python, through the browser.

| Method | Does |
|---|---|
| `convert(files, output=".", mode="balanced", image="color", timeout=3600, overwrite=False, wait=True, progress=None)` | Uploads, waits and downloads; returns a `ConversionResult` per file (`file`, `job`, `output`, `error`, `ok`). A file that fails gets `error` instead of raising. With `wait=False` it only uploads and starts. |
| `submit(path, mode, image)` | Uploads one file and starts it; returns its `Job`. |
| `wait(jobs, timeout=3600)` | Waits until the jobs are done or failed; returns the `Job`s. |
| `download(job, folder=".", overwrite=False)` | Saves a done job's result; returns its path. |
| `jobs(status=None)`, `job(job)` | Your conversions, newest first, or one of them. |
| `delete(jobs)` | Deletes conversions and their files; returns how many. |
| `account()` | `Account(email, has_datalab_key, key_hint)`. |

The full reference is at https://dbqmri38t4eq6.cloudfront.net/docs/sdk/kes_tools.html.

A `Job` has `id`, `status` (`awaiting_upload`, `queued`, `processing`, `done` or `failed`), `filename`, `kind`, `mode`, `image`, `pages`, `cost_cents`, `error` and `created_at`, plus `running`, `done` and `failed`. Jobs and files can be passed as objects or ids and paths.

Errors derive from `KesToolsError`: `AuthError` (not signed in, or the sign-in expired), `ApiError` (with `status`) and `MissingDatalabKey` (add the key in Settings on the website). The package is typed.

## License

Apache License 2.0. The full text is in the LICENSE file included in the package.
