# amd-agi/geak architecture

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

## Overview

GEAK optimizes AMD GPU workloads through two user-facing workflows: end-to-end model serving and single-kernel tuning. The e2e workflow profiles serving, prioritizes hot kernels, explores configuration and kernel options, and validates overlays; it can delegate kernel work to the kernel workflow. Supporting layers include the standalone workflow runtime, launch-configuration and handoff handling, persistent optimization knowledge, and reference optimization skills. README statements establish the main workflow relationship; source-index references support the shown module connections. Unsampled workflow internals and optional integrations are not expanded.

Main entry points: [`e2e_workflow/scripts/e2e_store.py`](https://github.com/amd-agi/geak/blob/main/e2e_workflow/scripts/e2e_store.py) (E2E knowledge adapter), [`kernel_workflow/scripts/experience_store.py`](https://github.com/amd-agi/geak/blob/main/kernel_workflow/scripts/experience_store.py) (Kernel experience adapter), [`e2e_workflow/e2e_workflow.js`](https://github.com/amd-agi/geak/blob/main/e2e_workflow/e2e_workflow.js) (Serving optimizer), [`interface/runtime/engine/run_workflow.mjs`](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/run_workflow.mjs) (Workflow executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Optimization workflows"]
  node_e2e["Serving optimizer<br/>[e2e_workflow.js]"]
  node_kernel["Kernel optimizer<br/>[kernel_workflow.js]"]
  node_kernel_lane["Kernel tuning lane<br/>[kernel_lane.js]"]
  node_e2e_tools["Serving analysis tools"]
  node_roofline["Roofline analysis<br/>[roofline_tools.py]"]
  node_overlay["FlyDSL overlay"]
end

subgraph group_runtime["Workflow runtime"]
  node_runtime_engine["Workflow executor<br/>[run_workflow.mjs]"]
  node_runtime_config["Agent configuration<br/>[config.mjs]"]
  node_backend_contract["Backend adapter<br/>[base.mjs]"]
  node_generic_backend["Generic backend<br/>[generic.mjs]"]
  node_runtime_schema["Workflow schema<br/>[schema.mjs]"]
  node_experiment["Experiment support<br/>[experiment.mjs]"]
end

subgraph group_knowledge["Optimization knowledge"]
  node_e2e_store["E2E knowledge adapter<br/>[e2e_store.py]"]
  node_experience_store["Kernel experience adapter"]
  node_identity["Knowledge identity<br/>[identity.py]"]
  node_local_store[("Local knowledge store<br/>[store_local.py]")]
  node_store_client["Remote store client<br/>[store_client.py]"]
  node_attestation["Record attestation<br/>[attest.py]"]
  node_retraction["Record retraction<br/>[retract.py]"]
  node_curation["Knowledge curation<br/>[curate.py]"]
  node_ladder["Fallback ladder<br/>[ladder.py]"]
  node_plane["Store plane<br/>[plane.py]"]
  node_remote_store["Remote store<br/>[store_remote.py]"]
end

subgraph group_skills["Expert skills"]
  node_skill_assets["Tuning reference skills"]
  node_gluon_tools["Gluon authoring tools"]
  node_tuning_tools["Tuning tools"]
  node_claims["Tuning claim checks<br/>[claims.py]"]
  node_flydsl_skill["FlyDSL MoE integration<br/>[flydsl_moe_shim.py]"]
end

subgraph group_integration["Handoff integration"]
  node_handoff_runner["E2E handoff runner<br/>[run_e2e.py]"]
  node_effective_config["Launch config"]
end

node_user(("Engineer"))
node_hyperloom(("External orchestrator"))

node_user -->|"optimizes serving"| node_e2e
node_user -->|"optimizes kernel"| node_kernel
node_e2e -->|"profiles and analyzes"| node_e2e_tools
node_e2e -.->|"uses analysis"| node_roofline
node_e2e -.->|"applies overlay"| node_overlay
node_e2e -->|"recursively calls"| node_kernel
node_kernel -->|"orchestrates"| node_kernel_lane
node_user -->|"runs workflow"| node_runtime_engine
node_runtime_engine -->|"loads selection"| node_runtime_config
node_runtime_engine -->|"dispatches agent"| node_backend_contract
node_runtime_engine -->|"selects fallback"| node_generic_backend
node_generic_backend -->|"uses contract"| node_backend_contract
node_runtime_engine -->|"validates workflow"| node_runtime_schema
node_runtime_engine -.->|"supports experiments"| node_experiment
node_hyperloom -->|"submits handoff"| node_handoff_runner
node_handoff_runner -->|"uses config"| node_effective_config
node_e2e_store -->|"uses identity"| node_identity
node_e2e_store -->|"uses attestation"| node_attestation
node_e2e_store -->|"uses curation"| node_curation
node_e2e_store -->|"uses fallback ladder"| node_ladder
node_e2e_store -->|"uses store plane"| node_plane
node_e2e_store -->|"uses retraction"| node_retraction
node_e2e_store -->|"uses local store"| node_local_store
node_experience_store -->|"uses identity"| node_identity
node_experience_store -->|"uses attestation"| node_attestation
node_experience_store -->|"uses curation"| node_curation
node_experience_store -->|"uses fallback ladder"| node_ladder
node_experience_store -->|"uses store plane"| node_plane
node_experience_store -->|"uses retraction"| node_retraction
node_experience_store -->|"uses local store"| node_local_store
node_remote_store -->|"mirrors store"| node_local_store
node_remote_store -->|"uses client"| node_store_client
node_attestation -->|"uses retraction"| node_retraction
node_retraction -->|"rewrites records"| node_local_store
node_e2e -.->|"draws on knowledge"| node_skill_assets
node_kernel -.->|"draws on knowledge"| node_skill_assets
node_skill_assets -.->|"includes tooling"| node_gluon_tools
node_skill_assets -.->|"includes tooling"| node_tuning_tools
node_skill_assets -.->|"includes validation"| node_claims
node_skill_assets -.->|"includes integration"| node_flydsl_skill

click node_e2e "https://github.com/amd-agi/geak/blob/main/e2e_workflow/e2e_workflow.js"
click node_kernel "https://github.com/amd-agi/geak/blob/main/kernel_workflow/kernel_workflow.js"
click node_kernel_lane "https://github.com/amd-agi/geak/blob/main/kernel_workflow/kernel_lane.js"
click node_e2e_tools "https://github.com/amd-agi/geak/tree/main/e2e_workflow/scripts"
click node_roofline "https://github.com/amd-agi/geak/blob/main/e2e_workflow/knowledge/analysis_skills/roofline/roofline_tools.py"
click node_overlay "https://github.com/amd-agi/geak/blob/main/e2e_workflow/knowledge/templates/flydsl_overlay_sitecustomize.py"
click node_runtime_engine "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/run_workflow.mjs"
click node_runtime_config "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/config.mjs"
click node_backend_contract "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/backends/base.mjs"
click node_generic_backend "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/backends/generic.mjs"
click node_runtime_schema "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/schema.mjs"
click node_experiment "https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/experiment.mjs"
click node_handoff_runner "https://github.com/amd-agi/geak/blob/main/interface/run_e2e.py"
click node_effective_config "https://github.com/amd-agi/geak/blob/main/interface/effective_config.py"
click node_e2e_store "https://github.com/amd-agi/geak/blob/main/e2e_workflow/scripts/e2e_store.py"
click node_experience_store "https://github.com/amd-agi/geak/blob/main/kernel_workflow/scripts/experience_store.py"
click node_identity "https://github.com/amd-agi/geak/blob/main/kb/identity.py"
click node_local_store "https://github.com/amd-agi/geak/blob/main/kb/store_local.py"
click node_store_client "https://github.com/amd-agi/geak/blob/main/kb/store_client.py"
click node_attestation "https://github.com/amd-agi/geak/blob/main/kb/attest.py"
click node_retraction "https://github.com/amd-agi/geak/blob/main/kb/retract.py"
click node_curation "https://github.com/amd-agi/geak/blob/main/kb/curate.py"
click node_ladder "https://github.com/amd-agi/geak/blob/main/kb/ladder.py"
click node_plane "https://github.com/amd-agi/geak/blob/main/kb/plane.py"
click node_remote_store "https://github.com/amd-agi/geak/blob/main/kb/store_remote.py"
click node_skill_assets "https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills"
click node_gluon_tools "https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills/skills/gluon_authoring/scripts"
click node_tuning_tools "https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills/tuning/tools"
click node_claims "https://github.com/amd-agi/geak/blob/main/perf_knowledge/expert_skills/tuning/validate/claims.py"
click node_flydsl_skill "https://github.com/amd-agi/geak/blob/main/perf_knowledge/expert_skills/skills/apply_flydsl_moe_to_vllm/flydsl_moe_shim.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_e2e,node_kernel,node_kernel_lane,node_e2e_tools,node_roofline,node_overlay toneBlue
class node_runtime_engine,node_runtime_config,node_backend_contract,node_generic_backend,node_runtime_schema,node_experiment toneAmber
class node_e2e_store,node_experience_store,node_identity,node_local_store,node_store_client,node_attestation,node_retraction,node_curation,node_ladder,node_plane,node_remote_store toneMint
class node_skill_assets,node_gluon_tools,node_tuning_tools,node_claims,node_flydsl_skill toneRose
class node_handoff_runner,node_effective_config,node_user,node_hyperloom toneIndigo
```

## Components

### Optimization workflows

- [Serving optimizer](https://github.com/amd-agi/geak/blob/main/e2e_workflow/e2e_workflow.js): `e2e_workflow/e2e_workflow.js`
- [Kernel optimizer](https://github.com/amd-agi/geak/blob/main/kernel_workflow/kernel_workflow.js): `kernel_workflow/kernel_workflow.js`
- [Kernel tuning lane](https://github.com/amd-agi/geak/blob/main/kernel_workflow/kernel_lane.js): `kernel_workflow/kernel_lane.js`
- [Serving analysis tools](https://github.com/amd-agi/geak/tree/main/e2e_workflow/scripts): `e2e_workflow/scripts`
- [Roofline analysis](https://github.com/amd-agi/geak/blob/main/e2e_workflow/knowledge/analysis_skills/roofline/roofline_tools.py): `e2e_workflow/knowledge/analysis_skills/roofline/roofline_tools.py`
- [FlyDSL overlay](https://github.com/amd-agi/geak/blob/main/e2e_workflow/knowledge/templates/flydsl_overlay_sitecustomize.py): `e2e_workflow/knowledge/templates/flydsl_overlay_sitecustomize.py`

### Workflow runtime

- [Workflow executor](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/run_workflow.mjs): `interface/runtime/engine/run_workflow.mjs`
- [Agent configuration](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/config.mjs): `interface/runtime/engine/config.mjs`
- [Backend adapter](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/backends/base.mjs): `interface/runtime/engine/backends/base.mjs`
- [Generic backend](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/backends/generic.mjs): `interface/runtime/engine/backends/generic.mjs`
- [Workflow schema](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/schema.mjs): `interface/runtime/engine/schema.mjs`
- [Experiment support](https://github.com/amd-agi/geak/blob/main/interface/runtime/engine/experiment.mjs): `interface/runtime/engine/experiment.mjs`

### Optimization knowledge

- [E2E knowledge adapter](https://github.com/amd-agi/geak/blob/main/e2e_workflow/scripts/e2e_store.py): `e2e_workflow/scripts/e2e_store.py`
- [Kernel experience adapter](https://github.com/amd-agi/geak/blob/main/kernel_workflow/scripts/experience_store.py): `kernel_workflow/scripts/experience_store.py`
- [Knowledge identity](https://github.com/amd-agi/geak/blob/main/kb/identity.py): `kb/identity.py`
- [Local knowledge store](https://github.com/amd-agi/geak/blob/main/kb/store_local.py): `kb/store_local.py`
- [Remote store client](https://github.com/amd-agi/geak/blob/main/kb/store_client.py): `kb/store_client.py`
- [Record attestation](https://github.com/amd-agi/geak/blob/main/kb/attest.py): `kb/attest.py`
- [Record retraction](https://github.com/amd-agi/geak/blob/main/kb/retract.py): `kb/retract.py`
- [Knowledge curation](https://github.com/amd-agi/geak/blob/main/kb/curate.py): `kb/curate.py`
- [Fallback ladder](https://github.com/amd-agi/geak/blob/main/kb/ladder.py): `kb/ladder.py`
- [Store plane](https://github.com/amd-agi/geak/blob/main/kb/plane.py): `kb/plane.py`
- [Remote store](https://github.com/amd-agi/geak/blob/main/kb/store_remote.py): `kb/store_remote.py`

### Expert skills

- [Tuning reference skills](https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills): `perf_knowledge/expert_skills`
- [Gluon authoring tools](https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills/skills/gluon_authoring/scripts): `perf_knowledge/expert_skills/skills/gluon_authoring/scripts`
- [Tuning tools](https://github.com/amd-agi/geak/tree/main/perf_knowledge/expert_skills/tuning/tools): `perf_knowledge/expert_skills/tuning/tools`
- [Tuning claim checks](https://github.com/amd-agi/geak/blob/main/perf_knowledge/expert_skills/tuning/validate/claims.py): `perf_knowledge/expert_skills/tuning/validate/claims.py`
- [FlyDSL MoE integration](https://github.com/amd-agi/geak/blob/main/perf_knowledge/expert_skills/skills/apply_flydsl_moe_to_vllm/flydsl_moe_shim.py): `perf_knowledge/expert_skills/skills/apply_flydsl_moe_to_vllm/flydsl_moe_shim.py`

### Handoff integration

- [E2E handoff runner](https://github.com/amd-agi/geak/blob/main/interface/run_e2e.py): `interface/run_e2e.py`
- [Launch config](https://github.com/amd-agi/geak/blob/main/interface/effective_config.py): `interface/effective_config.py`

### Other components

- **Engineer**
- **External orchestrator**

## Connections

- Engineer → Serving optimizer: optimizes serving (evidence: `README.md`)
- Engineer → Kernel optimizer: optimizes kernel (evidence: `README.md`)
- Serving optimizer → Serving analysis tools: profiles and analyzes (evidence: `README.md`)
- Serving optimizer → Roofline analysis: uses analysis
- Serving optimizer → FlyDSL overlay: applies overlay
- Serving optimizer → Kernel optimizer: recursively calls (evidence: `README.md`)
- Kernel optimizer → Kernel tuning lane: orchestrates (evidence: `README.md`)
- Engineer → Workflow executor: runs workflow (evidence: `README.md`)
- Workflow executor → Agent configuration: loads selection (evidence: `interface/runtime/engine/run_workflow.mjs`)
- Workflow executor → Backend adapter: dispatches agent (evidence: `interface/runtime/engine/run_workflow.mjs`)
- Workflow executor → Generic backend: selects fallback (evidence: `interface/runtime/engine/run_workflow.mjs`)
- Generic backend → Backend adapter: uses contract (evidence: `interface/runtime/engine/backends/generic.mjs`)
- Workflow executor → Workflow schema: validates workflow (evidence: `interface/runtime/engine/run_workflow.mjs`)
- Workflow executor → Experiment support: supports experiments
- External orchestrator → E2E handoff runner: submits handoff (evidence: `interface/run_e2e.py`)
- E2E handoff runner → Launch config: uses config (evidence: `interface/run_e2e.py`)
- E2E knowledge adapter → Knowledge identity: uses identity (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Record attestation: uses attestation (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Knowledge curation: uses curation (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Fallback ladder: uses fallback ladder (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Store plane: uses store plane (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Record retraction: uses retraction (evidence: `e2e_workflow/scripts/e2e_store.py`)
- E2E knowledge adapter → Local knowledge store: uses local store (evidence: `e2e_workflow/scripts/e2e_store.py`)
- Kernel experience adapter → Knowledge identity: uses identity (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Record attestation: uses attestation (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Knowledge curation: uses curation (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Fallback ladder: uses fallback ladder (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Store plane: uses store plane (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Record retraction: uses retraction (evidence: `kernel_workflow/scripts/experience_store.py`)
- Kernel experience adapter → Local knowledge store: uses local store (evidence: `kernel_workflow/scripts/experience_store.py`)
- Remote store → Local knowledge store: mirrors store (evidence: `kb/store_remote.py`)
- Remote store → Remote store client: uses client (evidence: `kb/store_remote.py`)
- Record attestation → Record retraction: uses retraction (evidence: `kb/attest.py`)
- Record retraction → Local knowledge store: rewrites records (evidence: `kb/retract.py`)
- Serving optimizer → Tuning reference skills: draws on knowledge
- Kernel optimizer → Tuning reference skills: draws on knowledge
- Tuning reference skills → Gluon authoring tools: includes tooling
- Tuning reference skills → Tuning tools: includes tooling
- Tuning reference skills → Tuning claim checks: includes validation
- Tuning reference skills → FlyDSL MoE integration: includes integration
