# bullygen/runweaver architecture

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

- Interactive diagram: https://gitdiagram.com/bullygen/runweaver
- Repository: https://github.com/bullygen/runweaver

## Overview

Runweaver is a typed framework for planning and running computational/ML experiments, then recovering, evaluating, and refining them. The principal workflow is declarative configuration or library API → parameter-space plans → validated block pipeline → local or optional-backend execution → durable run state and content-addressed artifacts → decisions and refinement. The README documents broader integrations and planning/selection capabilities; source excerpts confirm key local-engine and CLI behavior. Several subsystems are unsampled, so their documented links are identified as such rather than inferred from imports.

Main entry points: [`src/runweaver/execution/engine.py`](https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/engine.py) (Local executor), [`src/runweaver/pipeline/graph.py`](https://github.com/bullygen/runweaver/blob/main/src/runweaver/pipeline/graph.py) (Validated DAG), [`src/runweaver/planning/planners.py`](https://github.com/bullygen/runweaver/blob/main/src/runweaver/planning/planners.py) (Trial planners), [`src/runweaver/cli/app.py`](https://github.com/bullygen/runweaver/blob/main/src/runweaver/cli/app.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI commands<br/>[app.py]"]
  node_config["Run configuration<br/>[config.py]"]
  node_api["Python API<br/>[api.py]"]
end

subgraph group_design["Pipeline and planning"]
  node_blocks["Typed blocks<br/>[blocks.py]"]
  node_pipeline["Validated DAG<br/>[graph.py]"]
  node_space["Parameter space<br/>[space.py]"]
  node_planners["Trial planners<br/>[planners.py]"]
  node_models["Domain contracts<br/>[models.py]"]
  node_pytorch["PyTorch blocks<br/>[blocks.py]"]
end

subgraph group_runtime["Execution runtime"]
  node_engine["Local executor<br/>[engine.py]"]
  node_context["Run context<br/>[context.py]"]
  node_study["Study runner<br/>[study.py]"]
  node_prefect["Prefect backend<br/>[backend.py]"]
  node_ray["Ray backend<br/>[backend.py]"]
end

subgraph group_records["State and artifacts"]
  node_state[("Run state store<br/>[store.py]")]
  node_checkpoints["Checkpoint service<br/>[checkpoints.py]"]
  node_artifactstore[("Artifact store<br/>[store.py]")]
  node_serializers["Artifact serializers<br/>[serializers.py]"]
  node_hashing["Lineage hashing<br/>[hashing.py]"]
end

subgraph group_iteration["Evaluation and extensions"]
  node_decisions["Trial decisions<br/>[decisions.py]"]
  node_refinement["Plan refinement<br/>[strategies.py]"]
  node_optuna["Optuna adapter<br/>[adapter.py]"]
  node_mlflow["MLflow tracking<br/>[tracker.py]"]
end

node_user(("Experiment author"))

node_user -->|"invokes"| node_cli
node_user -->|"builds runs"| node_api
node_cli -->|"loads config"| node_config
node_cli -->|"selects planner"| node_planners
node_config -->|"builds pipeline"| node_pipeline
node_api -->|"exposes pipeline"| node_pipeline
node_api -->|"exposes blocks"| node_blocks
node_space -->|"defines design"| node_planners
node_planners -.->|"supplies trial plans"| node_engine
node_pipeline -->|"executes DAG"| node_engine
node_blocks -->|"forms graph nodes"| node_pipeline
node_engine -->|"constructs context"| node_context
node_engine -->|"records run state"| node_state
node_engine -->|"reads and writes artifacts"| node_artifactstore
node_engine -->|"serializes values"| node_serializers
node_engine -->|"computes cache key"| node_hashing
node_checkpoints -->|"persists checkpoints"| node_state
node_serializers -->|"uses fingerprints"| node_hashing
node_engine -.->|"supports study runs"| node_study
node_engine -.->|"delegates execution"| node_prefect
node_engine -.->|"delegates execution"| node_ray
node_engine -.->|"produces metrics"| node_decisions
node_decisions -->|"guides next design"| node_refinement
node_refinement -.->|"refines plans"| node_planners
node_planners -.->|"uses sampler"| node_optuna
node_engine -.->|"reports tracking"| node_mlflow
node_pytorch -->|"implements block patterns"| node_blocks
node_pipeline -->|"validates contracts"| node_models
node_state -->|"stores run records"| node_models

click node_cli "https://github.com/bullygen/runweaver/blob/main/src/runweaver/cli/app.py"
click node_config "https://github.com/bullygen/runweaver/blob/main/src/runweaver/config.py"
click node_api "https://github.com/bullygen/runweaver/blob/main/src/runweaver/api.py"
click node_blocks "https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/blocks.py"
click node_pipeline "https://github.com/bullygen/runweaver/blob/main/src/runweaver/pipeline/graph.py"
click node_space "https://github.com/bullygen/runweaver/blob/main/src/runweaver/planning/space.py"
click node_planners "https://github.com/bullygen/runweaver/blob/main/src/runweaver/planning/planners.py"
click node_models "https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/models.py"
click node_engine "https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/engine.py"
click node_context "https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/context.py"
click node_study "https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/study.py"
click node_state "https://github.com/bullygen/runweaver/blob/main/src/runweaver/persistence/store.py"
click node_checkpoints "https://github.com/bullygen/runweaver/blob/main/src/runweaver/persistence/checkpoints.py"
click node_artifactstore "https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/store.py"
click node_serializers "https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/serializers.py"
click node_hashing "https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/hashing.py"
click node_decisions "https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/decisions.py"
click node_refinement "https://github.com/bullygen/runweaver/blob/main/src/runweaver/refinement/strategies.py"
click node_optuna "https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/optuna/adapter.py"
click node_prefect "https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/prefect/backend.py"
click node_ray "https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/ray/backend.py"
click node_mlflow "https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/mlflow/tracker.py"
click node_pytorch "https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/pytorch/blocks.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,node_api toneBlue
class node_blocks,node_pipeline,node_space,node_planners,node_models,node_pytorch toneAmber
class node_engine,node_context,node_study,node_prefect,node_ray toneMint
class node_state,node_checkpoints,node_artifactstore,node_serializers,node_hashing toneRose
class node_decisions,node_refinement,node_optuna,node_mlflow,node_user toneIndigo
```

## Components

### Entry and configuration

- [CLI commands](https://github.com/bullygen/runweaver/blob/main/src/runweaver/cli/app.py): `src/runweaver/cli/app.py`
- [Run configuration](https://github.com/bullygen/runweaver/blob/main/src/runweaver/config.py): `src/runweaver/config.py`
- [Python API](https://github.com/bullygen/runweaver/blob/main/src/runweaver/api.py): `src/runweaver/api.py`

### Pipeline and planning

- [Typed blocks](https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/blocks.py): `src/runweaver/domain/blocks.py`
- [Validated DAG](https://github.com/bullygen/runweaver/blob/main/src/runweaver/pipeline/graph.py): `src/runweaver/pipeline/graph.py`
- [Parameter space](https://github.com/bullygen/runweaver/blob/main/src/runweaver/planning/space.py): `src/runweaver/planning/space.py`
- [Trial planners](https://github.com/bullygen/runweaver/blob/main/src/runweaver/planning/planners.py): `src/runweaver/planning/planners.py`
- [Domain contracts](https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/models.py): `src/runweaver/domain/models.py`
- [PyTorch blocks](https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/pytorch/blocks.py): `src/runweaver/integrations/pytorch/blocks.py`

### Execution runtime

- [Local executor](https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/engine.py): `src/runweaver/execution/engine.py`
- [Run context](https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/context.py): `src/runweaver/execution/context.py`
- [Study runner](https://github.com/bullygen/runweaver/blob/main/src/runweaver/execution/study.py): `src/runweaver/execution/study.py`
- [Prefect backend](https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/prefect/backend.py): `src/runweaver/integrations/prefect/backend.py`
- [Ray backend](https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/ray/backend.py): `src/runweaver/integrations/ray/backend.py`

### State and artifacts

- [Run state store](https://github.com/bullygen/runweaver/blob/main/src/runweaver/persistence/store.py): `src/runweaver/persistence/store.py`
- [Checkpoint service](https://github.com/bullygen/runweaver/blob/main/src/runweaver/persistence/checkpoints.py): `src/runweaver/persistence/checkpoints.py`
- [Artifact store](https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/store.py): `src/runweaver/artifacts/store.py`
- [Artifact serializers](https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/serializers.py): `src/runweaver/artifacts/serializers.py`
- [Lineage hashing](https://github.com/bullygen/runweaver/blob/main/src/runweaver/artifacts/hashing.py): `src/runweaver/artifacts/hashing.py`

### Evaluation and extensions

- [Trial decisions](https://github.com/bullygen/runweaver/blob/main/src/runweaver/domain/decisions.py): `src/runweaver/domain/decisions.py`
- [Plan refinement](https://github.com/bullygen/runweaver/blob/main/src/runweaver/refinement/strategies.py): `src/runweaver/refinement/strategies.py`
- [Optuna adapter](https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/optuna/adapter.py): `src/runweaver/integrations/optuna/adapter.py`
- [MLflow tracking](https://github.com/bullygen/runweaver/blob/main/src/runweaver/integrations/mlflow/tracker.py): `src/runweaver/integrations/mlflow/tracker.py`

### Other components

- **Experiment author**

## Connections

- Experiment author → CLI commands: invokes
- Experiment author → Python API: builds runs
- CLI commands → Run configuration: loads config (evidence: `src/runweaver/cli/app.py`)
- CLI commands → Trial planners: selects planner (evidence: `src/runweaver/cli/app.py`)
- Run configuration → Validated DAG: builds pipeline (evidence: `src/runweaver/config.py`)
- Python API → Validated DAG: exposes pipeline (evidence: `src/runweaver/api.py`)
- Python API → Typed blocks: exposes blocks (evidence: `src/runweaver/api.py`)
- Parameter space → Trial planners: defines design (evidence: `src/runweaver/planning/planners.py`)
- Trial planners → Local executor: supplies trial plans
- Validated DAG → Local executor: executes DAG
- Typed blocks → Validated DAG: forms graph nodes (evidence: `src/runweaver/pipeline/graph.py`)
- Local executor → Run context: constructs context (evidence: `src/runweaver/execution/engine.py`)
- Local executor → Run state store: records run state (evidence: `src/runweaver/execution/engine.py`)
- Local executor → Artifact store: reads and writes artifacts (evidence: `src/runweaver/execution/engine.py`)
- Local executor → Artifact serializers: serializes values (evidence: `src/runweaver/execution/engine.py`)
- Local executor → Lineage hashing: computes cache key (evidence: `src/runweaver/execution/engine.py`)
- Checkpoint service → Run state store: persists checkpoints (evidence: `src/runweaver/persistence/checkpoints.py`)
- Artifact serializers → Lineage hashing: uses fingerprints (evidence: `src/runweaver/artifacts/serializers.py`)
- Local executor → Study runner: supports study runs
- Local executor → Prefect backend: delegates execution
- Local executor → Ray backend: delegates execution
- Local executor → Trial decisions: produces metrics
- Trial decisions → Plan refinement: guides next design
- Plan refinement → Trial planners: refines plans
- Trial planners → Optuna adapter: uses sampler (evidence: `src/runweaver/integrations/optuna/adapter.py`)
- Local executor → MLflow tracking: reports tracking
- PyTorch blocks → Typed blocks: implements block patterns (evidence: `src/runweaver/integrations/pytorch/blocks.py`)
- Validated DAG → Domain contracts: validates contracts (evidence: `src/runweaver/pipeline/graph.py`)
- Run state store → Domain contracts: stores run records (evidence: `src/runweaver/persistence/store.py`)
