feat(proxy): auto-discovery de modelos + backend Kimchi

- Nueva interfaz Discoverer con Refresh() por backend - Kilo: full auto (isFree + metadata completa del upstream) - OpenCode: heurística -free para descubrir nuevos free - Kimchi: agrega todos los IDs no-curados del upstream - discoveryLoop cada 10 min en el Proxy - Backends stateful (mutex + catálogo dinámico) - CREDENCIALES.md y KIMCHI_ANALISIS.md documentan el setup
2026-07-12 19:58:30 -03:00
parent 05a52d29e2
commit 46127431a3
8 changed files with 1041 additions and 29 deletions
@@ -0,0 +1,136 @@
+# Free IDE Proxy — Credenciales y Modelos
+
+## Endpoint
+
+```
+http://127.0.0.1:6446
+```
+
+## Clientes compatibles
+
+Cualquier cliente OpenAI o Anthropic. Apunta la base URL a `http://127.0.0.1:6446`.
+
+### Claude Code
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:6446"
+export ANTHROPIC_MODEL="claude-sonnet-4-6"   # se mapea a deepseek-v4-flash-free
+```
+
+Claude Code agrega `/v1/messages` automáticamente. No pongas `/v1` en la base URL.
+
+### OpenAI SDK
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://127.0.0.1:6446/v1", api_key="...")
+
+response = client.chat.completions.create(
+    model="deepseek-v4-flash-free",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### curl
+
+```bash
+curl http://127.0.0.1:6446/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "deepseek-v4-flash-free",
+    "messages": [{"role": "user", "content": "Hello"}],
+    "stream": true
+  }'
+```
+
+```bash
+curl http://127.0.0.1:6446/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "deepseek-v4-flash-free",
+    "max_tokens": 1000,
+    "messages": [{"role": "user", "content": "Hello"}]
+  }'
+```
+
+## Autenticación
+
+Actualmente: **DESHABILITADA** (sin API key).
+
+Para activar:
+
+```bash
+# Por flag
+./free-ide-proxy -api-key "tu-clave-secreta"
+
+# O por env var
+export OPENCODE_PROXY_KEY="tu-clave-secreta"
+```
+
+Headers aceptados: `Authorization: Bearer <key>` o `x-api-key: <key>`
+
+---
+
+## Modelos disponibles
+
+> **Auto-discovery activo.** El proxy descubre modelos automáticamente cada 10 min desde los `/models` de cada upstream. La lista de abajo es la **base curada** (metadata confiable + aliases); los modelos adicionales descubiertos aparecen en `/v1/models` en runtime. Consultá siempre el endpoint para la lista vigente:
+> ```bash
+> curl -s http://127.0.0.1:6446/v1/models | python3 -m json.tool
+> ```
+>
+> **Estrategia por backend:**
+> - **Kilo** → full auto: parsea `isFree:true` + metadata completa (ctx, max_tokens, vision). Modelos nuevos aparecen solos.
+> - **OpenCode** → heurística: curados + cualquier ID con token `free` (sufijo `-free`/`:free`).
+> - **Kimchi** → todos los IDs del upstream (cuenta por crédito, todos usables).
+
+### OpenCode Zen (`opencode.ai/zen/v1`)
+
+| Modelo ID | Aliases | Contexto | Output | Tags |
+|-----------|---------|----------|--------|------|
+| `deepseek-v4-flash-free` | `deepseek`, `deepseek-v4`, `ds` | 1M | 384K | ⭐ recomendado, razonamiento, propósito general |
+| `big-pickle` | `pickle` | 200K | 32K | legacy, refactors, mantenimiento |
+| `mimo-v2.5-free` | `mimo`, `mimo-v2.5`, `xiaomi` | 1M | 32K | multimodal, imágenes → código, MIT |
+| `north-mini-code-free` | `north`, `north-mini`, `cohere` | 256K | 64K | respuesta rápida, scripts |
+| `nemotron-3-ultra-free` | `nemotron`, `nemotron-3`, `nvidia` | 1M | 16K | razonamiento, Mamba-2 + MoE |
+
+### Kilo Gateway (`api.kilo.ai/api/gateway`)
+
+| Modelo ID | Aliases | Contexto | Output | Tags |
+|-----------|---------|----------|--------|------|
+| `stepfun/step-3.7-flash:free` | `stepfun`, `stepfun-free` | 256K | 32K | flash, tareas generales |
+| `poolside/laguna-m.1:free` | `poolside`, `poolside-free`, `laguna` | 256K | 32K | código |
+| `nvidia/nemotron-3-ultra-550b-a55b:free` | — | 1M | 16K | razonamiento, MoE |
+| `openrouter/free` | `openrouter` | 256K | 32K | selección automática |
+
+> Kilo además **auto-descubre** modelos free adicionales (ej: `kilo-auto/free`, `tencent/hy3:free`, `cohere/north-mini-code:free`, `nvidia/nemotron-3-super-120b-a12b:free`, etc.) con metadata completa del upstream.
+
+### Kimchi Dev (`llm.kimchi.dev/openai/v1`)
+
+| Modelo ID | Aliases | Contexto | Output | Tags |
+|-----------|---------|----------|--------|------|
+| `deepseek-v4-flash` | `kimchi`, `kimchi/deepseek` | 1M | 1M | ⭐ rápido, razonamiento |
+| `glm-5.2-fp8` | `kimchi/glm` | 1M | 1M | GLM, FP8 |
+| `kimi-k2.7` | `kimchi/kimi` | 262K | 262K | Moonshot, visión |
+| `minimax-m3` | `kimchi/minimax` | 1M | 1M | MiniMax, visión |
+| `nemotron-3-ultra-fp4` | `kimchi/nemotron` | 1M | 1M | NVIDIA, FP4 |
+
+> Kimchi auto-descubre **todos** los IDs del upstream (cuenta por crédito). Adicionales típicos: `qwen3-coder-next-fp8`, `nemotron-3-super-fp4`, `kimi-k2.5/k2.6`, `minimax-m2.5/m2.7`, `smollm2-*`. Requiere header `User-Agent: kimchi/0.1.50` (sino el upstream devuelve 402).
+
+### Alias de modelos Claude
+
+| Alias Claude | Se resuelve a |
+|--------------|---------------|
+| `claude-sonnet-4-6` | `deepseek-v4-flash-free` |
+| `claude-sonnet-4` | `deepseek-v4-flash-free` |
+| `claude-3.5-sonnet` | `deepseek-v4-flash-free` |
+| `claude-3-haiku` | `deepseek-v4-flash-free` |
+| `claude-opus` | `deepseek-v4-flash-free` |
+
+## Notas
+
+- **Auto-discovery**: cada 10 min el proxy refresca el catálogo desde los `/models` de cada upstream. Los modelos descubiertos se agregan a `/v1/models` en runtime; la base curada (metadata + aliases) siempre se preserva.
+- **Razonamiento**: DeepSeek, Nemotron y StepFun necesitan `max_tokens >= 500`. Con valores chicos devuelven contenido vacío.
+- **Rate limiting**: si un modelo devuelve 429, se oculta de `/v1/models` y se reintenta cada 30 min.
+- **Modelos nuevos**: los descubiertos rutean a su backend correcto automáticamente. Los totalmente desconocidos se reenvían al backend default (OpenCode Zen) como pass-through.
+- **Session rotation**: las sesiones rotan cada 30 min.
+- **Claude Code**: el proxy también acepta `/v1/v1/messages` por el bug de doble path.