modelduel 0.6.0__tar.gz

modelduel-0.6.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+runs/
+
+# Demo y clasificación generadas en el CI
+site/demo/
+site/leaderboard/
+.coverage
+.coverage.*
+htmlcov/
+
+# Grafo de conocimiento local (graphify)
+graphify-out/

modelduel-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contribuir a modelduel
+
+Gracias por querer ayudar. Esta guía es breve; las reglas completas del equipo están en [`AGENTS.md`](AGENTS.md) y el estado del proyecto en [`MEMORY.md`](MEMORY.md). Si solo quieres **usar** modelduel, lee [`docs/USO.md`](docs/USO.md).
+
+## Entorno
+
+Necesitas Python 3.12 o superior.
+
+```bash
+git clone https://github.com/BertMarti/modelduel
+cd modelduel
+python -m venv .venv
+source .venv/bin/activate        # Windows (PowerShell): .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+El extra `dev` instala pytest, pytest-cov y ruff. En ejecución el programa solo usa la biblioteca estándar: **no añadas dependencias** sin justificarlo en «Decisiones» de `MEMORY.md`.
+
+## Comandos
+
+Antes de abrir un pull request tienen que pasar los mismos pasos que el CI (Ubuntu y Windows):
+
+```bash
+ruff check .                     # lint
+ruff format --check .            # formato (usa «ruff format .» para aplicarlo)
+pytest --cov                     # tests con cobertura; el mínimo es el 90 %
+modelduel run examples/tasks --model replay:alfa --model replay:beta --model replay:gamma --out runs/demo   # demo
+```
+
+- Los tests **no pueden usar la red** ni claves reales: las APIs se simulan.
+- La demo debe terminar con código 0 y generar `runs/demo/index.html` y `runs/demo/results.json`. El CI comprueba además que `--a`/`--b` sigue dando el «Informe de duelo» (la carpeta `runs/` no se sube al repositorio).
+- El informe HTML y la página de clasificación no pueden contener JavaScript. El CI genera `site/leaderboard` con `modelduel leaderboard results --out site/leaderboard`.
+- `results/` son datos versionados (un `results.json` por duelo o liga): añade ahí los reales con el procedimiento de [`docs/USO.md`](docs/USO.md#clasificación-pública).
+
+## Ramas y pull requests
+
+- **Nunca hagas commit directo a `main`.** Trabaja en una rama (`agent/<rol>/<n>-<slug>` para los agentes, con `<n>` el número del issue, por ejemplo `agent/docs/9-documentacion-v0.2`; `feat/…` o `fix/…` para personas) y abre un pull request.
+- Cambios pequeños y con sentido propio. Describe qué cambia y por qué, y cómo lo has comprobado.
+- Al terminar, actualiza `MEMORY.md` (estado, decisiones, siguiente paso y una línea en «Registro de sesiones»).
+- La documentación y la interfaz, en español; los nombres del código, en inglés.
+- No subas claves, tokens, `.env` ni datos personales: el repositorio es público.
+
+## Commits
+
+[Commits convencionales](https://www.conventionalcommits.org/es/) en español: `feat:`, `fix:`, `test:`, `docs:`, `ci:`, `chore:`, `refactor:`.
+
+```text
+fix: distinguir el timeout de la petición del de los tests
+```
+
+## Añadir un proveedor
+
+Un proveedor es una clase con esta interfaz (`Provider`, en `src/modelduel/providers/base.py`):
+
+```python
+class MiProveedor:
+    spec: str  # "miproveedor:<modelo>", tal como lo escribe la persona usuaria
+
+    def complete(self, prompt: str, *, task_id: str | None = None) -> Response: ...
+```
+
+`Response` lleva `text`, `input_tokens`, `output_tokens` (pueden ser `None` si el proveedor no los da) y `latency_s`. `task_id` solo lo usa `replay`; el resto lo ignora.
+
+1. Crea `src/modelduel/providers/<nombre>.py` (usa como modelo `gemini.py` o `openai_compat.py`). Para HTTP usa `post_json` de `base.py`, que ya convierte los fallos de red y HTTP en `ProviderError` con mensajes en español, y pásale las claves en `secrets` para que se redacten. Lee las claves **solo de variables de entorno** (`require_env`), nunca las pongas en la URL ni en los mensajes de error.
+2. Registra el proveedor en `src/modelduel/providers/__init__.py`: añade su nombre a `PROVIDERS` y una rama en `get_provider`.
+3. Si tiene precios propios o variables nuevas, documéntalo en el README (tabla «Proveedores y variables de entorno») y en `docs/USO.md`.
+4. Escribe los tests en `tests/test_providers.py` **sin red**: simula `urllib.request.urlopen` con el ayudante `_fake_urlopen` del propio archivo y prueba la respuesta buena, la falta de clave, las respuestas vacías o raras y los errores HTTP (401, 429, 5xx).
+
+Toda excepción de un proveedor debe ser `ProviderError`: el duelo la registra como «error del proveedor» y sigue con el resto de intentos.
+
+## Añadir una tarea de ejemplo
+
+Una tarea es una carpeta en `examples/tasks/<id>/` con `task.md`, `test_task.py` y `meta.toml` (formato en el README y en [`docs/USO.md`](docs/USO.md#crear-tu-propia-tarea-paso-a-paso)). Las tareas de ejemplo son **originales**: no copies enunciados ni tests de otras fuentes.
+
+1. Crea los tres archivos. Incluye casos límite y da un `order` y una `difficulty` coherentes con las demás.
+2. Graba una respuesta por contendiente en `examples/replays/alfa/<id>.md` y `examples/replays/beta/<id>.md` (con el front-matter de tokens y latencia). Son ficticias y se escriben a mano.
+3. Actualiza lo que dependa del conjunto de tareas: `tests/test_tasks.py` (orden esperado) y `tests/test_cli.py` (resultados de la demo), además de las cifras del README y de la web (`site/index.html`) si cambian los marcadores.
+4. Comprueba `modelduel list-tasks examples/tasks`, ejecuta la demo y revisa el informe.
+
+## Añadir un color a la paleta de la liga
+
+La liga admite hasta seis contendientes (`A` a `F`), cada uno con un acento. Para subir el máximo y añadir un séptimo (`G`), hay que tocar estos sitios:
+
+1. **Letra:** añade `"g"` a `ALL_SIDES` en `src/modelduel/results.py` (`MAX_CONTENDERS` se calcula solo).
+2. **Color:** en `src/modelduel/report/style.css` añade `--g` en `:root`, las reglas `.g { color: var(--g); }` y `.fill-g { fill: var(--g); }`, y el valor para la hoja de impresión en el `:root` de `@media print`.
+3. **Elige un color que pase el contraste AA** (mínimo 4,5:1): en pantalla, sobre el fondo `#0f0f11` y sobre el panel `#151518`; en impresión, sobre blanco y sobre el panel claro `#f6f6f6`. Además, el valor «perdedor» atenuado (`opacity: .8`) sigue teniendo que llegar a 4,5:1, y el color tiene que distinguirse de los demás (con la letra siempre al lado: el color nunca es la única pista).
+4. **Tests:** `tests/test_league.py` calcula el contraste de toda la paleta (`test_paleta_ampliada_cumple_contraste_aa` y `test_contraste_aa_de_toda_la_paleta_sobre_todos_fondos`) y exige colores distintos: si tu color no cumple, fallan. Varios tests fijan «6» a mano (`_html(make_task, 6)`, «máximo 6», `len(...) == 6`): actualízalos a 7. Ejecuta `pytest tests/test_league.py tests/test_report.py`.
+5. **Documentación:** la paleta aparece en `AGENTS.md` (sección «Diseño»), `docs/USO.md` y el README (límite de seis), y en la web (`site/index.html`).
+
+## Publicar una versión en PyPI (mantenedor)
+
+La publicación es automática y **no usa tokens**: `release.yml` usa *Trusted Publishing* (OIDC) de PyPI, a través del *environment* de GitHub `pypi`.
+
+**Una sola vez (configuración previa):**
+
+1. En PyPI: *Your projects* > *Publishing* > *Add a new pending publisher*, con proyecto `modelduel`, propietario `BertMarti`, repositorio `modelduel`, workflow `release.yml` y environment `pypi`.
+2. En GitHub: *Settings* > *Environments* > crea el environment `pypi` (puedes añadirle revisores obligatorios para aprobar cada publicación).
+
+**En cada versión:**
+
+1. Sube la versión en `src/modelduel/__init__.py` (única fuente: `pyproject.toml` la lee de ahí), pasa la sección «Sin publicar» de `CHANGELOG.md` a la nueva versión con su fecha (y actualiza los enlaces de comparación del final), actualiza `MEMORY.md` y fusiona el PR en `main`.
+2. Crea una *Release* en GitHub sobre un commit de `main`, con una etiqueta `vX.Y.Z` igual a la versión (por ejemplo, `v0.2.0`).
+3. El workflow construye el sdist y la wheel, comprueba que el commit está en `main` y que la etiqueta coincide con la versión, ejecuta `twine check --strict`, prueba la wheel en un entorno limpio y, si todo va bien, publica en PyPI a través del *environment* `pypi`. Sigue el resultado en la pestaña *Actions*.
+4. Comprueba la publicación desde un entorno limpio: `pip install "modelduel[pytest]"` y `modelduel demo`.
+
+Para comprobar el paquete en local sin publicar: `pip install build twine`, `python -m build` y `twine check dist/*`.

