pi-tool-router

Intelligent tool routing extension for pi coding agent

🔀 Automatically select the best tool stack for each task using intelligent routing rules

Features

🎯 Intelligent Tool Selection

• Smart Routing: AI automatically selects the optimal tool based on task characteristics
• Configurable Rules: Define custom routing rules for your workflow
• Priority System: Set tool priorities and fallback chains
• Real-time Analytics: Track tool usage patterns and effectiveness

🔧 Multi-Tool Support

• Web search tools (built-in, ollama, tavily, etc.)
• Code analysis tools (grep, find, read)
• File manipulation tools (edit, write, bash)
• Custom extension tools

📊 Observability

• Real-time routing dashboard
• Tool usage statistics
• Performance metrics
• Cost tracking per tool

⚙️ Extensible

• Custom routing strategies
• Plugin architecture
• Easy to add new tools and providers

Installation

# Global installation
pi install npm:@jessenguyen22/pi-tool-router

# Project-local installation
pi install -l npm:@jessenguyen22/pi-tool-router

Quick Start

1. Install the extension

pi install npm:@jessenguyen22/pi-tool-router

2. Restart pi

pi

3. The extension auto-initializes and registers routing rules

The router will automatically:

• Analyze incoming tasks
• Select optimal tools based on rules
• Execute with fallback support
• Track analytics

Configuration

Create ~/.pi/agent/settings.json to customize routing:

{
  "toolRouter": {
    "enabled": true,
    "defaultStrategy": "priority",
    "strategies": {
      "priority": {
        "enabled": true,
        "fallbackEnabled": true
      },
      "cost": {
        "enabled": true,
        "maxCostPerTask": 5.0
      },
      "capability": {
        "enabled": true,
        "strictMatching": false
      }
    },
    "toolWeights": {
      "web_search": 10,
      "ollama_web_search": 8,
      "code_search": 7,
      "fetch_content": 6,
      "read": 5,
      "bash": 4
    },
    "routingRules": [
      {
        "name": "real-time-news",
        "match": {
          "queryPatterns": ["news", "price", "weather", "stock", "live"]
        },
        "preferredTools": ["ollama_web_search", "web_search"],
        "priority": 10
      },
      {
        "name": "code-search",
        "match": {
          "queryPatterns": ["function", "class", "api", "implementation"]
        },
        "preferredTools": ["code_search", "grep", "find"],
        "priority": 9
      }
    ],
    "analytics": {
      "enabled": true,
      "retentionDays": 30
    }
  }
}

Usage

Automatic Routing (Default)

Just describe your task naturally:

User: "Find the latest news about AI agents"
→ Router selects: ollama_web_search (real-time priority)

User: "Show me how the auth function is implemented"
→ Router selects: code_search + read (code analysis)

User: "Search for React performance patterns"
→ Router selects: web_search + code_search (combined)

Manual Tool Override

Force a specific tool:

User: "Use tavily to search for X"
→ Router respects: tavily_web_search

Dashboard

View routing analytics:

/tool-router-stats

Shows:

• Tool usage frequency
• Average response times
• Cost per tool
• Success rates
• Routing decisions log

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    pi-tool-router                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Router   │  │   Matcher   │  │  Executor  │          │
│  │   Core     │→ │   Engine    │→ │   Manager  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│         ↓               ↓               ↓                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Config   │  │   Rules    │  │   Tools    │          │
│  │   Manager  │  │   Engine   │  │   Registry │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│         ↓                                                    │
│  ┌─────────────────────────────────────────────┐           │
│  │            Analytics & Dashboard            │           │
│  └─────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

Components

Component	Description
Router Core	Central orchestrator, manages routing decisions
Matcher Engine	Analyzes task context and matches routing rules
Executor Manager	Executes tools with fallback support
Config Manager	Loads and validates configuration
Rules Engine	Evaluates and prioritizes routing rules
Tools Registry	Maintains available tools and their metadata
Analytics	Tracks usage, costs, and performance

Routing Strategies

Priority Strategy (Default)

Routes to highest-priority tool that matches task requirements.

Cost Strategy

Routes to lowest-cost tool that can complete the task.

Capability Strategy

Routes based on tool capabilities matching task requirements.

Custom Strategy

Implement your own routing logic:

import type { RoutingStrategy } from 'pi-tool-router';

const myStrategy: RoutingStrategy = {
  name: 'my-strategy',
  selectTool(context: RoutingContext): ToolSelection {
    // Custom logic
    return { toolName: 'best-tool', confidence: 0.95 };
  },
};

API Reference

Extension Events

// On tool selection
pi.events.on('tool-router:tool-selected', tool => {
  console.log(`Selected: ${tool.name}`);
});

// On routing decision
pi.events.on('tool-router:routing-decision', decision => {
  console.log(`Decision: ${decision.selectedTool}`);
});

// On tool execution complete
pi.events.on('tool-router:tool-complete', result => {
  console.log(`Completed: ${result.toolName}`);
});

Tool Registration

// Register custom routing strategy
pi.events.emit('tool-router:register-strategy', myStrategy);

// Register custom tool
pi.events.emit('tool-router:register-tool', {
  name: 'my-custom-tool',
  capabilities: ['web', 'search'],
  cost: 0.001,
  priority: 5,
});

Examples

See examples/ for complete examples:

Installation

# Global installation
pi install npm:pi-tool-router

# Project-local installation
pi install -l npm:pi-tool-router

# From GitHub (latest)
pi install git:github.com/jessenguyen22/pi-tool-router

• Basic routing
• Custom strategy
• Dashboard integration

Development

# Clone repository
git clone https://github.com/your-username/pi-tool-router.git
cd pi-tool-router

# Install dependencies
npm install

# Run tests
npm test

# Run in dev mode
npm run dev

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request to jessenguyen22/pi-tool-router

License

MIT License - see LICENSE for details.

Related Projects

• pi-coding-agent - The coding agent this extends
• pi-coordinator - Multi-agent orchestration
• pi-coordination - Advanced coordination system
• pi-interactive-shell - Interactive CLI spawning

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• ⭐ Star on GitHub