python-skills

LlamaFarm 向け Python スキル

LlamaFarm モノレポ内のすべての Python コンポーネントで共有する、Python のベストプラクティスとコードレビュー用チェックリストです。

対象コンポーネント

コンポーネント	パス	Python	主な依存関係
サーバー	server/	3.12+	FastAPI, Celery, Pydantic, structlog
RAG	rag/	3.11+	LlamaIndex, ChromaDB, Celery
ユニバーサルランタイム	runtimes/universal/	3.11+	PyTorch, transformers, FastAPI
設定	config/	3.11+	Pydantic, JSONSchema
共通	common/	3.10+	HuggingFace Hub

クイックリファレンス

トピック	ファイル	主なポイント
パターン	patterns.md	データクラス、Pydantic、内包表記、インポート
非同期処理	async.md	async/await、asyncio、並行実行
型付け	typing.md	型ヒント、ジェネリクス、プロトコル、Pydantic
テスト	testing.md	Pytest フィクスチャ、モック、非同期テスト
エラー	error-handling.md	カスタム例外、ログ記録、コンテキストマネージャー
セキュリティ	security.md	パストラバーサル、インジェクション、シークレット、デシリアライズ

コードスタイル

LlamaFarm は ruff を使用し、共有設定を ruff.toml に定義しています。

line-length = 88
target-version = "py311"
select = ["E", "F", "I", "B", "UP", "SIM"]

主なルール：

• E, F：基本的な pyflakes と pycodestyle
• I：インポートの並べ替え（isort）
• B：Bugbear（よくある落とし穴）
• UP：構文を最新の Python にアップグレード
• SIM：コードパターンの簡素化

アーキテクチャパターン

pydantic-settings による設定

from pydantic_settings import BaseSettings

class Settings(BaseSettings, env_file=".env"):
    LOG_LEVEL: str = "INFO"
    HOST: str = "0.0.0.0"
    PORT: int = 14345

settings = Settings()  # Singleton at module level

structlog による構造化ログ

from core.logging import FastAPIStructLogger  # Server
from core.logging import RAGStructLogger      # RAG
from core.logging import UniversalRuntimeLogger  # Runtime

logger = FastAPIStructLogger(__name__)
logger.info("Operation completed", extra={"count": 10, "duration_ms": 150})

拡張性を実現する抽象基底クラス

from abc import ABC, abstractmethod

class Component(ABC):
    def __init__(self, name: str, config: dict[str, Any] | None = None):
        self.name = name or self.__class__.__name__
        self.config = config or {}

    @abstractmethod
    def process(self, documents: list[Document]) -> ProcessingResult:
        pass

内部データ用のデータクラス

from dataclasses import dataclass, field

@dataclass
class Document:
    content: str
    metadata: dict[str, Any] = field(default_factory=dict)
    id: str = field(default_factory=lambda: str(uuid.uuid4()))

API 境界用の Pydantic モデル

from pydantic import BaseModel, Field, ConfigDict

class EmbeddingRequest(BaseModel):
    model: str
    input: str | list[str]
    encoding_format: Literal["float", "base64"] | None = "float"

    model_config = ConfigDict(str_strip_whitespace=True)

ディレクトリ構成

各 Python コンポーネントは、次の構成に従います。

component/
├── pyproject.toml     # UV-managed dependencies
├── core/              # Core functionality
│   ├── __init__.py
│   ├── settings.py    # Pydantic Settings
│   └── logging.py     # structlog setup
├── services/          # Business logic (server)
├── models/            # ML models (runtime)
├── tasks/             # Celery tasks (rag)
├── utils/             # Utility functions
└── tests/
    ├── conftest.py    # Shared fixtures
    └── test_*.py

レビューチェックリストの概要

LlamaFarm の Python コードをレビューする際は、次の点を確認します。

1. パターン（優先度：中）

   • 最新の Python 構文（3.10 以降の型ヒント）
   • データクラスと Pydantic が適切に使い分けられている
   • 可変のデフォルト引数を使用していない

2. 非同期処理（優先度：高）

   • 非同期関数内でブロッキング呼び出しを行っていない
   • asyncio.Lock を適切に使用している
   • キャンセルを正しく処理している

3. 型付け（優先度：中）

   • 戻り値の型ヒントがすべて指定されている
   • ジェネリック型に型パラメーターが指定されている
   • Pydantic v2 のパターンを使用している

4. テスト（優先度：中）

   • フィクスチャのスコープが適切に設定されている
   • 非同期テストで pytest-asyncio を使用している
   • モックを後始末している

5. エラー（優先度：高）

   • コンテキストを含むカスタム例外を使用している
   • extra dict を使って構造化ログを記録している
   • 例外チェーンを適切に処理している

6. セキュリティ（優先度：重大）

   • パストラバーサルを防止している
   • 入力をサニタイズしている
   • 安全なデシリアライズを行っている

grep パターンを含む詳細なチェックリストについては、各トピックのファイルを参照してください。