Metadata-Version: 2.5
Name: kes-tools
Version: 0.2.0
Summary: Command-line tool for kes-tools: turn PDFs and Kurzweil 3000 .kes files into .kes files with Datalab OCR
Project-URL: Website, https://dbqmri38t4eq6.cloudfront.net
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: kes-tools-sdk<0.2,>=0.1
Requires-Dist: keyring>=24
Description-Content-Type: text/markdown

# kes-tools

Command-line tool 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.

## Install

```bash
uv tool install kes-tools        # or: pipx install kes-tools
```

Or run it without installing: `uvx kes-tools …`. Works on Windows, macOS and Linux with Python 3.9 or newer.

## Sign in

```bash
kes-tools login
```

This opens your browser to sign in with your kes-tools account (email and password, or Google). The sign-in is kept in your system's keychain (macOS Keychain, Windows Credential Manager or the Linux Secret Service) and lasts a year. `kes-tools logout` signs out.

On a machine without a browser or keychain, such as a server or CI job, run `kes-tools login --export` on your own computer, store the printed token as a secret, and set it as `KES_TOOLS_REFRESH_TOKEN` where the CLI runs. Anyone with that token can use your account until it expires or you run `kes-tools logout`.

## Use

```bash
kes-tools convert book.pdf chapter*.kes -o converted/   # upload, wait and download the results
kes-tools convert --no-wait *.pdf                        # only start the conversions
kes-tools jobs                                           # list your conversions
kes-tools download JOB_ID … -o converted/                # download finished conversions
kes-tools delete JOB_ID …                                # delete conversions and their files
kes-tools whoami                                         # who is signed in, and whether a Datalab key is set up
```

`convert` takes `--mode fast|balanced|accurate` (Datalab's mode, default `balanced`) and, for `.kes` files, `--image color|bitmap` (send the colour scan or the black-and-white text bitmap). Wildcards like `*.pdf` work in every shell, including PowerShell and cmd. Files are converted one at a time on the server; existing files in the output folder are kept and the new one gets " (2)" unless you pass `--overwrite`.

Every command takes `--json` for machine-readable output. Exit codes: `0` success, `1` a conversion or download failed, `2` wrong arguments or files, `3` not signed in or the sign-in expired.

`--url` or `KES_TOOLS_URL` points the CLI at another deployment of kes-tools.

## From Python

The Python SDK is a separate package, [kes-tools-sdk](https://pypi.org/project/kes-tools-sdk/), which this tool is built on: `pip install kes-tools-sdk`, then `from kes_tools import Client`. It uses the same sign-in.

## License

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