# vizuaraai/capstone-gemma-4-local architecture

> Architecture diagram of the GitHub repository vizuaraai/capstone-gemma-4-local, 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/vizuaraai/capstone-gemma-4-local
- Repository: https://github.com/vizuaraai/capstone-gemma-4-local

## Overview

Gemma 4, fully local is a reproducible model-download, quantization, and benchmarking project. The main workflow takes a user-selected registry variant through download and rung building, then runs generation on MLX or llama.cpp and records measured timings with a validated environment envelope. Analysis turns results into latency, privacy, and cost findings and optional charts. The graph preserves documented measurement branches and export recipes; connections for unsampled modules rely on the README, and do not imply their implementation was inspected.

Main entry points: [`harness/bench.py`](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/bench.py) (Benchmark runner), [`quantize/ladder.py`](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/ladder.py) (Rung builder), [`harness/references.py`](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/references.py) (Published references), [`harness/memory.py`](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/memory.py) (Memory sampling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model_prep["Model preparation"]
  node_registry["Variant registry<br/>[registry.yaml]"]
  node_downloader["Model downloader<br/>[download.py]"]
  node_checkpoint["HF checkpoint"]
end

subgraph group_quantization["Quantization"]
  node_ladder["Rung builder<br/>[ladder.py]"]
  node_mlx_convert["MLX conversion<br/>[mlx_convert.py]"]
  node_gguf_convert["GGUF conversion<br/>[gguf_convert.py]"]
  node_awq["AWQ export<br/>[awq_export.py]"]
  node_gptq["GPTQ export<br/>[gptq_export.py]"]
  node_fp8["FP8 note<br/>[fp8_note.md]"]
  node_built_model["Built model"]
end

subgraph group_benchmarking["Benchmarking"]
  node_bench["Benchmark runner<br/>[bench.py]"]
  node_runtime_base["Runtime contract<br/>[base.py]"]
  node_mlx_runtime["MLX runtime<br/>[mlx_runtime.py]"]
  node_llama_runtime["llama.cpp runtime"]
  node_memory["Memory sampling<br/>[memory.py]"]
  node_power["Power sampling<br/>[power.py]"]
  node_concurrency["Concurrency test<br/>[concurrency.py]"]
  node_roofline["Roofline estimate<br/>[roofline.py]"]
  node_cost["Cost crossover<br/>[cost.py]"]
  node_references["Published references<br/>[references.py]"]
  node_report["Report writer<br/>[report.py]"]
  node_results[("Benchmark results")]
end

subgraph group_analysis["Analysis"]
  node_verdict["Local verdict<br/>[when_local_wins.py]"]
  node_plots["Result charts<br/>[plots.py]"]
end

node_user(("User"))

node_user -->|"selects variant"| node_registry
node_user -->|"starts download"| node_downloader
node_registry -->|"provides variant"| node_downloader
node_downloader -->|"downloads weights"| node_checkpoint
node_user -->|"chooses rungs"| node_ladder
node_ladder -->|"calls conversion"| node_mlx_convert
node_ladder -->|"calls conversion"| node_gguf_convert
node_checkpoint -->|"supplies source"| node_ladder
node_mlx_convert -->|"builds MLX model"| node_built_model
node_gguf_convert -->|"builds GGUF model"| node_built_model
node_user -->|"runs export"| node_awq
node_user -->|"runs export"| node_gptq
node_user -->|"consults rung note"| node_fp8
node_user -->|"starts benchmark"| node_bench
node_built_model -->|"loads for run"| node_bench
node_bench -->|"dispatches generation"| node_mlx_runtime
node_bench -->|"dispatches generation"| node_llama_runtime
node_mlx_runtime -->|"implements contract"| node_runtime_base
node_llama_runtime -->|"implements contract"| node_runtime_base
node_bench -->|"samples memory"| node_memory
node_bench -->|"samples power"| node_power
node_bench -->|"tests concurrency"| node_concurrency
node_bench -->|"attaches ceiling"| node_roofline
node_bench -->|"attaches crossover"| node_cost
node_bench -->|"writes report"| node_report
node_memory -->|"reads constants"| node_references
node_memory -->|"uses calculations"| node_roofline
node_concurrency -->|"uses runtime contract"| node_runtime_base
node_cost -->|"reads price table"| node_references
node_roofline -->|"reads constants"| node_references
node_report -->|"reads chip facts"| node_references
node_report -->|"writes JSON"| node_results
node_results -->|"feeds analysis"| node_verdict
node_results -->|"feeds charts"| node_plots
node_user -->|"requests verdict"| node_verdict
node_user -->|"requests charts"| node_plots

click node_registry "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/models/registry.yaml"
click node_downloader "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/models/download.py"
click node_ladder "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/ladder.py"
click node_mlx_convert "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/mlx_convert.py"
click node_gguf_convert "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/gguf_convert.py"
click node_awq "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/awq_export.py"
click node_gptq "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/gptq_export.py"
click node_fp8 "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/fp8_note.md"
click node_bench "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/bench.py"
click node_runtime_base "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/base.py"
click node_mlx_runtime "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/mlx_runtime.py"
click node_llama_runtime "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/llamacpp_runtime.py"
click node_memory "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/memory.py"
click node_power "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/power.py"
click node_concurrency "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/concurrency.py"
click node_roofline "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/roofline.py"
click node_cost "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/cost.py"
click node_references "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/references.py"
click node_report "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/report.py"
click node_results "https://github.com/vizuaraai/capstone-gemma-4-local/tree/main/results"
click node_verdict "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/analysis/when_local_wins.py"
click node_plots "https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/analysis/plots.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_registry,node_downloader,node_checkpoint,node_user toneBlue
class node_ladder,node_mlx_convert,node_gguf_convert,node_awq,node_gptq,node_fp8,node_built_model toneAmber
class node_bench,node_runtime_base,node_mlx_runtime,node_llama_runtime,node_memory,node_power,node_concurrency,node_roofline,node_cost,node_references,node_report,node_results toneMint
class node_verdict,node_plots toneRose
```

## Components

### Model preparation

- [Variant registry](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/models/registry.yaml): `models/registry.yaml`
- [Model downloader](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/models/download.py): `models/download.py`
- **HF checkpoint**

### Quantization

- [Rung builder](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/ladder.py): `quantize/ladder.py`
- [MLX conversion](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/mlx_convert.py): `quantize/mlx_convert.py`
- [GGUF conversion](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/gguf_convert.py): `quantize/gguf_convert.py`
- [AWQ export](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/awq_export.py): `quantize/awq_export.py`
- [GPTQ export](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/gptq_export.py): `quantize/gptq_export.py`
- [FP8 note](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/quantize/fp8_note.md): `quantize/fp8_note.md`
- **Built model**

### Benchmarking

- [Benchmark runner](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/bench.py): `harness/bench.py`
- [Runtime contract](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/base.py): `harness/runtimes/base.py`
- [MLX runtime](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/mlx_runtime.py): `harness/runtimes/mlx_runtime.py`
- [llama.cpp runtime](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/runtimes/llamacpp_runtime.py): `harness/runtimes/llamacpp_runtime.py`
- [Memory sampling](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/memory.py): `harness/memory.py`
- [Power sampling](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/power.py): `harness/power.py`
- [Concurrency test](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/concurrency.py): `harness/concurrency.py`
- [Roofline estimate](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/roofline.py): `harness/roofline.py`
- [Cost crossover](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/cost.py): `harness/cost.py`
- [Published references](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/references.py): `harness/references.py`
- [Report writer](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/harness/report.py): `harness/report.py`
- [Benchmark results](https://github.com/vizuaraai/capstone-gemma-4-local/tree/main/results): `results`

### Analysis

- [Local verdict](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/analysis/when_local_wins.py): `analysis/when_local_wins.py`
- [Result charts](https://github.com/vizuaraai/capstone-gemma-4-local/blob/main/analysis/plots.py): `analysis/plots.py`

### Other components

- **User**

## Connections

- User → Variant registry: selects variant (evidence: `README.md`)
- User → Model downloader: starts download (evidence: `README.md`)
- Variant registry → Model downloader: provides variant (evidence: `models/download.py`)
- Model downloader → HF checkpoint: downloads weights (evidence: `models/download.py`)
- User → Rung builder: chooses rungs (evidence: `README.md`)
- Rung builder → MLX conversion: calls conversion (evidence: `quantize/ladder.py`)
- Rung builder → GGUF conversion: calls conversion (evidence: `quantize/ladder.py`)
- HF checkpoint → Rung builder: supplies source (evidence: `README.md`)
- MLX conversion → Built model: builds MLX model (evidence: `README.md`)
- GGUF conversion → Built model: builds GGUF model (evidence: `README.md`)
- User → AWQ export: runs export (evidence: `README.md`)
- User → GPTQ export: runs export (evidence: `README.md`)
- User → FP8 note: consults rung note (evidence: `README.md`)
- User → Benchmark runner: starts benchmark (evidence: `README.md`)
- Built model → Benchmark runner: loads for run (evidence: `README.md`)
- Benchmark runner → MLX runtime: dispatches generation (evidence: `README.md`)
- Benchmark runner → llama.cpp runtime: dispatches generation (evidence: `README.md`)
- MLX runtime → Runtime contract: implements contract (evidence: `harness/runtimes/mlx_runtime.py`)
- llama.cpp runtime → Runtime contract: implements contract (evidence: `harness/runtimes/llamacpp_runtime.py`)
- Benchmark runner → Memory sampling: samples memory (evidence: `README.md`)
- Benchmark runner → Power sampling: samples power (evidence: `README.md`)
- Benchmark runner → Concurrency test: tests concurrency (evidence: `README.md`)
- Benchmark runner → Roofline estimate: attaches ceiling (evidence: `README.md`)
- Benchmark runner → Cost crossover: attaches crossover (evidence: `README.md`)
- Benchmark runner → Report writer: writes report (evidence: `README.md`)
- Memory sampling → Published references: reads constants (evidence: `harness/memory.py`)
- Memory sampling → Roofline estimate: uses calculations (evidence: `harness/memory.py`)
- Concurrency test → Runtime contract: uses runtime contract (evidence: `harness/concurrency.py`)
- Cost crossover → Published references: reads price table (evidence: `harness/cost.py`)
- Roofline estimate → Published references: reads constants (evidence: `harness/roofline.py`)
- Report writer → Published references: reads chip facts (evidence: `harness/report.py`)
- Report writer → Benchmark results: writes JSON (evidence: `README.md`)
- Benchmark results → Local verdict: feeds analysis (evidence: `README.md`)
- Benchmark results → Result charts: feeds charts (evidence: `README.md`)
- User → Local verdict: requests verdict (evidence: `README.md`)
- User → Result charts: requests charts (evidence: `README.md`)
