n8n-nodes-mistral-ocr

A powerful n8n community node for document OCR (Optical Character Recognition) using Mistral AI's OCR API. Extract text and structured data from documents with ease!

Features

- 📄 Basic OCR: Extract text from documents (PDFs, images)
- 🎯 Smart Templates: Pre-configured templates for common document types (invoices, contracts, IDs, etc.)
- 🛠️ Custom Fields: Define your own data extraction fields
- 📊 Element Analysis: Extract data from charts, tables, and figures
- 🔧 Advanced Mode: Full JSON schema control for power users
- 📱 User-Friendly UI: No JSON knowledge required for basic use

Supported Document Types

- Invoices/Bills - Extract amounts, dates, customer info
- Letters/Correspondence - Extract sender, recipient, dates, references
- Contracts - Extract parties, dates, amounts, terms
- Receipts - Extract store info, amounts, items
- ID Documents - Extract names, birth dates, ID numbers
- Research Papers - Extract titles, authors, abstracts, keywords

Installation

``bash
npm install n8n-nodes-mistral-ocr
`

Configuration

1. Get your Mistral API key from Mistral AI
2. In n8n, create a new credential of type "Mistral API"
3. Enter your API key

Project Structure

The project has been modularized for better maintainability:

`
nodes/MistralOcr/
├── MistralOcr.node.ts # Main node implementation
├── types/
│ └── index.ts # TypeScript type definitions
├── templates/
│ └── documentTemplates.ts # Predefined document templates
├── utils/
│ ├── nodeProperties.ts # UI property definitions
│ └── schemaUtils.ts # Schema helper functions
├── constants/
│ └── defaults.ts # Default values and constants
└── mistral.svg # Node icon
`

$3

- types/: Contains all TypeScript interfaces and type definitions
- templates/: Predefined schemas for common document types (invoices, contracts, etc.)
- utils/: Helper functions for schema building, parsing, and UI configuration
- constants/: Default values, API endpoints, and limits

Usage Examples

$3

Simply upload a document and extract all text content.

$3

1. Select "OCR with Annotations"
2. Choose "Invoice/Bill" template
3. The node automatically extracts: total amount, customer number, invoice date, etc.

$3

1. Select "OCR with Annotations"
2. Choose "Custom Fields"
3. Define your fields in JSON format:

`json
{
"contract_value": {
"type": "number",
"description": "Total contract value"
},
"client_name": {
"type": "string",
"description": "Name of the client"
},
"due_date": {
"type": "string",
"description": "Payment due date"
}
}
`

$3

For power users who need full control over JSON schemas:
1. Enable "Advanced: Custom JSON Schema"
2. Define complete JSON schemas for document and bbox annotations

API Limits

- Document Annotations: Maximum 8 pages per request
- File Size: Up to 50MB per document
- Total Pages: Up to 1000 pages per document
- File Expiry: 1-168 hours (default: 24 hours)

Rate Limiting & Error Handling

The node includes intelligent rate limiting and error handling:

- Automatic Retry: 429 errors (rate limits) are automatically retried with exponential backoff
- Smart Backoff: Delays increase exponentially (1s, 2s, 4s) with randomization to avoid thundering herd
- Descriptive Errors: Clear error messages when rate limits are exceeded
- File Validation: Pre-upload validation for file size and format
- Graceful Degradation: Continue-on-fail support for batch processing

$3

If you encounter "Service tier capacity exceeded" errors:
1. The node automatically retries up to 3 times
2. Wait times increase with each retry attempt
3. Consider upgrading your Mistral API plan for higher limits
4. For batch processing, add delays between workflow executions

Development

$3

`bash
npm run build
`

$3

`bash
npm run lint
npm run lint:fix
`

$3

The project follows n8n's coding standards:
- TypeScript for all implementations
- ESLint + Prettier for code formatting
- Comprehensive JSDoc documentation
- Modular architecture for maintainability

Error Handling

The node includes comprehensive error handling:
- Invalid JSON schema detection
- API rate limiting awareness
- File upload validation
- Graceful degradation with continue-on-fail

Contributing

Contributions are welcome! The modular structure makes it easy to:
- Add new document templates in templates/documentTemplates.ts
- Extend type definitions in types/index.ts
- Add utility functions in utils/
- Update constants in constants/defaults.ts`

Changelog

$3

- NEW: Automatic retry logic for 429 rate limit errors
- NEW: Exponential backoff with randomization to prevent thundering herd
- NEW: File size validation (50MB limit) before upload
- NEW: Enhanced error messages for rate limiting issues
- IMPROVED: Better API compliance with Mistral documentation
- FIXED: Robust handling of "Service tier capacity exceeded" errors

$3

- BREAKING: Restructured project into modules for better maintainability
- NEW: Separated types, templates, utils, and constants into dedicated modules
- IMPROVED: Better code organization and TypeScript support
- FIXED: Various linting issues and type safety improvements

$3

- NEW: Pre-configured document templates
- NEW: Simplified custom field definition
- NEW: Element analysis for charts and tables
- IMPROVED: No JSON knowledge required for basic use
- FIXED: n8n compatibility issues with displayOptions

$3

- Basic OCR functionality
- JSON schema-based annotations
- Mistral API integration

License

MIT

Support

- Documentation: GitHub Repository
- Issues: GitHub Issues
- Mistral API: Mistral Documentation