zihoAutoResearch

LLM이 기존 ML 프로젝트를 이해하고 전처리·학습·검증을 점검하며, 코드 수정과 실험을 반복하도록 돕는 가벼운 연구 도구.

사용자가 선택한 기존 환경과 실행 명령을 활용하며, Git 코드 커밋과 후속 실험 기록 커밋을 연결해 연구 이력을 쌓습니다. 대회에서는 주최측 데이터·평가 지표·제출 규칙을 읽고, 로컬 검증 결과와 제출 점수를 실험 변경에 연결합니다. Docker나 별도 실행 플랫폼은 초기 범위에 포함하지 않습니다.

작업 흐름

프로젝트 이해 → 연구 지침 작성 → 현재 실험 점검 → 유효한 기준 확보 → 가설·코드 수정 → 실행·비교 → 유지·되돌리기·보류 → 다음 실험

카파시의 AutoResearch에서 작은 연구 지침과 반복 실험 방식을 가져옵니다. 여기에 기존 프로젝트 이해, 전처리·학습의 근거 기반 점검, 제출 결과 연결을 보완합니다. 전체 파이프라인을 연구 대상으로 삼으며 특정 데이터셋에 제품을 고정하지 않습니다.

아키텍처

현재 구조는 연구 판단, 원본 기록, 재개용 조회를 분리합니다. 스킬이 프로젝트를 해석하고 판단하며 CLI는 기록·검사·비교와 근거 조회를 담당합니다. 상세 계약은 맥락 조회와 근거 재조회를 따릅니다.

flowchart TD
    U[사용자: 목표 · 변경 범위 · 예산] --> S[LLM 연구 스킬]
    S --> C[CLI: 기록 변경 · 비교 · 판단 저장]
    C --> J[원본 JSON + Git 코드 이력]
    J --> R[공통 기록 스냅샷과 검증]
    R --> C
    R --> Q[context: 제한된 재개 정보]
    Q --> S
    R --> E[evidence read: 근거 원문 부분 조회]
    L[기존 로그 · 데이터 · 산출물] --> E
    E --> S
    S --> X[기존 에이전트 도구: 허용된 코드 수정과 실행]
    X --> L
    J --> P[JSON 기반 보고서 생성]

CLI는 LLM 호출·학습 실행·코드 되돌리기·대회 제출을 수행하지 않습니다. 실제 사용 중 실행은 기존 에이전트 도구가 맡으며, 도구 개발 검증에서는 로그와 점수를 모의 데이터로 대체합니다.

현재 상태

로컬 CLI의 JSON 저장·검증 기반과 init, project set, status, check, review add, submission add, memory add, candidate add, experiment create/update/correct/compare/decide, git status, experiment create --git-head, context, evidence read, lineage, report를 구현했습니다. LLM용 스킬과 실행 가능한 모의 연구 예제를 제공합니다. check는 기록의 형식·연결·근거 파일을 검사하며 ML 과정의 타당성을 판정하지 않습니다.

• 실험 계보의 JSON·Mermaid 조회
• 다음 실험 후보의 근거·예상 비용·선택 이유
• 실패 기억의 기록·정정·재조회
• 맥락 조회·근거 재조회와 구조
• 최근 관련 연구와 개선 이슈
• 보고서 필드별 원본 매핑
• Git 기반 연구 이력과 사용 순서
• 현재 제품 정의
• v1 사용 흐름·CLI·파일 계약
• 실제 학습 없이 확인하는 모의 파일 예제
• 연구 절차와 판정 규칙
• 기존 프로젝트 연결과 실행 환경
• 프로젝트 연구 지침 템플릿
• 실험 기록 템플릿
• 작업 기록

목표는 사용자가 적용할 수 있는 도구를 완성하는 것입니다. 스킬은 기존 CLI로 실험 기록·비교·판단·선택을 연결하며, 확인된 제출 결과를 실험·파일 해시와 연결합니다. 보고서는 원본 JSON에서 생성하며 미기록 값과 근거의 한계를 표시합니다. 제품 개발 중 실제 ML 학습·대회 제출은 하지 않으며, 완성 후 실제 적용은 사용자가 수행합니다.

