# leojeshua/reader architecture

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

- Interactive diagram: https://gitdiagram.com/leojeshua/reader
- Repository: https://github.com/leojeshua/reader

## Overview

READER attributes black-box LLM responses to enrolled sources. Its main workflow loads response records, forms query-plus-response or response-only inputs, extracts frozen-proxy hidden-state fingerprints, trains a linear source probe, and accumulates evidence across query budgets. Separate branches support relationship benchmarks, stress and diagnostic experiments, and reporting. Some links reflect README descriptions or SOURCE INDEX references rather than inspected implementations; those evidence limits are noted by citing the README or the referencing source.

Main entry points: [`src/llm_api_provenance/framework/runners.py`](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/framework/runners.py) (Experiment runner), [`src/llm_api_provenance/tasks/closed_set.py`](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/tasks/closed_set.py) (Closed-set task), [`src/llm_api_provenance/methods/reader.py`](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/methods/reader.py) (Frozen proxy reader), [`src/llm_api_provenance/evaluation/grouped.py`](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/grouped.py) (Budget accumulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and release"]
  node_release["Dataset release<br/>[release.py]"]
  node_records["Response records<br/>[records.py]"]
end

subgraph group_pipeline["Attribution pipeline"]
  node_config["Run configuration<br/>[config.py]"]
  node_runner["Experiment runner<br/>[runners.py]"]
  node_inputform["Input formatting<br/>[inputs.py]"]
  node_proxy["Frozen proxy reader<br/>[reader.py]"]
  node_dct["DCT fingerprints<br/>[dct.py]"]
  node_features["Feature archives<br/>[io.py]"]
  node_probe["Linear source probe<br/>[probe.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_closedset["Closed-set task<br/>[closed_set.py]"]
  node_folds["Prompt-grouped folds<br/>[protocol.py]"]
  node_accumulation["Budget accumulation<br/>[grouped.py]"]
  node_evidence["Bayesian evidence<br/>[evidence.py]"]
  node_relationship["Relationship benchmark<br/>[relationship.py]"]
  node_bench["Bench-A experiment<br/>[bench_a.py]"]
end

subgraph group_analysis["Diagnostics"]
  node_stress["Stress tests<br/>[stress.py]"]
  node_temporal["Temporal controls<br/>[temporal.py]"]
  node_layers["Layer scans<br/>[layers.py]"]
  node_geometry["Source geometry<br/>[geometry.py]"]
end

subgraph group_reporting["Reporting"]
  node_reportruns["Run reports<br/>[runs.py]"]
  node_figures["Figures and tables<br/>[figures.py]"]
  node_statistics["Statistical analysis<br/>[statistics.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures runs"| node_config
node_release -.->|"provides responses"| node_records
node_runner -->|"uses configuration"| node_config
node_runner -->|"loads dataset"| node_records
node_runner -->|"selects input"| node_inputform
node_runner -->|"invokes extraction"| node_proxy
node_proxy -->|"formats interaction"| node_inputform
node_proxy -->|"extracts fingerprint"| node_dct
node_runner -->|"saves features"| node_features
node_runner -->|"runs task"| node_closedset
node_closedset -->|"loads features"| node_features
node_closedset -->|"builds folds"| node_folds
node_closedset -->|"trains probe"| node_probe
node_closedset -->|"scores budgets"| node_accumulation
node_accumulation -->|"accumulates evidence"| node_evidence
node_runner -->|"dispatches benchmark"| node_relationship
node_runner -->|"dispatches Bench-A"| node_bench
node_researcher -->|"runs diagnostics"| node_stress
node_researcher -->|"runs controls"| node_temporal
node_researcher -->|"scans layers"| node_layers
node_researcher -->|"inspects geometry"| node_geometry
node_researcher -->|"generates reports"| node_figures
node_figures -->|"reads completed runs"| node_reportruns
node_researcher -->|"requests statistics"| node_statistics

click node_release "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/data/release.py"
click node_records "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/data/records.py"
click node_config "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/framework/config.py"
click node_runner "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/framework/runners.py"
click node_inputform "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/inputs.py"
click node_proxy "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/methods/reader.py"
click node_dct "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/features/dct.py"
click node_features "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/features/io.py"
click node_probe "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/training/probe.py"
click node_closedset "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/tasks/closed_set.py"
click node_folds "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/protocol.py"
click node_accumulation "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/grouped.py"
click node_evidence "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/evidence.py"
click node_relationship "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/tasks/relationship.py"
click node_bench "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/bench_a.py"
click node_stress "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/stress.py"
click node_temporal "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/temporal.py"
click node_layers "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/layers.py"
click node_geometry "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/geometry.py"
click node_reportruns "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/runs.py"
click node_figures "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/figures.py"
click node_statistics "https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/statistics.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_release,node_records toneBlue
class node_config,node_runner,node_inputform,node_proxy,node_dct,node_features,node_probe toneAmber
class node_closedset,node_folds,node_accumulation,node_evidence,node_relationship,node_bench toneMint
class node_stress,node_temporal,node_layers,node_geometry toneRose
class node_reportruns,node_figures,node_statistics,node_researcher toneIndigo
```

## Components

### Data and release

- [Dataset release](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/data/release.py): `src/llm_api_provenance/data/release.py`
- [Response records](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/data/records.py): `src/llm_api_provenance/data/records.py`

### Attribution pipeline

- [Run configuration](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/framework/config.py): `src/llm_api_provenance/framework/config.py`
- [Experiment runner](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/framework/runners.py): `src/llm_api_provenance/framework/runners.py`
- [Input formatting](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/inputs.py): `src/llm_api_provenance/inputs.py`
- [Frozen proxy reader](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/methods/reader.py): `src/llm_api_provenance/methods/reader.py`
- [DCT fingerprints](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/features/dct.py): `src/llm_api_provenance/features/dct.py`
- [Feature archives](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/features/io.py): `src/llm_api_provenance/features/io.py`
- [Linear source probe](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/training/probe.py): `src/llm_api_provenance/training/probe.py`

### Evaluation

- [Closed-set task](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/tasks/closed_set.py): `src/llm_api_provenance/tasks/closed_set.py`
- [Prompt-grouped folds](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/protocol.py): `src/llm_api_provenance/evaluation/protocol.py`
- [Budget accumulation](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/grouped.py): `src/llm_api_provenance/evaluation/grouped.py`
- [Bayesian evidence](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/evaluation/evidence.py): `src/llm_api_provenance/evaluation/evidence.py`
- [Relationship benchmark](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/tasks/relationship.py): `src/llm_api_provenance/tasks/relationship.py`
- [Bench-A experiment](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/bench_a.py): `src/llm_api_provenance/experiments/bench_a.py`

### Diagnostics

- [Stress tests](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/stress.py): `src/llm_api_provenance/experiments/stress.py`
- [Temporal controls](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/temporal.py): `src/llm_api_provenance/experiments/temporal.py`
- [Layer scans](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/layers.py): `src/llm_api_provenance/experiments/layers.py`
- [Source geometry](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/experiments/geometry.py): `src/llm_api_provenance/experiments/geometry.py`

### Reporting

- [Run reports](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/runs.py): `src/llm_api_provenance/reporting/runs.py`
- [Figures and tables](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/figures.py): `src/llm_api_provenance/reporting/figures.py`
- [Statistical analysis](https://github.com/leojeshua/reader/blob/main/src/llm_api_provenance/reporting/statistics.py): `src/llm_api_provenance/reporting/statistics.py`

### Other components

- **Researcher**

## Connections

- Researcher → Run configuration: configures runs (evidence: `README.md`)
- Dataset release → Response records: provides responses
- Experiment runner → Run configuration: uses configuration (evidence: `src/llm_api_provenance/framework/runners.py`)
- Experiment runner → Response records: loads dataset (evidence: `src/llm_api_provenance/framework/runners.py`)
- Experiment runner → Input formatting: selects input (evidence: `src/llm_api_provenance/framework/runners.py`)
- Experiment runner → Frozen proxy reader: invokes extraction (evidence: `src/llm_api_provenance/framework/runners.py`)
- Frozen proxy reader → Input formatting: formats interaction (evidence: `src/llm_api_provenance/methods/reader.py`)
- Frozen proxy reader → DCT fingerprints: extracts fingerprint (evidence: `src/llm_api_provenance/methods/reader.py`)
- Experiment runner → Feature archives: saves features (evidence: `src/llm_api_provenance/framework/runners.py`)
- Experiment runner → Closed-set task: runs task (evidence: `src/llm_api_provenance/framework/runners.py`)
- Closed-set task → Feature archives: loads features (evidence: `src/llm_api_provenance/tasks/closed_set.py`)
- Closed-set task → Prompt-grouped folds: builds folds (evidence: `src/llm_api_provenance/tasks/closed_set.py`)
- Closed-set task → Linear source probe: trains probe (evidence: `src/llm_api_provenance/tasks/closed_set.py`)
- Closed-set task → Budget accumulation: scores budgets (evidence: `src/llm_api_provenance/tasks/closed_set.py`)
- Budget accumulation → Bayesian evidence: accumulates evidence (evidence: `src/llm_api_provenance/evaluation/grouped.py`)
- Experiment runner → Relationship benchmark: dispatches benchmark (evidence: `src/llm_api_provenance/framework/runners.py`)
- Experiment runner → Bench-A experiment: dispatches Bench-A (evidence: `src/llm_api_provenance/framework/runners.py`)
- Researcher → Stress tests: runs diagnostics (evidence: `README.md`)
- Researcher → Temporal controls: runs controls (evidence: `README.md`)
- Researcher → Layer scans: scans layers (evidence: `README.md`)
- Researcher → Source geometry: inspects geometry (evidence: `README.md`)
- Researcher → Figures and tables: generates reports (evidence: `README.md`)
- Figures and tables → Run reports: reads completed runs (evidence: `src/llm_api_provenance/reporting/figures.py`)
- Researcher → Statistical analysis: requests statistics (evidence: `README.md`)
