Deadwax

Агентный музыкальный библиотекарь для личной истории прослушиваний. Он отвечает на вопросы на естественном языке о том, что вы слушали, и собирает плейлисты с учётом жёстких ограничений — с детерминированным валидатором, циклом восстановления и набором для оценки, который сообщает показатели успешных прохождений, а не просто «прошло/не прошло».

Создан как портфолио-проект, демонстрирующий практику промышленной разработки LLM: использование инструментов, поиск, трассировку, оценку и MCP.

Самое интересное

Большинство LLM-демо работают, пока не запустишь их дважды. Deadwax построен вокруг того, что происходит при втором запуске.

Система разделена одной линией: модель никогда не вычисляет. Она интерпретирует язык, выбирает инструменты и составляет прозу. Каждая арифметическая операция, проверка порогов и разрешение ограничений выполняются в обычном Python, который понятия не имеет о существовании LLM. Когда плейлист нарушает ограничение, валидатор не возвращает False — он возвращает код нарушения, идентификаторы треков-нарушителей и конкретное исправление, и только поэтому автоматический цикл восстановления вообще может работать.

Выполнимость проверяется до генерации. Если бриф невозможно удовлетворить, система прямо об этом говорит. Она никогда не дополняет, не подменяет и не деградирует молча — status="infeasible" — это корректный результат со своими собственными оценочными кейсами.

Related MCP server: Navidrome-MCP

Правила архитектуры

Это не стилистические предпочтения. Нарушение любого из этих правил сводит на нет цель проекта.

1. Модель никогда не вычисляет.

2. Описания инструментов — это управление поведением: они являются промптами, а не документацией. Изменение любого из них — это изменение поведения, и оно переоценивается перед слиянием.

3. Нарушения должны быть машинообрабатываемыми: код, идентификаторы нарушителей, исправление. Никогда — голое булево значение, никогда — только проза.

4. Выполнимость проверяется до генерации.

5. Неудача — допустимый результат.

6. Жёсткие ограничения измеряются и обеспечиваются. Мягкие ограничения выводятся и оцениваются и несут поле provenance, которое должно быть раскрыто в любом сообщении о них.

7. Ни одного вызова модели без трассировки.

Решения и их компромиссы задокументированы в docs/adr.

Стек

Всё работает на бесплатном тарифе. Это жёсткое ограничение, а не предпочтение.

Этапы с 0 по 2 используют только стандартную библиотеку — никаких фреймворков, SDK и зависимостей. Сырой HTTP-вызов пишется вручную до введения каких-либо абстракций, чтобы, когда фреймворк искажает то, что он делает, разница была видна.

Ход разработки

Двенадцать этапов, четыре фазы. Одна ветка и один PR со squash-merge на каждый этап, так что история читается так, как реально шла разработка.

Запуск

Вам понадобится uv. Он устанавливает и управляет самим Python, так что это единственное необходимое условие.

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

Затем, из корня репозитория:

uv sync

Это создаёт виртуальное окружение, устанавливает зафиксированную версию Python из .python-version и устанавливает проект.

Добавьте бесплатный API-ключ Gemini из Google AI Studio:

copy .env.example .env

Вставьте ключ после GEMINI_API_KEY=. Затем посмотрите, к каким моделям ваш ключ имеет доступ, поскольку каталоги бесплатного тарифа меняются без предупреждения:

uv run scripts/raw_call.py --list

Поместите один из этих идентификаторов в .env как GEMINI_MODEL и выполните вызов:

uv run scripts/raw_call.py

Он выводит полный запрос и полный ответ перед извлечением ответа. В этом и смысл скрипта — структуры стоит знать, прежде чем фреймворк их скроет.

Фактические лимиты запросов вашего аккаунта показаны на aistudio.google.com/rate-limit; Google больше не публикует таблицу бесплатных тарифов по моделям в документации API.

Оценка

Оценочный набор появляется на этапе 5. Кейсы пишутся вручную и никогда не генерируются — если один и тот же инструмент пишет и код, и оценку, результат ничего не значит. Результаты сообщаются как доля успешных прохождений по множественным запускам, потому что единственное успешное прохождение на недетерминированной системе — это анекдот.

Любой коммит, который меняет промпт, описание инструмента или модель, должен содержать в сообщении оценки до/после.

Лицензия

MIT. См. LICENSE.

Создано David Koen.