# neurostuff/pondie architecture

> Architecture diagram of the GitHub repository neurostuff/pondie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neurostuff/pondie
- Repository: https://github.com/neurostuff/pondie

## Overview

Pondie turns neuroimaging papers into validated, queryable records, maps source wording to shared values, and selects records and coordinates for meta-analysis. The documented extraction journey moves from paper inputs through nine ordered stages to record assembly and validation; optional repair is separate. Normalization and query selection are downstream capabilities. The graph follows README-described contracts and stages; source excerpts are partial, so implementation-level calls not explicitly evidenced are omitted.

Main entry points: [`pondie/extraction/stages.py`](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/stages.py) (Extraction stages), [`pondie/extraction/record/builder.py`](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/record/builder.py) (Record assembly), [`pondie/normalization`](https://github.com/neurostuff/pondie/tree/main/pondie/normalization) (Field normalization), [`pondie/extraction/driver.py`](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/driver.py) (Extraction runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Paper extraction"]
  node_pipeline["Extraction runner<br/>[driver.py]"]
  node_stages["Extraction stages<br/>[stages.py]"]
  node_corpus["Corpus preparation"]
  node_prompts["Prompt rendering"]
  node_evidence["Evidence retrieval"]
  node_repair["Optional repair"]
end

subgraph group_record["Record contracts"]
  node_builder["Record assembly<br/>[builder.py]"]
  node_recordfix["Deterministic fixes"]
  node_validation["Record validation<br/>[validate.py]"]
end

subgraph group_normalize["Normalization"]
  node_normalizer["Field normalization"]
end

subgraph group_query["Meta-analysis selection"]
  node_query["Pooling selection<br/>[engine.py]"]
end

subgraph group_shared["Shared foundations"]
  node_schema["Schema contract<br/>[reader.py]"]
  node_formats["Record formats<br/>[values.py]"]
  node_vocabulary[("Shared vocabularies")]
  node_paths["Data locations<br/>[paths.py]"]
end

node_researcher(("Researcher"))
node_papers[("Paper corpus")]
node_model["Model gateway"]
node_selected["Meta-analysis result"]

node_researcher -->|"runs extraction"| node_pipeline
node_papers -->|"provides papers"| node_pipeline
node_pipeline -->|"runs stages"| node_stages
node_stages -->|"requests model work"| node_prompts
node_stages -->|"sends model calls"| node_model
node_stages -->|"gathers evidence"| node_evidence
node_corpus -->|"prepares inputs"| node_papers
node_stages -->|"builds record"| node_builder
node_builder -->|"applies repairs"| node_recordfix
node_builder -->|"checks rules"| node_validation
node_validation -->|"checks conformance"| node_schema
node_builder -->|"uses value wrappers"| node_formats
node_stages -.->|"optionally repairs"| node_repair
node_researcher -->|"normalizes records"| node_normalizer
node_normalizer -->|"maps shared terms"| node_vocabulary
node_researcher -->|"selects records"| node_query
node_query -->|"reads record values"| node_formats
node_query -->|"returns pooled subset"| node_selected
node_normalizer -->|"reads record wording"| node_formats
node_pipeline -->|"uses run locations"| node_paths
node_normalizer -->|"uses data locations"| node_paths

click node_pipeline "https://github.com/neurostuff/pondie/blob/main/pondie/extraction/driver.py"
click node_stages "https://github.com/neurostuff/pondie/blob/main/pondie/extraction/stages.py"
click node_corpus "https://github.com/neurostuff/pondie/tree/main/pondie/extraction/corpus"
click node_prompts "https://github.com/neurostuff/pondie/tree/main/pondie/extraction/prompt"
click node_evidence "https://github.com/neurostuff/pondie/tree/main/pondie/extraction/evidence"
click node_repair "https://github.com/neurostuff/pondie/tree/main/pondie/extraction/repair"
click node_builder "https://github.com/neurostuff/pondie/blob/main/pondie/extraction/record/builder.py"
click node_recordfix "https://github.com/neurostuff/pondie/tree/main/pondie/extraction/record/fix"
click node_validation "https://github.com/neurostuff/pondie/blob/main/pondie/extraction/record/validate.py"
click node_schema "https://github.com/neurostuff/pondie/blob/main/pondie/schema/reader.py"
click node_formats "https://github.com/neurostuff/pondie/blob/main/pondie/formats/values.py"
click node_vocabulary "https://github.com/neurostuff/pondie/tree/main/pondie/vocabularies"
click node_normalizer "https://github.com/neurostuff/pondie/tree/main/pondie/normalization"
click node_query "https://github.com/neurostuff/pondie/blob/main/pondie/query/engine.py"
click node_paths "https://github.com/neurostuff/pondie/blob/main/pondie/paths.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline,node_stages,node_corpus,node_prompts,node_evidence,node_repair toneBlue
class node_builder,node_recordfix,node_validation,node_papers toneAmber
class node_normalizer toneMint
class node_query toneRose
class node_schema,node_formats,node_vocabulary,node_paths,node_researcher,node_model,node_selected toneIndigo
```

## Components

### Paper extraction

- [Extraction runner](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/driver.py): `pondie/extraction/driver.py`
- [Extraction stages](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/stages.py): `pondie/extraction/stages.py`
- [Corpus preparation](https://github.com/neurostuff/pondie/tree/main/pondie/extraction/corpus): `pondie/extraction/corpus`
- [Prompt rendering](https://github.com/neurostuff/pondie/tree/main/pondie/extraction/prompt): `pondie/extraction/prompt`
- [Evidence retrieval](https://github.com/neurostuff/pondie/tree/main/pondie/extraction/evidence): `pondie/extraction/evidence`
- [Optional repair](https://github.com/neurostuff/pondie/tree/main/pondie/extraction/repair): `pondie/extraction/repair`

### Record contracts

- [Record assembly](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/record/builder.py): `pondie/extraction/record/builder.py`
- [Deterministic fixes](https://github.com/neurostuff/pondie/tree/main/pondie/extraction/record/fix): `pondie/extraction/record/fix`
- [Record validation](https://github.com/neurostuff/pondie/blob/main/pondie/extraction/record/validate.py): `pondie/extraction/record/validate.py`

### Normalization

- [Field normalization](https://github.com/neurostuff/pondie/tree/main/pondie/normalization): `pondie/normalization`

### Meta-analysis selection

- [Pooling selection](https://github.com/neurostuff/pondie/blob/main/pondie/query/engine.py): `pondie/query/engine.py`

### Shared foundations

- [Schema contract](https://github.com/neurostuff/pondie/blob/main/pondie/schema/reader.py): `pondie/schema/reader.py`
- [Record formats](https://github.com/neurostuff/pondie/blob/main/pondie/formats/values.py): `pondie/formats/values.py`
- [Shared vocabularies](https://github.com/neurostuff/pondie/tree/main/pondie/vocabularies): `pondie/vocabularies`
- [Data locations](https://github.com/neurostuff/pondie/blob/main/pondie/paths.py): `pondie/paths.py`

### Other components

- **Researcher**
- **Paper corpus**
- **Model gateway**
- **Meta-analysis result**

## Connections

- Researcher → Extraction runner: runs extraction (evidence: `README.md`)
- Paper corpus → Extraction runner: provides papers (evidence: `README.md`)
- Extraction runner → Extraction stages: runs stages (evidence: `README.md`)
- Extraction stages → Prompt rendering: requests model work (evidence: `README.md`)
- Extraction stages → Model gateway: sends model calls (evidence: `README.md`)
- Extraction stages → Evidence retrieval: gathers evidence (evidence: `README.md`)
- Corpus preparation → Paper corpus: prepares inputs (evidence: `README.md`)
- Extraction stages → Record assembly: builds record (evidence: `README.md`)
- Record assembly → Deterministic fixes: applies repairs (evidence: `README.md`)
- Record assembly → Record validation: checks rules (evidence: `README.md`)
- Record validation → Schema contract: checks conformance (evidence: `README.md`)
- Record assembly → Record formats: uses value wrappers (evidence: `README.md`)
- Extraction stages → Optional repair: optionally repairs (evidence: `README.md`)
- Researcher → Field normalization: normalizes records (evidence: `README.md`)
- Field normalization → Shared vocabularies: maps shared terms (evidence: `README.md`)
- Researcher → Pooling selection: selects records (evidence: `README.md`)
- Pooling selection → Record formats: reads record values (evidence: `README.md`)
- Pooling selection → Meta-analysis result: returns pooled subset (evidence: `README.md`)
- Field normalization → Record formats: reads record wording (evidence: `README.md`)
- Extraction runner → Data locations: uses run locations
- Field normalization → Data locations: uses data locations (evidence: `pondie/normalization/_records.py`)