Metadata-Version: 2.4
Name: caia-convert
Version: 0.1.2
Summary: Convert Any file Into Anything - one command to convert files between formats, a dispatcher over Docling, Calibre, MarkItDown, faster-whisper, FFmpeg and ImageMagick.
Project-URL: Homepage, https://github.com/yhigorrr/caia
Project-URL: Repository, https://github.com/yhigorrr/caia
Project-URL: Issues, https://github.com/yhigorrr/caia/issues
Author: Gordon
License-Expression: MIT
License-File: LICENSE
Keywords: cli,convert,docling,ebook,ffmpeg,markdown,ocr,pdf,whisper
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# caia

**C**onvert **A**ny file **I**nto **A**nything. 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](#requirements)). `caia --list` shows what's found and what's missing,
and **`caia setup` installs the missing ones for you** (see [Getting the engines](#getting-the-engines)).

## Install

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

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

**As an ordinary package (what others do):**

```bash
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:

```bash
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
```

```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](src/caia/recipes.py) - changes apply live.
2. **No source edit:** add a `[[recipes]]` block to your config (`caia --config`).

```python
{
    "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).
