config-skills

The config module provides YAML/TOML/JSON configuration loading with JSONSchema validation:

| File | Purpose |

|------|---------|

| datamodel.py | Generated Pydantic v2 models from JSONSchema |

| schema.yaml | Source JSONSchema with $ref references |

| compile_schema.py | Dereferences $ref to create schema.deref.yaml |

| generate_types.py | Generates Python types via datamodel-codegen |

| validators.py | Custom validators beyond JSONSchema capabilities |

| helpers/loader.py | Config loading, saving, and format detection |

| helpers/generator.py | Template-based config generation |

This module follows Python conventions from the shared skills:

| Topic | Link | Key Relevance |

|-------|------|---------------|

| Patterns | [python-skills/patterns.md](../python-skills/patterns.md) | Pydantic v2, dataclasses |

| Typing | [python-skills/typing.md](../python-skills/typing.md) | Type hints, constrained types |

| Testing | [python-skills/testing.md](../python-skills/testing.md) | Pytest fixtures, temp files |

| Errors | [python-skills/error-handling.md](../python-skills/error-handling.md) | Custom exceptions |

| Security | [python-skills/security.md](../python-skills/security.md) | Path traversal prevention |

| Checklist | Description |

|-----------|-------------|

| [pydantic.md](pydantic.md) | Pydantic v2 configuration patterns, nested models, constraints |

| [jsonschema.md](jsonschema.md) | JSONSchema generation, dereferencing, validation |

• Python: 3.11+
• Pydantic: v2 with ConfigDict, Field, constrained types
• JSONSchema: Draft-07 with $ref dereferencing via jsonref
• YAML: ruamel.yaml for comment-preserving read/write
• Code Generation: datamodel-codegen for schema-to-Pydantic

Generated Pydantic Models

The datamodel.py file is auto-generated from JSONSchema:

```python

# Generated by datamodel-codegen from schema.deref.yaml

from pydantic import BaseModel, ConfigDict, Field, conint, constr

class Database(BaseModel):

model_config = ConfigDict(extra="forbid")

name: constr(pattern=r"^[a-z][a-z0-9_]*$", min_length=1, max_length=50)

type: Type

config: dict[str, Any] | None = Field(None, description="Database-specific configuration")

```

Custom Validators for Cross-Field Constraints

JSONSchema draft-07 cannot express all constraints. Custom validators extend validation:

```python

def validate_llamafarm_config(config_dict: dict[str, Any]) -> None:

"""Validate constraints beyond JSONSchema (uniqueness, references)."""

# Check for duplicate prompt names

prompt_names = [p.get("name") for p in config_dict.get("prompts", [])]

duplicates = [name for name in prompt_names if prompt_names.count(name) > 1]

if duplicates:

raise ValueError(f"Duplicate prompt set names: {', '.join(set(duplicates))}")

```

Comment-Preserving YAML with ruamel.yaml

Configuration files preserve user comments when modified:

```python

from ruamel.yaml import YAML

from ruamel.yaml.comments import CommentedMap

def _get_ruamel_yaml() -> YAML:

yaml_instance = YAML()

yaml_instance.preserve_quotes = True

yaml_instance.indent(mapping=2, sequence=4, offset=2)

return yaml_instance

```

```

config/

├── pyproject.toml # UV-managed dependencies

├── schema.yaml # Source JSONSchema with $ref

├── schema.deref.yaml # Dereferenced schema (generated)

├── datamodel.py # Pydantic models (generated)

├── compile_schema.py # Schema compilation script

├── generate_types.py # Type generation script

├── validators.py # Custom validation beyond JSONSchema

├── validate_config.py # CLI validation wrapper

├── __init__.py # Public API exports

├── helpers/

│ ├── loader.py # Config loading/saving

│ └── generator.py # Template-based generation

├── templates/

│ └── default.yaml # Default config template

└── tests/

├── conftest.py # Shared fixtures

└── test_*.py # Test modules

```

When modifying the configuration schema:

1. Edit schema.yaml (or referenced schemas like ../rag/schema.yaml)
2. Run nx run generate-types to compile and generate types
3. Update validators.py if new cross-field constraints are needed
4. Test with uv run pytest config/tests/

```bash

# Generate types from schema

nx run generate-types

# Validate a config file

uv run python config/validate_config.py path/to/llamafarm.yaml --verbose

# Run tests

uv run pytest config/tests/ -v

# Lint and format

ruff check config/ --fix

ruff format config/

```