How vizuaraai/capstone-gemma-4-local works
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: bench.py Benchmark runner · ladder.py Rung builder · references.py Published references · memory.py Memory sampling
Components 25
Model preparation
- Variant registry
models/registry.yaml - Model downloader
models/download.py - HF checkpoint
Quantization
- Rung builder
quantize/ladder.py - MLX conversion
quantize/mlx_convert.py - GGUF conversion
quantize/gguf_convert.py - AWQ export
quantize/awq_export.py - GPTQ export
quantize/gptq_export.py - FP8 note
quantize/fp8_note.md - Built model
Benchmarking
- Benchmark runner
harness/bench.py - Runtime contract
harness/runtimes/base.py - MLX runtime
harness/runtimes/mlx_runtime.py - llama.cpp runtime
harness/runtimes/llamacpp_runtime.py - Memory sampling
harness/memory.py - Power sampling
harness/power.py - Concurrency test
harness/concurrency.py - Roofline estimate
harness/roofline.py - Cost crossover
harness/cost.py - Published references
harness/references.py - Report writer
harness/report.py - Benchmark results
results
Analysis
- Local verdict
analysis/when_local_wins.py - Result charts
analysis/plots.py
Other components
- User
Connections 36
- User → Variant registry: selects variant
README.md - User → Model downloader: starts download
README.md - Variant registry → Model downloader: provides variant
models/download.py - Model downloader → HF checkpoint: downloads weights
models/download.py - User → Rung builder: chooses rungs
README.md - Rung builder → MLX conversion: calls conversion
quantize/ladder.py - Rung builder → GGUF conversion: calls conversion
quantize/ladder.py - HF checkpoint → Rung builder: supplies source
README.md - MLX conversion → Built model: builds MLX model
README.md - GGUF conversion → Built model: builds GGUF model
README.md - User → AWQ export: runs export
README.md - User → GPTQ export: runs export
README.md - User → FP8 note: consults rung note
README.md - User → Benchmark runner: starts benchmark
README.md - Built model → Benchmark runner: loads for run
README.md - Benchmark runner → MLX runtime: dispatches generation
README.md - Benchmark runner → llama.cpp runtime: dispatches generation
README.md - MLX runtime → Runtime contract: implements contract
harness/runtimes/mlx_runtime.py - llama.cpp runtime → Runtime contract: implements contract
harness/runtimes/llamacpp_runtime.py - Benchmark runner → Memory sampling: samples memory
README.md - Benchmark runner → Power sampling: samples power
README.md - Benchmark runner → Concurrency test: tests concurrency
README.md - Benchmark runner → Roofline estimate: attaches ceiling
README.md - Benchmark runner → Cost crossover: attaches crossover
README.md - Benchmark runner → Report writer: writes report
README.md - Memory sampling → Published references: reads constants
harness/memory.py - Memory sampling → Roofline estimate: uses calculations
harness/memory.py - Concurrency test → Runtime contract: uses runtime contract
harness/concurrency.py - Cost crossover → Published references: reads price table
harness/cost.py - Roofline estimate → Published references: reads constants
harness/roofline.py - Report writer → Published references: reads chip facts
harness/report.py - Report writer → Benchmark results: writes JSON
README.md - Benchmark results → Local verdict: feeds analysis
README.md - Benchmark results → Result charts: feeds charts
README.md - User → Local verdict: requests verdict
README.md - User → Result charts: requests charts
README.md