@heripo/model 0.1.25 → 0.1.27

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/language/bcp47-language-tag.ts","../src/language/language-display.ts"],"sourcesContent":["// Language utilities\nexport type * from './language/bcp47-language-tag';\nexport {\n  BCP47_LANGUAGE_TAGS,\n  BCP47_LANGUAGE_TAG_SET,\n  isValidBcp47Tag,\n  normalizeToBcp47,\n} from './language/bcp47-language-tag';\nexport {\n  LANGUAGE_DISPLAY_NAMES,\n  buildLanguageDescription,\n  getLanguageDisplayName,\n} from './language/language-display';\n\n// Type definitions\nexport type * from './types/docling-document';\nexport type * from './types/document-process-result';\nexport type * from './types/ocr-strategy';\nexport type * from './types/processed-document';\nexport type * from './types/token-usage-report';\n","/**\n * Language tags supported by the ocrmac OCR engine (via docling-serve).\n * These are the only tags that can be passed to the Docling pipeline without\n * triggering \"Invalid language preference\" errors.\n */\nexport const BCP47_LANGUAGE_TAGS = [\n  'ar-SA',\n  'ars-SA',\n  'cs-CZ',\n  'da-DK',\n  'de-DE',\n  'en-US',\n  'es-ES',\n  'fr-FR',\n  'id-ID',\n  'it-IT',\n  'ja-JP',\n  'ko-KR',\n  'ms-MY',\n  'nb-NO',\n  'nl-NL',\n  'nn-NO',\n  'no-NO',\n  'pl-PL',\n  'pt-BR',\n  'ro-RO',\n  'ru-RU',\n  'sv-SE',\n  'th-TH',\n  'tr-TR',\n  'uk-UA',\n  'vi-VT',\n  'yue-Hans',\n  'yue-Hant',\n  'zh-Hans',\n  'zh-Hant',\n] as const;\n\n/** Union type of all supported BCP 47 language tags */\nexport type Bcp47LanguageTag = (typeof BCP47_LANGUAGE_TAGS)[number];\n\n/** Set for O(1) lookup of valid BCP 47 tags */\nexport const BCP47_LANGUAGE_TAG_SET: ReadonlySet<string> = new Set(\n  BCP47_LANGUAGE_TAGS,\n);\n\n/** Check whether a string is a valid BCP 47 language tag */\nexport function isValidBcp47Tag(tag: string): tag is Bcp47LanguageTag {\n  return BCP47_LANGUAGE_TAG_SET.has(tag);\n}\n\n/**\n * Maps bare language codes to their default BCP 47 tag.\n * Used when VLM returns only a language code without a region subtag.\n */\nconst DEFAULT_REGION_MAP: Record<string, Bcp47LanguageTag> = {\n  ar: 'ar-SA',\n  cs: 'cs-CZ',\n  da: 'da-DK',\n  de: 'de-DE',\n  en: 'en-US',\n  es: 'es-ES',\n  fr: 'fr-FR',\n  id: 'id-ID',\n  it: 'it-IT',\n  ja: 'ja-JP',\n  ko: 'ko-KR',\n  ms: 'ms-MY',\n  nl: 'nl-NL',\n  no: 'no-NO',\n  pl: 'pl-PL',\n  pt: 'pt-BR',\n  ro: 'ro-RO',\n  ru: 'ru-RU',\n  sv: 'sv-SE',\n  th: 'th-TH',\n  tr: 'tr-TR',\n  uk: 'uk-UA',\n  vi: 'vi-VT',\n  zh: 'zh-Hans',\n};\n\n/**\n * Normalize a language string to a valid BCP 47 tag.\n *\n * - If the input is already a valid full tag (e.g. \"en-US\"), return it as-is.\n * - If it is a bare language code (e.g. \"en\", \"ko\"), map it to the default region.\n * - Otherwise return null (e.g. \"und\", \"unknown\", empty string).\n */\nexport function normalizeToBcp47(tag: string): Bcp47LanguageTag | null {\n  if (isValidBcp47Tag(tag)) {\n    return tag;\n  }\n\n  const lower = tag.toLowerCase();\n  const mapped = DEFAULT_REGION_MAP[lower];\n  if (mapped) {\n    return mapped;\n  }\n\n  return null;\n}\n","/** Language display names for prompt context (keyed by ISO 639-1 base language code) */\nexport const LANGUAGE_DISPLAY_NAMES: Record<string, string> = {\n  ko: 'Korean (한국어)',\n  ja: 'Japanese (日本語)',\n  zh: 'Chinese (中文)',\n  en: 'English',\n  fr: 'French (Français)',\n  de: 'German (Deutsch)',\n  es: 'Spanish (Español)',\n  pt: 'Portuguese (Português)',\n  ru: 'Russian (Русский)',\n  uk: 'Ukrainian (Українська)',\n  it: 'Italian (Italiano)',\n};\n\n/**\n * Get human-readable display name for a BCP 47 or ISO 639-1 language code.\n */\nexport function getLanguageDisplayName(code?: string): string {\n  if (!code) return 'unknown';\n  const baseCode = code.split('-')[0];\n  return LANGUAGE_DISPLAY_NAMES[baseCode] ?? code;\n}\n\n/**\n * Build language description string from document languages.\n * @returns e.g. \"primarily written in Korean (한국어), with English also present\"\n */\nexport function buildLanguageDescription(documentLanguages: string[]): string {\n  const primaryName = getLanguageDisplayName(documentLanguages[0]);\n  const otherNames = documentLanguages\n    .slice(1)\n    .map((code) => getLanguageDisplayName(code));\n  return otherNames.length > 0\n    ? `primarily written in ${primaryName}, with ${otherNames.join(', ')} also present`\n    : `written in ${primaryName}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAMO,IAAM,yBAA8C,IAAI;AAAA,EAC7D;AACF;AAGO,SAAS,gBAAgB,KAAsC;AACpE,SAAO,uBAAuB,IAAI,GAAG;AACvC;AAMA,IAAM,qBAAuD;AAAA,EAC3D,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AASO,SAAS,iBAAiB,KAAsC;AACrE,MAAI,gBAAgB,GAAG,GAAG;AACxB,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,IAAI,YAAY;AAC9B,QAAM,SAAS,mBAAmB,KAAK;AACvC,MAAI,QAAQ;AACV,WAAO;AAAA,EACT;AAEA,SAAO;AACT;;;ACpGO,IAAM,yBAAiD;AAAA,EAC5D,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAKO,SAAS,uBAAuB,MAAuB;AAC5D,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,WAAW,KAAK,MAAM,GAAG,EAAE,CAAC;AAClC,SAAO,uBAAuB,QAAQ,KAAK;AAC7C;AAMO,SAAS,yBAAyB,mBAAqC;AAC5E,QAAM,cAAc,uBAAuB,kBAAkB,CAAC,CAAC;AAC/D,QAAM,aAAa,kBAChB,MAAM,CAAC,EACP,IAAI,CAAC,SAAS,uBAAuB,IAAI,CAAC;AAC7C,SAAO,WAAW,SAAS,IACvB,wBAAwB,WAAW,UAAU,WAAW,KAAK,IAAI,CAAC,kBAClE,cAAc,WAAW;AAC/B;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/language/bcp47-language-tag.ts","../src/language/language-display.ts"],"sourcesContent":["// Language utilities\nexport type * from './language/bcp47-language-tag';\nexport {\n  BCP47_LANGUAGE_TAGS,\n  BCP47_LANGUAGE_TAG_SET,\n  isValidBcp47Tag,\n  normalizeToBcp47,\n} from './language/bcp47-language-tag';\nexport {\n  LANGUAGE_DISPLAY_NAMES,\n  buildLanguageDescription,\n  getLanguageDisplayName,\n} from './language/language-display';\n\n// Type definitions\nexport type * from './types/docling-document';\nexport type * from './types/document-process-result';\nexport type * from './types/ocr-strategy';\nexport type * from './types/processed-document';\nexport type * from './types/review-assistance';\nexport type * from './types/token-usage-report';\n","/**\n * Language tags supported by the ocrmac OCR engine (via docling-serve).\n * These are the only tags that can be passed to the Docling pipeline without\n * triggering \"Invalid language preference\" errors.\n */\nexport const BCP47_LANGUAGE_TAGS = [\n  'ar-SA',\n  'ars-SA',\n  'cs-CZ',\n  'da-DK',\n  'de-DE',\n  'en-US',\n  'es-ES',\n  'fr-FR',\n  'id-ID',\n  'it-IT',\n  'ja-JP',\n  'ko-KR',\n  'ms-MY',\n  'nb-NO',\n  'nl-NL',\n  'nn-NO',\n  'no-NO',\n  'pl-PL',\n  'pt-BR',\n  'ro-RO',\n  'ru-RU',\n  'sv-SE',\n  'th-TH',\n  'tr-TR',\n  'uk-UA',\n  'vi-VT',\n  'yue-Hans',\n  'yue-Hant',\n  'zh-Hans',\n  'zh-Hant',\n] as const;\n\n/** Union type of all supported BCP 47 language tags */\nexport type Bcp47LanguageTag = (typeof BCP47_LANGUAGE_TAGS)[number];\n\n/** Set for O(1) lookup of valid BCP 47 tags */\nexport const BCP47_LANGUAGE_TAG_SET: ReadonlySet<string> = new Set(\n  BCP47_LANGUAGE_TAGS,\n);\n\n/** Check whether a string is a valid BCP 47 language tag */\nexport function isValidBcp47Tag(tag: string): tag is Bcp47LanguageTag {\n  return BCP47_LANGUAGE_TAG_SET.has(tag);\n}\n\n/**\n * Maps bare language codes to their default BCP 47 tag.\n * Used when VLM returns only a language code without a region subtag.\n */\nconst DEFAULT_REGION_MAP: Record<string, Bcp47LanguageTag> = {\n  ar: 'ar-SA',\n  cs: 'cs-CZ',\n  da: 'da-DK',\n  de: 'de-DE',\n  en: 'en-US',\n  es: 'es-ES',\n  fr: 'fr-FR',\n  id: 'id-ID',\n  it: 'it-IT',\n  ja: 'ja-JP',\n  ko: 'ko-KR',\n  ms: 'ms-MY',\n  nl: 'nl-NL',\n  no: 'no-NO',\n  pl: 'pl-PL',\n  pt: 'pt-BR',\n  ro: 'ro-RO',\n  ru: 'ru-RU',\n  sv: 'sv-SE',\n  th: 'th-TH',\n  tr: 'tr-TR',\n  uk: 'uk-UA',\n  vi: 'vi-VT',\n  zh: 'zh-Hans',\n};\n\n/**\n * Normalize a language string to a valid BCP 47 tag.\n *\n * - If the input is already a valid full tag (e.g. \"en-US\"), return it as-is.\n * - If it is a bare language code (e.g. \"en\", \"ko\"), map it to the default region.\n * - Otherwise return null (e.g. \"und\", \"unknown\", empty string).\n */\nexport function normalizeToBcp47(tag: string): Bcp47LanguageTag | null {\n  if (isValidBcp47Tag(tag)) {\n    return tag;\n  }\n\n  const lower = tag.toLowerCase();\n  const mapped = DEFAULT_REGION_MAP[lower];\n  if (mapped) {\n    return mapped;\n  }\n\n  return null;\n}\n","/** Language display names for prompt context (keyed by ISO 639-1 base language code) */\nexport const LANGUAGE_DISPLAY_NAMES: Record<string, string> = {\n  ko: 'Korean (한국어)',\n  ja: 'Japanese (日本語)',\n  zh: 'Chinese (中文)',\n  en: 'English',\n  fr: 'French (Français)',\n  de: 'German (Deutsch)',\n  es: 'Spanish (Español)',\n  pt: 'Portuguese (Português)',\n  ru: 'Russian (Русский)',\n  uk: 'Ukrainian (Українська)',\n  it: 'Italian (Italiano)',\n};\n\n/**\n * Get human-readable display name for a BCP 47 or ISO 639-1 language code.\n */\nexport function getLanguageDisplayName(code?: string): string {\n  if (!code) return 'unknown';\n  const baseCode = code.split('-')[0];\n  return LANGUAGE_DISPLAY_NAMES[baseCode] ?? code;\n}\n\n/**\n * Build language description string from document languages.\n * @returns e.g. \"primarily written in Korean (한국어), with English also present\"\n */\nexport function buildLanguageDescription(documentLanguages: string[]): string {\n  const primaryName = getLanguageDisplayName(documentLanguages[0]);\n  const otherNames = documentLanguages\n    .slice(1)\n    .map((code) => getLanguageDisplayName(code));\n  return otherNames.length > 0\n    ? `primarily written in ${primaryName}, with ${otherNames.join(', ')} also present`\n    : `written in ${primaryName}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAMO,IAAM,yBAA8C,IAAI;AAAA,EAC7D;AACF;AAGO,SAAS,gBAAgB,KAAsC;AACpE,SAAO,uBAAuB,IAAI,GAAG;AACvC;AAMA,IAAM,qBAAuD;AAAA,EAC3D,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AASO,SAAS,iBAAiB,KAAsC;AACrE,MAAI,gBAAgB,GAAG,GAAG;AACxB,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,IAAI,YAAY;AAC9B,QAAM,SAAS,mBAAmB,KAAK;AACvC,MAAI,QAAQ;AACV,WAAO;AAAA,EACT;AAEA,SAAO;AACT;;;ACpGO,IAAM,yBAAiD;AAAA,EAC5D,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAKO,SAAS,uBAAuB,MAAuB;AAC5D,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,WAAW,KAAK,MAAM,GAAG,EAAE,CAAC;AAClC,SAAO,uBAAuB,QAAQ,KAAK;AAC7C;AAMO,SAAS,yBAAyB,mBAAqC;AAC5E,QAAM,cAAc,uBAAuB,kBAAkB,CAAC,CAAC;AAC/D,QAAM,aAAa,kBAChB,MAAM,CAAC,EACP,IAAI,CAAC,SAAS,uBAAuB,IAAI,CAAC;AAC7C,SAAO,WAAW,SAAS,IACvB,wBAAwB,WAAW,UAAU,WAAW,KAAK,IAAI,CAAC,kBAClE,cAAc,WAAW;AAC/B;","names":[]}

