Skip to content

"Vibe-Trading: Your Personal Trading Agent"

13.6 KB
Raw Blame
"""Strategy and factor artifact store — Protocol + in-memory reference implementation.

The ``StrategyStoreProtocol`` defines the abstract interface for persisting
strategy/factor artifacts, bench results, and decay snapshots.  Concrete
backends (SQLite, DuckDB, JSON, …) will be decided by the community via
GitHub Issue #455.

``InMemoryStrategyStore`` is a fully functional reference implementation backed
by Python dicts and lists, suitable for tests and as a template for concrete
backends.
"""

from __future__ import annotations

import threading
import uuid
from dataclasses import replace
from datetime import datetime, timezone
from functools import wraps
from typing import Callable, Sequence, TypeVar, runtime_checkable
from typing import Protocol

from src.strategy_store.models import (
    Artifact,
    ArtifactStatus,
    ArtifactType,
    BenchResult,
    DecaySnapshot,
    ValidationStatus,
    validate_validation_status_transition,
)


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def _now_iso() -> str:
    """Return the current UTC time as an ISO-8601 string."""
    return datetime.now(timezone.utc).isoformat()


def _new_artifact_id() -> str:
    """Generate a unique artifact identifier."""
    return f"art_{uuid.uuid4().hex[:12]}"


F = TypeVar("F", bound=Callable)


def _synchronized(method: F) -> F:
    """Serialize access to shared in-memory state."""

    @wraps(method)
    def wrapper(self, *args, **kwargs):  # type: ignore[no-untyped-def]
        with self._lock:
            return method(self, *args, **kwargs)

    return wrapper  # type: ignore[return-value]


# ---------------------------------------------------------------------------
# Protocol — abstract store interface
# ---------------------------------------------------------------------------


@runtime_checkable
class StrategyStoreProtocol(Protocol):
    """Abstract interface for the strategy/factor artifact store.

    Concrete implementations may use SQLite, DuckDB, JSON, or any other backend.
    The community will decide on the production backend via GitHub Issue #455.
    """

    # --- Artifact CRUD ---

    def register_artifact(self, artifact: Artifact) -> str:
        """Register a new artifact. Returns the artifact_id."""
        ...

    def get_artifact(self, artifact_id: str) -> Artifact | None:
        """Get a single artifact by ID. Returns None if not found."""
        ...

    def list_artifacts(
        self,
        *,
        type: ArtifactType | None = None,
        status: ArtifactStatus | None = None,
        universe: str | None = None,
        limit: int = 100,
    ) -> Sequence[Artifact]:
        """List artifacts with optional filters."""
        ...

    def update_status(
        self,
        artifact_id: str,
        status: ArtifactStatus,
        *,
        reason: str | None = None,
    ) -> Artifact | None:
        """Transition an artifact to a new status. Returns updated artifact or None."""
        ...

    def update_artifact(self, artifact: Artifact) -> Artifact | None:
        """Replace an artifact record. Returns updated artifact or None if not found."""
        ...

    # --- Bench history ---

    def record_bench(self, result: BenchResult) -> int:
        """Record a bench result. Returns the result ID."""
        ...

    def record_bench_once(self, result: BenchResult) -> int | None:
        """Atomically record new evidence; ignore location and grading metadata."""
        ...

    def get_bench_history(
        self,
        artifact_id: str,
        *,
        limit: int = 50,
        bench_types: Sequence[str] | None = None,
    ) -> Sequence[BenchResult]:
        """Get bench history for an artifact, newest first.

        Args:
            artifact_id: Artifact whose bench rows are returned.
            limit: Maximum number of rows.
            bench_types: When given, only rows of these bench types are
                returned, and ``limit`` applies after the filter.

        Returns:
            Matching bench results, newest first.
        """
        ...

    def has_bench_result(self, result: BenchResult) -> bool:
        """Return whether an identical bench row is already stored.

        Identity uses the artifact, evaluation windows and measured metrics.
        IDs, timestamps, directories, bench labels and grading are metadata.

        Args:
            result: Candidate bench result.

        Returns:
            ``True`` when a stored row matches ``result``.
        """
        ...

    # --- Decay snapshots ---

    def record_decay_snapshot(self, snapshot: DecaySnapshot) -> int:
        """Record a decay monitoring snapshot. Returns the snapshot ID."""
        ...

    def get_decay_history(
        self, artifact_id: str, *, limit: int = 20
    ) -> Sequence[DecaySnapshot]:
        """Get decay snapshots for an artifact, newest first."""
        ...


