파이썬 노트북에서 노드 기반 AI 실험 러너로 넘어간 개인 프로젝트

이 저장소는 “내 글쓰기 스타일을 따라 하는 로컬 AI 모델”을 만들려다 생긴 AI 실험 runner starter임

• 출발점은 포틀랜드를 배경으로 한 weird fiction을 쓰던 개인 프로젝트였음
• 처음엔 Python notebook으로 시작했는데, 끝까지 가보니 Node 기반 범용 실험 runner 형태가 됐다는 이야기임
• 생성 예시 문단도 포함돼 있는데, 글쓴이는 embedding보다 keyword retrieval 쪽이 voice 유지에 영향을 줬다고 설명함

사용 흐름은 꽤 작게 설계돼 있음

• clone, install, run을 하면 1분 안쪽으로 test pipeline이 end-to-end로 실행되는 걸 목표로 함
• package.json에는 runner GitHub 의존성, setup/pipeline/ui/clean 스크립트, 그 외에는 거의 아무것도 없음
• recipe나 override는 runner package에서 오거나 첫 실행 때 scaffold되는 구조임

요구 환경은 Node 중심이지만, MLX를 쓰려면 애플 생태계 제약이 붙음

• Node 20 이상이 필요하고, runner는 CoffeeScript와 node:sqlite를 사용함
• Python 3.10 이상은 MLX 표면을 실행할 때 필요함
• MLX는 Apple Silicon 전용이라, 해당 부분까지 쓰려면 macOS와 Apple Silicon이 사실상 전제임

run-first.sh는 setup부터 demo까지 한 번에 묶어주는 입구임

• npm run setup은 override.test.yaml을 override.yaml로 복사하고 Python 가상환경을 만든 뒤 MLX 관련 패키지를 설치함
• npm run demo 또는 npm run pipeline은 override.yaml에 지정된 pipeline을 실행함
• npm run ui는 127.0.0.1:4311에서 로컬 UI 서버를 띄움
• npm run clean은 runtime artifact를 지워 fresh clone 상태로 되돌림

흥미로운 건 UI를 node_modules 안에 숨기지 않고 프로젝트 루트에 둔다는 점임

• ui와 ui_server.coffee가 first-class project file로 제공됨
• 사용자는 패널 추가, protocol 변경, layout 교체 같은 수정을 프로젝트 파일에서 바로 할 수 있음
• 패키지 업데이트가 이 파일들을 건드리지 않고, 필요하면 npm run ui:reset으로 기본값을 다시 덮어쓸 수 있음

실험 확장은 override.yaml과 recipe 교체로 하는 방식임

• 기본 pipeline은 test이고, 9단계로 runner 메커니즘을 한 번씩 보여주는 용도임
• prompt_ite는 iterative prompt generation, diary_ite는 LoRA 유무에 따른 diary generation A/B, lora_ite는 LoRA adapter training 쪽임
• oracle_ite는 raw story에서 KAG extraction을 하는 흐름이고, diary_translate_ite는 adapter 기반 translation recipe임

자기 recipe를 만들려면 config 디렉터리와 scripts 디렉터리를 프로젝트 쪽에서 덮어쓰면 됨

• config/myname.yaml을 만들고 override.yaml에서 pipeline 값을 myname으로 바꾸는 식임
• step을 바꾸고 싶으면 scripts/name.coffee를 두면 runner가 제공하는 파일보다 프로젝트 파일이 우선함
• 즉, engine은 패키지에서 가져오고 실험 구성과 override는 로컬 프로젝트에서 관리하는 모델임

한국 개발자 관점에서는 “대세 도구”라기보다 로컬 LLM 실험을 구조화하는 참고 샘플에 가까움

• Apple Silicon에서 MLX로 이것저것 실험하는 사람에게는 setup, recipe, UI 분리 방식이 꽤 참고될 수 있음
• 반대로 클라우드 GPU나 리눅스 서버 중심 워크플로우라면 바로 가져다 쓰기엔 제약이 많음
• 그래도 notebook에 실험이 흩어지는 문제를 runner와 YAML lifecycle로 묶는 접근은 꽤 현실적인 포인트임