API: Parser¶
Structural front-end: Markdown → Novel → Modules.
Abstract parser interface for novel ingestion.
All novel parsers must implement the NovelParser strategy. A parser takes raw text and converts it into a structured Novel object that can be consumed by the contract system.
This layer isolates file format concerns from narrative logic.
NovelParser ¶
Bases: ABC
Strategy interface for novel parsers.
Implementations of this class define how raw text is converted into a structured Novel model. Different parsers can be created for:
- CommonMark Markdown
- HTML
- Scrivener exports
- Plain text
without changing the rest of the system.
parse
abstractmethod
¶
parse(text, *, title)
Parse raw novel text into a Novel object.
:param text: Raw novel content. :param title: Title of the novel. :return: Parsed Novel instance.
CommonMark (Markdown) novel parser.
This parser consumes segmented Markdown produced by the segmentation stage.
It recognizes: - Chapters starting with: # Chapter Title - Modules starting with: ## Scene ..., ## Exposition ..., ## Transition ...
Each module is converted into a Module object with: - type inference - line anchors - start and end text previews - stable module IDs
This parser is intentionally strict. It assumes segmentation has already inserted valid chapter and module markers. If no modules are found, the segmentation stage failed or was skipped, and the pipeline is invalid.
CommonMarkNovelParser ¶
Bases: NovelParser
Parser for CommonMark-style Markdown novels.
This parser operates strictly on annotated Markdown generated by the segmentation stage. It does not attempt to infer structure from raw prose.
Recognizes: - # Chapter headings - ## Module headings
Module type is inferred from the first word of the module title: Scene, Exposition, Transition, or OTHER.
parse ¶
parse(text, *, title)
Parse segmented CommonMark Markdown into a Novel model.
Expected structure:
# Chapter Title
## Scene ...
## Exposition ...
## Transition ...
Everything between two module headers becomes one Module.
:param text: Annotated Markdown text (output of the segmentation stage). :param title: Title of the novel. :return: Novel object containing parsed modules.
The parser layer is intentionally mechanical.
It does not interpret meaning. It only finds joints.