メインコンテンツまでスキップ

アーキテクチャ概要

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. ファイルアクセス​

  • パス検証: ディレクトリトラバーサル攻撃を防止
  • 権限チェック: ファイルシステム権限を尊重
  • 一時ファイル: 安全な一時ファイル作成とクリーンアップ

次: 外部ツール →