Skip to content

CLAUDE.md

Latest commit

 

History

History
43 lines (31 loc) · 1.77 KB

CLAUDE.md

File metadata and controls

43 lines (31 loc) · 1.77 KB

CLAUDE.md

Repository Overview

Herd is a model registry and lifecycle manager for local GGUF models served via llama-swap. The models/ directory is the source of truth for all model metadata. manage.py is the unified CLI (installed as herd via pip).

Architecture

models/ Directory — Source of Truth

Model metadata is split across per-category YAML files. Config resolution cascades: global defaults → category defaults → per-model overrides.

  • _defaults.yaml — Global config (base_path, server, defaults, aliases)
  • {category}.yaml — Flat dict of models (category inferred from filename)
  • Files prefixed with _ are config, not category files

Module Architecture

Module Purpose
lib/registry.py Loads models/ directory, resolves cascading defaults, filtering
lib/builder.py Generates llama-swap config.yaml from resolved registry
lib/status.py Checks registry against disk state, validates
lib/mutator.py Add/enable/disable models in registry YAML files
lib/downloader.py Generates HF download commands
lib/hf.py HuggingFace API, model type detection, special flag detection

Development Commands

python3 -m pytest tests/ -v          # Run tests
python3 manage.py build              # Generate config
python3 manage.py status             # Check model status
python3 manage.py add                # Add model interactively
python3 manage.py validate           # Validate registry

Key Conventions

  • Model paths are relative to base_path: {category}/{model-dir}/{filename.gguf}
  • Flags merge by default; use flags_override to replace
  • Auto-detection patterns live in MODEL_PATTERNS in lib/hf.py
  • system_prompt field stores the model creator's recommended system prompt