ocr-provenance-mcp 1.0.0

package/dist/models/embedding.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Embedding interfaces for OCR Provenance MCP System
+ *
+ * Represents vector embeddings with full provenance.
+ * Provenance depth: 3
+ *
+ * CRITICAL: This interface is denormalized to include original_text
+ * and source file info. Search results are self-contained per CP-002.
+ */
+/**
+ * Embedding model constants
+ */
+export declare const EMBEDDING_MODEL: {
+    readonly name: "nomic-embed-text-v1.5";
+    readonly version: "1.5.0";
+    readonly dimensions: 768;
+    readonly maxSequenceLength: 8192;
+    readonly prefixes: {
+        readonly document: "search_document: ";
+        readonly query: "search_query: ";
+    };
+};
+/**
+ * Represents a vector embedding with full provenance
+ * Provenance depth: 3 (from chunks) or 4 (from VLM descriptions)
+ *
+ * CRITICAL: This table is denormalized to include original_text
+ * and source file info. Search results are self-contained.
+ *
+ * Either chunk_id (for text embeddings), image_id (for VLM embeddings),
+ * or extraction_id (for extraction embeddings) must be set.
+ */
+export interface Embedding {
+    /** UUID v4 identifier */
+    id: string;
+    /** Reference to source chunk (null for VLM embeddings) */
+    chunk_id: string | null;
+    /** Reference to source image (null for text embeddings) */
+    image_id: string | null;
+    /** Reference to source extraction (null for text/VLM embeddings) */
+    extraction_id: string | null;
+    /** Reference to root document */
+    document_id: string;
+    /** The actual chunk text that was embedded - ALWAYS INCLUDED */
+    original_text: string;
+    /** Length of original text in characters */
+    original_text_length: number;
+    /** Full path to source file */
+    source_file_path: string;
+    /** Source file name */
+    source_file_name: string;
+    /** SHA-256 hash of source file */
+    source_file_hash: string;
+    /** Page number (1-indexed) */
+    page_number: number | null;
+    /** Page range if spanning multiple pages */
+    page_range: string | null;
+    /** Start character offset in OCR text */
+    character_start: number;
+    /** End character offset in OCR text */
+    character_end: number;
+    /** Chunk index in document */
+    chunk_index: number;
+    /** Total chunks in document */
+    total_chunks: number;
+    /** 768-dimensional float32 vector */
+    vector: Float32Array;
+    /** Model name (nomic-embed-text-v1.5) */
+    model_name: string;
+    /** Model version */
+    model_version: string;
+    /** Task type used (search_document) */
+    task_type: 'search_document' | 'search_query';
+    /** Inference mode (always 'local') */
+    inference_mode: 'local';
+    /** GPU device used */
+    gpu_device: string;
+    /** Reference to provenance record */
+    provenance_id: string;
+    /** SHA-256 hash of original_text */
+    content_hash: string;
+    /** ISO 8601 timestamp */
+    created_at: string;
+    /** Generation duration in milliseconds */
+    generation_duration_ms: number | null;
+}
+//# sourceMappingURL=embedding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/models/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IAGpB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IAEtB,4CAA4C;IAC5C,oBAAoB,EAAE,MAAM,CAAC;IAG7B,+BAA+B;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uBAAuB;IACvB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IAGzB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IAExB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IAEtB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IAEpB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAGrB,qCAAqC;IACrC,MAAM,EAAE,YAAY,CAAC;IAGrB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IAEnB,oBAAoB;IACpB,aAAa,EAAE,MAAM,CAAC;IAEtB,uCAAuC;IACvC,SAAS,EAAE,iBAAiB,GAAG,cAAc,CAAC;IAE9C,sCAAsC;IACtC,cAAc,EAAE,OAAO,CAAC;IAExB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IAGnB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IAEtB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IAErB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC"}

package/dist/models/embedding.js

