Upload 5 files

engine/drift.py

@@ -0,0 +1,161 @@
+def apply_context_shift(persona, scenario):
+    """
+    Apply contextual scenario effects to persona's current state.
+    This simulates how external events affect the client's emotional state.
+    """
+    state = persona.get("default_state", {})
+    effects = scenario.get("effects", {})
+    
+    # Apply each effect with bounds checking
+    for key, change in effects.items():
+        if key in state and isinstance(state[key], (int, float)):
+            current_value = state[key]
+            new_value = current_value + change
+            # Clamp between 0 and 1
+            state[key] = max(0.0, min(1.0, round(new_value, 3)))
+    
+    # Add context to emotional memory if it exists
+    if "emotional_memory" in state:
+        if not isinstance(state["emotional_memory"], list):
+            state["emotional_memory"] = []
+        state["emotional_memory"].append(
+            f"context: {scenario.get('description', scenario.get('scenario'))}"
+        )
+        # Keep only last 5 memories
+        state["emotional_memory"] = state["emotional_memory"][-5:]
+    
+    return persona
+
+
+def get_current_mode(state):
+    """
+    Determine the client's current emotional mode based on state values.
+    This helps select appropriate response templates and tone.
+    """
+    anxiety = state.get("anxiety", 0.5)
+    trust = state.get("trust", 0.5)
+    openness = state.get("openness", 0.5)
+    
+    # Crisis threshold
+    if anxiety > 0.8:
+        return "decompensating"
+    
+    # Defensive/triggered
+    if anxiety > 0.6 and openness < 0.3:
+        return "triggered"
+    
+    # Guarded but present
+    if trust < 0.4 and openness < 0.5:
+        return "guarded"
+    
+    # Opening up
+    if trust > 0.6 and openness > 0.6:
+        return "trusting"
+    
+    # Recovering/hopeful
+    if anxiety < 0.4 and trust > 0.5:
+        return "recovering"
+    
+    # Baseline
+    return "baseline"
+
+
+def calculate_state_change(current_state, student_response):
+    """
+    Calculate how the student's response affects the client's emotional state.
+    This is a simplified heuristic - in production, would use more sophisticated NLP.
+    """
+    response_lower = student_response.lower()
+    changes = {}
+    
+    # Positive indicators (validation, open questions, empathy)
+    validating_words = ["understand", "sounds like", "seems", "feel", "must be", "makes sense"]
+    open_questions = ["tell me more", "what's that like", "how", "what"]
+    empathy_phrases = ["hard", "difficult", "challenging", "tough"]
+    
+    # Negative indicators (advice-giving, minimizing, interrogating)
+    advice_words = ["should", "need to", "have to", "must", "why don't you"]
+    minimizing = ["just", "simply", "easy", "only", "at least"]
+    closed_questions = ["did you", "have you", "are you", "do you"]
+    
+    validation_score = sum(1 for word in validating_words if word in response_lower)
+    open_q_score = sum(1 for phrase in open_questions if phrase in response_lower)
+    empathy_score = sum(1 for phrase in empathy_phrases if phrase in response_lower)
+    
+    advice_score = sum(1 for word in advice_words if word in response_lower)
+    minimizing_score = sum(1 for word in minimizing if word in response_lower)
+    
+    # Calculate changes
+    positive_impact = (validation_score * 0.05 + open_q_score * 0.04 + empathy_score * 0.03)
+    negative_impact = (advice_score * 0.08 + minimizing_score * 0.06)
+    
+    changes["trust"] = positive_impact - negative_impact
+    changes["openness"] = positive_impact * 0.8 - negative_impact * 0.5
+    changes["anxiety"] = negative_impact * 0.5 - positive_impact * 0.3
+    
+    # Response length consideration (too short or too long can be problematic)
+    word_count = len(student_response.split())
+    if word_count < 5:
+        changes["openness"] = changes.get("openness", 0) - 0.05
+    elif word_count > 100:
+        changes["anxiety"] = changes.get("anxiety", 0) + 0.05
+    
+    return changes
+
+
+def apply_response_effects(state, student_response):
+    """
+    Apply the effects of the student's response to the client's state.
+    """
+    changes = calculate_state_change(state, student_response)
+    
+    for key, change in changes.items():
+        if key in state and isinstance(state[key], (int, float)):
+            current_value = state[key]
+            new_value = current_value + change
+            state[key] = max(0.0, min(1.0, round(new_value, 3)))
+    
+    return state
+
+
+def generate_teaching_note(state, student_response, mode):
+    """
+    Generate teaching feedback based on the interaction.
+    """
+    response_lower = student_response.lower()
+    notes = []
+    
+    # Check for common issues
+    if any(word in response_lower for word in ["should", "need to", "have to"]):
+        notes.append("⚠️ Advice-giving detected. Consider asking open questions instead of giving directives.")
+    
+    if any(word in response_lower for word in ["just", "simply", "only"]):
+        notes.append("⚠️ Potential minimizing language. Avoid words that might diminish the client's experience.")
+    
+    if response_lower.count("?") > 2:
+        notes.append("⚠️ Multiple questions detected. Consider asking one question at a time to avoid overwhelming the client.")
+    
+    if len(student_response.split()) < 10:
+        notes.append("💡 Very brief response. Consider adding validation or reflection before asking questions.")
+    
+    # Check for strengths
+    if any(phrase in response_lower for phrase in ["sounds like", "seems", "hear you"]):
+        notes.append("✅ Good use of reflection and validation.")
+    
+    if "tell me more" in response_lower or "what's that like" in response_lower:
+        notes.append("✅ Effective use of open-ended questions.")
+    
+    # Mode-specific feedback
+    if mode == "triggered" and state.get("trust", 0) < 0.4:
+        notes.append("📊 Client is defensive. Consider backing off and focusing on rapport building.")
+    
+    if mode == "trusting" and state.get("openness", 0) > 0.6:
+        notes.append("📊 Strong therapeutic alliance forming. This is a good time to explore deeper issues.")
+    
+    if mode == "decompensating":
+        notes.append("🚨 Client may be in crisis. Assess safety and consider referral to crisis services.")
+    
+    if not notes:
+        notes.append("✅ Solid therapeutic response. Continue building rapport.")
+    
+    return "\n".join(notes)

