Content
# Universal AI Converter
Convert documents, images, audio, and video into Markdown or structured JSON. The core is agent-agnostic: use it from a terminal, Python, an HTTP API, an MCP-compatible AI agent, Docker, or your own application.
## One-command Codex installation
The installer creates an isolated environment, installs all conversion features, installs the Codex plugin, and enables automatic file routing.
Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.ps1 | iex
```
macOS or Linux:
```bash
curl -fsSL https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.sh | sh
```
Requirements: Python 3.10+ and Codex. Restart Codex and open a new task after installation. Attach a file and ask a normal question; the plugin selects the converter automatically.
FFmpeg and Tesseract are system programs. The Python features are installed automatically, while the installer reports any missing system executable when that format is first used.
## Why it is portable
- No dependency on Codex, ChatGPT, Claude, or a specific LLM.
- A stable Python API and command-line interface form the core.
- MCP is an optional adapter for compatible agents.
- HTTP is an optional adapter for everything else.
- Heavy document, OCR, and speech dependencies are installed only when needed.
## Install
Python 3.10 or newer is required.
```bash
pip install universal-ai-converter
pip install "universal-ai-converter[documents]"
pip install "universal-ai-converter[ocr]"
pip install "universal-ai-converter[media]"
pip install "universal-ai-converter[all]"
```
Until the first PyPI release, install directly from GitHub:
```bash
pip install "universal-ai-converter[all] @ git+https://github.com/KOLRNCH/Universal-AI-Converter.git"
```
OCR additionally requires the Tesseract executable. Video additionally requires FFmpeg. Both must be available in `PATH`.
For development from this repository:
```bash
python -m venv .venv
pip install -e ".[dev]"
pytest
```
## Command line
```bash
uac convert report.pdf -o report.md
uac convert interview.mp4 -o transcript.md --whisper-model small
uac convert scan.png --format json -o result.json
```
## Python
```python
from universal_ai_converter import Converter
result = Converter().convert("report.pdf")
print(result.text)
```
## HTTP API
```bash
pip install "universal-ai-converter[api,documents]"
uac serve --host 127.0.0.1 --port 8765
curl -F "file=@report.pdf" http://127.0.0.1:8765/convert
```
## Any MCP-compatible agent
```bash
pip install "universal-ai-converter[mcp,documents]"
uac-mcp
```
Register `uac-mcp` as a stdio MCP server in the agent's configuration. The agent receives a `convert_file` tool. Exact configuration differs between clients, so examples for popular agents will live in `docs/integrations/`.
See the [generic MCP setup](docs/integrations/mcp.md) for a reusable configuration example.
## Docker
```bash
docker build -t universal-ai-converter .
docker run --rm -p 127.0.0.1:8765:8765 universal-ai-converter
```
Then upload a file to `http://127.0.0.1:8765/convert`. Model files downloaded by faster-whisper should be mounted in a persistent cache for repeated media conversions.
## Format routing
| Input | Backend |
|---|---|
| PDF, DOCX, PPTX, XLSX, HTML, EPUB, ZIP, MSG | MarkItDown |
| PNG, JPEG, TIFF, WebP | Tesseract OCR |
| MP3, WAV, M4A, FLAC, OGG | faster-whisper |
| MP4, MKV, MOV, WebM, AVI | FFmpeg + faster-whisper |
| TXT, Markdown, CSV, JSON, XML, YAML | Built-in text reader |
## Security
The HTTP server binds to localhost by default. Conversion libraries process untrusted files, so public deployments should run in an isolated container with file-size, time, CPU, and memory limits. Do not expose the development server directly to the internet.
## Roadmap
- Plugin entry points for third-party converters
- Recursive archives and batch conversion
- URL and YouTube adapters
- Docker image and cross-platform desktop app
- Configurable OCR languages and timestamped transcripts
- Sandboxed production worker
## License
MIT
