common-skills

LlamaFarm の共通スキル

common/ パッケージのベストプラクティスとコードレビューのチェックリストです。すべての LlamaFarm サービスで共有される Python ユーティリティを扱います。

コンポーネントの概要

属性	値
パス	common/
パッケージ	llamafarm-common
Python	3.10+
主な依存関係	huggingface_hub, hf-transfer

目的

common/ パッケージは、複数の Python サービス間で一貫性を保つ必要がある共通機能を提供します。

• モデルファイルユーティリティ（GGUF の選択、量子化の解析）
• HuggingFace Hub との連携（一覧表示、ダウンロード）
• プロセス管理（PID ファイル）

共通 Python スキル

このスキルは、共通 Python スキルのすべてのパターンを継承します。

トピック	ファイル	関連性
パターン	../python-skills/patterns.md	データクラス、型ヒント、内包表記
型付け	../python-skills/typing.md	型注釈、モダンな構文
テスト	../python-skills/testing.md	Pytest のフィクスチャ、HuggingFace API のモック
エラー	../python-skills/error-handling.md	カスタム例外、ロギング
セキュリティ	../python-skills/security.md	パスの検証、安全なファイル処理

フレームワーク固有のチェックリスト

トピック	ファイル	主なポイント
HuggingFace	huggingface.md	Hub API、モデルのダウンロード、キャッシュ、認証

モジュール構成

common/
├── pyproject.toml           # UV-managed dependencies
├── llamafarm_common/
│   ├── __init__.py          # Public API exports
│   ├── model_utils.py       # GGUF file utilities
│   └── pidfile.py           # PID file management
└── tests/
    └── test_model_utils.py  # Unit tests with mocking

公開 API

モデルユーティリティ

from llamafarm_common import (
    # Parse model:quantization syntax
    parse_model_with_quantization,
    # Extract quantization from filename
    parse_quantization_from_filename,
    # Select best GGUF file from list
    select_gguf_file,
    select_gguf_file_with_logging,
    # List GGUF files in HF repo
    list_gguf_files,
    # Download and get path to GGUF file
    get_gguf_file_path,
    # Default quantization preference order
    GGUF_QUANTIZATION_PREFERENCE_ORDER,
)

PID ファイル管理

from llamafarm_common.pidfile import write_pid, get_pid_file

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

common/ のコードをレビューする際は、次を確認します。

1. HuggingFace との連携（優先度：高）

   • ネットワーク障害に対する適切なエラー処理
   • 認証トークンが正しく渡されている
   • 高速転送が適切に有効化されている

2. モデルの選択（優先度：中）

   • 量子化の優先順位が維持されている
   • 大文字と小文字を区別しない照合
   • 優先候補が利用できない場合の適切なフォールバック

3. テスト（優先度：高）

   • HuggingFace API 呼び出しがモック化されている
   • テストでネットワークが分離されている
   • エッジケースが網羅されている（空のリスト、ファイルの欠落）

4. セキュリティ（優先度：中）

   • ログにトークンが露出しない
   • 安全なファイルパス処理
   • 環境変数の保護

HuggingFace 固有の詳細なチェックリストについては、huggingface.md を参照してください。