Deadwax

개인 청취 기록을 다루는 에이전틱 음악 사서입니다. 무엇을 들었는지에 대한 자연어 질문에 답하고, 하드 제약 조건에 맞춰 재생 목록을 만듭니다. 결정론적 검증기, 복구 루프, 그리고 통과/실패가 아닌 통과 비율을 보고하는 평가 스위트를 갖추고 있습니다.

도구 사용, 검색, 추적, 평가, MCP 등 프로덕션 LLM 엔지니어링 실무를 보여주는 포트폴리오 작품으로 제작되었습니다.

흥미로운 부분

대부분의 LLM 데모는 두 번 실행하기 전까지만 작동합니다. Deadwax는 두 번째 실행에서 일어나는 일을 중심으로 설계되었습니다.

시스템은 한 가지 기준으로 나뉩니다: 모델은 절대 계산하지 않습니다. 모델은 언어를 해석하고, 도구를 선택하며, 산문을 작성합니다. 모든 산술 연산, 임계값 검사, 제약 조건 판정은 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개 페이즈. 각 단계마다 하나의 브랜치와 하나의 스쿼시 병합 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

답변을 추출하기 전에 전체 요청과 전체 응답을 출력합니다. 이것이 스크립트의 핵심입니다. 프레임워크가 숨기기 전에 그 형태를 알아 둘 가치가 있습니다.

계정의 실제 rate limit은 aistudio.google.com/rate-limit에서 확인할 수 있습니다. Google은 더 이상 API 문서에 모델별 무료 티어 표를 게시하지 않습니다.

평가

평가 스위트는 5단계에서 도입됩니다. 케이스는 직접 작성되며 절대 생성되지 않습니다 — 같은 도구가 코드와 채점을 모두 작성한다면 점수는 의미가 없습니다. 점수는 반복 실행에 걸친 통과 비율로 보고됩니다. 비결정적 시스템에서의 단일 통과는 일화에 불과하기 때문입니다.

프롬프트, 도구 설명 또는 모델을 변경하는 모든 커밋은 커밋 메시지에 평가 전후 점수를 포함해야 합니다.

라이선스

MIT. LICENSE를 참조하세요.

David Koen이 제작했습니다.