@doclo/core 0.1.5

package/dist/validation-CzOz6fwq.d.ts

@@ -0,0 +1,1126 @@
+/**
+ * Provider Identity Types
+ *
+ * Implements the 3-layer hierarchy for provider identification:
+ * 1. Provider (Company/Vendor) - e.g., datalab, openai, anthropic
+ * 2. Model - e.g., surya, marker-ocr, claude-sonnet-4.5
+ * 3. Method - e.g., native, openrouter, self-hosted
+ */
+/**
+ * Provider vendors (companies)
+ * These represent the company or organization providing the service
+ */
+type ProviderVendor = 'datalab' | 'reducto' | 'unsiloed' | 'openai' | 'anthropic' | 'google' | 'xai';
+/**
+ * Access methods for providers
+ * - native: Direct API call to provider's official endpoint
+ * - openrouter: Via OpenRouter aggregator (LLM only)
+ * - self-hosted: Self-hosted instance (e.g., pip install surya-ocr)
+ */
+type AccessMethod = 'native' | 'openrouter' | 'self-hosted';
+/**
+ * Complete provider identity combining all three layers
+ */
+interface ProviderIdentity {
+    /** The company/vendor (e.g., 'datalab') */
+    readonly provider: ProviderVendor;
+    /** The specific model/version (e.g., 'surya', 'marker-vlm') */
+    readonly model: string;
+    /** How the provider is accessed (e.g., 'native', 'self-hosted') */
+    readonly method: AccessMethod;
+}
+/**
+ * Convert provider identity to canonical string format
+ * Format: "provider:model" (e.g., "datalab:surya")
+ *
+ * @example
+ * ```typescript
+ * toProviderString({ provider: 'datalab', model: 'surya', method: 'native' })
+ * // => "datalab:surya"
+ * ```
+ */
+declare function toProviderString(identity: ProviderIdentity): string;
+/**
+ * Parse canonical provider string back to partial identity
+ * Note: method cannot be determined from string alone
+ *
+ * @example
+ * ```typescript
+ * parseProviderString("datalab:surya")
+ * // => { provider: 'datalab', model: 'surya' }
+ * ```
+ */
+declare function parseProviderString(str: string): {
+    provider: string;
+    model: string;
+};
+/**
+ * Check if an endpoint appears to be self-hosted
+ * Used to determine the access method for OCR providers
+ */
+declare function isLocalEndpoint(endpoint?: string): boolean;
+/**
+ * Create a provider identity with inferred method
+ *
+ * @param provider - The vendor/company
+ * @param model - The model name
+ * @param opts - Options including endpoint for method inference
+ */
+declare function createIdentity(provider: ProviderVendor, model: string, opts?: {
+    endpoint?: string;
+    via?: 'openrouter' | 'native';
+}): ProviderIdentity;
+
+/**
+ * Browser-safe validation utilities
+ *
+ * This module contains all validation code with ZERO Node.js dependencies.
+ * It can be safely bundled for browser environments.
+ */
+/** Page-centric IR */
+type BBox = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+type IRLine = {
+    text: string;
+    bbox?: BBox;
+    startChar?: number;
+    endChar?: number;
+    lineId?: string;
+};
+type IRPage = {
+    pageNumber?: number;
+    width: number;
+    height: number;
+    lines: IRLine[];
+    markdown?: string;
+    html?: string;
+    extras?: Record<string, unknown>;
+};
+/** Standard extras fields for DocumentIR */
+type DocumentIRExtras = {
+    /** Total number of pages in the original document (for PDFs, DOCX, etc.) */
+    pageCount?: number;
+    /** Cost in USD for processing this document */
+    costUSD?: number;
+    /** Provider-specific raw response */
+    raw?: unknown;
+    /** For chunked documents: which chunk this is (0-indexed) */
+    chunkIndex?: number;
+    /** For chunked documents: total number of chunks */
+    totalChunks?: number;
+    /** For chunked documents: page range [startPage, endPage] (1-indexed, inclusive) */
+    pageRange?: [number, number];
+    /** For Unsiloed: total semantic chunks (not traditional pages) */
+    totalSemanticChunks?: number;
+    /** Allow arbitrary additional fields */
+    [key: string]: unknown;
+};
+type DocumentIR = {
+    pages: IRPage[];
+    extras?: DocumentIRExtras;
+};
+
+/** Provider capability contracts */
+type OCRProvider = {
+    /** Full 3-layer identity (provider/model/method) */
+    identity?: ProviderIdentity;
+    /** Canonical name in "provider:model" format */
+    name: string;
+    parseToIR: (input: {
+        url?: string;
+        base64?: string;
+    }) => Promise<DocumentIR>;
+};
+/** Multimodal input for VLM providers */
+type MultimodalInput = {
+    text?: string;
+    images?: Array<{
+        url?: string;
+        base64?: string;
+        mimeType: string;
+    }>;
+    pdfs?: Array<{
+        url?: string;
+        base64?: string;
+        fileId?: string;
+    }>;
+};
+/** Reasoning configuration (normalized across providers) */
+type ReasoningConfig = {
+    /** Reasoning effort level: low (20% budget), medium (50%), high (80%) */
+    effort?: 'low' | 'medium' | 'high';
+    /** Exclude reasoning tokens from response (only use for accuracy, not visible) */
+    exclude?: boolean;
+    /** Enable reasoning with default (medium) effort */
+    enabled?: boolean;
+};
+/** Base LLM provider (text-only) */
+type LLMProvider = {
+    /** Full 3-layer identity (provider/model/method) */
+    identity?: ProviderIdentity;
+    /** Canonical name in "provider:model" format */
+    name: string;
+    completeJson: (input: {
+        prompt: string;
+        schema: object;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+    }) => Promise<{
+        json: unknown;
+        rawText?: string;
+        costUSD?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    }>;
+};
+/** Vision-capable LLM provider */
+type VLMProvider = {
+    /** Full 3-layer identity (provider/model/method) */
+    identity?: ProviderIdentity;
+    /** Canonical name in "provider:model" format */
+    name: string;
+    completeJson: (input: {
+        prompt: string | MultimodalInput;
+        schema: object;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+    }) => Promise<{
+        json: unknown;
+        rawText?: string;
+        costUSD?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    }>;
+    capabilities: {
+        supportsImages: true;
+        supportsPDFs: boolean;
+        maxPDFPages?: number;
+    };
+};
+/** Legacy alias for backward compatibility */
+type LLMJsonProvider = VLMProvider;
+/**
+ * Processing quality/speed tradeoff modes
+ * Providers map their specific modes to these normalized values
+ */
+type ProcessingMode = 'fast' | 'balanced' | 'high_accuracy';
+/**
+ * Page range specification for partial document processing
+ * Allows processing a subset of pages for cost savings
+ */
+type PageRangeOptions = {
+    /** Process only the first N pages */
+    maxPages?: number;
+    /** Specific page range (0-indexed), e.g., "0,2-4,10" */
+    pageRange?: string;
+};
+/**
+ * Language hints for OCR processing
+ */
+type LanguageOptions = {
+    /** ISO language codes for OCR, e.g., ['en', 'de', 'fr'] */
+    langs?: string[];
+};
+/**
+ * Document segmentation result for splitting "stapled" PDFs
+ * Returns page boundaries for each detected document type
+ */
+type SegmentationResult = {
+    segments: Array<{
+        /** Document type name (e.g., 'invoice', 'contract') */
+        name: string;
+        /** Page indices (0-indexed) belonging to this segment */
+        pages: number[];
+        /** Confidence level of segmentation */
+        confidence: 'high' | 'medium' | 'low';
+    }>;
+    metadata: {
+        /** Total pages in the original document */
+        totalPages: number;
+        /** How segmentation was performed */
+        segmentationMethod: 'auto' | 'schema' | 'manual';
+    };
+};
+/**
+ * Extracted image from a document
+ * Represents figures, charts, or embedded images
+ */
+type ExtractedImage = {
+    /** Block ID or reference (provider-specific) */
+    id: string;
+    /** Page number where image appears (0-indexed) */
+    pageNumber: number;
+    /** Base64-encoded image data */
+    base64: string;
+    /** MIME type of the image */
+    mimeType: string;
+    /** Location on page (normalized 0-1 coordinates) */
+    bbox?: NormalizedBBox;
+    /** Caption text if detected */
+    caption?: string;
+};
+/**
+ * Extended OCR provider options (beyond basic parseToIR)
+ * These options are normalized across different OCR providers
+ */
+type OCRProviderOptions = PageRangeOptions & LanguageOptions & {
+    /** Processing quality/speed tradeoff */
+    mode?: ProcessingMode;
+    /** Force OCR even on text-based PDFs */
+    forceOCR?: boolean;
+    /** Extract embedded images from document */
+    extractImages?: boolean;
+    /** Add page delimiters to output */
+    paginate?: boolean;
+    /** Remove and redo existing OCR */
+    stripExistingOCR?: boolean;
+};
+/**
+ * Extended VLM provider options for document extraction
+ * These options are normalized across different VLM providers
+ */
+type VLMProviderOptions = PageRangeOptions & LanguageOptions & {
+    /** Processing quality/speed tradeoff */
+    mode?: ProcessingMode;
+    /** Force OCR even on text-based PDFs */
+    forceOCR?: boolean;
+    /** Additional prompt/instructions for extraction */
+    prompt?: string;
+    /** Schema for auto-segmentation of multi-document PDFs */
+    segmentationSchema?: object;
+};
+/**
+ * Provider citation from source document
+ * Maps extracted fields to their source locations
+ */
+type ProviderCitation = {
+    /** JSON path to extracted field (e.g., "invoice.total") */
+    fieldPath: string;
+    /** Source block IDs from the provider */
+    blockIds: string[];
+    /** Confidence score (0-1) */
+    confidence?: number;
+};
+/** Consensus configuration for any node */
+type ConsensusConfig = {
+    runs: number;
+    strategy?: 'majority' | 'unanimous';
+    onTie?: 'random' | 'fail' | 'retry';
+    parallel?: boolean;
+    includeMetadata?: boolean;
+    level?: 'object' | 'field';
+    retryOnFailure?: boolean;
+    maxRetries?: number;
+};
+/** Individual consensus run result */
+type ConsensusRunResult<T = any> = {
+    runIndex: number;
+    value: T | null;
+    success: boolean;
+    error?: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    attempts?: number;
+};
+/** Field-level voting details */
+type FieldVotingDetails = {
+    fieldPath: string;
+    values: Array<{
+        /** The actual value for this voting option - can be any JSON-serializable type */
+        value: unknown;
+        count: number;
+        percentage: number;
+        runIndices: number[];
+    }>;
+    /** The winning value from consensus - can be any JSON-serializable type */
+    winner: unknown;
+    isTie: boolean;
+    agreementScore: number;
+};
+/** Consensus execution metadata */
+type ConsensusMetadata<T = unknown> = {
+    totalRuns: number;
+    successfulRuns: number;
+    failedRuns: number;
+    strategy: 'majority' | 'unanimous';
+    selectedResult: T;
+    selectedRunIndex: number;
+    confidence: 'high' | 'medium' | 'low';
+    overallAgreement: number;
+    fieldAgreement: Record<string, number>;
+    votingDetails: FieldVotingDetails[];
+    runs: ConsensusRunResult<T>[];
+    executionTime: number;
+    wasRetry: boolean;
+    tieBreakerUsed?: 'random' | 'retry' | 'fail' | null;
+    votingLevel?: 'object' | 'field';
+    isSyntheticResult?: boolean;
+    totalRetries?: number;
+    emptyResultsFiltered?: number;
+};
+/** Output with consensus metadata wrapper */
+type OutputWithConsensus<T = unknown> = {
+    data: T;
+    consensus: ConsensusMetadata<T>;
+};
+/** Conditional type helper for consensus metadata */
+type MaybeWithConsensusMetadata<T, Config> = Config extends {
+    includeMetadata: true;
+} ? OutputWithConsensus<T> : T;
+/** Flow input/output types */
+type FlowInput = {
+    url?: string;
+    base64?: string;
+    pages?: number[];
+    bounds?: BBox;
+};
+/**
+ * All MIME types supported by at least one provider.
+ * This is the union of all provider capabilities.
+ */
+type SupportedMimeType = 'application/pdf' | 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'image/tiff' | 'image/bmp' | 'image/heic' | 'image/heif' | 'image/vnd.adobe.photoshop' | 'application/msword' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'application/vnd.ms-powerpoint' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/vnd.oasis.opendocument.text' | 'application/vnd.oasis.opendocument.spreadsheet' | 'application/vnd.oasis.opendocument.presentation' | 'text/plain' | 'text/csv' | 'text/html' | 'application/rtf' | 'application/epub+zip';
+/**
+ * Flow-level input validation configuration
+ *
+ * Allows specifying accepted MIME types for early validation
+ * before flow execution begins.
+ */
+type FlowInputValidation = {
+    /**
+     * List of accepted MIME types.
+     * If specified, input must match one of these types or validation fails.
+     * If empty/undefined, all supported types are accepted.
+     */
+    acceptedFormats?: SupportedMimeType[];
+    /**
+     * Whether to throw on validation failure.
+     * @default true
+     */
+    throwOnInvalid?: boolean;
+};
+type FlowResult<T = any> = {
+    output: T;
+    metrics: StepMetric[];
+    aggregated: AggregatedMetrics;
+    artifacts: Record<string, any>;
+    error?: Error;
+};
+type SplitDocument = {
+    type: string;
+    schema: object;
+    pages: number[];
+    bounds?: BBox;
+    input: FlowInput;
+};
+/** Citation and source tracking types */
+/** Citation source type indicating data provenance */
+type CitationSourceType = 'ocr' | 'vlm' | 'llm' | 'inferred';
+/** Normalized bounding box (0-1 coordinates relative to page dimensions) */
+type NormalizedBBox = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** Line-level citation reference with spatial information */
+type LineCitation = {
+    pageNumber: number;
+    lineIndex: number;
+    bbox?: NormalizedBBox;
+    text: string;
+    confidence?: number;
+    sourceType: CitationSourceType;
+    startChar?: number;
+    endChar?: number;
+};
+/** Field-level citation mapping extracted values to sources */
+type FieldCitation = {
+    fieldPath: string;
+    /** Extracted value - can be any JSON-serializable type */
+    value: unknown;
+    citations: LineCitation[];
+    reasoning?: string;
+    confidence?: number;
+};
+/** Citation configuration for nodes */
+type CitationConfig = {
+    enabled: boolean;
+    includeTextSnippets?: boolean;
+    includeBoundingBoxes?: boolean;
+    includeConfidence?: boolean;
+    minConfidence?: number;
+    detectInferred?: boolean;
+};
+/** Extended output with citations */
+type OutputWithCitations<T> = {
+    data: T;
+    citations: FieldCitation[];
+    metadata: {
+        totalPages?: number;
+        sourceType: CitationSourceType;
+        hasInferredValues?: boolean;
+        processingTime?: number;
+    };
+};
+/** Node configuration types */
+type ParseNodeConfig = {
+    provider: OCRProvider | VLMProvider;
+    consensus?: ConsensusConfig;
+    chunked?: {
+        maxPagesPerChunk: number;
+        overlap?: number;
+        parallel?: boolean;
+    };
+    format?: 'text' | 'markdown' | 'html';
+    describeFigures?: boolean;
+    includeImages?: boolean;
+    additionalPrompt?: string;
+    citations?: CitationConfig;
+    promptRef?: string;
+    /**
+     * Optional custom variables for prompt rendering (e.g., language, strictMode, tenantId).
+     *
+     * Auto-injected variables (no need to pass manually):
+     * - format: From config.format
+     * - schema: Constructed schema (if applicable)
+     * - describeFigures: From config.describeFigures
+     * - citationsEnabled: From config.citations?.enabled
+     *
+     * Use promptVariables only for runtime context (localization, multi-tenancy, behavioral flags).
+     */
+    promptVariables?: Record<string, any>;
+    /**
+     * Additional instructions to append to the default prompt.
+     * This provides a simple way to customize the prompt without creating a custom prompt asset.
+     * The instructions will be added after the main prompt content.
+     *
+     * @example
+     * ```typescript
+     * parse({
+     *   provider: vlmProvider,
+     *   format: 'markdown',
+     *   additionalInstructions: "Pay special attention to preserving table structures and footnotes."
+     * })
+     * ```
+     */
+    additionalInstructions?: string;
+    /**
+     * When using promptRef, automatically inject format instruction if {{format}} placeholder is not present.
+     * This ensures the UI format selection always takes effect.
+     * Default: true
+     *
+     * @example
+     * ```typescript
+     * parse({
+     *   provider: vlmProvider,
+     *   format: 'markdown',
+     *   promptRef: 'my-custom-prompt',
+     *   autoInjectFormat: false  // Disable auto-injection
+     * })
+     * ```
+     */
+    autoInjectFormat?: boolean;
+    /**
+     * Enable extended reasoning/thinking for VLM providers that support it.
+     * Only applies when using a VLM provider (not OCR).
+     *
+     * @example
+     * ```typescript
+     * parse({
+     *   provider: vlmProvider,
+     *   format: 'markdown',
+     *   reasoning: { enabled: true, effort: 'medium' }
+     * })
+     * ```
+     */
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        exclude?: boolean;
+        enabled?: boolean;
+    };
+};
+type SplitNodeConfig = {
+    provider: VLMProvider;
+    schemas: Record<string, object>;
+    includeOther?: boolean;
+    consensus?: ConsensusConfig;
+    schemaRef?: string;
+    /**
+     * Enable extended reasoning/thinking for providers that support it.
+     *
+     * @example
+     * ```typescript
+     * split({
+     *   provider: vlmProvider,
+     *   schemas: { invoice: invoiceSchema, receipt: receiptSchema },
+     *   reasoning: { enabled: true, effort: 'high' }
+     * })
+     * ```
+     */
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        exclude?: boolean;
+        enabled?: boolean;
+    };
+};
+type CategorizeNodeConfig = {
+    provider: LLMProvider | VLMProvider;
+    categories: string[];
+    consensus?: ConsensusConfig;
+    additionalPrompt?: string;
+    promptRef?: string;
+    /**
+     * Optional custom variables for prompt rendering (e.g., language, strictMode, tenantId).
+     *
+     * Auto-injected variables (no need to pass manually):
+     * - categories: From config.categories
+     * - documentText: Computed from DocumentIR input
+     *
+     * Use promptVariables only for runtime context (localization, multi-tenancy, behavioral flags).
+     */
+    promptVariables?: Record<string, any>;
+    /**
+     * Additional instructions to append to the default prompt.
+     * This provides a simple way to customize the prompt without creating a custom prompt asset.
+     * The instructions will be added after the main prompt content.
+     *
+     * @example
+     * ```typescript
+     * categorize({
+     *   provider: llmProvider,
+     *   categories: ['invoice', 'receipt', 'contract'],
+     *   additionalInstructions: "Consider the document's header and footer when categorizing."
+     * })
+     * ```
+     */
+    additionalInstructions?: string;
+    /**
+     * Enable extended reasoning/thinking for providers that support it.
+     *
+     * @example
+     * ```typescript
+     * categorize({
+     *   provider: vlmProvider,
+     *   categories: ['invoice', 'receipt', 'contract'],
+     *   reasoning: { enabled: true, effort: 'low' }
+     * })
+     * ```
+     */
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        exclude?: boolean;
+        enabled?: boolean;
+    };
+};
+type ExtractNodeConfig<T = any> = {
+    provider: LLMProvider | VLMProvider;
+    schema: object | EnhancedExtractionSchema<T> | {
+        ref: string;
+    };
+    consensus?: ConsensusConfig;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        exclude?: boolean;
+        enabled?: boolean;
+    };
+    additionalPrompt?: string;
+    citations?: CitationConfig;
+    promptRef?: string;
+    /**
+     * Optional custom variables for prompt rendering (e.g., language, strictMode, tenantId).
+     *
+     * Auto-injected variables (no need to pass manually):
+     * - schema: From config.schema
+     * - documentText: Computed from DocumentIR or FlowInput
+     * - schemaTitle: From schema.title or default "the provided schema"
+     * - schemaDescription: From schema.description or empty string
+     * - structuredFormat: Generated formatting instructions (for markdown/html)
+     *
+     * Use promptVariables only for runtime context (localization, multi-tenancy, behavioral flags).
+     */
+    promptVariables?: Record<string, any>;
+    /**
+     * Additional instructions to append to the default prompt.
+     * This provides a simple way to customize the prompt without creating a custom prompt asset.
+     * The instructions will be added after the main prompt content.
+     *
+     * @example
+     * ```typescript
+     * extract({
+     *   provider: llmProvider,
+     *   schema: mySchema,
+     *   additionalInstructions: "Be strict with date formats. Use YYYY-MM-DD format only."
+     * })
+     * ```
+     */
+    additionalInstructions?: string;
+};
+/** Chunk output structure */
+type ChunkMetadata = {
+    content: string;
+    id: string;
+    index: number;
+    startChar: number;
+    endChar: number;
+    pageNumbers: number[];
+    section?: string;
+    headers?: string[];
+    strategy: string;
+    tokenCount?: number;
+    wordCount: number;
+    charCount: number;
+};
+type ChunkOutput = {
+    chunks: ChunkMetadata[];
+    totalChunks: number;
+    averageChunkSize: number;
+    sourceMetadata?: {
+        providerType?: string;
+    };
+    sourceDocument?: DocumentIR;
+};
+type ChunkNodeConfig = {
+    strategy: 'recursive' | 'section' | 'page' | 'fixed';
+    maxSize?: number;
+    minSize?: number;
+    overlap?: number;
+    separators?: string[];
+    pagesPerChunk?: number;
+    combineShortPages?: boolean;
+    minPageContent?: number;
+    size?: number;
+    unit?: 'tokens' | 'characters';
+};
+type CombineNodeConfig = {
+    strategy: 'merge' | 'concatenate' | 'first' | 'last';
+};
+type OutputNodeConfig = {
+    source?: string | string[];
+    transform?: 'first' | 'last' | 'merge' | 'pick' | 'custom';
+    fields?: string[];
+    name?: string;
+    /**
+     * Custom transform function for 'custom' transform mode.
+     * @param inputs - The input value(s) from the source step(s)
+     * @param artifacts - All artifacts from the flow execution
+     * @returns The transformed output value
+     */
+    customTransform?: (inputs: unknown | unknown[], artifacts: Record<string, unknown>) => unknown;
+};
+/** Enhanced extraction schema with examples and guidance */
+type EnhancedExtractionSchema<T = unknown> = {
+    schema: object;
+    examples?: Array<{
+        description: string;
+        input: string;
+        output: T;
+    }>;
+    extractionRules?: string;
+    contextPrompt?: string;
+    hints?: string[];
+};
+/** Node & runner */
+type StepMetric = {
+    step: string;
+    configStepId?: string;
+    startMs: number;
+    provider?: string;
+    model?: string;
+    ms: number;
+    costUSD?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+    attemptNumber?: number;
+    metadata?: {
+        kind?: 'leaf' | 'wrapper' | 'prep';
+        rollup?: boolean;
+        overheadMs?: number;
+        /** Additional metadata fields */
+        [key: string]: string | number | boolean | undefined;
+    };
+};
+/** Aggregated metrics for multi-step flows */
+interface AggregatedMetrics {
+    totalDurationMs: number;
+    totalCostUSD: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheCreationTokens: number;
+    totalCacheReadTokens: number;
+    stepCount: number;
+    byProvider: Record<string, {
+        costUSD: number;
+        inputTokens: number;
+        outputTokens: number;
+        callCount: number;
+    }>;
+}
+/**
+ * Aggregate metrics from multiple steps
+ * @param metrics - Array of step metrics
+ * @returns Aggregated totals and per-provider breakdowns
+ */
+declare function aggregateMetrics(metrics: StepMetric[]): AggregatedMetrics;
+/**
+ * Execution context passed to conditional functions and trigger nodes
+ * Provides access to artifacts and metrics from all previous steps
+ */
+interface FlowContext {
+    /** Outputs from all completed steps, indexed by step ID */
+    artifacts: Record<string, any>;
+    /** Performance metrics from all completed steps */
+    metrics: StepMetric[];
+    /** Call stack for tracking nested flow execution (for circular dependency detection) */
+    callStack?: string[];
+    /** Maximum nesting depth for flow triggers (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * W3C Trace Context for distributed tracing.
+ * Compatible with observability module's TraceContext.
+ */
+interface TraceContextLite {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceFlags: number;
+    traceState?: string;
+}
+/**
+ * Observability context passed to node executions.
+ * Uses 'any' for config and traceContext to avoid circular imports and
+ * maintain compatibility with the full observability types.
+ */
+type NodeObservabilityContext = {
+    /** Observability configuration - full type in observability module */
+    config?: any;
+    flowId?: string;
+    executionId?: string;
+    stepId?: string;
+    stepIndex?: number;
+    /** W3C Trace Context - compatible with TraceContext from observability module */
+    traceContext?: any;
+    metadata?: Record<string, unknown>;
+};
+type NodeCtx = {
+    stepId?: string;
+    artifacts: Record<string, unknown>;
+    emit: (key: string, value: unknown) => void;
+    metrics: {
+        push: (m: StepMetric) => void;
+    };
+    /** Observability context for hooks (optional) */
+    observability?: NodeObservabilityContext;
+};
+/** Node type metadata for runtime validation */
+type NodeTypeInfo = {
+    /** Input types this node accepts (e.g., ['FlowInput', 'DocumentIR']) */
+    inputTypes: string[];
+    /**
+     * Output type this node produces - can be string or function for config-dependent types.
+     * When a function, it receives the node's specific config and returns the output type string.
+     * Uses 'any' parameter to allow nodes to use their specific config types.
+     */
+    outputType: string | ((config: any) => string);
+    /** Provider types this node requires (if any) */
+    requiresProvider?: ('OCR' | 'VLM' | 'LLM')[];
+    /** Whether this node can accept array input */
+    acceptsArray?: boolean;
+    /**
+     * Whether this node always outputs an array (or function for config-dependent).
+     * Uses 'any' parameter to allow nodes to use their specific config types.
+     */
+    outputsArray?: boolean | ((config: any) => boolean);
+    /** Human-readable description of what this node does */
+    description?: string;
+};
+type NodeDef<I, O> = {
+    key: string;
+    run: (input: I, ctx: NodeCtx) => Promise<O>;
+    /** Optional type metadata for validation */
+    __meta?: NodeTypeInfo;
+};
+declare const node: <I, O>(key: string, run: NodeDef<I, O>["run"]) => NodeDef<I, O>;
+declare function runPipeline(steps: NodeDef<any, any>[], input: any, observabilityContext?: NodeObservabilityContext): Promise<{
+    output: any;
+    artifacts: Record<string, unknown>;
+    metrics: StepMetric[];
+}>;
+/**
+ * Flow execution error with step context
+ *
+ * Thrown when a flow step fails during execution. Includes:
+ * - Which step failed (ID, index, type)
+ * - Which steps completed successfully
+ * - Partial artifacts from completed steps (for debugging)
+ * - The original error that caused the failure
+ *
+ * This makes debugging flow failures much easier by showing exactly where the error occurred
+ * and what data was produced before the failure.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await flow.run(input);
+ * } catch (error) {
+ *   if (error instanceof FlowExecutionError) {
+ *     console.error(`Failed at step ${error.failedStepIndex}: ${error.failedStepType}`);
+ *     console.error(`Step ID: ${error.failedStep}`);
+ *     console.error(`Completed: ${error.completedSteps.join(', ')}`);
+ *     console.error(`Original error: ${error.originalError.message}`);
+ *
+ *     // Access partial results from completed steps
+ *     if (error.partialArtifacts?.qualify) {
+ *       console.log('Quality assessment completed:', error.partialArtifacts.qualify);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class FlowExecutionError extends Error {
+    /** The ID of the step that failed (e.g., 'parse_node123') */
+    readonly failedStep: string;
+    /** The index of the failed step in the flow (0-based) */
+    readonly failedStepIndex: number;
+    /** The type of the failed step (e.g., 'parse', 'extract', 'step', 'conditional', 'forEach') */
+    readonly failedStepType: string;
+    /** Array of step IDs that completed successfully before the failure */
+    readonly completedSteps: string[];
+    /** The original error that caused the failure */
+    readonly originalError: Error;
+    /** Partial artifacts from steps that completed before the failure */
+    readonly partialArtifacts?: Record<string, any> | undefined;
+    constructor(message: string, 
+    /** The ID of the step that failed (e.g., 'parse_node123') */
+    failedStep: string, 
+    /** The index of the failed step in the flow (0-based) */
+    failedStepIndex: number, 
+    /** The type of the failed step (e.g., 'parse', 'extract', 'step', 'conditional', 'forEach') */
+    failedStepType: string, 
+    /** Array of step IDs that completed successfully before the failure */
+    completedSteps: string[], 
+    /** The original error that caused the failure */
+    originalError: Error, 
+    /** Partial artifacts from steps that completed before the failure */
+    partialArtifacts?: Record<string, any> | undefined);
+}
+/**
+ * Flow validation error for invalid node connections
+ *
+ * Thrown when building a flow with incompatible node connections.
+ * Provides helpful error messages and suggestions for fixing the issue.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const flow = createFlow()
+ *     .step('parse', parse({ provider: ocrProvider }))
+ *     .step('combine', combine())  // Invalid: combine needs array input
+ *     .build();
+ * } catch (error) {
+ *   if (error instanceof FlowValidationError) {
+ *     console.error(error.message);
+ *     console.error('Reason:', error.reason);
+ *     console.log('Suggestions:', error.suggestions?.join('\n'));
+ *   }
+ * }
+ * ```
+ */
+declare class FlowValidationError extends Error {
+    readonly reason?: string | undefined;
+    readonly suggestions?: string[] | undefined;
+    readonly sourceNode?: string | undefined;
+    readonly targetNode?: string | undefined;
+    readonly sourceOutputType?: string | undefined;
+    readonly targetInputTypes?: string[] | undefined;
+    constructor(message: string, reason?: string | undefined, suggestions?: string[] | undefined, sourceNode?: string | undefined, targetNode?: string | undefined, sourceOutputType?: string | undefined, targetInputTypes?: string[] | undefined);
+}
+/** Node type names for validation */
+type NodeTypeName = 'parse' | 'split' | 'categorize' | 'extract' | 'chunk' | 'combine' | 'trigger' | 'output';
+/** Compatibility rule for node connections */
+type CompatibilityRule = {
+    valid: boolean;
+    requiresForEach?: boolean;
+    /** Indicates this connection cannot be fully validated at build-time and requires runtime type checking */
+    requiresRuntimeValidation?: boolean;
+    reason?: string;
+    note?: string;
+};
+/**
+ * Node Compatibility Matrix
+ *
+ * Defines which nodes can connect to which other nodes.
+ * This is the single source of truth for node connection validation.
+ *
+ * Rules based on input/output type compatibility:
+ * - parse: FlowInput → DocumentIR (or DocumentIR[] if chunked)
+ * - split: FlowInput → SplitDocument[] (requires forEach)
+ * - categorize: DocumentIR|FlowInput → {input, category}
+ * - extract: DocumentIR|FlowInput|ChunkOutput → T (typed JSON)
+ * - chunk: DocumentIR|DocumentIR[] → ChunkOutput
+ * - combine: T[] → T|T[] (merges forEach results)
+ * - trigger: any → TOutput (depends on child flow)
+ *
+ * Special behaviors:
+ * - forEach auto-unwraps SplitDocument.input → FlowInput
+ * - Conditional auto-unwraps {input, category} → input
+ * - parse with chunked:true outputs DocumentIR[] instead of DocumentIR
+ */
+declare const NODE_COMPATIBILITY_MATRIX: Record<NodeTypeName, Record<NodeTypeName, CompatibilityRule>>;
+/**
+ * Get node type name from a NodeDef
+ * @param node - Node definition
+ * @returns Node type name (e.g., 'parse', 'extract')
+ */
+declare function getNodeTypeName(node: NodeDef<any, any>): NodeTypeName | null;
+/**
+ * Get type information from a node
+ * @param node - Node definition
+ * @returns NodeTypeInfo if available
+ */
+declare function getNodeTypeInfo(node: NodeDef<any, any>): NodeTypeInfo | null;
+/**
+ * Get compatible target nodes for a given source node
+ * @param sourceType - Source node type name
+ * @param includeForEach - Include connections that require forEach
+ * @returns Array of compatible target node types
+ */
+declare function getCompatibleTargets(sourceType: NodeTypeName, includeForEach?: boolean): NodeTypeName[];
+/**
+ * Get suggested connections when a connection is invalid
+ * @param sourceType - Source node type name
+ * @returns Array of suggestion strings
+ */
+declare function getSuggestedConnections(sourceType: NodeTypeName): string[];
+/**
+ * Validation result for node connections
+ */
+type ValidationResult = {
+    valid: boolean;
+    reason?: string;
+    suggestions?: string[];
+    requiresForEach?: boolean;
+    /** Warning message for connections that are valid but require runtime type checking */
+    warning?: string;
+};
+/**
+ * Validate if two node types can be connected
+ * @param sourceType - Source node type name
+ * @param targetType - Target node type name
+ * @param forEachEnabled - Whether forEach is enabled on the source node
+ * @returns Validation result with reason and suggestions
+ */
+declare function validateNodeConnection(sourceType: NodeTypeName, targetType: NodeTypeName, forEachEnabled?: boolean): ValidationResult;
+/**
+ * Get valid starting nodes for forEach itemFlow based on parent node type
+ *
+ * When a node outputs an array and uses forEach, the itemFlow receives individual
+ * array items. This function returns which node types can accept those items.
+ *
+ * @param parentType - The node type that outputs the array (e.g., 'split', 'parse')
+ * @returns Array of node types that can start the forEach itemFlow
+ *
+ * @example
+ * ```typescript
+ * // split outputs SplitDocument[], itemFlow gets SplitDocument
+ * getValidForEachStarters('split')  // ['parse', 'extract', 'categorize', 'trigger']
+ *
+ * // parse(chunked:true) outputs DocumentIR[], itemFlow gets DocumentIR
+ * getValidForEachStarters('parse')  // ['categorize', 'extract', 'chunk']
+ * ```
+ */
+declare function getValidForEachStarters(parentType: NodeTypeName): NodeTypeName[];
+/**
+ * Validate if a node type can start a forEach itemFlow for a given parent
+ *
+ * @param parentType - The node type that outputs the array (e.g., 'split')
+ * @param starterType - The node type to validate as itemFlow starter
+ * @returns ValidationResult with detailed error messages and suggestions
+ *
+ * @example
+ * ```typescript
+ * // Valid: split → forEach → parse
+ * canStartForEachItemFlow('split', 'parse')  // { valid: true }
+ *
+ * // Invalid: split → forEach → chunk
+ * canStartForEachItemFlow('split', 'chunk')
+ * // {
+ * //   valid: false,
+ * //   reason: 'chunk cannot start forEach itemFlow after split...',
+ * //   suggestions: ['Valid starters: parse, extract, categorize, trigger']
+ * // }
+ * ```
+ */
+declare function canStartForEachItemFlow(parentType: NodeTypeName, starterType: NodeTypeName): ValidationResult;
+/**
+ * JSON Schema node structure for validation.
+ * Represents a node in a JSON Schema definition.
+ */
+interface JSONSchemaNode {
+    type?: string | string[];
+    properties?: Record<string, JSONSchemaNode>;
+    items?: JSONSchemaNode | JSONSchemaNode[];
+    required?: string[];
+    enum?: (string | number | boolean | null)[];
+    nullable?: boolean;
+    anyOf?: JSONSchemaNode[];
+    oneOf?: JSONSchemaNode[];
+    allOf?: JSONSchemaNode[];
+    const?: unknown;
+    additionalProperties?: boolean | JSONSchemaNode;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    pattern?: string;
+    format?: string;
+    description?: string;
+    default?: unknown;
+    $ref?: string;
+}
+/**
+ * Lightweight JSON Schema validator for Edge Runtime compatibility
+ *
+ * Validates data against a JSON Schema without using AJV's code generation.
+ * This is fully Edge Runtime compatible with zero dependencies.
+ *
+ * @param data - The data to validate
+ * @param schema - JSON Schema object (plain object, not AJV JSONSchemaType)
+ * @returns The validated data cast to type T
+ * @throws Error if validation fails
+ */
+declare function validateJson<T>(data: unknown, schema: JSONSchemaNode): T;
+/**
+ * Reserved variables that are auto-injected per node type.
+ * These variables come from config or computed data and cannot be overridden by users.
+ */
+declare const RESERVED_VARIABLES: {
+    readonly extract: readonly ["schema", "documentText", "schemaTitle", "schemaDescription", "structuredFormat"];
+    readonly categorize: readonly ["categories", "documentText"];
+    readonly parse: readonly ["format", "schema", "describeFigures", "citationsEnabled"];
+};
+/**
+ * Validates that user-provided promptVariables don't attempt to override reserved variables.
+ * Emits console warnings if reserved variables are found in user variables and removes them.
+ *
+ * @param nodeType - The type of node (extract, categorize, parse)
+ * @param userVariables - The user-provided promptVariables object
+ * @param autoInjectedVariables - The auto-injected variables object
+ * @returns A cleaned variables object with reserved variables protected
+ */
+declare function protectReservedVariables(nodeType: 'extract' | 'categorize' | 'parse', userVariables: Record<string, any> | undefined, autoInjectedVariables: Record<string, any>): Record<string, any>;
+
+export { type ExtractedImage as $, type AccessMethod as A, type BBox as B, type ConsensusConfig as C, type DocumentIR as D, type ExtractNodeConfig as E, type FieldVotingDetails as F, type FlowContext as G, type NodeCtx as H, type IRLine as I, type NodeTypeInfo as J, type NodeDef as K, type LLMProvider as L, type MultimodalInput as M, type NormalizedBBox as N, type OCRProvider as O, type ProviderVendor as P, type NodeTypeName as Q, type ReasoningConfig as R, type SplitDocument as S, type CompatibilityRule as T, type ValidationResult as U, type VLMProvider as V, type JSONSchemaNode as W, type ProcessingMode as X, type PageRangeOptions as Y, type LanguageOptions as Z, type SegmentationResult as _, type IRPage as a, type OCRProviderOptions as a0, type VLMProviderOptions as a1, type ProviderCitation as a2, aggregateMetrics as a3, node as a4, runPipeline as a5, FlowExecutionError as a6, FlowValidationError as a7, NODE_COMPATIBILITY_MATRIX as a8, getNodeTypeName as a9, getNodeTypeInfo as aa, getCompatibleTargets as ab, getSuggestedConnections as ac, validateNodeConnection as ad, getValidForEachStarters as ae, canStartForEachItemFlow as af, validateJson as ag, RESERVED_VARIABLES as ah, protectReservedVariables as ai, type ProviderIdentity as aj, toProviderString as ak, parseProviderString as al, isLocalEndpoint as am, createIdentity as an, type SupportedMimeType as ao, type TraceContextLite as ap, type NodeObservabilityContext as aq, type DocumentIRExtras as b, type LLMJsonProvider as c, type ConsensusRunResult as d, type ConsensusMetadata as e, type OutputWithConsensus as f, type MaybeWithConsensusMetadata as g, type FlowInput as h, type FlowInputValidation as i, type FlowResult as j, type CitationSourceType as k, type LineCitation as l, type FieldCitation as m, type CitationConfig as n, type OutputWithCitations as o, type ParseNodeConfig as p, type SplitNodeConfig as q, type CategorizeNodeConfig as r, type ChunkMetadata as s, type ChunkOutput as t, type ChunkNodeConfig as u, type CombineNodeConfig as v, type OutputNodeConfig as w, type EnhancedExtractionSchema as x, type StepMetric as y, type AggregatedMetrics as z };