Python コードベース分析 RAG システム

このシステムは、抽象構文木（AST）を用いてPythonコードを解析し、抽出した情報（関数、クラス、呼び出し、変数など）をWeaviateベクターデータベースに保存し、モデルコンテキストプロトコル（MCP）サーバーを介してコードベースをクエリおよび理解するためのツールを提供します。埋め込みと自然言語による説明／回答の生成には、GoogleのGeminiモデルを活用しています。

特徴

• コードスキャン: Python ファイルを解析し、コード要素 (関数、クラス、インポート、呼び出し、代入) とその関係を識別します。抽出対象:
  • 基本情報: 名前、タイプ、ファイル パス、行番号、コード スニペット、ドキュメント文字列。
  • 関数/メソッドの詳細: パラメーター、戻り値の型、シグネチャ、デコレーター。
  • スコープ情報: 親スコープ (クラス/関数) UUID、読み取り可能 ID (例: file:type:name:line )、基本クラス名。
  • 使用情報: スコープ内の属性アクセス、呼び出し関係 (部分的に追跡)。
• ベクター ストレージ: Weaviate を使用して、コード要素とそのベクター埋め込みを保存します (LLM 生成が有効な場合)。
• LLMエンリッチメント（オプション＆バックグラウンド）： Geminiを使用して、関数とクラスのセマンティック記述と埋め込みを生成します。これは、スキャン後にトリガーされるバックグラウンドタスクとして、または手動で実行されます。.env .envで有効化/無効化できます。
• 自動改良 (オプション & バックグラウンド): LLM 生成が有効になっている場合、バックグラウンド処理の一部としてコンテキスト (呼び出し元、呼び出し先、兄弟、関連変数) を使用して、新しい関数または更新された関数の説明を自動的に改良します。
• **RAG Q&A:**検索拡張生成を使用してコードベースに関する自然言語の質問に回答します (LLM 機能が有効になっており、バックグラウンド処理が完了している必要があります)。
• **ユーザーの説明:**ユーザーが特定のコード要素に手動でメモを追加できるようにします。
• **視覚化:**保存された関係に基づいて MermaidJS 呼び出しグラフを生成します。
• MCP サーバー: MCP ツールを使用して分析およびクエリ機能を公開し、コードベースとアクティブなコードベース コンテキストを管理します。
• **ファイルウォッチャー（統合）：**コードベースがスキャンされると自動的に開始（ scan_codebase ）し、別のコードベースが選択されると（ select_codebase ）、またはコードベースが削除されると（ delete_codebase ）停止します。アクティブなコードベースのファイルが変更されると、再解析とデータベース更新がトリガーされます。start_watcher およびstop_watcherツールを介して手動で制御することstart_watcherできます。
• **コードベースの依存関係:**スキャンされたコードベース間の依存関係を定義できます ( add_codebase_dependency 、 remove_codebase_dependency )。
• **コードベース間のクエリ:**アクティブなコードベースとその宣言された依存関係全体での検索 ( find_element ) と質問 ( ask_question ) を可能にします。

設定

1. 環境: Python 3.10 以上と Docker がインストールされていることを確認します。
2. Weaviate: Docker Compose を使用して Weaviate インスタンスを起動します。
   docker-compose up -d
3. 依存関係: Python パッケージをインストールします:
   pip install -r requirements.txt
4. **APIキーと設定:**プロジェクトルートに.envファイルを作成し、Gemini APIキーを追加します。その他の設定も行えます。
   # --- Required --- GEMINI_API_KEY=YOUR_API_KEY_HERE # --- Optional --- # Set to true to enable background LLM description generation and refinement GENERATE_LLM_DESCRIPTIONS=true # Max concurrent background LLM tasks (embeddings/descriptions/refinements) LLM_CONCURRENCY=5 # ANALYZE_ON_STARTUP is no longer used. Scanning is done via the scan_codebase tool. # Specify Weaviate connection details if not using defaults # WEAVIATE_HOST=localhost # WEAVIATE_PORT=8080 # WEAVIATE_GRPC_PORT=50051 # Specify alternative Gemini models if desired # GENERATION_MODEL_NAME="models/gemini-pro" # EMBEDDING_MODEL_NAME="models/embedding-001" # Adjust Weaviate batch size # WEAVIATE_BATCH_SIZE=100 # SEMANTIC_SEARCH_LIMIT=5 # SEMANTIC_SEARCH_DISTANCE=0.7 # Watcher polling interval (seconds) # WATCHER_POLLING_INTERVAL=5
5. **MCP サーバーの実行:**別のターミナルでサーバーを起動します。
   python src/code_analysis_mcp/mcp_server.py
   (ツールが利用できるようにするには、このターミナルが実行中であることを確認してください)

アーキテクチャの概要

このシステムはPythonコードを分析し、抽出した情報をWeaviateベクターデータベースに保存し、モデルコンテキストプロトコル（MCP）サーバーを介してコードベースをクエリおよび理解するためのツールを提供します。埋め込みと自然言語による説明／回答の生成には、GoogleのGeminiモデルを活用しています。

主なモジュールは次のとおりです。

• code_scanner.py : Python ファイルを検索し、AST を使用して解析し、構造要素 (関数、クラス、インポート、呼び出しなど) を抽出し、Weaviate 用のデータを準備します。
• weaviate_client.py : Weaviate への接続を管理し、データ スキーマ ( CodeFile 、 CodeElement 、 CodebaseRegistry ) を定義し、データのバッチアップロード、クエリ、更新、削除の機能を提供します。
• rag.py : コードベースに関する質問に答えるための検索拡張生成（RAG）を実装しています。セマンティック検索を使用して関連するコード要素を見つけ、LLMを使用して回答を合成します。
• mcp_server.py : FastMCP サーバーを設定し、 CodebaseRegistryコレクション内のコードベースを管理し、アクティブなコードベース コンテキスト ( ACTIVE_CODEBASE_NAME ) を処理し、ファイル監視ロジック (自動開始/停止を含む) を統合し、コードベースの依存関係を管理し、詳細な引数の説明を持つ MCP ツールとして分析機能を公開します。
• visualization.py : 保存された関係に基づいて MermaidJS 呼び出しグラフを生成します。

システムは、 CodeFileおよびCodeElementコレクションに Weaviate のマルチテナント機能を使用します。テナント ID はユーザー定義のcodebase_nameです。別の非マルチテナントCodebaseRegistryコレクションは、コードベースのメタデータ（名前、ディレクトリ、ステータス、サマリー、ウォッチャーステータス、依存関係）を追跡します。サーバーのACTIVE_CODEBASE_NAMEグローバル変数は、クエリのプライマリコードベーステナントを決定します。クエリツール（ find_element 、 ask_question ）は、レジストリに保存されているアクティブなコードベースと宣言された依存関係をオプションで検索できます。list_codebases ツールlist_codebases使用すると、すべてのコードベースのステータスと依存関係を表示できます。

バックグラウンドLLM処理は、コード要素の意味記述と埋め込みを生成するために使用されます。これはオプション機能であり、 .envファイルで有効化/無効化できます。

使用可能なツールとその引数に関する詳細情報は、サーバーの実行後、標準の MCP イントロスペクション メソッドを使用して MCP サーバーから直接取得できます。