hermes-smart-router 0.2.0__tar.gz

hermes_smart_router-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 raydatalab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_smart_router-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: hermes-smart-router
+Version: 0.2.0
+Summary: Intelligent model tier routing for Hermes Agent
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: semantic-router[ollama]>=0.1.15
+Dynamic: license-file

hermes_smart_router-0.2.0/README.md

@@ -0,0 +1,162 @@
+# Hermes Smart Router
+
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python">
+  <img src="https://img.shields.io/badge/Hermes-v0.17+-purple.svg" alt="Hermes">
+</p>
+
+Intelligent model tier routing for Hermes Agent — helps the agent pick the right model for each query.
+
+> **Note:** Hermes does not support in-session model switching via skills. The router classifies queries and recommends a tier; the user must run the suggested `/model` command manually.
+
+## The Problem
+
+A user may have access to multiple model tiers: a local model (fast, free, offline), a low-cost cloud model, and a more capable frontier model. Without routing, every query goes to the same target, incurring unnecessary cost on simple tasks and under-serving complex ones.
+
+## The Solution
+
+A Hermes skill that classifies queries on demand and recommends the appropriate model tier. Classification runs entirely on the local machine:
+
+```
+"Translate hello to German"           → local (Ollama, free)
+"Explain how DNS works"               → flash (low-cost API)
+"Design a multi-region database"      → pro (highest capability)
+```
+
+Routing uses [semantic-router](https://github.com/aurelio-labs/semantic-router) with local Ollama embeddings — zero API calls, zero cost. After the one-time embedding model pull, classification runs entirely offline.
+
+## Tiers
+
+| Tier | Purpose | Provider examples |
+|------|---------|-------------------|
+| **local** | Free, offline, private — simple lookups, translations, formatting | Ollama (llama3.2, qwen3, mistral), any local model |
+| **flash** | Fast, low-cost — everyday coding, explanations, general Q&A | DeepSeek Flash, Gemini Flash, GPT-4o-mini, Claude Haiku |
+| **pro** | Highest capability — complex architecture, debugging, multi-step reasoning | DeepSeek Pro, Gemini Pro, GPT-4o, Claude Sonnet |
+
+One API token, different models for different complexity. There is no requirement for multiple providers — a single provider such as OpenRouter or DeepSeek provides both flash and pro tiers.
+
+## Features
+
+- 3-tier routing: local / flash / pro, auto-selected per query
+- 100% local classification via Ollama embeddings — no cloud dependencies
+- Ollama lifecycle: auto-start when needed, auto-kill when idle
+- No GPU required — runs on CPU
+- Queries never leave the local machine during routing decisions
+
+## Installation
+
+**Prerequisites:** Hermes Agent v0.17+, Python 3.10+, Ollama installed.
+
+### Via Hermes (recommended)
+
+```bash
+hermes skills install hermes-smart-router
+```
+
+If the short form is unavailable, use the repo path:
+
+```bash
+hermes skills install raydatalab/hermes-smart-router
+```
+
+Then run the one-time setup script to install Python dependencies into Hermes' environment and pull the embedding model (~30 seconds, once per machine):
+
+```bash
+git clone https://github.com/raydatalab/hermes-smart-router.git
+cd hermes-smart-router && bash scripts/install.sh
+```
+
+The script auto-detects Hermes' Python venv and installs there — the skill can import `smart_router` immediately after.
+
+### Manual
+
+```bash
+git clone https://github.com/raydatalab/hermes-smart-router.git
+cd hermes-smart-router && bash scripts/install.sh
+hermes skills install SKILL.md
+```
+
+On first use, Smart Router detects available Ollama models from `ollama list` and adapts. If no cloud providers are configured, the skill operates in local-only mode — no errors, no missing-config warnings.
+
+## Configuration
+
+Configure via `hermes config set` for each tier, or add a `smart_router:` block in config.yaml with the following structure:
+
+```yaml
+smart_router:
+  enabled: true
+  default_tier: flash
+  encoder_model: nomic-embed-text
+  tiers:
+    local:
+      provider: custom
+      model: llama3.2:3b
+      base_url: http://localhost:11434/v1
+    flash:
+      provider: openrouter
+      model: google/gemini-flash-1.5
+    pro:
+      provider: openrouter
+      model: anthropic/claude-sonnet-4
+  ollama:
+    auto_start: true
+    idle_timeout: 300
+```
+
+Providers are configured via `hermes model` — no manual `.env` editing is required.
+
+## Provider Support
+
+| Tier | Ollama | OpenRouter | DeepSeek | Anthropic | OpenAI | Custom endpoint |
+|------|--------|------------|----------|-----------|--------|-----------------|
+| local | auto-detect | — | — | — | — | configurable |
+| flash | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+| pro | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+The local tier auto-detects whichever Ollama model is available. Flash and pro tiers work with any provider Hermes supports — the `provider` and `model` fields in the tier config determine the target.
+
+## Usage
+
+Once loaded, the skill provides a classification tool the agent invokes when the current model feels wrong for the query — either too weak or too expensive. The router fires `needs_switch` in both directions, and the agent recommends a `/model` command the user can execute:
+
+```
+Agent (flash): receives "Design a fault-tolerant payment system"
+→ classifies → needs_switch=true → recommends pro upgrade
+💡 Switch to pro: /model deepseek deepseek-v4-pro
+Agent: [detailed architecture answer]
+
+Agent (pro): receives "Translate hello to German"
+→ classifies → needs_switch=true → recommends flash downgrade
+💡 Downgrade to flash: /model deepseek deepseek-v4-flash
+Agent: Hallo
+```
+
+### Python API
+
+```python
+from smart_router.router import get_router
+
+router = get_router()
+decision = router.resolve("Explain how DNS works", current_tier="flash")
+# → {"tier": "flash", "model": {...}, "ollama_ready": null, "needs_switch": false}
+```
+
+### CLI
+
+```bash
+python -m smart_router route "What is the capital of France?"
+python -m smart_router chat          # interactive mode with stats
+python -m smart_router tiers         # list configured tiers
+python -m smart_router ollama status # check Ollama
+```
+
+If installed via the script into Hermes' venv, use that Python directly:
+
+```bash
+~/.hermes/hermes-agent/venv/bin/python3 -m smart_router route "What is the capital of France?"
+```
+
+## License
+
+MIT

hermes_smart_router-0.2.0/hermes_smart_router.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: hermes-smart-router
+Version: 0.2.0
+Summary: Intelligent model tier routing for Hermes Agent
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: semantic-router[ollama]>=0.1.15
+Dynamic: license-file

hermes_smart_router-0.2.0/hermes_smart_router.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+hermes_smart_router.egg-info/PKG-INFO
+hermes_smart_router.egg-info/SOURCES.txt
+hermes_smart_router.egg-info/dependency_links.txt
+hermes_smart_router.egg-info/requires.txt
+hermes_smart_router.egg-info/top_level.txt
+smart_router/__init__.py
+smart_router/__main__.py
+smart_router/ollama.py
+smart_router/router.py
+smart_router/tier.py
+tests/__init__.py
+tests/test_cli.py
+tests/test_ollama.py
+tests/test_router.py
+tests/test_tier.py

hermes_smart_router-0.2.0/hermes_smart_router.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hermes_smart_router-0.2.0/hermes_smart_router.egg-info/requires.txt

@@ -0,0 +1 @@
+semantic-router[ollama]>=0.1.15

hermes_smart_router-0.2.0/hermes_smart_router.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+build
+dist
+examples
+scripts
+smart_router
+tests

hermes_smart_router-0.2.0/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "hermes-smart-router"
+version = "0.2.0"
+description = "Intelligent model tier routing for Hermes Agent"
+requires-python = ">=3.10"
+dependencies = [
+    "semantic-router[ollama]>=0.1.15",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]

hermes_smart_router-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hermes_smart_router-0.2.0/smart_router/__init__.py

@@ -0,0 +1,10 @@
+"""
+Hermes Smart Router — Intelligent model tier routing for Hermes Agent.
+
+Classifies queries on demand and recommends the optimal model tier:
+- local (Ollama, free)
+- flash (low-cost API)
+- pro (frontier API, highest quality)
+"""
+
+__version__ = "0.2.0"

hermes_smart_router-0.2.0/smart_router/__main__.py

@@ -0,0 +1,386 @@
+"""
+CLI entry point for Smart Router.
+
+Usage:
+    python -m smart_router route [--json] [--verbose] <query>
+    python -m smart_router ollama start|stop|status [--json]
+    python -m smart_router chat [--verbose]
+    python -m smart_router tiers              # list configured tiers
+    python -m smart_router status [--json]    # show version, tiers, Ollama status
+
+Examples:
+    python -m smart_router route "What is the capital of France?"
+    python -m smart_router route --json "Design a microservice architecture"
+    python -m smart_router ollama status
+    python -m smart_router status
+    python -m smart_router chat
+"""
+
+import json
+import sys
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SEPARATOR = "─" * 50
+
+
+def _setup_logging(verbose: bool) -> None:
+    """Configure logging level based on verbosity flag."""
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
+
+
+def _parse_flags(args: list[str]) -> tuple[bool, bool, list[str]]:
+    """Extract --json and --verbose from args, returning (json_mode, verbose, remaining)."""
+    json_mode = False
+    verbose = False
+    remaining: list[str] = []
+    for arg in args:
+        if arg == "--json":
+            json_mode = True
+        elif arg == "--verbose":
+            verbose = True
+        else:
+            remaining.append(arg)
+    return json_mode, verbose, remaining
+
+
+# ---------------------------------------------------------------------------
+# Route command
+# ---------------------------------------------------------------------------
+
+def cmd_route(args: list[str]) -> None:
+    """Classify a query and print the routing decision."""
+    json_mode, verbose, remaining = _parse_flags(args)
+    _setup_logging(verbose)
+
+    query = " ".join(remaining) if remaining else "Hello, how are you?"
+
+    from .router import ModelRouter
+
+    router = ModelRouter()
+
+    try:
+        info = router.route_info(query)
+    except Exception as e:
+        if json_mode:
+            print(json.dumps({"error": str(e)}, ensure_ascii=False))
+        else:
+            print(f"Error: {e}")
+        sys.exit(1)
+
+    if json_mode:
+        print(json.dumps(info, indent=2, ensure_ascii=False))
+    else:
+        model = info["model"]
+        provider_model = f"{model['provider']}/{model['model']}"
+        base_url = model.get("base_url", "")
+        url_info = f"\n  Base URL:    {base_url}" if base_url else ""
+
+        print(f"Query:    {info['query']}")
+        print(f"Tier:     {info['tier']}")
+        print(f"Model:    {provider_model}{url_info}")
+        print(f"Summary:  {info['description']}")
+
+
+# ---------------------------------------------------------------------------
+# Ollama commands
+# ---------------------------------------------------------------------------
+
+def cmd_ollama(args: list[str]) -> None:
+    """Manage Ollama lifecycle: start, stop, status."""
+    json_mode, verbose, remaining = _parse_flags(args)
+    _setup_logging(verbose)
+
+    from .ollama import OllamaManager
+
+    mgr = OllamaManager()
+
+    if not remaining or remaining[0] == "status":
+        status = mgr.status()
+        if json_mode:
+            print(json.dumps(status, indent=2))
+        else:
+            print("Ollama Status")
+            print(SEPARATOR)
+            print(f"  Running:       {'✓ yes' if status['running'] else '✗ no'}")
+            print(f"  Binary:        {'✓ found' if status['binary_exists'] else '✗ not found'}")
+            print(f"  Model:         {status['model'] or '(none)'}")
+            print(f"  Model loaded:  {'✓ yes' if status['model_loaded'] else '✗ no'}")
+            print(f"  Model pulled:  {'✓ yes' if status['model_pulled'] else '✗ no'}")
+            print(f"  Idle:          {status['idle_seconds']}s (timeout: {status['idle_timeout']}s)")
+            print(f"  Managed PID:   {status['our_pid'] or 'none'}")
+            print(f"  WSL:           {'✓ yes' if status['wsl'] else '✗ no'}")
+        return
+
+    action = remaining[0]
+    if action == "start":
+        ok = mgr.ensure_running()
+        if json_mode:
+            print(json.dumps({"action": "start", "success": ok}))
+        else:
+            print(f"Ollama start: {'✓ ready' if ok else '✗ failed'}")
+            if not ok:
+                print("  Is ollama installed? Try: curl -fsSL https://ollama.com/install.sh | sh")
+
+    elif action == "stop":
+        ok = mgr.ensure_killed(force=True)
+        if json_mode:
+            print(json.dumps({"action": "stop", "success": ok}))
+        else:
+            print(f"Ollama stop: {'✓ killed' if ok else '✗ not killed (may be systemd-managed)'}")
+
+    else:
+        print(f"Unknown action: {action}. Use: start, stop, status", file=sys.stderr)
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Tiers command
+# ---------------------------------------------------------------------------
+
+def cmd_tiers(args: list[str]) -> None:
+    """List configured tiers with model info."""
+    json_mode, verbose, remaining = _parse_flags(args)
+    _setup_logging(verbose)
+
+    from .tier import get_tiers, DEFAULT_TIER
+
+    tiers = get_tiers()
+
+    if json_mode:
+        print(json.dumps({"tiers": tiers, "default": DEFAULT_TIER}, indent=2, ensure_ascii=False))
+        return
+
+    print("Smart Router — Configured Tiers")
+    print(SEPARATOR)
+    for name, config in tiers.items():
+        marker = " ★ DEFAULT" if name == DEFAULT_TIER else ""
+        m = config["models"]
+        provider_model = f"{m['provider']}/{m['model']}"
+        print(f"  [{name}]{marker}")
+        print(f"    Model:       {provider_model}")
+        if "base_url" in m:
+            print(f"    Base URL:    {m['base_url']}")
+        print(f"    Utterances:  {len(config['utterances'])} examples")
+        print(f"    Description: {config.get('description', '')}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# Status command
+# ---------------------------------------------------------------------------
+
+def cmd_status(args: list[str]) -> None:
+    """Show smart-router version, configured tiers, and Ollama status."""
+    json_mode, verbose, remaining = _parse_flags(args)
+    _setup_logging(verbose)
+
+    from . import __version__
+    from .tier import get_tiers, DEFAULT_TIER
+    from .ollama import OllamaManager
+
+    tiers = get_tiers()
+    ollama = OllamaManager()
+    ostatus = ollama.status()
+
+    status_data = {
+        "version": __version__,
+        "default_tier": DEFAULT_TIER,
+        "encoder_model": "nomic-embed-text",
+        "tiers": {},
+        "ollama": ostatus,
+    }
+
+    for name, config in tiers.items():
+        status_data["tiers"][name] = {
+            "model": dict(config["models"]),
+            "utterance_count": len(config["utterances"]),
+        }
+
+    if json_mode:
+        print(json.dumps(status_data, indent=2, ensure_ascii=False))
+        return
+
+    print("Smart Router Status")
+    print(SEPARATOR)
+    print(f"  Version:       {__version__}")
+    print(f"  Default tier:  {DEFAULT_TIER}")
+    print(f"  Encoder:       nomic-embed-text (Ollama)")
+    print()
+    print("  Configured Tiers:")
+    for name, config in tiers.items():
+        marker = " ★ default" if name == DEFAULT_TIER else ""
+        m = config["models"]
+        base_url = m.get("base_url", "")
+        url_info = f" @ {base_url}" if base_url else ""
+        print(f"    [{name}]{marker}")
+        print(f"      Model:  {m['provider']}/{m['model']}{url_info}")
+    print()
+    print("  Ollama:")
+    print(f"    Running:       {'✓ yes' if ostatus['running'] else '✗ no'}")
+    print(f"    Binary:        {'✓ found' if ostatus['binary_exists'] else '✗ not found'}")
+    print(f"    Chat model:    {ostatus['model'] or '(none)'}")
+    print(f"    Model loaded:  {'✓ yes' if ostatus['model_loaded'] else '✗ no'}")
+    print(f"    Model pulled:  {'✓ yes' if ostatus['model_pulled'] else '✗ no'}")
+    if ostatus.get("idle_seconds") is not None:
+        print(f"    Idle:          {ostatus['idle_seconds']}s (timeout: {ostatus['idle_timeout']}s)")
+
+
+# ---------------------------------------------------------------------------
+# Chat (interactive) command
+# ---------------------------------------------------------------------------
+
+def cmd_chat(args: list[str]) -> None:
+    """Interactive routing test with session statistics."""
+    json_mode, verbose, remaining = _parse_flags(args)
+    _setup_logging(verbose)
+
+    from .router import ModelRouter
+
+    router = ModelRouter()
+
+    # Session routing statistics
+    stats: dict[str, int] = {"local": 0, "flash": 0, "pro": 0}
+
+    print("╔══════════════════════════════════════════════════╗")
+    print("║        Smart Router — Interactive Test           ║")
+    print("╠══════════════════════════════════════════════════╣")
+    print("║  Type a query to see tier + model routing.       ║")
+    print("║  Commands: :stats  :reset  :help  quit          ║")
+    print("╚══════════════════════════════════════════════════╝")
+    print()
+
+    while True:
+        try:
+            query = input("query ▸ ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not query:
+            continue
+
+        # Handle special commands
+        if query.lower() in ("quit", "exit", "q"):
+            print("Goodbye!")
+            break
+
+        if query.startswith(":"):
+            _handle_chat_command(query, stats, router)
+            continue
+
+        # Route the query
+        info = router.route_info(query)
+        tier = info["tier"]
+        stats[tier] += 1
+        model = info["model"]
+        provider_model = f"{model['provider']}/{model['model']}"
+
+        # Display routing decision
+        tier_symbols = {"local": "🖥 ", "flash": "⚡", "pro": "🧠"}
+        symbol = tier_symbols.get(tier, "→")
+
+        print(f"  {symbol}  Tier:  {tier}")
+        print(f"     Model: {provider_model}")
+        if "base_url" in model:
+            print(f"     URL:   {model['base_url']}")
+        print(f"     {info['description']}")
+        print()
+
+
+def _handle_chat_command(cmd: str, stats: dict[str, int], router) -> None:
+    """Process in-chat meta-commands (prefixed with ':')."""
+    cmd = cmd.lower()
+
+    if cmd == ":stats":
+        total = sum(stats.values())
+        print(f"  Session Stats ({total} queries)")
+        print(f"  {'─' * 28}")
+        if total == 0:
+            print("    No queries yet.")
+        else:
+            for tier, count in stats.items():
+                pct = (count / total * 100) if total > 0 else 0
+                bar = "█" * int(pct / 5) + "░" * (20 - int(pct / 5))
+                print(f"    {tier:8s}  {bar}  {count:3d} ({pct:3.0f}%)")
+
+    elif cmd == ":reset":
+        for key in stats:
+            stats[key] = 0
+        print("  Stats reset.")
+
+    elif cmd == ":help":
+        print("  Commands:")
+        print("    :stats   Show session routing statistics")
+        print("    :reset   Reset session statistics")
+        print("    :help    Show this help")
+        print("    :tiers   List configured tiers")
+        print("    quit     Exit interactive mode")
+
+    elif cmd == ":tiers":
+        from .tier import get_tiers, DEFAULT_TIER
+        tiers = get_tiers()
+        for name, config in tiers.items():
+            marker = " (default)" if name == DEFAULT_TIER else ""
+            m = config["models"]
+            print(f"    [{name}]{marker}: {m['provider']}/{m['model']}")
+
+    else:
+        print(f"  Unknown command: {cmd}. Type :help for available commands.")
+
+    print()
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Parse subcommand and dispatch."""
+
+    usage_text = (
+        "Smart Router CLI — intelligent model tier routing\n"
+        "\n"
+        "Usage:\n"
+        "  python -m smart_router route [--json] [--verbose] <query>\n"
+        "  python -m smart_router ollama start|stop|status [--json]\n"
+        "  python -m smart_router chat  [--verbose]\n"
+        "  python -m smart_router tiers [--json]\n"
+        "  python -m smart_router status [--json]\n"
+        "\n"
+        "Examples:\n"
+        '  python -m smart_router route "What is the capital of France?"\n'
+        '  python -m smart_router route --json "Design a system"\n'
+        "  python -m smart_router ollama status\n"
+    )
+
+    if len(sys.argv) < 2:
+        print(usage_text)
+        sys.exit(0)
+
+    command = sys.argv[1]
+    args = sys.argv[2:]
+
+    if command == "route":
+        cmd_route(args)
+    elif command == "ollama":
+        cmd_ollama(args)
+    elif command == "chat":
+        cmd_chat(args)
+    elif command == "tiers":
+        cmd_tiers(args)
+    elif command == "status":
+        cmd_status(args)
+    elif command in ("--help", "-h", "help"):
+        print(usage_text)
+    else:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        print("Available: route, ollama, chat, tiers, status", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()