# swaroop494/helia architecture

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

## Overview

Helia is a failure-guided pytest-generation and evaluation system for Python repositories. Users configure and launch runs through the CLI; the controller coordinates repository indexing, mutant sampling, test generation and execution, using feedback to guide later generation before evaluating held-out mutants. Results include triage, provenance and reports. The README documents these product stages and integrations, but the controller and several subsystem implementations were not excerpted, so their internal call structure is not asserted.

Main entry points: [`src/helia/controller/__init__.py`](https://github.com/swaroop494/helia/blob/main/src/helia/controller/__init__.py) (Experiment controller), [`src/helia/cli.py`](https://github.com/swaroop494/helia/blob/main/src/helia/cli.py) (Helia CLI), [`src/helia/executor/__init__.py`](https://github.com/swaroop494/helia/blob/main/src/helia/executor/__init__.py) (Docker executor), [`src/helia/repo_index/__init__.py`](https://github.com/swaroop494/helia/blob/main/src/helia/repo_index/__init__.py) (Repository index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["Helia CLI<br/>[cli.py]"]
  node_config["Run configuration<br/>[config.py]"]
end

subgraph group_experiment["Experiment control"]
  node_controller["Experiment controller<br/>[__init__.py]"]
  node_index["Repository index<br/>[__init__.py]"]
  node_mutants["Mutant sampling<br/>[__init__.py]"]
  node_generator["Test generation<br/>[__init__.py]"]
  node_policy["Guidance policy<br/>[__init__.py]"]
  node_llm["Cached LLM<br/>[__init__.py]"]
end

subgraph group_execution["Test execution"]
  node_executor["Docker executor<br/>[__init__.py]"]
  node_worker["Container worker<br/>[worker.py]"]
  node_baselines["Baseline adapters<br/>[__init__.py]"]
  node_coverup["CoverUp import<br/>[__init__.py]"]
end

subgraph group_analysis["Feedback analysis"]
  node_feedback["Failure analysis<br/>[__init__.py]"]
  node_triage["Original failure triage<br/>[triage.py]"]
  node_history["Fix verification<br/>[history.py]"]
end

subgraph group_records["Contracts and results"]
  node_report["Reports and plots<br/>[report.py]"]
  node_io["Run persistence<br/>[io.py]"]
  node_contracts["Versioned records<br/>[models.py]"]
end

node_user(("Researcher"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads configuration"| node_config
node_cli -->|"launches runs"| node_controller
node_cli -->|"builds index"| node_index
node_cli -->|"requests reports"| node_report
node_cli -->|"verifies fixes"| node_history
node_cli -->|"creates executor"| node_executor
node_controller -->|"indexes source"| node_index
node_controller -->|"samples mutants"| node_mutants
node_controller -->|"generates tests"| node_generator
node_controller -->|"evaluates tests"| node_executor
node_controller -->|"guides generation"| node_policy
node_controller -->|"requests generations"| node_llm
node_controller -->|"runs baseline arms"| node_baselines
node_controller -->|"learns from feedback"| node_feedback
node_controller -->|"triages failures"| node_triage
node_controller -->|"produces reports"| node_report
node_executor -->|"dispatches jobs"| node_worker
node_controller -->|"imports baseline results"| node_coverup
node_cli -->|"supplies execution evidence"| node_history

click node_cli "https://github.com/swaroop494/helia/blob/main/src/helia/cli.py"
click node_config "https://github.com/swaroop494/helia/blob/main/src/helia/controller/config.py"
click node_controller "https://github.com/swaroop494/helia/blob/main/src/helia/controller/__init__.py"
click node_index "https://github.com/swaroop494/helia/blob/main/src/helia/repo_index/__init__.py"
click node_mutants "https://github.com/swaroop494/helia/blob/main/src/helia/mutants/__init__.py"
click node_generator "https://github.com/swaroop494/helia/blob/main/src/helia/generator/__init__.py"
click node_policy "https://github.com/swaroop494/helia/blob/main/src/helia/policy/__init__.py"
click node_llm "https://github.com/swaroop494/helia/blob/main/src/helia/llm/__init__.py"
click node_executor "https://github.com/swaroop494/helia/blob/main/src/helia/executor/__init__.py"
click node_worker "https://github.com/swaroop494/helia/blob/main/src/helia/executor/worker.py"
click node_baselines "https://github.com/swaroop494/helia/blob/main/src/helia/baselines/__init__.py"
click node_coverup "https://github.com/swaroop494/helia/blob/main/src/helia/baselines/__init__.py"
click node_feedback "https://github.com/swaroop494/helia/blob/main/src/helia/analysis/__init__.py"
click node_triage "https://github.com/swaroop494/helia/blob/main/src/helia/analysis/triage.py"
click node_history "https://github.com/swaroop494/helia/blob/main/src/helia/analysis/history.py"
click node_report "https://github.com/swaroop494/helia/blob/main/src/helia/controller/report.py"
click node_io "https://github.com/swaroop494/helia/blob/main/src/helia/io.py"
click node_contracts "https://github.com/swaroop494/helia/blob/main/contracts/models.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_config toneBlue
class node_controller,node_index,node_mutants,node_generator,node_policy,node_llm toneAmber
class node_executor,node_worker,node_baselines,node_coverup toneMint
class node_feedback,node_triage,node_history toneRose
class node_report,node_io,node_contracts,node_user toneIndigo
```

## Components

### User interface

- [Helia CLI](https://github.com/swaroop494/helia/blob/main/src/helia/cli.py): `src/helia/cli.py`
- [Run configuration](https://github.com/swaroop494/helia/blob/main/src/helia/controller/config.py): `src/helia/controller/config.py`

### Experiment control

- [Experiment controller](https://github.com/swaroop494/helia/blob/main/src/helia/controller/__init__.py): `src/helia/controller/__init__.py`
- [Repository index](https://github.com/swaroop494/helia/blob/main/src/helia/repo_index/__init__.py): `src/helia/repo_index/__init__.py`
- [Mutant sampling](https://github.com/swaroop494/helia/blob/main/src/helia/mutants/__init__.py): `src/helia/mutants/__init__.py`
- [Test generation](https://github.com/swaroop494/helia/blob/main/src/helia/generator/__init__.py): `src/helia/generator/__init__.py`
- [Guidance policy](https://github.com/swaroop494/helia/blob/main/src/helia/policy/__init__.py): `src/helia/policy/__init__.py`
- [Cached LLM](https://github.com/swaroop494/helia/blob/main/src/helia/llm/__init__.py): `src/helia/llm/__init__.py`

### Test execution

- [Docker executor](https://github.com/swaroop494/helia/blob/main/src/helia/executor/__init__.py): `src/helia/executor/__init__.py`
- [Container worker](https://github.com/swaroop494/helia/blob/main/src/helia/executor/worker.py): `src/helia/executor/worker.py`
- [Baseline adapters](https://github.com/swaroop494/helia/blob/main/src/helia/baselines/__init__.py): `src/helia/baselines/__init__.py`
- [CoverUp import](https://github.com/swaroop494/helia/blob/main/src/helia/baselines/__init__.py): `src/helia/baselines/__init__.py`

### Feedback analysis

- [Failure analysis](https://github.com/swaroop494/helia/blob/main/src/helia/analysis/__init__.py): `src/helia/analysis/__init__.py`
- [Original failure triage](https://github.com/swaroop494/helia/blob/main/src/helia/analysis/triage.py): `src/helia/analysis/triage.py`
- [Fix verification](https://github.com/swaroop494/helia/blob/main/src/helia/analysis/history.py): `src/helia/analysis/history.py`

### Contracts and results

- [Reports and plots](https://github.com/swaroop494/helia/blob/main/src/helia/controller/report.py): `src/helia/controller/report.py`
- [Run persistence](https://github.com/swaroop494/helia/blob/main/src/helia/io.py): `src/helia/io.py`
- [Versioned records](https://github.com/swaroop494/helia/blob/main/contracts/models.py): `contracts/models.py`

### Other components

- **Researcher**

## Connections

- Researcher → Helia CLI: runs commands (evidence: `README.md`)
- Helia CLI → Run configuration: loads configuration (evidence: `src/helia/cli.py`)
- Helia CLI → Experiment controller: launches runs (evidence: `src/helia/cli.py`)
- Helia CLI → Repository index: builds index (evidence: `src/helia/cli.py`)
- Helia CLI → Reports and plots: requests reports (evidence: `src/helia/cli.py`)
- Helia CLI → Fix verification: verifies fixes (evidence: `src/helia/cli.py`)
- Helia CLI → Docker executor: creates executor (evidence: `src/helia/cli.py`)
- Experiment controller → Repository index: indexes source (evidence: `README.md`)
- Experiment controller → Mutant sampling: samples mutants (evidence: `README.md`)
- Experiment controller → Test generation: generates tests (evidence: `README.md`)
- Experiment controller → Docker executor: evaluates tests (evidence: `README.md`)
- Experiment controller → Guidance policy: guides generation (evidence: `README.md`)
- Experiment controller → Cached LLM: requests generations (evidence: `README.md`)
- Experiment controller → Baseline adapters: runs baseline arms (evidence: `README.md`)
- Experiment controller → Failure analysis: learns from feedback (evidence: `README.md`)
- Experiment controller → Original failure triage: triages failures (evidence: `README.md`)
- Experiment controller → Reports and plots: produces reports (evidence: `README.md`)
- Docker executor → Container worker: dispatches jobs (evidence: `src/helia/executor/__init__.py`)
- Experiment controller → CoverUp import: imports baseline results (evidence: `README.md`)
- Helia CLI → Fix verification: supplies execution evidence (evidence: `src/helia/cli.py`)