# sivabalajisleo/leo architecture

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

- Interactive diagram: https://gitdiagram.com/sivabalajisleo/leo
- Repository: https://github.com/sivabalajisleo/leo

## Overview

HYPER is a research and execution system for finding lower-cost software pathways that satisfy an application contract on constrained local hardware; it does not emulate GPU hardware. The principal workflow accepts a workload and contract, analyzes necessary work, searches candidate pathways, executes and verifies a candidate, falls back when needed, and records evidence and measurements. The README also describes prediction, precision, reuse, and heterogeneous scheduling as capabilities. This map reflects the documented workflow and sampled orchestration; several subsystems are represented at their exact indexed paths because their implementations were not excerpted.

Main entry points: [`hyper_x/pipeline.py`](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pipeline.py) (HYPER-X pipeline), [`hyper_x/contract_ir/contract.py`](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/contract_ir/contract.py) (Contract IR), [`hyper/research_engine/master_pipeline.py`](https://github.com/sivabalajisleo/leo/blob/main/hyper/research_engine/master_pipeline.py) (Research pipeline), [`hyper_runtime/mvp_pipeline.py`](https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/mvp_pipeline.py) (Adaptive runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Contract workflow"]
  node_pipeline["HYPER-X pipeline<br/>[pipeline.py]"]
  node_contract["Contract IR<br/>[contract.py]"]
end

subgraph group_optimization["Work reduction"]
  node_boundary["Information boundary<br/>[engine.py]"]
  node_necessity["Necessary work<br/>[compiler.py]"]
  node_pathsearch["Pathway search<br/>[search_engine.py]"]
  node_reuse["Exact reuse<br/>[exact_reuse.py]"]
  node_representations["Representation search"]
  node_discovery["Algorithm discovery"]
  node_prediction["Prediction"]
  node_reconstruction["Reconstruction"]
  node_escape["Computational escape<br/>[escape_engine.py]"]
  node_mathadapter["Math adapter<br/>[math.py]"]
  node_residual["Residual computation<br/>[residual_engine.py]"]
end

subgraph group_verification["Verification and evidence"]
  node_verification["Candidate verifier<br/>[verifier.py]"]
  node_fallback["Fallback execution<br/>[engine.py]"]
  node_certificates["Execution certificates"]
  node_research["Research pipeline<br/>[master_pipeline.py]"]
  node_anti_cheat["Anti-cheat audit"]
end

subgraph group_runtime["Runtime and measurement"]
  node_avoidance["Work avoidance tracking"]
  node_local_compute["Local CPU and iGPU"]
  node_telemetry["Runtime telemetry"]
  node_hyper_runtime["Adaptive runtime<br/>[mvp_pipeline.py]"]
  node_cache[("Semantic replay cache<br/>[replay_cache.py]")]
  node_scheduling["CPU kernel scheduler"]
end

node_requester(("Workload user"))

node_requester -->|"submits workload"| node_pipeline
node_pipeline -->|"parses contract"| node_contract
node_pipeline -->|"analyzes workload"| node_boundary
node_pipeline -->|"builds work DAG"| node_necessity
node_pipeline -->|"evaluates representations"| node_representations
node_pipeline -->|"searches candidates"| node_pathsearch
node_pathsearch -->|"checks exact reuse"| node_reuse
node_pathsearch -->|"constrains candidates"| node_contract
node_pipeline -->|"uses discovery"| node_discovery
node_pipeline -->|"uses prediction"| node_prediction
node_pipeline -->|"uses reconstruction"| node_reconstruction
node_pipeline -->|"verifies candidate"| node_verification
node_pipeline -->|"runs fallback"| node_fallback
node_pipeline -.->|"schedules execution"| node_local_compute
node_pipeline -->|"records proof"| node_certificates
node_pipeline -.->|"tracks avoided work"| node_avoidance
node_pipeline -->|"records measurements"| node_telemetry
node_research -->|"loads workload contract"| node_contract
node_research -->|"uses discovery graph"| node_discovery
node_research -->|"audits claims"| node_anti_cheat
node_research -->|"runs reference workload"| node_local_compute
node_hyper_runtime -->|"checks replay"| node_cache
node_hyper_runtime -->|"dispatches kernels"| node_scheduling
node_hyper_runtime -->|"records runtime metrics"| node_telemetry
node_hyper_runtime -->|"executes workload"| node_local_compute
node_mathadapter -->|"executes matrix product"| node_local_compute
node_mathadapter -.->|"uses low-rank method"| node_escape
node_escape -->|"checks constraints"| node_contract
node_residual -->|"uses residual contract"| node_contract
node_verification -->|"rejects to fallback"| node_fallback

click node_pipeline "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pipeline.py"
click node_contract "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/contract_ir/contract.py"
click node_boundary "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/information_boundary/engine.py"
click node_necessity "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/necessity/compiler.py"
click node_pathsearch "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pathway_search/search_engine.py"
click node_reuse "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pathway_search/exact_reuse.py"
click node_representations "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/representations/representation_search.py"
click node_discovery "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/discovery/discovery_engine.py"
click node_prediction "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/prediction/prediction_engine.py"
click node_reconstruction "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/reconstruction/reconstruction_engine.py"
click node_escape "https://github.com/sivabalajisleo/leo/blob/main/hyper/escape/escape_engine.py"
click node_mathadapter "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/ahce/domains/math.py"
click node_verification "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/verification/verifier.py"
click node_fallback "https://github.com/sivabalajisleo/leo/blob/main/hyper_x/fallback/engine.py"
click node_certificates "https://github.com/sivabalajisleo/leo/blob/main/hyper/certificates/certificate_engine.py"
click node_research "https://github.com/sivabalajisleo/leo/blob/main/hyper/research_engine/master_pipeline.py"
click node_anti_cheat "https://github.com/sivabalajisleo/leo/blob/main/hyper/research_engine/anti_cheat_and_holdout.py"
click node_residual "https://github.com/sivabalajisleo/leo/blob/main/hyper_cco/residual_engine.py"
click node_avoidance "https://github.com/sivabalajisleo/leo/blob/main/backend/analytics/avoidance_tracker.py"
click node_telemetry "https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/benchmarking/telemetry_tracker.py"
click node_hyper_runtime "https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/mvp_pipeline.py"
click node_cache "https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/semantic_replay/replay_cache.py"
click node_scheduling "https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/cpu_orchestrator/kernel_scheduler.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_pipeline,node_contract,node_requester toneBlue
class node_boundary,node_necessity,node_pathsearch,node_reuse,node_representations,node_discovery,node_prediction,node_reconstruction,node_escape,node_mathadapter,node_residual toneAmber
class node_verification,node_fallback,node_certificates,node_research,node_anti_cheat toneMint
class node_avoidance,node_local_compute,node_telemetry,node_hyper_runtime,node_cache,node_scheduling toneRose
```

## Components

### Contract workflow

- [HYPER-X pipeline](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pipeline.py): `hyper_x/pipeline.py`
- [Contract IR](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/contract_ir/contract.py): `hyper_x/contract_ir/contract.py`

### Work reduction

- [Information boundary](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/information_boundary/engine.py): `hyper_x/information_boundary/engine.py`
- [Necessary work](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/necessity/compiler.py): `hyper_x/necessity/compiler.py`
- [Pathway search](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pathway_search/search_engine.py): `hyper_x/pathway_search/search_engine.py`
- [Exact reuse](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/pathway_search/exact_reuse.py): `hyper_x/pathway_search/exact_reuse.py`
- [Representation search](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/representations/representation_search.py): `hyper_x/representations/representation_search.py`
- [Algorithm discovery](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/discovery/discovery_engine.py): `hyper_x/discovery/discovery_engine.py`
- [Prediction](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/prediction/prediction_engine.py): `hyper_x/prediction/prediction_engine.py`
- [Reconstruction](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/reconstruction/reconstruction_engine.py): `hyper_x/reconstruction/reconstruction_engine.py`
- [Computational escape](https://github.com/sivabalajisleo/leo/blob/main/hyper/escape/escape_engine.py): `hyper/escape/escape_engine.py`
- [Math adapter](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/ahce/domains/math.py): `hyper_x/ahce/domains/math.py`
- [Residual computation](https://github.com/sivabalajisleo/leo/blob/main/hyper_cco/residual_engine.py): `hyper_cco/residual_engine.py`

### Verification and evidence

- [Candidate verifier](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/verification/verifier.py): `hyper_x/verification/verifier.py`
- [Fallback execution](https://github.com/sivabalajisleo/leo/blob/main/hyper_x/fallback/engine.py): `hyper_x/fallback/engine.py`
- [Execution certificates](https://github.com/sivabalajisleo/leo/blob/main/hyper/certificates/certificate_engine.py): `hyper/certificates/certificate_engine.py`
- [Research pipeline](https://github.com/sivabalajisleo/leo/blob/main/hyper/research_engine/master_pipeline.py): `hyper/research_engine/master_pipeline.py`
- [Anti-cheat audit](https://github.com/sivabalajisleo/leo/blob/main/hyper/research_engine/anti_cheat_and_holdout.py): `hyper/research_engine/anti_cheat_and_holdout.py`

### Runtime and measurement

- [Work avoidance tracking](https://github.com/sivabalajisleo/leo/blob/main/backend/analytics/avoidance_tracker.py): `backend/analytics/avoidance_tracker.py`
- **Local CPU and iGPU**
- [Runtime telemetry](https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/benchmarking/telemetry_tracker.py): `hyper_runtime/benchmarking/telemetry_tracker.py`
- [Adaptive runtime](https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/mvp_pipeline.py): `hyper_runtime/mvp_pipeline.py`
- [Semantic replay cache](https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/semantic_replay/replay_cache.py): `hyper_runtime/semantic_replay/replay_cache.py`
- [CPU kernel scheduler](https://github.com/sivabalajisleo/leo/blob/main/hyper_runtime/cpu_orchestrator/kernel_scheduler.py): `hyper_runtime/cpu_orchestrator/kernel_scheduler.py`

### Other components

- **Workload user**

## Connections

- Workload user → HYPER-X pipeline: submits workload (evidence: `README.md`)
- HYPER-X pipeline → Contract IR: parses contract (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Information boundary: analyzes workload (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Necessary work: builds work DAG (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Representation search: evaluates representations (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Pathway search: searches candidates (evidence: `hyper_x/pipeline.py`)
- Pathway search → Exact reuse: checks exact reuse (evidence: `hyper_x/pathway_search/search_engine.py`)
- Pathway search → Contract IR: constrains candidates (evidence: `hyper_x/pathway_search/search_engine.py`)
- HYPER-X pipeline → Algorithm discovery: uses discovery (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Prediction: uses prediction (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Reconstruction: uses reconstruction (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Candidate verifier: verifies candidate (evidence: `README.md`)
- HYPER-X pipeline → Fallback execution: runs fallback (evidence: `hyper_x/pipeline.py`)
- HYPER-X pipeline → Local CPU and iGPU: schedules execution
- HYPER-X pipeline → Execution certificates: records proof (evidence: `README.md`)
- HYPER-X pipeline → Work avoidance tracking: tracks avoided work
- HYPER-X pipeline → Runtime telemetry: records measurements (evidence: `README.md`)
- Research pipeline → Contract IR: loads workload contract (evidence: `hyper/research_engine/master_pipeline.py`)
- Research pipeline → Algorithm discovery: uses discovery graph (evidence: `hyper/research_engine/master_pipeline.py`)
- Research pipeline → Anti-cheat audit: audits claims (evidence: `hyper/research_engine/master_pipeline.py`)
- Research pipeline → Local CPU and iGPU: runs reference workload (evidence: `hyper/research_engine/master_pipeline.py`)
- Adaptive runtime → Semantic replay cache: checks replay (evidence: `hyper_runtime/mvp_pipeline.py`)
- Adaptive runtime → CPU kernel scheduler: dispatches kernels (evidence: `hyper_runtime/mvp_pipeline.py`)
- Adaptive runtime → Runtime telemetry: records runtime metrics (evidence: `hyper_runtime/mvp_pipeline.py`)
- Adaptive runtime → Local CPU and iGPU: executes workload (evidence: `hyper_runtime/mvp_pipeline.py`)
- Math adapter → Local CPU and iGPU: executes matrix product (evidence: `hyper_x/ahce/domains/math.py`)
- Math adapter → Computational escape: uses low-rank method
- Computational escape → Contract IR: checks constraints (evidence: `hyper/escape/escape_engine.py`)
- Residual computation → Contract IR: uses residual contract (evidence: `hyper_cco/residual_engine.py`)
- Candidate verifier → Fallback execution: rejects to fallback (evidence: `hyper_x/pipeline.py`)
