Hermes-Bitrouter Plugin

A Hermes Agent provider plugin that integrates with Bitrouter for intelligent model routing and provider management.

Overview

This plugin allows Hermes Agent to leverage Bitrouter's sophisticated routing capabilities, including:

• 🔄 Intelligent Routing: Auto-cascade through multiple providers based on availability
• 🔐 Unified Auth: Bitrouter handles all provider authentication (Bearer, OAuth, etc.)
• 📊 Model Discovery: Automatic sync of available models from Bitrouter config
• 🚀 Auto-start: Automatically launches Bitrouter daemon when needed
• 📡 Streaming: Full SSE streaming support with progress events

Architecture

Hermes Agent → Bitrouter Plugin → Bitrouter Daemon → Provider APIs
                                       ↓
                                 Routing Logic
                                 Auth Management  
                                 Rate Limiting
                                 Fallback Chains

Quick Start

1. Install Dependencies

pip install pyyaml httpx psutil

2. Setup Bitrouter

Ensure Bitrouter is installed and configured:

# Install Bitrouter (if not already installed)
cargo install bitrouter

# Create basic config
mkdir -p ~/.bitrouter
cp examples/bitrouter-config.yaml ~/.bitrouter/config.yaml

3. Install Plugin

# Copy plugin to Hermes plugins directory
mkdir -p ~/.hermes/plugins/model-providers
cp -r hermes_bitrouter ~/.hermes/plugins/model-providers/bitrouter

4. Configure Hermes

# Set Bitrouter as your provider
hermes config set provider bitrouter

# Test the integration
hermes chat "Hello, world!"

Configuration

Environment Variables

• BITROUTER_URL: Daemon URL (default: http://localhost:7777)
• BITROUTER_CONFIG_PATH: Custom config path (optional)

Bitrouter Config Example

See examples/bitrouter-config.yaml for a complete configuration example.

Features

Auto-start Daemon

The plugin automatically detects and starts the Bitrouter daemon:

# Daemon management is handled automatically
provider = BitrouterProvider()  # Will start daemon if needed

Model Discovery

Models are automatically synced from Bitrouter:

# List available models
hermes models list

# Models from Bitrouter config appear automatically
# - gpt-4o (via openai)
# - claude-3-5-sonnet (via anthropic) 
# - Virtual models from config

Streaming Support

Full streaming compatibility with Hermes:

# Streaming works automatically
response = await provider.stream_chat_completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True
)

Error Handling

Comprehensive error handling with context:

• Daemon Issues: Auto-retry with restart
• Routing Errors: Clear model availability feedback
• Provider Errors: Surface upstream issues with provider context

Development

Running Tests

python -m pytest tests/ -v

Manual Testing

# Test daemon connectivity
python -c "from hermes_bitrouter.daemon import BitrouterDaemonManager; dm = BitrouterDaemonManager(); print('Running:', dm.is_running())"

# Test model discovery
python -c "from hermes_bitrouter.config import BitrouterConfigReader; cr = BitrouterConfigReader(); print('Models:', [m.id for m in cr.get_all_models()])"

Troubleshooting

Common Issues

1. Daemon won't start: Check that bitrouter binary is in PATH
2. No models found: Verify Bitrouter config has providers configured
3. Auth errors: Check provider credentials in Bitrouter config
4. Connection refused: Ensure daemon is running on correct port

Debug Mode

# Enable debug logging
export HERMES_LOG_LEVEL=debug
hermes chat "test message"

Repository

GitHub: https://github.com/bitrouter/hermes-bitrouter-plugin

Installation from Source

git clone https://github.com/bitrouter/hermes-bitrouter-plugin.git
cd hermes-bitrouter-plugin
pip install -r requirements.txt
python3 scripts/setup.py

Live Testing

export OPENROUTER_API_KEY="your-api-key-here"
python3 test_live.py

Contributing

1. Fork this repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE for details.