solar_eval/stores/base.py

"""Abstract result store protocol for runner persistence."""

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class ResultStore(Protocol):
    """Protocol for persisting run results.

    The runner calls these methods during execution. Implementations can
    persist to MongoDB, JSONL files, or any other backend.
    """

    async def update_run(self, run_id: str, data: dict[str, Any]) -> None:
        """Update run metadata (status, timestamps, sample counts)."""
        ...

    async def insert_run_result(self, data: dict[str, Any]) -> str:
        """Save a single inference result. Returns result ID."""
        ...

    async def create_evaluation(self, data: dict[str, Any]) -> str:
        """Save aggregated evaluation scores. Returns evaluation ID."""
        ...

    async def insert_eval_details(self, details: list[dict[str, Any]]) -> int:
        """Save per-sample evaluation details. Returns count inserted."""
        ...