Capability Graph Builder

Capability Graph Builder

関係性の推論に Codex を使用して、マニフェストからクエリ可能な能力グラフを構築します

目的

manifest-generator によって生成された能力マニフェストを取り込み、すべての能力とその関係性を表すクエリ可能なグラフ構造を構築します。OpenAI Codex を使用して、不足している関係性を推論し、互換性の宣言を検証します。

使用するタイミング

• スキル／MCP／ツールのマニフェストを生成した後
• オーケストレーションシステムのナレッジベースを構築するとき
• 能力の関係性と依存関係を特定するとき
• リソース間でマニフェストの整合性を検証するとき
• オーケストレーション計画のために、グラフベースのクエリを有効にするとき

主な機能

• グラフ構築：マニフェストからノード（能力）とエッジ（関係性）を構築します
• 関係性の推論：Codex を使用して、説明から暗黙の関係性を特定します
• 整合性の検証：双方向の関係性を検証します（A が B を有効にする場合、B は A を必要とするか？）
• 経路探索：「X を達成するにはどのスキルが必要か？」などのクエリをサポートします
• サブグラフの抽出：ドメイン内または特定の効果を持つすべての能力を検索します

入力

inputs:
  manifest_dir: string # Directory containing manifest.yaml files (e.g., SKILLS/)
  output_path: string # Where to write capability-graph.json
  validate_consistency: boolean # Run Codex validation on relationships
  infer_missing: boolean # Use Codex to infer missing compatibility fields

処理

ステップ 1：マニフェストをスキャンして読み込む

#!/bin/bash
# Find all manifest.yaml files
MANIFESTS=$(find SKILLS MCP-SERVERS TOOLS COMPONENTS INTEGRATIONS -name 'manifest.yaml' 2>/dev/null)

# Load each manifest
echo "Loading manifests..."
for manifest in $MANIFESTS; do
  echo "  - $manifest"
done

ステップ 2：初期グラフを構築する

// Pseudocode for graph construction
const graph = {
  nodes: [],
  edges: [],
  domains: {},
  effects: {}
}

for (const manifest of manifests) {
  // Add node
  graph.nodes.push({
    id: manifest.name,
    kind: manifest.kind,
    description: manifest.description,
    preconditions: manifest.preconditions,
    effects: manifest.effects,
    domains: manifest.domains,
    cost: manifest.cost,
    latency: manifest.latency,
    risk_level: manifest.risk_level
  })

  // Add edges from compatibility
  if (manifest.compatibility) {
    if (manifest.compatibility.requires) {
      for (const required of manifest.compatibility.requires) {
        graph.edges.push({
          from: required,
          to: manifest.name,
          type: 'requires'
        })
      }
    }
    if (manifest.compatibility.enables) {
      for (const enabled of manifest.compatibility.enables) {
        graph.edges.push({
          from: manifest.name,
          to: enabled,
          type: 'enables'
        })
      }
    }
    if (manifest.compatibility.conflicts_with) {
      for (const conflict of manifest.compatibility.conflicts_with) {
        graph.edges.push({
          from: manifest.name,
          to: conflict,
          type: 'conflicts_with'
        })
      }
    }
    if (manifest.compatibility.composes_with) {
      for (const compose of manifest.compatibility.composes_with) {
        graph.edges.push({
          from: manifest.name,
          to: compose,
          type: 'composes_with'
        })
      }
    }
  }

  // Index by domain
  for (const domain of manifest.domains) {
    if (!graph.domains[domain]) graph.domains[domain] = []
    graph.domains[domain].push(manifest.name)
  }

  // Index by effect
  for (const effect of manifest.effects) {
    if (!graph.effects[effect]) graph.effects[effect] = []
    graph.effects[effect].push(manifest.name)
  }
}

ステップ 3：Codex で不足している関係性を推論する