배포와 라이선스

v0.1.1 GitHub 릴리스를 공개했습니다. 변경 내역과 배포 파일 설치·검증 안내를 확인하세요. PyPI에 공개됐다고 가정하지 않으며, 아래 소스 설치 방법은 현재 사용할 수 있습니다. 프로젝트 라이선스는 MIT입니다. 참고 연구·외부 코드와 데이터의 권리는 각 원본 조건을 따릅니다.

설치와 기본 사용

Python 3.11 이상이 필요하며 실행 시 외부 라이브러리는 필요하지 않습니다. uv 설치·업데이트 안내에서 현재 공개 wheel과 향후 PyPI 설치 경로를 확인하세요. 개발 버전 0.2.0은 아직 배포하지 않았으며, PyPI 자동화는 설정 완료 후에만 활성화합니다. 저장소에서 가상환경을 만든 뒤 설치할 수도 있습니다.

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell에서는 .venv\Scripts\Activate.ps1
python -m pip install .
zar init --project /path/to/ml-project
zar status --project /path/to/ml-project

처음 설정하거나 중단한 작업을 이어갈 때는 처음 사용과 재개 안내를 따르세요. 공개 버전 0.1.1은 문서 보완과 재개 검증을 포함합니다. 공개 배포본 검증 결과에 수정 근거를 기록했습니다.

LLM 스킬 사용

스킬 원본은 skills/ziho-autoresearch/이며 references/를 포함한 폴더 전체가 한 단위입니다. 0.2.0 개발본부터 wheel에도 같은 파일을 포함합니다. zar skill install --dest ./ziho-autoresearch-skill-0.2.0 --json으로 새 폴더에 설치하고 반환된 SKILL.md 경로를 에이전트에 알려주세요. 기존 폴더를 덮어쓰거나 전역 설정에 자동 등록하지 않습니다. 자세한 갱신 절차는 스킬 설치 안내를 따릅니다. 공개 v0.1.1에서는 기존처럼 소스 배포본의 스킬 폴더를 사용합니다. 소스 스킬을 직접 사용할 때는 다음처럼 경로를 지정합니다.

/absolute/path/to/zihoAutoResearch/skills/ziho-autoresearch/SKILL.md를 읽고 /absolute/path/to/ml-project를 점검해줘. 우선 실행 없이 프로젝트 해석과 누락 정보를 정리해줘.

실험까지 맡길 때는 목표, 허용 변경 경로, 실행 환경, 횟수·시간 한도를 함께 지정하거나 이미 확정한 project.json을 참조합니다. 스킬은 현재 기록을 읽고 미완료 실행을 확인한 뒤 이어갑니다. keep 판단, 기록상 선택, 실제 작업 폴더의 코드는 각각 확인합니다. 모든 지침이 설치된 에이전트에서 자동 발견된다고 보장하지는 않습니다.

학습 없이 한 사이클 확인

위 CLI 설치 후, 저장소에서 실행합니다. 출력 경로는 존재하지 않는 새 폴더이고 그 상위 폴더는 있어야 합니다.

python examples/mock-cycle.py --output /tmp/zar-mock-adopt
python examples/mock-cycle.py --output /tmp/zar-mock-hold --scenario scope-mismatch

Windows에서는 /tmp/... 대신 존재하는 임시 폴더 아래의 새 경로를 지정하세요. 예제는 기준/후보의 가짜 코드·로그·시각·점수를 생성하고 CLI로 초기화 → 모의 점검 등록 → 기준 선택 → 후보 기록 → 비교 → 판단 → 선택/보류 → 모의 제출 결과 기록 → 보고서 → check/status를 수행합니다. 학습 명령은 호출하지 않습니다. 예제의 고정 판단은 모의 시나리오이며 실제 연구의 자동 채택 정책이 아닙니다.

