config-skills

LlamaFarm 配置技能

针对 LlamaFarm 配置模块（config/）的专用模式和最佳实践。

模块概览

配置模块提供 YAML/TOML/JSON 配置加载，并支持 JSONSchema 验证：

文件	用途
datamodel.py	根据 JSONSchema 生成的 Pydantic v2 模型
schema.yaml	使用 $ref 引用的源 JSONSchema
compile_schema.py	取消 $ref 引用，以创建 schema.deref.yaml
generate_types.py	通过 datamodel-codegen 生成 Python 类型
validators.py	JSONSchema 能力之外的自定义验证器
helpers/loader.py	配置加载、保存和格式检测
helpers/generator.py	基于模板生成配置

共享技能链接

此模块遵循共享技能中的 Python 约定：

主题	链接	主要相关内容
模式	python-skills/patterns.md	Pydantic v2、数据类
类型标注	python-skills/typing.md	类型提示、受限类型
测试	python-skills/testing.md	Pytest 夹具、临时文件
错误	python-skills/error-handling.md	自定义异常
安全	python-skills/security.md	防止路径遍历

框架专属检查清单

检查清单	描述
pydantic.md	Pydantic v2 配置模式、嵌套模型、约束
jsonschema.md	JSONSchema 生成、取消引用、验证

技术栈

• Python：3.11+
• Pydantic：v2，使用 ConfigDict、Field 和受限类型
• JSONSchema：Draft-07，通过 jsonref 取消 $ref 引用
• YAML：使用 ruamel.yaml 保留注释地读写
• 代码生成：使用 datamodel-codegen 将 schema 转为 Pydantic

关键模式

生成的 Pydantic 模型

datamodel.py 文件由 JSONSchema 自动生成：

# 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")

用于跨字段约束的自定义验证器

JSONSchema draft-07 无法表达所有约束。自定义验证器可扩展验证能力：

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))}")

使用 ruamel.yaml 保留注释

修改配置文件时会保留用户注释：

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

工作流：Schema 变更

修改配置 schema 时：

1. 编辑 schema.yaml（或被引用的 schema，例如 ../rag/schema.yaml）
2. 运行 nx run generate-types 以编译并生成类型
3. 如果需要新的跨字段约束，更新 validators.py
4. 使用 uv run pytest config/tests/ 测试

常用命令

# 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/