ai-model-router

智能 AI 模型路由器，可在两个配置的模型之间自动切换（本地用于简单任务，云用于复杂任务）。自动检测本地模型（Ollama、LM Studio），根据任务复杂性和隐私进行路由。当用户要求“切换模型”、“使用本地/云模型”或提及 API 密钥/密码（触发隐私模式）时使用。触发：敏感数据检测（强制本地）、“设计架构”（使用云）等复杂任务或配置请求。

# AI Model Router

Compact, intelligent model routing that just works.

## Quick Start

```bash
# Install
npx clawhub@latest install ai-model-router

# First run - auto-detects your models
python3 skill/core/router.py "What is Python?"

# List available models
python3 skill/core/router.py --list
```

## How It Works

```
Your Request → Analyze → Select Model
                          ↓
                    Simple? → Primary (fast/cheap)
                    Complex? → Secondary (capable)
                    Private? → Primary (forced)
```

## Scoring (from model-router-premium)

| Pattern | Points |
|---------|--------|
| Microservices, architecture | +10 |
| Design, implement, optimize | +5 |
| Explain, analyze, compare | +3 |
| **Syntax, example, "what is"** | **-3** |

**Threshold: 5** (simple vs complex)

## Features

| Feature | Status |
|---------|--------|
| Auto-detect local models | ✓ (Ollama, LM Studio) |
| Cloud model registry | ✓ (7 built-in) |
| Privacy detection | ✓ (API keys, passwords) |
| Context tracking | ✓ (conversations) |
| JSON config | ✓ (optional) |
| CLI interface | ✓ |
| **Core code size** | **~200 lines** |

## CLI

```bash
# Route a task
python3 skill/core/router.py "Design a system"
python3 skill/core/router.py "What is a for loop?"

# Options
--json                    # JSON output
--force primary           # Force primary model
--list                    # List all models
--status                  # Show status
```

## Python API

```python
from skill.core.router import RouterCore

router = RouterCore()
result = router.route("Design microservices")

print(result.model_name)   # "Claude Opus 4"
print(result.reason)        # "complex_task(score=15)"
print(result.confidence)    # 0.75
```

## Configuration (Optional)

Create `~/.model-router/models.json`:

```json
{
  "primary_model": {"id": "ollama:llama3:8b"},
  "secondary_model": {"id": "anthropic:claude-opus-4"},
  "models": [...]
}
```

**Without config**: Auto-detects local + uses cloud registry.

## Privacy Protection

Automatically forces primary (local) when sensitive data detected:
- API keys (`sk-...`, `api_key`)
- Passwords (`password`, `passwd`)
- Tokens (`bearer`, `secret`)
- Emails, SSN, credit cards

## Files

- `core/router.py` - Core routing engine (~200 lines)
- `modules/detector.py` - Auto-detection (optional)
- `modules/context.py` - Context tracking (optional)

## Inspired By

- **model-router-premium**: Simple scoring logic, cost-aware routing
- **Model Router v1**: Full feature set, documentation

This version combines:
- The **simplicity** of model-router-premium (~200 lines)
- The **features** of ai-model-router (privacy, auto-detect, context)

---

## 中文说明

# AI 模型路由器

紧凑、智能、开箱即用的模型路由。

## 快速开始

```bash
# Install
npx clawhub@latest install ai-model-router

# First run - auto-detects your models
python3 skill/core/router.py "What is Python?"

# List available models
python3 skill/core/router.py --list
```

## 工作原理

```
Your Request → Analyze → Select Model
                          ↓
                    Simple? → Primary (fast/cheap)
                    Complex? → Secondary (capable)
                    Private? → Primary (forced)
```

## 评分机制（来自 model-router-premium）

| 模式 | 分值 |
|---------|--------|
| Microservices, architecture | +10 |
| Design, implement, optimize | +5 |
| Explain, analyze, compare | +3 |
| **Syntax, example, "what is"** | **-3** |

**阈值：5**（简单 vs 复杂）

## 功能特性

| 功能 | 状态 |
|---------|--------|
| 自动检测本地模型 | ✓ (Ollama, LM Studio) |
| 云端模型注册表 | ✓ (7 built-in) |
| 隐私检测 | ✓ (API keys, passwords) |
| 上下文跟踪 | ✓ (conversations) |
| JSON 配置 | ✓ (optional) |
| CLI 接口 | ✓ |
| **核心代码量** | **~200 lines** |

## CLI

```bash
# Route a task
python3 skill/core/router.py "Design a system"
python3 skill/core/router.py "What is a for loop?"

# Options
--json                    # JSON output
--force primary           # Force primary model
--list                    # List all models
--status                  # Show status
```

## Python API

```python
from skill.core.router import RouterCore

router = RouterCore()
result = router.route("Design microservices")

print(result.model_name)   # "Claude Opus 4"
print(result.reason)        # "complex_task(score=15)"
print(result.confidence)    # 0.75
```

## 配置（可选）

创建 `~/.model-router/models.json`：

```json
{
  "primary_model": {"id": "ollama:llama3:8b"},
  "secondary_model": {"id": "anthropic:claude-opus-4"},
  "models": [...]
}
```

**无配置时**：自动检测本地模型 + 使用云端注册表。

## 隐私保护

当检测到敏感数据时，自动强制使用 primary（本地）模型：
- API 密钥（`sk-...`、`api_key`）
- 密码（`password`、`passwd`）
- 令牌（`bearer`、`secret`）
- 邮箱、SSN、信用卡

## 文件

- `core/router.py` - 核心路由引擎（~200 行）
- `modules/detector.py` - 自动检测（可选）
- `modules/context.py` - 上下文跟踪（可选）

## 灵感来源

- **model-router-premium**：简单的评分逻辑，成本感知路由
- **Model Router v1**：完整的功能集、文档

此版本结合了：
- model-router-premium 的**简洁性**（~200 行）
- ai-model-router 的**功能特性**（隐私、自动检测、上下文）