@okrapdf/cli 0.1.2 → 0.1.4

package/dist/lib/scorer.d.ts

@@ -0,0 +1,305 @@
+/**
+ * OCR Review Scorer - Deterministic scoring for prioritizing page review
+ *
+ * Composable scoring strategies inspired by document understanding research:
+ * - Direct scoring: page-level metrics only
+ * - Structure-aware: considers table density and layout
+ * - Comparison-based: OCR layer vs rendered markdown
+ *
+ * Financial verification strategies from industry best practices:
+ * - Cross-querying: verify related fields match (e.g., Assets = Liabilities + Equity)
+ * - Check-sum logic: validate mathematical relationships between cells
+ * - Confidence filtering: auto-approve >95%, spot-check 70-95%, manual <70%
+ * - Anomaly detection: flag statistical outliers (e.g., decimal point errors)
+ *
+ * @see https://arxiv.org/html/2510.10138v1
+ */
+export interface PageData {
+    page: number;
+    status: string;
+    total: number;
+    verified: number;
+    pending: number;
+    flagged: number;
+    rejected: number;
+    avgConfidence: number;
+    hasOcr: boolean;
+    ocrLineCount: number;
+    hasCoverageGaps: boolean;
+    uncoveredCount: number;
+    resolution: string | null;
+    classification: string | null;
+    isStale: boolean;
+}
+export interface TableData {
+    id: string;
+    page_number: number;
+    markdown: string;
+    verification_status: string;
+    confidence?: number;
+}
+export interface OcrBlock {
+    text: string;
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    confidence?: number;
+}
+export interface ScoredPage {
+    page: number;
+    score: number;
+    breakdown: ScoreBreakdown;
+    tableCount: number;
+    avgConfidence: number;
+    status: string;
+    flags: string[];
+}
+export interface ScoreBreakdown {
+    tableScore: number;
+    confidenceScore: number;
+    coverageScore: number;
+    flaggedScore: number;
+    structureScore: number;
+    comparisonScore: number;
+}
+export interface ScorerConfig {
+    weights: ScorerWeights;
+    thresholds: ScorerThresholds;
+}
+export interface ScorerWeights {
+    tableCount: number;
+    inverseConfidence: number;
+    coverageGap: number;
+    flaggedEntity: number;
+    structurePenalty: number;
+    comparisonDelta: number;
+}
+export interface ScorerThresholds {
+    autoApproveConfidence: number;
+    requireReviewConfidence: number;
+    maxTablesForAutoApprove: number;
+    minOcrLinesForContent: number;
+}
+export interface FilterOptions {
+    status?: string | string[];
+    minConfidence?: number;
+    maxConfidence?: number;
+    minTables?: number;
+    maxTables?: number;
+    hasGaps?: boolean;
+    hasTables?: boolean;
+    isStale?: boolean;
+}
+export interface ReviewStats {
+    totalPages: number;
+    pagesWithTables: number;
+    totalTables: number;
+    avgConfidence: number;
+    lowConfidencePages: number;
+    pagesWithGaps: number;
+    byStatus: Record<string, number>;
+    byPriority: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    estimatedReviewTime: {
+        pages: number;
+        minutes: number;
+    };
+}
+export interface ComparisonResult {
+    page: number;
+    ocrCharCount: number;
+    markdownCharCount: number;
+    delta: number;
+    deltaPct: number;
+    spatialIntegrity: number;
+    tableStructureScore: number;
+    flags: string[];
+}
+export declare const DEFAULT_CONFIG: ScorerConfig;
+export declare class OcrReviewScorer {
+    private config;
+    private tablesByPage;
+    constructor(config?: Partial<ScorerConfig>);
+    /**
+     * Load table data for scoring
+     */
+    loadTables(tables: TableData[]): void;
+    /**
+     * Score a single page - deterministic priority calculation
+     */
+    scorePage(page: PageData): ScoredPage;
+    /**
+     * Score all pages and return sorted by priority (highest first)
+     */
+    scoreAll(pages: PageData[]): ScoredPage[];
+    /**
+     * Filter pages by criteria before scoring
+     */
+    filter(pages: PageData[], options: FilterOptions): PageData[];
+    /**
+     * Get pages eligible for auto-approval
+     */
+    getAutoApprovable(pages: PageData[]): PageData[];
+    /**
+     * Get pages that require human review
+     */
+    getRequireReview(pages: PageData[]): ScoredPage[];
+    /**
+     * Compute review statistics
+     */
+    computeStats(pages: PageData[]): ReviewStats;
+}
+/**
+ * Compare OCR text blocks to rendered markdown for quality assessment
+ * Inspired by spatial structure preservation evaluation
+ */
+export declare function compareOcrToMarkdown(ocrBlocks: OcrBlock[], markdownContent: string): ComparisonResult & {
+    score: number;
+};
+export type ScoringStrategy = 'direct' | 'structure' | 'comparison' | 'combined';
+/**
+ * Create a scorer with a specific strategy
+ */
+export declare function createScorer(strategy: ScoringStrategy, config?: Partial<ScorerConfig>): OcrReviewScorer;
+/**
+ * Parse pages JSON from CLI output
+ */
+export declare function parsePagesJson(json: string): PageData[];
+/**
+ * Parse tables JSON from CLI output
+ */
+export declare function parseTablesJson(json: string): TableData[];
+/**
+ * Format scored pages for output
+ */
+export declare function formatScoredPages(pages: ScoredPage[], format?: 'json' | 'jsonl' | 'table' | 'csv'): string;
+/**
+ * Format stats for output
+ */
+export declare function formatStats(stats: ReviewStats, format?: 'json' | 'table'): string;
+/**
+ * Confidence-based filtering thresholds
+ * Based on industry best practices for financial document verification
+ */
+export declare const CONFIDENCE_TIERS: {
+    readonly AUTO_APPROVE: 0.95;
+    readonly SPOT_CHECK: 0.7;
+    readonly MANUAL_REVIEW: 0.7;
+};
+export type ConfidenceTier = 'auto_approve' | 'spot_check' | 'manual_review';
+/**
+ * Categorize a confidence score into action tiers
+ */
+export declare function getConfidenceTier(confidence: number): ConfidenceTier;
+/**
+ * Batch categorize pages by confidence tier
+ */
+export declare function categorizeByConfidence(pages: PageData[]): Record<ConfidenceTier, PageData[]>;
+/**
+ * Financial value extracted from a table cell
+ */
+export interface FinancialValue {
+    label: string;
+    value: number;
+    page: number;
+    tableId?: string;
+    confidence?: number;
+}
+/**
+ * Check-sum validation rule
+ */
+export interface CheckSumRule {
+    name: string;
+    formula: string;
+    fields: string[];
+    validate: (values: Record<string, number>) => CheckSumResult;
+}
+export interface CheckSumResult {
+    passed: boolean;
+    expected: number;
+    actual: number;
+    difference: number;
+    tolerancePct: number;
+}
+/**
+ * Common financial check-sum rules
+ */
+export declare const FINANCIAL_CHECKSUMS: CheckSumRule[];
+/**
+ * Run all applicable check-sum validations on extracted values
+ */
+export declare function runCheckSums(values: Record<string, number>, rules?: CheckSumRule[]): Array<{
+    rule: CheckSumRule;
+    result: CheckSumResult;
+}>;
+/**
+ * Anomaly detection result
+ */
+export interface AnomalyResult {
+    field: string;
+    currentValue: number;
+    historicalMean: number;
+    historicalStdDev: number;
+    zScore: number;
+    isAnomaly: boolean;
+    possibleCause: string;
+}
+/**
+ * Detect anomalies in extracted values using statistical analysis
+ * Flags potential OCR errors like decimal point shifts
+ */
+export declare function detectAnomalies(currentValues: Record<string, number>, historicalValues: Array<Record<string, number>>, zScoreThreshold?: number): AnomalyResult[];
+/**
+ * Cross-query validation - verify related fields match
+ * e.g., verify Total = Sum of components
+ */
+export interface CrossQueryRule {
+    name: string;
+    totalField: string;
+    componentFields: string[];
+    tolerance: number;
+}
+export declare const CROSS_QUERY_RULES: CrossQueryRule[];
+export interface CrossQueryResult {
+    rule: CrossQueryRule;
+    passed: boolean;
+    totalValue: number;
+    componentSum: number;
+    difference: number;
+    differencePercent: number;
+    presentComponents: string[];
+}
+/**
+ * Validate that total fields match sum of their components
+ */
+export declare function validateCrossQuery(values: Record<string, number>, rules?: CrossQueryRule[]): CrossQueryResult[];
+/**
+ * Complete financial verification result
+ */
+export interface VerificationReport {
+    confidenceTier: ConfidenceTier;
+    checkSums: Array<{
+        rule: CheckSumRule;
+        result: CheckSumResult;
+    }>;
+    anomalies: AnomalyResult[];
+    crossQueries: CrossQueryResult[];
+    overallStatus: 'pass' | 'warning' | 'fail';
+    issues: string[];
+    recommendations: string[];
+}
+/**
+ * Run comprehensive financial verification
+ */
+export declare function runFinancialVerification(extractedValues: Record<string, number>, confidence: number, historicalValues?: Array<Record<string, number>>): VerificationReport;
+/**
+ * Format verification report for display
+ */
+export declare function formatVerificationReport(report: VerificationReport): string;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/lib/scorer.d.ts.map

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