# kys928/hephaestus architecture

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

- Interactive diagram: https://gitdiagram.com/kys928/hephaestus
- Repository: https://github.com/kys928/hephaestus

## Overview

Hephaestus is a governed autonomous scientific-experimentation system: it supports dataset/model discovery, experiment planning, training, evaluation, diagnosis, and controlled recovery or promotion decisions. The principal workflow is mediated by a stage-aware orchestrator, with contracts, policy, durable jobs, and storage as internal layers. The README is empty, and many implementation files were not sampled; edges below are limited to relationships visible in excerpts or SOURCE INDEX references, so some runtime handoffs are intentionally omitted.

Main entry points: [`src/hephaestus/schemas`](https://github.com/kys928/hephaestus/tree/main/src/hephaestus/schemas) (Domain contracts), [`src/hephaestus/control/orchestrator.py`](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/control/orchestrator.py) (Stage orchestrator), [`src/hephaestus/policy/action_registry.py`](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/action_registry.py) (Action registry), [`src/hephaestus/policy/stage_policy.py`](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/stage_policy.py) (Stage policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and governance"]
  node_orchestrator["Stage orchestrator<br/>[orchestrator.py]"]
  node_action_policy["Action registry<br/>[action_registry.py]"]
  node_stage_policy["Stage policy<br/>[stage_policy.py]"]
  node_recovery["Recovery planning<br/>[service.py]"]
  node_recovery_execution["Recovery execution<br/>[controller.py]"]
end

subgraph group_science["Experiment lifecycle"]
  node_dataset["Dataset discovery and processing"]
  node_planning["Experiment planner<br/>[service.py]"]
  node_training_roles["Training setup"]
  node_generation["Evaluation generation<br/>[service.py]"]
  node_evaluation["Experiment comparison"]
  node_diagnosis["Failure diagnosis<br/>[service.py]"]
end

subgraph group_runtime["Execution and jobs"]
  node_training_runtime["Training workers"]
  node_jobs["Durable job queue"]
end

subgraph group_foundation["Contracts and persistence"]
  node_contracts["Domain contracts"]
  node_eval_pack["Evaluation pack loader<br/>[pack_loader.py]"]
  node_config["Configuration loader<br/>[config_loader.py]"]
  node_storage["Storage interface<br/>[base.py]"]
end

node_operator(("Operator"))

node_operator -.->|"requests control"| node_orchestrator
node_orchestrator -->|"checks actions"| node_action_policy
node_orchestrator -->|"resolves stages"| node_stage_policy
node_planning -->|"uses experiment contracts"| node_contracts
node_planning -->|"applies experiment policy"| node_action_policy
node_training_roles -->|"loads launch config"| node_config
node_training_roles -->|"builds training plan"| node_contracts
node_generation -->|"loads frozen pack"| node_eval_pack
node_generation -->|"uses storage interface"| node_storage
node_evaluation -->|"loads evaluation pack"| node_eval_pack
node_evaluation -->|"uses experiment contracts"| node_contracts
node_diagnosis -->|"uses diagnosis contracts"| node_contracts
node_diagnosis -->|"applies diagnosis policy"| node_stage_policy
node_recovery -->|"uses stage policy"| node_stage_policy
node_recovery -->|"uses shared contracts"| node_contracts
node_recovery_execution -->|"checks action boundary"| node_action_policy
node_jobs -.->|"persists job state"| node_storage

click node_orchestrator "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/control/orchestrator.py"
click node_action_policy "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/action_registry.py"
click node_stage_policy "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/stage_policy.py"
click node_dataset "https://github.com/kys928/hephaestus/tree/main/src/hephaestus/data"
click node_planning "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/planning/service.py"
click node_training_roles "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/roles/training_engineer.py"
click node_training_runtime "https://github.com/kys928/hephaestus/tree/main/src/hephaestus/training"
click node_generation "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/generation/service.py"
click node_evaluation "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/evaluation/experiment_service.py"
click node_diagnosis "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/diagnosis/service.py"
click node_recovery "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/recovery/service.py"
click node_recovery_execution "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/recovery/controller.py"
click node_contracts "https://github.com/kys928/hephaestus/tree/main/src/hephaestus/schemas"
click node_eval_pack "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/evaluation/pack_loader.py"
click node_config "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/config_loader.py"
click node_jobs "https://github.com/kys928/hephaestus/tree/main/src/hephaestus/jobs"
click node_storage "https://github.com/kys928/hephaestus/blob/main/src/hephaestus/storage/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_orchestrator,node_action_policy,node_stage_policy,node_recovery,node_recovery_execution toneBlue
class node_dataset,node_planning,node_training_roles,node_generation,node_evaluation,node_diagnosis toneAmber
class node_training_runtime,node_jobs toneMint
class node_contracts,node_eval_pack,node_config,node_storage toneRose
class node_operator toneIndigo
```

## Components

### Control and governance

- [Stage orchestrator](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/control/orchestrator.py): `src/hephaestus/control/orchestrator.py`
- [Action registry](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/action_registry.py): `src/hephaestus/policy/action_registry.py`
- [Stage policy](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/policy/stage_policy.py): `src/hephaestus/policy/stage_policy.py`
- [Recovery planning](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/recovery/service.py): `src/hephaestus/recovery/service.py`
- [Recovery execution](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/recovery/controller.py): `src/hephaestus/recovery/controller.py`

### Experiment lifecycle

- [Dataset discovery and processing](https://github.com/kys928/hephaestus/tree/main/src/hephaestus/data): `src/hephaestus/data`
- [Experiment planner](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/planning/service.py): `src/hephaestus/planning/service.py`
- [Training setup](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/roles/training_engineer.py): `src/hephaestus/roles/training_engineer.py`
- [Evaluation generation](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/generation/service.py): `src/hephaestus/generation/service.py`
- [Experiment comparison](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/evaluation/experiment_service.py): `src/hephaestus/evaluation/experiment_service.py`
- [Failure diagnosis](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/diagnosis/service.py): `src/hephaestus/diagnosis/service.py`

### Execution and jobs

- [Training workers](https://github.com/kys928/hephaestus/tree/main/src/hephaestus/training): `src/hephaestus/training`
- [Durable job queue](https://github.com/kys928/hephaestus/tree/main/src/hephaestus/jobs): `src/hephaestus/jobs`

### Contracts and persistence

- [Domain contracts](https://github.com/kys928/hephaestus/tree/main/src/hephaestus/schemas): `src/hephaestus/schemas`
- [Evaluation pack loader](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/evaluation/pack_loader.py): `src/hephaestus/evaluation/pack_loader.py`
- [Configuration loader](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/config_loader.py): `src/hephaestus/config_loader.py`
- [Storage interface](https://github.com/kys928/hephaestus/blob/main/src/hephaestus/storage/base.py): `src/hephaestus/storage/base.py`

### Other components

- **Operator**

## Connections

- Operator → Stage orchestrator: requests control
- Stage orchestrator → Action registry: checks actions (evidence: `src/hephaestus/control/orchestrator.py`)
- Stage orchestrator → Stage policy: resolves stages (evidence: `src/hephaestus/control/orchestrator.py`)
- Experiment planner → Domain contracts: uses experiment contracts (evidence: `src/hephaestus/planning/service.py`)
- Experiment planner → Action registry: applies experiment policy (evidence: `src/hephaestus/planning/service.py`)
- Training setup → Configuration loader: loads launch config (evidence: `src/hephaestus/roles/training_engineer.py`)
- Training setup → Domain contracts: builds training plan (evidence: `src/hephaestus/roles/training_engineer.py`)
- Evaluation generation → Evaluation pack loader: loads frozen pack (evidence: `src/hephaestus/generation/service.py`)
- Evaluation generation → Storage interface: uses storage interface (evidence: `src/hephaestus/generation/service.py`)
- Experiment comparison → Evaluation pack loader: loads evaluation pack (evidence: `src/hephaestus/evaluation/experiment_service.py`)
- Experiment comparison → Domain contracts: uses experiment contracts (evidence: `src/hephaestus/evaluation/experiment_service.py`)
- Failure diagnosis → Domain contracts: uses diagnosis contracts (evidence: `src/hephaestus/diagnosis/service.py`)
- Failure diagnosis → Stage policy: applies diagnosis policy (evidence: `src/hephaestus/diagnosis/service.py`)
- Recovery planning → Stage policy: uses stage policy (evidence: `src/hephaestus/recovery/service.py`)
- Recovery planning → Domain contracts: uses shared contracts (evidence: `src/hephaestus/recovery/service.py`)
- Recovery execution → Action registry: checks action boundary (evidence: `src/hephaestus/recovery/controller.py`)
- Durable job queue → Storage interface: persists job state
