provider-commander
Orquestador multi-agente sobre todas las APIs del usuario. Secreta las llaves fuera del
prompt, elige modelo por tarea (gratis primero) y ejecuta en paralelo con resiliencia.
Pipeline
- Descubrimiento —
discover.py --path <repo>: escaneo estatico de llaves
(regex por proveedor). Salida enmascarada, nunca valores completos.
- Validacion —
catalog.py: sondea cada llave y el catalogo de modelos gratis
disponible ahora. Escribe commander/catalog.json.
- Planificacion —
registry.json: cadena de fallback y tabla routing por tipo de
tarea.
- Ejecucion —
orchestrator.py: reparte tareas en paralelo, rota llaves, aplica
throttling, circuit breaker, backoff y fallback.
- Auditoria —
references/usage.json: llamadas, tokens y coste estimado por llave.
references/last_run.json: resultados con la cadena tried.
Capacidades de seguridad (implementadas)
- Secretos fuera del prompt: las llaves solo viven en env. Nunca se pasan al texto.
- Enmascarado de logs:
mask() sustituye cualquier valor de llave o patron
sk-or-v1-, nvapi-, gsk_, etc. en la salida de los proveedores.
- Tool abstraction: el sub-agente recibe tarea; el orquestador resuelve llave.
- Aislamiento de contexto: cada tarea es independiente; solo se agrega el resultado.
- State cleanup: el estado vive en memoria del proceso y muere al terminar.
Capacidades de resiliencia (implementadas)
- Throttling por proveedor con ventana deslizante de 60s (
rpm del registry).
- Rotacion round-robin de llaves del mismo proveedor (OpenRouter x3, NVIDIA x2).
- Circuit breaker por llave: 2 fallos consecutivos de red/HTTP -> 60s de cooldown;
si todas las llaves del proveedor abren, el proveedor se salta.
- Backoff exponencial: 1s, 2s, 4s.
- Fallback en cadena por tipo de tarea (hasta 7 eslabones).
- Tracking de coste por llave y global.
Uso
cd ~/.config/opencode/skills/provider-commander/scripts
python discover.py --path C:\ruta\repo --out inventory.json # escanear llaves
python catalog.py # modelos gratis en vivo
python orchestrator.py --dry-run --tasks tasks.json # simulacion, coste 0
python orchestrator.py --tasks tasks.json # real, gratis primero
python orchestrator.py --compare "prompt" --providers groq,zai,openrouter
Registry (registry.json)
chain: orden de fallback global.providers: base, api, env vars, rpm, tier, coste, disabled+reason.routing: tipo de tarea -> lista ordenada de (proveedor, modelo).
Deshabilitados con motivo: cerebras (402), google (key invalida), openai (401),
openzen (DNS).
Contrato de agente
Ver references/agent-contract.md (JSON schema de Task/Result, invariantes).
Inventario de llaves
Ver references/keys.md. Resumen: OpenRouter 4 (3 vivas), NVIDIA 2, y una por proveedor
en Groq, Morph, DeepSeek, Z.ai, Anthropic. Alias detectados por hash.
Reglas
- Gratis primero; subir tier solo justificado.
- Nunca Qwen / Alibaba / Bailian.
max_tokens >= 2000 con modelos de razonamiento.- No escribir valores de llaves en disco: solo nombres de variable.
- Z.ai
glm-4.5-flash es gratis pero lento (~200s); usar Groq para lo que importe latencia.
Estructura
provider-commander/
SKILL.md
scripts/ discover.py · catalog.py · orchestrator.py · providers.py · commander.py · registry.json
references/ keys.md · agent-contract.md · usage.json · last_run.json
commander/ keys_inventory.json · catalog.json (estado runtime)
1---2name: provider-commander3description: Orquestador multi-proveedor con gestion de secretos, enmascarado de logs, throttling, rotacion de llaves, circuit breaker, backoff, fallback y tracking de coste. Descubre llaves en repos, sondea el catalogo de modelos gratis en vivo y reparte tareas en paralelo al modelo mas barato capaz. Trigger: 'comandante', 'orquestador', 'todas las apis', 'reparte tareas', 'fan-out', 'paralelo', 'multi-proveedor', 'que modelos gratis hay', 'organiza las llaves', 'varias keys del mismo proveedor', 'escanea llaves'.4---56# provider-commander78Orquestador multi-agente sobre todas las APIs del usuario. Secreta las llaves fuera del9prompt, elige modelo por tarea (gratis primero) y ejecuta en paralelo con resiliencia.1011## Pipeline12131. **Descubrimiento** — `discover.py --path <repo>`: escaneo estatico de llaves14 (regex por proveedor). Salida enmascarada, nunca valores completos.152. **Validacion** — `catalog.py`: sondea cada llave y el catalogo de modelos gratis16 disponible **ahora**. Escribe `commander/catalog.json`.173. **Planificacion** — `registry.json`: cadena de fallback y tabla `routing` por tipo de18 tarea.194. **Ejecucion** — `orchestrator.py`: reparte tareas en paralelo, rota llaves, aplica20 throttling, circuit breaker, backoff y fallback.215. **Auditoria** — `references/usage.json`: llamadas, tokens y coste estimado por llave.22 `references/last_run.json`: resultados con la cadena `tried`.2324## Capacidades de seguridad (implementadas)2526- **Secretos fuera del prompt**: las llaves solo viven en env. Nunca se pasan al texto.27- **Enmascarado de logs**: `mask()` sustituye cualquier valor de llave o patron28 `sk-or-v1-`, `nvapi-`, `gsk_`, etc. en la salida de los proveedores.29- **Tool abstraction**: el sub-agente recibe tarea; el orquestador resuelve llave.30- **Aislamiento de contexto**: cada tarea es independiente; solo se agrega el resultado.31- **State cleanup**: el estado vive en memoria del proceso y muere al terminar.3233## Capacidades de resiliencia (implementadas)3435- **Throttling** por proveedor con ventana deslizante de 60s (`rpm` del registry).36- **Rotacion round-robin** de llaves del mismo proveedor (OpenRouter x3, NVIDIA x2).37- **Circuit breaker** por llave: 2 fallos consecutivos de red/HTTP -> 60s de cooldown;38 si todas las llaves del proveedor abren, el proveedor se salta.39- **Backoff exponencial**: 1s, 2s, 4s.40- **Fallback en cadena** por tipo de tarea (hasta 7 eslabones).41- **Tracking de coste** por llave y global.4243## Uso4445```bash46cd ~/.config/opencode/skills/provider-commander/scripts4748python discover.py --path C:\ruta\repo --out inventory.json # escanear llaves49python catalog.py # modelos gratis en vivo50python orchestrator.py --dry-run --tasks tasks.json # simulacion, coste 051python orchestrator.py --tasks tasks.json # real, gratis primero52python orchestrator.py --compare "prompt" --providers groq,zai,openrouter53```5455## Registry (registry.json)5657- `chain`: orden de fallback global.58- `providers`: base, api, env vars, rpm, tier, coste, disabled+reason.59- `routing`: tipo de tarea -> lista ordenada de (proveedor, modelo).6061Deshabilitados con motivo: cerebras (402), google (key invalida), openai (401),62openzen (DNS).6364## Contrato de agente6566Ver `references/agent-contract.md` (JSON schema de Task/Result, invariantes).6768## Inventario de llaves6970Ver `references/keys.md`. Resumen: OpenRouter 4 (3 vivas), NVIDIA 2, y una por proveedor71en Groq, Morph, DeepSeek, Z.ai, Anthropic. Alias detectados por hash.7273## Reglas7475- Gratis primero; subir tier solo justificado.76- Nunca Qwen / Alibaba / Bailian.77- `max_tokens >= 2000` con modelos de razonamiento.78- No escribir valores de llaves en disco: solo nombres de variable.79- Z.ai `glm-4.5-flash` es gratis pero lento (~200s); usar Groq para lo que importe latencia.8081## Estructura8283```84provider-commander/85 SKILL.md86 scripts/ discover.py · catalog.py · orchestrator.py · providers.py · commander.py · registry.json87 references/ keys.md · agent-contract.md · usage.json · last_run.json88commander/ keys_inventory.json · catalog.json (estado runtime)89```
belentani7