@doclo/providers-llm 0.1.6 → 0.1.8

package/dist/chunk-7YPJIWRM.js

@@ -0,0 +1,291 @@
+// src/schema-prompt-formatter.ts
+function formatSchemaForPrompt(schema, indent = 0) {
+  if (!schema || typeof schema !== "object") {
+    return "";
+  }
+  const indentStr = "  ".repeat(indent);
+  let result = "";
+  if (schema.type === "object" && schema.properties) {
+    const properties = schema.properties;
+    const required = schema.required || [];
+    for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+      const isRequired = required.includes(fieldName);
+      const requiredMarker = isRequired ? " (REQUIRED)" : " (optional)";
+      result += `${indentStr}- \`${fieldName}\`${requiredMarker}`;
+      const type = getTypeDescription(fieldSchema);
+      if (type) {
+        result += `: ${type}`;
+      }
+      if (fieldSchema.description) {
+        result += `
+${indentStr}  ${fieldSchema.description}`;
+      }
+      if (fieldSchema.enum) {
+        result += `
+${indentStr}  Allowed values: ${fieldSchema.enum.map((v) => JSON.stringify(v)).join(", ")}`;
+      }
+      result += "\n";
+      if (fieldSchema.type === "object" && fieldSchema.properties) {
+        result += formatSchemaForPrompt(fieldSchema, indent + 1);
+      }
+      if (fieldSchema.type === "array" && fieldSchema.items) {
+        result += `${indentStr}  Array items:
+`;
+        const itemSchema = Array.isArray(fieldSchema.items) ? fieldSchema.items[0] : fieldSchema.items;
+        if (itemSchema && itemSchema.type === "object" && itemSchema.properties) {
+          result += formatSchemaForPrompt(itemSchema, indent + 2);
+        } else if (itemSchema) {
+          const itemType = getTypeDescription(itemSchema);
+          result += `${indentStr}    ${itemType}
+`;
+        }
+      }
+    }
+  }
+  return result;
+}
+function getTypeDescription(schema) {
+  if (!schema) return "any";
+  if (schema.type) {
+    const typeStr = Array.isArray(schema.type) ? schema.type.join(" | ") : schema.type;
+    if (typeStr === "array" || Array.isArray(schema.type) && schema.type.includes("array")) {
+      if (schema.items && !Array.isArray(schema.items) && schema.items.type) {
+        const itemType = Array.isArray(schema.items.type) ? schema.items.type.join(" | ") : schema.items.type;
+        return `array of ${itemType}`;
+      }
+      return "array";
+    }
+    if ((typeStr === "string" || Array.isArray(schema.type) && schema.type.includes("string")) && schema.format) {
+      const formatHints = {
+        "date": "YYYY-MM-DD",
+        "time": "HH:MM or HH:MM:SS",
+        "date-time": "YYYY-MM-DDTHH:MM:SS (ISO 8601)"
+      };
+      const hint = formatHints[schema.format];
+      if (hint) {
+        return `string (format: ${schema.format}, use ${hint})`;
+      }
+      return `string (format: ${schema.format})`;
+    }
+    return typeStr;
+  }
+  if (schema.anyOf) {
+    return schema.anyOf.map((s) => getTypeDescription(s)).join(" OR ");
+  }
+  if (schema.oneOf) {
+    return schema.oneOf.map((s) => getTypeDescription(s)).join(" OR ");
+  }
+  return "any";
+}
+function buildSchemaPromptSection(schema) {
+  const schemaFields = formatSchemaForPrompt(schema);
+  return `
+==================================================
+CRITICAL: OUTPUT STRUCTURE REQUIREMENTS
+==================================================
+
+YOU MUST RETURN JSON MATCHING THIS EXACT STRUCTURE:
+
+${schemaFields}
+
+CRITICAL FIELD NAME REQUIREMENTS:
+\u2713 Use EXACTLY the field names shown above (character-for-character match)
+\u2713 Preserve the exact casing (e.g., "fullName", not "full_name" or "FullName")
+\u2713 Do NOT abbreviate field names (e.g., "dob" instead of "dateOfBirth")
+\u2713 Do NOT invent alternative names (e.g., "directorName" instead of "fullName")
+\u2713 Do NOT use snake_case if the schema uses camelCase
+\u2713 Do NOT flatten nested structures or rename nested fields
+\u2713 The schema above is the SINGLE SOURCE OF TRUTH for field naming
+
+MISSING DATA:
+- If a required field has no data in the document, use null
+- If an optional field has no data, you may omit it or use null
+- Do NOT invent data that isn't in the document
+
+==================================================
+`.trim();
+}
+function combineSchemaAndUserPrompt(schema, userPrompt) {
+  const schemaSection = buildSchemaPromptSection(schema);
+  if (!userPrompt || userPrompt.trim() === "") {
+    return schemaSection + "\n\nTASK: Extract structured data from the provided document.";
+  }
+  return schemaSection + "\n\n" + userPrompt;
+}
+function buildOutputFormatPrompt(options) {
+  const parts = [];
+  if (options.outputFormat) {
+    switch (options.outputFormat) {
+      case "markdown":
+        parts.push("Format all text content using markdown syntax. Use proper headings (#, ##, ###), lists (-, *), bold (**text**), and other markdown formatting where appropriate.");
+        break;
+      case "html":
+        parts.push("Format all text content as valid HTML. Use semantic tags like <p>, <h1>-<h6>, <ul>, <ol>, <strong>, <em> where appropriate.");
+        break;
+      case "json":
+        parts.push("For text fields that contain structured data, format them as embedded JSON strings where appropriate.");
+        break;
+      case "text":
+        parts.push("Return plain text without any formatting. No markdown, HTML, or other markup.");
+        break;
+    }
+  }
+  if (options.tableFormat) {
+    switch (options.tableFormat) {
+      case "markdown":
+        parts.push("Format all tables using markdown table syntax with | column separators and header row with ---.");
+        break;
+      case "html":
+        parts.push("Format all tables as HTML <table> elements with <thead>, <tbody>, <tr>, <th>, and <td> tags.");
+        break;
+      case "csv":
+        parts.push("Format all tables as CSV with headers in the first row and comma-separated values.");
+        break;
+    }
+  }
+  if (options.pageMarkers) {
+    parts.push('Insert "---" page break markers between content from different pages of the document.');
+  }
+  return parts.join("\n");
+}
+function buildLanguageHintsPrompt(languages) {
+  if (!languages || languages.length === 0) {
+    return "";
+  }
+  return `The document is written in ${languages.join(", ")}. Extract and preserve text in the original language(s).`;
+}
+function buildConfidencePrompt() {
+  return `
+For each extracted field, assess your confidence level and include it in the "_confidence" object:
+- Use a number from 0.0 to 1.0 where:
+  - 0.9-1.0: Very high confidence - text is clear and unambiguous
+  - 0.7-0.9: High confidence - minor ambiguity but likely correct
+  - 0.5-0.7: Medium confidence - some uncertainty or partial visibility
+  - 0.3-0.5: Low confidence - significant uncertainty
+  - 0.0-0.3: Very low confidence - guessing or text was unclear
+
+Include "_confidence" as a sibling object mapping field paths to their scores.
+Example: "_confidence": { "invoiceNumber": 0.95, "amount": 0.82 }
+`.trim();
+}
+function buildSourcesPrompt() {
+  return `
+For each extracted field, identify the source location in the document and include it in the "_sources" array:
+Each source entry should contain:
+- "field": The field name/path that was extracted
+- "text": The exact text from the document used for extraction
+- "bbox": Bounding box as [y_min, x_min, y_max, x_max] normalized to 0-1000 scale
+- "page": Page number (0-indexed) where the text appears
+
+Include "_sources" as a sibling array to your extracted data.
+Example: "_sources": [{ "field": "invoiceNumber", "text": "INV-001", "bbox": [100, 50, 120, 150], "page": 0 }]
+`.trim();
+}
+function buildBlockClassificationPrompt() {
+  return `
+For each extracted element or text block, classify its type in a "_blockTypes" object:
+- "title": Main document title or major section headers
+- "heading": Section headings and subheadings
+- "paragraph": Body text paragraphs
+- "table": Tabular data
+- "list": Bulleted or numbered lists
+- "header": Page headers (repeated at top of pages)
+- "footer": Page footers (repeated at bottom of pages)
+- "caption": Image or figure captions
+- "code": Code blocks or preformatted text
+
+Include "_blockTypes" mapping field paths to their block type.
+Example: "_blockTypes": { "summary": "paragraph", "items": "list" }
+`.trim();
+}
+function buildHeaderFooterPrompt(options) {
+  const parts = [];
+  if (options.extractHeaders) {
+    parts.push('Identify and extract document headers (repeated content at the top of pages) into a "_headers" array.');
+  }
+  if (options.extractFooters) {
+    parts.push('Identify and extract document footers (repeated content at the bottom of pages, like page numbers) into a "_footers" array.');
+  }
+  if (parts.length > 0) {
+    parts.push('Each header/footer entry should include: { "text": "...", "pages": [0, 1, 2] } listing which pages contain it.');
+  }
+  return parts.join("\n");
+}
+function buildChunkingPrompt(strategy, maxChunkSize) {
+  const sizeNote = maxChunkSize ? ` Keep chunks under ${maxChunkSize} characters when possible.` : "";
+  switch (strategy) {
+    case "page":
+      return `Organize the extracted content by page. Include page number for each chunk.${sizeNote}`;
+    case "section":
+      return `Divide the document into logical sections based on headings and structure. Each section should be a coherent unit.${sizeNote}`;
+    case "paragraph":
+      return `Divide the content into individual paragraphs, preserving the natural paragraph breaks from the document.${sizeNote}`;
+    case "semantic":
+      return `Divide the document into semantically coherent chunks. Each chunk should be a self-contained unit of meaning that could stand alone.${sizeNote}`;
+    default:
+      return "";
+  }
+}
+function buildLLMDerivedFeaturesPrompt(options) {
+  const parts = [];
+  const formatPrompt = buildOutputFormatPrompt(options);
+  if (formatPrompt) {
+    parts.push(formatPrompt);
+  }
+  if (options.languageHints && options.languageHints.length > 0) {
+    parts.push(buildLanguageHintsPrompt(options.languageHints));
+  }
+  if (options.includeConfidence) {
+    parts.push(buildConfidencePrompt());
+  }
+  if (options.includeSources) {
+    parts.push(buildSourcesPrompt());
+  }
+  if (options.includeBlockTypes) {
+    parts.push(buildBlockClassificationPrompt());
+  }
+  if (options.extractHeaders || options.extractFooters) {
+    parts.push(buildHeaderFooterPrompt(options));
+  }
+  if (options.chunkingStrategy) {
+    parts.push(buildChunkingPrompt(options.chunkingStrategy, options.maxChunkSize));
+  }
+  if (parts.length === 0) {
+    return "";
+  }
+  return `
+==================================================
+ADDITIONAL OUTPUT REQUIREMENTS
+==================================================
+
+${parts.join("\n\n")}
+
+==================================================
+`.trim();
+}
+function combineSchemaUserAndDerivedPrompts(schema, userPrompt, derivedOptions) {
+  let result = combineSchemaAndUserPrompt(schema, userPrompt);
+  if (derivedOptions) {
+    const derivedPrompt = buildLLMDerivedFeaturesPrompt(derivedOptions);
+    if (derivedPrompt) {
+      result = result + "\n\n" + derivedPrompt;
+    }
+  }
+  return result;
+}
+
+export {
+  formatSchemaForPrompt,
+  buildSchemaPromptSection,
+  combineSchemaAndUserPrompt,
+  buildOutputFormatPrompt,
+  buildLanguageHintsPrompt,
+  buildConfidencePrompt,
+  buildSourcesPrompt,
+  buildBlockClassificationPrompt,
+  buildHeaderFooterPrompt,
+  buildChunkingPrompt,
+  buildLLMDerivedFeaturesPrompt,
+  combineSchemaUserAndDerivedPrompts
+};
+//# sourceMappingURL=chunk-7YPJIWRM.js.map

