Sobre el proyecto

# Weave Router **Un endpoint. Cada modelo. Siempre el correcto.** Weave Router es un proxy integrable para Anthropic, OpenAI y Gemini que selecciona automáticamente el mejor modelo para cada solicitud. En lugar de usar un prompt basado en intuición, utiliza un pequeño embedder local con un cluster scorer derivado del artículo de investigación [Avengers-Pro](https://arxiv.org/abs/2508.12631) para dirigir cada solicitud al modelo correcto de entre tus proveedores habilitados. ## Características principales - **Enruta por acción** — Un cluster scorer selecciona el modelo correcto para cada solicitud de API upstream, enrutando por acción en lugar de por turno. - **Habla la API de todos** — Compatible con Anthropic Messages, OpenAI Chat Completions y las APIs nativas de Gemini, incluyendo streaming, herramientas y visión. - **También conoce OSS** — DeepSeek, Kimi, GLM, Qwen, Llama y Mistral vía OpenRouter o cualquier endpoint compatible con OpenAI. - **BYOK por defecto** — Las claves de los proveedores permanecen en tu máquina, cifradas en reposo. - **Observable** — Trazas OTLP listas para usar, visualizables en el panel de Weave o en cualquier recolector compatible con OTLP como Honeycomb, Datadog o Grafana. ## Inicio rápido La forma más rápida de empezar es con el Weave Router alojado: ```bash npx @weave-os/router ``` El instalador pregunta qué herramienta (Claude Code, Codex, opencode o pi), te guía por el alcance (usuario vs. proyecto), obtiene una clave de enrutador y configura el archivo correcto. Otras variantes incluyen: ```bash npx @weave-os/router --claude # omitir el selector, Claude Code npx @weave-os/router --codex # omitir el selector, OpenAI Codex CLI npx @weave-os/router --opencode # omitir el selector, opencode npx @weave-os/router --pi # omitir el selector, pi + Loom UI npx @weave-os/router --scope project # por repositorio, confirma settings.json npx @weave-os/router --local # autoinstalado localhost:8080 npx @weave-os/router --base-url https://router.acme.internal npx @weave-os/router@0.1.0 # fijar una versión ``` Requiere Node ≥ 18. La referencia completa de flags está en [install/npm/README.md](install/npm/README.md). ## Autoinstalación Para ejecutar el enrutador y el panel en tu propia máquina: ```bash # 1. Coloca una clave de proveedor. OpenRouter es la línea base recomendada. echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local # 2. Establece una contraseña para el panel. echo "ROUTER_ADMIN_PASSWORD=replace-with-a-strong-password" >> .env.local # 3. Inicia Postgres + enrutador en :8080 y genera una clave rk_. make full-setup ``` El enrutador está disponible en http://localhost:8080, el panel en http://localhost:8080/ui/, y tu clave `rk_...` se muestra en los logs. ### Ejemplo de llamadas a la API ```bash # Llámalo como Anthropic curl -sS http://localhost:8080/v1/messages \ -H "Authorization: Bearer rk_..." \ -d '{"model":"claude-sonnet-4-5","max_tokens":256, "messages":[{"role":"user","content":"hi"}]}' # ...o como OpenAI curl -sS http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer rk_..." \ -d '{"model":"gpt-4o-mini", "messages":[{"role":"user","content":"hi"}]}' # Consulta la decisión de enrutamiento sin proxy curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_..." -d '...' ``` ## Arquitectura Solo las cajas grises están fuera de tu máquina. El enrutador, el scorer, Postgres y tus claves de proveedor permanecen locales; los prompts van del enrutador directamente al proveedor que configuraste, nunca a Weave. ```mermaid flowchart LR client["Claude Code, Codex, opencode,<br/>pi, Cursor, tu propia app"] router["Router :8080<br/>/v1/messages · /v1/chat/completions<br/>/v1beta/models · /v1/route"] scorer["Cluster scorer<br/>embedder ONNX en proceso"] hmm["Sidecar de política HMM :8093<br/>opcional, make up-hmm"] pg[("Postgres<br/>instalaciones, claves rk_,<br/>claves BYOK cifradas, uso")] ui["Panel /ui<br/>solo modo autoinstalado"] providers["Anthropic · OpenAI · Gemini<br/>OpenRouter y cualquier<br/>endpoint compatible con OpenAI"] otel["Tu recolector OTLP<br/>Honeycomb, Datadog, Grafana"] client -->|"rk_… bearer token,<br/>respuesta en streaming de vuelta"| router router -->|"embeber y evaluar la acción"| scorer router -.->|"ROUTER_DEFAULT_STRATEGY=hmm"| hmm router -->|"auth, config, uso"| pg pg --> ui router -->|"clave de proveedor desde env o BYOK"| providers router -.->|"spans y logs de uso"| otel ``` Los despliegues multi-réplica también necesitan Pub/Sub (`PUBSUB_*`) para la invalidación de caché; `docker compose` ejecuta el emulador por ti. ## Opcional: Sidecar de política HMM El stack por defecto utiliza el cluster scorer en proceso. Para ejecutar la política HMM congelada como un contenedor companion, añade una clave de Google API y usa el target opt-in: ```bash echo 'GOOGLE_API_KEY=...' >> .env.local make up-hmm ``` Esto no cambia la estrategia por defecto. Consulta [sidecars/hmm/README.md](sidecars/hmm/README.md) para la verificación de artefactos, compatibilidad de embeddings y selección explícita de HMM. ## Integración con herramientas **Claude Code.** Ejecuta `make install-cc` para conectar Claude Code al enrutador local autoinstalado (también se invoca automáticamente al final de `make full-setup`). Para el enrutador alojado, usa `npx @weave-os/router` de arriba. **Codex** (OpenAI CLI). `npx @weave-os/router --codex` modifica `~/.codex/config.toml` (o `<repo>/.codex/config.toml` con `--scope project`) con un bloque `[model_providers.weave]` gestionado y establece `model_provider = "weave"`. El proveedor preserva el inicio de sesión OAuth de ChatGPT existente de Codex mientras la clave del enrutador viaja en un header HTTP `X-Weave-Router-Key`. ## Licencia Licenciado bajo Elastic License v2 (ELv2). --- *Construido por [Weave](https://www.workweave.ai): La plataforma #1 de inteligencia de ingeniería, amada por Robinhood, PostHog, Reducto y cientos más.*