EPUB Read

Provide a strict, auditable EPUB workflow that safely handles long books through explicit task routing instead of loading full-book text by default.

<use_when>

• The user mentions an .epub file or ebook
• The user wants a quick structural overview
• The user wants chapter-specific or chunk-specific reading
• The user wants full-book sequential reading with chunking
• The user wants structured extraction
• The user wants to inspect images, tables, or other complex content
• The user wants to batch-process multiple EPUB files </use_when>

STEP 0 - Choose exactly one task mode before doing anything else

ModePurposeUse whenoverviewFast structural overviewMetadata, TOC, themes, structure onlytargeted_readFocused readingSpecific chapters, chunk ranges, or keyword hitsfull_readSequential readingLong-book chunked reading with saved progressextractStructured extractionKeywords, definitions, quotes, examples, action items, entities, tables, listscomplex_contentComplex-layout inspectionImages, tables, SVG, low-text sectionsbatchMulti-book planningMultiple EPUB files or folders

Default to overview or targeted_read when the user intent is ambiguous. Never load a long book's full body text by default.

STEP 1 - Parse if needed

1. Check whether the output directory already exists and contains manifest.json.
2. If not, run parse_epub.py.
3. After parsing, report:
   • title
   • author
   • chapter count
   • chunk count if available
   • image count
   • table count
   • output directory

STEP 2 - Build an execution plan

Use task_router.py to decide whether parsing, chunking, or state updates are required:

bash

python3 task_router.py <book_dir> --mode <mode> [params...]

The plan should tell you:

• whether parsing is required
• whether chunking is required
• which files are recommended to read
• whether session state must be updated

STEP 3 - Mode-specific behavior

overview#

• Read only metadata, TOC, reading index, and other structural outputs
• Do not load the whole book body by default
• Return:
  • title
  • author
  • chapter count
  • TOC structure
  • theme overview
  • suggested next actions

targeted_read#

Support:

• --chapter
• --chapter-id
• --chunk-start
• --chunk-end
• --keyword

Return:

• the requested section
• short context
• concise summary

full_read#

• Prefer chunk-based reading for long books
• Support continue, previous, next, and jump flows
• Always update session_state.json
• Never pretend progress exists if the session state is missing

extract#

Support extracting:

• keywords
• definitions
• quotes
• examples
• action_items
• names
• locations
• organizations
• tables
• lists

Return a hit list with chapter references and short context.

complex_content#

Inspect:

• images
• SVG
• tables
• image-heavy sections
• low-text / high-resource sections

Return a structured report. OCR is not required by default.

batch#

Support:

• multiple EPUB file paths
• directory scanning
• batch planning
• batch extraction requests

Return success / failure counts and a concise overview.

STEP 4 - Long-book safety rules

• Never push the full body of a long book into context at once
• Prefer chunks/ over chapter markdown for full sequential reading
• When chunking is required, run chunk_book.py first
• Use reading_index.json to map chapters to chunk ranges

STEP 5 - State management rules

When running full_read or any progress-sensitive flow:

1. Read session_state.json first
2. Update it after every progress-changing action
3. Respect existing saved progress unless the user explicitly asks to restart

STEP 6 - Output style

Be explicit about:

• what files were used
• what mode was selected
• why a long book was chunked instead of loaded fully
• what the user can do next

When possible, point the user toward the safest next step:

• continue reading
• jump to a chapter
• inspect a chunk range
• extract a structure
• review complex content

Before considering the task complete, check:

• parsing outputs exist
• chunk files exist when required
• reading index and session state are coherent
• extraction targets match the requested type
• complex-content reports are generated from real parsed outputs