caia-convert 0.1.2

Convert Any file Into Anything - one command to convert files between formats, a dispatcher over Docling, Calibre, MarkItDown, faster-whisper, FFmpeg and ImageMagick.

caia

Convert Any file Into Anything. One command to convert files between formats. You run it, you get the output. All the actual tool commands live in one editable registry, so you never have to remember another ffmpeg/docling/calibre incantation.

caia file.pdf --to md           # PDF -> Markdown
caia file.pdf                    # no target? lists everything .pdf can become, then pick
caia --list                      # the whole capability matrix + which tools are installed
caia book.epub --to pdf
caia talk.mp3 --to txt           # audio -> transcript (faster-whisper)
caia clip.mp4 --to gif
caia photo.png --to jpg --out thumb.jpg

caia itself is a tiny pure-Python dispatcher (no dependencies). It doesn't convert anything - it finds the real tool for input -> target, runs it, and prints the exact command so you passively re-learn the incantations. The conversions it drives:

Engine	Used for
Docling	PDF -> md / json / txt / html / yaml / docx; image OCR -> md
Calibre (ebook-convert)	EPUB -> pdf / docx / txt / htmlz / azw3 / mobi / md
MarkItDown	docx / pptx / xlsx / html -> md
faster-whisper (via uvx)	audio & video -> txt / srt / vtt / json
FFmpeg	video/audio -> mp3 / wav / gif / mp4
ImageMagick	image -> jpg / png / webp / pdf

The converters are external programs, not pip dependencies - install the ones you need (see Requirements). caia --list shows what's found and what's missing, and caia setup installs the missing ones for you (see Getting the engines).

Install

For yourself, globally (recommended) — editable so recipe edits apply live:

uv tool install --editable .        # global `caia` command, on PATH
# or:  pipx install --editable .

As an ordinary package (what others do):

pip install caia-convert             # from PyPI  (the command is still `caia`)
uv tool install caia-convert
pip install .                        # from a clone of this folder
pip install "git+https://github.com/yhigorrr/caia.git"   # straight from GitHub

Either way you get a caia command. The PyPI/distribution name is caia-convert (the short name was too close to existing packages); what you type is always caia. (Requires Python >= 3.11 for stdlib tomllib.)

Getting the engines

caia drives external programs - it doesn't bundle them (they're large and most people want a subset). After installing caia, run:

caia doctor      # report which engines are present / missing
caia setup       # install the missing ones, with confirmation

caia setup uses uv tool install for the Python engines (Docling, MarkItDown), winget for the native ones (FFmpeg, ImageMagick, Calibre) on Windows, and automatically wires Calibre's off-PATH ebook-convert into your config. Flags: --yes (no prompt), --dry-run (show the plan only). On non-Windows it prints the manual install hints. You only need the engines for the conversions you actually use.

Configuration

The package ships with no machine-specific paths. Tools are found on your PATH. Anything off-PATH (commonly Calibre on Windows) or any custom recipe goes in your user config - run caia --config to see its location and a template:

Windows:  %APPDATA%\caia\config.toml
else:     ~/.config/caia/config.toml

[tools]
# Only list tools NOT on your PATH:
ebook-convert = "C:/Program Files/Calibre2/ebook-convert.exe"
# markitdown  = ["C:/path/.venv/Scripts/python.exe", "-m", "markitdown"]
# pandoc      = "pandoc"                  # add an entirely new tool

[[recipes]]                              # extra/override recipes (yours win on ties)
src = "pdf"
dst = "md"
tool = "docling"
cmd = "{docling} convert {in} --to md --output {outdir}"
produces = "{stem}.md"
desc = "PDF -> Markdown (Docling)"

Usage

