src/example_cache.py

"""Stable example output loading for demo playback."""

from __future__ import annotations

import json
from pathlib import Path

from src.models.schema import GenerationResult, TraceRecord


DEFAULT_SAMPLE_TRACE_DIR = Path("data/traces/samples")


def sample_trace_path(index: int, sample_dir: Path = DEFAULT_SAMPLE_TRACE_DIR) -> Path | None:
    """Return the committed sample trace path for a 0-based example index."""
    trace_id = f"sample-{index + 1:02d}"
    matches = sorted(sample_dir.glob(f"{trace_id}-*.json"))
    return matches[0] if matches else None


def load_sample_generation(index: int, sample_dir: Path = DEFAULT_SAMPLE_TRACE_DIR) -> GenerationResult | None:
    path = sample_trace_path(index, sample_dir)
    if path is None:
        return None

    trace = TraceRecord.model_validate(json.loads(path.read_text(encoding="utf-8")))
    return GenerationResult(
        object_understanding=trace.object_understanding,
        persona=trace.persona,
        diary=trace.diary,
        trace=trace,
        trace_path=str(path),
    )