각 출력 폴더에 project/.autoresearch/ 기록, 호출과 진단의 events.json, 결과의 summary.json, 제한된 조회의 context.json, 원문 발췌의 evidence-page.json과 project/.autoresearch/reports/summary.md를 보존합니다. 점검·제출 결과도 모두 합성 관측이며 실제 학습·제출을 증명하지 않습니다. 기본 예제는 정확한 0.1 개선으로 후보를 선택합니다. scope-mismatch 예제는 proxy/full 불일치로 후보를 보류하고 기준 선택을 유지합니다. 이때 작업 폴더에는 후보 코드가 남으므로 workspace_matches_selection:false를 명시합니다. 기록상 선택이 코드를 복구하지 않는다는 예제입니다. 기존 출력 폴더는 덮어쓰지 않으며 재실행에는 새 경로를 사용합니다.

필요한 맥락과 근거만 읽기

zar context --project /path/to/ml-project --experiment exp-candidate-1 --max-bytes 16384 --json
zar evidence read --project /path/to/ml-project --kind experiment --id exp-candidate-1 --pointer /execution/evidence/0 --max-lines 80 --json

context는 기록의 형식·참조를 확인하고 선택/후보/미완료/실패 정보를 제한된 크기로 제공합니다. 전체 로그의 존재·해시는 확인하지 않으며 evidence_not_checked를 명시합니다. 누락 카드와 잘린 필드를 확인하고 next_offset과 --snapshot으로 이어 읽습니다.

evidence read는 등록된 근거의 해시와 원문을 같은 스트림에서 확인하며 UTF-8 줄을 그대로 반환합니다. 등록 해시가 바뀌었으면 내용을 반환하지 않습니다. 해시가 없는 파일은 미검증으로 표시하고, 다음 페이지에는 이전 actual_sha256을 --sha256으로 전달할 수 있습니다. 원본은 자동 보관·복원하지 않습니다. 전체 근거 검사는 기존 check, ML 해석은 스킬이 담당합니다. 정확한 상한·오류·동시 변경 한계는 조회 계약을 참고하세요.

프로젝트 설정과 검사

초기화는 .autoresearch/만 생성하고 기존 코드·루트 program.md·AGENTS.md를 보존합니다. --project를 생략하면 현재 폴더를 사용하며 상위 폴더를 탐색하지 않습니다.

초안은 원본과 다른 파일에 작성합니다. .autoresearch/drafts/를 사용한다면 init이 만들지 않는 선택 폴더이므로 먼저 생성하세요. 프로젝트 밖에 초안을 두어도 됩니다. 생성된 .autoresearch/project.json을 별도 파일로 복사해 목표·비교 조건·명령·예산·수정 허용 경로를 채웁니다. environment.os는 사용자가 windows, linux, macos, other 중 선택하고 runtime, device도 직접 기록합니다. 기록된 명령은 실행하지 않습니다.

zar project set --project /path/to/ml-project --file edited-project.json
zar status --project /path/to/ml-project --json
zar check --project /path/to/ml-project --json

project set은 현재 revision의 전체 수정본을 받아 검증 후 revision을 올립니다. ID·생성 시각은 유지하고 updated_at은 CLI가 기록합니다. 같은 comparison ID의 조건을 바꾸려면 새 ID를 지정합니다. 미완성 설정도 저장할 수 있으며 status는 누락을 보여주고 check는 종료 코드 3을 반환합니다. 성공은 0, 인자·형식 오류는 2, 상태·참조 충돌은 3, 파일·잠금 오류는 4입니다.

CLI는 .autoresearch/.lock으로 동시 접근을 조정하며 잠금이 있으면 자동 삭제하지 않습니다. 중단으로 잠금이 남으면 실행 중인 CLI가 없는지 확인한 뒤 수동으로 복구합니다. init은 프로젝트 루트의 .autoresearch.init.lock을 사용합니다. CLI 밖의 동시 파일 편집은 보호하지 않습니다.

check는 저장된 review/experiment/submission/memory/candidate 파일도 검사합니다. 파일 근거의 누락·해시 미기록·변경과 확인하지 못한 코드/데이터 최신성은 진단으로 표시하고 URL에 접속하지 않습니다. 실제 ML 실행이나 제출 없이 테스트합니다.

