Update README and bump version to 1.2.0

README.md

@@ -1,254 +1,157 @@
 # Mistral OCR CLI
 
+[![CI](https://github.com/r-uben/mistral-ocr-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/r-uben/mistral-ocr-cli/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/mistral-ocr-cli.svg)](https://badge.fury.io/py/mistral-ocr-cli)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A powerful command-line tool for OCR processing using Mistral AI's state-of-the-art OCR API. Process PDFs and images to extract text, tables, equations, and images with unprecedented accuracy.
+A command-line tool for OCR processing using Mistral AI's OCR API. Process PDFs and images to extract text, tables, equations, and images.
 
-## ⚠️ Disclaimer
-
-**This is an unofficial, community-created tool** that uses Mistral AI's OCR API. This project is not affiliated with, officially maintained, or endorsed by Mistral AI.
-
-- **Official Mistral OCR**: https://mistral.ai/news/mistral-ocr
-- **Official Documentation**: https://docs.mistral.ai/capabilities/OCR/
-- **Mistral AI Platform**: https://console.mistral.ai/
-
-For official tools and support, please visit [Mistral AI's website](https://mistral.ai).
-
-## Features
-
-- 📄 **Multi-format Support**: Process PDFs and images (JPG, PNG, WEBP, GIF, BMP, TIFF)
-- 📊 **Advanced Extraction**: Extract text, tables, equations, and images
-- 📁 **Batch Processing**: Process single files or entire directories
-- 🎯 **Smart Output**: Preserves document structure in markdown format
-- 🖼️ **Image Extraction**: Optionally extract and save embedded images
-- 📈 **Progress Tracking**: Real-time progress bars for batch operations
-- 🔧 **Flexible Configuration**: Environment variables or command-line options
+> **Disclaimer:** This is an unofficial, community-created tool. Not affiliated with or endorsed by [Mistral AI](https://mistral.ai). For official tools, see the [Mistral OCR docs](https://docs.mistral.ai/capabilities/OCR/).
 
 ## Installation
 
-### Prerequisites
-
-- Python 3.9 or higher
-- Mistral API key from [Mistral Console](https://console.mistral.ai/)
-
-### Install from PyPI (Recommended)
+Requires Python 3.11+ and a [Mistral API key](https://console.mistral.ai/).
 
 ```bash
 pip install mistral-ocr-cli
 ```
 
-### Install from Source
+Or from source:
 
 ```bash
-# Clone the repository
 git clone https://github.com/r-uben/mistral-ocr-cli.git
 cd mistral-ocr-cli
-
-# Install with Poetry
-poetry install
-
-# Or with pip
-pip install -e .
-```
-
-## Configuration
-
-### 1. Set up your Mistral API key
-
-Create a `.env` file in your project root (or copy from `.env.example`):
-
-```bash
-cp .env.example .env
-```
-
-Edit `.env` and add your API key:
-
-```env
-MISTRAL_API_KEY=your_actual_api_key_here
+uv sync
 ```
 
-### 2. Alternative: Export as environment variable
+## Quick start
 
 ```bash
-export MISTRAL_API_KEY="your_actual_api_key_here"
-```
-
-## Usage
-
-### Basic Usage
-
-Process a single PDF file (output saved to `mistral_ocr_output/` in the same directory):
+# Set your API key
+export MISTRAL_API_KEY="your_key_here"
 
-```bash
+# Process a single file
 mistral-ocr document.pdf
-```
 
-### Specify Output Directory
-
-```bash
-mistral-ocr document.pdf --output-path ./results
-```
+# Process a directory
+mistral-ocr ./documents --output-path ./results
 
-### Process Entire Directory
+# Preview what would be processed (no API calls)
+mistral-ocr ./documents --dry-run
 
-```bash
-mistral-ocr ./documents --output-path ./extracted
+# Process 4 files concurrently
+mistral-ocr ./documents --workers 4
 ```
 
-### Command-Line Options
+## Options
 
 ```
 Usage: mistral-ocr INPUT_PATH [OPTIONS]
 
 Arguments:
-  INPUT_PATH                  Path to input file or directory (required)
+  INPUT_PATH                        Path to input file or directory (required)
 
 Options:
-  -o, --output-path PATH      Output directory (default: <input_dir>/mistral_ocr_output/)
-  --api-key TEXT             Mistral API key (or set MISTRAL_API_KEY env var)
-  --model TEXT               OCR model (default: mistral-ocr-latest)
-  --env-file PATH            Path to .env file
-  --include-images/--no-images  Extract images (default: True)
-  -v, --verbose              Enable verbose output
-  --version                  Show version
-  --help                     Show this message
-```
+  -o, --output-path PATH            Output directory (default: <input_dir>/mistral_ocr_output/)
+  --api-key TEXT                    Mistral API key (or set MISTRAL_API_KEY env var)
+  --model TEXT                      OCR model (default: mistral-ocr-latest)
+  --env-file PATH                   Path to .env file
 
-## Examples
+  --include-images/--no-images      Extract embedded images (default: True)
+  --save-originals/--no-save-originals  Copy original files to output (default: True)
+  --metadata/--no-metadata          Include markdown header block (default: True)
+  --page-headings/--no-page-headings  Include "## Page N" headings (default: True)
 
-### Process a single image
+  --table-format [markdown|html]    Extract tables separately (OCR 3+)
+  --extract-headers/--no-extract-headers  Extract page headers (OCR 3+)
+  --extract-footers/--no-extract-footers  Extract page footers (OCR 3+)
 
-```bash
-mistral-ocr photo.jpg
+  -w, --workers N                   Concurrent workers for batch processing (default: 1)
+  --reprocess                       Reprocess already-processed files
+  --add-timestamp/--no-timestamp    Timestamp output folder name (default: False)
+  --dry-run                         List files without calling the API
+  -q, --quiet                       Suppress all output except errors
+  -v, --verbose                     Enable verbose/debug output
+  --log-file PATH                   Write logs to file
+  --version                         Show version
+  --help                            Show this message
 ```
 
-### Process multiple PDFs with custom output
-
-```bash
-mistral-ocr ./reports --output-path ./extracted_text --verbose
-```
-
-### Use a different .env file
-
-```bash
-mistral-ocr document.pdf --env-file .env.production
-```
-
-### Process without extracting images
-
-```bash
-mistral-ocr document.pdf --no-images
-```
-
-### Pass API key directly (not recommended for production)
-
-```bash
-mistral-ocr doc.pdf --api-key "your_api_key_here"
-```
-
-## Output Structure
-
-The tool creates the following output structure:
+## Output structure
 
 ```
 mistral_ocr_output/
-├── document1.md           # Extracted text in markdown format
-├── document1_images/      # Extracted images (if enabled)
-│   ├── page1_img1.png
-│   └── page1_img2.png
-├── document2.md
-├── document2_images/
+├── document_name/
+│   ├── document_name.pdf       # original copy (if --save-originals)
+│   ├── document_name.md        # OCR markdown
+│   ├── figures/                # extracted images
+│   │   ├── page1_img1.png
+│   │   └── page2_img1.png
+│   └── tables/                 # extracted tables (if --table-format)
+│       └── page1_table1.md
+├── another_document/
 │   └── ...
-└── metadata.json         # Processing statistics and errors
+└── metadata.json               # processing stats, file list, errors
 ```
 
-### Markdown Output
-
-Each processed document generates a markdown file containing:
-- Document metadata (source, processing time)
-- Extracted text with preserved formatting
-- Tables rendered in markdown format
-- Mathematical equations
-- Image references (if image extraction is enabled)
-
-### Metadata File
-
-The `metadata.json` file contains:
-- List of processed files
-- Processing time
-- File sizes
-- Output paths
-- Any errors encountered
-
-## Limitations
-
-- Maximum file size: 50 MB
-- Maximum pages per document: 1,000
-- Supported formats: PDF, JPG, JPEG, PNG, WEBP, GIF, BMP, TIFF
+Use `--no-metadata` and `--no-page-headings` for cleaner markdown output without the header block and page separators.
 
-## Pricing
+## Configuration
 
-Mistral OCR API pricing: $1 per 1,000 pages ($0.001 per page)
+All CLI options can also be set via environment variables or a `.env` file:
+
+| CLI flag | Environment variable | Default |
+|----------|---------------------|---------|
+| `--api-key` | `MISTRAL_API_KEY` | (required) |
+| `--model` | `MISTRAL_MODEL` | `mistral-ocr-latest` |
+| `--include-images` | `INCLUDE_IMAGES` | `true` |
+| `--save-originals` | `SAVE_ORIGINAL_IMAGES` | `true` |
+| `--metadata` | `INCLUDE_METADATA` | `true` |
+| `--page-headings` | `INCLUDE_PAGE_HEADINGS` | `true` |
+| `--table-format` | `TABLE_FORMAT` | (none) |
+| `--extract-headers` | `EXTRACT_HEADER` | `false` |
+| `--extract-footers` | `EXTRACT_FOOTER` | `false` |
+| `--workers` | `MAX_WORKERS` | `1` |
+| `--verbose` | `VERBOSE` | `false` |
+| | `MAX_FILE_SIZE_MB` | `50` |
+| | `MAX_RETRIES` | `3` |
+| | `RETRY_BASE_DELAY` | `1.0` |
+
+CLI flags override environment variables when explicitly passed.
 
 ## Development
 
-### Run tests
-
 ```bash
-poetry run pytest
-```
+# Install dev dependencies
+uv sync --extra dev
 
-### Format code
+# Run tests
+uv run pytest
 
-```bash
-poetry run black mistral_ocr/
-poetry run ruff check mistral_ocr/
-```
+# Lint
+uv run ruff check .
 
-### Type checking
+# Format
+uv run ruff format .
 
-```bash
-poetry run mypy mistral_ocr/
+# Type check
+uv run mypy mistral_ocr/ --ignore-missing-imports
 ```
 
-## Troubleshooting
-
-### API Key Not Found
-
-If you get an error about missing API key:
-1. Ensure `.env` file exists and contains `MISTRAL_API_KEY=your_key`
-2. Or export it: `export MISTRAL_API_KEY="your_key"`
-3. Or pass it directly: `mistral-ocr --api-key "your_key" ...`
-
-### File Size Error
+## Limitations
 
-If a file exceeds 50 MB:
-- Consider splitting large PDFs into smaller parts
-- Compress images before processing
+- Maximum file size: 50 MB (configurable via `MAX_FILE_SIZE_MB`)
+- Supported formats: PDF, DOCX, PPTX, JPG, JPEG, PNG, WEBP, GIF, BMP, TIFF
 
-### Installation Issues
+## Pricing
 
-If the command is not found after installation:
-1. Ensure the package is installed: `pip show mistral-ocr`
-2. Check your PATH includes pip's script directory
-3. Try reinstalling with: `pip install -e .`
+Mistral OCR API: ~$1 per 1,000 pages. See [Mistral pricing](https://mistral.ai/products/pricing/) for current rates.
 
 ## License
 
-MIT License - see LICENSE file for details
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Support
-
-For issues or questions about this CLI tool, please open an issue on [GitHub](https://github.com/r-uben/mistral-ocr-cli/issues)
-
-For questions about Mistral AI's OCR API, please refer to [Mistral's official documentation](https://docs.mistral.ai) or contact their support.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ## Legal
 
-"Mistral AI" and "Mistral" are trademarks of Mistral AI. This project is not affiliated with or endorsed by Mistral AI. The use of Mistral AI's OCR API is subject to Mistral AI's [Terms of Service](https://mistral.ai/terms/).
+"Mistral AI" and "Mistral" are trademarks of Mistral AI. This project is not affiliated with or endorsed by Mistral AI. Use of Mistral AI's OCR API is subject to Mistral AI's [Terms of Service](https://mistral.ai/terms/).

mistral_ocr/__init__.py

@@ -1,6 +1,6 @@
 """Mistral OCR CLI - A clean command-line tool for OCR processing using Mistral AI."""
 
-__version__ = "1.1.1"
+__version__ = "1.2.0"
 __author__ = "Ruben Fernandez-Fuertes"
 
 from .config import Config

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mistral-ocr-cli"
-version = "1.1.1"
+version = "1.2.0"
 description = "A clean command-line tool for OCR processing using Mistral AI's API"
 authors = [{name = "Ruben Fernandez-Fuertes", email = "fernandezfuertesruben@gmail.com"}]
 readme = "README.md"

tests/test_import.py

@@ -25,4 +25,4 @@ def test_version():
     """Test that version is defined."""
     from mistral_ocr import __version__
 
-    assert __version__ == "1.1.1"
+    assert __version__ == "1.2.0"