config-skills

LlamaFarm の設定スキル

LlamaFarm の設定モジュール（config/）に特化したパターンとベストプラクティスです。

モジュールの概要

設定モジュールは、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	テンプレートベースの設定生成

共通スキルへのリンク

このモジュールでは、共通スキルの 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: ConfigDict、Field、制約付き型を使用する v2
• JSONSchema: Draft-07。jsonref による $ref の参照解決に対応
• YAML: コメントを保持した読み書きに ruamel.yaml を使用
• コード生成: スキーマから Pydantic への変換に datamodel-codegen を使用

主なパターン

生成された 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 によるコメント保持 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

ワークフロー：スキーマの変更

設定スキーマを変更する場合：

1. schema.yaml（または ../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/