Deadwax

個人のリスニング履歴に対するエージェント型ミュージックライブラリアンです。何を聴いたかについての自然言語の質問に答え、厳格な制約に基づいてプレイリストを構築します。決定的なバリデーター、修復ループ、そして合格/不合格ではなく合格率を報告する評価スイートを備えています。

ツール使用、検索、トレーシング、評価、MCPといった本番レベルのLLMエンジニアリング実践を示すポートフォリオ作品として構築されました。

面白い部分

ほとんどのLLMデモは、2回実行するまでは機能します。Deadwaxは、2回目の実行で何が起こるかを中心に構築されています。

システムは一線で分割されています。モデルは決して計算しません。 モデルは言語を解釈し、ツールを選択し、散文を構成します。すべての算術演算、閾値チェック、制約の判定は、LLMの存在を知らない素のPythonで行われます。プレイリストが制約に違反した場合、バリデーターはFalseを返すのではなく、違反コード、問題のトラックID、具体的な修正方法を返します。これこそが、自動修復ループが機能する唯一の理由です。

実現可能性は生成の前にチェックされます。ブリーフを満たせない場合、システムはその旨を明言します。パディング、代替、黙っての劣化は決して行いません。status="infeasible"は、独自の評価ケースを持つ正しい結果です。

Related MCP server: Navidrome-MCP

アーキテクチャのルール

スタイル上の好みではありません。これらに違反すると、プロジェクトの目的が損なわれます。

1. モデルは決して計算しない。

2. ツールの説明は動作の制御です。プロンプトであり、ドキュメントではありません。変更は動作の変更であり、マージ前に再評価されます。

3. 違反は機械が実行可能な形で示されます。コード、問題のID、修正方法。裸のブール値や散文だけでは不十分です。

4. 実現可能性は生成前にチェックされます。

5. 失敗は有効な結果です。

6. ハード制約は測定され、強制されます。ソフト制約は推論され、スコア化され、それについてのメッセージは必ず開示しなければならないprovenanceフィールドを持ちます。

7. トレースなしのモデル呼び出しはありません。

決定とそのトレードオフはdocs/adrに記録されています。

スタック

すべて無料枠で動作します。これは好みではなく、厳格な制約です。

ステージ0から2までは標準ライブラリのみを使用します。フレームワーク、SDK、依存関係はありません。生のHTTP呼び出しは、抽象化が導入される前に手書きで行われます。これにより、フレームワークが実際の動作を誤って表現した場合に、その違いが明確になります。

ビルドの進捗

12のステージ、4つのフェーズ。各ステージにつき1つのブランチと1つのスカッシュマージPRがあり、履歴は実際のビルドの進行を反映しています。

実行方法

uvが必要です。uvはPython自体をインストールおよび管理するため、唯一の前提条件です。

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

次に、リポジトリのルートから:

uv sync

これにより仮想環境が作成され、.python-versionから固定されたPythonバージョンがインストールされ、プロジェクトがインストールされます。

Google AI Studioから無料のGemini APIキーを追加します:

copy .env.example .env

GEMINI_API_KEY=の後にキーを貼り付けます。次に、無料枠のカタログは予告なく変更されるため、キーがアクセスできるモデルを確認します:

uv run scripts/raw_call.py --list

そのIDのいずれかを.envにGEMINI_MODELとして設定し、呼び出しを実行します:

uv run scripts/raw_call.py

このスクリプトは、回答を抽出する前に完全なリクエストと完全なレスポンスを出力します。これがスクリプトの要点です。フレームワークがそれらを隠す前に、その形状を知っておく価値があります。

アカウントの実際のレート制限はaistudio.google.com/rate-limitに表示されます。GoogleはAPIドキュメントでモデルごとの無料枠テーブルを公開しなくなりました。

評価

評価スイートはステージ5で導入されます。ケースは手書きであり、決して生成されません。同じツールがコードと採点の両方を書く場合、スコアは意味を持ちません。スコアは繰り返し実行の合格率として報告されます。非決定的システムでの1回の合格は逸話に過ぎないからです。

プロンプト、ツールの説明、またはモデルを変更するコミットには、そのメッセージに変更前後の評価スコアが含まれます。

ライセンス

MIT。 LICENSE を参照してください。

David Koen によって構築されました。