ocr-provenance-mcp 1.0.0

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * OCR Provenance MCP Server - CLI Entry Point
+ *
+ * This file serves as the bin entry point for global npm installation.
+ * It simply imports and runs the main server module.
+ *
+ * Usage:
+ *   npx ocr-provenance-mcp              # via npx
+ *   ocr-provenance-mcp                  # after npm install -g
+ *   node dist/index.js                  # direct invocation
+ *
+ * @module bin
+ */
+import './index.js';
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OCR Provenance MCP Server
+ *
+ * Entry point for the MCP server using stdio transport.
+ * Exposes OCR, search, provenance, and clustering tools via JSON-RPC.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/index.js

@@ -0,0 +1,90 @@
+/**
+ * OCR Provenance MCP Server
+ *
+ * Entry point for the MCP server using stdio transport.
+ * Exposes OCR, search, provenance, and clustering tools via JSON-RPC.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module index
+ */
+import dotenv from 'dotenv';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+// Load .env from multiple candidate locations (first found wins):
+// 1. OCR_PROVENANCE_ENV_FILE env var (explicit override)
+// 2. CWD/.env (project-local)
+// 3. Package root/.env (development)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const envCandidates = [
+    process.env.OCR_PROVENANCE_ENV_FILE,
+    path.resolve(process.cwd(), '.env'),
+    path.resolve(__dirname, '..', '.env'),
+].filter((p) => typeof p === 'string');
+for (const envPath of envCandidates) {
+    if (fs.existsSync(envPath)) {
+        dotenv.config({ path: envPath, quiet: true });
+        break;
+    }
+}
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerAllTools } from './server/register-tools.js';
+import { validateStartupDependencies } from './server/startup.js';
+// =============================================================================
+// SERVER INITIALIZATION
+// =============================================================================
+const server = new McpServer({
+    name: 'ocr-provenance-mcp',
+    version: '1.0.0',
+});
+// =============================================================================
+// TOOL REGISTRATION
+// =============================================================================
+const toolCount = registerAllTools(server);
+// =============================================================================
+// SERVER STARTUP
+// =============================================================================
+async function main() {
+    validateStartupDependencies();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`OCR Provenance MCP Server running on stdio`);
+    console.error(`Tools registered: ${toolCount}`);
+}
+// Log memory usage every 5 minutes for observability (stderr only - safe for MCP)
+setInterval(() => {
+    const mem = process.memoryUsage();
+    console.error(`[Memory] RSS=${(mem.rss / 1024 / 1024).toFixed(1)}MB ` +
+        `Heap=${(mem.heapUsed / 1024 / 1024).toFixed(1)}/${(mem.heapTotal / 1024 / 1024).toFixed(1)}MB ` +
+        `External=${(mem.external / 1024 / 1024).toFixed(1)}MB`);
+}, 300_000).unref();
+// Graceful shutdown handler
+function handleShutdown(signal) {
+    console.error(`[Shutdown] Received ${signal}, shutting down gracefully...`);
+    // Close the MCP server connection
+    server
+        .close()
+        .then(() => {
+        console.error('[Shutdown] Server closed successfully');
+        process.exit(0);
+    })
+        .catch((err) => {
+        console.error(`[Shutdown] Error closing server: ${err}`);
+        process.exit(1);
+    });
+    // Force exit after 5s if graceful shutdown hangs
+    setTimeout(() => {
+        console.error('[Shutdown] Forced exit after timeout');
+        process.exit(1);
+    }, 5000).unref();
+}
+process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+process.on('SIGINT', () => handleShutdown('SIGINT'));
+main().catch((error) => {
+    console.error('Fatal error starting MCP server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/models/chunk.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Chunk interfaces for OCR Provenance MCP System
+ *
+ * Represents text chunks extracted from OCR output.
+ * Provenance depth: 2
+ */
+/**
+ * Configuration for text chunking
+ */
+/** Configuration for heading level normalization */
+export interface HeadingNormalizationConfig {
+    /** Enable heading normalization (default: false) */
+    enabled: boolean;
+    /** Minimum pattern group size to trigger normalization (default: 3) */
+    minPatternCount?: number;
+}
+export interface ChunkingConfig {
+    /** Maximum characters per chunk (default: 2000) */
+    chunkSize: number;
+    /** Overlap percentage between chunks (default: 10) */
+    overlapPercent: number;
+    /** Maximum chunk size for oversized sections (default: 8000) */
+    maxChunkSize: number;
+    /** Minimum chunk size - heading-only chunks below this are merged (default: 100) */
+    minChunkSize?: number;
+    /** Heading normalization configuration (default: disabled) */
+    headingNormalization?: HeadingNormalizationConfig;
+}
+/**
+ * Default chunking configuration per PRD
+ */
+export declare const DEFAULT_CHUNKING_CONFIG: ChunkingConfig;
+/**
+ * Calculate overlap in characters
+ */
+export declare function getOverlapCharacters(config: ChunkingConfig): number;
+/**
+ * Calculate step size for chunking
+ */
+export declare function getStepSize(config: ChunkingConfig): number;
+/**
+ * Result of chunking operation (before database storage)
+ */
+export interface ChunkResult {
+    /** 0-indexed chunk position */
+    index: number;
+    /** The chunk text */
+    text: string;
+    /** Start offset in source text */
+    startOffset: number;
+    /** End offset in source text */
+    endOffset: number;
+    /** Characters overlapping with previous chunk */
+    overlapWithPrevious: number;
+    /** Characters overlapping with next chunk */
+    overlapWithNext: number;
+    /** Page number if determinable (1-indexed) */
+    pageNumber: number | null;
+    /** Page range if spanning pages (e.g., "4-5") */
+    pageRange: string | null;
+    /** Heading text that provides context for this chunk */
+    headingContext: string | null;
+    /** Heading level (1-6) of the section this chunk belongs to */
+    headingLevel: number | null;
+    /** Full section path (e.g., "Introduction > Background > History") */
+    sectionPath: string | null;
+    /** Content types present in this chunk (e.g., ["text", "table", "list"]) */
+    contentTypes: string[];
+    /** Whether this chunk is atomic (should not be split further) */
+    isAtomic: boolean;
+    /** Table metadata if this chunk contains a table */
+    tableMetadata?: {
+        columnHeaders: string[];
+        rowCount: number;
+        columnCount: number;
+        /** Human-readable summary of table content */
+        summary?: string;
+        /** Caption text from preceding block (e.g., "Table 1: Budget Summary") */
+        caption?: string;
+        /** Index of a prior table structure this continues (cross-page) */
+        continuationOf?: number;
+    } | null;
+}
+/**
+ * Represents a text chunk stored in database
+ * Provenance depth: 2
+ */
+export interface Chunk {
+    /** UUID v4 identifier */
+    id: string;
+    /** Reference to parent document */
+    document_id: string;
+    /** Reference to OCR result this chunk came from */
+    ocr_result_id: string;
+    /** The actual chunk text content */
+    text: string;
+    /** SHA-256 hash of text content */
+    text_hash: string;
+    /** 0-indexed position in document */
+    chunk_index: number;
+    /** Character offset where chunk starts in OCR text */
+    character_start: number;
+    /** Character offset where chunk ends in OCR text */
+    character_end: number;
+    /** Page number this chunk primarily belongs to (1-indexed) */
+    page_number: number | null;
+    /** Page range if chunk spans multiple pages (e.g., "4-5") */
+    page_range: string | null;
+    /** Characters overlapping with previous chunk */
+    overlap_previous: number;
+    /** Characters overlapping with next chunk */
+    overlap_next: number;
+    /** Reference to provenance record */
+    provenance_id: string;
+    /** ISO 8601 timestamp */
+    created_at: string;
+    /** Status of embedding generation */
+    embedding_status: 'pending' | 'complete' | 'failed';
+    /** ISO 8601 timestamp when embedded */
+    embedded_at: string | null;
+    /** OCR parse quality score from Datalab (0-5 range), propagated to chunk level */
+    ocr_quality_score: number | null;
+    /** Heading text that provides context for this chunk */
+    heading_context: string | null;
+    /** Heading level (1-6) of the section this chunk belongs to */
+    heading_level: number | null;
+    /** Full section path (e.g., "Introduction > Background > History") */
+    section_path: string | null;
+    /** JSON-encoded array of content types (e.g., '["text","table"]') */
+    content_types: string | null;
+    /** Whether this chunk is atomic (should not be split further) */
+    is_atomic: number;
+    /** Chunking strategy used to create this chunk (e.g., "fixed", "hybrid_section") */
+    chunking_strategy: string;
+}
+//# sourceMappingURL=chunk.d.ts.map

package/dist/models/chunk.d.ts.map

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

package/dist/models/chunk.js

@@ -0,0 +1,27 @@
+/**
+ * Chunk interfaces for OCR Provenance MCP System
+ *
+ * Represents text chunks extracted from OCR output.
+ * Provenance depth: 2
+ */
+/**
+ * Default chunking configuration per PRD
+ */
+export const DEFAULT_CHUNKING_CONFIG = {
+    chunkSize: 2000,
+    overlapPercent: 10,
+    maxChunkSize: 8000,
+};
+/**
+ * Calculate overlap in characters
+ */
+export function getOverlapCharacters(config) {
+    return Math.floor(config.chunkSize * config.overlapPercent / 100);
+}
+/**
+ * Calculate step size for chunking
+ */
+export function getStepSize(config) {
+    return config.chunkSize - getOverlapCharacters(config);
+}
+//# sourceMappingURL=chunk.js.map

package/dist/models/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/models/chunk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8BH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,EAAE;IAClB,YAAY,EAAE,IAAI;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB;IACzD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,cAAc,GAAG,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAsB;IAChD,OAAO,MAAM,CAAC,SAAS,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/dist/models/cluster.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Cluster and Document Clustering interfaces
+ *
+ * Types for document clustering and auto-classification.
+ * Clusters group semantically similar documents using HDBSCAN or agglomerative algorithms.
+ *
+ * @module models/cluster
+ */
+/**
+ * A cluster of semantically similar documents
+ */
+export interface Cluster {
+    id: string;
+    run_id: string;
+    cluster_index: number;
+    label: string | null;
+    description: string | null;
+    classification_tag: string | null;
+    document_count: number;
+    centroid_json: string | null;
+    top_terms_json: string | null;
+    coherence_score: number | null;
+    algorithm: string;
+    algorithm_params_json: string;
+    silhouette_score: number | null;
+    content_hash: string;
+    provenance_id: string;
+    created_at: string;
+    processing_duration_ms: number | null;
+}
+/**
+ * Assignment of a document to a cluster within a specific run
+ */
+export interface DocumentCluster {
+    id: string;
+    document_id: string;
+    cluster_id: string | null;
+    run_id: string;
+    similarity_to_centroid: number;
+    membership_probability: number;
+    is_noise: boolean;
+    assigned_at: string;
+}
+/**
+ * Configuration for a clustering run
+ */
+export interface ClusterRunConfig {
+    algorithm: 'hdbscan' | 'agglomerative' | 'kmeans';
+    n_clusters: number | null;
+    min_cluster_size: number;
+    distance_threshold: number | null;
+    linkage: 'average' | 'complete' | 'single';
+}
+/**
+ * Result of a clustering run
+ */
+export interface ClusterRunResult {
+    run_id: string;
+    algorithm: string;
+    n_clusters: number;
+    total_documents: number;
+    noise_document_ids: string[];
+    silhouette_score: number;
+    clusters: ClusterResultItem[];
+    processing_duration_ms: number;
+}
+/**
+ * A single cluster within a run result
+ */
+export interface ClusterResultItem {
+    cluster_index: number;
+    document_count: number;
+    coherence_score: number;
+    centroid: number[];
+    document_ids: string[];
+    similarities: number[];
+    probabilities: number[];
+}
+//# sourceMappingURL=cluster.d.ts.map

package/dist/models/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/models/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,SAAS,GAAG,eAAe,GAAG,QAAQ,CAAC;IAClD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB"}

package/dist/models/cluster.js

@@ -0,0 +1,10 @@
+/**
+ * Cluster and Document Clustering interfaces
+ *
+ * Types for document clustering and auto-classification.
+ * Clusters group semantically similar documents using HDBSCAN or agglomerative algorithms.
+ *
+ * @module models/cluster
+ */
+export {};
+//# sourceMappingURL=cluster.js.map

package/dist/models/cluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../../src/models/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/models/comparison.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Comparison interfaces for OCR Provenance MCP System
+ *
+ * Types for document comparison (text diff, structural diff).
+ * Pure types - no logic.
+ */
+/**
+ * A single diff operation (insert, delete, or equal)
+ */
+export interface TextDiffOperation {
+    type: 'insert' | 'delete' | 'equal';
+    text: string;
+    doc1_offset: number;
+    doc2_offset: number;
+    line_count: number;
+}
+/**
+ * Result of comparing two documents' text content
+ */
+export interface TextDiffResult {
+    operations: TextDiffOperation[];
+    total_operations: number;
+    truncated: boolean;
+    insertions: number;
+    deletions: number;
+    unchanged: number;
+    similarity_ratio: number;
+    doc1_length: number;
+    doc2_length: number;
+}
+/**
+ * Structural metadata comparison between two documents
+ */
+export interface StructuralDiff {
+    doc1_page_count: number | null;
+    doc2_page_count: number | null;
+    doc1_chunk_count: number;
+    doc2_chunk_count: number;
+    doc1_text_length: number;
+    doc2_text_length: number;
+    doc1_quality_score: number | null;
+    doc2_quality_score: number | null;
+    doc1_ocr_mode: string;
+    doc2_ocr_mode: string;
+}
+/**
+ * Stored comparison record (maps to comparisons table row)
+ */
+export interface Comparison {
+    id: string;
+    document_id_1: string;
+    document_id_2: string;
+    similarity_ratio: number;
+    text_diff_json: string;
+    structural_diff_json: string;
+    summary: string;
+    content_hash: string;
+    provenance_id: string;
+    created_at: string;
+    processing_duration_ms: number | null;
+}
+//# sourceMappingURL=comparison.d.ts.map

package/dist/models/comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.d.ts","sourceRoot":"","sources":["../../src/models/comparison.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC"}

package/dist/models/comparison.js

@@ -0,0 +1,8 @@
+/**
+ * Comparison interfaces for OCR Provenance MCP System
+ *
+ * Types for document comparison (text diff, structural diff).
+ * Pure types - no logic.
+ */
+export {};
+//# sourceMappingURL=comparison.js.map

package/dist/models/comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.js","sourceRoot":"","sources":["../../src/models/comparison.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/models/document.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Document interfaces for OCR Provenance MCP System
+ *
+ * Represents source documents ingested into the system.
+ * Provenance depth: 0 (root of chain)
+ */
+/**
+ * Document status throughout processing lifecycle
+ */
+export type DocumentStatus = 'pending' | 'processing' | 'complete' | 'failed';
+/**
+ * Supported file types for OCR processing
+ */
+export declare const SUPPORTED_FILE_TYPES: readonly ["pdf", "docx", "doc", "pptx", "ppt", "xlsx", "xls", "png", "jpg", "jpeg", "tiff", "tif", "bmp", "gif", "webp", "txt", "csv", "md"];
+/**
+ * Represents a source document ingested into the system
+ * Provenance depth: 0 (root of chain)
+ */
+export interface Document {
+    /** UUID v4 identifier */
+    id: string;
+    /** Full absolute path to source file */
+    file_path: string;
+    /** Original filename */
+    file_name: string;
+    /** SHA-256 hash of file content (format: 'sha256:...') */
+    file_hash: string;
+    /** File size in bytes */
+    file_size: number;
+    /** File type/extension (e.g., 'pdf', 'png', 'docx') */
+    file_type: string;
+    /** Current processing status */
+    status: DocumentStatus;
+    /** Number of pages (populated after OCR) */
+    page_count: number | null;
+    /** Reference to provenance record */
+    provenance_id: string;
+    /** ISO 8601 timestamp when document was ingested */
+    created_at: string;
+    /** ISO 8601 timestamp when file was last modified */
+    modified_at: string | null;
+    /** ISO 8601 timestamp when OCR completed */
+    ocr_completed_at: string | null;
+    /** Error message if status is 'failed' */
+    error_message: string | null;
+    /** Document title from metadata */
+    doc_title: string | null;
+    /** Document author from metadata */
+    doc_author: string | null;
+    /** Document subject from metadata */
+    doc_subject: string | null;
+    /** Reference to Datalab uploaded file ID */
+    datalab_file_id: string | null;
+}
+/**
+ * OCR result from Datalab processing
+ * Provenance depth: 1
+ */
+export interface OCRResult {
+    /** UUID v4 identifier */
+    id: string;
+    /** Reference to provenance record */
+    provenance_id: string;
+    /** Reference to source document */
+    document_id: string;
+    /** Extracted text content (Markdown format) */
+    extracted_text: string;
+    /** Length of extracted text */
+    text_length: number;
+    /** Datalab API request ID for tracing */
+    datalab_request_id: string;
+    /** OCR mode used: 'fast', 'balanced', 'accurate' */
+    datalab_mode: 'fast' | 'balanced' | 'accurate';
+    /** Datalab parse quality score (0-5) */
+    parse_quality_score: number | null;
+    /** Number of pages processed */
+    page_count: number;
+    /** Processing cost in cents */
+    cost_cents: number | null;
+    /** SHA-256 hash of extracted text */
+    content_hash: string;
+    /** ISO 8601 processing start timestamp */
+    processing_started_at: string;
+    /** ISO 8601 processing complete timestamp */
+    processing_completed_at: string;
+    /** Processing duration in milliseconds */
+    processing_duration_ms: number;
+    /** JSON block hierarchy from Datalab */
+    json_blocks?: string | null;
+    /** Extras metadata (cost_breakdown, Datalab metadata, etc.) */
+    extras_json?: string | null;
+}
+/**
+ * Page offset information for tracking text positions
+ */
+export interface PageOffset {
+    /** 1-indexed page number */
+    page: number;
+    /** Character offset where page starts */
+    charStart: number;
+    /** Character offset where page ends */
+    charEnd: number;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/models/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/models/document.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,oBAAoB,8IAIvB,CAAC;AAIX;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAElB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAElB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAElB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAElB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAElB,gCAAgC;IAChC,MAAM,EAAE,cAAc,CAAC;IAEvB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IAEtB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,0CAA0C;IAC1C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,mCAAmC;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oCAAoC;IACpC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qCAAqC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,4CAA4C;IAC5C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IAEX,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IAEtB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IAEpB,yCAAyC;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAE3B,oDAAoD;IACpD,YAAY,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAE/C,wCAAwC;IACxC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IAEnB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IAErB,0CAA0C;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAE9B,6CAA6C;IAC7C,uBAAuB,EAAE,MAAM,CAAC;IAEhC,0CAA0C;IAC1C,sBAAsB,EAAE,MAAM,CAAC;IAE/B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/models/document.js

@@ -0,0 +1,15 @@
+/**
+ * Document interfaces for OCR Provenance MCP System
+ *
+ * Represents source documents ingested into the system.
+ * Provenance depth: 0 (root of chain)
+ */
+/**
+ * Supported file types for OCR processing
+ */
+export const SUPPORTED_FILE_TYPES = [
+    'pdf', 'docx', 'doc', 'pptx', 'ppt', 'xlsx', 'xls',
+    'png', 'jpg', 'jpeg', 'tiff', 'tif', 'bmp', 'gif', 'webp',
+    'txt', 'csv', 'md',
+];
+//# sourceMappingURL=document.js.map

package/dist/models/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/models/document.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK;IAClD,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM;IACzD,KAAK,EAAE,KAAK,EAAE,IAAI;CACV,CAAC"}