script-build-and-framework-tmp/agent/agent/orchestration/evidence.py

"""Guarded V2 evidence queries scoped to a frozen validation snapshot."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict, List, Protocol

from .models import ArtifactRef


class EvidenceError(RuntimeError):
    pass


class EvidenceOwnershipError(EvidenceError):
    pass


class EvidenceBudgetExceeded(EvidenceError):
    pass


class EvidenceProviderError(EvidenceError):
    pass


@dataclass(frozen=True)
class EvidenceQuery:
    root_trace_id: str
    task_id: str
    attempt_id: str
    snapshot_id: str
    validation_id: str
    query: str
    limit: int = 10

    def __post_init__(self) -> None:
        for name in (
            "root_trace_id",
            "task_id",
            "attempt_id",
            "snapshot_id",
            "validation_id",
            "query",
        ):
            value = getattr(self, name)
            if not isinstance(value, str) or not value.strip():
                raise ValueError(f"{name} must be a non-empty string")
        if (
            isinstance(self.limit, bool)
            or not isinstance(self.limit, int)
            or self.limit < 1
        ):
            raise ValueError("limit must be a positive integer")


@dataclass(frozen=True)
class EvidenceProviderResult:
    items: List[Dict[str, Any]] = field(default_factory=list)
    evidence_refs: List[ArtifactRef] = field(default_factory=list)


@dataclass(frozen=True)
class EvidenceResponse:
    items: List[Dict[str, Any]]
    evidence_refs: List[ArtifactRef]
    queries_used: int
    queries_remaining: int


class EvidenceProvider(Protocol):
    async def query(self, request: EvidenceQuery) -> EvidenceProviderResult: ...


class EvidencePort(Protocol):
    async def query(
        self,
        actor_context: Dict[str, Any],
        request: EvidenceQuery,
    ) -> EvidenceResponse: ...


__all__ = [
    "EvidenceBudgetExceeded",
    "EvidenceError",
    "EvidenceOwnershipError",
    "EvidencePort",
    "EvidenceProvider",
    "EvidenceProviderError",
    "EvidenceProviderResult",
    "EvidenceQuery",
    "EvidenceResponse",
]