ypollak2/llm-router

pip install llm-routing   # PyPI name is llm-routing; the CLI command is llm-router

• Por qué la gente instala esto

• Puesto #8 en RouterArena

• Inicio rápido

• Ejemplo de enrutamiento

• Funciona con

• Cómo funciona

• Características

• CLI

• Proveedores

• Políticas de enrutamiento

• Herramientas MCP

• Ahorro: cómo funciona

• Confianza, privacidad y diseño local-first

• Configuración

• Documentación

• Empresa

• Contribuciones

Por qué la gente instala esto

Las herramientas de codificación con IA envían demasiados prompts a modelos premium por defecto.

Eso significa que:

• Desperdicias tokens de pago en preguntas simples

• Agotas la cuota de Claude, Gemini u OpenAI más rápido de lo necesario

• Te quedas bloqueado cuando un proveedor está limitado por tasa o fuera de servicio

llm-router se sitúa entre tu herramienta de codificación y tus proveedores de modelos. Clasifica cada prompt, prueba primero el modelo capaz más barato y recurre automáticamente a la alternativa cuando es necesario.

Mantienes el mismo flujo de trabajo. El router cambia la elección del modelo por debajo.

Related MCP server: MCP AI Router

Puesto #8 en RouterArena

llm-router fue evaluado de forma independiente y obtuvo el puesto #8 en RouterArena — una clasificación comunitaria que evalúa los routers de modelos según la precisión del enrutamiento, la latencia, la eficiencia de costes y la fiabilidad del fallback.

Inicio rápido

1. Instalación

pip install llm-routing
llm-router install

Nombre del paquete: llm-routing en PyPI. Comando CLI: llm-router.

2. Añadir proveedores (opcional)

export OPENAI_API_KEY="sk-..."          # GPT-4o, o3
export GEMINI_API_KEY="AIza..."         # Gemini Flash/Pro (free tier available)
export OLLAMA_BASE_URL="http://localhost:11434"  # Local models (free)
export OPENROUTER_API_KEY="sk-or-v1-…"  # 343 OpenRouter models (qwen, deepseek, grok, …)

Funciona con cero claves de API en las suscripciones de Claude Code Pro/Max: el enrutamiento usa herramientas MCP que solo llaman a modelos externos cuando es beneficioso. Añade OPENROUTER_API_KEY para desbloquear el grupo de modelos de pesos abiertos que hace el trabajo pesado, utilizado por la política cost_aggressive.

3. Verificación

llm-router health            # Check provider connectivity

Si ya usas Claude Code, Codex o Gemini CLI, mantén tu flujo de trabajo actual y deja que llm-router elija los modelos por debajo.

Ejemplo de enrutamiento

La cadena exacta depende de tus proveedores configurados, tu perfil de presupuesto y tu política de enrutamiento.

Funciona con

• Enrutamiento automático completo significa que los hooks interceptan los prompts y los enrutan automáticamente sin ningún cambio en el flujo de trabajo.

• Herramientas MCP manuales significa que el enrutamiento está disponible bajo demanda a través de herramientas como llm_query.

llm-router install                    # Claude Code (default)
llm-router install --host codex       # Codex CLI
llm-router install --host gemini-cli  # Gemini CLI
llm-router install --host vscode      # VS Code
llm-router install --host cursor      # Cursor

Consulta guide/HOST_SUPPORT_MATRIX.md para obtener todos los detalles de cada host.

Protege tu cuota de 5 horas de Claude Code

enforce: smart + mode: zero_claude hace que los prompts se completen externamente o se detengan antes de que se ejecute el Claude nativo; consulta guide/GETTING_STARTED.md.

Cómo funciona

User prompt
    │
    ▼
┌──────────────────────┐
│ Complexity Classifier │  ← Heuristic (free, instant) or Ollama/Flash ($0.0001)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Free-First Router   │  ← Tries cheapest model first, walks up the chain
│                      │
│  Ollama (free)       │
│  → Codex (prepaid)   │
│  → Gemini Flash      │
│  → GPT-4o / Claude   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Guards (parallel)   │  ← Circuit breaker, budget pressure, quality check
└──────────┬───────────┘
           │
           ▼
      Response + cost logged to local SQLite

La clasificación es gratuita para muchas tareas (las heurísticas de regex detectan ~70%) o casi gratuita para prompts ambiguos cuando se usa Ollama local o Gemini Flash.

Características

Más allá de «enviar prompts baratos a modelos baratos»:

• Los secretos nunca salen de tu máquina. Un prompt que contenga una clave de API, un token o una clave privada se enruta únicamente a modelos locales —modo fail-closed—, por lo que no puede llegar a un proveedor externo.

• Enrutamiento de suscripción invertido por coste. Lo gratuito/local primero para prompts simples y moderados, tu único asiento de pago primero para los complejos, y el asiento pasa a segundo plano cuando su cuota está al límite. Actívalo con LLM_ROUTER_SUBSCRIPTION_PROVIDER.

• Reintento automático con interruptores de circuito (circuit breakers). Un proveedor que falla o aplica límites de tasa se omite, no se insiste hasta el agotamiento.

