feat(ocr): add a Mistral-based OCR adapter for KVM frames

test/test.ocr.smartai.ts

@@ -0,0 +1,70 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { createMistralKvmOcrEngine } from '../ts/smartkvm.ocr.smartai.js';
+import type { IKvmFrame } from '../ts/smartkvm.interfaces.js';
+
+const createDummyFrame = (): IKvmFrame => ({
+  timestamp: Date.now(),
+  width: 1,
+  height: 1,
+  mimeType: 'image/png',
+  dataBase64: 'iVBORw0KGgo=',
+});
+
+tap.test('createMistralKvmOcrEngine should adapt KVM frames to smartai OCR', async () => {
+  const calls: unknown[] = [];
+  const ocrEngine = createMistralKvmOcrEngine({
+    transport: {
+      process: async (request) => {
+        calls.push(request);
+        return {
+          pages: [
+            {
+              index: 0,
+              markdown: 'terminal text',
+              confidence_scores: {
+                average_page_confidence_score: 0.93,
+              },
+            },
+          ],
+          model: 'mistral-ocr-latest',
+        };
+      },
+    },
+  });
+
+  const result = await ocrEngine.recognize(createDummyFrame());
+
+  expect(calls.length).toEqual(1);
+  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('terminal text');
+  expect(result.confidence).toEqual(0.93);
+});
+
+tap.test('createMistralKvmOcrEngine should reject unsupported crop options', async () => {
+  const ocrEngine = createMistralKvmOcrEngine({
+    transport: {
+      process: async () => {
+        throw new Error('should not call OCR');
+      },
+    },
+  });
+
+  let error: Error | undefined;
+  try {
+    await ocrEngine.recognize(createDummyFrame(), {
+      crop: {
+        x: 0,
+        y: 0,
+        width: 1,
+        height: 1,
+      },
+    });
+  } catch (caughtError) {
+    error = caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+  }
+
+  expect(error?.message).toEqual('Mistral KVM OCR does not support crop options yet.');
+});
+
+export default tap.start();