caia <file> --to <fmt>        convert one file
caia <file>                   list valid targets for that file and pick one
caia *.pdf --to md            convert many (glob or several paths)
caia <folder> --to md         convert every convertible file in a folder
caia --list                   show every conversion and tool status
caia --config                 show the user config path + a template
caia --version | -h

  --to <fmt>          target format (md, pdf, txt, jpg, mp3, ...)
  --tool <name>       force a specific tool when several can do the job
  --out <path>        exact output file path (single input only)
  --outdir <dir>      output directory (filename keeps the input's name)
  -r, --recursive     recurse into sub-folders (folder inputs)
  --delete-original   after a verified conversion, offer to trash the source(s)
  --yes               skip confirmation prompts
  -- <args...>        everything after -- is passed straight to the underlying tool

Output lands next to the input by default. Ad-hoc tool flags via --:

caia clip.mp4 --to mp4 -- -crf 20        # tighter compression
caia talk.mp3 --to txt -- --model medium # bigger whisper model for accuracy

Batch conversion

Pass a glob, a folder, or several paths. --to is required for multiple inputs. caia expands globs itself (Windows shells pass *.pdf through literally):

caia *.docx --to md                 # every .docx here
caia ./scans --to md -r             # a folder, recursively
caia a.png b.png c.png --to webp    # explicit list

Each file converts independently; you get a 2/3 converted summary. Inputs whose output would collide (same target name) or overwrite another input's source are skipped, not clobbered.

Deleting originals

--delete-original offers, after each conversion is verified (output exists and is non-empty), to move the source file(s) to the OS trash - recoverable (Windows Recycle Bin, macOS Finder Trash, Linux gio/trash-cli). It's opt-in, asks first (use --yes to skip the prompt), never deletes a source whose conversion failed or whose output was skipped, and if no trash mechanism exists it keeps everything rather than hard-deleting.

caia *.png --to webp --delete-original      # convert, then confirm trashing the .png's

Most conversions are lossy (pdf→md drops layout, mp4→gif, wav→mp3), so the trash-not-delete default is the safety net if a conversion isn't what you wanted.

Adding a conversion

Two ways, same schema:

1. Editable install: edit src/caia/recipes.py - changes apply live.
2. No source edit: add a [[recipes]] block to your config (caia --config).

{
    "src":  "pdf",                 # input extension, or a list of extensions
    "dst":  "md",                  # what you type after --to
    "tool": "docling",             # primary tool (drives the --list availability check)
    "cmd":  "{docling} convert {in} --to md --output {outdir}",
    "produces": "{stem}.md",       # filename the tool writes into {outdir} (omit if cmd uses {out})
    "desc": "PDF -> Markdown (Docling)",
}

Placeholders: {in} {out} {outdir} {stem} {tmpdir} and tool names like {docling} {ebook-convert} {ffmpeg} (plus any tool you define in config [tools]). Multi-step jobs use "steps": ["...", "..."] with {tmpdir} for intermediates - see the epub -> md and video -> txt recipes.

Requirements

External tools, installed however you like (caia just needs them on PATH or in config):

• Docling - pip install docling
• MarkItDown - uv tool install 'markitdown[all]'
• Calibre - provides ebook-convert (off-PATH on Windows -> add to config)
• FFmpeg, ImageMagick - via your package manager / winget
• uv - so caia can run faster-whisper through uvx (no whisper install needed)

Layout

pyproject.toml         # packaging (hatchling, console-script entry point `caia`)
src/caia/
  cli.py               # the dispatcher: resolve tools, pick recipe, run it
  recipes.py           # the built-in registry (BUILTIN_RECIPES)
  config.py            # user config loading + tool resolution
  __main__.py          # `python -m caia`

Notes

• FFmpeg conversions default to high quality, not small files: MP4 crf 18 (visually lossless), MP3 320k, WAV lossless at the source rate, GIF via a 2-pass palette. Want a smaller file? Override per run, e.g. caia clip.mp4 --to mp4 -- -crf 28. (Recipes put {args} before the output so ffmpeg actually honours the override.)
• Whisper runs on CPU with int8 (--device cpu --compute_type int8) by default, since GPU needs a CUDA cublas library. First run downloads the base model (~145 MB), then it's cached. Override per run: -- --model medium.
• Child Python tools run with PYTHONUTF8=1 so non-Latin output doesn't crash the Windows cp1252 console.
• Web -> Markdown (Jina / Firecrawl) is sketched as commented stubs in recipes.py but not wired up yet (URLs aren't files).