@heripo/document-processor 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -267,16 +267,9 @@ declare class DocumentProcessor {
      * Convert chapters and link resources
      *
      * Generates chapters based on TOC and links images/tables/footnotes using ChapterConverter.
-     * Falls back to single "Document" chapter when TOC is empty.
+     * Throws TocNotFoundError if TOC entries are empty (defensive assertion).
      */
     private convertChapters;
-    /**
-     * Create a fallback chapter when TOC is not available
-     *
-     * Creates a single "Document" chapter containing all text blocks,
-     * images, tables, and footnotes from the document.
-     */
-    private createFallbackChapter;
 }
 
 /**
@@ -729,6 +722,27 @@ declare class PageRangeParser extends VisionLLMComponent {
     protected buildUserPrompt(pageNos: number[]): string;
 }
 
+/**
+ * Single validation issue detected during TOC validation
+ */
+interface TocValidationIssue {
+    /**
+     * Issue code (V001, V002, etc.)
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Path to the problematic entry (e.g., "[0].children[2]")
+     */
+    path: string;
+    /**
+     * The problematic entry
+     */
+    entry: TocEntry;
+}
 /**
  * TocExtractError
  *
@@ -775,6 +789,12 @@ interface TocValidationOptions {
      * Maximum allowed title length (default: 200)
      */
     maxTitleLength?: number;
