Metadata-Version: 2.4
Name: caia-convert
Version: 0.1.0
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
caia <file>                   list valid targets for that file and pick one
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
  --outdir <dir>  output directory (filename keeps the input's name)
  -- <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
```

## 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

- **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).