package/dist/chunk-7YPJIWRM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema-prompt-formatter.ts"],"sourcesContent":["/**\n * Utility for converting JSON Schema to human-readable prompt text\n * that emphasizes exact field name requirements for structured extraction.\n */\n\n/**\n * JSON Schema type used for prompt formatting.\n * Uses a recursive structure to support nested schemas.\n */\nexport interface JSONSchema {\n  type?: string | string[];  // Can be array for union types (e.g., [\"string\", \"null\"])\n  properties?: Record<string, JSONSchema>;\n  items?: JSONSchema | JSONSchema[];  // Can be array for tuple validation\n  description?: string;\n  required?: string[];\n  enum?: (string | number | boolean | null)[];\n  anyOf?: JSONSchema[];\n  oneOf?: JSONSchema[];\n  allOf?: JSONSchema[];\n  format?: string;\n  [key: string]: unknown;  // Allow additional properties\n}\n\n/**\n * Formats a JSON Schema into prompt text that emphasizes exact field names.\n * This helps LLMs understand they must use the exact field names specified\n * in the schema, not invent their own based on document content.\n */\nexport function formatSchemaForPrompt(schema: JSONSchema, indent: number = 0): string {\n  if (!schema || typeof schema !== 'object') {\n    return '';\n  }\n\n  const indentStr = '  '.repeat(indent);\n  let result = '';\n\n  // Handle object type with properties\n  if (schema.type === 'object' && schema.properties) {\n    const properties = schema.properties;\n    const required = schema.required || [];\n\n    for (const [fieldName, fieldSchema] of Object.entries(properties)) {\n      const isRequired = required.includes(fieldName);\n      const requiredMarker = isRequired ? ' (REQUIRED)' : ' (optional)';\n\n      // Field name in backticks to emphasize exactness\n      result += `${indentStr}- \\`${fieldName}\\`${requiredMarker}`;\n\n      // Type information\n      const type = getTypeDescription(fieldSchema);\n      if (type) {\n        result += `: ${type}`;\n      }\n\n      // Description if available\n      if (fieldSchema.description) {\n        result += `\\n${indentStr}  ${fieldSchema.description}`;\n      }\n\n      // Enum values if specified\n      if (fieldSchema.enum) {\n        result += `\\n${indentStr}  Allowed values: ${fieldSchema.enum.map((v) => JSON.stringify(v)).join(', ')}`;\n      }\n\n      result += '\\n';\n\n      // Nested object properties\n      if (fieldSchema.type === 'object' && fieldSchema.properties) {\n        result += formatSchemaForPrompt(fieldSchema, indent + 1);\n      }\n\n      // Array item schema\n      if (fieldSchema.type === 'array' && fieldSchema.items) {\n        result += `${indentStr}  Array items:\\n`;\n        // Handle both single schema and tuple schemas (array of schemas)\n        const itemSchema = Array.isArray(fieldSchema.items)\n          ? fieldSchema.items[0]  // For tuple validation, describe first item type\n          : fieldSchema.items;\n        if (itemSchema && itemSchema.type === 'object' && itemSchema.properties) {\n          result += formatSchemaForPrompt(itemSchema, indent + 2);\n        } else if (itemSchema) {\n          const itemType = getTypeDescription(itemSchema);\n          result += `${indentStr}    ${itemType}\\n`;\n        }\n      }\n    }\n  }\n\n  return result;\n}\n\n/**\n * Gets a human-readable type description from a schema property\n */\nfunction getTypeDescription(schema: JSONSchema): string {\n  if (!schema) return 'any';\n\n  if (schema.type) {\n    // Handle array of types (e.g., [\"string\", \"null\"])\n    const typeStr = Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type;\n\n    if (typeStr === 'array' || (Array.isArray(schema.type) && schema.type.includes('array'))) {\n      if (schema.items && !Array.isArray(schema.items) && schema.items.type) {\n        const itemType = Array.isArray(schema.items.type)\n          ? schema.items.type.join(' | ')\n          : schema.items.type;\n        return `array of ${itemType}`;\n      }\n      return 'array';\n    }\n    // Include format information for strings (e.g., date, time, date-time, email, uri)\n    if ((typeStr === 'string' || (Array.isArray(schema.type) && schema.type.includes('string'))) && schema.format) {\n      const formatHints: Record<string, string> = {\n        'date': 'YYYY-MM-DD',\n        'time': 'HH:MM or HH:MM:SS',\n        'date-time': 'YYYY-MM-DDTHH:MM:SS (ISO 8601)',\n      };\n      const hint = formatHints[schema.format];\n      if (hint) {\n        return `string (format: ${schema.format}, use ${hint})`;\n      }\n      return `string (format: ${schema.format})`;\n    }\n    return typeStr;\n  }\n\n  // Handle anyOf, oneOf, allOf\n  if (schema.anyOf) {\n    return schema.anyOf.map((s) => getTypeDescription(s)).join(' OR ');\n  }\n  if (schema.oneOf) {\n    return schema.oneOf.map((s) => getTypeDescription(s)).join(' OR ');\n  }\n\n  return 'any';\n}\n\n/**\n * Generates a complete prompt section with schema information and\n * strict field name instructions.\n */\nexport function buildSchemaPromptSection(schema: JSONSchema): string {\n  const schemaFields = formatSchemaForPrompt(schema);\n\n  return `\n==================================================\nCRITICAL: OUTPUT STRUCTURE REQUIREMENTS\n==================================================\n\nYOU MUST RETURN JSON MATCHING THIS EXACT STRUCTURE:\n\n${schemaFields}\n\nCRITICAL FIELD NAME REQUIREMENTS:\n✓ Use EXACTLY the field names shown above (character-for-character match)\n✓ Preserve the exact casing (e.g., \"fullName\", not \"full_name\" or \"FullName\")\n✓ Do NOT abbreviate field names (e.g., \"dob\" instead of \"dateOfBirth\")\n✓ Do NOT invent alternative names (e.g., \"directorName\" instead of \"fullName\")\n✓ Do NOT use snake_case if the schema uses camelCase\n✓ Do NOT flatten nested structures or rename nested fields\n✓ The schema above is the SINGLE SOURCE OF TRUTH for field naming\n\nMISSING DATA:\n- If a required field has no data in the document, use null\n- If an optional field has no data, you may omit it or use null\n- Do NOT invent data that isn't in the document\n\n==================================================\n`.trim();\n}\n\n/**\n * Combines schema prompt section with user's custom prompt\n */\nexport function combineSchemaAndUserPrompt(\n  schema: JSONSchema,\n  userPrompt: string\n): string {\n  const schemaSection = buildSchemaPromptSection(schema);\n\n  if (!userPrompt || userPrompt.trim() === '') {\n    return schemaSection + '\\n\\nTASK: Extract structured data from the provided document.';\n  }\n\n  return schemaSection + '\\n\\n' + userPrompt;\n}\n\n// ============================================================================\n// LLM-Derived Feature Prompts\n// ============================================================================\n\n/**\n * Output format types for LLM text generation\n */\nexport type OutputFormat = 'markdown' | 'html' | 'json' | 'text';\nexport type TableFormat = 'markdown' | 'html' | 'csv';\nexport type ChunkingStrategy = 'page' | 'section' | 'paragraph' | 'semantic';\n\n/**\n * Options for LLM-derived features that are implemented via prompting\n */\nexport interface LLMDerivedPromptOptions {\n  outputFormat?: OutputFormat;\n  tableFormat?: TableFormat;\n  pageMarkers?: boolean;\n  includeConfidence?: boolean;\n  includeSources?: boolean;\n  includeBlockTypes?: boolean;\n  extractHeaders?: boolean;\n  extractFooters?: boolean;\n  chunkingStrategy?: ChunkingStrategy;\n  maxChunkSize?: number;\n  languageHints?: string[];\n}\n\n/**\n * Builds prompt additions for output format options\n */\nexport function buildOutputFormatPrompt(options: LLMDerivedPromptOptions): string {\n  const parts: string[] = [];\n\n  // Output format\n  if (options.outputFormat) {\n    switch (options.outputFormat) {\n      case 'markdown':\n        parts.push('Format all text content using markdown syntax. Use proper headings (#, ##, ###), lists (-, *), bold (**text**), and other markdown formatting where appropriate.');\n        break;\n      case 'html':\n        parts.push('Format all text content as valid HTML. Use semantic tags like <p>, <h1>-<h6>, <ul>, <ol>, <strong>, <em> where appropriate.');\n        break;\n      case 'json':\n        parts.push('For text fields that contain structured data, format them as embedded JSON strings where appropriate.');\n        break;\n      case 'text':\n        parts.push('Return plain text without any formatting. No markdown, HTML, or other markup.');\n        break;\n    }\n  }\n\n  // Table format\n  if (options.tableFormat) {\n    switch (options.tableFormat) {\n      case 'markdown':\n        parts.push('Format all tables using markdown table syntax with | column separators and header row with ---.');\n        break;\n      case 'html':\n        parts.push('Format all tables as HTML <table> elements with <thead>, <tbody>, <tr>, <th>, and <td> tags.');\n        break;\n      case 'csv':\n        parts.push('Format all tables as CSV with headers in the first row and comma-separated values.');\n        break;\n    }\n  }\n\n  // Page markers\n  if (options.pageMarkers) {\n    parts.push('Insert \"---\" page break markers between content from different pages of the document.');\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Builds prompt additions for language hints\n */\nexport function buildLanguageHintsPrompt(languages: string[]): string {\n  if (!languages || languages.length === 0) {\n    return '';\n  }\n  return `The document is written in ${languages.join(', ')}. Extract and preserve text in the original language(s).`;\n}\n\n/**\n * Builds prompt additions for confidence scoring\n */\nexport function buildConfidencePrompt(): string {\n  return `\nFor each extracted field, assess your confidence level and include it in the \"_confidence\" object:\n- Use a number from 0.0 to 1.0 where:\n  - 0.9-1.0: Very high confidence - text is clear and unambiguous\n  - 0.7-0.9: High confidence - minor ambiguity but likely correct\n  - 0.5-0.7: Medium confidence - some uncertainty or partial visibility\n  - 0.3-0.5: Low confidence - significant uncertainty\n  - 0.0-0.3: Very low confidence - guessing or text was unclear\n\nInclude \"_confidence\" as a sibling object mapping field paths to their scores.\nExample: \"_confidence\": { \"invoiceNumber\": 0.95, \"amount\": 0.82 }\n`.trim();\n}\n\n/**\n * Builds prompt additions for source citations with bounding boxes\n */\nexport function buildSourcesPrompt(): string {\n  return `\nFor each extracted field, identify the source location in the document and include it in the \"_sources\" array:\nEach source entry should contain:\n- \"field\": The field name/path that was extracted\n- \"text\": The exact text from the document used for extraction\n- \"bbox\": Bounding box as [y_min, x_min, y_max, x_max] normalized to 0-1000 scale\n- \"page\": Page number (0-indexed) where the text appears\n\nInclude \"_sources\" as a sibling array to your extracted data.\nExample: \"_sources\": [{ \"field\": \"invoiceNumber\", \"text\": \"INV-001\", \"bbox\": [100, 50, 120, 150], \"page\": 0 }]\n`.trim();\n}\n\n/**\n * Builds prompt additions for block type classification\n */\nexport function buildBlockClassificationPrompt(): string {\n  return `\nFor each extracted element or text block, classify its type in a \"_blockTypes\" object:\n- \"title\": Main document title or major section headers\n- \"heading\": Section headings and subheadings\n- \"paragraph\": Body text paragraphs\n- \"table\": Tabular data\n- \"list\": Bulleted or numbered lists\n- \"header\": Page headers (repeated at top of pages)\n- \"footer\": Page footers (repeated at bottom of pages)\n- \"caption\": Image or figure captions\n- \"code\": Code blocks or preformatted text\n\nInclude \"_blockTypes\" mapping field paths to their block type.\nExample: \"_blockTypes\": { \"summary\": \"paragraph\", \"items\": \"list\" }\n`.trim();\n}\n\n/**\n * Builds prompt additions for header/footer extraction\n */\nexport function buildHeaderFooterPrompt(options: { extractHeaders?: boolean; extractFooters?: boolean }): string {\n  const parts: string[] = [];\n\n  if (options.extractHeaders) {\n    parts.push('Identify and extract document headers (repeated content at the top of pages) into a \"_headers\" array.');\n  }\n\n  if (options.extractFooters) {\n    parts.push('Identify and extract document footers (repeated content at the bottom of pages, like page numbers) into a \"_footers\" array.');\n  }\n\n  if (parts.length > 0) {\n    parts.push('Each header/footer entry should include: { \"text\": \"...\", \"pages\": [0, 1, 2] } listing which pages contain it.');\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Builds prompt additions for semantic chunking\n */\nexport function buildChunkingPrompt(strategy: ChunkingStrategy, maxChunkSize?: number): string {\n  const sizeNote = maxChunkSize\n    ? ` Keep chunks under ${maxChunkSize} characters when possible.`\n    : '';\n\n  switch (strategy) {\n    case 'page':\n      return `Organize the extracted content by page. Include page number for each chunk.${sizeNote}`;\n    case 'section':\n      return `Divide the document into logical sections based on headings and structure. Each section should be a coherent unit.${sizeNote}`;\n    case 'paragraph':\n      return `Divide the content into individual paragraphs, preserving the natural paragraph breaks from the document.${sizeNote}`;\n    case 'semantic':\n      return `Divide the document into semantically coherent chunks. Each chunk should be a self-contained unit of meaning that could stand alone.${sizeNote}`;\n    default:\n      return '';\n  }\n}\n\n/**\n * Combines all LLM-derived feature prompts into a single prompt section\n */\nexport function buildLLMDerivedFeaturesPrompt(options: LLMDerivedPromptOptions): string {\n  const parts: string[] = [];\n\n  // Output format options\n  const formatPrompt = buildOutputFormatPrompt(options);\n  if (formatPrompt) {\n    parts.push(formatPrompt);\n  }\n\n  // Language hints\n  if (options.languageHints && options.languageHints.length > 0) {\n    parts.push(buildLanguageHintsPrompt(options.languageHints));\n  }\n\n  // Metadata features (confidence, sources, block types)\n  if (options.includeConfidence) {\n    parts.push(buildConfidencePrompt());\n  }\n\n  if (options.includeSources) {\n    parts.push(buildSourcesPrompt());\n  }\n\n  if (options.includeBlockTypes) {\n    parts.push(buildBlockClassificationPrompt());\n  }\n\n  // Header/footer extraction\n  if (options.extractHeaders || options.extractFooters) {\n    parts.push(buildHeaderFooterPrompt(options));\n  }\n\n  // Chunking strategy\n  if (options.chunkingStrategy) {\n    parts.push(buildChunkingPrompt(options.chunkingStrategy, options.maxChunkSize));\n  }\n\n  if (parts.length === 0) {\n    return '';\n  }\n\n  return `\n==================================================\nADDITIONAL OUTPUT REQUIREMENTS\n==================================================\n\n${parts.join('\\n\\n')}\n\n==================================================\n`.trim();\n}\n\n/**\n * Combines schema prompt with user prompt and LLM-derived features\n */\nexport function combineSchemaUserAndDerivedPrompts(\n  schema: JSONSchema,\n  userPrompt: string,\n  derivedOptions?: LLMDerivedPromptOptions\n): string {\n  let result = combineSchemaAndUserPrompt(schema, userPrompt);\n\n  if (derivedOptions) {\n    const derivedPrompt = buildLLMDerivedFeaturesPrompt(derivedOptions);\n    if (derivedPrompt) {\n      result = result + '\\n\\n' + derivedPrompt;\n    }\n  }\n\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -93,6 +93,7 @@ interface LLMResponse<T = unknown> {
     metrics: ResponseMetrics;
     reasoning?: string;
     reasoning_details?: ReasoningDetail[];
+    metadata?: LLMExtractedMetadata;
 }
 /** Provider capability flags */
 interface ProviderCapabilities {
@@ -106,6 +107,60 @@ interface ProviderCapabilities {
 }
 /** JSON output mode */
 type JsonMode = 'strict' | 'relaxed';
+/**
+ * LLM-derived feature options that are implemented via prompting
+ * These options are normalized across providers and work through prompt engineering
+ */
+interface LLMDerivedOptions {
+    /** Format for text output (markdown, html, json, text) */
+    outputFormat?: 'markdown' | 'html' | 'json' | 'text';
+    /** Format for tables within text fields */
+    tableFormat?: 'markdown' | 'html' | 'csv';
+    /** Add page break markers (---) between pages */
+    pageMarkers?: boolean;
+    /** Include per-field confidence scores (attached to result, not in JSON) */
+    includeConfidence?: boolean;
+    /** Include source citations with bounding boxes (attached to result, not in JSON) */
+    includeSources?: boolean;
+    /** Include block type classification for each extracted element */
+    includeBlockTypes?: boolean;
+    /** Extract document headers (repeated content at top of pages) */
+    extractHeaders?: boolean;
+    /** Extract document footers (repeated content at bottom of pages) */
+    extractFooters?: boolean;
+    /** Document chunking strategy */
+    chunkingStrategy?: 'page' | 'section' | 'paragraph' | 'semantic';
+    /** Maximum chunk size in characters (when using chunking) */
+    maxChunkSize?: number;
+    /** Language hints for the document */
+    languageHints?: string[];
+}
+/**
+ * Extracted metadata from LLM response (populated when derived options are enabled)
+ */
+interface LLMExtractedMetadata {
+    /** Per-field confidence scores (0-1) */
+    confidence?: Record<string, number>;
+    /** Source citations with bounding boxes */
+    sources?: Array<{
+        field: string;
+        text: string;
+        bbox?: [number, number, number, number];
+        page?: number;
+    }>;
+    /** Block type classifications */
+    blockTypes?: Record<string, string>;
+    /** Extracted headers */
+    headers?: Array<{
+        text: string;
+        pages: number[];
+    }>;
+    /** Extracted footers */
+    footers?: Array<{
+        text: string;
+        pages: number[];
+    }>;
+}
 /** Provider interface */
 interface LLMProvider {
     readonly name: string;
@@ -117,6 +172,7 @@ interface LLMProvider {
         max_tokens?: number;
         reasoning?: ReasoningConfig;
         embedSchemaInPrompt?: boolean;
+        derivedOptions?: LLMDerivedOptions;
     }): Promise<LLMResponse<T>>;
 }
 /** Reasoning configuration (normalized across providers) */
