"""run 시작·resume 이 공유하는 준비 단계와 run.json 메타 조립 (계획 2026-09-24-phase1a D3·D5·D12·D17·D19). `runs start` 는 run 디렉토리를 만들기 **전에** 이 모듈로 모든 것을 정한다: 태스크·프롬프트·파이프라인 해석 → 행 선택(`where`·`limit`) → 데이터셋 한 번 읽기 → 파이프라인 생성 → 스냅샷(run.json `dataset`·`snapshot` 블록, 자기 검증까지). 그래서 0행 선택·라벨 누락·없는 사전·깨진 lock 같은 오류가 빈 run 디렉토리를 남기지 않고, run.json 이 적은 sha256·스냅샷과 러너가 실제로 도는 데이터·파이프라인이 **같은 객체**에서 나온다. resume 은 같은 조립 함수(`build_snapshot`)로 지금 디스크 기준 스냅샷을 다시 떠 설정 드리프트를 막는다(D17). `poc_bundle` import 는 이 모듈(과 `run_resume`·`run_eval`)과 `core/snapshot/**` 에서만 한다(D18). """ from __future__ import annotations import subprocess from collections.abc import Callable, Mapping, Sequence from dataclasses import dataclass from pathlib import Path from typing import Any import click from poc_bundle.data.errors import DataError from solar_eval.core.dataset_loader import DatasetLoader, LoadedJsonl from solar_eval.core.dataset_prep import ( PreparedDataset, build_selection, prepare_dataset, reject_defaults_where, ) from solar_eval.core.pipeline_factory import build_task_pipeline from solar_eval.core.row_filter import RowSelection, parse_cli_where from solar_eval.core.snapshot import EngineSnapshotInputs, build_engine_snapshot, self_check from solar_eval.core.snapshot import environment from solar_eval.core.snapshot.dataset_block import describe_dataset from solar_eval.evaluators.judge_config import JudgeConfigError, validate_judge_config #: run 을 시작하기 전에 사람이 읽을 메시지로 바꿔 멈추는 오류 — 행 선택·meta_fields·defaults.where #: (ValueError 계열), 없는 데이터셋·지식 자산(FileNotFoundError 계열), 깨진 datasets.lock(DataError). PREP_ERRORS: tuple[type[Exception], ...] = (ValueError, FileNotFoundError, DataError) #: 지문을 사람이 눈으로 대조할 때 보여 주는 앞자리 수 — legacy `prompt_sha` 형식과 맞춘다. FINGERPRINT_DISPLAY_CHARS = 12 def resolve_prompt(prompts_dir: Path, prompt_name: str) -> Path: """Resolve prompt from prompts/ directory (directory or YAML file). Resolution order: 1. prompts/{name}/ (directory TXT format) 2. prompts/{name}.yaml (flat YAML layout) 3. prompts/_library/{name}.yaml (legacy layout) """ dir_path = prompts_dir / prompt_name if dir_path.is_dir(): return dir_path yaml_path = prompts_dir / f"{prompt_name}.yaml" if yaml_path.exists(): return yaml_path legacy_path = prompts_dir / "_library" / f"{prompt_name}.yaml" if legacy_path.exists(): return legacy_path raise click.ClickException( f"Prompt '{prompt_name}' not found. Searched:\n" f" {dir_path}/ (directory)\n" f" {yaml_path} (YAML)\n" f" {legacy_path} (legacy)" ) def resolve_pipeline_file(project_dir: Path, pipeline_name: str) -> Path: """Resolve pipeline YAML from pipelines/ directory.""" path = project_dir / "pipelines" / f"{pipeline_name}.yaml" if not path.exists(): raise click.ClickException(f"Pipeline '{pipeline_name}' not found: {path}") return path def compose_pipeline_config(project_dir: Path, pipeline_name: str, overrides: dict) -> dict: """파이프라인을 `extends`/override 까지 해석해 돌려준다. 조립 실패(없는 base, 없는 스텝을 가리키는 override 등)는 run 을 시작하기 전에 죽인다 — 효과 없는 override 로 돌아간 run 은 결론을 조용히 오염시킨다. """ from solar_eval.core.pipeline_compose import PipelineCompositionError, compose_pipeline from solar_eval.core.project_loader import load_pipeline_file pipelines_dir = resolve_pipeline_file(project_dir, pipeline_name).parent try: composed = load_pipeline_file(pipelines_dir, pipeline_name) if overrides: composed = compose_pipeline(composed, overrides=overrides) return composed except (PipelineCompositionError, FileNotFoundError) as e: raise click.ClickException(str(e)) from None def config_source(cfg, project: str) -> str: """run 의 config 출처 — 레포 관리 프로젝트면 레포 상대 경로, 아니면 데이터 홈 절대 경로.""" config_dir = cfg.config_dir(project) if cfg.is_repo_managed(project) and cfg.repo_root is not None: return str(config_dir.relative_to(cfg.repo_root)) return str(config_dir) def git_commit(repo_root: Path | None) -> str | None: """재현용 도장: 레포 HEAD 커밋. 작업 트리가 더러우면 '-dirty' 를 붙인다 (레포 전체 — D8 불변).""" if repo_root is None: return None try: head = subprocess.run( ["git", "-C", str(repo_root), "rev-parse", "--short", "HEAD"], capture_output=True, text=True, check=True, ).stdout.strip() status = subprocess.run( ["git", "-C", str(repo_root), "status", "--porcelain"], capture_output=True, text=True, check=True, ).stdout.strip() return f"{head}-dirty" if status else head except (OSError, subprocess.CalledProcessError): return None def find_task(cfg, project: str, task: str) -> tuple[dict[str, Any], dict[str, Any]]: """로드된 프로젝트 설정과 태스크 설정. 없으면 ClickException.""" from solar_eval.core.project_loader import load_all_project_configs configs = load_all_project_configs(cfg.projects_dir, cfg.config_dirs) project_config = next((c for c in configs if c["name"] == project), None) if not project_config: raise click.ClickException(f"Project not found in {cfg.projects_dir}: {project}") task_config = next((t for t in project_config.get("tasks", []) if t["name"] == task), None) if not task_config: raise click.ClickException(f"Task '{task}' not found in project '{project}'") return project_config, task_config def load_run(cfg, project: str, run_id: str) -> tuple[Path, Any, dict[str, Any]]: """(run 디렉토리, 스토어, run.json). 없으면 ClickException.""" from solar_eval.stores import JsonlStore run_dir = cfg.artifacts_dir(project) / run_id if not run_dir.exists(): raise click.ClickException(f"Run directory not found: {run_dir}") store = JsonlStore(run_dir) run_meta = store.load_run_meta() if not run_meta: raise click.ClickException(f"No run.json found in {run_dir}") if not run_meta.get("task"): raise click.ClickException("Cannot determine task from run.json") return run_dir, store, run_meta def load_prompt( prompt_path: Path, model: str, temperature: float, max_tokens: int, reasoning_effort: str | None, ) -> tuple[dict[str, Any], str]: """프롬프트 파일을 러너가 받는 dict 로 — (prompt, 포맷 `multi_step`|`single_step`).""" from solar_eval.models.prompt_version import ( detect_prompt_format, load_prompt_messages, load_step_prompts, ) fmt = detect_prompt_format(prompt_path) if fmt == "multi_step": prompt: dict[str, Any] = {"step_prompts": load_step_prompts(prompt_path)} else: prompt = {"messages": load_prompt_messages(prompt_path)} prompt.update({"model": model, "temperature": temperature, "max_tokens": max_tokens}) if reasoning_effort: prompt["reasoning_effort"] = reasoning_effort return prompt, fmt def make_providers(evaluator_config: Mapping[str, Any] | None = None) -> tuple[Any, Any]: """(추론 프로바이더, judge 프로바이더). 테스트는 이 함수를 바꿔 끼워 네트워크 없이 돈다. `evaluator_config` 는 태스크의 평가기 설정(키가 없으면 None) — judge 인스턴스를 선언(`judge_provider`)으로 고르는 자리다(계획 2026-09-28 L12 §2.8 · D-L12-10). 선언이 없거나 판정 없는 평가기는 오늘처럼 `OpenAIProvider()` — run.json 스냅샷 `provenance.providers.judge` 바이트가 바뀌지 않는다. 추론 프로바이더는 늘 `UpstageProvider()`. Raises: JudgeConfigError: 모르는 provider·합성 평가기 안의 provider 충돌. """ from solar_eval.evaluators.judge_config import ( PROVIDER_OPENAI, PROVIDER_UPSTAGE, judge_provider_name, ) from solar_eval.providers import UpstageProvider from solar_eval.providers.openai_provider import OpenAIProvider judge_classes = {PROVIDER_UPSTAGE: UpstageProvider, PROVIDER_OPENAI: OpenAIProvider} name = judge_provider_name(evaluator_config) or PROVIDER_OPENAI return UpstageProvider(), judge_classes[name]() def route_inference_provider(provider: Any, step_models: Sequence[str]) -> Any: """스텝 모델에 라우트 접두어(`timely:<모델>`)가 하나라도 있으면 추론 제공자를 `RoutedProvider` 로 감싼다. 없으면 그대로 돌려준다 — 라우트 없는 run 의 provenance(`providers.inference` 모듈)가 예전 바이트 그대로여야 한다. 외부 라우트를 써도 되는가는 엔진이 아니라 case 의 데이터 정책(계약)이 정한다 — 2026-10 judge egress 정책 폐지(#353)와 같은 자리. """ from solar_eval.providers import INFERENCE_ROUTES, RoutedProvider from solar_eval.providers.routed import route_prefixes if not route_prefixes(list(step_models), INFERENCE_ROUTES): return provider return RoutedProvider(provider, {k: cls() for k, cls in INFERENCE_ROUTES.items()}) @dataclass(frozen=True) class RunPlan: """run 하나가 무엇으로 도는가 — run 디렉토리를 만들기 전에 전부 정해진다.""" project: str task: str project_config: dict[str, Any] task_config: dict[str, Any] prompt_name: str prompt_path: Path prompt_format: str prompt: dict[str, Any] model: str temperature: float max_tokens: int reasoning_effort: str | None pipeline_name: str pipeline_config: dict[str, Any] pipeline_overrides: dict[str, Any] | None max_workers: int dataset_loader: DatasetLoader prepared: PreparedDataset pipeline: Any provider: Any judge_provider: Any @property def selection(self) -> RowSelection | None: return self.prepared.selection def resolve_pipeline( cfg, project: str, task_config: dict[str, Any], pipeline_name: str | None, overrides: dict ) -> tuple[dict[str, Any], str, dict[str, Any]]: """(파이프라인을 얹은 task_config, 실효 파이프라인 이름, 해석된 파이프라인 dict). `-P` 가 있으면 config 정본의 pipelines/ 에서 `extends`·`--set` 까지 해석하고, 없으면 project.yaml 기본값(project_loader 가 이미 해석)을 쓴다. config 는 레포 관리 프로젝트면 git 쪽이 정본이다. `extends` 상속과 `--set` override 는 여기서 전부 해석돼, 실행 엔진에는 완성된 steps 목록만 넘어간다. """ if pipeline_name: pipeline_config = compose_pipeline_config(cfg.config_dir(project), pipeline_name, overrides) return {**task_config, "pipeline_config": pipeline_config}, pipeline_name, pipeline_config if overrides: raise click.ClickException("--set requires an explicit --pipeline/-P") pc = task_config.get("pipeline_config", {}) effective = pc.get("name", "default") if isinstance(pc, dict) else str(pc) return task_config, effective, pc if isinstance(pc, dict) else {} class _CheckedReader: """`prepare_dataset` 에 넘기는 얇은 대리자 — 파일을 읽은 **직후**, 행을 고르기 **전에** `on_read` 를 부른다. resume 의 데이터셋 sha 가드(D17 순서의 첫째)가 선택·라벨 검사보다 먼저 걸리게 하려는 것이다 — 데이터셋이 바뀌어 선택이 0행이 되면 원인은 "where 가 0행" 이 아니라 "데이터셋이 바뀌었다" 다. 바이트는 여전히 한 번만 읽는다(D16). """ def __init__(self, loader: DatasetLoader, on_read: Callable[[LoadedJsonl], None]) -> None: self._loader = loader self._on_read = on_read def read_jsonl(self, repo: str, path: str, source: str) -> LoadedJsonl: loaded = self._loader.read_jsonl(repo, path, source=source) self._on_read(loaded) return loaded def _step_models(pipeline: Any) -> list[str]: """파이프라인 스텝들이 명시한 모델 문자열 — 라우트 접두어 검사용(없는 스텝은 run 의 `-m` 모델 = Upstage).""" return [ str(step.config["model"]) for step in getattr(pipeline, "steps", []) if isinstance(getattr(step, "config", None), dict) and step.config.get("model") ] def assemble_plan( cfg, selection: RowSelection | None, *, on_read: Callable[[LoadedJsonl], None] | None = None, **fields: Any, ) -> RunPlan: """데이터셋을 한 번 읽어 고르고, 러너가 돌 파이프라인 인스턴스를 만든다(D6·D16). `fields` 는 `RunPlan` 의 나머지 필드(project·task_config·prompt 등)다. `on_read` 는 데이터셋을 읽은 직후·선택 전에 불린다(resume 의 sha 가드 — 거기서 난 ClickException 은 그대로 올라간다). judge 설정 오류는 데이터셋 읽기·파이프라인·provider 생성보다 먼저 확인한다. `runs start`·`quick-run`·`runs batch`(프롬프트마다)·`runs resume` 이 모두 이 자리를 지난다. Raises: click.ClickException: judge 설정·선택·meta_fields·데이터셋·파이프라인 생성 오류(run 시작 전). """ preflight_judge_config(fields["task_config"]) loader = DatasetLoader(base_dir=cfg.projects_dir) reader: Any = loader if on_read is None else _CheckedReader(loader, on_read) try: prepared = prepare_dataset( reader, fields["project_config"], fields["task_config"], selection ) pipeline = build_task_pipeline( fields["project_config"], fields["task_config"], fields["prompt"], loader ) except PREP_ERRORS as e: raise click.ClickException(str(e)) from None provider, judge_provider = make_providers(fields["task_config"].get("evaluator")) provider = route_inference_provider(provider, _step_models(pipeline)) return RunPlan( dataset_loader=loader, prepared=prepared, pipeline=pipeline, provider=provider, judge_provider=judge_provider, **fields, ) def preflight_judge_config(task_config: Mapping[str, Any]) -> None: """Judge 설정 오류를 CLI 오류로 바꾸되 provider 는 만들지 않는다.""" try: validate_judge_config(task_config) except JudgeConfigError as exc: raise click.ClickException(str(exc)) from None def start_options( project_config: dict[str, Any], task_config: dict[str, Any], set_options: tuple[str, ...], where: tuple[str, ...], limit: int | None, ) -> tuple[dict[str, Any], RowSelection]: """(`--set` override, 행 선택) — 프롬프트와 무관한 시작 검사. `runs batch` 는 루프 전에 한 번 부른다. Raises: click.ClickException: `defaults.where`·where 문법·`--set` 문법 오류. """ from solar_eval.core.pipeline_compose import PipelineCompositionError, parse_set_option try: reject_defaults_where(project_config) overrides = parse_set_option(set_options) selection = build_selection(task_config, parse_cli_where(where), limit) except (PipelineCompositionError, *PREP_ERRORS) as e: raise click.ClickException(str(e)) from None return overrides, selection def plan_run( cfg, *, project: str, task: str, prompt_name: str, model: str, pipeline_name: str | None, reasoning_effort: str | None, temperature: float, max_tokens: int, max_workers: int, limit: int | None, set_options: tuple[str, ...] = (), where: tuple[str, ...] = (), ) -> RunPlan: """`runs start` 의 준비 단계 전부 — `reject_defaults_where` → 선택 → `prepare_dataset` → `build_task_pipeline` (계획 §9 G2 순서). 모든 오류는 run 디렉토리를 만들기 전에 난다. """ project_config, task_config = find_task(cfg, project, task) overrides, selection = start_options(project_config, task_config, set_options, where, limit) prompt_path = resolve_prompt(cfg.prompts_dir(project), prompt_name) prompt, fmt = load_prompt(prompt_path, model, temperature, max_tokens, reasoning_effort) task_config, effective, pipeline_config = resolve_pipeline( cfg, project, task_config, pipeline_name, overrides ) return assemble_plan( cfg, selection, project=project, task=task, project_config=project_config, task_config=task_config, prompt_name=prompt_name, prompt_path=prompt_path, prompt_format=fmt, prompt=prompt, model=model, temperature=temperature, max_tokens=max_tokens, reasoning_effort=reasoning_effort, pipeline_name=effective, pipeline_config=pipeline_config, pipeline_overrides=overrides or None, max_workers=max_workers, ) def dataset_block(cfg, plan: RunPlan) -> dict[str, Any]: """run.json `dataset` 블록 — 읽은 바이트의 sha256·행 수·정규화된 선택·lock 대조(S6).""" prepared = plan.prepared selection = plan.selection or RowSelection() try: return describe_dataset( sha256=prepared.sha256, rows_total=prepared.rows_total, rows_selected=prepared.rows_selected, selection=selection.to_json(), meta_fields=prepared.meta_fields, task_config=plan.task_config, loader_cfg=plan.project_config.get("dataset") or {}, config_dir=cfg.config_dir(plan.project), project_name=plan.project, repo_root=environment.engine_repo(), ) except PREP_ERRORS as e: raise click.ClickException(f"dataset lock check failed: {e}") from None def build_snapshot( cfg, plan: RunPlan, dataset: dict[str, Any] | None, *, source: str | None, commit: str | None, ) -> dict[str, Any]: """run.json `snapshot` 블록(engine-snapshot/v1). start 와 resume 이 같은 함수를 쓴다(D17). Raises: click.ClickException: 선언한 자원이 없거나 스냅샷이 자기 검증(D5)을 통과하지 못할 때. """ inputs = EngineSnapshotInputs( model=plan.model, temperature=plan.temperature, max_tokens=plan.max_tokens, reasoning_effort=plan.reasoning_effort, pipeline_type=plan.task_config.get("pipeline", "single_step"), input_fields=plan.task_config.get("input_fields", []), resolved_pipeline=plan.pipeline_config, prompt_path=plan.prompt_path, pipeline=plan.pipeline, evaluator_config=plan.task_config.get("evaluator"), inference_provider=plan.provider, judge_provider=plan.judge_provider, prompt_name=plan.prompt_name, pipeline_name=plan.pipeline_name, config_source=source, git_commit=commit, pipeline_overrides=plan.pipeline_overrides, max_workers=plan.max_workers, config_dir=cfg.config_dir(plan.project), repo_managed=cfg.is_repo_managed(plan.project), dataset=dataset, ) try: snapshot = build_engine_snapshot(inputs) self_check(snapshot) except PREP_ERRORS as e: raise click.ClickException(f"cannot snapshot this run's config: {e}") from None return snapshot def auto_note(note: str | None, plan: RunPlan) -> str | None: """`--where` run 의 note 자동 기입(D19) — Experiment Hub 목록에서 전체셋 반복과 사람이 구분하게. note 가 비면 `where tags=yul-ryul · 12/159 rows`, 사용자가 주면 그 뒤에 ` [where …]`. where 가 없는 run 은 note 를 그대로 둔다(다른 run 의 run.json 바이트 불변). """ selection = plan.selection if selection is None or selection.where is None: return note prepared = plan.prepared label = ( f"where {selection.where.describe()} · {prepared.rows_selected}/{prepared.rows_total} rows" ) return f"{note} [{label}]" if note else label def build_run_meta(cfg, plan: RunPlan, note: str | None) -> dict[str, Any]: """run.json 초기 내용 — legacy 키(값 규칙 불변, D12) 뒤에 `dataset`·`snapshot`(계획 §3.2 순서).""" from solar_eval.core.fingerprint import pipeline_fingerprint, prompt_fingerprint source = config_source(cfg, plan.project) commit = git_commit(cfg.repo_root) if cfg.is_repo_managed(plan.project) else None dataset = dataset_block(cfg, plan) return { "task": plan.task, "model": plan.model, "prompt": plan.prompt_name, "pipeline": plan.pipeline_name, "temperature": plan.temperature, "max_tokens": plan.max_tokens, "reasoning_effort": plan.reasoning_effort, # 왜 돌렸는지 — 예전에는 별도 랩노트(experiments/*.yaml)가 담았지만 run 과 분리돼 있어 # 참조가 끊어지고 썩었다. run 과 같은 파일에 두면 끊어질 수가 없다. where run 은 자동 기입(D19). "note": auto_note(note, plan), # provenance: 이 run 의 config(프롬프트·파이프라인)가 어디서 왔는지 (W&B/DVC 식 도장) "config_source": source, "git_commit": commit, # 내용 지문 — 이름이 아니라 내용으로 설정을 식별한다. 이름만 다른 사본, # `extends` 로 조립한 것, `--set` 으로 즉석에서 만든 것이 모두 같은 값이면 # 같은 지문을 갖는다 (core/fingerprint.py). legacy 값 규칙 그대로(D12) — 새 지문은 snapshot 에. "prompt_sha": prompt_fingerprint(plan.prompt_path), "pipeline_sha": pipeline_fingerprint(plan.pipeline_config), # 파일 없이 돌린 실험이면 무엇을 바꿨는지가 여기 남는다. "pipeline_overrides": plan.pipeline_overrides, "dataset": dataset, "snapshot": build_snapshot(cfg, plan, dataset, source=source, commit=commit), } def short_fingerprint(value: str | None) -> str: """64-hex 지문을 `sha256:<12>` 로 — legacy `prompt_sha` 와 같은 모양으로 눈 대조.""" if not value: return "-" return f"sha256:{value[:FINGERPRINT_DISPLAY_CHARS]}"