# ---------------------------------------------------------------------------
# In-memory reference implementation
# ---------------------------------------------------------------------------


class InMemoryStrategyStore:
    """Dict/list-backed reference implementation of ``StrategyStoreProtocol``.

    Thread-safe via ``threading.RLock``.  Intended for tests and as a template
    for concrete persistent backends.
    """

    def __init__(self) -> None:
        self._lock = threading.RLock()
        self._artifacts: dict[str, Artifact] = {}
        self._bench_results: list[BenchResult] = []
        self._decay_snapshots: list[DecaySnapshot] = []
        self._bench_counter: int = 0
        self._decay_counter: int = 0

    # -- Artifact CRUD -------------------------------------------------------

    @_synchronized
    def register_artifact(self, artifact: Artifact) -> str:
        """Register a new artifact, assigning an ID and timestamps.

        Returns:
            The assigned ``artifact_id``.
        """
        for existing in self._artifacts.values():
            if existing.name == artifact.name and existing.universe == artifact.universe:
                raise ValueError(
                    f"artifact '{artifact.name}' already exists in "
                    f"universe '{artifact.universe}'"
                )
        # A brand-new record has no prior validation history, so its implicit
        # "current" state is UNVALIDATED — registering directly with
        # validation_status=APPROVED would skip the VALIDATED step.
        validate_validation_status_transition(
            ValidationStatus.UNVALIDATED, artifact.validation_status
        )
        now = _now_iso()
        artifact_id = artifact.id or _new_artifact_id()
        stored = replace(
            artifact,
            id=artifact_id,
            created_at=artifact.created_at or now,
            updated_at=now,
        )
        self._artifacts[artifact_id] = stored
        return artifact_id

    @_synchronized
    def get_artifact(self, artifact_id: str) -> Artifact | None:
        """Return a single artifact by ID, or ``None``."""
        return self._artifacts.get(artifact_id)

    @_synchronized
    def list_artifacts(
        self,
        *,
        type: ArtifactType | None = None,
        status: ArtifactStatus | None = None,
        universe: str | None = None,
        limit: int = 100,
    ) -> Sequence[Artifact]:
        """List artifacts with composable filters, newest first."""
        results: list[tuple[int, Artifact]] = []
        for position, art in enumerate(self._artifacts.values()):
            if type is not None and art.type != type:
                continue
            if status is not None and art.status != status:
                continue
            if universe is not None and art.universe != universe:
                continue
            results.append((position, art))

        # Sort by created_at descending (newest first), breaking ties on
        # insertion order. Sorting is stable and reverse=True does not reorder
        # equal keys, so without the tiebreaker records sharing a timestamp
        # come back oldest first. Timestamps collide readily: _now_iso() has
        # only the clock's resolution behind it.
        results.sort(key=lambda pair: (pair[1].created_at or "", pair[0]), reverse=True)
        return [art for _, art in results[:limit]]

    @_synchronized
    def update_status(
        self,
        artifact_id: str,
        status: ArtifactStatus,
        *,
        reason: str | None = None,
    ) -> Artifact | None:
        """Transition an artifact to a new status.

        Sets ``disabled_at`` and ``disabled_reason`` when transitioning to
        ``DISABLED``.  Returns the updated artifact, or ``None`` if not found.
        """
        existing = self._artifacts.get(artifact_id)
        if existing is None:
            return None

        now = _now_iso()
        updates: dict = {
            "status": status,
            "updated_at": now,
        }

        if status is ArtifactStatus.DISABLED:
            updates["disabled_at"] = now
            if reason is not None:
                updates["disabled_reason"] = reason
        else:
            # Clear disabled fields when moving out of DISABLED.
            if existing.status is ArtifactStatus.DISABLED:
                updates["disabled_at"] = None
                updates["disabled_reason"] = None

        updated = replace(existing, **updates)
        self._artifacts[artifact_id] = updated
        return updated

    @_synchronized
    def update_artifact(self, artifact: Artifact) -> Artifact | None:
        """Replace an artifact record.

        Returns the updated artifact, or ``None`` if the ID is not found.
        """
        existing = self._artifacts.get(artifact.id)
        if existing is None:
            return None

        # Structural enforcement of the validation state machine: an
        # unvalidated model can never be updated straight into APPROVED.
        validate_validation_status_transition(
            existing.validation_status, artifact.validation_status
        )

        now = _now_iso()
        stored = replace(artifact, updated_at=now)
        self._artifacts[artifact.id] = stored
        return stored

    # -- Bench history -------------------------------------------------------

    @_synchronized
    def record_bench(self, result: BenchResult) -> int:
        """Record a bench result, assigning an auto-increment ID.

        Returns:
            The assigned result ID.
        """
        self._bench_counter += 1
        now = _now_iso()
        stored = replace(
            result,
            id=self._bench_counter,
            created_at=result.created_at or now,
        )
        self._bench_results.append(stored)
        return stored.id

    @_synchronized
    def record_bench_once(self, result: BenchResult) -> int | None:
        """Record new evidence once under the same lock as the duplicate check."""
        if self.has_bench_result(result):
            return None
        return self.record_bench(result)

    @_synchronized
    def get_bench_history(
        self,
        artifact_id: str,
        *,
        limit: int = 50,
        bench_types: Sequence[str] | None = None,
    ) -> Sequence[BenchResult]:
        """Return bench results for an artifact, newest first.

        Args:
            artifact_id: Artifact whose bench rows are returned.
            limit: Maximum number of rows.
            bench_types: When given, only rows of these bench types are
                returned, and ``limit`` applies after the filter.

        Returns:
            Matching bench results, newest first.
        """
        matched = [
            r
            for r in self._bench_results
            if r.artifact_id == artifact_id
            and (bench_types is None or r.bench_type in bench_types)
        ]
        # id ascends with insertion, so it breaks timestamp ties newest first.
        matched.sort(key=lambda r: (r.created_at or "", r.id or 0), reverse=True)
        return matched[:limit]

    @_synchronized
    def has_bench_result(self, result: BenchResult) -> bool:
        """Return whether an identical bench row is already stored.

        Args:
            result: Candidate measurement; location, time and grading metadata
                are ignored.

        Returns:
            ``True`` when a stored measurement has the same artifact, windows and metrics.
        """
        probe = replace(result, id=None, created_at="", run_dir=None, bench_type="", category=None)
        return any(
            replace(stored, id=None, created_at="", run_dir=None, bench_type="", category=None) == probe
            for stored in self._bench_results
        )

    # -- Decay snapshots -----------------------------------------------------

    @_synchronized
    def record_decay_snapshot(self, snapshot: DecaySnapshot) -> int:
        """Record a decay monitoring snapshot, assigning an auto-increment ID.

        Returns:
            The assigned snapshot ID.
        """
        self._decay_counter += 1
        now = _now_iso()
        stored = replace(
            snapshot,
            id=self._decay_counter,
            created_at=snapshot.created_at or now,
        )
        self._decay_snapshots.append(stored)
        return stored.id

    @_synchronized
    def get_decay_history(
        self, artifact_id: str, *, limit: int = 20
    ) -> Sequence[DecaySnapshot]:
        """Return decay snapshots for an artifact, newest first."""
        matched = [s for s in self._decay_snapshots if s.artifact_id == artifact_id]
        # id ascends with insertion, so it breaks timestamp ties newest first.
        matched.sort(key=lambda s: (s.created_at or "", s.id or 0), reverse=True)
        return matched[:limit]