# mikamika06/mlsys-lab architecture

> Architecture diagram of the GitHub repository mikamika06/mlsys-lab, 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/mikamika06/mlsys-lab
- Repository: https://github.com/mikamika06/mlsys-lab

## Overview

mlsys-lab is an offline, auto-graded low-level ML systems learning platform. Learners choose a task or multi-file project, copy its starter into a work directory, run it, and submit it for deterministic grading against computed oracles and metric gates. The bank spans Python, C++, CUDA, quantization, inference, memory, and performance topics; a VS Code extension is also documented. The supplied tree and excerpts omit the main package implementation, so CLI, grader, and simulator internals are not mapped; documented workflow links are cited to the README.

Main entry points: [`projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py`](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py) (Hybrid KV cache), [`projects/p-ngram-prompt-lookup/reference/ngram/engine.py`](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-ngram-prompt-lookup/reference/ngram/engine.py) (N-gram lookup), [`projects/m-implement-vllm-s-prefix-block-hashing-scheme/reference/prefix_cache/cache_engine.py`](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-implement-vllm-s-prefix-block-hashing-scheme/reference/prefix_cache/cache_engine.py) (Prefix hashing), [`projects/p-structured-output-contract-breaks/reference/runner/engine.py`](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-structured-output-contract-breaks/reference/runner/engine.py) (Constrained output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning bank"]
  node_taskbank["Task bank"]
  node_projectbank["Project bank"]
  node_starter["Project starter<br/>[cache.py]"]
  node_run["Run task"]
  node_grade["Grade submission"]
  node_oracle["Computed oracle"]
  node_gates["Metric gates"]
end

subgraph group_inference["Inference projects"]
  node_simulator["Batching simulator"]
  node_hybrid["Hybrid KV cache<br/>[cache.py]"]
  node_cacheconfig["Cache configuration<br/>[config.py]"]
  node_ngram["N-gram lookup<br/>[engine.py]"]
  node_prefix["Prefix hashing<br/>[cache_engine.py]"]
  node_structured["Constrained output<br/>[engine.py]"]
  node_grammar["JSON grammar<br/>[grammar.py]"]
end

subgraph group_analysis["Systems analysis"]
  node_quant["Quantization parity<br/>[pipeline.py]"]
  node_opset["Opset validation<br/>[opset.py]"]
  node_layout["Layout analysis<br/>[pipeline.py]"]
  node_layoutops["Layout transforms<br/>[layout.py]"]
end

subgraph group_editor["Editor integration"]
  node_extension["VS Code extension<br/>[extension.js]"]
end

node_learner(("Learner"))

node_learner -->|"chooses task"| node_taskbank
node_learner -->|"chooses project"| node_projectbank
node_projectbank -.->|"provides starter"| node_starter
node_learner -->|"runs work"| node_run
node_learner -->|"submits work"| node_grade
node_run -->|"grades separately"| node_grade
node_grade -->|"computes reference"| node_oracle
node_grade -->|"checks metrics"| node_gates
node_simulator -.->|"models KV cache"| node_hybrid
node_hybrid -->|"uses configuration"| node_cacheconfig
node_ngram -.->|"represents feature"| node_taskbank
node_prefix -.->|"represents feature"| node_taskbank
node_structured -->|"applies mask"| node_grammar
node_quant -->|"validates opset"| node_opset
node_layout -->|"converts layout"| node_layoutops
node_learner -->|"opens workspace"| node_extension

click node_starter "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py"
click node_hybrid "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py"
click node_cacheconfig "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/config.py"
click node_ngram "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-ngram-prompt-lookup/reference/ngram/engine.py"
click node_prefix "https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-implement-vllm-s-prefix-block-hashing-scheme/reference/prefix_cache/cache_engine.py"
click node_structured "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-structured-output-contract-breaks/reference/runner/engine.py"
click node_grammar "https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-structured-output-contract-breaks/skeleton/runner/grammar.py"
click node_quant "https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/reference/quantizer/pipeline.py"
click node_opset "https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/skeleton/quantizer/opset.py"
click node_layout "https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-transpose-overhead-from-layout-mismatch/reference/edgeio/pipeline.py"
click node_layoutops "https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-transpose-overhead-from-layout-mismatch/skeleton/edgeio/layout.py"
click node_extension "https://github.com/mikamika06/mlsys-lab/blob/main/editor/extension.js"

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_taskbank,node_projectbank,node_starter,node_run,node_grade,node_oracle,node_gates toneBlue
class node_simulator,node_hybrid,node_cacheconfig,node_ngram,node_prefix,node_structured,node_grammar toneAmber
class node_quant,node_opset,node_layout,node_layoutops toneMint
class node_extension toneRose
class node_learner toneIndigo
```

## Components

### Learning bank

- **Task bank**
- **Project bank**
- [Project starter](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py): `projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py`
- **Run task**
- **Grade submission**
- **Computed oracle**
- **Metric gates**

### Inference projects

- **Batching simulator**
- [Hybrid KV cache](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py): `projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py`
- [Cache configuration](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-hybrid-sliding-window-cache/skeleton/kvcache/config.py): `projects/p-hybrid-sliding-window-cache/skeleton/kvcache/config.py`
- [N-gram lookup](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-ngram-prompt-lookup/reference/ngram/engine.py): `projects/p-ngram-prompt-lookup/reference/ngram/engine.py`
- [Prefix hashing](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-implement-vllm-s-prefix-block-hashing-scheme/reference/prefix_cache/cache_engine.py): `projects/m-implement-vllm-s-prefix-block-hashing-scheme/reference/prefix_cache/cache_engine.py`
- [Constrained output](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-structured-output-contract-breaks/reference/runner/engine.py): `projects/p-structured-output-contract-breaks/reference/runner/engine.py`
- [JSON grammar](https://github.com/mikamika06/mlsys-lab/blob/main/projects/p-structured-output-contract-breaks/skeleton/runner/grammar.py): `projects/p-structured-output-contract-breaks/skeleton/runner/grammar.py`

### Systems analysis

- [Quantization parity](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/reference/quantizer/pipeline.py): `projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/reference/quantizer/pipeline.py`
- [Opset validation](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/skeleton/quantizer/opset.py): `projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/skeleton/quantizer/opset.py`
- [Layout analysis](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-transpose-overhead-from-layout-mismatch/reference/edgeio/pipeline.py): `projects/m-transpose-overhead-from-layout-mismatch/reference/edgeio/pipeline.py`
- [Layout transforms](https://github.com/mikamika06/mlsys-lab/blob/main/projects/m-transpose-overhead-from-layout-mismatch/skeleton/edgeio/layout.py): `projects/m-transpose-overhead-from-layout-mismatch/skeleton/edgeio/layout.py`

### Editor integration

- [VS Code extension](https://github.com/mikamika06/mlsys-lab/blob/main/editor/extension.js): `editor/extension.js`

### Other components

- **Learner**

## Connections

- Learner → Task bank: chooses task (evidence: `README.md`)
- Learner → Project bank: chooses project (evidence: `README.md`)
- Project bank → Project starter: provides starter
- Learner → Run task: runs work (evidence: `README.md`)
- Learner → Grade submission: submits work (evidence: `README.md`)
- Run task → Grade submission: grades separately (evidence: `README.md`)
- Grade submission → Computed oracle: computes reference (evidence: `README.md`)
- Grade submission → Metric gates: checks metrics (evidence: `README.md`)
- Batching simulator → Hybrid KV cache: models KV cache
- Hybrid KV cache → Cache configuration: uses configuration (evidence: `projects/p-hybrid-sliding-window-cache/skeleton/kvcache/cache.py`)
- N-gram lookup → Task bank: represents feature
- Prefix hashing → Task bank: represents feature
- Constrained output → JSON grammar: applies mask (evidence: `projects/p-structured-output-contract-breaks/reference/runner/engine.py`)
- Quantization parity → Opset validation: validates opset (evidence: `projects/m-ovquantizer-one-shot-vs-manual-nncf-quantize-output-/reference/quantizer/pipeline.py`)
- Layout analysis → Layout transforms: converts layout (evidence: `projects/m-transpose-overhead-from-layout-mismatch/reference/edgeio/pipeline.py`)
- Learner → VS Code extension: opens workspace (evidence: `README.md`)
