"""평가 디렉토리 — `runs eval` 새 경로의 채점 결과 자리 (계획 2026-09-27 L6 §2.12 B4 ② · D-L6-15). 자리는 `/solar-eval-evaluations////` 다. 레거시 아카이브 트리(`solar-eval-projects/`) **밖**이라 레거시 적재기가 프로젝트 자원으로 오인하지 않고, run 디렉토리 밖이라 run 번들이 그대로다. - `evaluation.json`·`eval_details.jsonl` 은 레거시 모양 그대로다 — run 디렉토리와 같은 `JsonlStore` 로 쓴다 (`build_evaluation_doc`·`build_eval_detail_docs` 재사용). eval-wrap 이 이 디렉토리를 평가 원천으로 읽는다(B3). - `eval-run.json` 은 이 평가의 정체 — 평가 시각·평가기 설정·judge 모델·원천 run 번들 id. 원자적 쓰기(임시 → `os.replace`). 다른 두 파일 뒤에 마지막으로 쓴다 — 이 파일이 없는 디렉토리는 끝나지 않은 평가다. - judge 경로(계획 2026-09-28 L12 §2.7)는 `verdicts.jsonl`(기준 판정 전부 — 근거·원 응답 포함, 데이터 홈 전용)을 더 쓰고 `eval-run.json` 에 `purpose`·`judge{evaluation_run_id, scoring_bundle_id, retry_of}` 를 싣는다(발행 **뒤**에 쓴다). lcs 경로는 선택 인자를 주지 않아 바이트가 그대로다. - 이름 조각(project·run_id)은 경로 구분자·제어 문자·`.`/`..` 를 거부하고, 루트가 레포(링크된 워크트리면 메인 작업 트리도) 안이면 쓰기 전에 멈춘다 — hub 대상 판정(`hub_hook.target`, D-L6-1)이 이미 보지만 이 모듈이 직접 쓰므로 한 번 더 본다. `poc_bundle`·`ulid` 는 함수 안에서만 import 한다(마스터 §4 규칙 11 · D-L6-14). """ from __future__ import annotations import dataclasses import json import os import re import shutil import tempfile from collections.abc import Iterable, Mapping, Sequence from dataclasses import dataclass from datetime import datetime from pathlib import Path from typing import Any from solar_eval.core.run_records import build_eval_detail_docs, build_evaluation_doc from solar_eval.stores import JsonlStore #: 데이터 홈 아래 평가 디렉토리 루트 이름(D-L6-15). EVALUATIONS_DIRNAME = "solar-eval-evaluations" EVAL_RUN_FILE = "eval-run.json" EVAL_RUN_SCHEMA = "solar-eval-eval-run/v1" #: 이 디렉토리가 싣는 평가의 목적 — eval-wrap 매니페스트 `purpose` 와 같은 값(PB `PURPOSE_RESCORE_AFTER_FIX`). EVAL_RUN_PURPOSE = "rescore_after_fix" #: judge 경로(계획 2026-09-28 L12 §2.7) — 기준 판정 전부(근거·원 응답 포함)와 `eval-run.json` 의 `judge` 칸 키. VERDICTS_FILE = "verdicts.jsonl" JUDGE_BLOCK_KEYS = ("evaluation_run_id", "scoring_bundle_id", "retry_of") #: 레포 안 쓰기 검사에 주는 이름표. WRITE_LABEL = "evaluation directory" _UNSAFE_SEGMENT = re.compile(r"[/\\\x00-\x1f\x7f]") _TMP_PREFIX = ".eval-run-" _TMP_SUFFIX = ".tmp" #: `EvalDirError.reason` — 발행 다리 코드 `publish_eval_dir:` 의 꼬리. 모두 설정·입력 오류라 다시 돌려도 같다. REASON_UNSAFE_SEGMENT = "unsafe_segment" REASON_INSIDE_REPO = "inside_repo" REASON_BAD_DOCUMENT = "bad_document" REASON_OUTSIDE_ROOT = "outside_root" class EvalDirError(ValueError): """평가 디렉토리를 만들거나 쓸 수 없다(이름 조각·레포 안·잘못된 문서). `reason` 은 위 `REASON_*` 하나.""" def __init__(self, message: str, reason: str) -> None: super().__init__(message) self.reason = reason #: 콘솔 보고용 집계의 채점 입력 행 수(성공 + 실패) — 채택된 run 번들의 정규화 사본 기준(l6b-verify 리뷰 지적 4). REPORT_SAMPLES = "input_samples" @dataclass(frozen=True) class WrittenEvaluation: """`write_evaluation` 결과 — 새 평가 id 와 콘솔 보고용 집계(`overall_score`·`failed`·`REPORT_SAMPLES` 포함).""" evaluation_id: str aggregated: Mapping[str, Any] def evaluations_root(env: Mapping[str, str] | None = None) -> Path: """`/solar-eval-evaluations`(절대 경로).""" from poc_bundle.home import data_home return data_home(env) / EVALUATIONS_DIRNAME def _check_segment(label: str, value: str) -> str: if not isinstance(value, str) or value in ("", ".", "..") or _UNSAFE_SEGMENT.search(value): raise EvalDirError( f"evaluation directory: {label} is not a safe path segment", REASON_UNSAFE_SEGMENT ) return value def _require_outside_repo(root: Path, repo_root: Path | None) -> None: """루트가 레포(링크된 워크트리면 메인 작업 트리도) 안이면 `EvalDirError`.""" from poc_bundle.home import HomeError, require_outside_repo from poc_bundle.mirror import linked_main_work_tree if repo_root is None: return main = linked_main_work_tree(Path(repo_root)) for tree in (Path(repo_root),) if main is None else (Path(repo_root), main): try: require_outside_repo(root, tree, WRITE_LABEL) except HomeError as exc: raise EvalDirError( f"evaluation directory is inside the repo: {exc}", REASON_INSIDE_REPO ) from None def create_evaluation_dir( project: str, run_id: str, *, repo_root: Path | None, env: Mapping[str, str] | None = None, ) -> Path: """새 평가 디렉토리(빈 디렉토리)를 만들어 돌려준다. 이름은 새 ULID — 같은 run 의 재평가는 시각 순으로 쌓인다.""" from ulid import ULID parent = ( evaluations_root(env) / _check_segment("project", project) / _check_segment("run_id", run_id) ) _require_outside_repo(evaluations_root(env), repo_root) path = parent / str(ULID()) path.mkdir(parents=True, exist_ok=False) return path async def write_evaluation( path: Path, run_id: str, evaluator: Any, eval_results: Sequence[Mapping[str, Any]], eval_failures: Sequence[Mapping[str, Any]], ) -> WrittenEvaluation: """레거시 모양 `evaluation.json`·`eval_details.jsonl` 을 쓴다(`run_eval._evaluate_run` 과 같은 조립).""" aggregated = evaluator.aggregate(list(eval_results)) doc = build_evaluation_doc( run_id, aggregated, eval_results, eval_failures, evaluator.judge_model ) store = JsonlStore(path) evaluation_id = await store.create_evaluation(doc) await store.insert_eval_details( build_eval_detail_docs(evaluation_id, eval_results, eval_failures) ) report = { **aggregated, "overall_score": doc["overall_score"], "failed": len(eval_failures), REPORT_SAMPLES: len(eval_results) + len(eval_failures), } return WrittenEvaluation(str(evaluation_id), report) def eval_run_document( *, project: str, run_id: str, run_bundle_id: str, evaluation_id: str, evaluated_at: str, evaluator_config: Mapping[str, Any] | None, eval_model: str | None, purpose: str = EVAL_RUN_PURPOSE, judge: Mapping[str, Any] | None = None, ) -> dict[str, Any]: """`eval-run.json` 문서(순수). 시각은 오프셋이 있어야 하고 평가기 설정은 JSON 매핑이어야 한다. `purpose`·`judge` 는 judge 경로(계획 2026-09-28 L12 §2.7)만 준다 — lcs 경로 호출은 인자를 주지 않아 바이트가 그대로다. `judge` 가 있으면 끝에 `{"evaluation_run_id", "scoring_bundle_id", "retry_of"}` 를 더한다(발행 실패면 bundle id 는 null). """ _check_offset(evaluated_at) doc: dict[str, Any] = { "schema": EVAL_RUN_SCHEMA, "project": project, "run_id": run_id, "run_bundle_id": run_bundle_id, "evaluation_id": evaluation_id, "evaluated_at": evaluated_at, "purpose": purpose, "evaluator_config": _json_mapping(evaluator_config), "eval_model": eval_model, } if judge is not None: doc["judge"] = _judge_block(judge) return doc def _judge_block(judge: Mapping[str, Any]) -> dict[str, Any]: """`eval-run.json` 의 `judge` 칸 — 닫힌 키 셋, 값은 문자열 id 또는 null.""" if not isinstance(judge, Mapping) or set(judge) != set(JUDGE_BLOCK_KEYS): raise EvalDirError( f"eval-run: judge must have exactly the keys {list(JUDGE_BLOCK_KEYS)}", REASON_BAD_DOCUMENT, ) if not all(judge[k] is None or isinstance(judge[k], str) for k in JUDGE_BLOCK_KEYS): raise EvalDirError("eval-run: judge ids must be strings or null", REASON_BAD_DOCUMENT) return {key: judge[key] for key in JUDGE_BLOCK_KEYS} def write_verdicts(path: Path, verdicts: Iterable[Any]) -> Path: """`verdicts.jsonl` — 기준 판정 전부(근거·원 응답 포함, 데이터 홈 전용 — 계획 L12 §2.7 · D-L12-8). 한 줄 = 판정 dataclass 의 JSON(키 순서 = 필드 순서, compact, `ensure_ascii=False`). UTF-8 로 옮길 수 없는 문자열(짝 없는 서로게이트)이 든 줄만 `ensure_ascii=True` 로 적는다 — 유료 판정 한 건이 파일 전체 쓰기를 깨뜨리지 않게. 레포 밖 검사는 디렉토리를 만들 때 이미 했다(`create_evaluation_dir`). """ lines: list[str] = [] for verdict in verdicts: record = dataclasses.asdict(verdict) line = json.dumps(record, ensure_ascii=False, separators=(",", ":"), allow_nan=False) try: line.encode("utf-8") except UnicodeEncodeError: line = json.dumps(record, ensure_ascii=True, separators=(",", ":"), allow_nan=False) lines.append(line + "\n") target = Path(path) / VERDICTS_FILE target.write_text("".join(lines), encoding="utf-8") return target def _check_offset(value: str) -> None: try: parsed = datetime.fromisoformat(value) except (TypeError, ValueError): raise EvalDirError( "eval-run: evaluated_at is not an ISO 8601 time", REASON_BAD_DOCUMENT ) from None if parsed.tzinfo is None: raise EvalDirError("eval-run: evaluated_at needs a UTC offset", REASON_BAD_DOCUMENT) def _json_mapping(value: Mapping[str, Any] | None) -> dict[str, Any] | None: """평가기 설정을 JSON 으로 옮길 수 있는 사본으로. 설정이 없으면(기본 평가기) None.""" if value is None: return None if not isinstance(value, Mapping): raise EvalDirError("eval-run: evaluator_config must be a mapping", REASON_BAD_DOCUMENT) try: return json.loads(json.dumps(dict(value), ensure_ascii=False)) except (TypeError, ValueError): raise EvalDirError( "eval-run: evaluator_config is not JSON serializable", REASON_BAD_DOCUMENT ) from None def write_eval_run(path: Path, doc: Mapping[str, Any]) -> Path: """`eval-run.json` 원자적 쓰기(직렬화 → 같은 디렉토리 임시 파일 → fsync → `os.replace`).""" text = json.dumps(doc, ensure_ascii=False, indent=2) + "\n" target = Path(path) / EVAL_RUN_FILE fd, tmp_name = tempfile.mkstemp(dir=path, prefix=_TMP_PREFIX, suffix=_TMP_SUFFIX) tmp = Path(tmp_name) try: with os.fdopen(fd, "w", encoding="utf-8") as fh: fh.write(text) fh.flush() os.fsync(fh.fileno()) os.replace(tmp, target) except BaseException: tmp.unlink(missing_ok=True) raise return target def remove_partial(path: Path, env: Mapping[str, str] | None = None) -> None: """끝나지 못한 평가 디렉토리를 치운다 — 평가 루트 아래의 디렉토리만(다른 곳은 `EvalDirError`).""" resolved = Path(path).resolve() root = evaluations_root(env).resolve() if root not in resolved.parents: raise EvalDirError( "evaluation directory: refusing to remove a path outside the root", REASON_OUTSIDE_ROOT ) shutil.rmtree(resolved)