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