"""
Voice/Vision alignment receipts.
"""
from __future__ import annotations

from typing import Optional, List
from datetime import datetime, timezone
from pydantic import Field

from receipts.base import BaseReceipt


class VoiceVisionClarifyReceipt(BaseReceipt):
    """
    Emitted when a voice-driven action cannot be grounded to the current perception
    without ambiguity.
    """

    receipt_type: str = Field(default="VoiceVisionClarifyReceipt", alias="type")
    domain: str = Field(default="organism")
    organ: str = Field(default="sensorium")

    voice_target: str = Field(description="Voice target text (normalized)")
    candidates: List[dict] = Field(
        default_factory=list,
        description="Candidate detections that partially match the voice target",
    )
    reason: str = Field(default="target_not_visible")

    @classmethod
    def build(
        cls,
        *,
        voice_target: str,
        candidates: Optional[List[dict]] = None,
        reason: str = "target_not_visible",
        parent_ids: Optional[List[str]] = None,
    ) -> "VoiceVisionClarifyReceipt":
        return cls(
            receipt_id=f"vv_clarify_{int(datetime.now(timezone.utc).timestamp() * 1000)}",
            ts=datetime.now(timezone.utc),
            voice_target=voice_target,
            candidates=candidates or [],
            reason=reason,
            parent_ids=parent_ids or [],
        )
