# jarambler/entropyguard architecture

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

## Overview

EntropyGuard is a research detector for indirect prompt injection: it probes a Transformer’s early attention over trusted instructions and untrusted data, selects informative heads, then classifies carrier-delta features. The main workflow is offline head selection and classifier training via `run_pipeline.py`, followed by single-input detection or cross-dataset evaluation. The README also documents an OpenClaw pre-tool-call integration design, but this tree contains no plugin implementation. Arrows follow the sampled pipeline references and README; unsampled implementation details are not inferred.

Main entry points: [`run_pipeline.py`](https://github.com/jarambler/entropyguard/blob/main/run_pipeline.py) (Train pipeline), [`scripts/eval_cross_dataset.py`](https://github.com/jarambler/entropyguard/blob/main/scripts/eval_cross_dataset.py) (Cross-dataset evaluation), [`src/classifier/trainer.py`](https://github.com/jarambler/entropyguard/blob/main/src/classifier/trainer.py) (Classifier training), [`scripts/detect.py`](https://github.com/jarambler/entropyguard/blob/main/scripts/detect.py) (Detect input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_dataset["Dataset builder<br/>[dataset.py]"]
  node_external_data["External datasets"]
end

subgraph group_probe["Model probing"]
  node_model["Model and attention<br/>[model_loader.py]"]
  node_registry["Model registry<br/>[registry.py]"]
  node_entropy["Regional features<br/>[entropy_compute.py]"]
end

subgraph group_detector["Head selection and detection"]
  node_pipeline["Train pipeline<br/>[run_pipeline.py]"]
  node_detect_cli["Detect input<br/>[detect.py]"]
  node_features["Carrier-delta features<br/>[features.py]"]
  node_selection["CI head selection<br/>[selector.py]"]
  node_artifacts["Selection artifacts<br/>[artifacts.py]"]
  node_trainer["Classifier training<br/>[trainer.py]"]
  node_logistic["Selected-head logistic"]
  node_adaptive["Adaptive margin<br/>[adaptive_margin.py]"]
  node_signed["Signed risk<br/>[signed_risk.py]"]
  node_thresholds["Threshold utilities<br/>[thresholds.py]"]
end

subgraph group_evaluation["Evaluation and integration"]
  node_evaluator["Metric evaluation<br/>[evaluator.py]"]
  node_cross_eval["Cross-dataset evaluation"]
  node_plotting["Result visualization<br/>[plotting.py]"]
  node_openclaw["OpenClaw hook design"]
end

node_researcher(("Researcher"))
node_workspace["Workspace files"]
node_agent(("OpenClaw agent"))
node_service["EntropyGuard service"]

node_researcher -->|"runs training"| node_pipeline
node_pipeline -->|"prepares samples"| node_dataset
node_pipeline -->|"loads model"| node_model
node_model -->|"reads registry"| node_registry
node_pipeline -->|"computes attention features"| node_entropy
node_pipeline -->|"selects heads"| node_selection
node_selection -->|"uses regional features"| node_entropy
node_pipeline -->|"saves selection"| node_artifacts
node_pipeline -->|"builds classifier features"| node_features
node_features -->|"uses regional measures"| node_entropy
node_pipeline -->|"trains classifier"| node_trainer
node_trainer -->|"selects classifier"| node_logistic
node_trainer -->|"supports classifier"| node_adaptive
node_trainer -->|"supports classifier"| node_signed
node_adaptive -->|"chooses thresholds"| node_thresholds
node_logistic -->|"uses threshold utilities"| node_thresholds
node_detect_cli -->|"formats input"| node_dataset
node_detect_cli -->|"loads model"| node_model
node_detect_cli -->|"computes features"| node_entropy
node_detect_cli -->|"loads classifier"| node_trainer
node_researcher -->|"submits input"| node_detect_cli
node_cross_eval -->|"loads benchmarks"| node_external_data
node_cross_eval -->|"loads model"| node_model
node_cross_eval -->|"computes features"| node_entropy
node_cross_eval -->|"formats samples"| node_dataset
node_cross_eval -->|"evaluates classifier"| node_trainer
node_trainer -->|"computes metrics"| node_evaluator
node_researcher -->|"runs evaluation"| node_cross_eval
node_researcher -->|"requests figures"| node_plotting
node_agent -.->|"references files"| node_workspace
node_openclaw -.->|"extracts content"| node_workspace
node_openclaw -.->|"sends detection request"| node_service
node_service -.->|"uses detector design"| node_detect_cli
node_openclaw -.->|"blocks tool call"| node_agent
node_external_data -->|"provides datasets"| node_cross_eval

click node_pipeline "https://github.com/jarambler/entropyguard/blob/main/run_pipeline.py"
click node_detect_cli "https://github.com/jarambler/entropyguard/blob/main/scripts/detect.py"
click node_dataset "https://github.com/jarambler/entropyguard/blob/main/src/data/dataset.py"
click node_external_data "https://github.com/jarambler/entropyguard/blob/main/src/data/external_datasets.py"
click node_model "https://github.com/jarambler/entropyguard/blob/main/src/models/model_loader.py"
click node_registry "https://github.com/jarambler/entropyguard/blob/main/src/models/registry.py"
click node_entropy "https://github.com/jarambler/entropyguard/blob/main/src/entropy/entropy_compute.py"
click node_features "https://github.com/jarambler/entropyguard/blob/main/src/head_selection/features.py"
click node_selection "https://github.com/jarambler/entropyguard/blob/main/src/head_selection/selector.py"
click node_artifacts "https://github.com/jarambler/entropyguard/blob/main/src/head_selection/artifacts.py"
click node_trainer "https://github.com/jarambler/entropyguard/blob/main/src/classifier/trainer.py"
click node_logistic "https://github.com/jarambler/entropyguard/blob/main/src/classifier/selected_head_logistic.py"
click node_adaptive "https://github.com/jarambler/entropyguard/blob/main/src/classifier/adaptive_margin.py"
click node_signed "https://github.com/jarambler/entropyguard/blob/main/src/classifier/signed_risk.py"
click node_thresholds "https://github.com/jarambler/entropyguard/blob/main/src/classifier/thresholds.py"
click node_evaluator "https://github.com/jarambler/entropyguard/blob/main/src/evaluation/evaluator.py"
click node_cross_eval "https://github.com/jarambler/entropyguard/blob/main/scripts/eval_cross_dataset.py"
click node_plotting "https://github.com/jarambler/entropyguard/blob/main/src/utils/plotting.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_dataset,node_external_data toneBlue
class node_model,node_registry,node_entropy toneAmber
class node_pipeline,node_detect_cli,node_features,node_selection,node_artifacts,node_trainer,node_logistic,node_adaptive,node_signed,node_thresholds toneMint
class node_evaluator,node_cross_eval,node_plotting,node_openclaw toneRose
class node_researcher,node_workspace,node_agent,node_service toneIndigo
```

## Components

### Data preparation

- [Dataset builder](https://github.com/jarambler/entropyguard/blob/main/src/data/dataset.py): `src/data/dataset.py`
- [External datasets](https://github.com/jarambler/entropyguard/blob/main/src/data/external_datasets.py): `src/data/external_datasets.py`

### Model probing

- [Model and attention](https://github.com/jarambler/entropyguard/blob/main/src/models/model_loader.py): `src/models/model_loader.py`
- [Model registry](https://github.com/jarambler/entropyguard/blob/main/src/models/registry.py): `src/models/registry.py`
- [Regional features](https://github.com/jarambler/entropyguard/blob/main/src/entropy/entropy_compute.py): `src/entropy/entropy_compute.py`

### Head selection and detection

- [Train pipeline](https://github.com/jarambler/entropyguard/blob/main/run_pipeline.py): `run_pipeline.py`
- [Detect input](https://github.com/jarambler/entropyguard/blob/main/scripts/detect.py): `scripts/detect.py`
- [Carrier-delta features](https://github.com/jarambler/entropyguard/blob/main/src/head_selection/features.py): `src/head_selection/features.py`
- [CI head selection](https://github.com/jarambler/entropyguard/blob/main/src/head_selection/selector.py): `src/head_selection/selector.py`
- [Selection artifacts](https://github.com/jarambler/entropyguard/blob/main/src/head_selection/artifacts.py): `src/head_selection/artifacts.py`
- [Classifier training](https://github.com/jarambler/entropyguard/blob/main/src/classifier/trainer.py): `src/classifier/trainer.py`
- [Selected-head logistic](https://github.com/jarambler/entropyguard/blob/main/src/classifier/selected_head_logistic.py): `src/classifier/selected_head_logistic.py`
- [Adaptive margin](https://github.com/jarambler/entropyguard/blob/main/src/classifier/adaptive_margin.py): `src/classifier/adaptive_margin.py`
- [Signed risk](https://github.com/jarambler/entropyguard/blob/main/src/classifier/signed_risk.py): `src/classifier/signed_risk.py`
- [Threshold utilities](https://github.com/jarambler/entropyguard/blob/main/src/classifier/thresholds.py): `src/classifier/thresholds.py`

### Evaluation and integration

- [Metric evaluation](https://github.com/jarambler/entropyguard/blob/main/src/evaluation/evaluator.py): `src/evaluation/evaluator.py`
- [Cross-dataset evaluation](https://github.com/jarambler/entropyguard/blob/main/scripts/eval_cross_dataset.py): `scripts/eval_cross_dataset.py`
- [Result visualization](https://github.com/jarambler/entropyguard/blob/main/src/utils/plotting.py): `src/utils/plotting.py`
- **OpenClaw hook design**

### Other components

- **Researcher**
- **Workspace files**
- **OpenClaw agent**
- **EntropyGuard service**

## Connections

- Researcher → Train pipeline: runs training (evidence: `README.md`)
- Train pipeline → Dataset builder: prepares samples (evidence: `run_pipeline.py`)
- Train pipeline → Model and attention: loads model (evidence: `run_pipeline.py`)
- Model and attention → Model registry: reads registry (evidence: `src/models/model_loader.py`)
- Train pipeline → Regional features: computes attention features (evidence: `run_pipeline.py`)
- Train pipeline → CI head selection: selects heads (evidence: `run_pipeline.py`)
- CI head selection → Regional features: uses regional features (evidence: `src/head_selection/selector.py`)
- Train pipeline → Selection artifacts: saves selection (evidence: `run_pipeline.py`)
- Train pipeline → Carrier-delta features: builds classifier features (evidence: `run_pipeline.py`)
- Carrier-delta features → Regional features: uses regional measures (evidence: `src/head_selection/features.py`)
- Train pipeline → Classifier training: trains classifier (evidence: `run_pipeline.py`)
- Classifier training → Selected-head logistic: selects classifier (evidence: `src/classifier/trainer.py`)
- Classifier training → Adaptive margin: supports classifier (evidence: `src/classifier/trainer.py`)
- Classifier training → Signed risk: supports classifier (evidence: `src/classifier/trainer.py`)
- Adaptive margin → Threshold utilities: chooses thresholds (evidence: `src/classifier/adaptive_margin.py`)
- Selected-head logistic → Threshold utilities: uses threshold utilities (evidence: `src/classifier/selected_head_logistic.py`)
- Detect input → Dataset builder: formats input (evidence: `scripts/detect.py`)
- Detect input → Model and attention: loads model (evidence: `scripts/detect.py`)
- Detect input → Regional features: computes features (evidence: `scripts/detect.py`)
- Detect input → Classifier training: loads classifier (evidence: `scripts/detect.py`)
- Researcher → Detect input: submits input (evidence: `README.md`)
- Cross-dataset evaluation → External datasets: loads benchmarks (evidence: `scripts/eval_cross_dataset.py`)
- Cross-dataset evaluation → Model and attention: loads model (evidence: `scripts/eval_cross_dataset.py`)
- Cross-dataset evaluation → Regional features: computes features (evidence: `scripts/eval_cross_dataset.py`)
- Cross-dataset evaluation → Dataset builder: formats samples (evidence: `scripts/eval_cross_dataset.py`)
- Cross-dataset evaluation → Classifier training: evaluates classifier (evidence: `scripts/eval_cross_dataset.py`)
- Classifier training → Metric evaluation: computes metrics (evidence: `src/classifier/trainer.py`)
- Researcher → Cross-dataset evaluation: runs evaluation (evidence: `README.md`)
- Researcher → Result visualization: requests figures (evidence: `README.md`)
- OpenClaw agent → Workspace files: references files (evidence: `README.md`)
- OpenClaw hook design → Workspace files: extracts content (evidence: `README.md`)
- OpenClaw hook design → EntropyGuard service: sends detection request (evidence: `README.md`)
- EntropyGuard service → Detect input: uses detector design
- OpenClaw hook design → OpenClaw agent: blocks tool call (evidence: `README.md`)
- External datasets → Cross-dataset evaluation: provides datasets (evidence: `scripts/eval_cross_dataset.py`)