modelduel-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Martínez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelduel-0.6.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.5
+Name: modelduel
+Version: 0.6.0
+Summary: Dos modelos, una tarea, los mismos tests: compara modelos de IA programando.
+Project-URL: Homepage, https://bertmarti.github.io/modelduel/
+Project-URL: Documentation, https://github.com/BertMarti/modelduel/blob/main/docs/USO.md
+Project-URL: Source, https://github.com/BertMarti/modelduel
+Project-URL: Issues, https://github.com/BertMarti/modelduel/issues
+Author: Alberto Martínez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,benchmark,cli,coding,evaluation,llm,pytest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == 'pytest'
+Description-Content-Type: text/markdown
+
+# modelduel
+
+**Dos modelos, una tarea, los mismos tests.** `modelduel` enfrenta a dos modelos de IA (o a una liga de hasta seis) con un problema de programación, ejecuta tus tests sobre el código de cada uno y te da un informe con quién acierta, cuánto tarda y cuánto cuesta.
+
+[![CI](https://github.com/BertMarti/modelduel/actions/workflows/ci.yml/badge.svg)](https://github.com/BertMarti/modelduel/actions/workflows/ci.yml)
+[![Licencia MIT](https://img.shields.io/badge/licencia-MIT-b5e853.svg)](https://github.com/BertMarti/modelduel/blob/main/LICENSE)
+![Python 3.12](https://img.shields.io/badge/python-3.12-ff7eb6.svg)
+
+**Web:** <https://bertmarti.github.io/modelduel/> · **[Ver un duelo en directo](https://bertmarti.github.io/modelduel/#demo)** (reproducción pregrabada, sin claves) · **Informe de demostración:** <https://bertmarti.github.io/modelduel/demo/> · **Clasificación pública:** <https://bertmarti.github.io/modelduel/leaderboard/>
+
+**Documentación:** [Guía de uso](https://github.com/BertMarti/modelduel/blob/main/docs/USO.md) (instalación, duelos reales, crear tus tareas, liga, reintentos, reanudación y leer el informe) · [Registro de cambios](https://github.com/BertMarti/modelduel/blob/main/CHANGELOG.md) · [Cómo contribuir](https://github.com/BertMarti/modelduel/blob/main/CONTRIBUTING.md)
+
+```text
+  #   Contendiente     Tareas   Tests   Tiempo   Tokens (ent/sal)        Coste
+  ----------------------------------------------------------------------------
+  1   A replay:alfa       2/3   31/32   10,1 s          1.401/703   0,0017 USD
+  2   C replay:gamma      2/3   30/32    3,7 s          1.314/426   0,0003 USD
+  3   B replay:beta       2/3   30/32   28,1 s        1.373/2.132   0,0248 USD
+  (precios ficticios de demostración)
+```
+
+> [!WARNING]
+> **El código generado por los modelos se ejecuta en tu máquina.** modelduel lo ejecuta siempre en un directorio temporal, en un subproceso con límite de tiempo y sin tus variables de entorno secretas, y al terminar mata todos los procesos que haya lanzado (Job Object en Windows, grupo de procesos en Linux/macOS), pero eso **no es un aislamiento real**: el código puede leer y escribir en el resto del disco, y un proceso que se desligue a propósito (`setsid`, `CREATE_BREAKAWAY_FROM_JOB`) puede sobrevivir. Úsalo solo con tareas de confianza e, idealmente, dentro de un contenedor o una máquina virtual.
+
+## Por qué
+
+Los rankings de modelos miden tareas que no son las tuyas. La forma honesta de elegir es hacer tu propia comparativa: el mismo enunciado, los mismos tests y los números a la vista. modelduel convierte ese ejercicio en una orden.
+
+## Novedades de v0.6.0
+
+- **Informe en Markdown**: `modelduel report results.json --format md --out DIR` (y `run ... --format html,md`) genera `informe.md`, listo para pegar en un PR o un issue de GitHub: marcador, veredicto con su criterio, tabla por tarea y por contendiente, coste y avisos. Todo lo que viene de `results.json` se trata como dato no fiable y se escapa (barras de tabla, backticks, HTML, enlaces, menciones y referencias).
+- Imagen social (`og:image`, `twitter:card`) en la web.
+
+### Antes (v0.5.0)
+
+- **Duelo en directo** en la web: un duelo pregrabado que se reproduce en el navegador (código escribiéndose, tests cayendo, marcador), con pausa y sin servidor ni claves.
+- Informes y portada más legibles: enlaces con foco visible, «▲ mejor» / «▼ peor» con glifo y texto, y una navegación más corta.
+
+### Antes (v0.2.0)
+
+- **Liga de 2 a 6 contendientes** con `--model` repetible: clasificación, comparativa, matriz por tarea y paleta de seis colores con contraste AA (siempre con su letra `A`-`F`).
+- **Reintentos** ante HTTP 429/5xx y cortes de conexión, con espera exponencial y `Retry-After` (`--retries`).
+- **Guardado incremental y `--resume`**: un corte no pierde lo ya hecho y el duelo se continúa con la misma orden.
+- **Publicación en PyPI** (`pip install modelduel`) y **`modelduel demo`**: prueba sin claves ni coste y `demo --copy` para empezar desde una plantilla.
+
+Detalle en el [registro de cambios](https://github.com/BertMarti/modelduel/blob/main/CHANGELOG.md).
+
+## Instalación
+
+Necesitas Python 3.12 o superior. modelduel solo usa la biblioteca estándar; pytest hace falta para ejecutar los tests de las tareas.
+
+```bash
+pip install "modelduel[pytest]"     # o: pip install modelduel pytest
+modelduel demo                       # prueba sin claves ni coste, con los ejemplos incluidos
+```
+
+> [!NOTE]
+> El paquete se publica en PyPI al crearse la *release* `v0.2.0`. Hasta entonces, instálalo desde GitHub: `pip install git+https://github.com/BertMarti/modelduel pytest`.
+
+`modelduel demo` enfrenta a tres modelos ficticios (respuestas grabadas) y escribe el informe en `modelduel-demo/`; `modelduel demo --copy MIS-EJEMPLOS` copia las tareas y respuestas de ejemplo para que las uses como plantilla.
+
+Para desarrollar:
+
+```bash
+git clone https://github.com/BertMarti/modelduel
+cd modelduel
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest --cov
+```
+
+## Uso rápido
+
+```bash
+# Demo sin claves ni coste, con respuestas grabadas: una liga de tres contendientes
+modelduel run examples/tasks --model replay:alfa --model replay:beta --model replay:gamma --out runs/demo
+
+# Dos modelos reales, tres ejecuciones por tarea
+export GEMINI_API_KEY=...        # PowerShell: $env:GEMINI_API_KEY = "..."
+export OPENAI_API_KEY=...
+modelduel run examples/tasks --a gemini:<modelo> --b openai:<modelo> --runs 3 --prices precios.json --out runs/duelo
+
+# Regenerar el HTML a partir de los resultados
+modelduel report runs/duelo/results.json --out runs/duelo
+
+# Informe en Markdown para pegar en un PR o un issue (informe.md)
+modelduel report runs/duelo/results.json --format md --out runs/duelo
+
+# Ver las tareas de una carpeta
+modelduel list-tasks examples/tasks
+```
+
+| Opción | Qué hace |
+|---|---|
+| `--a`, `--b` | Contendientes A y B en formato `proveedor:modelo` (un duelo de dos, como en v0.1.0). |
+| `--model`, `-m` | Contendiente `proveedor:modelo`; repítelo para una **liga de 2 a 6** (se pueden mezclar con `--a`/`--b`: van primero A y B, después cada `--model`). Los nombres repetidos se rechazan; para repetir un modelo usa `--runs`. |
+| `--runs N` | Ejecuciones por tarea (1 por defecto). Una sola ejecución es una señal débil. |
+| `--timeout S` | Límite en segundos para los tests de cada respuesta (20 por defecto). |
+| `--retries N` | Reintentos ante HTTP 429/500/502/503/504 y cortes de conexión, con espera exponencial y respetando `Retry-After` (3 por defecto; `0` los desactiva). |
+| `--resume` | Continúa el duelo de `--out` saltando los intentos ya terminados (ver «Cortes y reanudación»). |
+| `--format F` | Formatos del informe: `html` (por defecto), `md` o `html,md`. `results.json` se guarda siempre. También lo acepta `report`. |
+| `--prices f.json` | Tabla de precios adicional (ver «Coste»). |
+| `--replays DIR` | Carpeta de respuestas grabadas para `replay` (por defecto, `replays/` junto a la carpeta de tareas). |
+| `--out DIR` | Carpeta donde se escriben `results.json` y el informe (`index.html`, `informe.md` o los dos, según `--format`). Se comprueba antes de llamar a las APIs. |
+
+Códigos de salida: `0` duelo completado (aunque los modelos fallen tests), `1` no se pudieron escribir los resultados, `2` error de uso o de configuración (argumentos, tareas, proveedores, precios, `results.json`) y `130` interrumpido con Ctrl+C.
+
+**Liga.** Con tres o más contendientes el informe cambia de forma: una **clasificación** (tareas resueltas, luego tests superados y luego coste, menos es mejor; los empates comparten posición), una comparativa con una barra fina por contendiente y una **matriz por tarea**. Cada contendiente tiene una letra (`A` a `F`) y un color con contraste AA sobre el fondo oscuro (lima, rosa, cian, ámbar, violeta y coral), pero la letra siempre acompaña al color. Con dos contendientes sigue el informe enfrentado de siempre. El coste solo desempata si todos tienen precio y en la misma moneda.
+
+**Cortes y reanudación.** `results.json` se reescribe de forma atómica (archivo temporal y reemplazo) tras cada intento, así que un corte —Ctrl+C, un apagón, una API caída— no pierde lo ya hecho, que además queda reflejado en un informe parcial marcado como «Duelo incompleto». Para continuar, repite la misma orden añadiendo `--resume`: se saltan los intentos terminados, se repiten los que acabaron en «error del proveedor» y se avisa si algo no coincide (tareas modificadas, otro límite de tiempo, otro número de ejecuciones). Si los contendientes son otros, la orden se detiene con un error. Sin `--resume`, modelduel se niega a sobrescribir un duelo incompleto.
+
+El informe `index.html` es un único archivo autocontenido: CSS en línea, gráficas SVG, sin JavaScript y con hoja de impresión clara.
+
+## Formato de una tarea
+
+Una tarea es una carpeta:
+
+```text
+examples/tasks/slugify/
+├── task.md        # enunciado para el modelo: pide una función concreta con nombre y firma
+├── test_task.py   # tests pytest que importan de `solution`
+└── meta.toml      # opcional: title, difficulty, order
+```
+
+```python
+# test_task.py
+from solution import slugify
+
+
+def test_acentos():
+    assert slugify("Canción de Añoranza") == "cancion-de-anoranza"
+```
+
+```toml
+# meta.toml
+title = "Convertir un texto en slug"
+difficulty = "fácil"
+order = 1
+```
+
+modelduel añade al enunciado la instrucción de responder con un único bloque de código Python, extrae el primer bloque `python` (o el único bloque de la respuesta), lo guarda como `solution.py` junto a una copia de `test_task.py` en un directorio temporal y ejecuta `python -m pytest` con límite de tiempo. Los resultados se leen del XML JUnit de pytest. Se distinguen estos casos: tests ejecutados, sin bloque de código, error al importar, tiempo agotado, error al ejecutar (p. ej. una tarea en la que pytest no encuentra tests) y error del proveedor. La salida de pytest se recorta conservando el principio y el final, donde está el resumen.
+
+Los archivos de la tarea se leen en UTF-8 (se acepta el BOM de los editores de Windows) y un `test_task.py` con errores de sintaxis se rechaza antes de llamar a los modelos.
+
+Las tres tareas de ejemplo son originales y de dificultad creciente: `slugify`, `merge_intervals` y `parse_duration`.
+
+## Proveedores y variables de entorno
+
+| Especificación | Qué usa | Variables |
+|---|---|---|
+| `replay:<nombre>` | Respuestas grabadas en `examples/replays/<nombre>/<tarea>.md`, con tokens y latencia en un front-matter. Sin red. | — |
+| `gemini:<modelo>` | API REST `generateContent` de Google Generative Language. | `GEMINI_API_KEY` (obligatoria), `GEMINI_BASE_URL` (opcional) |
+| `openai:<modelo>` | Cualquier API compatible con Chat Completions de OpenAI: OpenAI, OpenRouter, Ollama… | `OPENAI_API_KEY`, `OPENAI_BASE_URL` (por defecto `https://api.openai.com/v1`) |
+| `omniroute:<modelo>` | OmniRoute, router local compatible con OpenAI (`omniroute serve`). | `OMNIROUTE_BASE_URL` (por defecto `http://localhost:20128/v1`), `OMNIROUTE_API_KEY` (opcional) |
+
+- **OpenRouter:** `OPENAI_BASE_URL=https://openrouter.ai/api/v1` y tu clave de OpenRouter en `OPENAI_API_KEY`.
+- **Ollama:** `OPENAI_BASE_URL=http://localhost:11434/v1`. En servidores locales la clave no es obligatoria.
+- `MODELDUEL_HTTP_TIMEOUT` cambia el límite de las peticiones HTTP (180 s por defecto).
+
+Las claves se leen **solo** de variables de entorno: nunca de archivos del repositorio, nunca en la URL (Gemini recibe la clave en una cabecera) y nunca en los mensajes de error ni en el informe. Tampoco llegan al subproceso que ejecuta el código de los modelos.
+
+Formato de una respuesta grabada (`examples/replays/alfa/slugify.md`):
+
+````markdown
+---
+input_tokens: 412
+output_tokens: 188
+latency_s: 2.84
+---
+```python
+def slugify(text: str, separator: str = "-") -> str:
+    ...
+```
+````
+
+## Coste
+
+```text
+coste = entrada / 1e6 × tarifa_entrada + salida / 1e6 × tarifa_salida
+```
+
+Las tarifas son por **millón de tokens**. Como los precios reales cambian a menudo, modelduel no trae precios reales: los pones tú con `--prices`:
+
+```json
+{
+  "_nota": "Precios por millón de tokens. Compruébalos en la web del proveedor.",
+  "openai:mi-modelo": { "input": 0.15, "output": 0.60, "currency": "USD" },
+  "gemini:otro-modelo": { "input": 0.10, "output": 0.40, "currency": "EUR" }
+}
+```
+
+Se busca primero por `proveedor:modelo` y después solo por `modelo`. Si un modelo no tiene precio, o el proveedor no devuelve tokens, el coste es **«sin datos»**: nunca se inventa. Los precios integrados de `replay:alfa` y `replay:beta` son **ficticios** y el informe lo indica.
+
+## Clasificación pública
+
+`modelduel leaderboard results/ --out site/leaderboard` agrega los `results.json` de una carpeta (uno por duelo o liga) y genera una página estática, sin JavaScript, con la clasificación por modelo y el histórico de duelos con enlace a cada informe. El CI la publica en la web a partir de [`results/`](https://github.com/BertMarti/modelduel/tree/main/results), que trae tres resultados de ejemplo con respuestas grabadas; la guía explica [cómo añadir resultados reales](https://github.com/BertMarti/modelduel/blob/main/docs/USO.md#clasificación-pública).
+
+## Más documentación
+
+- [`docs/USO.md`](https://github.com/BertMarti/modelduel/blob/main/docs/USO.md): guía para personas usuarias, paso a paso y con solución de problemas.
+- [`CHANGELOG.md`](https://github.com/BertMarti/modelduel/blob/main/CHANGELOG.md): qué trae cada versión.
+- [`CONTRIBUTING.md`](https://github.com/BertMarti/modelduel/blob/main/CONTRIBUTING.md): entorno, comandos, ramas, commits, cómo añadir un proveedor, una tarea o un color a la liga, y cómo publicar una versión.
+
+## Estructura
+
+```text
+src/modelduel/
+├── cli.py              # run, report, leaderboard, list-tasks, demo
+├── tasks.py            # carga de tareas y recuento de tests
+├── extract.py          # extracción del bloque de código
+├── runner.py           # prompt + ejecución de pytest en temporal con límite
+├── duel.py             # orquestación del duelo
+├── resume.py           # reanudación de un duelo interrumpido
+├── demo.py             # localiza los ejemplos incluidos (modelduel demo)
+├── results.py          # results.json y resumen del marcador
+├── pricing.py          # tarifas y fórmula de coste
+├── providers/          # replay, gemini, openai_compat (openai y omniroute)
+├── leaderboard.py      # clasificación pública: agregado de results/*.json y página estática
+└── report/             # informe HTML (duelo de dos y liga de 3 a 6, string.Template + SVG) y Markdown (`markdown.py`)
+docs/USO.md             # guía de uso para personas usuarias
+CHANGELOG.md            # registro de cambios (Keep a Changelog)
+examples/tasks/         # tareas originales de ejemplo
+examples/replays/       # respuestas grabadas de alfa, beta y gamma
+site/                   # web del proyecto (la demo se genera en el CI)
+tests/                  # pytest, sin llamadas de red
+```
+
+## Stack
+
+- Python 3.12, solo biblioteca estándar en ejecución (`argparse`, `urllib`, `string.Template`, `xml.etree`, `tomllib`).
+- pytest para los tests y para ejecutar las tareas; ruff para lint y formato.
+- GitHub Actions: CI en Ubuntu y Windows, y despliegue en GitHub Pages de la web y del informe de demostración.
+
+## Cómo se ha construido
+
+Este proyecto lo ha desarrollado un **equipo de agentes de IA** (Claude Code), cada uno en su rama y con pull requests, **supervisado por Alberto Martínez**, que revisa y fusiona todo:
+
+- **v0.1.0:** lead, builder y qa con Claude Opus; la documentación (docs), con Claude Sonnet.
+- **v0.2.0:** todo con Claude Sonnet, guiado por issues del hito y un pull request por issue.
+- **OpenCode** estaba previsto para la documentación, pero no pudo ejecutarse en modo autónomo, así que la escribe Claude Code. Las decisiones y el estado del proyecto están en [`MEMORY.md`](https://github.com/BertMarti/modelduel/blob/main/MEMORY.md) y las reglas del equipo en [`AGENTS.md`](https://github.com/BertMarti/modelduel/blob/main/AGENTS.md).
+
+## Licencia
+
+[MIT](https://github.com/BertMarti/modelduel/blob/main/LICENSE).