multi-dim-manager
장기 실행되는 다차원 계산 실험의 상태에 질서를 부여하는 독립형 스킬입니다. 사용자의 계산 플러그인은 계산을 수행하고, 이 스킬은 반복, 스냅샷, 감사 및 롤백이라는 주변 혼란을 관리합니다.
이 스킬은 오케스트레이션만 수행합니다. 결과 자체를 계산하지 않습니다. 모든 숫자는 사용자의 플러그인에서 비롯됩니다.
사용 시기
- 워크플로가 파라미터 공간(차원의 Cartesian 그리드)에서 많은 라운드를 실행하며 각 라운드의 상태를 기록해야 하는 경우.
- 각 라운드 전후에 선언된 중요 파일의 스냅샷이 필요한 경우.
- 모든 라운드에 대해 전체 감사 추적(파라미터, 해시, 타임스탬프, 상태)이 존재해야 하는 경우.
- 사용자가 비파괴적으로 과거 라운드로 롤백할 수 있어야 하는 경우.
- 일반적인 형태: 종단 연구, 파라미터 스캔, 또는 외부 솔버(Mathematica, GAP, SymPy, 사용자 지정 스크립트)를 호출하는 기호/수치 스윕.
필수 워크플로
종속성 부트스트랩 (첫 사용 시 실행)
첫 실행 전에 이 스킬의 런타임 종속성을 확인합니다.
- 핵심: 순수 표준 라이브러리 — 설치 불필요.
- 선택 사항:
PyYAML(설정이.yaml인 경우에만 필요; JSON 설정은 표준 라이브러리만으로 작동).
PyYAML이 없고 사용자 설정이 YAML인 경우, 사용자에게 알리고 pip install pyyaml을 할지 물어본 후, 명시적 동의가 있을 때만 설치하세요. 절대 명시적 동의 없이 전역 환경에 설치하지 마십시오.
사용자가 다차원 실험을 실행, 검사 또는 복구하도록 요청할 때마다 다음 단계를 순서대로 따르십시오.
- 설정 로드. 실험 설정(
config.example.yaml이 템플릿)을 읽습니다.param_space.dimensions,critical_paths및plugin.command가 있는지 확인합니다. YAML이 사용되면 PyYAML이 설치되어 있어야 합니다. 그렇지 않으면 JSON을 사용합니다. - 공간 확장. 모든 차원의 Cartesian 곱을 열거합니다. 실행하기 전에 총 라운드 수를 사용자에게 보고합니다.
- 드라이 런 우선.
python scripts/run.py dryrun --config <cfg>를 실행하여 사용자가 부작용 없이 전체 계획(모든 파라미터 조합)을 볼 수 있도록 합니다. 확인 후에만 실행을 진행합니다. - 스윕 실행.
python scripts/run.py run --config <cfg>를 실행합니다. 각 라운드에 대해 순서대로: 이전에 선언된 중요 경로를 스냅샷하고, 플러그인을 호출하고, 이후에 스냅샷하고, 하나의 감사 레코드를 추가합니다. - 오류 처리. 라운드 플러그인이 0이 아닌 코드로 종료되면 해당 상태를 기록합니다(
failed/error).auto_rollback이 켜져 있으면 마지막 성공한 라운드의 사후 상태를 작업 디렉토리로 복구하여 이후 라운드가 깨끗하게 시작되도록 합니다. 이 복구 자체도 감사됩니다. 단일 잘못된 조합 때문에 전체 스윕을 중단하지 마십시오. - 요약. 스윕 후 스킬은 출력 디렉토리 아래에
results_summary.csv,results_summary.md,report_draft.md및run_metadata.json을 작성합니다. 사용자에게 이를 알립니다. - 요청 시 복구. 과거 라운드를 복원하려면
python scripts/run.py rollback --config <cfg> --round <N>을 실행합니다. 기본적으로 새 디렉토리로 복원합니다. 사용자가 명시적으로 라이브 작업 디렉토리를 덮어쓰려는 경우에만--force를 추가합니다.
엄격한 제약 조건
- 결과를 직접 계산하지 마십시오. 모든 도메인 수학은 사용자 플러그인에 속합니다. 스킬은 이를 호출하고 계약 결과를 기록만 합니다.
- 선언된 중요 경로만 스냅샷합니다. 전체 작업 디렉토리 복사본은 절대 생성되지 않습니다. 콘텐츠는 해시로 주소 지정되어 저장되므로 변경되지 않은 파일은 추가 비용이 들지 않습니다.
- 롤백은 기본적으로 비파괴적입니다.
--force없이는 라이브 작업 디렉토리가 수정되지 않습니다. 복원된 상태는 새 디렉토리에 배치됩니다. 모든 롤백(수동 또는 자동)은 감사 로그에 기록됩니다. - 결정론은 사용자의 약속입니다. 스킬은 오케스트레이션이 재현 가능함(동일한 파라미터 -> 동일한 기록된 계획, 동일한 해시)을 보장합니다. 비결정론적 플러그인을 결정론적으로 만들 수는 없습니다. 제한 사항을 참조하십시오.
사용 예
# 부작용 없이 전체 라운드 계획 출력 (항상 먼저 수행).
python scripts/run.py dryrun --config config.example.yaml
# 스윕 실행.
python scripts/run.py run --config config.example.yaml
# 과거 라운드 복원 (--force 없으면 새 디렉토리로).
python scripts/run.py rollback --config config.example.yaml --round 7
# 요약 재생성 또는 한 라운드 결과 확인.
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7
플러그인 계약
관리자는 라운드당 정확히 하나의 셸 명령을 실행합니다:
python your_plugin.py --params {PARAMS} --out {OUT}
{PARAMS}- 이 라운드의 파라미터 조합이 포함된 JSON 파일의 경로.{OUT}- 플러그인이 결과 JSON을 반드시 기록해야 하는 경로.- 종료 코드:
0성공,1어설션 실패/검사 실패,2오류 또는 건너뜀.
모든 외부 솔버(Mathematica, GAP, Python LMM 스크립트)는 이 계약을 준수하도록 래핑됩니다. params 파일을 읽고 결과 파일을 기록합니다. 스킬은 무엇이 계산되는지 신경 쓰지 않습니다.
오류 처리
- 플러그인이
1로 종료된 라운드는failed로 표시되고,2로 종료되면error로 표시됩니다. 둘 다 감사 로그에 유지되며 스윕은 계속됩니다. config오류(공간 누락, 잘못된 YAML,{OUT}누락)는 부작용 없이 중단하고 명확한 메시지를 출력합니다(종료 코드 2).- 기록된 적이 없거나 사후 스냅샷이 없는 라운드로의
rollback은 상태를 손상시키는 대신 명확한 오류와 함께 실패합니다.
제한 사항
- 결정론은 오케스트레이션 계층에만 해당됩니다. 관리자는 해시를 기록하고 동일한 파라미터에 대해 동일한 계획을 재생하지만 플러그인이 결정론적임을 강제할 수는 없습니다. 플러그인이 네트워크에 접속하거나, 난수 시드를 사용하거나, 벽 시계를 읽는 경우 동일한 입력이 다른 출력을 생성할 수 있습니다. 이러한 비결정론은 플러그인에서 직접 선언하십시오.
- 중요 경로는 사전에 선언되어야 합니다.
critical_paths에 나열되지 않은 파일은 절대 스냅샷되지 않으므로 롤백할 수 없습니다. - 황금 출력 검증은 v0.2입니다. 현재 검증기는 플러그인 계약(종료 코드 0 + 결과 파일 존재)만 확인합니다. 알려진 예상 출력과의 비교는 계획되었지만 아직 구현되지 않았습니다.
- YAML 설정에는 PyYAML이 필요합니다. JSON 설정은 표준 라이브러리만으로 작동합니다.