ocr-provenance-mcp 1.0.0

package/dist/services/vlm/service.js

@@ -0,0 +1,256 @@
+/**
+ * VLM Service - Gemini 3 Multimodal Image Analysis
+ *
+ * Provides high-level API for analyzing images from legal and medical documents
+ * using Google Gemini 3 Flash multimodal capabilities.
+ *
+ * @module services/vlm/service
+ */
+import { GeminiClient, getSharedClient } from '../gemini/index.js';
+import { LEGAL_IMAGE_PROMPT, CLASSIFY_IMAGE_PROMPT, DEEP_ANALYSIS_PROMPT, UNIVERSAL_EVALUATION_PROMPT, UNIVERSAL_EVALUATION_SCHEMA, createContextPrompt, IMAGE_ANALYSIS_SCHEMA, CLASSIFICATION_SCHEMA, } from './prompts.js';
+/**
+ * VLMService - High-level Gemini multimodal image analysis
+ *
+ * Provides methods for:
+ * - describeImage: Detailed legal/medical image analysis
+ * - classifyImage: Quick categorization
+ * - analyzeDeep: Extended reasoning analysis
+ * - batch operations for multiple images
+ */
+export class VLMService {
+    client;
+    constructor(client) {
+        this.client = client ?? getSharedClient();
+    }
+    /**
+     * Generate detailed description of an image from a legal/medical document.
+     *
+     * @param imagePath - Path to the image file
+     * @param options - Analysis options
+     * @returns VLMAnalysisResult with description and structured data
+     */
+    async describeImage(imagePath, options = {}) {
+        const fileRef = GeminiClient.fileRefFromPath(imagePath);
+        return this.analyzeFileRef(fileRef, options);
+    }
+    /**
+     * Analyze image from a FileRef (already loaded buffer).
+     *
+     * @param fileRef - Pre-loaded file reference
+     * @param options - Analysis options
+     * @returns VLMAnalysisResult
+     */
+    async describeImageFromRef(fileRef, options = {}) {
+        return this.analyzeFileRef(fileRef, options);
+    }
+    /**
+     * Core analysis logic shared by describeImage and describeImageFromRef.
+     */
+    async analyzeFileRef(fileRef, options) {
+        const { prompt, schema } = this.selectPromptAndSchema(options);
+        const response = await this.client.analyzeImage(prompt, fileRef, {
+            schema,
+            mediaResolution: options.highResolution !== false ? 'MEDIA_RESOLUTION_HIGH' : 'MEDIA_RESOLUTION_LOW',
+        });
+        const analysis = this.parseAnalysis(response.text);
+        const description = [analysis.paragraph1, analysis.paragraph2, analysis.paragraph3]
+            .filter(Boolean)
+            .join('\n\n');
+        return {
+            description,
+            analysis,
+            model: response.model,
+            processingTimeMs: response.processingTimeMs,
+            tokensUsed: response.usage.totalTokens,
+        };
+    }
+    /**
+     * Select prompt and schema based on analysis options.
+     * Universal prompt is the default for all images.
+     */
+    selectPromptAndSchema(options) {
+        if (options.useUniversalPrompt !== false) {
+            return { prompt: UNIVERSAL_EVALUATION_PROMPT, schema: UNIVERSAL_EVALUATION_SCHEMA };
+        }
+        if (options.contextText) {
+            return {
+                prompt: createContextPrompt(options.contextText),
+                schema: IMAGE_ANALYSIS_SCHEMA,
+            };
+        }
+        return { prompt: LEGAL_IMAGE_PROMPT, schema: IMAGE_ANALYSIS_SCHEMA };
+    }
+    /**
+     * Quick classification of an image.
+     *
+     * @param imagePath - Path to the image file
+     * @returns ImageClassification with type and complexity
+     */
+    async classifyImage(imagePath) {
+        const fileRef = GeminiClient.fileRefFromPath(imagePath);
+        const response = await this.client.analyzeImage(CLASSIFY_IMAGE_PROMPT, fileRef, {
+            schema: CLASSIFICATION_SCHEMA,
+            mediaResolution: 'MEDIA_RESOLUTION_LOW', // Low res for classification
+        });
+        return this.parseClassification(response.text);
+    }
+    /**
+     * Deep analysis using extended reasoning.
+     *
+     * @param imagePath - Path to the image file
+     * @returns DeepAnalysisResult with reasoning steps
+     */
+    async analyzeDeep(imagePath) {
+        const fileRef = GeminiClient.fileRefFromPath(imagePath);
+        const response = await this.client.analyzeImage(DEEP_ANALYSIS_PROMPT, fileRef, {
+            mediaResolution: 'MEDIA_RESOLUTION_HIGH',
+            thinkingConfig: { thinkingLevel: 'HIGH' },
+        });
+        const deepResult = this.parseDeepAnalysis(response.text);
+        const analysis = this.convertDeepToStandardAnalysis(deepResult);
+        return {
+            description: deepResult.fullDescription || '',
+            analysis,
+            model: response.model,
+            processingTimeMs: response.processingTimeMs,
+            tokensUsed: response.usage.totalTokens,
+        };
+    }
+    /**
+     * Get service status including Gemini client status.
+     */
+    getStatus() {
+        return this.client.getStatus();
+    }
+    /**
+     * Parse a VLM JSON response, stripping markdown fences.
+     *
+     * When thinking mode is enabled, responseMimeType: 'application/json' is incompatible,
+     * so Gemini may include reasoning preamble before the JSON block. This method handles
+     * that by: (0) rejecting empty/blank responses immediately, (1) stripping code fences,
+     * (2) trying full text parse, (3) extracting the outermost JSON object from mixed text,
+     * (4) throwing with diagnostics on failure.
+     */
+    parseVLMJson(text, label) {
+        // Step 0: Reject empty/blank responses immediately with a clear error
+        if (!text || text.trim().length === 0) {
+            console.error(`[VLMService] Gemini returned empty response for ${label}`);
+            throw new Error(`VLM ${label} failed: Gemini returned an empty response. ` +
+                `The image may be too small, corrupted, or unprocessable by the model.`);
+        }
+        // Step 1: Strip markdown code fences
+        const clean = text.replace(/```json\n?|\n?```/g, '').trim();
+        // Step 2: Try parsing the full cleaned text
+        try {
+            return JSON.parse(clean);
+        }
+        catch (error) {
+            console.error(`[VLMService] Failed to parse full cleaned text as JSON for ${label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Step 3: Extract JSON object from mixed text (reasoning preamble + JSON)
+        // Find the first '{' and last '}' to isolate the JSON block
+        const firstBrace = clean.indexOf('{');
+        const lastBrace = clean.lastIndexOf('}');
+        if (firstBrace !== -1 && lastBrace > firstBrace) {
+            const jsonCandidate = clean.slice(firstBrace, lastBrace + 1);
+            try {
+                return JSON.parse(jsonCandidate);
+            }
+            catch (error) {
+                console.error(`[VLMService] Failed to parse extracted JSON substring for ${label}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Step 4: All extraction attempts failed - throw with diagnostics
+        console.error(`[VLMService] Failed to parse ${label} JSON from response`);
+        throw new Error(`VLM ${label} JSON parse failed: could not extract valid JSON from response. ` +
+            `Raw response (first 500 chars): ${text.slice(0, 500)}`);
+    }
+    /**
+     * Parse JSON response into ImageAnalysis structure.
+     */
+    parseAnalysis(text) {
+        const parsed = this.parseVLMJson(text, 'analysis');
+        return {
+            imageType: parsed.imageType || 'unknown',
+            primarySubject: parsed.primarySubject || '',
+            paragraph1: parsed.paragraph1 || '',
+            paragraph2: parsed.paragraph2 || '',
+            paragraph3: parsed.paragraph3 || '',
+            extractedText: parsed.extractedText || [],
+            dates: parsed.dates || [],
+            names: parsed.names || [],
+            numbers: parsed.numbers || [],
+            confidence: parsed.confidence ?? 0.5,
+        };
+    }
+    /**
+     * Parse classification response.
+     */
+    parseClassification(text) {
+        const parsed = this.parseVLMJson(text, 'classification');
+        return {
+            type: parsed.type || 'other',
+            hasText: parsed.hasText ?? false,
+            textDensity: parsed.textDensity || 'unknown',
+            complexity: parsed.complexity || 'medium',
+            confidence: parsed.confidence ?? 0.5,
+        };
+    }
+    /**
+     * Parse deep analysis response.
+     */
+    parseDeepAnalysis(text) {
+        const parsed = this.parseVLMJson(text, 'deep analysis');
+        return {
+            thinkingSteps: parsed.thinkingSteps || [],
+            imageType: parsed.imageType || 'unknown',
+            fullDescription: parsed.fullDescription || text,
+            extractedData: {
+                text: parsed.extractedData?.text || [],
+                dates: parsed.extractedData?.dates || [],
+                amounts: parsed.extractedData?.amounts || [],
+                names: parsed.extractedData?.names || [],
+                references: parsed.extractedData?.references || [],
+            },
+            legalSignificance: parsed.legalSignificance || '',
+            medicalSignificance: parsed.medicalSignificance,
+            uncertainties: parsed.uncertainties || [],
+            confidence: parsed.confidence ?? 0.5,
+        };
+    }
+    /**
+     * Convert deep analysis to standard ImageAnalysis format.
+     */
+    convertDeepToStandardAnalysis(deep) {
+        return {
+            imageType: deep.imageType,
+            primarySubject: deep.fullDescription.slice(0, 200),
+            paragraph1: deep.thinkingSteps.slice(0, 3).join(' ') || deep.fullDescription.slice(0, 300),
+            paragraph2: deep.fullDescription,
+            paragraph3: [deep.legalSignificance, deep.medicalSignificance].filter(Boolean).join(' '),
+            extractedText: deep.extractedData.text,
+            dates: deep.extractedData.dates,
+            names: deep.extractedData.names,
+            numbers: [...deep.extractedData.amounts, ...deep.extractedData.references],
+            confidence: deep.confidence,
+        };
+    }
+}
+// Singleton management
+let _service = null;
+/**
+ * Get or create VLMService singleton.
+ */
+export function getVLMService() {
+    if (!_service) {
+        _service = new VLMService();
+    }
+    return _service;
+}
+/**
+ * Reset singleton for testing.
+ */
+export function resetVLMService() {
+    _service = null;
+}
+//# sourceMappingURL=service.js.map

package/dist/services/vlm/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/services/vlm/service.ts"],"names":[],"mappings":"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"}

package/dist/services/webhook-delivery.d.ts

@@ -0,0 +1,4 @@
+import type Database from 'better-sqlite3';
+/** Initialize webhook delivery for a database connection */
+export declare function initWebhookDelivery(getConnection: () => Database.Database): void;
+//# sourceMappingURL=webhook-delivery.d.ts.map

package/dist/services/webhook-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-delivery.d.ts","sourceRoot":"","sources":["../../src/services/webhook-delivery.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAuG3C,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAyDhF"}

package/dist/services/webhook-delivery.js

@@ -0,0 +1,140 @@
+/**
+ * Webhook Delivery Service
+ *
+ * Delivers events to registered webhook URLs with:
+ * - HMAC-SHA256 signing (when secret configured)
+ * - Exponential backoff retry (3 attempts)
+ * - Auto-disable after 10 consecutive failures
+ *
+ * CRITICAL: NEVER use console.log() - stdout is JSON-RPC protocol.
+ *
+ * @module services/webhook-delivery
+ */
+import { createHmac } from 'crypto';
+import { eventBus } from '../server/events.js';
+import { calculateBackoffDelay } from '../utils/backoff.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const MAX_FAILURES = 10;
+const MAX_RETRIES = 3;
+const DELIVERY_TIMEOUT_MS = 10000;
+// =============================================================================
+// SIGNING
+// =============================================================================
+/** Sign payload with HMAC-SHA256 */
+function signPayload(payload, secret) {
+    return createHmac('sha256', secret).update(payload).digest('hex');
+}
+// =============================================================================
+// DELIVERY
+// =============================================================================
+/** Deliver event to a single webhook with retry */
+async function deliverToWebhook(webhook, event) {
+    const payload = JSON.stringify({
+        event: event.type,
+        timestamp: event.timestamp,
+        entity_type: event.entityType,
+        entity_id: event.entityId,
+        data: event.data,
+    });
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Webhook-Event': event.type,
+    };
+    if (webhook.secret) {
+        headers['X-Webhook-Signature'] = `sha256=${signPayload(payload, webhook.secret)}`;
+    }
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(webhook.url, {
+                method: 'POST',
+                headers,
+                body: payload,
+                signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+            });
+            if (response.ok)
+                return true;
+            if (response.status >= 400 && response.status < 500) {
+                // Client error - don't retry
+                console.error(`[Webhook] ${webhook.id} client error ${response.status} for ${event.type}`);
+                return false;
+            }
+            // Server error - retry with backoff
+            if (attempt < MAX_RETRIES - 1) {
+                const delay = calculateBackoffDelay(attempt);
+                console.error(`[Webhook] ${webhook.id} server error ${response.status}, retrying in ${delay}ms`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        catch (error) {
+            if (attempt < MAX_RETRIES - 1) {
+                const delay = calculateBackoffDelay(attempt);
+                console.error(`[Webhook] ${webhook.id} delivery error: ${error instanceof Error ? error.message : String(error)}, retrying in ${delay}ms`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            else {
+                console.error(`[Webhook] ${webhook.id} delivery failed after ${MAX_RETRIES} attempts: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    return false;
+}
+// =============================================================================
+// INITIALIZATION
+// =============================================================================
+/** Initialize webhook delivery for a database connection */
+export function initWebhookDelivery(getConnection) {
+    eventBus.onEvent('*', async (event) => {
+        let conn;
+        try {
+            conn = getConnection();
+        }
+        catch {
+            return; // No database selected
+        }
+        let webhooks;
+        try {
+            webhooks = conn
+                .prepare('SELECT * FROM webhooks WHERE is_active = 1')
+                .all();
+        }
+        catch (error) {
+            console.error(`[Webhook] Failed to query webhooks: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        for (const webhook of webhooks) {
+            // Check if webhook is subscribed to this event type
+            const subscribedEvents = webhook.events.split(',').map((e) => e.trim());
+            if (!subscribedEvents.includes(event.type) && !subscribedEvents.includes('*'))
+                continue;
+            const success = await deliverToWebhook(webhook, event);
+            try {
+                if (success) {
+                    conn
+                        .prepare(`UPDATE webhooks SET last_triggered_at = datetime('now'), failure_count = 0 WHERE id = ?`)
+                        .run(webhook.id);
+                }
+                else {
+                    const newCount = webhook.failure_count + 1;
+                    if (newCount >= MAX_FAILURES) {
+                        conn
+                            .prepare('UPDATE webhooks SET failure_count = ?, is_active = 0 WHERE id = ?')
+                            .run(newCount, webhook.id);
+                        console.error(`[Webhook] ${webhook.id} disabled after ${MAX_FAILURES} failures`);
+                    }
+                    else {
+                        conn
+                            .prepare('UPDATE webhooks SET failure_count = ? WHERE id = ?')
+                            .run(newCount, webhook.id);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`[Webhook] Failed to update webhook ${webhook.id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    });
+    console.error('[WebhookDelivery] Initialized - listening for events');
+}
+//# sourceMappingURL=webhook-delivery.js.map

package/dist/services/webhook-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-delivery.js","sourceRoot":"","sources":["../../src/services/webhook-delivery.ts"],"names":[],"mappings":"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"}

package/dist/tools/chunks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Chunk-Level MCP Tools
+ *
+ * Tools for inspecting individual chunks, browsing document structure
+ * at chunk granularity, and building context windows from neighboring chunks.
+ *
+ * Tools: ocr_chunk_get, ocr_chunk_list, ocr_chunk_context, ocr_document_page
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module tools/chunks
+ */
+import { type ToolDefinition } from './shared.js';
+/**
+ * Chunk tools collection for MCP server registration
+ */
+export declare const chunkTools: Record<string, ToolDefinition>;
+//# sourceMappingURL=chunks.d.ts.map

package/dist/tools/chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/tools/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAwE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAqZxH;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAyBrD,CAAC"}