# hari-goml/retrace architecture

> Architecture diagram of the GitHub repository hari-goml/retrace, 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/hari-goml/retrace
- Repository: https://github.com/hari-goml/retrace

## Overview

Retrace prepares a structured fact knowledge base, trains a baseline model, selectively erases requested facts with a stackable LoRA adapter, verifies forgetting and retention, and produces a report. Users can run these stages through the CLI or interact with the serving UI, which supports live adapter switching and erasure workflows. The graph preserves documented preparation capabilities such as paraphrase, probe, control-fact, and neighbor generation. Some source was not sampled; edges are limited to relationships visible in excerpts, the SOURCE INDEX, or README statements.

Main entry points: [`retrace/knowledge/build.py`](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/build.py) (Knowledge builder), [`retrace/cli.py`](https://github.com/hari-goml/retrace/blob/main/retrace/cli.py) (CLI commands), [`retrace/verification/harness.py`](https://github.com/hari-goml/retrace/blob/main/retrace/verification/harness.py) (Retention verification), [`retrace/serving/engine.py`](https://github.com/hari-goml/retrace/blob/main/retrace/serving/engine.py) (Serving engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Knowledge preparation"]
  node_schema["Fact schema<br/>[schema.py]"]
  node_dataset["Fact dataset<br/>[dataset.py]"]
  node_knowledge_build["Knowledge builder<br/>[build.py]"]
  node_paraphrase["Fact paraphrases<br/>[paraphrase.py]"]
  node_probes["Probe generation<br/>[probes.py]"]
  node_controls["Control facts<br/>[controls.py]"]
  node_neighbors["Neighbor graph<br/>[neighbors.py]"]
  node_resolver["Fact resolver<br/>[resolver.py]"]
end

subgraph group_training["Baseline training"]
  node_training_build["Training builder<br/>[build.py]"]
  node_training_data["Training data<br/>[data.py]"]
  node_finetune["Baseline fine-tuning<br/>[finetune.py]"]
  node_gate["Baseline quality gate<br/>[gate.py]"]
end

subgraph group_erasure["Selective erasure"]
  node_request["Erasure request<br/>[request.py]"]
  node_eraser_build["Erasure builder<br/>[build.py]"]
  node_unlearn["LoRA unlearning<br/>[unlearn.py]"]
end

subgraph group_evaluation["Verification and reporting"]
  node_verification["Retention verification<br/>[harness.py]"]
  node_adversarial["Adversarial probes<br/>[adversarial.py]"]
  node_metrics["Verification metrics<br/>[metrics.py]"]
  node_report["Erasure report<br/>[generate.py]"]
  node_report_render["Markdown and HTML<br/>[markdown_html.py]"]
end

subgraph group_runtime["User runtime"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_config["Stage configuration<br/>[config.py]"]
  node_model["Model inference<br/>[modeling.py]"]
  node_scoring["Answer scoring<br/>[scoring.py]"]
  node_serving_ui["Interactive UI<br/>[app.py]"]
  node_serving_engine["Serving engine<br/>[engine.py]"]
  node_artifacts[("Pipeline artifacts<br/>[serialize.py]")]
  node_errors["Domain errors<br/>[exceptions.py]"]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"starts preparation"| node_knowledge_build
node_cli -->|"starts training"| node_training_build
node_cli -->|"starts erasure"| node_eraser_build
node_cli -->|"starts verification"| node_verification
node_cli -->|"starts reporting"| node_report
node_knowledge_build -->|"loads facts"| node_dataset
node_dataset -->|"validates records"| node_schema
node_knowledge_build -->|"generates paraphrases"| node_paraphrase
node_knowledge_build -->|"generates probes"| node_probes
node_knowledge_build -->|"builds controls"| node_controls
node_knowledge_build -->|"builds neighbors"| node_neighbors
node_training_build -->|"trains baseline"| node_finetune
node_training_build -->|"checks baseline"| node_gate
node_finetune -->|"loads training data"| node_training_data
node_gate -->|"scores probes"| node_model
node_gate -->|"aggregates answers"| node_scoring
node_eraser_build -->|"resolves selection"| node_request
node_eraser_build -->|"trains adapter"| node_unlearn
node_request -->|"selects facts"| node_dataset
node_request -->|"selects hard retains"| node_neighbors
node_unlearn -->|"uses collator"| node_training_data
node_unlearn -->|"uses inference wrapper"| node_model
node_verification -->|"evaluates outputs"| node_model
node_verification -->|"uses adversarial probes"| node_adversarial
node_verification -->|"computes metrics"| node_metrics
node_verification -->|"scores answers"| node_scoring
node_report -->|"renders report"| node_report_render
node_serving_ui -->|"uses engine"| node_serving_engine
node_serving_engine -->|"resolves queries"| node_resolver
node_serving_engine -->|"generates answers"| node_model
node_serving_engine -->|"resolves erasure"| node_request
node_serving_engine -->|"runs verification"| node_verification
node_serving_engine -->|"loads reports"| node_report
node_knowledge_build -->|"writes artifacts"| node_artifacts
node_training_build -->|"writes artifacts"| node_artifacts
node_eraser_build -->|"writes artifacts"| node_artifacts
node_verification -->|"writes results"| node_artifacts
node_report -->|"reads artifacts"| node_artifacts
node_cli -->|"sets options"| node_config

click node_cli "https://github.com/hari-goml/retrace/blob/main/retrace/cli.py"
click node_config "https://github.com/hari-goml/retrace/blob/main/retrace/config.py"
click node_schema "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/schema.py"
click node_dataset "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/dataset.py"
click node_knowledge_build "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/build.py"
click node_paraphrase "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/paraphrase.py"
click node_probes "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/probes.py"
click node_controls "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/controls.py"
click node_neighbors "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/neighbors.py"
click node_resolver "https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/resolver.py"
click node_training_build "https://github.com/hari-goml/retrace/blob/main/retrace/training/build.py"
click node_training_data "https://github.com/hari-goml/retrace/blob/main/retrace/training/data.py"
click node_finetune "https://github.com/hari-goml/retrace/blob/main/retrace/training/finetune.py"
click node_gate "https://github.com/hari-goml/retrace/blob/main/retrace/training/gate.py"
click node_model "https://github.com/hari-goml/retrace/blob/main/retrace/modeling.py"
click node_request "https://github.com/hari-goml/retrace/blob/main/retrace/erasure/request.py"
click node_eraser_build "https://github.com/hari-goml/retrace/blob/main/retrace/erasure/build.py"
click node_unlearn "https://github.com/hari-goml/retrace/blob/main/retrace/erasure/unlearn.py"
click node_verification "https://github.com/hari-goml/retrace/blob/main/retrace/verification/harness.py"
click node_adversarial "https://github.com/hari-goml/retrace/blob/main/retrace/verification/adversarial.py"
click node_metrics "https://github.com/hari-goml/retrace/blob/main/retrace/verification/metrics.py"
click node_scoring "https://github.com/hari-goml/retrace/blob/main/retrace/scoring.py"
click node_report "https://github.com/hari-goml/retrace/blob/main/retrace/reporting/generate.py"
click node_report_render "https://github.com/hari-goml/retrace/blob/main/retrace/reporting/markdown_html.py"
click node_serving_ui "https://github.com/hari-goml/retrace/blob/main/retrace/serving/app.py"
click node_serving_engine "https://github.com/hari-goml/retrace/blob/main/retrace/serving/engine.py"
click node_artifacts "https://github.com/hari-goml/retrace/blob/main/retrace/serialize.py"
click node_errors "https://github.com/hari-goml/retrace/blob/main/retrace/exceptions.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_schema,node_dataset,node_knowledge_build,node_paraphrase,node_probes,node_controls,node_neighbors,node_resolver toneBlue
class node_training_build,node_training_data,node_finetune,node_gate toneAmber
class node_request,node_eraser_build,node_unlearn toneMint
class node_verification,node_adversarial,node_metrics,node_report,node_report_render toneRose
class node_cli,node_config,node_model,node_scoring,node_serving_ui,node_serving_engine,node_artifacts,node_errors,node_user toneIndigo
```

## Components

### Knowledge preparation

- [Fact schema](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/schema.py): `retrace/knowledge/schema.py`
- [Fact dataset](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/dataset.py): `retrace/knowledge/dataset.py`
- [Knowledge builder](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/build.py): `retrace/knowledge/build.py`
- [Fact paraphrases](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/paraphrase.py): `retrace/knowledge/paraphrase.py`
- [Probe generation](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/probes.py): `retrace/knowledge/probes.py`
- [Control facts](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/controls.py): `retrace/knowledge/controls.py`
- [Neighbor graph](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/neighbors.py): `retrace/knowledge/neighbors.py`
- [Fact resolver](https://github.com/hari-goml/retrace/blob/main/retrace/knowledge/resolver.py): `retrace/knowledge/resolver.py`

### Baseline training

- [Training builder](https://github.com/hari-goml/retrace/blob/main/retrace/training/build.py): `retrace/training/build.py`
- [Training data](https://github.com/hari-goml/retrace/blob/main/retrace/training/data.py): `retrace/training/data.py`
- [Baseline fine-tuning](https://github.com/hari-goml/retrace/blob/main/retrace/training/finetune.py): `retrace/training/finetune.py`
- [Baseline quality gate](https://github.com/hari-goml/retrace/blob/main/retrace/training/gate.py): `retrace/training/gate.py`

### Selective erasure

- [Erasure request](https://github.com/hari-goml/retrace/blob/main/retrace/erasure/request.py): `retrace/erasure/request.py`
- [Erasure builder](https://github.com/hari-goml/retrace/blob/main/retrace/erasure/build.py): `retrace/erasure/build.py`
- [LoRA unlearning](https://github.com/hari-goml/retrace/blob/main/retrace/erasure/unlearn.py): `retrace/erasure/unlearn.py`

### Verification and reporting

- [Retention verification](https://github.com/hari-goml/retrace/blob/main/retrace/verification/harness.py): `retrace/verification/harness.py`
- [Adversarial probes](https://github.com/hari-goml/retrace/blob/main/retrace/verification/adversarial.py): `retrace/verification/adversarial.py`
- [Verification metrics](https://github.com/hari-goml/retrace/blob/main/retrace/verification/metrics.py): `retrace/verification/metrics.py`
- [Erasure report](https://github.com/hari-goml/retrace/blob/main/retrace/reporting/generate.py): `retrace/reporting/generate.py`
- [Markdown and HTML](https://github.com/hari-goml/retrace/blob/main/retrace/reporting/markdown_html.py): `retrace/reporting/markdown_html.py`

### User runtime

- [CLI commands](https://github.com/hari-goml/retrace/blob/main/retrace/cli.py): `retrace/cli.py`
- [Stage configuration](https://github.com/hari-goml/retrace/blob/main/retrace/config.py): `retrace/config.py`
- [Model inference](https://github.com/hari-goml/retrace/blob/main/retrace/modeling.py): `retrace/modeling.py`
- [Answer scoring](https://github.com/hari-goml/retrace/blob/main/retrace/scoring.py): `retrace/scoring.py`
- [Interactive UI](https://github.com/hari-goml/retrace/blob/main/retrace/serving/app.py): `retrace/serving/app.py`
- [Serving engine](https://github.com/hari-goml/retrace/blob/main/retrace/serving/engine.py): `retrace/serving/engine.py`
- [Pipeline artifacts](https://github.com/hari-goml/retrace/blob/main/retrace/serialize.py): `retrace/serialize.py`
- [Domain errors](https://github.com/hari-goml/retrace/blob/main/retrace/exceptions.py): `retrace/exceptions.py`

### Other components

- **Engineer**

## Connections

- Engineer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Knowledge builder: starts preparation (evidence: `retrace/cli.py`)
- CLI commands → Training builder: starts training (evidence: `retrace/cli.py`)
- CLI commands → Erasure builder: starts erasure (evidence: `retrace/cli.py`)
- CLI commands → Retention verification: starts verification (evidence: `retrace/cli.py`)
- CLI commands → Erasure report: starts reporting (evidence: `retrace/cli.py`)
- Knowledge builder → Fact dataset: loads facts (evidence: `retrace/knowledge/build.py`)
- Fact dataset → Fact schema: validates records (evidence: `retrace/knowledge/dataset.py`)
- Knowledge builder → Fact paraphrases: generates paraphrases (evidence: `retrace/knowledge/build.py`)
- Knowledge builder → Probe generation: generates probes (evidence: `retrace/knowledge/build.py`)
- Knowledge builder → Control facts: builds controls (evidence: `retrace/knowledge/build.py`)
- Knowledge builder → Neighbor graph: builds neighbors (evidence: `retrace/knowledge/build.py`)
- Training builder → Baseline fine-tuning: trains baseline (evidence: `retrace/training/build.py`)
- Training builder → Baseline quality gate: checks baseline (evidence: `retrace/training/build.py`)
- Baseline fine-tuning → Training data: loads training data (evidence: `retrace/training/finetune.py`)
- Baseline quality gate → Model inference: scores probes (evidence: `retrace/training/gate.py`)
- Baseline quality gate → Answer scoring: aggregates answers (evidence: `retrace/training/gate.py`)
- Erasure builder → Erasure request: resolves selection (evidence: `retrace/erasure/build.py`)
- Erasure builder → LoRA unlearning: trains adapter (evidence: `retrace/erasure/build.py`)
- Erasure request → Fact dataset: selects facts (evidence: `retrace/erasure/request.py`)
- Erasure request → Neighbor graph: selects hard retains (evidence: `retrace/erasure/request.py`)
- LoRA unlearning → Training data: uses collator (evidence: `retrace/erasure/unlearn.py`)
- LoRA unlearning → Model inference: uses inference wrapper (evidence: `retrace/erasure/unlearn.py`)
- Retention verification → Model inference: evaluates outputs (evidence: `retrace/verification/harness.py`)
- Retention verification → Adversarial probes: uses adversarial probes (evidence: `retrace/verification/harness.py`)
- Retention verification → Verification metrics: computes metrics (evidence: `retrace/verification/harness.py`)
- Retention verification → Answer scoring: scores answers (evidence: `retrace/verification/harness.py`)
- Erasure report → Markdown and HTML: renders report (evidence: `retrace/reporting/generate.py`)
- Interactive UI → Serving engine: uses engine (evidence: `retrace/serving/app.py`)
- Serving engine → Fact resolver: resolves queries (evidence: `retrace/serving/engine.py`)
- Serving engine → Model inference: generates answers (evidence: `retrace/serving/engine.py`)
- Serving engine → Erasure request: resolves erasure (evidence: `retrace/serving/engine.py`)
- Serving engine → Retention verification: runs verification (evidence: `retrace/serving/engine.py`)
- Serving engine → Erasure report: loads reports (evidence: `retrace/serving/engine.py`)
- Knowledge builder → Pipeline artifacts: writes artifacts (evidence: `retrace/knowledge/build.py`)
- Training builder → Pipeline artifacts: writes artifacts (evidence: `retrace/training/build.py`)
- Erasure builder → Pipeline artifacts: writes artifacts (evidence: `retrace/erasure/build.py`)
- Retention verification → Pipeline artifacts: writes results (evidence: `retrace/verification/harness.py`)
- Erasure report → Pipeline artifacts: reads artifacts (evidence: `retrace/reporting/generate.py`)
- CLI commands → Stage configuration: sets options (evidence: `retrace/cli.py`)