@@ -263,6 +319,82 @@ declare function buildSchemaPromptSection(schema: JSONSchema): string;
  * Combines schema prompt section with user's custom prompt
  */
 declare function combineSchemaAndUserPrompt(schema: JSONSchema, userPrompt: string): string;
+/**
+ * Output format types for LLM text generation
+ */
+type OutputFormat = 'markdown' | 'html' | 'json' | 'text';
+type TableFormat = 'markdown' | 'html' | 'csv';
+type ChunkingStrategy = 'page' | 'section' | 'paragraph' | 'semantic';
+/**
+ * Options for LLM-derived features that are implemented via prompting
+ */
+interface LLMDerivedPromptOptions {
+    outputFormat?: OutputFormat;
+    tableFormat?: TableFormat;
+    pageMarkers?: boolean;
+    includeConfidence?: boolean;
+    includeSources?: boolean;
+    includeBlockTypes?: boolean;
+    extractHeaders?: boolean;
+    extractFooters?: boolean;
+    chunkingStrategy?: ChunkingStrategy;
+    maxChunkSize?: number;
+    languageHints?: string[];
+}
+/**
+ * Builds prompt additions for output format options
+ */
+declare function buildOutputFormatPrompt(options: LLMDerivedPromptOptions): string;
+/**
+ * Builds prompt additions for language hints
+ */
+declare function buildLanguageHintsPrompt(languages: string[]): string;
+/**
+ * Builds prompt additions for confidence scoring
+ */
+declare function buildConfidencePrompt(): string;
+/**
+ * Builds prompt additions for source citations with bounding boxes
+ */
+declare function buildSourcesPrompt(): string;
+/**
+ * Builds prompt additions for block type classification
+ */
+declare function buildBlockClassificationPrompt(): string;
+/**
+ * Combines all LLM-derived feature prompts into a single prompt section
+ */
+declare function buildLLMDerivedFeaturesPrompt(options: LLMDerivedPromptOptions): string;
+/**
+ * Combines schema prompt with user prompt and LLM-derived features
+ */
+declare function combineSchemaUserAndDerivedPrompts(schema: JSONSchema, userPrompt: string, derivedOptions?: LLMDerivedPromptOptions): string;
+
+/**
+ * Utility for extracting metadata from LLM responses
+ * Handles the `_` prefixed fields that contain confidence, sources, etc.
+ */
+
+/**
+ * Extracts metadata fields from a JSON response and returns clean JSON + metadata
+ *
+ * @param json - The raw JSON response from the LLM (may contain _ prefixed fields)
+ * @returns Object with clean JSON (metadata removed) and extracted metadata
+ */
+declare function extractMetadataFromResponse<T>(json: unknown): {
+    json: T;
+    metadata?: LLMExtractedMetadata;
+};
+/**
+ * Checks if derived options require metadata extraction
+ */
+declare function shouldExtractMetadata(derivedOptions?: {
+    includeConfidence?: boolean;
+    includeSources?: boolean;
+    includeBlockTypes?: boolean;
+    extractHeaders?: boolean;
+    extractFooters?: boolean;
+}): boolean;
 
 /**
  * Factory function type for creating provider instances
@@ -331,6 +463,7 @@ declare class OpenAIProvider implements LLMProvider {
         max_tokens?: number;
         reasoning?: ReasoningConfig;
         embedSchemaInPrompt?: boolean;
+        derivedOptions?: LLMDerivedOptions;
     }): Promise<LLMResponse<T>>;
     private buildReasoningConfig;
     private buildMessages;
@@ -355,6 +488,7 @@ declare class AnthropicProvider implements LLMProvider {
         max_tokens?: number;
         reasoning?: ReasoningConfig;
         embedSchemaInPrompt?: boolean;
+        derivedOptions?: LLMDerivedOptions;
     }): Promise<LLMResponse<T>>;
     private buildNativeThinkingConfig;
     private translateToOpenRouterFormat;
@@ -394,6 +528,7 @@ declare class GoogleProvider implements LLMProvider {
         max_tokens?: number;
         reasoning?: ReasoningConfig;
         embedSchemaInPrompt?: boolean;
+        derivedOptions?: LLMDerivedOptions;
     }): Promise<LLMResponse<T>>;
     private buildNativeThinkingConfig;
     private translateToOpenRouterFormat;
@@ -421,6 +556,7 @@ declare class XAIProvider implements LLMProvider {
         max_tokens?: number;
         reasoning?: ReasoningConfig;
         embedSchemaInPrompt?: boolean;
+        derivedOptions?: LLMDerivedOptions;
     }): Promise<LLMResponse<T>>;
     private buildReasoningConfig;
     private buildMessages;
@@ -445,8 +581,6 @@ declare class FallbackManager {
     }): Promise<LLMResponse<T>>;
     private createProvider;
     private validateResponse;
-    private isRetryable;
-    private calculateDelay;
     private sleep;
     private isCircuitOpen;
     private recordSuccess;
@@ -458,6 +592,98 @@ declare class FallbackManager {
  */
 declare function adaptToCoreLLMProvider(provider: LLMProvider): LLMJsonProvider;
 
