Skip to content

mistral-ocr

Verbatim OCR of PDFs and images using Mistral's vision model - ImageMagick conversion at 300 DPI, per-page transcription, QA flags, OCR_Log row. Use when the user requests Mistral-based OCR for verbatim transcription (legal documents, contracts) or as secondary validation after the okf-ocr pipeline. Pairs with verbatim-ocr (QA) and okf-ocr (canonical pipeline).

Source: .opencode/skills/mistral-ocr/SKILL.md — site rebuilt 2026-09-05.

mistral-ocr

Mistral OCR — PDF/Image to Verbatim Text

When to Run

  • User requests OCR of a PDF or image using Mistral's vision model.
  • Verbatim transcription is required (legal documents, contracts, or precise text extraction).
  • The okf-ocr pipeline has already run, but user explicitly requests Mistral-based OCR for QA or secondary validation.

Dependencies

  1. ImageMagick: For PDF-to-image conversion (must be installed system-wide and in PATH).
  2. Download: ImageMagick Official Site
  3. Verify installation: magick --version
  4. Mistral Vision Model: Access via API (requires MISTRAL_API_KEY in environment variables).

Core Principle

This skill performs verbatim transcription using Mistral's vision model. Every word, figure, punctuation mark, capitalisation, and line break is preserved exactly as it appears in the source. This is critical for legal documents where precision is non-negotiable.

Workflow

Phase 1: Convert PDF to Images (if input is PDF)

  1. Check input type: If the file is a PDF, convert it to images using ImageMagick.
  2. Command: magick -density 300 "input.pdf" -quality 100 "output_page_%02d.png"
  3. Resolution: 300 DPI (adjustable for higher quality if needed).

  4. Output: One PNG image per PDF page.

  5. Handle non-PDF images: If the input is already an image (PNG, JPG, etc.), skip conversion.

Phase 2: OCR with Mistral Vision Model

  1. Process each image: Send each image to Mistral's vision model for OCR.
  2. API endpoint: https://api.mistral.ai/v1/vision (or relevant endpoint).

  3. Prompt: "Extract all text from this image verbatim. Preserve every word, figure, punctuation mark, capitalisation, and line break exactly as it appears. Do not interpret, correct, or summarize."

  4. Combine results: Concatenate OCR results from all images into a single text file.

  5. Format: Include page separators (e.g., --- PAGE 1 ---).
  6. Output filename: <source_name>_V2_MISTRAL_OCR.txt (sidecar next to source).

Phase 3: Quality Assurance (QA)

  1. Verify completeness: Ensure all pages are processed and no text is truncated.
  2. Check metadata: Extract and log document type, parties, dates, and key figures.
  3. Flag issues: Mark unreadable sections as [ILLEGIBLE] or [LOW CONFIDENCE].

Phase 4: Output and Logging

  1. Save transcription: Write verbatim text to <source_name>_V2_MISTRAL_OCR.txt.
  2. Save metadata: Log extracted metadata (document type, parties, dates, key figures) in a structured format (e.g., JSON sidecar <source_name>_mistral_metadata.json).
  3. Update OCR Log: Append a row to 97_OCR_Log/OCR_Log.csv with:
  4. Date
  5. Filename
  6. Document type
  7. Source path
  8. Destination path
  9. Method: Mistral Vision Model
  10. Quality Check: PASS/PARTIAL/FAIL
  11. Notes (e.g., "6 pages, verbatim")

Rules

  • Never edit or redact content: Preserve the source exactly.
  • Stop on unreadable text: If a section is genuinely unreadable, flag it as [ILLEGIBLE] and continue.
  • Confidentiality: All processing happens locally or via secure API calls; no document content is stored externally.

Example Usage

User Request:

"OCR this contract PDF using Mistral."

Steps:

  1. Convert PDF to images: 
    magick -density 300 "Another Contract.pdf" "Another Contract_page_%02d.png"
  2. OCR each image with Mistral's vision model.
  3. Combine results into Another Contract_V2_MISTRAL_OCR.txt.
  4. Log metadata and update 97_OCR_Log/OCR_Log.csv.

Self-Learning

  • Record lessons in learnings.md (same folder as this SKILL.md).
  • Example lessons:
  • "Mistral vision model struggles with handwritten text in scanned PDFs; flag as [HANDWRITTEN: ILLEGIBLE]."
  • "ImageMagick at 300 DPI produces optimal balance of quality and file size for Mistral OCR."

File Structure

mistral-ocr/
├── SKILL.md          # This file
├── learnings.md      # Self-learning log
├── tools/
│   ├── pdf_to_images.py    # PDF-to-image conversion script
│   ├── mistral_ocr.py       # Mistral vision model OCR script
│   └── combine_results.py  # Combine OCR results into final output
└── templates/
    └── metadata_template.json  # Template for metadata sidecar

Tools

1. pdf_to_images.py

  • Input: PDF file path, output directory, DPI (default: 300).
  • Output: PNG images (one per page).
  • Uses: subprocess to call ImageMagick.

2. mistral_ocr.py

  • Input: Image file path, Mistral API key.
  • Output: Extracted text (verbatim).
  • Uses: requests to call Mistral's vision API.

3. combine_results.py

  • Input: Directory of OCR'd text files (one per image).
  • Output: Combined text file with page separators.

Environment Setup

  1. Install ImageMagick and add to PATH.
  2. Set MISTRAL_API_KEY in environment variables.
  3. Install Python dependencies: 
    pip install requests pillow python-dotenv

Error Handling

  • ImageMagick not found: Return error with installation instructions.
  • Mistral API failure: Retry 3 times; if persistent, log error and skip the image.
  • Unreadable text: Flag as [ILLEGIBLE] and continue.

Performance Notes

  • PDF-to-image conversion: ~3–10 seconds for a 6-page PDF at 300 DPI.
  • Mistral OCR: ~1–2 seconds per image (depends on API latency).
  • Total time for 6-page PDF: ~10–20 seconds.