# matrx_ai.processing.blocks.parsers — Module Overview


## IMPORTANT: Do not edit auto-generated sections.

> This document is partially auto-generated. Sections tagged `<!-- AUTO:id -->` are refreshed by the generator.
> Everything else is yours to edit freely and will never be overwritten.

<!-- AUTO:meta -->
## About This Document

This file is **partially auto-generated**. Sections wrapped in `<!-- AUTO:id -->` tags
are overwritten each time the generator runs. Everything else is yours to edit freely.

| Field | Value |
|-------|-------|
| Module | `matrx_ai/processing/blocks/parsers` |
| Last generated | 2026-04-07 11:38 |
| Output file | `matrx_ai/processing/blocks/parsers/MODULE_README.md` |
| Signature mode | `signatures` |

**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py matrx_ai/processing/blocks/parsers --mode signatures
```

**To add permanent notes:** Write anywhere outside the `<!-- AUTO:... -->` blocks.
<!-- /AUTO:meta -->

<!-- HUMAN-EDITABLE: This section is yours. Agents & Humans can edit this section freely — it will not be overwritten. -->

## Architecture

> **Fill this in.** Describe the execution flow and layer map for this module.
> See `utils/code_context/MODULE_README_SPEC.md` for the recommended format.
>
> Suggested structure:
>
> ### Layers
> | File | Role |
> |------|------|
> | `entry.py` | Public entry point — receives requests, returns results |
> | `engine.py` | Core dispatch logic |
> | `models.py` | Shared data types |
>
> ### Call Flow (happy path)
> ```
> entry_function() → engine.dispatch() → implementation()
> ```


<!-- AUTO:tree -->
## Directory Tree

> Auto-generated. 24 files across 1 directories.

```
matrx_ai/processing/blocks/parsers/
├── MODULE_README.md
├── __init__.py
├── artifact_parser.py
├── comparison_parser.py
├── decision_parser.py
├── decision_tree_parser.py
├── diagram_parser.py
├── diff_parser.py
├── flashcard_parser.py
├── math_problem_parser.py
├── presentation_parser.py
├── progress_parser.py
├── questionnaire_parser.py
├── quiz_parser.py
├── recipe_parser.py
├── research_parser.py
├── resources_parser.py
├── table_parser.py
├── task_parser.py
├── timeline_parser.py
├── timeline_stream_parser.py
├── transcript_parser.py
├── troubleshooting_parser.py
# excluded: 1 .md
```
<!-- /AUTO:tree -->

<!-- AUTO:signatures -->
## API Signatures

> Auto-generated via `output_mode="signatures"`. ~5-10% token cost vs full source.
> For full source, open the individual files directly.

```
---
Filepath: matrx_ai/processing/blocks/parsers/recipe_parser.py  [python]

  def parse_recipe(content: str, *, is_final: bool = False) -> RecipeBlockData | None


---
Filepath: matrx_ai/processing/blocks/parsers/troubleshooting_parser.py  [python]

  def parse_troubleshooting(content: str) -> TroubleshootingBlockData | None
  def _detect_severity(text: str) -> str | None


---
Filepath: matrx_ai/processing/blocks/parsers/diff_parser.py  [python]

  def looks_like_diff(content: str) -> bool
  def detect_diff_style(content: str) -> str


---
Filepath: matrx_ai/processing/blocks/parsers/progress_parser.py  [python]

  def parse_progress(content: str) -> ProgressTrackerBlockData | None


---
Filepath: matrx_ai/processing/blocks/parsers/questionnaire_parser.py  [python]

  def _extract_bold(text: str) -> str
  def _is_list_item(line: str) -> bool
  def _parse_list_block(lines: list[str], start: int) -> tuple[list[dict[str, Any]], int]
  def parse_questionnaire(content: str, *, is_final: bool = False) -> QuestionnaireBlockData | None
  def finalize_section() -> None


---
Filepath: matrx_ai/processing/blocks/parsers/decision_parser.py  [python]

  def parse_decision(inner_content: str, attributes: dict[str, str], block_index: int = 0) -> DecisionBlockData | None
  def parse_decision_from_raw_xml(full_xml: str, block_index: int = 0) -> DecisionBlockData | None
  def _parse_xml_attributes(attr_string: str) -> dict[str, str]


---
Filepath: matrx_ai/processing/blocks/parsers/__init__.py  [python]



---
Filepath: matrx_ai/processing/blocks/parsers/flashcard_parser.py  [python]

  def parse_flashcards(content: str, *, is_final: bool = False) -> FlashcardsBlockData
  def seal_card(back_text: str | None) -> None


---
Filepath: matrx_ai/processing/blocks/parsers/resources_parser.py  [python]

  def parse_resources(content: str) -> ResourcesBlockData | None
  def _parse_resource_item(text: str, index: int) -> ResourceItem


---
Filepath: matrx_ai/processing/blocks/parsers/math_problem_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_math_problem(content: str) -> MathProblemBlockData | None
  def _parse_solution(raw: dict) -> MathSolution
  def _parse_steps_list(steps_raw: Any) -> list[MathSolutionStep]