# For each pair of capabilities, ask Codex about relationships
for capability_a in "${capabilities[@]}"; do
  for capability_b in "${capabilities[@]}"; do
    if [ "$capability_a" != "$capability_b" ]; then
      # Get manifests
      MANIFEST_A=$(cat "path/to/$capability_a/manifest.yaml")
      MANIFEST_B=$(cat "path/to/$capability_b/manifest.yaml")

      # Ask Codex
      codex exec "
Analyze these two capabilities and determine their relationship:

CAPABILITY A:
$MANIFEST_A

CAPABILITY B:
$MANIFEST_B

Questions:
1. Does A require B to function?
2. Does A enable B (make B possible)?
3. Do A and B conflict (can't coexist)?
4. Do A and B compose well together?
5. Are there any implicit dependencies or relationships?

Output JSON:
{
  \"requires\": boolean,
  \"enables\": boolean,
  \"conflicts_with\": boolean,
  \"composes_with\": boolean,
  \"reasoning\": \"explanation\"
}
" > /tmp/relationship-${capability_a}-${capability_b}.json
    fi
  done
done

ステップ 4：整合性を検証する

# Check bidirectional relationships
codex exec "
Analyze this capability graph for consistency issues:

GRAPH:
$(cat /tmp/capability-graph.json)

Check for:
1. Asymmetric relationships (A enables B but B doesn't require A)
2. Conflicting declarations (A enables B but B conflicts with A)
3. Missing transitive relationships (A requires B, B requires C, but A doesn't require C)
4. Circular dependencies (A requires B, B requires A)

Output JSON array of issues:
[
  {
    \"type\": \"asymmetric_enables\",
    \"from\": \"capability-a\",
    \"to\": \"capability-b\",
    \"issue\": \"A enables B but B doesn't list A as required\",
    \"severity\": \"warning\"
  }
]
"

ステップ 5：グラフを書き込む

# Write final graph with metadata
cat > META/capability-graph.json <<EOF
{
  "version": "1.0.0",
  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "node_count": ${node_count},
  "edge_count": ${edge_count},
  "graph": $(cat /tmp/capability-graph.json)
}
EOF

グラフクエリ API

生成されたグラフは、次のクエリをサポートします。

効果で能力を検索する

// Find all capabilities that create vector indexes
const creators = graph.effects['creates_vector_index']
// => ['rag-implementer', 'pinecone-mcp', 'weaviate-mcp']

ドメインで能力を検索する

// Find all RAG-related capabilities
const ragCapabilities = graph.domains['rag']
// => ['rag-implementer', 'embedding-generator-mcp', 'vector-search-tool', ...]

依存関係を検索する

// What does rag-implementer require?
const deps = findDependencies('rag-implementer')
// => ['openai-integration', 'pinecone-mcp']

function findDependencies(capabilityName) {
  return graph.edges.filter(e => e.to === capabilityName && e.type === 'requires').map(e => e.from)
}

有効化される能力を検索する

// What does having openai-integration enable?
const enabled = findEnabled('openai-integration')
// => ['rag-implementer', 'embedding-generator-mcp', 'gpt-vision-analyzer']

function findEnabled(capabilityName) {
  return graph.edges.filter(e => e.from === capabilityName && e.type === 'enables').map(e => e.to)
}

競合を検索する

// What conflicts with existing-vector-database?
const conflicts = findConflicts('existing-vector-database')
// => ['rag-implementer']

function findConflicts(capabilityName) {
  return graph.edges
    .filter(
      e => (e.from === capabilityName || e.to === capabilityName) && e.type === 'conflicts_with'
    )
    .map(e => (e.from === capabilityName ? e.to : e.from))
}

組み合わせ可能な能力を検索する

// What composes well with rag-implementer?
const partners = findCompositionPartners('rag-implementer')
// => ['pinecone-mcp', 'weaviate-mcp', 'semantic-search-tool']

function findCompositionPartners(capabilityName) {
  return graph.edges
    .filter(
      e => (e.from === capabilityName || e.to === capabilityName) && e.type === 'composes_with'
    )
    .map(e => (e.from === capabilityName ? e.to : e.from))
}

目標への経路を検索する

// What capabilities are needed to achieve "semantic_search"?
const path = findPathToEffect('semantic_search')
// => ['openai-integration', 'rag-implementer', 'vector-search-tool']

function findPathToEffect(effect) {
  // BFS through requires/enables edges
  const capabilities = graph.effects[effect] || []
  const visited = new Set()
  const path = []

  for (const cap of capabilities) {
    const deps = findAllDependencies(cap, visited)
    path.push(...deps, cap)
  }

  return [...new Set(path)]
}

function findAllDependencies(capabilityName, visited = new Set()) {
  if (visited.has(capabilityName)) return []
  visited.add(capabilityName)

  const directDeps = graph.edges
    .filter(e => e.to === capabilityName && e.type === 'requires')
    .map(e => e.from)

  const allDeps = []
  for (const dep of directDeps) {
    allDeps.push(...findAllDependencies(dep, visited), dep)
  }

  return allDeps
}

出力例

{
  "version": "1.0.0",
  "generated_at": "2025-10-28T12:00:00Z",
  "node_count": 109,
  "edge_count": 287,
  "graph": {
    "nodes": [
      {
        "id": "rag-implementer",
        "kind": "skill",
        "description": "Implement retrieval-augmented generation systems",
        "preconditions": [
          { "check": "file_exists('package.json')", "required": true },
          { "check": "env_var_set('OPENAI_API_KEY')", "required": true }
        ],
        "effects": ["creates_vector_index", "adds_embedding_pipeline", "configures_retrieval_api"],
        "domains": ["rag", "ai", "search"],
        "cost": "medium",
        "latency": "slow",
        "risk_level": "low"
      },
      {
        "id": "pinecone-mcp",
        "kind": "mcp",
        "description": "Vector database operations for Pinecone",
        "effects": ["creates_vector_index", "performs_similarity_search"],
        "domains": ["rag", "vector-db"],
        "cost": "low",
        "latency": "fast",
        "risk_level": "safe"
      }
    ],
    "edges": [
      {
        "from": "openai-integration",
        "to": "rag-implementer",
        "type": "requires"
      },
      {
        "from": "rag-implementer",
        "to": "pinecone-mcp",
        "type": "composes_with"
      },
      {
        "from": "rag-implementer",
        "to": "semantic-search",
        "type": "enables"
      }
    ],
    "domains": {
      "rag": ["rag-implementer", "pinecone-mcp", "weaviate-mcp", "embedding-generator-mcp"],
      "auth": ["frontend-builder", "api-designer", "security-engineer"],
      "api": ["api-designer", "frontend-builder", "performance-optimizer"]
    },
    "effects": {
      "creates_vector_index": ["rag-implementer", "pinecone-mcp", "weaviate-mcp"],
      "adds_auth": ["frontend-builder", "api-designer"],
      "configures_database": ["api-designer", "data-engineer"]
    }
  }
}

統合

manifest-generator との連携

manifest-generator スキルによって生成されたマニフェストを取り込みます。

orchestration-planner との連携

目標の要件に一致する能力を検索するための、クエリ可能なグラフを提供します。

skill-validator との連携

グラフ構造を利用して、宣言された関係性が実際に存在することを検証します。

成功指標

• ✅ グラフに 109 個すべての能力が含まれている
• ✅ すべてのエッジで双方向の整合性が検証されている
• ✅ ドメインと効果のインデックスがすべて揃っている
• ✅ 経路探索クエリが正しい結果を返す
• ✅ グラフを効率的にシリアライズ／デシリアライズできる

関連スキル

• manifest-generator：このビルダーに渡すマニフェストを生成します
• orchestration-planner：計画にグラフを使用します
• skill-validator：グラフの整合性を検証します