@@ -0,0 +1,23 @@
+/**
+ * Embedding interfaces for OCR Provenance MCP System
+ *
+ * Represents vector embeddings with full provenance.
+ * Provenance depth: 3
+ *
+ * CRITICAL: This interface is denormalized to include original_text
+ * and source file info. Search results are self-contained per CP-002.
+ */
+/**
+ * Embedding model constants
+ */
+export const EMBEDDING_MODEL = {
+    name: 'nomic-embed-text-v1.5',
+    version: '1.5.0',
+    dimensions: 768,
+    maxSequenceLength: 8192,
+    prefixes: {
+        document: 'search_document: ',
+        query: 'search_query: '
+    }
+};
+//# sourceMappingURL=embedding.js.map

package/dist/models/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/models/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,GAAG;IACf,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE;QACR,QAAQ,EAAE,mBAAmB;QAC7B,KAAK,EAAE,gBAAgB;KACxB;CACO,CAAC"}

package/dist/models/extraction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extraction interface for structured data extracted via page_schema
+ * Provenance depth: 2 (parallel to CHUNK)
+ */
+export interface Extraction {
+    id: string;
+    document_id: string;
+    ocr_result_id: string;
+    schema_json: string;
+    extraction_json: string;
+    content_hash: string;
+    provenance_id: string;
+    created_at: string;
+}
+//# sourceMappingURL=extraction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../src/models/extraction.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/models/extraction.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extraction.js.map

package/dist/models/extraction.js.map

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

package/dist/models/form-fill.d.ts

@@ -0,0 +1,23 @@
+/**
+ * FormFill interface for form fill results from Datalab /fill API
+ * Provenance depth: 1
+ */
+export interface FormFill {
+    id: string;
+    source_file_path: string;
+    source_file_hash: string;
+    field_data_json: string;
+    context: string | null;
+    confidence_threshold: number;
+    output_file_path: string | null;
+    output_base64: string | null;
+    fields_filled: string;
+    fields_not_found: string;
+    page_count: number | null;
+    cost_cents: number | null;
+    status: 'pending' | 'processing' | 'complete' | 'failed';
+    error_message: string | null;
+    provenance_id: string;
+    created_at: string;
+}
+//# sourceMappingURL=form-fill.d.ts.map

package/dist/models/form-fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-fill.d.ts","sourceRoot":"","sources":["../../src/models/form-fill.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/models/form-fill.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=form-fill.js.map

package/dist/models/form-fill.js.map

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