+    /**
+     * Maximum ratio of the first entry's page to total pages (default: 0.3)
+     * Used for V007 completeness check - if the first level-1 entry
+     * starts beyond max(50, totalPages * ratio), the TOC may be incomplete.
+     */
+    maxFirstEntryPageRatio?: number;
 }
 
 /**
@@ -963,7 +983,7 @@ declare class TocFinder {
      */
     private isTableTocLike;
     /**
-     * Expand TOC area to consecutive pages
+     * Expand TOC area to consecutive pages (both backward and forward)
      */
     private expandToConsecutivePages;
     /**
@@ -1023,6 +1043,9 @@ interface TocExtractorOptions extends BaseLLMComponentOptions {
  *
  * Uses high-performance LLM to extract structured TOC from Markdown representation.
  * Extends TextLLMComponent for standardized LLM call handling.
+ *
+ * When validation fails, automatically retries with correction feedback
+ * up to MAX_VALIDATION_RETRIES times before throwing.
  */
 declare class TocExtractor extends TextLLMComponent {
     private readonly validationOptions?;
@@ -1031,21 +1054,34 @@ declare class TocExtractor extends TextLLMComponent {
     /**
      * Extract TOC structure from Markdown
      *
+     * When validation fails, retries with correction feedback up to MAX_VALIDATION_RETRIES times.
+     *
      * @param markdown - Markdown representation of TOC area
-     * @returns Object with entries array and token usage information
+     * @param validationOverrides - Optional overrides for validation options (merged with constructor options)
+     * @returns Object with entries array and token usage array (initial extraction + any corrections)
      * @throws {TocParseError} When LLM fails to parse structure
-     * @throws {TocValidationError} When validation fails
+     * @throws {TocValidationError} When validation fails after all retries
      */
-    extract(markdown: string): Promise<{
+    extract(markdown: string, validationOverrides?: Partial<TocValidationOptions>): Promise<{
         entries: TocEntry[];
-        usage: ExtendedTokenUsage;
+        usages: ExtendedTokenUsage[];
     }>;
     /**
-     * Validate extracted entries
+     * Validate extracted entries and return error or null
+     *
+     * Unlike validateOrThrow, this returns the error instead of throwing,
+     * allowing the retry loop to handle it.
+     *
+     * @returns TocValidationError if validation fails, null if valid
+     */
+    private tryValidateEntries;
+    /**
+     * Build correction prompt with validation error feedback
      *
-     * @throws {TocValidationError} When validation fails
+     * Includes the original markdown, previous extraction result,
+     * validation errors, and guidance for fixing common mistakes.
      */
-    private validateEntries;
+    protected buildCorrectionPrompt(markdown: string, previousEntries: TocEntry[], issues: TocValidationIssue[]): string;
     /**
      * Build system prompt for TOC extraction
      */

package/dist/index.d.ts

@@ -267,16 +267,9 @@ declare class DocumentProcessor {
      * Convert chapters and link resources
      *
      * Generates chapters based on TOC and links images/tables/footnotes using ChapterConverter.
-     * Falls back to single "Document" chapter when TOC is empty.
+     * Throws TocNotFoundError if TOC entries are empty (defensive assertion).
      */
     private convertChapters;
-    /**
-     * Create a fallback chapter when TOC is not available
-     *
-     * Creates a single "Document" chapter containing all text blocks,
-     * images, tables, and footnotes from the document.
-     */
-    private createFallbackChapter;
 }
 
 /**
@@ -729,6 +722,27 @@ declare class PageRangeParser extends VisionLLMComponent {
     protected buildUserPrompt(pageNos: number[]): string;
 }
 
+/**
+ * Single validation issue detected during TOC validation
+ */
+interface TocValidationIssue {
+    /**
+     * Issue code (V001, V002, etc.)
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Path to the problematic entry (e.g., "[0].children[2]")
+     */
+    path: string;
+    /**
+     * The problematic entry
+     */
+    entry: TocEntry;
+}
 /**
  * TocExtractError
  *
@@ -775,6 +789,12 @@ interface TocValidationOptions {
      * Maximum allowed title length (default: 200)
      */
     maxTitleLength?: number;
+    /**
+     * Maximum ratio of the first entry's page to total pages (default: 0.3)
+     * Used for V007 completeness check - if the first level-1 entry
+     * starts beyond max(50, totalPages * ratio), the TOC may be incomplete.
+     */
+    maxFirstEntryPageRatio?: number;
 }
 
 /**
@@ -963,7 +983,7 @@ declare class TocFinder {
      */
     private isTableTocLike;
     /**
-     * Expand TOC area to consecutive pages
+     * Expand TOC area to consecutive pages (both backward and forward)
      */
     private expandToConsecutivePages;
     /**
@@ -1023,6 +1043,9 @@ interface TocExtractorOptions extends BaseLLMComponentOptions {
  *
  * Uses high-performance LLM to extract structured TOC from Markdown representation.
  * Extends TextLLMComponent for standardized LLM call handling.
+ *
+ * When validation fails, automatically retries with correction feedback
+ * up to MAX_VALIDATION_RETRIES times before throwing.
  */
 declare class TocExtractor extends TextLLMComponent {
     private readonly validationOptions?;
@@ -1031,21 +1054,34 @@ declare class TocExtractor extends TextLLMComponent {
     /**
      * Extract TOC structure from Markdown
      *
+     * When validation fails, retries with correction feedback up to MAX_VALIDATION_RETRIES times.
+     *
      * @param markdown - Markdown representation of TOC area
-     * @returns Object with entries array and token usage information
+     * @param validationOverrides - Optional overrides for validation options (merged with constructor options)
+     * @returns Object with entries array and token usage array (initial extraction + any corrections)
      * @throws {TocParseError} When LLM fails to parse structure
-     * @throws {TocValidationError} When validation fails
+     * @throws {TocValidationError} When validation fails after all retries
      */
-    extract(markdown: string): Promise<{
+    extract(markdown: string, validationOverrides?: Partial<TocValidationOptions>): Promise<{
         entries: TocEntry[];
-        usage: ExtendedTokenUsage;
+        usages: ExtendedTokenUsage[];
     }>;
     /**
-     * Validate extracted entries
+     * Validate extracted entries and return error or null
+     *
+     * Unlike validateOrThrow, this returns the error instead of throwing,
+     * allowing the retry loop to handle it.
+     *
+     * @returns TocValidationError if validation fails, null if valid
+     */
+    private tryValidateEntries;
+    /**
+     * Build correction prompt with validation error feedback
      *
-     * @throws {TocValidationError} When validation fails
+     * Includes the original markdown, previous extraction result,
+     * validation errors, and guidance for fixing common mistakes.
      */
-    private validateEntries;
+    protected buildCorrectionPrompt(markdown: string, previousEntries: TocEntry[], issues: TocValidationIssue[]): string;
     /**
      * Build system prompt for TOC extraction
      */