+/**
+ * Schema for Gemini bounding box detection
+ * Used for OCR-style parsing with spatial information
+ *
+ * Note: Gemini uses [y_min, x_min, y_max, x_max] coordinate order (Y first, not X!)
+ * Coordinates are normalized to 0-1000 (divide by 1000, multiply by image dimensions)
+ */
+
+/**
+ * Block types for document structure classification
+ */
+declare const BLOCK_TYPES: readonly ["title", "paragraph", "table", "list", "header", "footer", "caption", "code", "image", "form", "signature", "handwriting"];
+type BlockType = typeof BLOCK_TYPES[number];
+/**
+ * Single text block with bounding box
+ */
+interface GeminiBoundingBoxBlock {
+    /**
+     * Bounding box coordinates: [y_min, x_min, y_max, x_max]
+     * Normalized to 0-1000 (Gemini format)
+     */
+    box_2d: [number, number, number, number];
+    /**
+     * Text content within the bounding box
+     */
+    text: string;
+    /**
+     * Block type classification
+     */
+    type: BlockType;
+    /**
+     * Confidence level (optional)
+     */
+    confidence?: 'high' | 'medium' | 'low';
+    /**
+     * Page number (0-indexed, for multi-page documents)
+     */
+    page?: number;
+}
+/**
+ * JSON Schema for Gemini bounding box extraction
+ * This schema is used with Gemini models to extract text with spatial information
+ */
+declare const geminiBoundingBoxSchema: UnifiedSchema<GeminiBoundingBoxBlock[]>;
+/**
+ * Prompt for Gemini bounding box extraction
+ * This activates Gemini's spatial understanding capabilities
+ */
+declare const GEMINI_BBOX_EXTRACTION_PROMPT = "Analyze this document and extract all text with precise bounding box locations.\n\nFor each text block, provide:\n- box_2d: Bounding box as [y_min, x_min, y_max, x_max] normalized to 0-1000\n- text: The exact text content\n- type: Block classification (title, paragraph, table, list, header, footer, caption, code, image, form, signature, handwriting)\n- confidence: Your confidence level (high, medium, low)\n- page: Page number (0-indexed) for multi-page documents\n\nIMPORTANT coordinate format:\n- Use [y_min, x_min, y_max, x_max] order (Y coordinate first, then X)\n- Normalize all values to 0-1000 range (top-left is [0, 0], bottom-right is [1000, 1000])\n\nReturn ONLY a valid JSON array, no other text.";
+/**
+ * Normalized bounding box format (0-1 range)
+ * This is the SDK's standard format after conversion from Gemini's 0-1000 format
+ */
+interface NormalizedBBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Convert Gemini 0-1000 coordinates to normalized 0-1 format
+ * Note: Gemini uses [y_min, x_min, y_max, x_max] order
+ *
+ * @param geminiBBox - Bounding box from Gemini [y_min, x_min, y_max, x_max] (0-1000)
+ * @returns Normalized bounding box with x, y, width, height (0-1)
+ */
+declare function normalizeGeminiBBox(geminiBBox: [number, number, number, number]): NormalizedBBox;
+/**
+ * Convert normalized 0-1 format back to Gemini 0-1000 coordinates
+ *
+ * @param bbox - Normalized bounding box (0-1)
+ * @returns Gemini format [y_min, x_min, y_max, x_max] (0-1000)
+ */
+declare function toGeminiBBox(bbox: NormalizedBBox): [number, number, number, number];
+/**
+ * Convert Gemini bounding box block to DocumentIR-compatible format
+ */
+interface DocumentBlock {
+    text: string;
+    bbox: NormalizedBBox;
+    type: BlockType;
+    confidence?: number;
+    page?: number;
+}
+/**
+ * Convert Gemini extraction result to DocumentIR blocks
+ *
+ * @param geminiBlocks - Raw blocks from Gemini extraction
+ * @returns Document blocks with normalized coordinates
+ */
+declare function convertGeminiBlocksToDocumentBlocks(geminiBlocks: GeminiBoundingBoxBlock[]): DocumentBlock[];
+
 /**
  * LLM Provider Metadata
  *
@@ -1419,4 +1645,4 @@ declare function createVLMProvider(config: {
  */
 declare function buildLLMProvider(config: FallbackConfig): VLMProvider;
 
