src/core/spiritual_state.py

# spiritual_state.py
"""
Spiritual State Machine - Data models for simplified spiritual triage.

Defines the state machine for background spiritual monitoring:
- GREEN: Normal medical dialog, no distress indicators
- YELLOW: Potential distress detected, soft triage in progress
- RED: Severe distress confirmed, referral needed

Requirements: 5.1, 7.1
"""

from enum import Enum
from dataclasses import dataclass, field
from typing import List, Optional


class SpiritualState(Enum):
    """
    Spiritual monitoring state.
    
    GREEN: Normal - no distress indicators detected
    YELLOW: Potential - soft triage in progress (max 3 questions)
    RED: Severe - referral needed
    AWAITING_CONSENT: RED detected, waiting for patient consent response
    
    Requirements: 5.1, 7.1
    """
    GREEN = "green"
    YELLOW = "yellow"
    RED = "red"
    AWAITING_CONSENT = "awaiting_consent"


class TriageOutcome(Enum):
    """
    Outcome of soft triage evaluation.
    
    RESOLVED_GREEN: Patient is coping well, return to medical dialog
    ESCALATE_RED: Distress confirmed, generate referral
    CONTINUE: Need more information (ask another question)
    
    Requirements: 3.3
    """
    RESOLVED_GREEN = "resolved_green"
    ESCALATE_RED = "escalate_red"
    CONTINUE = "continue"


@dataclass
class SpiritualAssessment:
    """
    Result of spiritual monitor classification.
    
    Attributes:
        state: Classified spiritual state (GREEN/YELLOW/RED)
        indicators: List of detected distress indicators
        confidence: Classification confidence (0.0-1.0)
        reasoning: Explanation of classification decision
        
    Requirements: 2.1, 5.1
    """
    state: SpiritualState
    indicators: List[str] = field(default_factory=list)
    confidence: float = 0.0
    reasoning: str = ""


@dataclass
class TriageSession:
    """
    Tracks soft triage session state.
    
    Attributes:
        question_count: Number of questions asked (max 3)
        questions_asked: List of triage questions asked
        patient_responses: List of patient responses
        outcome: Final triage outcome (None if in progress)
        
    Requirements: 3.1, 7.2
    """
    question_count: int = 0
    questions_asked: List[str] = field(default_factory=list)
    patient_responses: List[str] = field(default_factory=list)
    outcome: Optional[TriageOutcome] = None
    
    def add_exchange(self, question: str, response: str):
        """Add a question-response exchange to the session."""
        self.questions_asked.append(question)
        self.patient_responses.append(response)
        self.question_count += 1
    
    def is_at_limit(self) -> bool:
        """Check if max questions (3) reached."""
        return self.question_count >= 3


@dataclass
class SessionSpiritualState:
    """
    Complete spiritual state for a session.
    
    Tracks current state, triage session (if active), and history.
    
    Attributes:
        spiritual_state: Current state (GREEN/YELLOW/RED/AWAITING_CONSENT)
        triage_session: Active triage session (None if not in YELLOW)
        last_assessment: Most recent spiritual assessment
        state_history: List of state transitions for debugging
        pending_referral: Referral data waiting for consent (None if not awaiting)
        
    Requirements: 7.1, 7.2, 7.3
    """
    spiritual_state: SpiritualState = SpiritualState.GREEN
    triage_session: Optional[TriageSession] = None
    last_assessment: Optional[SpiritualAssessment] = None
    state_history: List[str] = field(default_factory=list)
    pending_referral: Optional[dict] = None
    
    def transition_to(self, new_state: SpiritualState, reason: str = ""):
        """
        Transition to a new spiritual state.
        
        Logs the transition and manages triage session lifecycle.
        
        Requirements: 7.1, 7.3
        """
        old_state = self.spiritual_state
        self.spiritual_state = new_state
        
        # Log transition
        transition_log = f"{old_state.value} -> {new_state.value}"
        if reason:
            transition_log += f" ({reason})"
        self.state_history.append(transition_log)
        
        # Manage triage session
        if new_state == SpiritualState.YELLOW and self.triage_session is None:
            self.triage_session = TriageSession()
        elif new_state != SpiritualState.YELLOW:
            self.triage_session = None
    
    def reset(self):
        """
        Reset spiritual state to GREEN.
        
        Called at session end.
        
        Requirements: 7.4
        """
        self.spiritual_state = SpiritualState.GREEN
        self.triage_session = None
        self.last_assessment = None
        self.state_history.append("RESET -> green")
    
    def get_state(self) -> SpiritualState:
        """Get current spiritual state."""
        return self.spiritual_state
    
    def is_in_triage(self) -> bool:
        """Check if currently in soft triage (YELLOW state)."""
        return self.spiritual_state == SpiritualState.YELLOW
    
    def is_awaiting_consent(self) -> bool:
        """Check if waiting for patient consent response."""
        return self.spiritual_state == SpiritualState.AWAITING_CONSENT
    
    def should_force_triage_decision(self) -> bool:
        """
        Check if triage should force a decision.
        
        Returns True if 3 questions asked without resolution.
        
        Requirements: 3.6
        """
        if self.triage_session is None:
            return False
        return self.triage_session.is_at_limit()