---
Filepath: matrx_ai/processing/blocks/parsers/presentation_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_presentation(content: str) -> PresentationBlockData | None
  def _parse_slide(raw: object) -> Slide | None


---
Filepath: matrx_ai/processing/blocks/parsers/research_parser.py  [python]

  def parse_research(content: str) -> ResearchBlockData | None
  def _parse(text: str) -> ResearchBlockData
  def _extract_findings(body: str, section_id: str, start_idx: int) -> list[ResearchFinding]
  def _split_bold_items(body: str) -> list[str]
  def _split_numbered_or_bold_items(body: str) -> list[str]
  def _split_title_desc(text: str) -> tuple[str, str]


---
Filepath: matrx_ai/processing/blocks/parsers/timeline_stream_parser.py  [python]

  class _State(Enum):
  class TimelineStreamParser:
      def __init__(self) -> None
      def feed(self, content: str) -> TimelineBlockData | None
      def finalize(self) -> TimelineBlockData
      def _process_line(self, line: str) -> bool
      def _flush_pending_event(self) -> bool
      def _snapshot(self) -> TimelineBlockData
  def _parse_event(text: str, sub_desc: str, period_name: str, index: int) -> TimelineEvent


---
Filepath: matrx_ai/processing/blocks/parsers/artifact_parser.py  [python]

  def parse_artifact(inner_content: str, metadata: dict | None = None) -> ArtifactBlockData | None


---
Filepath: matrx_ai/processing/blocks/parsers/comparison_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_comparison(content: str) -> ComparisonBlockData | None
  def _infer_type(values: list[Any]) -> str
  def _default_higher_is_better(crit_type: str) -> bool


---
Filepath: matrx_ai/processing/blocks/parsers/transcript_parser.py  [python]

  def parse_transcript(content: str, *, is_final: bool = False) -> TranscriptBlockData


---
Filepath: matrx_ai/processing/blocks/parsers/table_parser.py  [python]

  def parse_table(content: str, *, is_final: bool = False) -> TableBlockData | None
  def _parse_row(line: str) -> list[str]


---
Filepath: matrx_ai/processing/blocks/parsers/timeline_parser.py  [python]

  def parse_timeline(content: str) -> TimelineBlockData | None
  def _parse_event_text(text: str) -> tuple[str, str, str, str | None]


---
Filepath: matrx_ai/processing/blocks/parsers/decision_tree_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_decision_tree(content: str) -> DecisionTreeBlockData | None
  def _process_node(data: dict, node_id: str) -> DecisionNode


---
Filepath: matrx_ai/processing/blocks/parsers/quiz_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_quiz(content: str) -> QuizBlockData | None
  def _parse_question(q: dict) -> QuizQuestion | None


---
Filepath: matrx_ai/processing/blocks/parsers/task_parser.py  [python]

  def _clean_id(text: str) -> str
  def parse_tasks(content: str, *, is_final: bool = False) -> TasksBlockData


---
Filepath: matrx_ai/processing/blocks/parsers/diagram_parser.py  [python]

  def _get(d: dict, *keys: str, default = None)
  def parse_diagram(content: str) -> DiagramBlockData | None
  def _default_position(index: int, diagram_type: str) -> Position
```
<!-- /AUTO:signatures -->

<!-- AUTO:callers -->
## Upstream Callers

> Auto-discovered by scanning all project files that import from this module.
> Set `ENTRY_POINTS` in `generate_readme.py` to pin specific functions.

| Caller | Calls |
|--------|-------|
| `matrx_ai/processing/blocks/stream_processor.py` | `TimelineStreamParser()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `detect_diff_style()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `detect_diff_style()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `looks_like_diff()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `looks_like_diff()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_artifact()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_comparison()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_decision()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_decision_tree()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_diagram()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_flashcards()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_flashcard_parser.py` | `parse_flashcards()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_math_problem()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_presentation()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_progress()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_questionnaire()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_quiz()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_quiz()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_recipe()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_recipe()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_research()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_resources()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_table()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_table()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_tasks()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_tasks()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_timeline()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_timeline()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_transcript()` |
| `matrx_ai/processing/blocks/tests/test_parsers/test_various_parsers.py` | `parse_transcript()` |
| `matrx_ai/processing/blocks/stream_processor.py` | `parse_troubleshooting()` |
<!-- /AUTO:callers -->

<!-- AUTO:dependencies -->
## Dependencies

**Internal modules:** matrx_ai.processing
<!-- /AUTO:dependencies -->

<!-- AUTO:config -->
## Generation Config

> Auto-managed. Contains the exact parameters used to generate this README.
> Used by parent modules to auto-refresh this file when it is stale.
> Do not edit manually — changes will be overwritten on the next run.

```json
{
  "subdirectory": "matrx_ai/processing/blocks/parsers",
  "mode": "signatures",
  "scope": null,
  "project_noise": null,
  "include_call_graph": false,
  "entry_points": null,
  "call_graph_exclude": [
    "tests"
  ],
  "signatures_exclude": [
    "tests",
    "db",
    "local_data",
    "docs"
  ]
}
```
<!-- /AUTO:config -->