package/dist/models/image.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Image interfaces for OCR Provenance MCP System
+ *
+ * Represents images extracted from documents for VLM analysis.
+ * Provenance depth: 2 (after OCR)
+ */
+/**
+ * Bounding box coordinates for image location in document
+ */
+interface BoundingBox {
+    /** X coordinate (pixels from left) */
+    x: number;
+    /** Y coordinate (pixels from top) */
+    y: number;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Image dimensions
+ */
+interface ImageDimensions {
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * VLM processing status
+ */
+export type VLMStatus = 'pending' | 'processing' | 'complete' | 'failed';
+/**
+ * Structured data extracted from image by VLM
+ */
+export interface VLMStructuredData {
+    /** Type of image identified */
+    imageType: string;
+    /** Primary subject/content */
+    primarySubject?: string;
+    /** Extracted text strings */
+    extractedText?: string[];
+    /** Dates found in image */
+    dates?: string[];
+    /** Names found in image */
+    names?: string[];
+    /** Numbers/amounts found */
+    numbers?: string[];
+    /** Additional metadata */
+    [key: string]: unknown;
+}
+/**
+ * Represents an extracted image from a document
+ * Provenance depth: 2 (after OCR extraction)
+ */
+export interface ImageReference {
+    /** UUID v4 identifier */
+    id: string;
+    /** Reference to source document */
+    document_id: string;
+    /** Reference to OCR result that produced this */
+    ocr_result_id: string;
+    /** Page number where image appears (1-indexed) */
+    page_number: number;
+    /** Bounding box coordinates on page */
+    bounding_box: BoundingBox;
+    /** Index of image on this page (0-indexed) */
+    image_index: number;
+    /** Image format (png, jpg, etc.) */
+    format: string;
+    /** Image dimensions in pixels */
+    dimensions: ImageDimensions;
+    /** Path to extracted image file */
+    extracted_path: string | null;
+    /** File size in bytes */
+    file_size: number | null;
+    /** VLM processing status */
+    vlm_status: VLMStatus;
+    /** Natural language description from VLM */
+    vlm_description: string | null;
+    /** Structured data extracted by VLM */
+    vlm_structured_data: VLMStructuredData | null;
+    /** Reference to embedding of VLM description */
+    vlm_embedding_id: string | null;
+    /** Model used for VLM processing */
+    vlm_model: string | null;
+    /** VLM confidence score (0-1) */
+    vlm_confidence: number | null;
+    /** ISO 8601 timestamp when VLM completed */
+    vlm_processed_at: string | null;
+    /** Tokens used for VLM processing */
+    vlm_tokens_used: number | null;
+    /** Surrounding text context from document */
+    context_text: string | null;
+    /** Reference to provenance record */
+    provenance_id: string | null;
+    /** Datalab block type: 'Figure', 'Picture', 'PageHeader', etc. Null if unknown */
+    block_type: string | null;
+    /** True if image is inside a PageHeader or PageFooter block */
+    is_header_footer: boolean;
+    /** SHA-256 hash of image file bytes for deduplication: 'sha256:...' */
+    content_hash: string | null;
+    /** ISO 8601 timestamp when image was extracted */
+    created_at: string;
+    /** Error message if VLM failed */
+    error_message: string | null;
+}
+/**
+ * Input for creating a new image reference
+ */
+export type CreateImageReference = Omit<ImageReference, 'id' | 'created_at' | 'vlm_status' | 'vlm_description' | 'vlm_structured_data' | 'vlm_embedding_id' | 'vlm_model' | 'vlm_confidence' | 'vlm_processed_at' | 'vlm_tokens_used' | 'error_message'>;
+/**
+ * VLM result to update an image with
+ */
+export interface VLMResult {
+    /** Natural language description */
+    description: string;
+    /** Structured data extracted */
+    structuredData: VLMStructuredData;
+    /** Embedding ID for description */
+    embeddingId: string;
+    /** Model used */
+    model: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Tokens used */
+    tokensUsed: number;
+}
+/**
+ * Image extraction result from PDF
+ */
+export interface ExtractedImage {
+    /** Page number (1-indexed) */
+    page: number;
+    /** Index on page (0-indexed) */
+    index: number;
+    /** Image format */
+    format: string;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+    /** Bounding box on page */
+    bbox: BoundingBox;
+    /** Path to extracted file */
+    path: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Image extraction options
+ */
+export interface ImageExtractionOptions {
+    /** Minimum image dimension (pixels) to include */
+    minSize?: number;
+    /** Maximum images to extract per document */
+    maxImages?: number;
+    /** Output directory for extracted images */
+    outputDir: string;
+}
+/**
+ * Image statistics
+ */
+export interface ImageStats {
+    /** Total images in database */
+    total: number;
+    /** Images with VLM complete */
+    processed: number;
+    /** Images pending VLM */
+    pending: number;
+    /** Images currently being processed */
+    processing: number;
+    /** Images with VLM failed */
+    failed: number;
+}
+export {};
+//# sourceMappingURL=image.d.ts.map

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

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

package/dist/models/image.js

@@ -0,0 +1,8 @@
+/**
+ * Image interfaces for OCR Provenance MCP System
+ *
+ * Represents images extracted from documents for VLM analysis.
+ * Provenance depth: 2 (after OCR)
+ */
+export {};
+//# sourceMappingURL=image.js.map

package/dist/models/image.js.map

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

package/dist/models/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OCR Provenance MCP System - Data Models
+ *
+ * Barrel export for all model interfaces.
+ */
+export * from './document.js';
+export * from './chunk.js';
+export * from './embedding.js';
+export * from './provenance.js';
+export * from './image.js';
+export * from './extraction.js';
+export * from './form-fill.js';
+export * from './comparison.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,eAAe,CAAC;AAG9B,cAAc,YAAY,CAAC;AAG3B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,YAAY,CAAC;AAG3B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC"}

package/dist/models/index.js

@@ -0,0 +1,22 @@
+/**
+ * OCR Provenance MCP System - Data Models
+ *
+ * Barrel export for all model interfaces.
+ */
+// Document models
+export * from './document.js';
+// Chunk models
+export * from './chunk.js';
+// Embedding models
+export * from './embedding.js';
+// Provenance models
+export * from './provenance.js';
+// Image models
+export * from './image.js';
+// Extraction models
+export * from './extraction.js';
+// Form fill models
+export * from './form-fill.js';
+// Comparison models
+export * from './comparison.js';
+//# sourceMappingURL=index.js.map

package/dist/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kBAAkB;AAClB,cAAc,eAAe,CAAC;AAE9B,eAAe;AACf,cAAc,YAAY,CAAC;AAE3B,mBAAmB;AACnB,cAAc,gBAAgB,CAAC;AAE/B,oBAAoB;AACpB,cAAc,iBAAiB,CAAC;AAEhC,eAAe;AACf,cAAc,YAAY,CAAC;AAE3B,oBAAoB;AACpB,cAAc,iBAAiB,CAAC;AAEhC,mBAAmB;AACnB,cAAc,gBAAgB,CAAC;AAE/B,oBAAoB;AACpB,cAAc,iBAAiB,CAAC"}

package/dist/models/provenance.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Provenance interfaces for OCR Provenance MCP System
+ *
+ * Comprehensive provenance tracking for complete data lineage.
+ * Every data transformation creates a provenance record.
+ */
+/**
+ * Types of provenance records in the chain
+ * Each type has a fixed chain depth
+ */
+export declare enum ProvenanceType {
+    /** Original source file (depth 0) */
+    DOCUMENT = "DOCUMENT",
+    /** Text extracted via Datalab OCR (depth 1) */
+    OCR_RESULT = "OCR_RESULT",
+    /** Text segment with overlap (depth 2) */
+    CHUNK = "CHUNK",
+    /** Extracted image from document (depth 2, parallel to CHUNK) */
+    IMAGE = "IMAGE",
+    /** VLM analysis output describing an image (depth 3) */
+    VLM_DESCRIPTION = "VLM_DESCRIPTION",
+    /** Structured extraction from page_schema (depth 2, parallel to CHUNK) */
+    EXTRACTION = "EXTRACTION",
+    /** Form fill result (depth 0, parallel to DOCUMENT) */
+    FORM_FILL = "FORM_FILL",
+    /** Comparison between two documents (depth 2, parallel to CHUNK) */
+    COMPARISON = "COMPARISON",
+    /** Document clustering result (depth 2, parallel to CHUNK) */
+    CLUSTERING = "CLUSTERING",
+    /** 768-dim vector from nomic model (depth 3 from CHUNK, depth 4 from VLM_DESCRIPTION) */
+    EMBEDDING = "EMBEDDING"
+}
+/**
+ * Chain depth for each provenance type
+ * Note: EMBEDDING depth is 3 when derived from CHUNK, but 4 when derived from VLM_DESCRIPTION.
+ * The actual depth is computed dynamically from the parent chain.
+ */
+export declare const PROVENANCE_CHAIN_DEPTH: Record<ProvenanceType, number>;
+/**
+ * Source type for provenance tracking
+ */
+export type SourceType = 'FILE' | 'OCR' | 'CHUNKING' | 'IMAGE_EXTRACTION' | 'VLM' | 'VLM_DEDUP' | 'EMBEDDING' | 'EXTRACTION' | 'FORM_FILL' | 'COMPARISON' | 'CLUSTERING';
+/**
+ * Location information within source document
+ */
+export interface ProvenanceLocation {
+    /** 1-indexed page number */
+    page_number?: number;
+    /** Page range if spanning pages (e.g., "4-5") */
+    page_range?: string;
+    /** Start character offset */
+    character_start?: number;
+    /** End character offset */
+    character_end?: number;
+    /** Chunk index (0-indexed) */
+    chunk_index?: number;
+    /** Bounding box for OCR position data */
+    bounding_box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        page: number;
+    };
+}
+/**
+ * Comprehensive provenance record
+ * Every data transformation creates one of these
+ */
+export interface ProvenanceRecord {
+    /** UUID v4 - globally unique */
+    id: string;
+    /** Type of record (determines chain depth) */
+    type: ProvenanceType;
+    /** ISO 8601 - when this record was created */
+    created_at: string;
+    /** ISO 8601 - when processing completed */
+    processed_at: string;
+    /** Original file creation time (for DOCUMENT type) */
+    source_file_created_at: string | null;
+    /** Original file modified time (for DOCUMENT type) */
+    source_file_modified_at: string | null;
+    /** Type of source operation */
+    source_type: SourceType;
+    /** Full absolute path (for FILE source) */
+    source_path: string | null;
+    /** Parent provenance ID (null for DOCUMENT type) */
+    source_id: string | null;
+    /** Original document this derives from */
+    root_document_id: string;
+    /** Precise location within source */
+    location: ProvenanceLocation | null;
+    /** SHA-256 of THIS item's content (format: 'sha256:...') */
+    content_hash: string;
+    /** SHA-256 of the INPUT that produced this */
+    input_hash: string | null;
+    /** SHA-256 of original source file (for tracing) */
+    file_hash: string | null;
+    /** Processor name (e.g., 'datalab-ocr', 'chunker', 'nomic-embed-text-v1.5') */
+    processor: string;
+    /** Exact processor version */
+    processor_version: string;
+    /** ALL parameters used for processing */
+    processing_params: Record<string, unknown>;
+    /** Processing duration in milliseconds */
+    processing_duration_ms: number | null;
+    /** Quality metric if available */
+    processing_quality_score: number | null;
+    /** Immediate parent provenance ID */
+    parent_id: string | null;
+    /** ALL ancestor provenance IDs as JSON array string */
+    parent_ids: string;
+    /** How many transformations from source */
+    chain_depth: number;
+    /** Human-readable path as JSON array string */
+    chain_path: string | null;
+}
+/**
+ * Parameters for creating a new provenance record
+ */
+export interface CreateProvenanceParams {
+    type: ProvenanceType;
+    source_type: SourceType;
+    source_id?: string | null;
+    root_document_id: string;
+    content_hash: string;
+    input_hash?: string | null;
+    file_hash?: string | null;
+    source_path?: string | null;
+    processor: string;
+    processor_version: string;
+    processing_params: Record<string, unknown>;
+    processing_duration_ms?: number | null;
+    processing_quality_score?: number | null;
+    location?: ProvenanceLocation | null;
+    source_file_created_at?: string | null;
+    source_file_modified_at?: string | null;
+}
+/**
+ * Verification result for provenance integrity
+ */
+export interface VerificationResult {
+    /** Overall validity */
+    valid: boolean;
+    /** Whether chain is intact (no missing records) */
+    chain_intact: boolean;
+    /** Number of hashes successfully verified */
+    hashes_verified: number;
+    /** Number of hash verification failures */
+    hashes_failed: number;
+    /** Details of failed verifications */
+    failed_items: Array<{
+        id: string;
+        expected_hash: string;
+        computed_hash: string;
+        type: ProvenanceType;
+    }>;
+    /** ISO 8601 timestamp of verification */
+    verified_at: string;
+}
+/**
+ * W3C PROV-JSON export format
+ */
+export interface W3CProvDocument {
+    prefix: Record<string, string>;
+    entity: Record<string, Record<string, unknown>>;
+    activity: Record<string, Record<string, unknown>>;
+    agent: Record<string, Record<string, unknown>>;
+    wasGeneratedBy: Record<string, Record<string, unknown>>;
+    wasDerivedFrom: Record<string, Record<string, unknown>>;
+    wasAttributedTo: Record<string, Record<string, unknown>>;
+    used: Record<string, Record<string, unknown>>;
+}
+//# sourceMappingURL=provenance.d.ts.map

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

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

package/dist/models/provenance.js

@@ -0,0 +1,53 @@
+/**
+ * Provenance interfaces for OCR Provenance MCP System
+ *
+ * Comprehensive provenance tracking for complete data lineage.
+ * Every data transformation creates a provenance record.
+ */
+/**
+ * Types of provenance records in the chain
+ * Each type has a fixed chain depth
+ */
+export var ProvenanceType;
+(function (ProvenanceType) {
+    /** Original source file (depth 0) */
+    ProvenanceType["DOCUMENT"] = "DOCUMENT";
+    /** Text extracted via Datalab OCR (depth 1) */
+    ProvenanceType["OCR_RESULT"] = "OCR_RESULT";
+    /** Text segment with overlap (depth 2) */
+    ProvenanceType["CHUNK"] = "CHUNK";
+    /** Extracted image from document (depth 2, parallel to CHUNK) */
+    ProvenanceType["IMAGE"] = "IMAGE";
+    /** VLM analysis output describing an image (depth 3) */
+    ProvenanceType["VLM_DESCRIPTION"] = "VLM_DESCRIPTION";
+    /** Structured extraction from page_schema (depth 2, parallel to CHUNK) */
+    ProvenanceType["EXTRACTION"] = "EXTRACTION";
+    /** Form fill result (depth 0, parallel to DOCUMENT) */
+    ProvenanceType["FORM_FILL"] = "FORM_FILL";
+    /** Comparison between two documents (depth 2, parallel to CHUNK) */
+    ProvenanceType["COMPARISON"] = "COMPARISON";
+    /** Document clustering result (depth 2, parallel to CHUNK) */
+    ProvenanceType["CLUSTERING"] = "CLUSTERING";
+    /** 768-dim vector from nomic model (depth 3 from CHUNK, depth 4 from VLM_DESCRIPTION) */
+    ProvenanceType["EMBEDDING"] = "EMBEDDING";
+})(ProvenanceType || (ProvenanceType = {}));
+/**
+ * Chain depth for each provenance type
+ * Note: EMBEDDING depth is 3 when derived from CHUNK, but 4 when derived from VLM_DESCRIPTION.
+ * The actual depth is computed dynamically from the parent chain.
+ */
+// NOTE: EMBEDDING depth is 3 for chunk-derived embeddings only.
+// VLM description embeddings use depth 4 and bypass createProvenance() - see pipeline.ts
+export const PROVENANCE_CHAIN_DEPTH = {
+    [ProvenanceType.DOCUMENT]: 0,
+    [ProvenanceType.OCR_RESULT]: 1,
+    [ProvenanceType.CHUNK]: 2,
+    [ProvenanceType.IMAGE]: 2, // Same depth as CHUNK (parallel branch)
+    [ProvenanceType.VLM_DESCRIPTION]: 3, // After IMAGE
+    [ProvenanceType.EXTRACTION]: 2, // Same depth as CHUNK (parallel branch)
+    [ProvenanceType.FORM_FILL]: 0, // Same depth as DOCUMENT (form fill is a root-level operation)
+    [ProvenanceType.COMPARISON]: 2, // Same depth as CHUNK (parallel branch)
+    [ProvenanceType.CLUSTERING]: 2, // Same depth as CHUNK (parallel branch)
+    [ProvenanceType.EMBEDDING]: 3 // Chunk-derived only; VLM embeddings use depth 4 (built in pipeline.ts)
+};
+//# sourceMappingURL=provenance.js.map