kes-tools-sdk

Python SDK for the kes-tools website, which turns PDFs and Kurzweil 3000 .kes files into .kes files with OCR, layout and reading order from Datalab, 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 instead, which is built on this package.

Install

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

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.

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.