feat(ocr): add Mistral OCR engine with package export, tests, and documentation

test/test.ocr.ts

@@ -0,0 +1,77 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { createMistralOcrEngine, type ISmartAiMistralOcrTransport } from '../ts_ocr/index.js';
+
+tap.test('createMistralOcrEngine should call Mistral OCR with image data URLs', async () => {
+  const calls: unknown[] = [];
+  const mockTransport: ISmartAiMistralOcrTransport = {
+    process: async (request) => {
+      calls.push(request);
+      return {
+        pages: [
+          {
+            index: 0,
+            markdown: 'hello terminal',
+            confidence_scores: {
+              average_page_confidence_score: 0.91,
+              minimum_page_confidence_score: 0.8,
+            },
+          },
+        ],
+        model: 'mistral-ocr-latest',
+        usage_info: {
+          pages_processed: 1,
+          doc_size_bytes: 12,
+        },
+      };
+    },
+  };
+
+  const ocrEngine = createMistralOcrEngine({
+    transport: mockTransport,
+    confidenceScoresGranularity: 'page',
+  });
+
+  const result = await ocrEngine.recognizeImage({
+    dataBase64: 'iVBORw0KGgo=',
+    mimeType: 'image/png',
+  });
+
+  expect(calls.length).toEqual(1);
+  expect((calls[0] as any).model).toEqual('mistral-ocr-latest');
+  expect((calls[0] as any).document.type).toEqual('image_url');
+  expect((calls[0] as any).document.image_url).toEqual('data:image/png;base64,iVBORw0KGgo=');
+  expect((calls[0] as any).confidence_scores_granularity).toEqual('page');
+  expect(result.text).toEqual('hello terminal');
+  expect(result.confidence).toEqual(0.91);
+  expect(result.pages).toEqual([
+    {
+      index: 0,
+      text: 'hello terminal',
+      confidence: 0.91,
+    },
+  ]);
+});
+
+tap.test('createMistralOcrEngine should validate image input', async () => {
+  const ocrEngine = createMistralOcrEngine({
+    transport: {
+      process: async () => {
+        throw new Error('should not call OCR');
+      },
+    },
+  });
+
+  let error: Error | undefined;
+  try {
+    await ocrEngine.recognizeImage({
+      dataBase64: '',
+      mimeType: 'image/png',
+    });
+  } catch (caughtError) {
+    error = caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+  }
+
+  expect(error?.message).toEqual('Mistral OCR image input requires dataBase64.');
+});
+
+export default tap.start();