mrz-genius 2.0.0

package/src/index.js

@@ -0,0 +1,150 @@
+/**
+ * mrz-genius
+ * Node.js library for MRZ (Machine Readable Zone) detection, OCR, and parsing
+ * 
+ * Supports: TD1 (ID Cards), TD2, TD3 (Passports), MRVA (Visa type A), MRVB (Visa type B)
+ * 
+ * Features:
+ *   - MRZ region detection on document images
+ *   - OCR (Optical Character Recognition) for MRZ text extraction
+ *   - Full MRZ parsing with check digit validation
+ *   - OCR error correction
+ *   - BAC key generation for e-Passports
+ * 
+ * @module mrz-genius
+ */
+
+'use strict';
+
+const { parse, detectFormat, parseName, parseDate, formatDate, parseSex, parseDocumentType } = require('./parser/mrzParser');
+const { calculateCheckDigit, isCheckDigitValid, isCompositeValid } = require('./parser/checkDigit');
+const { correctOCR, findMatchingStrings } = require('./parser/ocrCorrector');
+const { MRZ_FORMATS, getFieldPositions } = require('./parser/fieldPositions');
+const { detectMRZRegion, optimizeForOCR, preprocessForOCR } = require('./detector/mrzDetector');
+const { performOCR, hasMRZ, postProcessOCR, extractMRZFromFullText } = require('./ocr/mrzOCR');
+const { extractWithLLM } = require('./ocr/llmExtractor');
+
+// ──────────────────────────────────────────────────────────
+// High-level API
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Complete MRZ processing pipeline:
+ * 1. Detect MRZ region in image
+ * 2. Perform OCR on the detected region
+ * 3. Parse the extracted MRZ text
+ * 
+ * @param {Buffer|string} image - Image buffer or file path
+ * @param {Object} [options] - Processing options
+ * @param {boolean} [options.ocrCorrection=true] - Enable OCR error correction in parser
+ * @param {boolean} [options.detectRegion=true] - Auto-detect MRZ region in image
+ * @param {string} [options.lang='eng'] - Tesseract language code
+ * @returns {Promise<Object>} Complete result with OCR data and parsed MRZ
+ */
+async function processImage(image, options = {}) {
+  const {
+    ocrCorrection = true,
+    detectRegion = true,
+    lang = 'eng',
+    llm = null // LLM configuration object
+  } = options;
+
+  let ocrResult;
+  let useLLM = !!llm;
+
+  if (useLLM) {
+    try {
+      // Ensure image is a buffer for LLM consumption
+      const fs = require('fs');
+      const imageBuffer = Buffer.isBuffer(image) ? image : fs.readFileSync(image);
+      const rawLLMText = await extractWithLLM(imageBuffer, llm);
+      
+      const extractedLines = extractMRZFromFullText(rawLLMText);
+      ocrResult = {
+        lines: extractedLines || rawLLMText.split('\n').filter(l => l.length > 5),
+        rawText: rawLLMText,
+        confidence: 99, // LLMs don't typically return confidence, assume high if parsable
+        method: `llm_${llm.provider}`
+      };
+    } catch (err) {
+      console.warn(`LLM extraction failed: ${err.message}. Falling back to Tesseract OCR.`);
+      useLLM = false;
+    }
+  }
+
+  // Fallback or Primary OCR
+  if (!useLLM) {
+    ocrResult = await performOCR(image, {
+      detectRegion,
+      lang,
+    });
+  }
+
+  // Step 3: Parse
+  const parsed = parse(ocrResult.lines, { ocrCorrection });
+
+  return {
+    success: !!parsed && parsed.valid,
+    ocr: {
+      lines: ocrResult.lines,
+      rawText: ocrResult.rawText,
+      confidence: ocrResult.confidence,
+      method: ocrResult.method,
+    },
+    parsed,
+  };
+}
+
+/**
+ * Parse an MRZ string directly (no image processing)
+ * @param {string|string[]} mrzText - MRZ text (multi-line string or array of lines)
+ * @param {Object} [options] - Parser options
+ * @param {boolean} [options.ocrCorrection=false] - Enable OCR error correction
+ * @returns {Object|null} Parsed MRZ result or null
+ */
+function parseMRZ(mrzText, options = {}) {
+  return parse(mrzText, options);
+}
+
+// ──────────────────────────────────────────────────────────
+// Exports
+// ──────────────────────────────────────────────────────────
+
+module.exports = {
+  // High-level API
+  processImage,
+  parseMRZ,
+
+  // Detection
+  detectMRZRegion,
+  optimizeForOCR,
+  preprocessForOCR,
+
+  // OCR
+  performOCR,
+  hasMRZ,
+  postProcessOCR,
+  extractMRZFromFullText,
+
+  // Parser
+  parse,
+  detectFormat,
+  parseName,
+  parseDate,
+  formatDate,
+  parseSex,
+  parseDocumentType,
+
+  // Validation
+  calculateCheckDigit,
+  isCheckDigitValid,
+  isCompositeValid,
+
+  // OCR Correction
+  correctOCR,
+  findMatchingStrings,
+
+  // Constants
+  MRZ_FORMATS,
+  getFieldPositions,
+};

