llama-farm/llamafarm / .claude/skills/config-skills
config-skills
VerifiedConfiguration module patterns for LlamaFarm. Covers Pydantic v2 models, JSONSchema generation, YAML processing, and validation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| jsonschema.md | markdown | 12.6 KB |
| pydantic.md | markdown | 11.3 KB |
SKILL.md
View on GitHub---
name: config-skills
description: Configuration module patterns for LlamaFarm. Covers Pydantic v2 models, JSONSchema generation, YAML processing, and validation.
allowed-tools: Read, Grep, Glob
user-invocable: false
---
# Config Skills for LlamaFarm
Specialized patterns and best practices for the LlamaFarm configuration module (`config/`).
## Module Overview
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 |
## Links to Shared Skills
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 |
## Framework-Specific Checklists
| Checklist | Description |
|-----------|-------------|
| [pydantic.md](pydantic.md) | Pydantic v2 configuration patterns, nested models, constraints |
| [jsonschema.md](jsonschema.md) | JSONSchema generation, dereferencing, validation |
## Tech Stack
- **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
## Key Patterns
### 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
```
## Directory Structure
```
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
```
## Workflow: Schema Changes
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/`
## Common Commands
```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/
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |