config-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Config Skills for LlamaFarm

LlamaFarm配置技能指南

Specialized patterns and best practices for the LlamaFarm configuration module (

config/

LlamaFarm配置模块（

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

配置模块提供带有JSONSchema验证的YAML/TOML/JSON配置加载功能：

文件	用途
`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`	基于模板的配置生成

Links to Shared Skills

关联通用技能

This module follows Python conventions from the shared skills:

Topic	Link	Key Relevance
Patterns	python-skills/patterns.md	Pydantic v2, dataclasses
Typing	python-skills/typing.md	Type hints, constrained types
Testing	python-skills/testing.md	Pytest fixtures, temp files
Errors	python-skills/error-handling.md	Custom exceptions
Security	python-skills/security.md	Path traversal prevention

本模块遵循通用技能中的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	路径遍历防护

Framework-Specific Checklists

框架专属检查清单

Checklist	Description
pydantic.md	Pydantic v2 configuration patterns, nested models, constraints
jsonschema.md	JSONSchema generation, dereferencing, validation

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

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

Python: 3.11+
Pydantic: v2（含
```
ConfigDict
```
、
```
Field
```
、约束类型）
JSONSchema: Draft-07，通过
```
jsonref
```
解析
```
$ref
```
YAML: 使用
```
ruamel.yaml
```
实现保留注释的读写
代码生成: 通过
```
datamodel-codegen
```
实现从Schema到Pydantic的转换

Key Patterns

核心模式

Generated Pydantic Models

自动生成的Pydantic模型

The

datamodel.py

file is auto-generated from JSONSchema:

python

undefined

datamodel.py

文件由JSONSchema自动生成：

python

undefined

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

undefined

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

undefined

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

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

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

使用ruamel.yaml保留注释的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

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

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

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

工作流：Schema变更

When modifying the configuration schema:

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

修改配置Schema时：

编辑
```
schema.yaml
```
（或引用的Schema，如
```
../rag/schema.yaml
```
）
运行
```
nx run generate-types
```
以编译并生成类型
若需新增跨字段约束，更新
```
validators.py
```
使用
```
uv run pytest config/tests/
```
进行测试

Common Commands

常用命令

bash

undefined

bash

undefined

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/

undefined

ruff check config/ --fix ruff format config/

undefined