llama-cpp-server/docs/superpowers/plans/2026-06-10-gguf-metadata-preset-generation.md

GGUF Metadata Preset Generation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make generate_models_preset.py derive richer models-preset.ini values from GGUF metadata only, annotate key numeric values with min/max comments, and stop defaulting to backup creation.

Architecture: Keep the work inside generate_models_preset.py. Tighten model classification to metadata-backed signals only, add explicit value-selection helpers for model-specific fields, and extend INI rendering so key numeric values are preceded by compact range comments. Cover the new behavior with focused unit tests.

Tech Stack: Python 3, unittest, existing preset generator script

---

Task 1: Lock expected behavior with tests

Files:

• Create: tests/test_generate_models_preset.py

• Modify: generate_models_preset.py

• [ ] Step 1: Write failing tests

  class ClassificationTests(unittest.TestCase):
  def test_moe_detection_uses_metadata_not_filename(self):
      ...
  
  class PresetValueTests(unittest.TestCase):
  def test_moe_values_include_cache_types_and_ncmoe(self):
      ...
  

• [ ] Step 2: Run test to verify it fails

Run: python -m unittest tests.test_generate_models_preset -v Expected: FAIL because the new tests assert metadata-only behavior and richer field output that the current implementation does not provide.

• [ ] Step 3: Write minimal implementation

  def classify_model_family(entry: ModelEntry) -> str:
  ...
  

• [ ] Step 4: Run test to verify it passes

Run: python -m unittest tests.test_generate_models_preset -v Expected: PASS

Task 2: Extend preset rendering and CLI defaults

Files:

• Modify: generate_models_preset.py

• Test: tests/test_generate_models_preset.py

• [ ] Step 1: Write failing tests

  def test_render_ini_emits_range_comments_for_numeric_values(self):
  ...
  
  def test_parser_disables_backup_by_default(self):
  ...
  

• [ ] Step 2: Run test to verify it fails

Run: python -m unittest tests.test_generate_models_preset -v Expected: FAIL because current output omits the new comments and currently enables backup by default.

• [ ] Step 3: Write minimal implementation

  def build_value_comments(...):
  ...
  

• [ ] Step 4: Run test to verify it passes

Run: python -m unittest tests.test_generate_models_preset -v Expected: PASS

Task 3: Verify against generated preset output

Files:

• Modify if needed: generate_models_preset.py

• [ ] Step 1: Generate a fresh preset

Run: python generate_models_preset.py --models-dir "<models-dir>" --output "models-preset.generated.ini" --select all --profile smart --alias-style section Expected: command succeeds and writes a preset with richer model-specific fields and range comments.

• Step 2: Inspect one MoE section

Look for:

; ctx-size range = ...
; n-gpu-layers range = ...
; n-cpu-moe range = ...
cache-type-k = q8_0
cache-type-v = q8_0

• [ ] Step 3: Adjust implementation only if the generated output contradicts the tests

  # Keep changes inside the preset heuristics helpers and comment rendering.