package/dist/index.d.cts

@@ -649,6 +649,12 @@ interface PhaseUsageReport {
      * If only primary or only fallback is present, equals that model's usage.
      */
     total: TokenUsageSummary;
+    /**
+     * Metadata for individual LLM calls aggregated into this phase.
+     *
+     * Examples: pageNo, commandCount, autoAppliedCount, proposalCount
+     */
+    metadata?: TokenUsageMetadata[];
 }
 /**
  * Detailed usage for a specific model
@@ -701,6 +707,8 @@ interface TokenUsageSummary {
      */
     totalTokens: number;
 }
+type TokenUsageMetadataValue = string | number | boolean | null;
+type TokenUsageMetadata = Record<string, TokenUsageMetadataValue>;
 
 /**
  * Result type for document processing operation
@@ -752,4 +760,194 @@ interface OcrStrategy {
     koreanHanjaMixPages?: number[];
 }
 
-export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type TextBlock, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };
+type ReviewAssistanceReportSchemaName = 'HeripoReviewAssistanceReport';
+type ReviewAssistanceReportVersion = '1.0';
+type ReviewAssistanceDisposition = 'auto_applied' | 'proposal' | 'skipped';
+type ReviewAssistanceFailurePolicy = 'partial_page';
+type ReviewAssistancePageStatus = 'succeeded' | 'failed';
+type ReviewAssistanceIssueCategory = 'text' | 'table' | 'caption' | 'picture' | 'reading_order' | 'role' | 'text_integrity' | 'paragraph' | 'footnote' | 'bbox' | 'multi_page_table' | 'domain_pattern' | 'review_execution';
+type ReviewAssistanceIssueSeverity = 'info' | 'warning' | 'error';
+type ReviewAssistanceProgressSubstage = 'review-assistance:prepare' | 'review-assistance:page' | 'review-assistance:patch' | 'review-assistance:write-report';
+type ReviewAssistanceProgressStatus = 'started' | 'progress' | 'completed' | 'failed';
+interface ReviewAssistanceTableCell {
+    text: string;
+    bbox?: DoclingBBox;
+    rowSpan?: number;
+    colSpan?: number;
+    columnHeader?: boolean;
+    rowHeader?: boolean;
+}
+interface ReviewAssistanceImageRegion {
+    id?: string;
+    bbox: DoclingBBox;
+    imageUri?: string;
+    caption?: string;
+}
+type ReviewAssistanceCommand = {
+    op: 'replaceText';
+    textRef: string;
+    text: string;
+} | {
+    op: 'addText';
+    pageNo: number;
+    bbox: DoclingBBox;
+    text: string;
+    label: string;
+    afterRef?: string;
+} | {
+    op: 'updateTextRole';
+    textRef: string;
+    label: string;
+} | {
+    op: 'removeText';
+    textRef: string;
+} | {
+    op: 'mergeTexts';
+    textRefs: string[];
+    text: string;
+    keepRef: string;
+} | {
+    op: 'splitText';
+    textRef: string;
+    parts: Array<{
+        text: string;
+        label?: string;
+    }>;
+} | {
+    op: 'updateTableCell';
+    tableRef: string;
+    row: number;
+    col: number;
+    text: string;
+} | {
+    op: 'replaceTable';
+    tableRef: string;
+    grid: ReviewAssistanceTableCell[][];
+    caption?: string;
+} | {
+    op: 'linkContinuedTable';
+    sourceTableRef: string;
+    continuedTableRef: string;
+    relation: 'continues_on_next_page' | 'continued_from_previous_page';
+} | {
+    op: 'updatePictureCaption';
+    pictureRef: string;
+    caption: string;
+} | {
+    op: 'addPicture';
+    pageNo: number;
+    bbox: DoclingBBox;
+    imageUri: string;
+    caption?: string;
+} | {
+    op: 'splitPicture';
+    pictureRef: string;
+    regions: ReviewAssistanceImageRegion[];
+} | {
+    op: 'hidePicture';
+    pictureRef: string;
+    reason: string;
+} | {
+    op: 'updateBbox';
+    targetRef: string;
+    bbox: DoclingBBox;
+} | {
+    op: 'linkFootnote';
+    markerTextRef: string;
+    footnoteTextRef: string;
+} | {
+    op: 'moveNode';
+    sourceRef: string;
+    targetRef: string;
+    position: 'before' | 'after';
+};
+interface ReviewAssistanceDecisionEvidence {
+    imageEvidence?: string;
+    textLayerEvidence?: string;
+    suspectReasons?: string[];
+    previousBbox?: DoclingBBox;
+    snappedBbox?: DoclingBBox;
+    generatedRefs?: string[];
+}
+interface ReviewAssistanceDecision {
+    id: string;
+    pageNo: number;
+    /** Present only when validation produced a normalized command. */
+    command?: ReviewAssistanceCommand;
+    /** Original op when validation rejected the payload before normalization. */
+    invalidOp?: string;
+    confidence: number;
+    disposition: ReviewAssistanceDisposition;
+    reasons: string[];
+    evidence?: ReviewAssistanceDecisionEvidence;
+    metadata?: Record<string, unknown>;
+}
+interface ReviewAssistanceIssue {
+    id: string;
+    pageNo: number;
+    category: ReviewAssistanceIssueCategory;
+    type: string;
+    severity: ReviewAssistanceIssueSeverity;
+    description: string;
+    confidence?: number;
+    refs?: string[];
+    bbox?: DoclingBBox;
+    reasons?: string[];
+}
+interface ReviewAssistancePageResult {
+    pageNo: number;
+    status: ReviewAssistancePageStatus;
+    decisions: ReviewAssistanceDecision[];
+    issues: ReviewAssistanceIssue[];
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+interface ReviewAssistanceReport {
+    schemaName: ReviewAssistanceReportSchemaName;
+    version: ReviewAssistanceReportVersion;
+    reportId: string;
+    source: {
+        doclingResult: 'result.json';
+        ocrOriginSnapshot?: 'result_ocr_origin.json';
+        originSnapshot?: 'result_review_origin.json';
+    };
+    options: {
+        enabled: true;
+        concurrency: number;
+        autoApplyThreshold: number;
+        proposalThreshold: number;
+        maxRetries: number;
+        temperature: number;
+        outputLanguage: string;
+        failurePolicy: ReviewAssistanceFailurePolicy;
+    };
+    summary: {
+        pageCount: number;
+        pagesSucceeded: number;
+        pagesFailed: number;
+        autoAppliedCount: number;
+        proposalCount: number;
+        skippedCount: number;
+        issueCount: number;
+        layoutIssueCount?: number;
+        textIntegrityIssueCount?: number;
+    };
+    pages: ReviewAssistancePageResult[];
+}
+interface ReviewAssistanceProgressEvent {
+    substage: ReviewAssistanceProgressSubstage;
+    status: ReviewAssistanceProgressStatus;
+    reportId: string;
+    pageNo?: number;
+    pageCount?: number;
+    completedPages?: number;
+    failedPages?: number;
+    commandCount?: number;
+    autoAppliedCount?: number;
+    proposalCount?: number;
+    message?: string;
+}
+
+export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };

package/dist/index.d.ts

@@ -649,6 +649,12 @@ interface PhaseUsageReport {
      * If only primary or only fallback is present, equals that model's usage.
      */
     total: TokenUsageSummary;
+    /**
+     * Metadata for individual LLM calls aggregated into this phase.
+     *
+     * Examples: pageNo, commandCount, autoAppliedCount, proposalCount
+     */
+    metadata?: TokenUsageMetadata[];
 }
 /**
  * Detailed usage for a specific model
@@ -701,6 +707,8 @@ interface TokenUsageSummary {
      */
     totalTokens: number;
 }
+type TokenUsageMetadataValue = string | number | boolean | null;
+type TokenUsageMetadata = Record<string, TokenUsageMetadataValue>;
 
 /**
  * Result type for document processing operation
@@ -752,4 +760,194 @@ interface OcrStrategy {
     koreanHanjaMixPages?: number[];
 }
 
-export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type TextBlock, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };
+type ReviewAssistanceReportSchemaName = 'HeripoReviewAssistanceReport';
+type ReviewAssistanceReportVersion = '1.0';
+type ReviewAssistanceDisposition = 'auto_applied' | 'proposal' | 'skipped';
+type ReviewAssistanceFailurePolicy = 'partial_page';
+type ReviewAssistancePageStatus = 'succeeded' | 'failed';
+type ReviewAssistanceIssueCategory = 'text' | 'table' | 'caption' | 'picture' | 'reading_order' | 'role' | 'text_integrity' | 'paragraph' | 'footnote' | 'bbox' | 'multi_page_table' | 'domain_pattern' | 'review_execution';
+type ReviewAssistanceIssueSeverity = 'info' | 'warning' | 'error';
+type ReviewAssistanceProgressSubstage = 'review-assistance:prepare' | 'review-assistance:page' | 'review-assistance:patch' | 'review-assistance:write-report';
+type ReviewAssistanceProgressStatus = 'started' | 'progress' | 'completed' | 'failed';
+interface ReviewAssistanceTableCell {
+    text: string;
+    bbox?: DoclingBBox;
+    rowSpan?: number;
+    colSpan?: number;
+    columnHeader?: boolean;
+    rowHeader?: boolean;
+}
+interface ReviewAssistanceImageRegion {
+    id?: string;
+    bbox: DoclingBBox;
+    imageUri?: string;
+    caption?: string;
+}
+type ReviewAssistanceCommand = {
+    op: 'replaceText';
+    textRef: string;
+    text: string;
+} | {
+    op: 'addText';
+    pageNo: number;
+    bbox: DoclingBBox;
+    text: string;
+    label: string;
+    afterRef?: string;
+} | {
+    op: 'updateTextRole';
+    textRef: string;
+    label: string;
+} | {
+    op: 'removeText';
+    textRef: string;
+} | {
+    op: 'mergeTexts';
+    textRefs: string[];
+    text: string;
+    keepRef: string;
+} | {
+    op: 'splitText';
+    textRef: string;
+    parts: Array<{
+        text: string;
+        label?: string;
+    }>;
+} | {
+    op: 'updateTableCell';
+    tableRef: string;
+    row: number;
+    col: number;
+    text: string;
+} | {
+    op: 'replaceTable';
+    tableRef: string;
+    grid: ReviewAssistanceTableCell[][];
+    caption?: string;
+} | {
+    op: 'linkContinuedTable';
+    sourceTableRef: string;
+    continuedTableRef: string;
+    relation: 'continues_on_next_page' | 'continued_from_previous_page';
+} | {
+    op: 'updatePictureCaption';
+    pictureRef: string;
+    caption: string;
+} | {
+    op: 'addPicture';
+    pageNo: number;
+    bbox: DoclingBBox;
+    imageUri: string;
+    caption?: string;
+} | {
+    op: 'splitPicture';
+    pictureRef: string;
+    regions: ReviewAssistanceImageRegion[];
+} | {
+    op: 'hidePicture';
+    pictureRef: string;
+    reason: string;
+} | {
+    op: 'updateBbox';
+    targetRef: string;
+    bbox: DoclingBBox;
+} | {
+    op: 'linkFootnote';
+    markerTextRef: string;
+    footnoteTextRef: string;
+} | {
+    op: 'moveNode';
+    sourceRef: string;
+    targetRef: string;
+    position: 'before' | 'after';
+};
+interface ReviewAssistanceDecisionEvidence {
+    imageEvidence?: string;
+    textLayerEvidence?: string;
+    suspectReasons?: string[];
+    previousBbox?: DoclingBBox;
+    snappedBbox?: DoclingBBox;
+    generatedRefs?: string[];
+}
+interface ReviewAssistanceDecision {
+    id: string;
+    pageNo: number;
+    /** Present only when validation produced a normalized command. */
+    command?: ReviewAssistanceCommand;
+    /** Original op when validation rejected the payload before normalization. */
+    invalidOp?: string;
+    confidence: number;
+    disposition: ReviewAssistanceDisposition;
+    reasons: string[];
+    evidence?: ReviewAssistanceDecisionEvidence;
+    metadata?: Record<string, unknown>;
+}
+interface ReviewAssistanceIssue {
+    id: string;
+    pageNo: number;
+    category: ReviewAssistanceIssueCategory;
+    type: string;
+    severity: ReviewAssistanceIssueSeverity;
+    description: string;
+    confidence?: number;
+    refs?: string[];
+    bbox?: DoclingBBox;
+    reasons?: string[];
+}
+interface ReviewAssistancePageResult {
+    pageNo: number;
+    status: ReviewAssistancePageStatus;
+    decisions: ReviewAssistanceDecision[];
+    issues: ReviewAssistanceIssue[];
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+interface ReviewAssistanceReport {
+    schemaName: ReviewAssistanceReportSchemaName;
+    version: ReviewAssistanceReportVersion;
+    reportId: string;
+    source: {
+        doclingResult: 'result.json';
+        ocrOriginSnapshot?: 'result_ocr_origin.json';
+        originSnapshot?: 'result_review_origin.json';
+    };
+    options: {
+        enabled: true;
+        concurrency: number;
+        autoApplyThreshold: number;
+        proposalThreshold: number;
+        maxRetries: number;
+        temperature: number;
+        outputLanguage: string;
+        failurePolicy: ReviewAssistanceFailurePolicy;
+    };
+    summary: {
+        pageCount: number;
+        pagesSucceeded: number;
+        pagesFailed: number;
+        autoAppliedCount: number;
+        proposalCount: number;
+        skippedCount: number;
+        issueCount: number;
+        layoutIssueCount?: number;
+        textIntegrityIssueCount?: number;
+    };
+    pages: ReviewAssistancePageResult[];
+}
+interface ReviewAssistanceProgressEvent {
+    substage: ReviewAssistanceProgressSubstage;
+    status: ReviewAssistanceProgressStatus;
+    reportId: string;
+    pageNo?: number;
+    pageCount?: number;
+    completedPages?: number;
+    failedPages?: number;
+    commandCount?: number;
+    autoAppliedCount?: number;
+    proposalCount?: number;
+    message?: string;
+}
+
+export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@heripo/model",
   "private": false,
   "type": "module",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Document models and type definitions for heripo engine",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -52,12 +52,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.5",
     "tsup": "^8.5.1",
-    "vitest": "^4.1.4",
+    "vitest": "^4.1.5",
     "@heripo/tsconfig": "0.0.0",
-    "@heripo/tsup-config": "0.0.0",
-    "@heripo/vitest-config": "0.0.0"
+    "@heripo/vitest-config": "0.0.0",
+    "@heripo/tsup-config": "0.0.0"
   },
   "scripts": {
     "clean": "rimraf dist",