# nukanarendra/shade_collision_detection architecture

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

- Interactive diagram: https://gitdiagram.com/nukanarendra/shade_collision_detection
- Repository: https://github.com/nukanarendra/shade_collision_detection

## Overview

SHADE is a research benchmark for studying covert collusion between AI agents and comparing detection methods. A user or evaluation run supplies a math task and secret token; paired agents exchange multi-turn messages, after which a semantic monitor and an oracle judge the transcript. The framework also computes CACC statistical anomalies and collusion/detection metrics, while experiment runners support cross-model evaluation and the Streamlit app presents live trials. Evidence is limited to the supplied source excerpts and index; unsampled dashboard and experiment behavior is not inferred.

Main entry points: [`app/streamlit_app.py`](https://github.com/nukanarendra/shade_collision_detection/blob/main/app/streamlit_app.py) (Live Trial UI), [`src/harness/turn_manager.py`](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/harness/turn_manager.py) (Turn Harness), [`src/pipeline.py`](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/pipeline.py) (Evaluation Pipeline), [`src/agents/base.py`](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/base.py) (Agent and LLM Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_streamlit["Live Trial UI<br/>[streamlit_app.py]"]
  node_dashboard["Dashboard<br/>[shade_dashboard.py]"]
  node_demo["Demo App<br/>[shade_demo.py]"]
end

subgraph group_runtime["Trial Runtime"]
  node_pipeline["Evaluation Pipeline<br/>[pipeline.py]"]
  node_config["Config and Data<br/>[config.py]"]
  node_tasks["Test Tasks<br/>[test_tasks.json]"]
  node_harness["Turn Harness<br/>[turn_manager.py]"]
  node_colluders["Colluder Agents<br/>[colluder.py]"]
  node_agentbase["Agent and LLM Client<br/>[base.py]"]
  node_logger["Trial Logger<br/>[logger.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_monitor["Semantic Monitor<br/>[monitor.py]"]
  node_oracle["Oracle Judge<br/>[oracle.py]"]
  node_cacc["CACC Detector<br/>[cacc_engine.py]"]
  node_classifier["Channel Classifier"]
  node_metrics["Trial Metrics<br/>[metrics.py]"]
  node_crossmodel["Cross-Model Evaluation"]
end

node_user(("Researcher"))
node_llm{{"Model Providers"}}

node_user -->|"starts trial"| node_streamlit
node_pipeline -->|"loads tasks"| node_config
node_config -.->|"reads"| node_tasks
node_pipeline -->|"runs trial"| node_harness
node_pipeline -->|"analyzes transcript"| node_cacc
node_pipeline -->|"records results"| node_metrics
node_harness -->|"creates agents"| node_colluders
node_harness -->|"evaluates transcript"| node_monitor
node_harness -->|"judges transcript"| node_oracle
node_harness -->|"logs turns"| node_logger
node_colluders -->|"extends"| node_agentbase
node_monitor -->|"extends"| node_agentbase
node_oracle -->|"extends"| node_agentbase
node_agentbase -->|"requests completions"| node_llm
node_streamlit -->|"creates agents"| node_colluders
node_streamlit -->|"evaluates transcript"| node_monitor
node_streamlit -->|"judges transcript"| node_oracle
node_streamlit -->|"logs trial"| node_logger
node_streamlit -->|"records results"| node_metrics
node_crossmodel -->|"loads tasks"| node_config
node_crossmodel -->|"runs trial"| node_harness
node_crossmodel -->|"analyzes transcript"| node_cacc

click node_streamlit "https://github.com/nukanarendra/shade_collision_detection/blob/main/app/streamlit_app.py"
click node_dashboard "https://github.com/nukanarendra/shade_collision_detection/blob/main/app/shade_dashboard.py"
click node_demo "https://github.com/nukanarendra/shade_collision_detection/blob/main/app/shade_demo.py"
click node_pipeline "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/pipeline.py"
click node_config "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/config.py"
click node_tasks "https://github.com/nukanarendra/shade_collision_detection/blob/main/data/test_tasks.json"
click node_harness "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/harness/turn_manager.py"
click node_colluders "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/colluder.py"
click node_agentbase "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/base.py"
click node_monitor "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/monitor.py"
click node_oracle "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/scoring/oracle.py"
click node_logger "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/harness/logger.py"
click node_cacc "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/cacc/cacc_engine.py"
click node_classifier "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/analysis/channel_classifier.py"
click node_metrics "https://github.com/nukanarendra/shade_collision_detection/blob/main/src/scoring/metrics.py"
click node_crossmodel "https://github.com/nukanarendra/shade_collision_detection/blob/main/experiments/run_cross_model_eval.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_streamlit,node_dashboard,node_demo toneBlue
class node_pipeline,node_config,node_tasks,node_harness,node_colluders,node_agentbase,node_logger toneAmber
class node_monitor,node_oracle,node_cacc,node_classifier,node_metrics,node_crossmodel toneMint
class node_user,node_llm toneIndigo
```

## Components

### User Interfaces

- [Live Trial UI](https://github.com/nukanarendra/shade_collision_detection/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Dashboard](https://github.com/nukanarendra/shade_collision_detection/blob/main/app/shade_dashboard.py): `app/shade_dashboard.py`
- [Demo App](https://github.com/nukanarendra/shade_collision_detection/blob/main/app/shade_demo.py): `app/shade_demo.py`

### Trial Runtime

- [Evaluation Pipeline](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/pipeline.py): `src/pipeline.py`
- [Config and Data](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/config.py): `src/config.py`
- [Test Tasks](https://github.com/nukanarendra/shade_collision_detection/blob/main/data/test_tasks.json): `data/test_tasks.json`
- [Turn Harness](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/harness/turn_manager.py): `src/harness/turn_manager.py`
- [Colluder Agents](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/colluder.py): `src/agents/colluder.py`
- [Agent and LLM Client](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/base.py): `src/agents/base.py`
- [Trial Logger](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/harness/logger.py): `src/harness/logger.py`

### Evaluation

- [Semantic Monitor](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/agents/monitor.py): `src/agents/monitor.py`
- [Oracle Judge](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/scoring/oracle.py): `src/scoring/oracle.py`
- [CACC Detector](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/cacc/cacc_engine.py): `src/cacc/cacc_engine.py`
- [Channel Classifier](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/analysis/channel_classifier.py): `src/analysis/channel_classifier.py`
- [Trial Metrics](https://github.com/nukanarendra/shade_collision_detection/blob/main/src/scoring/metrics.py): `src/scoring/metrics.py`
- [Cross-Model Evaluation](https://github.com/nukanarendra/shade_collision_detection/blob/main/experiments/run_cross_model_eval.py): `experiments/run_cross_model_eval.py`

### Other components

- **Researcher**
- **Model Providers**

## Connections

- Researcher → Live Trial UI: starts trial (evidence: `app/streamlit_app.py`)
- Evaluation Pipeline → Config and Data: loads tasks (evidence: `src/pipeline.py`)
- Config and Data → Test Tasks: reads
- Evaluation Pipeline → Turn Harness: runs trial (evidence: `src/pipeline.py`)
- Evaluation Pipeline → CACC Detector: analyzes transcript (evidence: `src/pipeline.py`)
- Evaluation Pipeline → Trial Metrics: records results (evidence: `src/pipeline.py`)
- Turn Harness → Colluder Agents: creates agents (evidence: `src/harness/turn_manager.py`)
- Turn Harness → Semantic Monitor: evaluates transcript (evidence: `src/harness/turn_manager.py`)
- Turn Harness → Oracle Judge: judges transcript (evidence: `src/harness/turn_manager.py`)
- Turn Harness → Trial Logger: logs turns (evidence: `src/harness/turn_manager.py`)
- Colluder Agents → Agent and LLM Client: extends (evidence: `src/agents/colluder.py`)
- Semantic Monitor → Agent and LLM Client: extends (evidence: `src/agents/monitor.py`)
- Oracle Judge → Agent and LLM Client: extends (evidence: `src/scoring/oracle.py`)
- Agent and LLM Client → Model Providers: requests completions (evidence: `src/agents/base.py`)
- Live Trial UI → Colluder Agents: creates agents (evidence: `app/streamlit_app.py`)
- Live Trial UI → Semantic Monitor: evaluates transcript (evidence: `app/streamlit_app.py`)
- Live Trial UI → Oracle Judge: judges transcript (evidence: `app/streamlit_app.py`)
- Live Trial UI → Trial Logger: logs trial (evidence: `app/streamlit_app.py`)
- Live Trial UI → Trial Metrics: records results (evidence: `app/streamlit_app.py`)
- Cross-Model Evaluation → Config and Data: loads tasks (evidence: `experiments/run_cross_model_eval.py`)
- Cross-Model Evaluation → Turn Harness: runs trial (evidence: `experiments/run_cross_model_eval.py`)
- Cross-Model Evaluation → CACC Detector: analyzes transcript (evidence: `experiments/run_cross_model_eval.py`)