-export { type AccessMethod, AnthropicProvider, type CircuitBreakerState, type FallbackConfig, FallbackManager, GoogleProvider, type ImageInput, type JsonMode, type LLMModelMetadata, type LLMProvider, type LLMProviderMetadata, type LLMProviderType, type LLMResponse, type MultimodalInput, type NodeType, OpenAIProvider, type PDFInput, PROVIDER_METADATA, type ProviderCapabilities, type ProviderConfig, type ProviderFactory, type ProviderInputType, type ProviderType, type ReasoningConfig, type ReasoningDetail, type ResourceLimits, type ResponseMetrics, SUPPORTED_IMAGE_TYPES, SchemaTranslator, type SupportedImageMimeType, type UnifiedSchema, XAIProvider, adaptToCoreLLMProvider, buildLLMProvider, buildSchemaPromptSection, combineSchemaAndUserPrompt, compareNativeVsOpenRouter, createProviderFromRegistry, createVLMProvider, estimateCost, formatSchemaForPrompt, getCheapestProvider, getProvidersForNode, isImageTypeSupported, isProviderCompatibleWithNode, providerRegistry, registerProvider, supportsPDFsInline };
+export { type AccessMethod, AnthropicProvider, BLOCK_TYPES, type BlockType, type CircuitBreakerState, type DocumentBlock, type FallbackConfig, FallbackManager, GEMINI_BBOX_EXTRACTION_PROMPT, type GeminiBoundingBoxBlock, GoogleProvider, type ImageInput, type JsonMode, type LLMDerivedOptions, type LLMExtractedMetadata, type LLMModelMetadata, type LLMProvider, type LLMProviderMetadata, type LLMProviderType, type LLMResponse, type MultimodalInput, type NodeType, type NormalizedBBox, OpenAIProvider, type PDFInput, PROVIDER_METADATA, type ProviderCapabilities, type ProviderConfig, type ProviderFactory, type ProviderInputType, type ProviderType, type ReasoningConfig, type ReasoningDetail, type ResourceLimits, type ResponseMetrics, SUPPORTED_IMAGE_TYPES, SchemaTranslator, type SupportedImageMimeType, type UnifiedSchema, XAIProvider, adaptToCoreLLMProvider, buildBlockClassificationPrompt, buildConfidencePrompt, buildLLMDerivedFeaturesPrompt, buildLLMProvider, buildLanguageHintsPrompt, buildOutputFormatPrompt, buildSchemaPromptSection, buildSourcesPrompt, combineSchemaAndUserPrompt, combineSchemaUserAndDerivedPrompts, compareNativeVsOpenRouter, convertGeminiBlocksToDocumentBlocks, createProviderFromRegistry, createVLMProvider, estimateCost, extractMetadataFromResponse, formatSchemaForPrompt, geminiBoundingBoxSchema, getCheapestProvider, getProvidersForNode, isImageTypeSupported, isProviderCompatibleWithNode, normalizeGeminiBBox, providerRegistry, registerProvider, shouldExtractMetadata, supportsPDFsInline, toGeminiBBox };