"""`solar-eval runs eval` — 새 추론 없이 디스크의 결과만 다시 채점한다 (계획 2026-09-24-phase1a D11). `runs.py` 에서 떼어 냈다(E1). 옮기면서 바뀐 것 두 가지: - evaluation.json `eval_model` 은 예전의 `"local"` 이 아니라 평가기가 보고하는 judge 모델이다 (judge 가 없는 lcs_diff·rule_based 는 null). 러너와 같은 규칙이다. - run.json 에 `snapshot` 이 있으면 `snapshot.config.evaluator_config` 를 새 평가기로 다시 쓰고 `config_fingerprint` 를 다시 계산하며 `provenance.re_evaluated_at` 을 남긴다 — 번들로 감쌀 때 평가 파일과 스냅샷이 어긋나지 않게(SPEC §4 "평가 정체성 연기"의 최소 대응, Q14). **두 경로(계획 2026-09-27 L6 §2.12 B4 · 마스터 D-M2-6).** hub 대상 lcs_diff 계열의 완료된 run 은 **run 디렉토리를 건드리지 않는다** — 채택된 run 번들의 결과로 채점해 평가 디렉토리에 남기고 `purpose=rescore_after_fix` 채점 번들로 발행한 뒤 (opt-in) hub 에 싣는다(`solar_eval.scoring_publish`). 그 밖(hub 대상 아님·비-lcs·미완료)은 위의 오늘 동작(in-place) + 안내 한 줄이다. hub 대상 run 을 옛 동작으로 돌리던 탈출구 플래그는 L10 컷오버에서 지웠다(계획 2026-09-28 L10 §2.6 · D-L10-7 — 주면 click 사용 오류, 종료 2). 종료 코드: 채점을 마쳤으면 0(발행·hub 실패와 무관), `--strict-ingest`/ `SOLAR_EVAL_STRICT_INGEST=1` 이고 실패 다리가 있으면 3, 새 경로에서 번들이 없거나 채점을 못 했으면 1. **judge 경로(계획 2026-09-28 L12 §2.5 · D-L12-6·9·13).** 태스크 평가기가 `rubric_judge` 인 hub 대상 완료 run 은 기준별 judge 채점 번들을 발행한다(`scoring_publish.judge`). `--purpose {primary,variance_check}` 와 `--retry-of ` 는 이 경로에서만 받는다(함께 쓰거나 다른 경로에서 쓰면 사용 오류, 종료 2). judge 설정은 경로 판정 전에 확인한다. judge 가지의 종료 코드: 발행 사전 거부 1 · retry 대상 없음 0 · 채점 뒤 실패는 위 규칙 그대로. """ from __future__ import annotations import asyncio from collections.abc import Mapping from datetime import datetime, timezone from pathlib import Path from typing import Any import click from solar_eval.cli.commands import run_meta as run_meta_module from solar_eval.cli.commands.run_meta import PREP_ERRORS, find_task, load_run from solar_eval.cli.formatters import format_scores from solar_eval.core.run_records import ( build_eval_detail_docs, build_eval_sample_from_result, build_evaluation_doc, ) from solar_eval.core.snapshot import self_check, with_evaluator from solar_eval.hub_hook import exit_code_for from solar_eval.hub_hook.optin import strict_requested from solar_eval.hub_hook.types import LEG_PUBLISH, PUBLISH_NO_BUNDLE_PREFIX, STATUS_SKIPPED from solar_eval.scoring_publish import FAMILY_JUDGE, EvalJob, Route, decide_route, publish_run_eval from solar_eval.scoring_publish import judge as judge_publish from solar_eval.scoring_publish.eval_dir import REPORT_SAMPLES from solar_eval.scoring_publish.publish import PublishOutcome, Scored #: `--no-ingest`·`--strict-ingest` 도움말(계획 L6 §2.2 `runs eval` 행). NO_INGEST_HELP = "새 경로에서 hub 다리(적재)만 건너뛴다 — 평가 디렉토리·채점 번들 발행은 한다" STRICT_INGEST_HELP = ( "새 경로의 번들·발행·hub 다리가 하나라도 실패하면 종료 코드 3 (기본 0). " "SOLAR_EVAL_STRICT_INGEST=1 과 같다" ) #: judge 경로 옵션 도움말(계획 2026-09-28 L12 D-L12-9). PURPOSE_HELP = ( "rubric judge 채점 번들의 purpose. 기본 primary — 같은 설정의 primary 가 이미 있으면 거부한다. " "같은 설정을 다시 채점해 판정 분산을 재려면 variance_check" ) RETRY_OF_HELP = "이 평가 실행(evaluation_run_id, ULID)의 error 판정만 다시 부른다 — purpose=retry" #: judge 경로에서만 받는 옵션 — 함께 쓰거나 다른 경로에서 쓰면 사용 오류(종료 2). USAGE_PURPOSE_WITH_RETRY = "--purpose 와 --retry-of 는 함께 쓸 수 없다" USAGE_JUDGE_ONLY = "--purpose/--retry-of 는 rubric judge 채점 번들 경로에서만 쓴다" #: 이 run 이 judge 경로가 아닌 이유(경로 안내)가 있으면 사용 오류 뒤에 붙인다. USAGE_NOT_JUDGE_REASON = " — 이 run 은 judge 경로가 아니다: {notice}" #: judge 가지에서 채점하지 못했을 때 — 종료 1. 플래그 권유는 그 플래그가 푸는 실패에만 붙인다(아래 둘). JUDGE_NOT_SCORED = "채점하지 않았다 — 위 요약의 실패 다리와 그 안내를 본다" #: 같은 설정의 primary 가 이미 있다(`publish_judge:primary_exists`) — purpose·retry 플래그가 푸는 유일한 실패. JUDGE_NOT_SCORED_PRIMARY_EXISTS = ( f"{JUDGE_NOT_SCORED}. 같은 설정을 다시 채점하려면 --purpose variance_check, " "error 만 다시 부르려면 --retry-of " ) #: 채택된 run 번들이 없다(`publish_no_bundle:*`) — 플래그로는 풀리지 않는다. JUDGE_NOT_SCORED_NO_BUNDLE = f"{JUDGE_NOT_SCORED}. 채택된 run 번들이 없다 — 요약의 백필 명령으로 부류를 확인한 뒤 다시 돌린다" #: retry 대상이 없을 때(종료 0). JUDGE_RETRY_NOTHING = "다시 부를 error 판정이 없다 — 원 평가 실행의 error 가 이미 모두 풀렸다" def _ulid_option(ctx: click.Context, param: click.Parameter, value: str | None) -> str | None: """`--retry-of` 는 ULID 모양만 받는다 — 틀리면 사용 오류(종료 2).""" from poc_bundle.mirror import ULID_RE if value is None or ULID_RE.fullmatch(value) is not None: return value raise click.BadParameter("evaluation_run_id 는 ULID(26자 Crockford base32)여야 한다") async def _score_all(evaluator, judge_provider, results) -> tuple[list[dict], list[dict]]: """샘플별 채점. 채점 실패는 점수가 아니라 실패로 남긴다 — aggregate() 에는 성공분만 넘긴다.""" eval_results: list[dict[str, Any]] = [] eval_failures: list[dict[str, Any]] = [] for result in results: # 리스트 위치가 아니라 원본 sample_idx 가 정본이다(F6). sample_idx = result["sample_idx"] try: eval_sample = build_eval_sample_from_result(result, reference=result.get("golden")) evaluator.validate_required_fields(eval_sample) eval_result = await evaluator.evaluate(sample=eval_sample, provider=judge_provider) eval_results.append({**eval_result, "sample_idx": sample_idx}) except Exception as e: click.secho(f" Sample {sample_idx} eval failed: {e}", fg="yellow") eval_failures.append({"sample_idx": sample_idx, "error": str(e)}) return eval_results, eval_failures def _updated_snapshot( run_meta: dict[str, Any], evaluator_config: dict[str, Any] | None, judge_provider: Any ) -> dict[str, Any] | None: """스냅샷이 있으면 새 평가기로 다시 쓴 스냅샷, 없으면 None(옛 run 에 스냅샷을 새로 쓰지 않는다). 채점 **전에** 부른다 — 기록된 스냅샷이 깨졌거나 새 평가기로 지문을 다시 뜰 수 없으면 유료 judge 호출을 하기 전에 멈춘다. `judge_provider` 는 이번 재채점이 실제로 쓰는 것이다 — judge 가 없던 run 을 llm_judge 로 다시 채점하면 그 프로바이더 모듈이 `runtime_impl_hash` 에 들어가야 한다(D7). `re_evaluated_at` 은 채점이 끝난 뒤 `_stamp` 가 덮어쓴다. """ snapshot = run_meta.get("snapshot") if snapshot is None: return None started = datetime.now(timezone.utc).isoformat() try: # 기록된 스냅샷부터 검사한다 — `config` 가 없는 스냅샷이 맨 KeyError 로 죽지 않게. self_check(snapshot) updated = with_evaluator( snapshot, evaluator_config, re_evaluated_at=started, judge_provider=judge_provider ) self_check(updated) except PREP_ERRORS as e: raise click.ClickException(f"cannot update the run snapshot's evaluator: {e}") from None return updated def _stamp(snapshot: dict[str, Any], at: str) -> dict[str, Any]: """`provenance.re_evaluated_at` 을 채점이 끝난 시각으로 — provenance 는 지문 밖이다.""" return {**snapshot, "provenance": {**snapshot["provenance"], "re_evaluated_at": at}} def _make_evaluator(evaluator_config: dict[str, Any] | None): """러너·스냅샷과 같은 규칙 — 키가 없을 때만 기본 평가기. 잘못된 설정은 채점 전에 멈춘다.""" from solar_eval.evaluators.registry import DEFAULT_EVALUATOR_CONFIG, create_evaluator raw = DEFAULT_EVALUATOR_CONFIG if evaluator_config is None else evaluator_config try: return create_evaluator(raw) except ValueError as e: raise click.ClickException(f"invalid evaluator config: {e}") from None async def _evaluate_run(store, run_id, run_meta, task_config, results) -> dict[str, Any]: """채점 → evaluation.json·eval_details·run.json(상태·스냅샷) 저장. 집계를 돌려준다.""" evaluator_config = task_config.get("evaluator") evaluator = _make_evaluator(evaluator_config) # judge provider 를 안 넘기면 llm_judge 계열은 전 샘플에서 실패한다 -- 그리고 # 그 실패가 예전엔 0점 placeholder 로 덮여 조용히 completed 로 끝났다(F8). _, judge_provider = run_meta_module.make_providers(evaluator_config) snapshot = _updated_snapshot(run_meta, evaluator_config, judge_provider) eval_results, eval_failures = await _score_all(evaluator, judge_provider, results) now = datetime.now(timezone.utc) if snapshot is not None: snapshot = _stamp(snapshot, now.isoformat()) aggregated = evaluator.aggregate(eval_results) # eval_model = 평가기가 보고하는 judge 모델(없으면 None) — 예전의 "local" 은 거짓이었다(D11). doc = build_evaluation_doc( run_id, aggregated, eval_results, eval_failures, evaluator.judge_model ) eval_id = await store.create_evaluation(doc) await store.insert_eval_details(build_eval_detail_docs(eval_id, eval_results, eval_failures)) update: dict[str, Any] = {"status": "completed", "completed_at": now} if snapshot is not None: update["snapshot"] = snapshot await store.update_run(run_id, update) return {**aggregated, "overall_score": doc["overall_score"], "failed": len(eval_failures)} def _report(aggregated: Mapping[str, Any], run_dir: Path) -> None: click.echo() click.secho("Evaluation completed!", fg="green", bold=True) overall = aggregated.get("overall_score") if overall is None: # 채점이 한 건도 성공하지 못했다 -- 숫자를 찍으면 "0점"으로 읽힌다. click.secho(" Overall Score: 측정 없음 (전 샘플 채점 실패)", fg="red", bold=True) else: click.echo(f" Overall Score: {overall:.4f}") samples = aggregated.get(REPORT_SAMPLES) if samples is not None: click.echo(f" Samples: {samples} (채택된 run 번들 기준)") failed = aggregated.get("failed", 0) if failed: click.secho(f" 채점 실패: {failed}건 (score: null 로 기록됨)", fg="yellow") scores = aggregated.get("scores", {}) if scores: click.echo(f" Scores: {format_scores(scores)}") click.echo(f"\nResults saved to: {run_dir}/") @click.command("eval") @click.argument("project") @click.option("--run-id", "-r", required=True, help="Run ID to evaluate") @click.option("--no-ingest", is_flag=True, help=NO_INGEST_HELP) @click.option("--strict-ingest", is_flag=True, help=STRICT_INGEST_HELP) @click.option( "--purpose", type=click.Choice(judge_publish.CLI_PURPOSES), default=None, help=PURPOSE_HELP ) @click.option( "--retry-of", "retry_of", default=None, metavar="EVALUATION_RUN_ID", callback=_ulid_option, help=RETRY_OF_HELP, ) @click.pass_context def eval_run( ctx: click.Context, project: str, run_id: str, no_ingest: bool, strict_ingest: bool, purpose: str | None, retry_of: str | None, ) -> None: """Run evaluation only on existing inference results (no new inference).""" cfg = ctx.obj["config"] if cfg.is_remote: raise click.ClickException("Eval is local-mode only") if purpose is not None and retry_of is not None: raise click.UsageError(USAGE_PURPOSE_WITH_RETRY) run_dir, store, run_meta = load_run(cfg, project, run_id) results = store.load_existing_results() if not results: raise click.ClickException(f"No inference results found in {run_dir}/results.jsonl") task = run_meta["task"] click.secho(f"Evaluating run: {run_id}", fg="blue", bold=True) _, task_config = find_task(cfg, project, task) run_meta_module.preflight_judge_config(task_config) route = decide_route(cfg, project, run_dir, run_meta, task_config) if route.family != FAMILY_JUDGE and (purpose is not None or retry_of is not None): raise click.UsageError(_judge_only_message(route)) if route.target is None: click.secho(f" Task: {task}, Samples: {len(results)}", fg="blue") _echo_route(route) # 이전 평가를 미리 지우지 않는다(F3) -- 재평가가 실패해도 옛 점수는 남는다. aggregated = asyncio.run(_evaluate_run(store, run_id, run_meta, task_config, results)) _report(aggregated, run_dir) return # 새 경로의 채점 입력은 채택된 run 번들 사본이다 — 원본 행 수(중복 포함)는 찍지 않고 채점 뒤 보고에 싣는다(리뷰 지적 4). click.secho(f" Task: {task}, Samples: 채택된 run 번들 기준(아래 보고)", fg="blue") strict = strict_requested(strict_ingest) judge_options = (purpose, retry_of) scored, code = _publish(route, project, run_dir, task_config, no_ingest, strict, judge_options) if scored is not None: _report(scored.aggregated, scored.path) if code: ctx.exit(code) def _judge_only_message(route: Route) -> str: """judge 전용 플래그를 다른 경로에서 쓴 사용 오류 — 경로 안내(미완료 status·대상 아님 등)가 있으면 이유로 붙인다.""" if route.notice is None: return USAGE_JUDGE_ONLY return USAGE_JUDGE_ONLY + USAGE_NOT_JUDGE_REASON.format(notice=route.notice) def _echo_route(route: Route) -> None: """옛 경로 안내 한 줄(standalone 은 없다).""" if route.notice is not None: click.secho(f" ⚠ {route.notice}", fg="blue") def _publish( route: Route, project: str, run_dir: Path, task_config: dict[str, Any], no_ingest: bool, strict: bool, judge_options: tuple[str | None, str | None] = (None, None), ) -> tuple[Scored | None, int]: """새 경로(`scoring_publish.publish_run_eval`) → (채점, 종료 코드). 채점을 못 했으면 ClickException(종료 1). `judge_options` = (`--purpose`, `--retry-of`) — judge 경로만 쓴다. judge 가지는 `_judge_outcome` 이 종료 코드를 정한다 (retry 대상 없음이면 채점 없이 종료 0 — 그때 채점은 None). """ evaluator_config = task_config.get("evaluator") evaluator = _make_evaluator(evaluator_config) # 잘못된 설정은 잠금·백필 전에 멈춘다 _, judge_provider = run_meta_module.make_providers(evaluator_config) purpose, retry_of = judge_options job = EvalJob( project=project, run_dir_name=run_dir.name, evaluator=evaluator, evaluator_config=evaluator_config, judge_provider=judge_provider, score_all=_score_all, no_ingest=no_ingest, strict=strict, family=route.family, purpose=purpose, retry_of=retry_of, ) outcome = publish_run_eval(route.target, job) if route.family == FAMILY_JUDGE: return _judge_outcome(outcome, strict) if outcome.scored is None: raise click.ClickException( "채점하지 않았다 — 위 요약의 실패 다리와 되살리기를 본다(run 디렉토리는 그대로다)" ) return outcome.scored, exit_code_for(outcome.result, strict) def _judge_outcome(outcome: PublishOutcome, strict: bool) -> tuple[Scored | None, int]: """judge 가지의 종료 코드(§2.5 · 검토 F8). 채점했으면 L6b 규칙(0, strict 이고 실패 다리면 3). 채점하지 못했으면: retry 대상 없음 → 안내 한 줄 뒤 (None, 0), 그 밖(발행 사전 거부·번들 없음·잠금 등) → judge 전용 문구로 종료 1. purpose·retry 플래그는 그것이 푸는 실패(`primary_exists`)에만 권한다 — 번들 없음·잠금 실패에는 요약의 안내를 가리킨다. """ if outcome.scored is not None: return outcome.scored, exit_code_for(outcome.result, strict) leg = outcome.result.legs.get(LEG_PUBLISH) code = leg.code if leg is not None else None if leg is not None and (leg.status, code) == ( STATUS_SKIPPED, judge_publish.RETRY_NOTHING_TO_DO, ): click.secho(f" {JUDGE_RETRY_NOTHING}", fg="blue") return None, 0 raise click.ClickException(_judge_not_scored_message(code)) def _judge_not_scored_message(code: str | None) -> str: """발행 다리 코드 → 종료 1 문구. 코드 문자열은 `scoring_publish.judge`·`hub_hook.types` 의 상수만 쓴다.""" if code == f"{judge_publish.PUBLISH_JUDGE_PREFIX}{judge_publish.JUDGE_PRIMARY_EXISTS}": return JUDGE_NOT_SCORED_PRIMARY_EXISTS if isinstance(code, str) and code.startswith(PUBLISH_NO_BUNDLE_PREFIX): return JUDGE_NOT_SCORED_NO_BUNDLE return JUDGE_NOT_SCORED