From cdc7897b610b81601adc2df2b4f8dd4e15769255 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ruben=20Fern=C3=A1ndez-Fuertes?= Date: Wed, 11 Mar 2026 14:13:12 +0100 Subject: [PATCH] Update README for current features and bump version to 1.2.0 - Rewrite README: fix badges, document all new flags, update output structure, replace Poetry with uv, add config env var table - Bump version 1.1.1 -> 1.2.0 (new features: concurrent workers, markdown output flags, quiet/dry-run fixes, config validation) --- README.md | 275 +++++++++++++--------------------------- mistral_ocr/__init__.py | 2 +- pyproject.toml | 2 +- tests/test_import.py | 2 +- 4 files changed, 92 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index 3290070..9b9e94b 100644 --- a/README.md +++ b/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: /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: /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/). \ No newline at end of file +"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/). diff --git a/mistral_ocr/__init__.py b/mistral_ocr/__init__.py index f1be723..de27090 100644 --- a/mistral_ocr/__init__.py +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 36ec42e..4613a9e 100644 --- a/pyproject.toml +++ b/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" diff --git a/tests/test_import.py b/tests/test_import.py index 89ca3ba..c0c4df6 100644 --- a/tests/test_import.py +++ b/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"