# aymaw/conformal-watch architecture

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

- Interactive diagram: https://gitdiagram.com/aymaw/conformal-watch
- Repository: https://github.com/aymaw/conformal-watch

## Overview

Conformal Watch is a reproducible synthetic-data experiment for split-conformal classification and label-free drift diagnostics. Its CLI workflow generates training data and fits a classifier, calibrates a finite-sample cutoff, evaluates prediction sets on IID and shifted slices, and assesses a fixed stream horizon with permutation MMD alarms. It also measures repeated calibration coverage and produces an offline interactive report and SVG preview. The graph reflects the README’s described stages and the sampled experiment’s calls; unsampled tests and committed results are not runtime components.

Main entry points: [`src/conformalwatch/experiment.py`](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py) (Experiment CLI), [`src/conformalwatch/visual.py`](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py) (HTML report), [`src/conformalwatch/core.py`](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py) (Synthetic data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Synthetic modeling"]
  node_data["Synthetic data<br/>[core.py]"]
  node_classifier["Softmax classifier<br/>[core.py]"]
end

subgraph group_conformal["Conformal inference"]
  node_calibration["Calibration cutoff<br/>[core.py]"]
  node_sets["Prediction sets<br/>[core.py]"]
  node_evaluation["Coverage metrics<br/>[core.py]"]
  node_trial["Repeated coverage<br/>[experiment.py]"]
  node_grid["Feature-grid predictions<br/>[experiment.py]"]
end

subgraph group_monitoring["Shift monitoring"]
  node_drift["Permutation MMD<br/>[core.py]"]
  node_horizon["Fixed-horizon alarms<br/>[experiment.py]"]
end

subgraph group_reporting["Experiment reporting"]
  node_cli["Experiment CLI<br/>[experiment.py]"]
  node_report["HTML report<br/>[visual.py]"]
  node_artifacts["Run artifacts<br/>[visual.py]"]
  node_preview["Scatter preview<br/>[visual.py]"]
end

node_engineer(("Experiment runner"))

node_engineer -->|"runs"| node_cli
node_cli -->|"generates"| node_data
node_cli -->|"fits and predicts"| node_classifier
node_cli -->|"computes cutoff"| node_calibration
node_cli -->|"forms sets"| node_sets
node_cli -->|"evaluates"| node_evaluation
node_cli -->|"tests windows"| node_drift
node_cli -->|"sets alarms"| node_horizon
node_cli -->|"measures coverage"| node_trial
node_cli -->|"predicts grid"| node_grid
node_cli -->|"renders report"| node_report
node_report -->|"writes JSON and HTML"| node_artifacts
node_cli -->|"renders SVG"| node_preview

click node_cli "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py"
click node_data "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_classifier "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_calibration "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_sets "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_evaluation "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_drift "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py"
click node_horizon "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py"
click node_trial "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py"
click node_grid "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py"
click node_report "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py"
click node_artifacts "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py"
click node_preview "https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.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_data,node_classifier toneBlue
class node_calibration,node_sets,node_evaluation,node_trial,node_grid toneAmber
class node_drift,node_horizon toneMint
class node_cli,node_report,node_artifacts,node_preview toneRose
class node_engineer toneIndigo
```

## Components

### Synthetic modeling

- [Synthetic data](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`
- [Softmax classifier](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`

### Conformal inference

- [Calibration cutoff](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`
- [Prediction sets](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`
- [Coverage metrics](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`
- [Repeated coverage](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py): `src/conformalwatch/experiment.py`
- [Feature-grid predictions](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py): `src/conformalwatch/experiment.py`

### Shift monitoring

- [Permutation MMD](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/core.py): `src/conformalwatch/core.py`
- [Fixed-horizon alarms](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py): `src/conformalwatch/experiment.py`

### Experiment reporting

- [Experiment CLI](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/experiment.py): `src/conformalwatch/experiment.py`
- [HTML report](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py): `src/conformalwatch/visual.py`
- [Run artifacts](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py): `src/conformalwatch/visual.py`
- [Scatter preview](https://github.com/aymaw/conformal-watch/blob/main/src/conformalwatch/visual.py): `src/conformalwatch/visual.py`

### Other components

- **Experiment runner**

## Connections

- Experiment runner → Experiment CLI: runs (evidence: `README.md`)
- Experiment CLI → Synthetic data: generates (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Softmax classifier: fits and predicts (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Calibration cutoff: computes cutoff (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Prediction sets: forms sets (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Coverage metrics: evaluates (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Permutation MMD: tests windows (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Fixed-horizon alarms: sets alarms (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Repeated coverage: measures coverage (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → Feature-grid predictions: predicts grid (evidence: `src/conformalwatch/experiment.py`)
- Experiment CLI → HTML report: renders report (evidence: `src/conformalwatch/experiment.py`)
- HTML report → Run artifacts: writes JSON and HTML (evidence: `src/conformalwatch/visual.py`)
- Experiment CLI → Scatter preview: renders SVG (evidence: `src/conformalwatch/experiment.py`)