# elamurugu10/runtime-interceptor architecture

> Architecture diagram of the GitHub repository elamurugu10/runtime-interceptor, 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/elamurugu10/runtime-interceptor
- Repository: https://github.com/elamurugu10/runtime-interceptor

## Overview

This is a research platform for containing hallucination cascades across multi-agent LLM workflows. Its principal workflow runs an agent architecture with controlled faults and optional handoff inspection, then evaluates interceptor-on versus interceptor-off outcomes. The README also documents adaptive calibration, dataset generation, three orchestration topologies, an API/dashboard, and statistical evaluation. The graph preserves these capabilities; sampled excerpts and the source index support only some internal call relationships, so other documented wiring is shown as unverified.

Main entry points: [`app/experiments/manager.py`](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/experiments/manager.py) (Experiment Manager), [`app/interceptor/interceptor.py`](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/interceptor.py) (Handoff Interceptor), [`app/orchestration/sequential.py`](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/sequential.py) (Sequential Workflow), [`app/orchestration/hierarchical.py`](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/hierarchical.py) (Hierarchical Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["REST API<br/>[routes.py]"]
  node_dashboard["Web Dashboard<br/>[dashboard.js]"]
end

subgraph group_orchestration["Agent Workflows"]
  node_sequential["Sequential Workflow<br/>[sequential.py]"]
  node_hierarchical["Hierarchical Workflow<br/>[hierarchical.py]"]
  node_consensus["Parallel Consensus"]
  node_agents["Agent Roles"]
end

subgraph group_interception["Runtime Interception"]
  node_interceptor["Handoff Interceptor<br/>[interceptor.py]"]
  node_signals["Detection Signals"]
  node_calibration["Adaptive Calibration<br/>[calibrator.py]"]
  node_repair["Repair Engine<br/>[repair_engine.py]"]
end

subgraph group_research["Research and Evaluation"]
  node_experiments["Experiment Manager<br/>[manager.py]"]
  node_datasets["Benchmark Datasets<br/>[generator.py]"]
  node_annotations["Human Annotations<br/>[annotation.py]"]
  node_faults["Fault Injection<br/>[injector.py]"]
  node_evaluation["Statistical Evaluation<br/>[runner.py]"]
end

subgraph group_infrastructure["Models and Persistence"]
  node_storage[("Persistence<br/>[repository.py]")]
  node_provider_factory["Provider Factory<br/>[factory.py]"]
  node_providers["LLM Providers<br/>[base.py]"]
end

node_user(("Researcher"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses API"| node_api
node_user -->|"uses dashboard"| node_dashboard
node_cli -->|"runs experiments"| node_experiments
node_api -.->|"starts experiments"| node_experiments
node_dashboard -.->|"uses API"| node_api
node_experiments -->|"generates tasks"| node_datasets
node_experiments -->|"configures faults"| node_faults
node_experiments -->|"runs architecture"| node_sequential
node_experiments -->|"runs architecture"| node_hierarchical
node_experiments -->|"runs architecture"| node_consensus
node_experiments -->|"calculates metrics"| node_evaluation
node_experiments -.->|"persists results"| node_storage
node_datasets -->|"injects faults"| node_faults
node_datasets -.->|"supports annotation"| node_annotations
node_sequential -->|"dispatches roles"| node_agents
node_sequential -->|"inspects handoffs"| node_interceptor
node_sequential -->|"injects faults"| node_faults
node_hierarchical -->|"dispatches roles"| node_agents
node_hierarchical -.->|"inspects handoffs"| node_interceptor
node_consensus -->|"dispatches roles"| node_agents
node_consensus -.->|"inspects handoffs"| node_interceptor
node_interceptor -->|"runs checks"| node_signals
node_interceptor -->|"loads thresholds"| node_calibration
node_interceptor -->|"repairs output"| node_repair
node_evaluation -.->|"optimizes thresholds"| node_calibration
node_provider_factory -->|"selects provider"| node_providers

click node_cli "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/cli.py"
click node_api "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/api/routes.py"
click node_dashboard "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/dashboard/static/js/dashboard.js"
click node_experiments "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/experiments/manager.py"
click node_datasets "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/datasets/generator.py"
click node_annotations "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/datasets/annotation.py"
click node_faults "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/fault_injection/injector.py"
click node_sequential "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/sequential.py"
click node_hierarchical "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/hierarchical.py"
click node_consensus "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/parallel_consensus.py"
click node_agents "https://github.com/elamurugu10/runtime-interceptor/tree/main/app/agents"
click node_interceptor "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/interceptor.py"
click node_signals "https://github.com/elamurugu10/runtime-interceptor/tree/main/app/interceptor/signals"
click node_calibration "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/calibration/calibrator.py"
click node_repair "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/repair/repair_engine.py"
click node_evaluation "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/evaluation/runner.py"
click node_storage "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/storage/repository.py"
click node_provider_factory "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/llm/factory.py"
click node_providers "https://github.com/elamurugu10/runtime-interceptor/blob/main/app/llm/base.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_cli,node_api,node_dashboard toneBlue
class node_sequential,node_hierarchical,node_consensus,node_agents toneAmber
class node_interceptor,node_signals,node_calibration,node_repair toneMint
class node_experiments,node_datasets,node_annotations,node_faults,node_evaluation toneRose
class node_storage,node_provider_factory,node_providers,node_user toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/cli.py): `app/cli.py`
- [REST API](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/api/routes.py): `app/api/routes.py`
- [Web Dashboard](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/dashboard/static/js/dashboard.js): `app/dashboard/static/js/dashboard.js`

### Agent Workflows

- [Sequential Workflow](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/sequential.py): `app/orchestration/sequential.py`
- [Hierarchical Workflow](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/hierarchical.py): `app/orchestration/hierarchical.py`
- [Parallel Consensus](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/orchestration/parallel_consensus.py): `app/orchestration/parallel_consensus.py`
- [Agent Roles](https://github.com/elamurugu10/runtime-interceptor/tree/main/app/agents): `app/agents`

### Runtime Interception

- [Handoff Interceptor](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/interceptor.py): `app/interceptor/interceptor.py`
- [Detection Signals](https://github.com/elamurugu10/runtime-interceptor/tree/main/app/interceptor/signals): `app/interceptor/signals`
- [Adaptive Calibration](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/calibration/calibrator.py): `app/interceptor/calibration/calibrator.py`
- [Repair Engine](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/interceptor/repair/repair_engine.py): `app/interceptor/repair/repair_engine.py`

### Research and Evaluation

- [Experiment Manager](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/experiments/manager.py): `app/experiments/manager.py`
- [Benchmark Datasets](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/datasets/generator.py): `app/datasets/generator.py`
- [Human Annotations](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/datasets/annotation.py): `app/datasets/annotation.py`
- [Fault Injection](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/fault_injection/injector.py): `app/fault_injection/injector.py`
- [Statistical Evaluation](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/evaluation/runner.py): `app/evaluation/runner.py`

### Models and Persistence

- [Persistence](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/storage/repository.py): `app/storage/repository.py`
- [Provider Factory](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/llm/factory.py): `app/llm/factory.py`
- [LLM Providers](https://github.com/elamurugu10/runtime-interceptor/blob/main/app/llm/base.py): `app/llm/base.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: runs commands
- Researcher → REST API: uses API
- Researcher → Web Dashboard: uses dashboard
- CLI → Experiment Manager: runs experiments (evidence: `app/cli.py`)
- REST API → Experiment Manager: starts experiments
- Web Dashboard → REST API: uses API
- Experiment Manager → Benchmark Datasets: generates tasks (evidence: `app/experiments/manager.py`)
- Experiment Manager → Fault Injection: configures faults (evidence: `app/experiments/manager.py`)
- Experiment Manager → Sequential Workflow: runs architecture (evidence: `app/experiments/manager.py`)
- Experiment Manager → Hierarchical Workflow: runs architecture (evidence: `app/experiments/manager.py`)
- Experiment Manager → Parallel Consensus: runs architecture (evidence: `app/experiments/manager.py`)
- Experiment Manager → Statistical Evaluation: calculates metrics (evidence: `app/experiments/manager.py`)
- Experiment Manager → Persistence: persists results (evidence: `app/experiments/manager.py`)
- Benchmark Datasets → Fault Injection: injects faults (evidence: `app/datasets/generator.py`)
- Benchmark Datasets → Human Annotations: supports annotation
- Sequential Workflow → Agent Roles: dispatches roles (evidence: `app/orchestration/sequential.py`)
- Sequential Workflow → Handoff Interceptor: inspects handoffs (evidence: `app/orchestration/sequential.py`)
- Sequential Workflow → Fault Injection: injects faults (evidence: `app/orchestration/sequential.py`)
- Hierarchical Workflow → Agent Roles: dispatches roles (evidence: `app/orchestration/hierarchical.py`)
- Hierarchical Workflow → Handoff Interceptor: inspects handoffs (evidence: `app/orchestration/hierarchical.py`)
- Parallel Consensus → Agent Roles: dispatches roles (evidence: `app/orchestration/parallel_consensus.py`)
- Parallel Consensus → Handoff Interceptor: inspects handoffs (evidence: `app/orchestration/parallel_consensus.py`)
- Handoff Interceptor → Detection Signals: runs checks (evidence: `app/interceptor/interceptor.py`)
- Handoff Interceptor → Adaptive Calibration: loads thresholds (evidence: `app/interceptor/interceptor.py`)
- Handoff Interceptor → Repair Engine: repairs output (evidence: `app/interceptor/interceptor.py`)
- Statistical Evaluation → Adaptive Calibration: optimizes thresholds
- Provider Factory → LLM Providers: selects provider (evidence: `app/llm/factory.py`)
