Deadwax

Un bibliotecario musical agéntico sobre un historial de escucha personal. Responde preguntas en lenguaje natural sobre lo que has escuchado y crea listas de reproducción sujetas a restricciones duras — con un validador determinista, un bucle de reparación y una suite de evaluación que informa tasas de aprobado en lugar de aprobado/suspenso.

Construido como pieza de portafolio que demuestra prácticas de ingeniería de LLM en producción: uso de herramientas, recuperación, trazado, evaluación y MCP.

La parte interesante

La mayoría de las demos de LLM funcionan hasta que las ejecutas dos veces. Deadwax está construido en torno a lo que ocurre en la segunda ejecución.

El sistema se divide en una línea: el modelo nunca calcula. Interpreta el lenguaje, elige herramientas y compone prosa. Cada operación aritmética, comprobación de umbrales y adjudicación de restricciones ocurre en Python puro que no tiene idea de que existe un LLM. Cuando una lista de reproducción viola una restricción, el validador no devuelve False — devuelve un código de violación, los ids de las pistas infractoras y un remedio concreto, que es la única razón por la que un bucle de reparación automatizado puede funcionar.

La viabilidad se comprueba antes de la generación. Si un encargo no puede satisfacerse, el sistema lo dice. Nunca rellena, sustituye ni degrada silenciosamente — status="infeasible" es un resultado correcto con sus propios casos de evaluación.

Related MCP server: Navidrome-MCP

Reglas de arquitectura

No son preferencias estilísticas. Violar cualquiera de estas anula el propósito del proyecto.

1. El modelo nunca calcula.

2. Las descripciones de herramientas son control de comportamiento — son prompts, no documentación. Cambiar una es un cambio de comportamiento y se re-evalúa antes de fusionar.

3. Las violaciones son procesables por máquina: un código, los ids infractores, un remedio. Nunca un booleano desnudo, nunca prosa sola.

4. La viabilidad se comprueba antes de la generación.

5. El fracaso es un resultado válido.

6. Las restricciones duras se miden y se hacen cumplir. Las restricciones blandas se infieren y se puntúan, y llevan un campo provenance que cualquier mensaje sobre ellas debe revelar.

7. Ninguna llamada al modelo sin una traza.

Las decisiones y sus compensaciones se documentan en docs/adr.

Stack

Todo se ejecuta en un plan gratuito. Eso es una restricción dura, no una preferencia.

Las etapas 0 a 2 usan solo la biblioteca estándar — sin framework, sin SDK, sin dependencias. La llamada HTTP en bruto se escribe a mano antes de introducir cualquier abstracción, de modo que cuando un framework tergiversa lo que hace, la diferencia es visible.

Progreso de la construcción

Doce etapas, cuatro fases. Una rama y un PR con squash-merge por etapa, de modo que el historial se lee como la construcción realmente ocurrió.

Cómo ejecutarlo

Necesitas uv. Instala y gestiona el propio Python, así que es el único requisito previo.

winget install --id=astral-sh.uv -e

Luego, desde la raíz del repositorio:

uv sync

Eso crea un entorno virtual, instala la versión de Python fijada desde .python-version e instala el proyecto.

Añade una clave gratuita de Gemini API desde Google AI Studio:

copy .env.example .env

Pega la clave después de GEMINI_API_KEY=. Luego mira a qué modelos puede acceder tu clave, ya que los catálogos del plan gratuito cambian sin previo aviso:

uv run scripts/raw_call.py --list

Pon uno de esos ids en .env como GEMINI_MODEL y haz la llamada:

uv run scripts/raw_call.py

Imprime la solicitud completa y la respuesta completa antes de extraer la respuesta. Ese es el objetivo del script — las formas merecen conocerse antes de que un framework las oculte.

Los límites de velocidad reales de tu cuenta se muestran en aistudio.google.com/rate-limit; Google ya no publica una tabla de plan gratuito por modelo en la documentación de la API.

Evaluación

La suite de evaluación llega en la etapa 5. Los casos se escriben a mano y nunca se generan — si la misma herramienta escribe tanto el código como la calificación, la puntuación no significa nada. Las puntuaciones se informan como tasas de aprobado en ejecuciones repetidas, porque un solo aprobado en un sistema no determinista es una anécdota.

Cualquier commit que cambie un prompt, una descripción de herramienta o un modelo lleva puntuaciones de evaluación antes/después en su mensaje.

Licencia

MIT. Consulta LICENSE.

Creado por David Koen.