JSON AST 에이전트 하네스 (Agent Harness)

이 프로젝트는 텍스트 명세(spec)를 Clojure 프로그램으로 변환하기 위한 로컬 코드 생성 하네스(harness)입니다. 검증된 로컬 설정은 llama.cpp를 통해 서빙되는 Gemma 4 E2B GGUF 모델로 테스트되었습니다. 다른 모델들도 작동할 수 있지만, 테스트되지는 않았습니다.

핵심 아이디어는 작은 로컬 모델에게 전체 소스 코드를 직접 작성하도록 요청하는 것을 중단하는 것입니다. 대신, 모델은 제약된 JSON AST(Abstract Syntax Tree, 추상 구문 트리) 조각을 출력합니다. 하네스는 해당 조각들을 검증하고, 프로그래밍 방식으로 더 큰 구조를 조립하며, 승인된 AST를 Clojure로 변환(lowering)하고, 모든 생성/수정 결과물(artifact)을 SQLite에 기록합니다.

주요 기능

• llama-server를 통해 로컬 Gemma 4 E2B GGUF 모델을 실행합니다.
• 실험적으로 다른 OpenAI 호환 채팅 엔드포인트를 대상으로 지정할 수 있습니다.
• 플래너 패스(planner pass)를 사용하여 텍스트 명세로부터 정제된 계약(contract)을 도출합니다.
• 모델에게 상세 로직을 요청하기 전에 결정론적인 스켈레톤(skeleton) AST를 구축합니다.
• 쿼리 필터, 파생 컬럼(derived columns), GUI 컴포넌트를 위해 마이크로 스텝 패스(micro-stepped passes)를 사용합니다.
• Malli, JSON Schema/GBNF 호환 제약 조건, 필드 출처(provenance) 확인, 타입 흐름(type-flow) 확인 및 의미론적 구조 가드(semantic structure guards)를 사용하여 생성된 JSON AST를 검증합니다.
• 승인된 JSON AST를 Clojure 소스로 컴파일합니다.
• 프롬프트, 모델의 원시 출력, 승인된 AST, 거부된 시도 및 실행 추적(execution traces)을 실행별 SQLite DB에 로그로 남깁니다.

비즈니스 로직 경로 (Business Logic Path)

비즈니스 규칙 플러그인은 Clojure 데이터 변환 함수를 생성합니다.

bb json-run \
  --self-plan \
  --skeleton-first \
...

출력물은 프로젝트 디렉토리 아래에 작성됩니다:

• candidate.ast.json
• candidate.clj
• report.json
• session.sqlite3
• llama-server.log

네이티브 Swing GUI 경로 (Native Swing GUI Path)

:gui-page 플러그인은 간단한 네이티브 Java Swing 프로그램을 생성합니다. 모델은 정제된 GUI 계약과 컴포넌트 서브트리(subtrees)를 출력하며, 하네스가 Swing 변환(lowering), 안전한 이벤트 와이어링(event wiring) 및 jar 패키징을 담당합니다.

bb gui-run \
  --self-plan \
  --component-pass \
...

생성된 Swing 프로그램을 실행 가능한 jar로 빌드합니다:

bb gui-jar tmp/gui_inventory/candidate.clj tmp/gui_inventory/app.jar

데스크톱 창을 열고 싶을 때 수동으로 실행합니다:

java -jar tmp/gui_inventory/app.jar

GUI 액션은 의도적으로 폐쇄적이고 결정론적(deterministic)입니다. 버튼은 show-message 및 clear-form과 같은 안전한 액션 맵(action maps)을 사용할 수 있습니다. 모델은 임의의 Java, Swing 리스너(listener) 코드, Clojure 폼(forms), 파일 액션, 네트워크 액션 또는 셸(shell) 명령을 생성할 수 없습니다.

스모크 테스트 (Smoke Tests)

bb json-smoke tmp/json_smoke
bb gui-smoke tmp/gui_smoke

이 테스트들은 모델을 호출하거나 GUI 창을 열지 않고도 로컬 Babashka 클래스패스 (classpath), JSON AST 검증, Clojure 코드 생성 (codegen) 경로, Swing AST 검증 및 Swing 소스 로드 경로를 검증합니다.

벤치마크 정직성 (Benchmark Honesty)

기본적으로 json-run은 텍스트 전용 생성입니다. --allow-semantic-guidance를 명시적으로 전달하지 않는 한, 생성 시 시맨틱 픽스처 (semantic fixtures)는 사용되지 않습니다.

시맨틱 테스트를 사용하는 경우, 다음과 같이 명시적으로 전달하십시오:

--semantic-test-file path/to/test.edn \
--semantic-oracle-source user|benchmark|assistant|unknown

깨끗한 벤치마크 증거를 위해서는 실행 중에 어시스턴트 (assistant)가 생성하지 않은 픽스처 (fixtures)를 사용해야 합니다.

런타임 파일 (Runtime Files)

최소 파일 매니페스트 (manifest)에 대해서는 RUNTIME_FILES.md를 참조하십시오.

확장 경계 (Extension Boundary)

하네스 (harness)는 bb/harness/plugins/ 아래에 플러그인 경계 (plugin boundary)를 가지고 있습니다.

• data_transformation.clj는 비즈니스 규칙 (business-rule) 생성을 담당합니다.
• gui_page.clj는 Swing GUI 생성을 담당합니다.
• api_router.clj는 루트 파이프라인 (root pipeline)을 변경하지 않고 다른 유스케이스 (use case)가 어떻게 생명주기 메서드 (lifecycle methods)를 등록할 수 있는지 보여주는 청사진 (blueprint) 플러그인입니다.