engine/loader.py

@@ -0,0 +1,191 @@
+import yaml
+import os
+
+def load_persona(path):
+    """
+    Load a mental health persona from YAML file.
+    Validates required fields for OT simulation.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Persona file not found: {path}")
+    
+    with open(path, "r", encoding="utf-8") as f:
+        persona = yaml.safe_load(f)
+    
+    # Required keys for mental health personas
+    required_keys = [
+        "persona_name",
+        "age", 
+        "role",
+        "system_prompt",
+        "facts",
+        "default_state"
+    ]
+    
+    for key in required_keys:
+        if key not in persona:
+            raise ValueError(f"Missing required key in persona: {key}")
+    
+    # Ensure default_state has required emotional metrics
+    state = persona.get("default_state", {})
+    required_state_keys = ["anxiety", "trust", "openness", "mode"]
+    
+    for key in required_state_keys:
+        if key not in state:
+            print(f"Warning: Missing state key '{key}' in persona. Using default value.")
+            if key == "mode":
+                state[key] = "baseline"
+            else:
+                state[key] = 0.5
+    
+    # Initialize emotional_memory if not present
+    if "emotional_memory" not in state:
+        state["emotional_memory"] = []
+    
+    # Ensure facts is a list
+    if not isinstance(persona.get("facts"), list):
+        print("Warning: facts should be a list. Converting.")
+        facts = persona.get("facts", [])
+        if isinstance(facts, dict):
+            persona["facts"] = list(facts.values())
+        else:
+            persona["facts"] = []
+    
+    return persona
+
+
+def validate_persona(persona):
+    """
+    Validate that a persona has all necessary components for simulation.
+    Returns (is_valid, error_message)
+    """
+    # Check persona name
+    if not persona.get("persona_name"):
+        return False, "Persona must have a name"
+    
+    # Check default state
+    state = persona.get("default_state", {})
+    if not state:
+        return False, "Persona must have a default_state"
+    
+    # Check that anxiety, trust, openness are numeric
+    for key in ["anxiety", "trust", "openness"]:
+        value = state.get(key)
+        if value is None:
+            return False, f"default_state missing required key: {key}"
+        if not isinstance(value, (int, float)):
+            return False, f"default_state.{key} must be numeric"
+        if not 0 <= value <= 1:
+            return False, f"default_state.{key} must be between 0 and 1"
+    
+    # Check tone_guidance exists
+    if not persona.get("tone_guidance"):
+        return False, "Persona must have tone_guidance"
+    
+    # Check that tone_guidance has mode entries
+    tone_guidance = persona.get("tone_guidance", {})
+    recommended_modes = ["baseline", "guarded", "triggered", "trusting", "decompensating"]
+    
+    missing_modes = [mode for mode in recommended_modes if mode not in tone_guidance]
+    if missing_modes:
+        print(f"Warning: tone_guidance missing modes: {missing_modes}")
+    
+    return True, "Persona is valid"
+
+
+def save_persona(persona, path):
+    """
+    Save a persona to YAML file.
+    """
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.dump(persona, f, sort_keys=False, default_flow_style=False)
+    
+    return path
+
+
+def create_default_persona(name, age, role):
+    """
+    Create a basic persona template for development/testing.
+    """
+    persona = {
+        "persona_name": name,
+        "age": age,
+        "role": role,
+        "system_prompt": f"You are {name}, a {age}-year-old {role}. Respond naturally and stay in character.",
+        "facts": [
+            f"{name} is {age} years old",
+            f"{name} works as a {role}"
+        ],
+        "triggers": [
+            "criticism",
+            "pressure",
+            "isolation"
+        ],
+        "reasoning_style": "Tends to analyze situations carefully before responding.",
+        "tone_guidance": {
+            "baseline": {
+                "voice": "Calm and thoughtful",
+                "example": "I'm doing okay today, thanks for asking."
+            },
+            "guarded": {
+                "voice": "Brief and cautious",
+                "example": "I'd rather not talk about that right now."
+            },
+            "triggered": {
+                "voice": "Defensive or withdrawn",
+                "example": "I don't see how that's relevant."
+            },
+            "trusting": {
+                "voice": "Open and reflective",
+                "example": "You know, I've been thinking about what you said last time..."
+            },
+            "decompensating": {
+                "voice": "Fragmented and overwhelmed",
+                "example": "I just... I can't... it's too much."
+            }
+        },
+        "default_state": {
+            "anxiety": 0.5,
+            "trust": 0.5,
+            "openness": 0.5,
+            "mode": "baseline",
+            "emotional_memory": []
+        },
+        "scripts": {
+            "crisis": "I'm not feeling safe right now. I need to step away.",
+            "deflection": "It's fine. I don't want to make a big deal out of it.",
+            "testing_trust": "Why are you asking about that?",
+            "resistance": "I don't see how talking about this helps."
+        },
+        "resilience_hooks": [
+            f"{name} has coping strategies they've used before",
+            f"{name} values certain relationships in their life"
+        ]
+    }
+    
+    return persona
+
+
+def list_available_personas(persona_dir="./personas"):
+    """
+    List all available persona files.
+    """
+    if not os.path.exists(persona_dir):
+        return []
+    
+    personas = []
+    for filename in os.listdir(persona_dir):
+        if filename.endswith(".yml") or filename.endswith(".yaml"):
+            path = os.path.join(persona_dir, filename)
+            try:
+                persona = load_persona(path)
+                personas.append({
+                    "filename": filename,
+                    "name": persona.get("persona_name", "Unknown"),
+                    "age": persona.get("age", ""),
+                    "role": persona.get("role", "")
+                })
+            except Exception as e:
+                print(f"Error loading {filename}: {e}")
+    
+    return personas

engine/logger.py

@@ -0,0 +1,317 @@
+import os
+from datetime import datetime
+import json
+import yaml
+
+def log_interaction(persona, student_prompt, scenario, response, state, teaching_note):
+    """
+    Log a therapeutic interaction for review and assessment purposes.
+    Creates both human-readable and machine-readable formats.
+    """
+    name = persona.get("persona_name", "Unknown")
+    age = persona.get("age", "")
+    role = persona.get("role", "")
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    # Human-readable transcript
+    transcript = f"""
+╔══════════════════════════════════════════════════════════════╗
+║         OT MENTAL HEALTH SIMULATION TRANSCRIPT               ║
+╚══════════════════════════════════════════════════════════════╝
+
+Timestamp: {timestamp}
+Client: {name} ({age}, {role})
+Scenario Context: {scenario}
+
+─────────────────────────────────────────────────────────────
+
+OT STUDENT RESPONSE:
+{student_prompt}
+
+─────────────────────────────────────────────────────────────
+
+CLIENT RESPONSE:
+{response}
+
+─────────────────────────────────────────────────────────────
+
+EMOTIONAL STATE AFTER INTERACTION:
+• Anxiety Level:    {state.get('anxiety', 0):.2f} {'█' * int(state.get('anxiety', 0) * 10)}
+• Trust Level:      {state.get('trust', 0):.2f} {'█' * int(state.get('trust', 0) * 10)}
+• Openness:         {state.get('openness', 0):.2f} {'█' * int(state.get('openness', 0) * 10)}
+• Current Mode:     {state.get('mode', 'baseline')}
+
+{f"• Physical Discomfort: {state.get('physical_discomfort', 0):.2f}" if 'physical_discomfort' in state else ""}
+{f"• Creative Engagement: {state.get('creative_engagement', 0):.2f}" if 'creative_engagement' in state else ""}
+{f"• Occupational Balance: {state.get('occupational_balance', 0):.2f}" if 'occupational_balance' in state else ""}
+
+─────────────────────────────────────────────────────────────
+
+TEACHING FEEDBACK:
+{teaching_note}
+
+─────────────────────────────────────────────────────────────
+
+EMOTIONAL MEMORY:
+{format_emotional_memory(state.get('emotional_memory', []))}
+
+═════════════════════════════════════════════════════════════
+"""
+    
+    # Save human-readable transcript
+    os.makedirs("transcripts", exist_ok=True)
+    safe_name = name.replace(' ', '_')
+    safe_timestamp = timestamp.replace(':', '-').replace(' ', '_')
+    filename = f"transcripts/{safe_name}_{safe_timestamp}.txt"
+    
+    with open(filename, "w", encoding="utf-8") as f:
+        f.write(transcript)
+    
+    # Save machine-readable JSON for analysis
+    json_data = {
+        "timestamp": timestamp,
+        "client": {
+            "name": name,
+            "age": age,
+            "role": role
+        },
+        "scenario": scenario,
+        "interaction": {
+            "student_prompt": student_prompt,
+            "client_response": response
+        },
+        "state": state,
+        "teaching_note": teaching_note
+    }
+    
+    json_filename = f"transcripts/{safe_name}_{safe_timestamp}.json"
+    with open(json_filename, "w", encoding="utf-8") as f:
+        json.dump(json_data, f, indent=2)
+    
+    return filename
+
+
+def format_emotional_memory(memory_list):
+    """Format emotional memory for display."""
+    if not memory_list:
+        return "No emotional memories recorded yet."
+    
+    formatted = ""
+    for i, memory in enumerate(memory_list, 1):
+        formatted += f"  {i}. {memory}\n"
+    return formatted
+
+
+def log_session_summary(persona, interactions, final_state):
+    """
+    Log a summary of an entire session (multiple interactions).
+    """
+    name = persona.get("persona_name", "Unknown")
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    
+    summary = f"""
+╔══════════════════════════════════════════════════════════════╗
+║              SESSION SUMMARY REPORT                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Client: {name}
+Date: {timestamp}
+Number of Interactions: {len(interactions)}
+
+─────────────────────────────────────────────────────────────
+
+INTERACTION OVERVIEW:
+"""
+    
+    for i, interaction in enumerate(interactions, 1):
+        summary += f"""
+Turn {i}:
+  Student: {interaction.get('student', '')[:80]}...
+  Client Mode: {interaction.get('mode', 'unknown')}
+  Anxiety: {interaction.get('anxiety', 0):.2f} | Trust: {interaction.get('trust', 0):.2f}
+"""
+    
+    summary += f"""
+
+─────────────────────────────────────────────────────────────
+
+FINAL STATE:
+• Anxiety:          {final_state.get('anxiety', 0):.2f}
+• Trust:            {final_state.get('trust', 0):.2f}
+• Openness:         {final_state.get('openness', 0):.2f}
+• Mode:             {final_state.get('mode', 'baseline')}
+
+─────────────────────────────────────────────────────────────
+
+THERAPEUTIC PROGRESS INDICATORS:
+
+Trust Development:    {assess_trust_progress(interactions)}
+Anxiety Management:   {assess_anxiety_progress(interactions)}
+Openness to Engage:   {assess_openness_progress(interactions)}
+
+─────────────────────────────────────────────────────────────
+
+RECOMMENDATIONS FOR FUTURE SESSIONS:
+{generate_recommendations(persona, interactions, final_state)}
+
+═════════════════════════════════════════════════════════════
+"""
+    
+    # Save summary
+    os.makedirs("transcripts/summaries", exist_ok=True)
+    summary_filename = f"transcripts/summaries/{name.replace(' ', '_')}_{timestamp}.txt"
+    
+    with open(summary_filename, "w", encoding="utf-8") as f:
+        f.write(summary)
+    
+    return summary_filename
+
+
+def assess_trust_progress(interactions):
+    """Assess how trust developed over the session."""
+    if len(interactions) < 2:
+        return "Insufficient data"
+    
+    trust_values = [i.get('trust', 0.5) for i in interactions if 'trust' in i]
+    
+    if not trust_values:
+        return "No trust data available"
+    
+    initial = trust_values[0]
+    final = trust_values[-1]
+    change = final - initial
+    
+    if change > 0.15:
+        return f"Strong improvement (+{change:.2f})"
+    elif change > 0.05:
+        return f"Moderate improvement (+{change:.2f})"
+    elif change < -0.15:
+        return f"Significant decline ({change:.2f})"
+    elif change < -0.05:
+        return f"Slight decline ({change:.2f})"
+    else:
+        return f"Stable ({change:+.2f})"
+
+
+def assess_anxiety_progress(interactions):
+    """Assess how anxiety changed over the session."""
+    if len(interactions) < 2:
+        return "Insufficient data"
+    
+    anxiety_values = [i.get('anxiety', 0.5) for i in interactions if 'anxiety' in i]
+    
+    if not anxiety_values:
+        return "No anxiety data available"
+    
+    initial = anxiety_values[0]
+    final = anxiety_values[-1]
+    change = final - initial
+    
+    # Note: For anxiety, decrease is good
+    if change < -0.15:
+        return f"Significant reduction ({change:.2f}) ✓"
+    elif change < -0.05:
+        return f"Moderate reduction ({change:.2f}) ✓"
+    elif change > 0.15:
+        return f"Significant increase (+{change:.2f}) ⚠"
+    elif change > 0.05:
+        return f"Slight increase (+{change:.2f})"
+    else:
+        return f"Stable ({change:+.2f})"
+
+
+def assess_openness_progress(interactions):
+    """Assess how openness changed over the session."""
+    if len(interactions) < 2:
+        return "Insufficient data"
+    
+    openness_values = [i.get('openness', 0.5) for i in interactions if 'openness' in i]
+    
+    if not openness_values:
+        return "No openness data available"
+    
+    initial = openness_values[0]
+    final = openness_values[-1]
+    change = final - initial
+    
+    if change > 0.15:
+        return f"Significant increase (+{change:.2f}) ✓"
+    elif change > 0.05:
+        return f"Moderate increase (+{change:.2f}) ✓"
+    elif change < -0.15:
+        return f"Significant decrease ({change:.2f}) ⚠"
+    elif change < -0.05:
+        return f"Slight decrease ({change:.2f})"
+    else:
+        return f"Stable ({change:+.2f})"
+
+
+def generate_recommendations(persona, interactions, final_state):
+    """Generate recommendations based on session data."""
+    recommendations = []
+    
+    # Check trust level
+    trust = final_state.get('trust', 0.5)
+    if trust < 0.4:
+        recommendations.append("• Focus on rapport building and validation in next session")
+        recommendations.append("• Avoid pushing for deep disclosure too quickly")
+    elif trust > 0.7:
+        recommendations.append("• Strong therapeutic alliance established")
+        recommendations.append("• May be ready for deeper exploration of difficult topics")
+    
+    # Check anxiety level
+    anxiety = final_state.get('anxiety', 0.5)
+    if anxiety > 0.7:
+        recommendations.append("• Client experiencing high anxiety - prioritize safety and stability")
+        recommendations.append("• Consider anxiety management techniques and grounding")
+    
+    # Check openness
+    openness = final_state.get('openness', 0.5)
+    if openness < 0.3:
+        recommendations.append("• Client is guarded - respect pace and boundaries")
+        recommendations.append("• Use more open-ended questions and active listening")
+    
+    # Mode-specific recommendations
+    mode = final_state.get('mode', 'baseline')
+    if mode == 'decompensating':
+        recommendations.append("• ⚠ CLIENT MAY NEED CRISIS INTERVENTION")
+        recommendations.append("• Assess safety and consider referral to mental health services")
+    elif mode == 'triggered':
+        recommendations.append("• Client ended session in defensive state")
+        recommendations.append("• Begin next session with rapport repair")
+    
+    if not recommendations:
+        recommendations.append("• Continue with current therapeutic approach")
+        recommendations.append("• Build on positive progress from this session")
+    
+    return "\n".join(recommendations)
+
+
+def export_session_for_assessment(persona, interactions, final_state, student_name=""):
+    """
+    Export session data in a format suitable for instructor assessment.
+    """
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    name = persona.get("persona_name", "Unknown")
+    
+    assessment_data = {
+        "student_name": student_name,
+        "timestamp": timestamp,
+        "client": name,
+        "interactions": interactions,
+        "final_state": final_state,
+        "metrics": {
+            "trust_progress": assess_trust_progress(interactions),
+            "anxiety_progress": assess_anxiety_progress(interactions),
+            "openness_progress": assess_openness_progress(interactions)
+        },
+        "recommendations": generate_recommendations(persona, interactions, final_state)
+    }
+    
+    os.makedirs("transcripts/assessments", exist_ok=True)
+    filename = f"transcripts/assessments/{student_name}_{name}_{timestamp}.json"
+    
+    with open(filename, "w", encoding="utf-8") as f:
+        json.dump(assessment_data, f, indent=2)
+    
+    return filename

engine/responder.py

@@ -0,0 +1,448 @@
+import json
+import os
+from engine.drift import get_current_mode, apply_response_effects, generate_teaching_note
+
+# Hugging Face Inference API
+def generate_response(student_prompt, persona, conversation_history):
+    """
+    Generate a response from the client persona using AI or fallback logic.
+    Priority: HF Inference API > Claude API > Local Templates
+    Returns: (response_text, updated_state, teaching_note)
+    """
+    try:
+        # Try Hugging Face Inference API first
+        if os.getenv("HF_TOKEN"):
+            return generate_response_hf(student_prompt, persona, conversation_history)
+        
+        # Try Claude API if available
+        elif os.getenv("ANTHROPIC_API_KEY"):
+            return generate_response_claude(student_prompt, persona, conversation_history)
+        
+        # Fall back to local templates
+        else:
+            return generate_response_local(student_prompt, persona, conversation_history)
+            
+    except Exception as e:
+        from engine.utils import safe_log
+        safe_log("Response generation error", str(e))
+        # Always fall back to local on error
+        return generate_response_local(student_prompt, persona, conversation_history)
+
+
+def generate_response_hf(student_prompt, persona, conversation_history):
+    """
+    Generate response using Hugging Face Inference API (free, non-gated models).
+    """
+    try:
+        from huggingface_hub import InferenceClient
+        
+        state = persona.get("default_state", {})
+        mode = get_current_mode(state)
+        
+        # Apply response effects to state
+        state = apply_response_effects(state, student_prompt)
+        mode = get_current_mode(state)
+        
+        # Build the prompt for the AI model
+        system_prompt = build_system_prompt_for_ai(persona, state, mode)
+        conversation_context = build_conversation_context(conversation_history)
+        
+        # Use Hugging Face Inference API
+        client = InferenceClient(token=os.getenv("HF_TOKEN"))
+        
+        # Try multiple free models in order of preference
+        models = [
+            "mistralai/Mistral-7B-Instruct-v0.2",  # Good quality, not gated
+            "HuggingFaceH4/zephyr-7b-beta",        # Good instruction following
+            "microsoft/Phi-3-mini-4k-instruct",    # Fast and capable
+        ]
+        
+        response_text = None
+        for model in models:
+            try:
+                messages = [
+                    {"role": "system", "content": system_prompt},
+                ]
+                
+                # Add conversation history
+                if conversation_history:
+                    for turn in conversation_history[-3:]:  # Last 3 turns
+                        if "student" in turn:
+                            messages.append({"role": "user", "content": turn["student"]})
+                        if "client" in turn:
+                            messages.append({"role": "assistant", "content": turn["client"]})
+                
+                # Add current prompt
+                messages.append({"role": "user", "content": student_prompt})
+                
+                # Generate response
+                response = client.chat_completion(
+                    messages=messages,
+                    model=model,
+                    max_tokens=300,
+                    temperature=0.7,
+                    stream=False
+                )
+                
+                response_text = response.choices[0].message.content.strip()
+                break  # Success, exit loop
+                
+            except Exception as model_error:
+                from engine.utils import safe_log
+                safe_log(f"HF model {model} failed", str(model_error))
+                continue  # Try next model
+        
+        # If all models failed, fall back to local
+        if not response_text:
+            raise Exception("All HF models failed")
+        
+        # Update emotional memory
+        if "emotional_memory" in state:
+            if not isinstance(state["emotional_memory"], list):
+                state["emotional_memory"] = []
+            memory_tag = determine_memory_tag(student_prompt, mode, state)
+            state["emotional_memory"].append(memory_tag)
+            state["emotional_memory"] = state["emotional_memory"][-5:]
+        
+        # Generate teaching note
+        teaching_note = generate_teaching_note(state, student_prompt, mode)
+        teaching_note += "\n\n💡 Response generated using AI (Hugging Face)"
+        
+        return response_text, state, teaching_note
+        
+    except Exception as e:
+        from engine.utils import safe_log
+        safe_log("HF Inference API error", str(e))
+        # Fall back to local generation
+        return generate_response_local(student_prompt, persona, conversation_history)
+
+
+def generate_response_claude(student_prompt, persona, conversation_history):
+    """
+    Generate response using Claude API (optional premium feature).
+    """
+    try:
+        import anthropic
+        
+        state = persona.get("default_state", {})
+        mode = get_current_mode(state)
+        
+        # Apply response effects to state
+        state = apply_response_effects(state, student_prompt)
+        mode = get_current_mode(state)
+        
+        # Build prompts
+        system_prompt = build_system_prompt_for_ai(persona, state, mode)
+        conversation_context = build_conversation_context(conversation_history)
+        
+        # Call Claude API
+        client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+        message = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=400,
+            system=system_prompt,
+            messages=[
+                {"role": "user", "content": f"{conversation_context}\n\nOT Student: {student_prompt}"}
+            ]
+        )
+        
+        response_text = message.content[0].text
+        
+        # Update emotional memory
+        if "emotional_memory" in state:
+            if not isinstance(state["emotional_memory"], list):
+                state["emotional_memory"] = []
+            memory_tag = determine_memory_tag(student_prompt, mode, state)
+            state["emotional_memory"].append(memory_tag)
+            state["emotional_memory"] = state["emotional_memory"][-5:]
+        
+        teaching_note = generate_teaching_note(state, student_prompt, mode)
+        teaching_note += "\n\n✨ Response generated using Claude AI (Premium)"
+        
+        return response_text, state, teaching_note
+        
+    except Exception as e:
+        from engine.utils import safe_log
+        safe_log("Claude API error", str(e))
+        return generate_response_local(student_prompt, persona, conversation_history)
+
+
+def generate_response_local(student_prompt, persona, conversation_history):
+    """
+    Local response generation using persona templates and state-based selection.
+    Fallback when no AI available or as primary mode.
+    """
+    state = persona.get("default_state", {})
+    mode = get_current_mode(state)
+    name = persona.get("persona_name", "Client")
+    
+    # Apply response effects to state
+    state = apply_response_effects(state, student_prompt)
+    
+    # Update mode after response effects
+    mode = get_current_mode(state)
+    
+    # Select response based on mode and prompt analysis
+    response = select_response_template(
+        student_prompt,
+        name,
+        mode,
+        state,
+        persona,
+        conversation_history
+    )
+    
+    # Update emotional memory
+    if "emotional_memory" in state:
+        if not isinstance(state["emotional_memory"], list):
+            state["emotional_memory"] = []
+        
+        memory_tag = determine_memory_tag(student_prompt, mode, state)
+        state["emotional_memory"].append(memory_tag)
+        state["emotional_memory"] = state["emotional_memory"][-5:]
+    
+    # Generate teaching note
+    teaching_note = generate_teaching_note(state, student_prompt, mode)
+    teaching_note += "\n\n🔧 Response generated using template system (Local)"
+    
+    return response, state, teaching_note
+
+
+def build_system_prompt_for_ai(persona, state, mode):
+    """
+    Build a detailed system prompt for AI models to generate in-character responses.
+    """
+    name = persona.get("persona_name", "Client")
+    age = persona.get("age", "")
+    role = persona.get("role", "")
+    system_prompt_base = persona.get("system_prompt", "")
+    
+    # Get tone guidance for current mode
+    tone_guidance = persona.get("tone_guidance", {}).get(mode, {})
+    tone_voice = tone_guidance.get("voice", "Natural and authentic")
+    tone_example = tone_guidance.get("example", "")
+    
+    # Get some facts about the persona
+    facts = persona.get("facts", [])
+    key_facts = facts[:5] if isinstance(facts, list) else []
+    
+    # Get resilience hooks
+    resilience = persona.get("resilience_hooks", [])
+    
+    prompt = f"""You are {name}, a {age}-year-old {role}. Stay completely in character and respond naturally.
+
+CHARACTER DESCRIPTION:
+{system_prompt_base}
+
+KEY BACKGROUND:
+{chr(10).join(f"- {fact}" for fact in key_facts)}
+
+CURRENT EMOTIONAL STATE:
+- Anxiety: {state.get('anxiety', 0):.2f} (0=calm, 1=crisis)
+- Trust in therapist: {state.get('trust', 0):.2f} (0=guarded, 1=trusting)
+- Openness: {state.get('openness', 0):.2f} (0=closed, 1=very open)
+- Current mode: {mode}
+
+HOW TO SPEAK IN THIS MODE ({mode}):
+{tone_voice}
+Example: "{tone_example}"
+
+IMPORTANT RULES:
+1. Respond as {name} would - use first person ("I", "my")
+2. Keep responses 3-7 sentences (conversational length)
+3. Match your emotional state - if anxious (>0.6), show it in your words
+4. If trust is low (<0.4), be more guarded
+5. Don't break character or mention that you're an AI
+6. Reference your life naturally (work, activities, relationships)
+7. Show emotional nuance - not every response is the same
+8. React authentically to what the student says
+
+STRENGTHS YOU HAVE:
+{chr(10).join(f"- {hook}" for hook in resilience[:3])}
+
+Respond naturally as {name} would in this situation."""
+
+    return prompt
+
+
+def build_conversation_context(history):
+    """Build context from conversation history for AI models."""
+    if not history:
+        return "This is the beginning of the conversation."
+    
+    context = "Previous conversation:\n"
+    for i, turn in enumerate(history[-3:], 1):  # Last 3 turns
+        if "student" in turn:
+            context += f"Student: {turn['student']}\n"
+        if "client" in turn:
+            context += f"You: {turn['client']}\n"
+    
+    return context
+
+
+def select_response_template(prompt, name, mode, state, persona, history):
+    """
+    Select and customize a response based on the current mode and prompt content.
+    Used for local fallback when AI is unavailable.
+    """
+    prompt_lower = prompt.lower()
+    
+    # Check for specific scenario triggers
+    if is_crisis_query(prompt_lower) and mode == "decompensating":
+        scripts = persona.get("scripts", {})
+        return scripts.get("crisis", "I don't feel safe right now. I need to pause.")
+    
+    # Check if prompt is about specific topics
+    if any(word in prompt_lower for word in ["work", "job", "boss", "brother", "supervisor"]):
+        return handle_work_topic(name, mode, state, persona, prompt_lower)
+    
+    if any(word in prompt_lower for word in ["pain", "hurt", "physical", "body"]):
+        return handle_pain_topic(name, mode, state, persona)
+    
+    if any(word in prompt_lower for word in ["feel", "feeling", "emotion"]):
+        return handle_feelings_topic(name, mode, state, persona, prompt_lower)
+    
+    if any(word in prompt_lower for word in ["family", "dad", "sister", "parent"]):
+        return handle_family_topic(name, mode, state, persona)
+    
+    # Default mode-based responses
+    return get_mode_based_response(name, mode, state, persona)
+
+
+def is_crisis_query(prompt_lower):
+    """Check if the prompt is asking about crisis/safety."""
+    crisis_terms = ["safe", "hurt yourself", "suicide", "end", "can't take"]
+    return any(term in prompt_lower for term in crisis_terms)
+
+
+def handle_work_topic(name, mode, state, persona, prompt_lower):
+    """Generate responses about work-related topics."""
+    if name == "Jack":
+        if mode == "triggered" or mode == "guarded":
+            return "I'd rather not get into it. Work is work, you know?"
+        elif mode == "trusting":
+            return "My brother's been on my case all week. It's like... I can't do anything right in his eyes. And my dad just backs him up because 'he's the foreman.' It's frustrating."
+        else:
+            return "Work's... fine. Same stuff, different day. Framing houses, dealing with Mike being Mike."
+    else:  # Maya
+        if mode == "triggered" or mode == "guarded":
+            return "It's just work stress. Everyone deals with it, right?"
+        elif mode == "trusting":
+            return "Honestly? I feel like I'm drowning. Between agency work and freelance projects, I'm just... constantly behind. And my review is coming up, so there's that pressure too."
+        else:
+            return "Work's been busy. Lots of deadlines. The usual design agency chaos."
+
+
+def handle_pain_topic(name, mode, state, persona):
+    """Generate responses about physical pain."""
+    pain_level = state.get("physical_discomfort", 0.5)
+    
+    if name == "Jack":
+        if pain_level > 0.6:
+            if mode == "trusting":
+                return "My knee's been killing me lately. Some days I'm limping by noon. I used to be able to do so much more physically, and now... yeah, it's frustrating."
+            else:
+                return "It's whatever. I just take some ibuprofen and push through. Not like I have a choice."
+        else:
+            return "Knee's okay today. Manageable."
+    else:  # Maya
+        if pain_level > 0.6:
+            if mode == "trusting":
+                return "The headaches are almost daily now, and my wrists hurt when I'm working. I keep thinking, what if I'm doing permanent damage? But I can't afford to stop working."
+            else:
+                return "I get headaches sometimes. Probably just from staring at screens all day. Everyone in design deals with it."
+        else:
+            return "Physically I'm okay. Just the usual screen fatigue."
+
+
+def handle_feelings_topic(name, mode, state, persona, prompt_lower):
+    """Generate responses about emotions and feelings."""
+    anxiety = state.get("anxiety", 0.5)
+    
+    if mode == "decompensating":
+        return "I don't... everything's just a lot right now. I can't really explain it. I'm just overwhelmed."
+    
+    if mode == "triggered" or mode == "guarded":
+        if "about" in prompt_lower:
+            return "I don't know. Fine, I guess?"
+        else:
+            return "I'm fine. Just tired."
+    
+    if mode == "trusting":
+        if name == "Jack":
+            if anxiety > 0.6:
+                return "Honestly? Anxious. Like there's this constant pressure I can't shake. Work, family expectations, feeling stuck... it all just builds up."
+            else:
+                return "Better than I have been, actually. Still stressed, but like... manageable stress?"
+        else:  # Maya
+            if anxiety > 0.6:
+                return "Overwhelmed, mostly. And scared that I'm not good enough for this. Everyone else seems to handle everything so much better than me."
+            else:
+                return "I'm doing okay. Some days are harder than others, but I'm managing."
+    
+    return "I'm alright. Just dealing with the usual stuff."
+
+
+def handle_family_topic(name, mode, state, persona):
+    """Generate responses about family relationships."""
+    if name == "Jack":
+        if mode == "triggered":
+            return "Can we talk about something else?"
+        elif mode == "trusting":
+            return "My dad and I mostly just coexist. He works a lot, I work a lot. My brother... that's complicated since he's also my boss. Mom moved to Arizona years ago."
+        else:
+            return "Family's fine. Nothing new there."
+    else:  # Maya
+        if mode == "triggered":
+            return "I don't really want to get into family stuff right now."
+        elif mode == "trusting":
+            return "My parents are supportive but they don't really understand creative work. My sister's a nurse practitioner and everyone's always comparing us. It's... yeah, it's a thing."
+        else:
+            return "Family's good. I talk to them pretty regularly."
+
+
+def get_mode_based_response(name, mode, state, persona):
+    """Generate generic response based on current emotional mode."""
+    resilience_hooks = persona.get("resilience_hooks", [])
+    scripts = persona.get("scripts", {})
+    
+    if mode == "decompensating":
+        return scripts.get("crisis", "I need to step away. This is too much right now.")
+    
+    if mode == "triggered":
+        return scripts.get("resistance", "I'm not really in the mood to talk about this.")
+    
+    if mode == "guarded":
+        return scripts.get("deflection", "It's not that deep. I'm just tired.")
+    
+    if mode == "trusting" and resilience_hooks:
+        return f"You know what? {resilience_hooks[0]}"
+    
+    if mode == "recovering":
+        return "I'm feeling a bit better actually. Still working through things, but... yeah, better."
+    
+    # Baseline
+    return "I'm doing okay. What did you want to talk about?"
+
+
+def determine_memory_tag(prompt, mode, state):
+    """Generate an emotional memory tag based on the interaction."""
+    prompt_lower = prompt.lower()
+    
+    if mode == "trusting":
+        if any(word in prompt_lower for word in ["understand", "hear you", "makes sense"]):
+            return "felt validated"
+        return "felt safe to open up"
+    
+    if mode == "triggered":
+        if any(word in prompt_lower for word in ["should", "need to", "why don't"]):
+            return "felt criticized"
+        return "felt defensive"
+    
+    if mode == "guarded":
+        return "felt cautious"
+    
+    if mode == "decompensating":
+        return "felt overwhelmed"
+    
+    return "shared thoughts"

engine/utils.py

@@ -0,0 +1,3 @@
+def safe_log(context, error):
+    with open("driftline_errors.log", "a", encoding="utf-8") as f:
+        f.write(f"[{context}] {error}\n")