アーキテクチャ概要
Upsilon は構成可能性と保守性を重視したモジュラーで拡張可能なアーキテクチャに従います。このドキュメントでは、システムアーキテクチャと設計原理の高レベル概要を提供します。
設計原理
1. 構成可能性
Upsilon は組み合わせて使用できる疎結合コンポーネントのコレクションとして構築されています:
- プラガブルツール: 共通インターフェース経由での組み込みツールと外部ツール
- 設定可能なワークフロー: カスタマイズ可能なレビュープロセス
- 複数のインターフェース: CLI、API、pre-commit 統合
2. 外部ツール統合
既存の機能を再実装するのではなく、Upsilon は実績のあるツールを活用します:
- 実際のコンパイラ: Python の
compile()、rustc、go build - 確立されたリンター: mypy、ruff、eslint
- ランゲージサーバー: 将来の統合可能性
3. 型安全性
モダンな Python プラクティスで構築:
- mypy strict モード: 完全な型チェックカバレッジ
- Pydantic モデル: ランタイム検証とシリアライゼーション
- ジェネリックインターフェース: 型安全なプラグインシステム
4. テスト可能性
包括的なテスト戦略:
- 59 テストケース: 全コンポーネントの高いカバレッジ
- モック実装: 外部依存関係なしでテスト可能
- 統合テスト: 実際のツール実行検証
システムアーキテクチャ
コアコンポーネント
1. 設定システム (config.py)
Pydantic モデルを使用してすべてのアプリケーション設定を管理:
class UpsilonConfig(BaseModel):
model: str = "claude-3-haiku-20240307"
max_tokens: int = 2000
temperature: float = 0.1
builtin_tools: Dict[str, BuiltinToolConfig] = Field(default_factory=dict)
rules: RulesConfig = Field(default_factory=RulesConfig)
prompts: PromptConfig = Field(default_factory=PromptConfig)
主要機能:
- 検証付き TOML ファイル解析
- デフォルト値管理
- 型安全な設定アクセス
- 階層設定構造
2. コードレビュアー (reviewer.py)
レビュープロセスを調整するメインオーケストレーター:
class CodeReviewer:
def __init__(self, config: UpsilonConfig, use_mock: bool = True):
self.config = config
self.llm_client = create_llm_client(config, use_mock=use_mock)
self._initialize_tools()
def review_file(self, file_path: Path) -> Dict[str, Any]:
# ファイル検証と言語検出
# ツール実行調整
# LLM 解析統合
# 結果集約
責任:
- ファイル種別検出と検証
- ツール初期化と登録
- レビューワークフロー統制
- 結果集約とフォーマット
3. ツールシステム (tools/)
コード解析ツール用のプラガブルアーキテクチャ:
ベースインターフェース (tools/base.py)
class Tool(ABC):
def __init__(self, name: str, config: Dict[str, Any]):
self.name = name
self.config = config
@abstractmethod
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
pass
@abstractmethod
def get_function_schema(self) -> Dict[str, Any]:
pass
組み込みツール (tools/builtin.py)
- SpellChecker: コメントと文字列のタイポを検出
- SyntaxChecker: 構文検証に言語コンパイラを使用
- ImportAnalyzer: インポートパターンと使用法をチェック
外部ツール (tools/external.py)
- 汎用 ExternalTool: サブプロセス実行フレームワーク
- 言語固有ツール: mypy、ruff、rustc、go build など
- 自動検出: システム上のツール可用性をチェック
4. LLM 統合 (llm_client.py)
言語モデルとの通信を処理:
class LLMClient(ABC):
def __init__(self, config: UpsilonConfig):
self.config = config
self.tools: Dict[str, Tool] = {}
def register_tool(self, tool: Tool) -> None:
self.tools[tool.name] = tool
@abstractmethod
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
pass
実装:
- MockLLMClient: テスト用の決定論的レスポンス
- AnthropicLLMClient: 関数呼び出し機能付き実際の Claude API 統合
5. CLI インターフェース (main.py)
Typer と Rich を使用したリッチなコマンドラインインターフェース:
app = typer.Typer(name="upsilon", help="AI 駆動コードレビュー")
@app.command()
def review(
files: List[Path] = typer.Argument(...),
config_path: Optional[Path] = typer.Option(None),
format: OutputFormat = typer.Option(OutputFormat.text),
mock: bool = typer.Option(True),
verbose: bool = typer.Option(False),
stdin: bool = typer.Option(False)
):
# 実装
データフロー
1. 初期化フロー
CLI コマンド → 設定読み込み → レビュアー初期化 → ツール登録 → 準備完了
2. レビューフロー
ファイル入力 → 言語検出 → ツール選択 → ツール実行 →
LLM 解析 → 関数呼び出し → 結果集約 → 出力フォーマット
3. ツール実行フロー
ツール登録 → 可用性チェック → 設定 → 実行 →
結果解析 → 正規化 → ToolResult 返却
拡張ポイント
1. カスタムツール
Tool インターフェースを実装:
class CustomTool(Tool):
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
# カスタム解析ロジック
pass
def get_function_schema(self) -> Dict[str, Any]:
# LLM 関数呼び出しスキーマ
pass
2. カスタム LLM クライアント
他のプロバイダー用に LLMClient インターフェースを実装:
class CustomLLMClient(LLMClient):
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
# カスタム LLM 統合
pass
3. 出力フォーマッター
異なる用途向けに出力フォーマットを拡張:
class CustomFormatter:
def format_results(self, results: List[Dict[str, Any]]) -> str:
# カスタムフォーマットロジック
pass
パフォーマンス考慮事項
1. ツール実行
- 並列実行: ツールは独立して実行
- キャッシュ: ファイル内容ハッシュごとに結果をキャッシュ
- タイムアウト処理: 問題のあるファイルでハングを防止
2. LLM 最適化
- トークン管理: リクエストごとの設定可能制限
- バッチ処理: 可能な場合は単一リクエストで複数ファイル
- モデル選択: pre-commit には高速モデル、CI/CD には強力なモデル
3. メモリ管理
- ストリーミング: 大きなファイルをチャンクで処理
- クリーンアップ: 一時ファイルを自動削除
- リソース制限: 設定可能なメモリと時間制約
セキュリティ考慮事項
1. 外部ツール実行
- サンドボックス: 外部ツールは分離された環境で実行
- 入力検証: ファイル内容は処理前にすべて検証
- タイムアウト強制: サービス拒否攻撃を防止
2. API キー管理
- 環境変数: API キーは安全に保存
- ログなし: API キーはログや公開されることはない
- 検証: API キー形式の検証
3. ファイルアクセス
- パス検証: ディレクトリトラバーサル攻撃を防止
- 権限チェック: ファイルシステム権限を尊重
- 一時ファイル: 安全な一時ファイル作成とクリーンアップ
次: 外部ツール →