• Puedes ver cómo funciona. Una línea de estado, el título de la terminal y una notificación del sistema muestran el último modelo enrutado, el ahorro y el estado de salud — para hosts sin barra de estado nativa.

• Resumen al final de la sesión. Ahorro frente a la línea base, combinación de niveles, coste por proveedor, latencia p50/p95/p99 y rutas más usadas.

• También contenido multimedia y pipelines. llm_image / llm_video / llm_audio, y llm_orchestrate para investigaciones de varios pasos.

CLI

llm-router install      # wire up your host (Claude Code by default)
llm-router health       # provider connectivity
llm-router status       # savings + quota at a glance
llm-router doctor       # diagnose a broken setup

Referencia completa de comandos: guide/GETTING_STARTED.md

Proveedores

Más de 20 proveedores, gratis primero. Ollama (local, gratuito) lidera la cadena; OpenRouter (343 modelos tras una sola clave) es el mayor desbloqueo individual; Gemini y Groq tienen niveles gratuitos utilizables. Anthropic funciona mediante tu suscripción existente de Claude — no se necesita clave de API.

Cada proveedor, sus modelos, su nivel de coste y su variable de entorno: guide/PROVIDERS.md

Políticas de enrutamiento

Una política determina con qué decisión el router desvía el tráfico de tu modelo premium: desde conservative (10–15% de ahorro), pasando por balanced (la predeterminada, 35–45%), hasta cost_aggressive (70–85%, requiere OPENROUTER_API_KEY).

llm-router policy set cost_aggressive

Las seis políticas, sus umbrales y el esquema YAML: guide/POLICIES.md

Herramientas MCP

60 herramientas repartidas entre enrutamiento, análisis, código, contenido multimedia, presupuesto y diagnósticos: expuestas a cualquier host MCP. La superficie consolidated predeterminada muestra 11 herramientas de entrada; configura LLM_ROUTER_SLIM=full para tener las 60.

Cada herramienta con su firma: guide/TOOLS.md

Ahorro: cómo funciona

El ahorro se calcula comparando el gasto real con una línea base de enrutar cada tarea a Claude Sonnet/Opus.

Metodología:

1. Cada tarea enrutada registra: modelo utilizado, tokens consumidos, coste estimado

2. Se calcula un coste de referencia como si los mismos tokens los procesara el modelo más caro de la cadena

3. Ahorro = (baseline - actual) / baseline

Supuestos y limitaciones:

• La línea base asume que habrías usado Opus/Sonnet para todo (peor caso)

• Los cálculos de tokens usan la aproximación len(text) / 4, no recuentos exactos del tokenizador

• Los datos de coste provienen de las tablas de precios de LiteLLM (pueden ir por detrás de los cambios de precios de los proveedores)

• El ahorro varía significativamente según la carga de trabajo: las sesiones con mucho código enrutan más hacia modelos baratos

• El propio router añade una pequeña sobrecarga (la clasificación cuesta ~$0.0001 por tarea ambigua)

Rango observado: 35–80% de ahorro según la política y la combinación de tareas. La cifra «87%» en algunos documentos representa un pico de un solo usuario durante un periodo de desarrollo concreto, no un resultado garantizado.

Confianza, privacidad y diseño local-first

llm-router se ejecuta íntegramente en tu máquina. No hay ningún proxy alojado, ni telemetría, ni se requiere cuenta.

Lo que hacemos:

• Limpiamos las claves de API de los registros estructurados

• Detectamos deadlocks de hooks antes de instalarlos

• Guardamos todos los datos localmente en ~/.llm-router/

• Respetamos los límites de peticiones y los términos de servicio de los proveedores

Lo que debes saber:

• Los prompts se envían al proveedor que seleccione el router — revisa la política de privacidad de tu proveedor

• Los registros de uso (SQLite) no están cifrados en reposo — usa cifrado de disco completo si es necesario

• El router no puede evitar jailbreaks del modelo ni la inyección de prompts a nivel del proveedor

Consulta SECURITY.md para la política de divulgación responsable.

Configuración

Todo se define mediante variables de entorno — no se requiere ningún archivo de configuración para empezar:

export OPENROUTER_API_KEY="sk-or-v1-..."          # biggest single unlock
export OLLAMA_BASE_URL="http://localhost:11434"   # local, free
export LLM_ROUTER_POLICY="cost_aggressive"        # routing policy
export LLM_ROUTER_ENFORCE="smart"                 # off | advise | smart | hard

Referencia completa, esquema de archivo de configuración y anulaciones por host: guide/GETTING_STARTED.md

Documentación

Índice completo: guide/README.md

Empresas

llm-router está creado para desarrolladores individuales y equipos pequeños: ahorro de costes local, cero sobrecarga operativa, nada alojado. Si necesitas aplicación de políticas en todo el equipo, exportación de auditoría, SSO o presupuestos por organización, para eso está Chuzom.

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para ver las directrices completas.

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (1900+)
uv run ruff check src/ tests/   # Lint

-|-----------| | llm-routing | Paquete de PyPI actual (pip install llm-routing) | | llm-router | Comando CLI y nombre del repositorio de GitHub | | claude-code-llm-router | Paquete antiguo obsoleto (redirige a llm-routing) |