Knowledge Graph Specialist

概要

knowledge_graph は、コードのエンティティ抽出とグラフ構築のための abhigyanpatwari/GitNexus のパターンと、 Graph RAG 検索のための topoteretes/cognee をラップしています。

ソースアーティファクト（リポジトリ URL、ファイルパス、または生のコード）を入力として、スペシャリストは エンティティと関係性からなる有向ナレッジグラフを構築し、グラフの走査を通じてエンティティと関係性の有向ナレッジグラフを構築し、自然言語の質問に答えます。結果はランク付けされたエンティティリスト、関連性スコア、明示的な関係パスとして返され、下流の推論または引用に利用できます。

スペシャリストはステートレスです。各 :meth:execute 呼び出しは新しいグラフを構築し、独立した結果辞書を返します。グラフ ID は呼び出し間で渡すことができ、グラフを再構築せずに以前構築されたグラフをクエリできます。

機能

• knowledge_graph: コードまたはドキュメントから構造化されたエンティティ/関係性グラフを構築します。走査深度とエンティティタイプでスコープできます。
• code_analysis: ソースリポジトリからモジュール、クラス、関数、変数、インポートを抽出し、依存性とコール グラフの構造を明らかにします。
• entity_linking: ファイルとモジュール全体にわたる名前付きエンティティを統一されたグラフに解決し、安定したエンティティ ID により参照を重複排除します。
• graph_rag: グラフ走査と関連性ランキングを通じて自然言語クエリに答えます — 構造化されたコード知識に対する Graph Retrieval-Augmented Generation です。

ツール

ツール	説明	副作用
build_graph	ソースアーティファクトからナレッジグラフを構築	なし（v1 ローカル；将来：ネットワーク/ディスク）
query_graph	グラフを自然言語でクエリ；ランク付けされたエンティティとパスを返す	なし
find_relationships	2 つの名前付きエンティティ間のすべてのパスを検出；タイプと強度を返す	なし

パラメータ

リクエストレベル（intent.parameters）

キー	型	デフォルト	説明
source	str	(query.user_input)	取り込むリポジトリ URL、ファイルパス、または生のコード
graph_type	str	"code"	エンティティ戦略：code、document、または mixed
max_depth	int	3	最大ファイル間走査深度
query	str	(query.user_input)	グラフに対して実行する自然言語の質問
max_results	int	10	グラフクエリの結果の上限
entity_a	str	None	関係性検索の送信元エンティティ（オプション）
entity_b	str	None	関係性検索の対象エンティティ（オプション）

グラフタイプ

• code — module、class、function、variable、import エンティティを抽出します。 ソースリポジトリ分析とコール グラフの推論に最適です。
• document — concept、section、claim、reference エンティティを抽出します。 技術ドキュメントまたは研究論文に適しています。
• mixed — コードとドキュメントタイプの統合です。実行可能なコードとリッチなインラインドキュメントを含むソースの場合に使用します。

レスポンスの形式

{
    "graph": {
        "graph_id": str,          # このグラフインスタンスの安定した UUID
        "node_count": int,        # 総エンティティノード数
        "edge_count": int,        # 総有向関係エッジ数
        "entity_types": list[str],# グラフに存在するエンティティラベル
        "graph_type": str,        # リクエストされた graph_type のエコー
    },
    "query_results": {
        "results": list[dict],    # ランク付けされたエンティティヒット
        "relevance_scores": list[float],  # 並列の関連性値 0-1
        "paths": list[dict],      # 接続する関係パス
        "total_found": int,       # max_results 上限以前の総マッチ数
    },
    # entity_a と entity_b が提供される場合のみ表示：
    "relationships": {
        "paths": list[dict],      # entity_a から entity_b へのすべてのパス
        "relationship_types": list[str],  # 重複排除されたエッジラベル
        "strength": float,        # カップリング強度 0-1
        "path_count": int,
    },
}

使用方法

Python API

import asyncio
from agents.specialists.knowledge_graph.agent import KnowledgeGraphSpecialist
from oss_agent_lab.contracts import Intent, Query, SpecialistRequest

specialist = KnowledgeGraphSpecialist()

request = SpecialistRequest(
    intent=Intent(
        action="knowledge_graph",
        domain="code_analysis",
        confidence=0.9,
        parameters={
            "source": "https://github.com/abhigyanpatwari/GitNexus",
            "graph_type": "code",
            "max_depth": 3,
        },
    ),
    query=Query(user_input="Which functions call the authentication module?"),
    specialist_name="knowledge_graph",
)

response = asyncio.run(specialist.execute(request))
print(response.result["graph"]["node_count"])
print(response.result["query_results"]["results"][0])

CLI

oss-lab run knowledge_graph "Which functions call the authentication module?"

関係性検索を使用した例

request = SpecialistRequest(
    intent=Intent(
        action="knowledge_graph",
        domain="code_analysis",
        confidence=0.9,
        parameters={
            "source": "./src/",
            "entity_a": "UserService",
            "entity_b": "DatabaseAdapter",
        },
    ),
    query=Query(user_input="How does UserService depend on DatabaseAdapter?"),
    specialist_name="knowledge_graph",
)

パラメータ付き CLI

oss-lab run knowledge_graph "dependency chain for PaymentProcessor" \
  --param source=https://github.com/owner/repo \
  --param graph_type=code \
  --param max_depth=5 \
  --param entity_a=PaymentProcessor \
  --param entity_b=DatabaseClient

ソース

abhigyanpatwari/GitNexus と topoteretes/cognee をラップしています。