How kys928/hephaestus works
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: schemas Domain contracts · orchestrator.py Stage orchestrator · action_registry.py Action registry · stage_policy.py Stage policy
Components 18
Control and governance
- Stage orchestrator
src/hephaestus/control/orchestrator.py - Action registry
src/hephaestus/policy/action_registry.py - Stage policy
src/hephaestus/policy/stage_policy.py - Recovery planning
src/hephaestus/recovery/service.py - Recovery execution
src/hephaestus/recovery/controller.py
Experiment lifecycle
- Dataset discovery and processing
src/hephaestus/data - Experiment planner
src/hephaestus/planning/service.py - Training setup
src/hephaestus/roles/training_engineer.py - Evaluation generation
src/hephaestus/generation/service.py - Experiment comparison
src/hephaestus/evaluation/experiment_service.py - Failure diagnosis
src/hephaestus/diagnosis/service.py
Execution and jobs
- Training workers
src/hephaestus/training - Durable job queue
src/hephaestus/jobs
Contracts and persistence
- Domain contracts
src/hephaestus/schemas - Evaluation pack loader
src/hephaestus/evaluation/pack_loader.py - Configuration loader
src/hephaestus/config_loader.py - Storage interface
src/hephaestus/storage/base.py
Other components
- Operator
Connections 17
- Operator → Stage orchestrator: requests control
- Stage orchestrator → Action registry: checks actions
src/hephaestus/control/orchestrator.py - Stage orchestrator → Stage policy: resolves stages
src/hephaestus/control/orchestrator.py - Experiment planner → Domain contracts: uses experiment contracts
src/hephaestus/planning/service.py - Experiment planner → Action registry: applies experiment policy
src/hephaestus/planning/service.py - Training setup → Configuration loader: loads launch config
src/hephaestus/roles/training_engineer.py - Training setup → Domain contracts: builds training plan
src/hephaestus/roles/training_engineer.py - Evaluation generation → Evaluation pack loader: loads frozen pack
src/hephaestus/generation/service.py - Evaluation generation → Storage interface: uses storage interface
src/hephaestus/generation/service.py - Experiment comparison → Evaluation pack loader: loads evaluation pack
src/hephaestus/evaluation/experiment_service.py - Experiment comparison → Domain contracts: uses experiment contracts
src/hephaestus/evaluation/experiment_service.py - Failure diagnosis → Domain contracts: uses diagnosis contracts
src/hephaestus/diagnosis/service.py - Failure diagnosis → Stage policy: applies diagnosis policy
src/hephaestus/diagnosis/service.py - Recovery planning → Stage policy: uses stage policy
src/hephaestus/recovery/service.py - Recovery planning → Domain contracts: uses shared contracts
src/hephaestus/recovery/service.py - Recovery execution → Action registry: checks action boundary
src/hephaestus/recovery/controller.py - Durable job queue → Storage interface: persists job state