# kaelvalen/relic architecture

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

- Interactive diagram: https://gitdiagram.com/kaelvalen/relic
- Repository: https://github.com/kaelvalen/relic

## Overview

RELIC is a Python research implementation of revocable per-fact knowledge updates for frozen language models. Its central workflow trains a low-rank adapter for a fact, checks divergence, stores accepted entries, and routes queries to at most one entry or the unchanged base model; answers retain entry provenance. The tree also contains confirmatory evaluation, a text live-learning sandbox, and a VLM mirror sandbox. Edges follow README-described behavior; sampled excerpts do not expose enough of the runtime implementation to assert additional call-level wiring.

Main entry points: [`relic/router.py`](https://github.com/kaelvalen/relic/blob/main/relic/router.py) (Entry router), [`relic/serving.py`](https://github.com/kaelvalen/relic/blob/main/relic/serving.py) (Answer serving), [`experiments/sandbox/live_learning/confirm/pilot.py`](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/pilot.py) (Confirmatory pilot), [`relic/model.py`](https://github.com/kaelvalen/relic/blob/main/relic/model.py) (Frozen model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["RELIC Runtime"]
  node_base["Frozen model<br/>[model.py]"]
  node_adapter["Adapter training<br/>[adapters.py]"]
  node_ledger[("Entry ledger<br/>[ledger.py]")]
  node_router["Entry router<br/>[router.py]"]
  node_serving["Answer serving<br/>[serving.py]"]
  node_metrics["Divergence metrics<br/>[metrics.py]"]
end

subgraph group_confirm["Confirmatory Study"]
  node_factgen["Fact generation<br/>[facts.py]"]
  node_pilot["Confirmatory pilot<br/>[pilot.py]"]
  node_routed_eval["Routed evaluation<br/>[routed_eval.py]"]
  node_locality["Locality evaluation<br/>[locality_eval.py]"]
  node_router_cal["Router calibration"]
  node_adapter_eval["Adapter comparison<br/>[adapter_only.py]"]
end

subgraph group_text["Text Sandbox"]
  node_stream["Learning stream<br/>[stream.py]"]
  node_mechanisms["Learning mechanisms<br/>[mechanisms.py]"]
  node_text_run["Text runner<br/>[run.py]"]
  node_bandit["Ledger bandit<br/>[ledger_bandit.py]"]
end

subgraph group_vlm["VLM Sandbox"]
  node_vlm_core["VLM harness<br/>[vlm_core.py]"]
  node_vlm_ledger["VLM ledger<br/>[vlm_ledger.py]"]
  node_vlm_controller["VLM controller<br/>[vlm_controller.py]"]
end

node_user(("User"))
node_fact["New fact"]
node_query["Query"]
node_answer["Answer + provenance"]

node_user -->|"submits"| node_fact
node_fact -->|"rewrites with"| node_base
node_base -->|"trains from"| node_adapter
node_adapter -->|"checks canaries"| node_metrics
node_metrics -->|"accepts if below limit"| node_ledger
node_user -->|"asks"| node_query
node_query -->|"routes"| node_router
node_ledger -.->|"provides entries"| node_router
node_router -->|"selects entry or abstains"| node_serving
node_serving -->|"answers with"| node_base
node_serving -->|"returns provenance"| node_answer
node_factgen -->|"supplies facts"| node_pilot
node_pilot -.->|"evaluates store"| node_routed_eval
node_pilot -->|"evaluates locality"| node_locality
node_router_cal -->|"calibrates routing"| node_router
node_adapter_eval -.->|"compares adapters"| node_adapter
node_stream -->|"provides events"| node_text_run
node_text_run -->|"runs mechanisms"| node_mechanisms
node_bandit -->|"consumes stream"| node_stream
node_vlm_controller -->|"uses harness"| node_vlm_core
node_vlm_controller -->|"uses ledger"| node_vlm_ledger
node_vlm_ledger -->|"uses core"| node_vlm_core

click node_base "https://github.com/kaelvalen/relic/blob/main/relic/model.py"
click node_adapter "https://github.com/kaelvalen/relic/blob/main/relic/adapters.py"
click node_ledger "https://github.com/kaelvalen/relic/blob/main/relic/ledger.py"
click node_router "https://github.com/kaelvalen/relic/blob/main/relic/router.py"
click node_serving "https://github.com/kaelvalen/relic/blob/main/relic/serving.py"
click node_metrics "https://github.com/kaelvalen/relic/blob/main/relic/metrics.py"
click node_factgen "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/facts.py"
click node_pilot "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/pilot.py"
click node_routed_eval "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/routed_eval.py"
click node_locality "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/locality_eval.py"
click node_router_cal "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/router_v4_calibrate.py"
click node_adapter_eval "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/adapter_only.py"
click node_stream "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/stream.py"
click node_mechanisms "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/mechanisms.py"
click node_text_run "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/run.py"
click node_bandit "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/ledger_bandit.py"
click node_vlm_core "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_core.py"
click node_vlm_ledger "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_ledger.py"
click node_vlm_controller "https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_controller.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_base,node_adapter,node_ledger,node_router,node_serving,node_metrics,node_user toneBlue
class node_factgen,node_pilot,node_routed_eval,node_locality,node_router_cal,node_adapter_eval toneAmber
class node_stream,node_mechanisms,node_text_run,node_bandit toneMint
class node_vlm_core,node_vlm_ledger,node_vlm_controller toneRose
class node_fact,node_query,node_answer toneIndigo
```

## Components

### RELIC Runtime

- [Frozen model](https://github.com/kaelvalen/relic/blob/main/relic/model.py): `relic/model.py`
- [Adapter training](https://github.com/kaelvalen/relic/blob/main/relic/adapters.py): `relic/adapters.py`
- [Entry ledger](https://github.com/kaelvalen/relic/blob/main/relic/ledger.py): `relic/ledger.py`
- [Entry router](https://github.com/kaelvalen/relic/blob/main/relic/router.py): `relic/router.py`
- [Answer serving](https://github.com/kaelvalen/relic/blob/main/relic/serving.py): `relic/serving.py`
- [Divergence metrics](https://github.com/kaelvalen/relic/blob/main/relic/metrics.py): `relic/metrics.py`

### Confirmatory Study

- [Fact generation](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/facts.py): `experiments/sandbox/live_learning/confirm/facts.py`
- [Confirmatory pilot](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/pilot.py): `experiments/sandbox/live_learning/confirm/pilot.py`
- [Routed evaluation](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/routed_eval.py): `experiments/sandbox/live_learning/confirm/routed_eval.py`
- [Locality evaluation](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/locality_eval.py): `experiments/sandbox/live_learning/confirm/locality_eval.py`
- [Router calibration](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/router_v4_calibrate.py): `experiments/sandbox/live_learning/confirm/router_v4_calibrate.py`
- [Adapter comparison](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/confirm/adapter_only.py): `experiments/sandbox/live_learning/confirm/adapter_only.py`

### Text Sandbox

- [Learning stream](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/stream.py): `experiments/sandbox/live_learning/text/stream.py`
- [Learning mechanisms](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/mechanisms.py): `experiments/sandbox/live_learning/text/mechanisms.py`
- [Text runner](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/run.py): `experiments/sandbox/live_learning/text/run.py`
- [Ledger bandit](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/text/ledger_bandit.py): `experiments/sandbox/live_learning/text/ledger_bandit.py`

### VLM Sandbox

- [VLM harness](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_core.py): `experiments/sandbox/live_learning/vlm/vlm_core.py`
- [VLM ledger](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_ledger.py): `experiments/sandbox/live_learning/vlm/vlm_ledger.py`
- [VLM controller](https://github.com/kaelvalen/relic/blob/main/experiments/sandbox/live_learning/vlm/vlm_controller.py): `experiments/sandbox/live_learning/vlm/vlm_controller.py`

### Other components

- **User**
- **New fact**
- **Query**
- **Answer + provenance**

## Connections

- User → New fact: submits
- New fact → Frozen model: rewrites with
- Frozen model → Adapter training: trains from (evidence: `relic/adapters.py`)
- Adapter training → Divergence metrics: checks canaries
- Divergence metrics → Entry ledger: accepts if below limit (evidence: `relic/ledger.py`)
- User → Query: asks
- Query → Entry router: routes
- Entry ledger → Entry router: provides entries (evidence: `relic/ledger.py`)
- Entry router → Answer serving: selects entry or abstains
- Answer serving → Frozen model: answers with
- Answer serving → Answer + provenance: returns provenance
- Fact generation → Confirmatory pilot: supplies facts (evidence: `experiments/sandbox/live_learning/confirm/pilot.py`)
- Confirmatory pilot → Routed evaluation: evaluates store (evidence: `experiments/sandbox/live_learning/confirm/routed_eval.py`)
- Confirmatory pilot → Locality evaluation: evaluates locality (evidence: `experiments/sandbox/live_learning/confirm/locality_eval.py`)
- Router calibration → Entry router: calibrates routing (evidence: `experiments/sandbox/live_learning/confirm/router_v4_calibrate.py`)
- Adapter comparison → Adapter training: compares adapters
- Learning stream → Text runner: provides events (evidence: `experiments/sandbox/live_learning/text/run.py`)
- Text runner → Learning mechanisms: runs mechanisms (evidence: `experiments/sandbox/live_learning/text/run.py`)
- Ledger bandit → Learning stream: consumes stream (evidence: `experiments/sandbox/live_learning/text/ledger_bandit.py`)
- VLM controller → VLM harness: uses harness (evidence: `experiments/sandbox/live_learning/vlm/vlm_controller.py`)
- VLM controller → VLM ledger: uses ledger (evidence: `experiments/sandbox/live_learning/vlm/vlm_controller.py`)
- VLM ledger → VLM harness: uses core (evidence: `experiments/sandbox/live_learning/vlm/vlm_ledger.py`)