python -m unittest discover -s tests -v

기존 자동화는 Linux·Windows·macOS의 GitHub 호스팅 runner에서 검증했습니다. 변경별 결과는 해당 PR의 CI와 작업 기록을 확인하세요. 실제 ML 프로젝트의 학습·장치 호환성 검증을 뜻하지 않습니다.

실험 생성과 관측 결과 기록

설정을 채운 프로젝트에서 생성 입력 예제를 복사하고 실험 ID·가설·코드/설정 식별자·명령을 실제 프로젝트에 맞게 수정합니다.

zar experiment create --project /path/to/ml-project --file experiment-create.json
zar experiment update exp-baseline-1 --project /path/to/ml-project --file experiment-update.json

create는 현재 comparison/environment를 복사하고 planned 기록을 만듭니다. 설정 누락, 실험 수 한도, 중복 ID와 존재하지 않는 참조는 거부합니다. update 입력은 생성된 .autoresearch/experiments/exp-baseline-1.json의 전체 수정본입니다. 현재 revision을 유지하고 execution에 실제 관측값을 채우면 CLI가 revision과 updated_at을 갱신합니다.

• planned → running → succeeded/failed/interrupted/unknown을 기록합니다. 이미 종료한 실행은 시작·종료 시각과 근거를 갖춰 planned에서 바로 종료 상태로 기록할 수 있습니다.
• unknown을 해소하려면 기존 근거와 구별되는 확인 근거를 추가합니다. 새 실행은 새 ID로 기록합니다.
• 계획·이미 기록한 실행 시각·판단은 update로 바꿀 수 없습니다. 종료 결과는 고정하며 산출물만 새 경로로 추가할 수 있습니다. 제출용 산출물은 SHA-256 해시가 필요합니다.

이 명령은 프로세스를 시작하거나 실행 상태를 자동 탐지하지 않습니다. 실험을 생성·갱신해도 project.json의 선택 실험은 바뀌지 않습니다. 새 실험 파일은 소유자 전용 권한으로 생성되고, 이후 갱신은 기존 파일 권한을 유지합니다.

Git 커밋으로 쌓는 연구 이력

코드·설정을 커밋한 뒤 다음 명령으로 실험을 연결합니다. CLI는 Git 조회만 수행합니다.

zar git status --project /path/to/ml-project --json
zar experiment create --git-head --project /path/to/ml-project --file /path/to/experiment-create.json

--git-head는 입력 code_ref를 git:<전체 HEAD SHA>로 대체하며 커밋되지 않은 코드·설정 변경이 있으면 거부합니다. .autoresearch/의 기록 변경은 허용합니다. 입력 파일은 대상 프로젝트 밖이나 .autoresearch/drafts/에 두세요. 실행 결과 JSON은 코드 커밋을 계속 가리키며, 기존 에이전트가 별도의 결과 기록 커밋으로 보존합니다.

추적할 파일·잠금 제외 규칙·실행 직전 확인·검사 한계는 Git 연구 이력에 정리했습니다. 과거 JSON 예제의 수동 code_ref는 실제 Git SHA가 아닙니다.

미실행 취소·시작 미확인·관측 정정

• 실행하지 않은 planned는 experiment update로 cancelled와 사유 note를 남깁니다. 시작·종료·점수·exit code는 null, artifacts는 []입니다. 미완료 목록에서 닫히고 횟수 예산을 반환합니다.
• 실행 시작 여부를 모르면 note/evidence와 함께 unknown을 기록하며 시작 시각을 추정하지 않습니다. 확인 전 재실행하지 않고, 새 근거로 실행 상태를 해소합니다.
• 완료 결과의 오기는 원본을 덮어쓰지 않고 새 정정 ID로 연결합니다.

zar experiment correct exp-baseline-1 --project /path/to/ml-project --file correction.json

