router-builder

What this skill does

# Router Builder Skill

> Build the Semantic Router for intelligent resource selection.

## Overview

The router provides fast, embedding-based routing to:
- Slash commands
- Sub-agents  
- Skills
- Workflows

Uses the same embedding model as RAG for consistency.

## Prerequisites

```bash
pip install semantic-router sentence-transformers pyyaml
```

## Build Steps

### Step 1: Create Router Core

**File: `routing/router.py`**

```python
#!/usr/bin/env python3
"""
Hierarchical Semantic Router

Two-tier routing:
- Tier 1: Category (command | agent | skill | workflow)
- Tier 2: Specific resource within category
"""

import os
import yaml
from pathlib import Path
from typing import Optional, Dict, List, Tuple
from dataclasses import dataclass
from enum import Enum

from semantic_router import Route
from semantic_router.layer import RouteLayer
from semantic_router.encoders import HuggingFaceEncoder

# Configuration
ROUTES_PATH = Path(os.getenv("ROUTES_PATH", "./routing/routes"))
CONFIDENCE_THRESHOLD = float(os.getenv("ROUTING_CONFIDENCE", "0.5"))


class Category(Enum):
    COMMAND = "command"
    AGENT = "agent"
    SKILL = "skill"
    WORKFLOW = "workflow"
    GENERAL = "general"


@dataclass
class RoutingResult:
    """Result of a routing decision."""
    category: Category
    resource: Optional[str]
    confidence: float
    metadata: Dict
    fallback: bool = False


class Router:
    """Hierarchical semantic router."""
    
    def __init__(self):
        # Use same model as RAG
        self.encoder = HuggingFaceEncoder(name="all-MiniLM-L6-v2")
        self.category_layer = self._build_category_layer()
        self.domain_layers: Dict[Category, RouteLayer] = {}
        self._build_domain_layers()
    
    def _load_routes(self, path: Path) -> List[Route]:
        """Load routes from YAML."""
        if not path.exists():
            return []
        
        with open(path) as f:
            data = yaml.safe_load(f) or {}
        
        return [
            Route(
                name=r["name"],
                utterances=r["utterances"],
                metadata=r.get("metadata", {})
            )
            for r in data.get("routes", [])
        ]
    
    def _build_category_layer(self) -> RouteLayer:
        """Build tier-1 category router."""
        routes = self._load_routes(ROUTES_PATH / "categories.yaml")
        
        if not routes:
            # Default routes
            routes = [
                Route(name="command", utterances=[
                    "/research", "/code-review", "/daily-standup",
                    "run the command", "execute command", "use slash command"
                ]),
                Route(name="agent", utterances=[
                    "ask the researcher", "have the coder", "use the analyst",
                    "delegate to agent", "agent should handle"
                ]),
                Route(name="skill", utterances=[
                    "use the skill", "apply skill", "leverage skill for"
                ]),
                Route(name="workflow", utterances=[
                    "run workflow", "start pipeline", "execute automation"
                ]),
            ]
        
        return RouteLayer(encoder=self.encoder, routes=routes)
    
    def _build_domain_layers(self):
        """Build tier-2 domain routers."""
        mappings = {
            Category.COMMAND: "commands.yaml",
            Category.AGENT: "agents.yaml",
            Category.SKILL: "skills.yaml",
            Category.WORKFLOW: "workflows.yaml",
        }
        
        for category, filename in mappings.items():
            routes = self._load_routes(ROUTES_PATH / filename)
            if routes:
                self.domain_layers[category] = RouteLayer(
                    encoder=self.encoder,
                    routes=routes
                )
    
    def route(self, query: str) -> RoutingResult:
        """Route a query through both tiers."""
        
        # Tier 1: Category
        cat_result = self.category_layer(query)
        
        if cat_result.name is None:
            return RoutingResult(
                category=Category.GENERAL,
                resource=None,
                confidence=0.0,
                metadata={"reason": "no_category_match"},
                fallback=True
            )
        
        category = Category(cat_result.name)
        
        # Tier 2: Specific resource
        if category in self.domain_layers:
            domain_result = self.domain_layers[category](query)
            
            if domain_result.name is not None:
                return RoutingResult(
                    category=category,
                    resource=domain_result.name,
                    confidence=0.8,  # TODO: extract actual score
                    metadata=getattr(domain_result, 'metadata', {}) or {}
                )
        
        # Category matched but no specific resource
        return RoutingResult(
            category=category,
            resource=None,
            confidence=0.5,
            metadata={"reason": "no_resource_match"},
            fallback=True
        )
    
    def add_route(self, category: Category, name: str, utterances: List[str], metadata: Dict = None):
        """Dynamically add a route."""
        route = Route(name=name, utterances=utterances, metadata=metadata or {})
        
        if category not in self.domain_layers:
            self.domain_layers[category] = RouteLayer(
                encoder=self.encoder,
                routes=[route]
            )
        else:
            # Rebuild with new route
            existing = list(self.domain_layers[category].routes)
            existing.append(route)
            self.domain_layers[category] = RouteLayer(
                encoder=self.encoder,
                routes=existing
            )


# Singleton
_router: Optional[Router] = None

def get_router() -> Router:
    global _router
    if _router is None:
        _router = Router()
    return _router

def route(query: str) -> RoutingResult:
    return get_router().route(query)
```

### Step 2: Create Route Definitions

**File: `routing/routes/categories.yaml`**

```yaml
routes:
  - name: command
    utterances:
      - "/research"
      - "/code-review"
      - "/daily-standup"
      - "/summarize"
      - "run the research command"
      - "execute code review"
      - "use slash command"
      - "run command for"
      
  - name: agent
    utterances:
      - "ask the researcher"
      - "have the coder implement"
      - "let the writer draft"
      - "use the analyst"
      - "delegate to agent"
      - "which agent should"
      - "agent help with"
      
  - name: skill
    utterances:
      - "use web research skill"
      - "apply document generation"
      - "use the skill for"
      - "leverage skill"
      
  - name: workflow
    utterances:
      - "run the workflow"
      - "start the pipeline"
      - "execute automation"
      - "trigger workflow"
```

**File: `routing/routes/commands.yaml`**

```yaml
routes:
  - name: research
    utterances:
      - "research this"
      - "find information about"
      - "look up"
      - "investigate"
      - "deep dive into"
      - "gather info on"
    metadata:
      file: ".claude/commands/research.md"
      
  - name: code-review
    utterances:
      - "review code"
      - "check for bugs"
      - "analyze code"
      - "security review"
      - "code quality"
    metadata:
      file: ".claude/commands/code-review.md"
      
  - name: daily-standup
    utterances:
      - "daily standup"
      - "standup report"
      - "what did I work on"
      - "yesterday today blockers"
    metadata:
      file: ".claude/commands/daily-standup.md"
```

**File: `routing/routes/agents.yaml`**

```yaml
routes:
  - name: researcher
    utterances:
      - "research topic"
      - "find information"
      - "look up facts"
      - "gather data"
      - "fact check"
    metadata:
      path: "agents/sub-