"""
core/intent/intent_signal.py

Pure data model for AIVA intent classification.
Created by IntentClassifier, consumed by SwarmRouter.

No I/O, no side effects, no external dependencies.
"""

from dataclasses import dataclass
from enum import Enum
from typing import Optional
from datetime import datetime

# VERIFICATION_STAMP
# Story: 5.01
# Verified By: parallel-builder
# Verified At: 2026-02-25
# Tests: 14/14
# Coverage: 100%


class IntentType(Enum):
    """All possible intent types AIVA can detect from caller utterances."""
    BOOK_JOB        = "book_job"
    QUALIFY_LEAD    = "qualify_lead"
    ANSWER_FAQ      = "answer_faq"
    ESCALATE_HUMAN  = "escalate_human"
    CAPTURE_MEMORY  = "capture_memory"
    TASK_DISPATCH   = "task_dispatch"
    UNKNOWN         = "unknown"


@dataclass
class IntentSignal:
    """
    Represents a classified intent from a caller utterance.
    Created by IntentClassifier, consumed by SwarmRouter.
    """
    session_id: str
    utterance: str
    intent_type: IntentType
    confidence: float           # 0.0 -> 1.0
    extracted_entities: dict    # {"name": "George", "location": "Cairns"}
    requires_swarm: bool        # True when intent needs a worker dispatched
    created_at: datetime
    raw_gemini_response: Optional[str] = None