package/src/ocr/llmExtractor.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const https = require('https');
+const http = require('http');
+
+/**
+ * Perform a generic HTTP/HTTPS JSON post request
+ */
+function jsonPost(urlStr, headers, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const lib = url.protocol === 'http:' ? http : https;
+    
+    const options = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers
+      }
+    };
+
+    const req = lib.request(url, options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (res.statusCode >= 400) {
+            reject(new Error(`API Error ${res.statusCode}: ${JSON.stringify(json)}`));
+          } else {
+            resolve(json);
+          }
+        } catch (e) {
+          reject(new Error('Invalid JSON response: ' + data));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+/**
+ * Extract MRZ using LLM Vision APIs
+ * @param {Buffer} imageBuffer - Image containing MRZ
+ * @param {Object} llmConfig - LLM Configuration
+ * @returns {Promise<string>} - Extracted MRZ text
+ */
+async function extractWithLLM(imageBuffer, llmConfig) {
+  if (!llmConfig || !llmConfig.provider || !llmConfig.apiKey) {
+    throw new Error('LLM config requires provider and apiKey');
+  }
+
+  const base64Image = imageBuffer.toString('base64');
+  const prompt = `Extract only the raw MRZ (Machine Readable Zone) text from this identity document image.
+Output nothing else but the exact MRZ text lines.
+Do not add markdown formatting, do not add introductions. Only the raw uppercase letters, numbers, and '<' characters.
+Preserve exact spacing and newlines.`;
+
+  const provider = llmConfig.provider.toLowerCase();
+
+  // OpenAI / ChatGPT / LiteLLM Compatible
+  if (provider === 'chatgpt' || provider === 'openai' || provider === 'litellm') {
+    const baseUrl = llmConfig.baseUrl || 'https://api.openai.com/v1';
+    const url = `${baseUrl.replace(/\/$/, '')}/chat/completions`;
+    const model = llmConfig.model || 'gpt-4o-mini';
+
+    const response = await jsonPost(url, {
+      'Authorization': `Bearer ${llmConfig.apiKey}`
+    }, {
+      model: model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: prompt },
+            { type: 'image_url', image_url: { url: `data:image/jpeg;base64,${base64Image}` } }
+          ]
+        }
+      ],
+      max_tokens: 300,
+      temperature: 0.1
+    });
+
+    return response.choices[0].message.content.trim();
+  }
+
+  // Anthropic Claude
+  if (provider === 'anthropic') {
+    const url = 'https://api.anthropic.com/v1/messages';
+    const model = llmConfig.model || 'claude-3-haiku-20240307';
+
+    const response = await jsonPost(url, {
+      'x-api-key': llmConfig.apiKey,
+      'anthropic-version': '2023-06-01'
+    }, {
+      model: model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'image',
+              source: { type: 'base64', media_type: 'image/jpeg', data: base64Image }
+            },
+            { type: 'text', text: prompt }
+          ]
+        }
+      ],
+      max_tokens: 300,
+      temperature: 0.1
+    });
+
+    return response.content[0].text.trim();
+  }
+
+  // Google Gemini
+  if (provider === 'gemini') {
+    const model = llmConfig.model || 'gemini-1.5-flash';
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${llmConfig.apiKey}`;
+
+    const response = await jsonPost(url, {}, {
+      contents: [{
+        parts: [
+          { text: prompt },
+          { inline_data: { mime_type: 'image/jpeg', data: base64Image } }
+        ]
+      }],
+      generationConfig: {
+        temperature: 0.1,
+        maxOutputTokens: 300
+      }
+    });
+
+    const candidate = response.candidates[0].content.parts[0].text;
+    return candidate.trim();
+  }
+
+  throw new Error(`Unsupported LLM provider: ${provider}`);
+}
+
+module.exports = {
+  extractWithLLM
+};