Deadwax

Ein agentischer Musik-Bibliothekar über einem persönlichen Hörverlauf. Er beantwortet natürlichsprachliche Fragen zu dem, was du gehört hast, und erstellt Playlists unter harten Beschränkungen – mit einem deterministischen Validator, einer Reparaturschleife und einer Evaluationssuite, die Pass-Raten statt Pass/Fail meldet.

Als Portfolio-Projekt gebaut, das die Praxis der LLM-Entwicklung in der Produktion demonstriert: Werkzeugnutzung, Abruf, Tracing, Evaluierung und MCP.

Der interessante Teil

Die meisten LLM-Demos funktionieren, bis man sie zweimal ausführt. Deadwax ist um das herum gebaut, was beim zweiten Lauf passiert.

Das System ist entlang einer Linie geteilt: Das Modell rechnet nie. Es interpretiert Sprache, wählt Werkzeuge und verfasst Prosa. Jede arithmetische Operation, Schwellenwertprüfung und Beschränkungsentscheidung passiert in einfachem Python, das keine Ahnung hat, dass ein LLM existiert. Wenn eine Playlist eine Beschränkung verletzt, gibt der Validator nicht False zurück – er gibt einen Verletzungscode, die betreffenden Track-IDs und eine konkrete Abhilfe zurück, was der einzige Grund ist, warum eine automatisierte Reparaturschleife überhaupt funktionieren kann.

Die Machbarkeit wird vor der Generierung geprüft. Wenn ein Brief nicht erfüllt werden kann, sagt das System das. Es füllt nie auf, ersetzt nicht und degradiert nicht stillschweigend – status="infeasible" ist ein korrektes Ergebnis mit eigenen Evaluationsfällen.

Related MCP server: Navidrome-MCP

Architekturregeln

Keine stilistischen Vorlieben. Die Verletzung einer dieser Regeln macht den Zweck des Projekts zunichte.

1. Das Modell rechnet nie.

2. Werkzeugbeschreibungen sind Verhaltenskontrolle – sie sind Prompts, keine Dokumentation. Eine Änderung ist eine Verhaltensänderung und wird vor dem Mergen neu evaluiert.

3. Verletzungen sind maschinenverwertbar: ein Code, die betreffenden IDs, eine Abhilfe. Nie ein nackter Boolean, nie nur Prosa.

4. Die Machbarkeit wird vor der Generierung geprüft.

5. Fehlschlag ist ein gültiges Ergebnis.

6. Harte Beschränkungen werden gemessen und durchgesetzt. Weiche Beschränkungen werden abgeleitet und bewertet und tragen ein provenance-Feld, das jede Nachricht über sie offenlegen muss.

7. Kein Modellaufruf ohne Trace.

Entscheidungen und ihre Abwägungen sind in docs/adr festgehalten.

Stack

Alles läuft auf einem kostenlosen Tarif. Das ist eine harte Beschränkung, keine Vorliebe.

Die Stufen 0 bis 2 verwenden nur die Standardbibliothek – kein Framework, kein SDK, keine Abhängigkeiten. Der rohe HTTP-Aufruf wird von Hand geschrieben, bevor eine Abstraktion eingeführt wird, damit der Unterschied sichtbar ist, wenn ein Framework falsch darstellt, was es tut.

Baufortschritt

Zwölf Stufen, vier Phasen. Ein Branch und ein Squash-Merge-PR pro Stufe, damit die Historie so liest, wie der Bau tatsächlich passiert ist.

Ausführen

Du brauchst uv. Es installiert und verwaltet Python selbst, also ist es die einzige Voraussetzung.

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

Dann, vom Repository-Root aus:

uv sync

Das erstellt eine virtuelle Umgebung, installiert die festgelegte Python-Version aus .python-version und installiert das Projekt.

Füge einen kostenlosen Gemini-API-Schlüssel von Google AI Studio hinzu:

copy .env.example .env

Füge den Schlüssel nach GEMINI_API_KEY= ein. Dann sieh nach, welche Modelle dein Schlüssel erreichen kann, da sich die Kataloge des kostenlosen Tarifs ohne Vorankündigung ändern:

uv run scripts/raw_call.py --list

Setze eine dieser IDs in .env als GEMINI_MODEL und führe den Aufruf aus:

uv run scripts/raw_call.py

Es gibt die vollständige Anfrage und die vollständige Antwort aus, bevor die Antwort extrahiert wird. Das ist der Sinn des Skripts – die Formen sind es wert, zu wissen, bevor ein Framework sie versteckt.

Die tatsächlichen Ratenlimits deines Kontos werden unter aistudio.google.com/rate-limit angezeigt; Google veröffentlicht keine Tabelle mehr pro Modell für den kostenlosen Tarif in der API-Dokumentation.

Evaluierung

Die Evaluationssuite kommt in Stufe 5. Fälle werden von Hand geschrieben und nie generiert – wenn dasselbe Werkzeug sowohl den Code als auch die Bewertung schreibt, bedeutet die Punktzahl nichts. Punktzahlen werden als Pass-Raten über wiederholte Läufe berichtet, denn ein einzelner Pass auf einem nicht-deterministischen System ist eine Anekdote.

Jeder Commit, der einen Prompt, eine Werkzeugbeschreibung oder ein Modell ändert, trägt Vorher/Nachher-Evaluierungspunktzahlen in seiner Nachricht.

Lizenz

MIT. Siehe LICENSE.

Erstellt von David Koen.