정정 입력은 {id, revision, execution, reason, evidence}이며 원본 revision과 새 ID를 제공합니다. 같은 실행 계획·산출물을 보존하고 결과만 정정합니다. 새 실행 횟수는 늘지 않으며 새 판단은 비어 있습니다. 선택된 원본은 먼저 선택 해제해야 합니다. 자세한 상태·정정 규칙은 파일 계약, 보고서의 출처는 필드 매핑을 따릅니다.

실험 비교와 판단 기록

생성 입력에 run_context를 지정합니다. scope는 proxy 또는 full, seed는 정수 또는 미확인 시 null, budget_ref는 실행 예산 조건 식별자입니다. 생성 예제의 값은 실제 조건으로 바꾸세요.

zar experiment compare exp-baseline-1 exp-candidate-1 --project /path/to/ml-project --json
zar experiment decide exp-candidate-1 --project /path/to/ml-project --file decision.json

판단 입력 예제의 revision은 대상 실험의 현재 값으로 바꿉니다. compare는 조건 일치 여부, 정확한 십진 개선 폭, 명시적으로 연결한 확인 실험의 횟수·분산을 보여줍니다. 미기록 조건·proxy/full 혼합·정정된 baseline은 비교를 제한하고, 근거 확인 한계는 별도로 출력합니다. decide는 사용자의 근거 있는 판단을 이력에 추가하며 코드·Git·현재 선택을 바꾸지 않습니다. 자세한 의미와 기존 기록 호환성은 비교 계약을 따릅니다.

실행 전 점검 기록

zar review add --project /path/to/ml-project --file review-draft.json --json으로 점검 결과를 등록합니다. 입력은 id, supersedes_id, code_ref, data_ref, items이며 생성 메타데이터는 CLI가 채웁니다. 프로젝트 설정이 미완성이어도 점검을 남길 수 있습니다. 입력 예시는 스킬의 CLI 레시피에 있습니다.

실험 전 변경 범위·가설과 실제 diff를 대조하고, 데이터 누수·평가 방법 변경·검증하지 못한 항목을 근거와 함께 남깁니다. 등록한 ID를 새 실험의 review_ids에 연결합니다. 등록 성공은 점검 내용이나 ML 타당성의 자동 승인을 뜻하지 않습니다. 같은 코드·데이터의 점검 정정은 새 ID와 supersedes_id로 원본을 보존하며, 기존 실험 참조는 바꾸지 않습니다. RRSI 적용 범위를 참고하세요.

확인된 제출 결과 기록

zar submission add --project /path/to/ml-project --file submission-draft.json --json은 이미 확인한 외부 점수와 제출 근거를 기록합니다. 먼저 성공한 실험의 artifacts에 role=submission 파일 경로와 SHA-256을 등록해야 합니다. 점수가 아직 없으면 산출물만 보존합니다. 입력 필드는 v1 계약과 CLI 레시피를 따릅니다.

중복 외부 결과는 거부하고, 정정은 같은 competition/external_id/leaderboard의 활성 기록을 새 ID로 대체합니다. 원본·실험 로컬 점수·판단·현재 선택은 보존됩니다. 실제 파일 해시가 다르면 등록을 거부하며, 파일이 없으면 확인 불가 경고를 남깁니다. CLI는 외부 제출이나 점수 조회를 수행하지 않습니다.

실패 기억 기록과 재조회

zar memory add --project /path/to/ml-project --file memory-draft.json --json으로 실패 원인·대응·한계와 원본 실험·근거를 연결합니다. 실패 기억이 있으면 기본 context가 집계와 조회 안내를 제공합니다. 활성 기억은 zar context --memories --project /path/to/ml-project --experiment exp-candidate-1 --json으로 읽습니다. 선언 조건의 일치만으로 해결책이 검증되었다고 판단하지 않습니다. 원본 근거와 현재 조건을 확인하고, 정정·폐기는 새 ID로 원본을 보존합니다. 입력과 호환성은 실패 기억 계약을 따릅니다. 설치 후 python examples/mock-memory.py --output /tmp/zar-mock-memory로 합성 기록의 등록·조회·정정·폐기를 확인할 수 있습니다. 출력은 상위 폴더가 존재하는 새 경로를 사용하며 Windows에서는 해당 환경의 임시 경로로 바꿉니다.

연구 보고서 생성

zar report --project /path/to/ml-project --output summary.md --json
zar report --project /path/to/ml-project --output summary.md --overwrite --json

프로젝트 전체 설정·점검·실험·제출 결과·실패 기억·후보 근거를 .autoresearch/reports/summary.md에 생성합니다. 활성 기록을 먼저 표시하고 정정된 원본도 보존해 보여줍니다. 저장된 판단과 현재 기록에서 계산한 비교 결과는 구분하며, 없는 값은 “미기록”, unknown은 “상태 불명”으로 표시합니다. 로그에서 사실을 추정하거나 LLM·Git·외부 서비스를 호출하지 않습니다. 근거 검사의 경고도 보고서에 포함합니다.

출력은 reports 내부의 .md 상대 경로만 허용하며 중첩 경로의 부모 폴더는 미리 존재해야 합니다. 기존 파일은 기본적으로 보존하고, --overwrite도 같은 프로젝트의 보고서 표식이 있는 일반 파일만 교체합니다. 원본 JSON은 변경하지 않습니다. 보고서는 모든 기록을 포함하므로 큰 이력의 재개에는 제한된 context를 먼저 사용하세요.

구현 기준과 자동 검증

문서의 요구사항과 회귀 테스트, PR 필수 검사, 리뷰 기준 및 초안 릴리스 절차는 문서 기반 자동화를 따릅니다. 자동 검사는 소프트웨어 계약을 확인하며 실제 ML 유효성이나 비용 절감을 대신 증명하지 않습니다.

기록 수가 늘 때의 응답 시간·최대 메모리·출력 크기와 측정 한계는 기록 규모별 성능 측정을 참고하세요.

다음 실험 후보 기록

zar candidate add --project /path/to/ml-project --file candidate-draft.json --json으로 관측·가설·예상 효과·비용·불확실성·선택 또는 보류 이유를 기록합니다. zar context --candidates --project /path/to/ml-project --json은 후보의 예측과 연결된 실제 관측을 구분하여 보여줍니다. selected는 다음에 시도할 의도이며 selected_experiment_id의 채택 결과와 다릅니다. 실험 생성에 선택적 candidate_id를 넣으면 정확한 selected 버전과 연결합니다. 자동 점수·순위·실행·예산 확대는 하지 않습니다. 입력·정정·재평가 절차는 후보 기록 계약을 따릅니다.

설치 후 python examples/mock-candidates.py --output /tmp/zar-mock-candidates로 합성 예측·관측·보류 흐름을 확인할 수 있습니다. 출력은 상위 폴더가 존재하는 새 경로를 사용하며 Windows에서는 임시 경로를 바꿉니다. 실제 학습·비용 검증은 하지 않습니다.

실험 계보 조회

zar lineage --project /path/to/ml-project --json은 기존 실험 JSON에서 계획 부모·비교 기준·관측 정정 관계를 구분해 전체 그래프를 반환합니다. zar lineage --project /path/to/ml-project --format mermaid는 Mermaid 원문을 출력합니다. 실패·취소·정정 원본을 남기고, 정정은 같은 실행 계보로 묶어 중복 집계하지 않습니다. 집계에는 planned/cancelled도 포함되므로 실제 실행 횟수나 소비 예산으로 해석하지 않습니다.

코드 식별자와 원래 참조를 표시하지만 Git 조상 관계·실제 실행·근거 파일을 검증하지는 않습니다. 전체 출력에는 크기 제한이 없으므로 제한된 재개 맥락에는 context를 사용합니다. 계보 조회 계약에서 방향·집계·한계를 확인할 수 있습니다. 설치 후 python examples/mock-lineage.py --output /tmp/zar-mock-lineage로 합성 이력의 JSON·Mermaid 조회와 원본 보존을 확인합니다. 출력은 상위 폴더가 존재하는 새 경로를 사용하며 Windows에서는 해당 환경의 임시 경로로 바꿉니다.