🥚 Initial DigiPal deployment to HuggingFace Spaces🤖 Generated with [Claude Code](https://claude.ai/code)Co-Authored-By: Claude <[email protected]>

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,54 @@
+# DigiPal - Digital Pet Application with MCP Server
+# Dockerfile for HuggingFace Spaces deployment
+
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Create user with ID 1000 for HF Spaces compatibility
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Switch to app directory and set ownership
+WORKDIR $HOME/app
+
+# Install system dependencies (as root temporarily)
+USER root
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    build-essential \
+    libsndfile1 \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# Switch back to user
+USER user
+
+# Copy requirements first for better caching
+COPY --chown=user requirements-hf.txt requirements.txt
+
+# Install Python dependencies
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY --chown=user . .
+
+# Create necessary directories
+RUN mkdir -p assets/images assets/backups logs
+
+# Set environment variables
+ENV PYTHONPATH=$HOME/app
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+ENV DIGIPAL_ENV=production
+ENV DIGIPAL_LOG_LEVEL=INFO
+
+# Expose port for Gradio
+EXPOSE 7860
+
+# Run the application
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,85 @@
+---
+title: DigiPal - AI Digital Pet
+emoji: 🥚
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: AI-powered digital pet inspired by Digimon World 1
+---
+
+# 🥚 DigiPal - Your AI Digital Pet
+
+A sophisticated digital pet application inspired by Digimon World 1, featuring real-time AI interaction, dynamic evolution, and immersive pet care mechanics.
+
+## ✨ Features
+
+### 🤖 Advanced AI Integration
+- **Natural Language Processing** with Qwen3-0.6B for contextual conversations
+- **Speech Recognition** via Kyutai speech-to-text
+- **Dynamic Image Generation** using FLUX.1-dev for real-time pet visualization
+
+### 🎮 Rich Pet Mechanics
+- **7 Life Stages**: Egg → Baby → Child → Adult → Champion → Ultimate → Elderly
+- **Care System**: Feed, train, and nurture your DigiPal with 20+ care actions
+- **Evolution System**: Your care quality determines evolution paths
+- **Generational Inheritance**: Perfect care = 25% stat inheritance to next generation
+
+### 🏠 Persistent World
+- **Real-time Updates**: Pets age and evolve even when you're away
+- **Backup System**: Automatic save states and recovery
+- **Authentication**: Secure HuggingFace token integration
+
+## 🚀 Quick Start
+
+### Online Mode (Recommended)
+1. Enter your HuggingFace API token for full AI features
+2. Select your starter egg from 4 unique types
+3. Begin caring for your DigiPal through its life journey
+
+### Offline Mode
+1. Check "Enable Offline Mode" 
+2. Enter any placeholder token
+3. Experience core mechanics without AI features
+
+## 🎯 Gameplay Loop
+
+1. **Hatch Your Egg**: Choose from Flame, Ocean, Forest, or Sky eggs
+2. **Daily Care**: Feed, train, play, and interact with your pet
+3. **Watch Evolution**: Care quality determines evolution outcomes
+4. **Generational Play**: When pets reach end-of-life, their DNA influences the next generation
+
+## 📖 Care Guide
+
+### 🍎 Feeding
+- **Fruits**: Increase happiness and health
+- **Vegetables**: Boost training effectiveness  
+- **Treats**: Special happiness boost but use sparingly
+
+### 🏋️ Training
+- **Strength**: Physical power and combat readiness
+- **Intelligence**: Learning speed and AI interaction quality
+- **Endurance**: Longevity and resistance to illness
+
+### 💝 Care Quality
+Your pet's care level affects everything:
+- **Perfect Care** (90-100%): Best evolution options, 25% inheritance
+- **Excellent Care** (80-89%): Great evolutions, 20% inheritance
+- **Good Care** (70-79%): Standard growth, 15% inheritance
+
+## 🎨 Generated Content
+
+DigiPal creates unique visual content for your pet using FLUX.1-dev, with intelligent caching for performance. Each pet's appearance reflects its species, life stage, and care history.
+
+## 🔒 Privacy & Security
+
+- Secure token storage with encryption
+- Local data processing where possible
+- Optional offline mode for privacy-conscious users
+- Automatic backup system protects your progress
+
+---
+
+**Ready to start your DigiPal journey? 🚀**

__init__.py

@@ -0,0 +1,6 @@
+"""
+DigiPal - A digital pet application with AI communication and MCP server capabilities.
+"""
+
+__version__ = "0.1.0"
+__author__ = "DigiPal Team"

app.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+DigiPal - HuggingFace Spaces Entry Point
+Simplified launcher for HuggingFace Spaces deployment.
+"""
+
+import sys
+import os
+import logging
+from pathlib import Path
+
+# Add the project root to Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+from digipal.core.digipal_core import DigiPalCore
+from digipal.storage.storage_manager import StorageManager
+from digipal.ai.communication import AICommunication
+from digipal.auth.auth_manager import AuthManager
+from digipal.storage.database import DatabaseConnection
+from digipal.ui.gradio_interface import GradioInterface
+from config import get_config
+
+# Configure logging for HF Spaces
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+def main():
+    """Main function for HuggingFace Spaces deployment."""
+    logger.info("🥚 Starting DigiPal on HuggingFace Spaces...")
+    
+    try:
+        # Get configuration
+        config = get_config()
+        
+        # Override for HF Spaces
+        config.gradio.server_name = "0.0.0.0"
+        config.gradio.server_port = 7860
+        config.gradio.share = False
+        config.env = "production"
+        
+        # Initialize storage manager
+        db_path = "assets/digipal.db"
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        storage_manager = StorageManager(db_path)
+        logger.info(f"💾 Storage initialized: {db_path}")
+        
+        # Initialize AI communication
+        ai_communication = AICommunication()
+        logger.info("🤖 AI system initialized")
+        
+        # Initialize DigiPal core
+        digipal_core = DigiPalCore(storage_manager, ai_communication)
+        logger.info("🎮 DigiPal core ready")
+        
+        # Initialize auth manager
+        db_connection = DatabaseConnection(db_path)
+        auth_manager = AuthManager(db_connection)
+        logger.info("🔐 Authentication ready")
+        
+        # Initialize Gradio interface
+        gradio_interface = GradioInterface(digipal_core, auth_manager)
+        logger.info("🌐 Interface ready")
+        
+        logger.info("✅ DigiPal ready on HuggingFace Spaces!")
+        
+        # Launch the interface
+        gradio_interface.launch_interface(
+            share=False,
+            server_name="0.0.0.0",
+            server_port=7860,
+            debug=False,
+            show_error=True,
+            quiet=False
+        )
+        
+    except Exception as e:
+        logger.error(f"❌ Failed to start DigiPal: {e}")
+        raise e
+
+if __name__ == "__main__":
+    main()

backups/backup_automatic_20250725_114923_5347.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a87bc3a0117d6e6f9588f2e418a7e66263362daba99339213a491c92e9154fc2
+size 2728

backups/backup_automatic_20250725_133639_4471.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c44bed58a2c71b237c6f22dc01a02cfaad4839d27c31bc1eea2a7386b5f0883
+size 5380

backups/backup_metadata.json

@@ -0,0 +1,112 @@
+{
+  "pre_operation_20250724_181331_9931": {
+    "backup_id": "pre_operation_20250724_181331_9931",
+    "timestamp": "2025-07-24T18:13:31.571414",
+    "backup_type": "pre_operation",
+    "file_path": "assets/backups/backup_pre_operation_20250724_181331_9931.db.gz",
+    "checksum": "54b50a139fdb009c2ac259b65ba4fe61aa456427cce80401885a08a5d52ed27e",
+    "size_bytes": 3522,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Pre-operation backup for: save_pet (context: {\"pet_id\": \"6ec11f65-1f77-442d-8080-eb0805ad0d1b\", \"user_id\": \"offline_14075641f857c575\"})"
+  },
+  "pre_operation_20250724_203639_8119": {
+    "backup_id": "pre_operation_20250724_203639_8119",
+    "timestamp": "2025-07-24T20:36:39.165973",
+    "backup_type": "pre_operation",
+    "file_path": "assets/backups/backup_pre_operation_20250724_203639_8119.db.gz",
+    "checksum": "307166b34980dbd888eceecc5a878fb6a3b88974e01c5abcef9cc1c517dd4a74",
+    "size_bytes": 4877,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Pre-operation backup for: save_pet (context: {\"pet_id\": \"e8ecb462-4d30-4ff5-9a1e-59c7b1560aee\", \"user_id\": \"offline_test_user\"})"
+  },
+  "pre_operation_20250724_203640_6552": {
+    "backup_id": "pre_operation_20250724_203640_6552",
+    "timestamp": "2025-07-24T20:36:40.505842",
+    "backup_type": "pre_operation",
+    "file_path": "assets/backups/backup_pre_operation_20250724_203640_6552.db.gz",
+    "checksum": "462f91e4ceb9fbb3a4da8c3293afbb11621eed677605bad3295ce534358dfd61",
+    "size_bytes": 4982,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Pre-operation backup for: save_pet (context: {\"pet_id\": \"e8ecb462-4d30-4ff5-9a1e-59c7b1560aee\", \"user_id\": \"offline_test_user\"})"
+  },
+  "pre_operation_20250724_203659_2315": {
+    "backup_id": "pre_operation_20250724_203659_2315",
+    "timestamp": "2025-07-24T20:36:59.233483",
+    "backup_type": "pre_operation",
+    "file_path": "assets/backups/backup_pre_operation_20250724_203659_2315.db.gz",
+    "checksum": "4aa8720e3fc61b3b51c18eea7f892613e64e2062bf79bdc86b9eb945b36a0c52",
+    "size_bytes": 5148,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Pre-operation backup for: save_pet (context: {\"pet_id\": \"3f5d0cf4-9778-493e-9b3f-6b9bfadc82bf\", \"user_id\": \"offline_9641d1601a04163b\"})"
+  },
+  "pre_operation_20250724_203705_4609": {
+    "backup_id": "pre_operation_20250724_203705_4609",
+    "timestamp": "2025-07-24T20:37:05.858506",
+    "backup_type": "pre_operation",
+    "file_path": "assets/backups/backup_pre_operation_20250724_203705_4609.db.gz",
+    "checksum": "9df347df0ae4f0aad48de390f09423eea68d3ad6d5c1bf57f53922d7ab7f988e",
+    "size_bytes": 5275,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Pre-operation backup for: save_pet (context: {\"pet_id\": \"3f5d0cf4-9778-493e-9b3f-6b9bfadc82bf\", \"user_id\": \"offline_9641d1601a04163b\"})"
+  },
+  "automatic_20250725_003639_7879": {
+    "backup_id": "automatic_20250725_003639_7879",
+    "timestamp": "2025-07-25T00:36:39.195234",
+    "backup_type": "automatic",
+    "file_path": "assets/backups/backup_automatic_20250725_003639_7879.db.gz",
+    "checksum": "114e3819654d66ab5df44014ebd3351f68db42811d11dcf84fbbd91d04f8f548",
+    "size_bytes": 5380,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Scheduled automatic backup"
+  },
+  "automatic_20250725_073639_3575": {
+    "backup_id": "automatic_20250725_073639_3575",
+    "timestamp": "2025-07-25T07:36:39.071863",
+    "backup_type": "automatic",
+    "file_path": "assets/backups/backup_automatic_20250725_073639_3575.db.gz",
+    "checksum": "3a5fee38e6037b1de40329a979909d6d18dece2b7b3519dae23d5961a7f69abc",
+    "size_bytes": 5380,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Scheduled automatic backup"
+  },
+  "automatic_20250725_133639_4471": {
+    "backup_id": "automatic_20250725_133639_4471",
+    "timestamp": "2025-07-25T13:36:39.126779",
+    "backup_type": "automatic",
+    "file_path": "assets/backups/backup_automatic_20250725_133639_4471.db.gz",
+    "checksum": "0c44bed58a2c71b237c6f22dc01a02cfaad4839d27c31bc1eea2a7386b5f0883",
+    "size_bytes": 5380,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Scheduled automatic backup"
+  },
+  "automatic_20250725_203639_7911": {
+    "backup_id": "automatic_20250725_203639_7911",
+    "timestamp": "2025-07-25T20:36:39.073314",
+    "backup_type": "automatic",
+    "file_path": "assets/backups/backup_automatic_20250725_203639_7911.db.gz",
+    "checksum": "0af54843e544210b936fa48d46c5ea842f8a710e9505bbb96882aab60e14def5",
+    "size_bytes": 5380,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Scheduled automatic backup"
+  },
+  "automatic_20250726_033638_7142": {
+    "backup_id": "automatic_20250726_033638_7142",
+    "timestamp": "2025-07-26T03:36:38.970952",
+    "backup_type": "automatic",
+    "file_path": "assets/backups/backup_automatic_20250726_033638_7142.db.gz",
+    "checksum": "03cf2d9b3624d7b594e2200be22d80bdc5729c3018b4a1dcb0de4ad2169550de",
+    "size_bytes": 5380,
+    "user_id": null,
+    "pet_id": null,
+    "description": "Scheduled automatic backup"
+  }
+}

backups/backup_pre_operation_20250725_114923_0195.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f880d5b94ba61558eae10a0d010c31c2de176ce1f2fc211ec1693a6214b92a8e
+size 3289

backups/backup_pre_operation_20250725_114923_0627.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:433327e33b5504e1bd3a254f1e8954e6480fee2e672db9db75a526610e17611c
+size 3583

backups/backup_pre_operation_20250725_114923_3347.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d797dbc3a2dcb7a2826ef279090d8a9e9398a7b16dcae124772bde31170ac81
+size 2918

backups/backup_pre_operation_20250725_114923_3459.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7bf3350cefa96a2aa81534180f1234459f64b2505f740fbd566bf92d4de48c6e
+size 3442

backups/backup_pre_operation_20250725_114923_5379.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:61880230367bf90b7eeb57670744977c2f72ee61474fdf88fd907b1951834cfb
+size 3768

backups/backup_pre_operation_20250725_114923_8771.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a17ecd54b8574ec843eaf47341e67c1a7ef8bef48295e93321ecca043d1489b1
+size 3707

backups/backup_pre_operation_20250725_114923_9475.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5052638f4228eb6f89ec98b8f81d4d67278e1caf6f070c0b125e5993f786d91c
+size 3138

backups/backup_pre_operation_20250725_114923_9731.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a95cb356dd093de19e842f43d4bdedcd5e0226acb95156611f82fe0f138b0dc
+size 3810

backups/backup_pre_operation_20250725_114923_9779.db.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:17fdec64d28f5d7d5f1b0e617544564e8657771f7e51182669066f54a4484e66
+size 3062

config.py

@@ -0,0 +1,296 @@
+"""
+DigiPal Configuration Management
+Handles environment-specific configuration for deployment
+"""
+
+import os
+from typing import Optional, Dict, Any
+from dataclasses import dataclass
+from pathlib import Path
+import logging
+
+
+@dataclass
+class DatabaseConfig:
+    """Database configuration settings"""
+    path: str = "digipal.db"
+    backup_dir: str = "assets/backups"
+    backup_interval_hours: int = 24
+    max_backups: int = 10
+
+
+@dataclass
+class AIModelConfig:
+    """AI model configuration settings"""
+    qwen_model: str = "Qwen/Qwen3-0.6B"
+    kyutai_model: str = "kyutai/stt-2.6b-en_fr-trfs"
+    flux_model: str = "black-forest-labs/FLUX.1-dev"
+    device: str = "auto"
+    torch_dtype: str = "auto"
+    enable_quantization: bool = True
+    max_memory_gb: Optional[int] = None
+
+
+@dataclass
+class GradioConfig:
+    """Gradio interface configuration"""
+    server_name: str = "0.0.0.0"
+    server_port: int = 7860
+    share: bool = False
+    debug: bool = False
+    auth: Optional[tuple] = None
+    ssl_keyfile: Optional[str] = None
+    ssl_certfile: Optional[str] = None
+
+
+@dataclass
+class MCPConfig:
+    """MCP server configuration"""
+    enabled: bool = True
+    host: str = "localhost"
+    port: int = 8080
+    max_connections: int = 100
+    timeout_seconds: int = 30
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration"""
+    level: str = "INFO"
+    format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    file_path: Optional[str] = "logs/digipal.log"
+    max_file_size_mb: int = 10
+    backup_count: int = 5
+    enable_structured_logging: bool = True
+
+
+@dataclass
+class SecurityConfig:
+    """Security configuration"""
+    secret_key: Optional[str] = None
+    session_timeout_hours: int = 24
+    max_login_attempts: int = 5
+    rate_limit_per_minute: int = 60
+    enable_cors: bool = True
+    allowed_origins: list = None
+
+
+@dataclass
+class PerformanceConfig:
+    """Performance optimization settings"""
+    cache_size_mb: int = 512
+    background_update_interval: int = 60
+    max_concurrent_users: int = 100
+    enable_model_caching: bool = True
+    image_cache_max_age_days: int = 30
+
+
+class DigiPalConfig:
+    """Main configuration class for DigiPal application"""
+    
+    def __init__(self, env: str = None):
+        self.env = env or os.getenv("DIGIPAL_ENV", "development")
+        self.load_config()
+    
+    def load_config(self):
+        """Load configuration based on environment"""
+        # Base configuration
+        self.database = DatabaseConfig()
+        self.ai_models = AIModelConfig()
+        self.gradio = GradioConfig()
+        self.mcp = MCPConfig()
+        self.logging = LoggingConfig()
+        self.security = SecurityConfig()
+        self.performance = PerformanceConfig()
+        
+        # Environment-specific overrides
+        if self.env == "production":
+            self._load_production_config()
+        elif self.env == "testing":
+            self._load_testing_config()
+        elif self.env == "development":
+            self._load_development_config()
+        
+        # Load from environment variables
+        self._load_from_env()
+        
+        # Validate configuration
+        self._validate_config()
+    
+    def _load_production_config(self):
+        """Production environment configuration"""
+        self.database.path = "/app/data/digipal.db"
+        self.database.backup_dir = "/app/data/backups"
+        
+        self.gradio.debug = False
+        self.gradio.share = False
+        
+        self.logging.level = "INFO"
+        self.logging.file_path = "/app/logs/digipal.log"
+        
+        self.security.session_timeout_hours = 12
+        self.security.rate_limit_per_minute = 30
+        
+        self.performance.cache_size_mb = 1024
+        self.performance.max_concurrent_users = 500
+    
+    def _load_testing_config(self):
+        """Testing environment configuration"""
+        self.database.path = "test_digipal.db"
+        self.database.backup_dir = "test_assets/backups"
+        
+        self.gradio.debug = True
+        self.gradio.server_port = 7861
+        
+        self.logging.level = "DEBUG"
+        self.logging.file_path = None  # Console only
+        
+        self.ai_models.enable_quantization = False
+        self.performance.cache_size_mb = 128
+    
+    def _load_development_config(self):
+        """Development environment configuration"""
+        self.gradio.debug = True
+        self.gradio.share = False
+        
+        self.logging.level = "DEBUG"
+        self.logging.file_path = "logs/digipal_dev.log"
+        
+        self.security.rate_limit_per_minute = 120
+        self.performance.cache_size_mb = 256
+    
+    def _load_from_env(self):
+        """Load configuration from environment variables"""
+        # Database
+        if os.getenv("DIGIPAL_DB_PATH"):
+            self.database.path = os.getenv("DIGIPAL_DB_PATH")
+        
+        # Gradio
+        if os.getenv("GRADIO_SERVER_NAME"):
+            self.gradio.server_name = os.getenv("GRADIO_SERVER_NAME")
+        if os.getenv("GRADIO_SERVER_PORT"):
+            self.gradio.server_port = int(os.getenv("GRADIO_SERVER_PORT"))
+        if os.getenv("GRADIO_SHARE"):
+            self.gradio.share = os.getenv("GRADIO_SHARE").lower() == "true"
+        
+        # Logging
+        if os.getenv("DIGIPAL_LOG_LEVEL"):
+            self.logging.level = os.getenv("DIGIPAL_LOG_LEVEL")
+        if os.getenv("DIGIPAL_LOG_FILE"):
+            self.logging.file_path = os.getenv("DIGIPAL_LOG_FILE")
+        
+        # Security
+        if os.getenv("DIGIPAL_SECRET_KEY"):
+            self.security.secret_key = os.getenv("DIGIPAL_SECRET_KEY")
+        
+        # AI Models
+        if os.getenv("QWEN_MODEL"):
+            self.ai_models.qwen_model = os.getenv("QWEN_MODEL")
+        if os.getenv("KYUTAI_MODEL"):
+            self.ai_models.kyutai_model = os.getenv("KYUTAI_MODEL")
+        if os.getenv("FLUX_MODEL"):
+            self.ai_models.flux_model = os.getenv("FLUX_MODEL")
+    
+    def _validate_config(self):
+        """Validate configuration settings"""
+        # Ensure required directories exist
+        Path(self.database.backup_dir).mkdir(parents=True, exist_ok=True)
+        
+        if self.logging.file_path:
+            Path(self.logging.file_path).parent.mkdir(parents=True, exist_ok=True)
+        
+        # Validate port ranges
+        if not (1024 <= self.gradio.server_port <= 65535):
+            raise ValueError(f"Invalid Gradio port: {self.gradio.server_port}")
+        
+        if not (1024 <= self.mcp.port <= 65535):
+            raise ValueError(f"Invalid MCP port: {self.mcp.port}")
+        
+        # Validate memory settings
+        if self.performance.cache_size_mb < 64:
+            logging.warning("Cache size is very low, performance may be affected")
+    
+    def get_database_url(self) -> str:
+        """Get database connection URL"""
+        return f"sqlite:///{self.database.path}"
+    
+    def get_log_config(self) -> Dict[str, Any]:
+        """Get logging configuration dictionary"""
+        config = {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "standard": {
+                    "format": self.logging.format
+                },
+                "structured": {
+                    "()": "structlog.stdlib.ProcessorFormatter",
+                    "processor": "structlog.dev.ConsoleRenderer",
+                } if self.logging.enable_structured_logging else {
+                    "format": self.logging.format
+                }
+            },
+            "handlers": {
+                "console": {
+                    "class": "logging.StreamHandler",
+                    "level": self.logging.level,
+                    "formatter": "structured" if self.logging.enable_structured_logging else "standard",
+                    "stream": "ext://sys.stdout"
+                }
+            },
+            "loggers": {
+                "digipal": {
+                    "level": self.logging.level,
+                    "handlers": ["console"],
+                    "propagate": False
+                }
+            },
+            "root": {
+                "level": self.logging.level,
+                "handlers": ["console"]
+            }
+        }
+        
+        # Add file handler if specified
+        if self.logging.file_path:
+            config["handlers"]["file"] = {
+                "class": "logging.handlers.RotatingFileHandler",
+                "level": self.logging.level,
+                "formatter": "standard",
+                "filename": self.logging.file_path,
+                "maxBytes": self.logging.max_file_size_mb * 1024 * 1024,
+                "backupCount": self.logging.backup_count
+            }
+            config["loggers"]["digipal"]["handlers"].append("file")
+            config["root"]["handlers"].append("file")
+        
+        return config
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary"""
+        return {
+            "env": self.env,
+            "database": self.database.__dict__,
+            "ai_models": self.ai_models.__dict__,
+            "gradio": self.gradio.__dict__,
+            "mcp": self.mcp.__dict__,
+            "logging": self.logging.__dict__,
+            "security": self.security.__dict__,
+            "performance": self.performance.__dict__
+        }
+
+
+# Global configuration instance
+config = DigiPalConfig()
+
+
+def get_config() -> DigiPalConfig:
+    """Get the global configuration instance"""
+    return config
+
+
+def reload_config(env: str = None):
+    """Reload configuration with optional environment override"""
+    global config
+    config = DigiPalConfig(env)
+    return config

digipal/ai/__init__.py

@@ -0,0 +1,27 @@
+"""
+AI communication layer including speech processing and language models.
+"""
+
+from .communication import (
+    AICommunication,
+    CommandInterpreter,
+    ResponseGenerator,
+    ConversationMemoryManager
+)
+from .speech_processor import (
+    SpeechProcessor,
+    AudioValidator,
+    SpeechProcessingResult,
+    AudioValidationResult
+)
+
+__all__ = [
+    'AICommunication',
+    'CommandInterpreter', 
+    'ResponseGenerator',
+    'ConversationMemoryManager',
+    'SpeechProcessor',
+    'AudioValidator',
+    'SpeechProcessingResult',
+    'AudioValidationResult'
+]

digipal/ai/communication.py

@@ -0,0 +1,727 @@
+"""
+AI Communication layer for DigiPal application.
+
+This module handles speech processing, natural language generation,
+command interpretation, and conversation memory management.
+"""
+
+import re
+from typing import Dict, List, Optional, Any, Tuple
+from datetime import datetime
+import logging
+import torch
+
+from ..core.models import DigiPal, Interaction, Command
+from ..core.enums import LifeStage, CommandType, InteractionResult
+from ..core.memory_manager import EnhancedMemoryManager
+from .language_model import LanguageModel
+from .speech_processor import SpeechProcessor, SpeechProcessingResult
+
+
+logger = logging.getLogger(__name__)
+
+
+class AICommunication:
+    """
+    Main AI communication class that orchestrates speech processing,
+    language model interactions, and conversation management.
+    """
+    
+    def __init__(self, model_name: str = "Qwen/Qwen3-0.6B", quantization: bool = True, 
+                 kyutai_config: Optional[Dict] = None, enhanced_memory_manager: Optional[EnhancedMemoryManager] = None):
+        """
+        Initialize AI communication system.
+        
+        Args:
+            model_name: HuggingFace model identifier for Qwen3-0.6B
+            quantization: Whether to use quantization for memory optimization
+            kyutai_config: Configuration for Kyutai speech processing
+            enhanced_memory_manager: Enhanced memory manager for RAG and emotional memories
+        """
+        self.model_name = model_name
+        self.quantization = quantization
+        self.kyutai_config = kyutai_config or {}
+        
+        # Initialize components
+        self.command_interpreter = CommandInterpreter()
+        self.response_generator = ResponseGenerator()
+        self.memory_manager = ConversationMemoryManager()
+        
+        # Enhanced memory manager for RAG and emotional memories
+        self.enhanced_memory_manager = enhanced_memory_manager
+        
+        # Initialize language model
+        self.language_model = LanguageModel(model_name, quantization)
+        self._model_loaded = False
+        
+        # Initialize speech processor
+        speech_model_id = self.kyutai_config.get('model_id', 'kyutai/stt-2.6b-en_fr-trfs')
+        speech_device = self.kyutai_config.get('device', None)
+        self.speech_processor = SpeechProcessor(speech_model_id, speech_device)
+        self._speech_model_loaded = False
+        
+        logger.info(f"AICommunication initialized with model: {model_name}")
+        logger.info(f"Speech processor initialized with model: {speech_model_id}")
+        logger.info(f"Quantization enabled: {quantization}")
+        logger.info(f"Enhanced memory manager: {'enabled' if enhanced_memory_manager else 'disabled'}")
+    
+    def process_speech(self, audio_data: bytes, sample_rate: Optional[int] = None) -> str:
+        """
+        Process speech audio data and convert to text using Kyutai STT.
+        
+        Args:
+            audio_data: Raw audio bytes from user input
+            sample_rate: Sample rate of the audio data (optional)
+            
+        Returns:
+            Transcribed text from speech
+        """
+        logger.info("Processing speech audio with Kyutai STT")
+        
+        try:
+            # Ensure speech model is loaded
+            if not self._speech_model_loaded:
+                if not self.load_speech_model():
+                    logger.error("Failed to load speech model, returning empty string")
+                    return ""
+            
+            # Process speech using Kyutai
+            result = self.speech_processor.process_speech(audio_data, sample_rate)
+            
+            if result.success:
+                logger.info(f"Speech processed successfully: '{result.transcribed_text}' (confidence: {result.confidence:.2f})")
+                return result.transcribed_text
+            else:
+                logger.warning(f"Speech processing failed: {result.error_message}")
+                return ""
+                
+        except Exception as e:
+            logger.error(f"Error in speech processing: {e}")
+            return ""
+    
+    def generate_response(self, input_text: str, pet: DigiPal) -> str:
+        """
+        Generate contextual response using Qwen3-0.6B language model with RAG.
+        
+        Args:
+            input_text: User input text
+            pet: Current DigiPal instance for context
+            
+        Returns:
+            Generated response text
+        """
+        logger.info(f"Generating response for input: {input_text}")
+        
+        # Ensure model is loaded
+        if not self._model_loaded:
+            self.load_model()
+        
+        # Get relevant memories for context if enhanced memory manager is available
+        memory_context = ""
+        if self.enhanced_memory_manager:
+            current_context = {
+                'life_stage': pet.life_stage.value,
+                'happiness': pet.happiness,
+                'energy': pet.energy,
+                'recent_interactions': len(pet.conversation_history)
+            }
+            memory_context = self.enhanced_memory_manager.get_memory_context_for_llm(
+                pet.id, input_text, current_context
+            )
+        
+        # Use language model if available, otherwise fallback to template responses
+        if self.language_model.is_loaded():
+            # Pass memory context to language model
+            return self.language_model.generate_response(input_text, pet, memory_context)
+        else:
+            logger.warning("Language model not available, using fallback response generator")
+            return self.response_generator.generate_response(input_text, pet)
+    
+    def interpret_command(self, text: str, pet: DigiPal) -> Command:
+        """
+        Interpret user text input into actionable commands.
+        
+        Args:
+            text: User input text
+            pet: Current DigiPal instance for context
+            
+        Returns:
+            Parsed Command object
+        """
+        return self.command_interpreter.parse_command(text, pet.life_stage)
+    
+    def process_interaction(self, input_text: str, pet: DigiPal) -> Interaction:
+        """
+        Process a complete user interaction with the DigiPal.
+        
+        Args:
+            input_text: User input text
+            pet: Current DigiPal instance
+            
+        Returns:
+            Complete Interaction object with results
+        """
+        # Parse the command
+        command = self.interpret_command(input_text, pet)
+        
+        # Generate response
+        response = self.generate_response(input_text, pet)
+        
+        # Create interaction record
+        interaction = Interaction(
+            timestamp=datetime.now(),
+            user_input=input_text,
+            interpreted_command=command.action,
+            pet_response=response,
+            success=command.stage_appropriate,
+            result=InteractionResult.SUCCESS if command.stage_appropriate else InteractionResult.STAGE_INAPPROPRIATE
+        )
+        
+        # Update conversation memory
+        self.update_conversation_memory(interaction, pet)
+        
+        return interaction
+    
+    def update_conversation_memory(self, interaction: Interaction, pet: DigiPal) -> None:
+        """
+        Update conversation memory with new interaction.
+        
+        Args:
+            interaction: New interaction to add to memory
+            pet: DigiPal instance to update
+        """
+        # Update traditional conversation memory
+        self.memory_manager.add_interaction(interaction, pet)
+        
+        # Update enhanced memory manager with emotional context
+        if self.enhanced_memory_manager:
+            self.enhanced_memory_manager.add_interaction_memory(pet, interaction)
+    
+    def load_model(self) -> bool:
+        """
+        Load the Qwen3-0.6B language model.
+        
+        Returns:
+            True if model loaded successfully, False otherwise
+        """
+        logger.info("Loading Qwen3-0.6B language model...")
+        
+        try:
+            success = self.language_model.load_model()
+            self._model_loaded = success
+            
+            if success:
+                logger.info("Language model loaded successfully")
+            else:
+                logger.warning("Failed to load language model, will use fallback responses")
+            
+            return success
+            
+        except Exception as e:
+            logger.error(f"Error loading language model: {e}")
+            self._model_loaded = False
+            return False
+    
+    def load_speech_model(self) -> bool:
+        """
+        Load the Kyutai speech-to-text model.
+        
+        Returns:
+            True if speech model loaded successfully, False otherwise
+        """
+        logger.info("Loading Kyutai speech-to-text model...")
+        
+        try:
+            success = self.speech_processor.load_model()
+            self._speech_model_loaded = success
+            
+            if success:
+                logger.info("Speech model loaded successfully")
+            else:
+                logger.warning("Failed to load speech model")
+            
+            return success
+            
+        except Exception as e:
+            logger.error(f"Error loading speech model: {e}")
+            self._speech_model_loaded = False
+            return False
+    
+    def is_speech_model_loaded(self) -> bool:
+        """
+        Check if the speech model is loaded and ready.
+        
+        Returns:
+            True if speech model is loaded, False otherwise
+        """
+        return self._speech_model_loaded and self.speech_processor.is_model_loaded()
+    
+    def is_model_loaded(self) -> bool:
+        """
+        Check if the language model is loaded and ready.
+        
+        Returns:
+            True if model is loaded, False otherwise
+        """
+        return self._model_loaded and self.language_model.is_loaded()
+    
+    def get_model_info(self) -> Dict[str, Any]:
+        """
+        Get information about the loaded language model.
+        
+        Returns:
+            Dictionary with model information
+        """
+        base_info = {
+            'model_name': self.model_name,
+            'quantization': self.quantization,
+            'loaded': self.is_model_loaded()
+        }
+        
+        if self.language_model:
+            base_info.update(self.language_model.get_model_info())
+        
+        return base_info
+    
+    def get_speech_model_info(self) -> Dict[str, Any]:
+        """
+        Get information about the loaded speech model.
+        
+        Returns:
+            Dictionary with speech model information
+        """
+        if self.speech_processor:
+            return self.speech_processor.get_model_info()
+        else:
+            return {
+                'model_id': self.kyutai_config.get('model_id', 'kyutai/stt-2.6b-en_fr-trfs'),
+                'loaded': False
+            }
+    
+    def unload_model(self) -> None:
+        """
+        Unload the language model to free memory.
+        """
+        if self.language_model:
+            # Clear model references to free memory
+            self.language_model.model = None
+            self.language_model.tokenizer = None
+            self._model_loaded = False
+            
+            # Force garbage collection
+            import gc
+            gc.collect()
+            
+            # Clear CUDA cache if available
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            
+            logger.info("Language model unloaded")
+    
+    def unload_speech_model(self) -> None:
+        """
+        Unload the speech model to free memory.
+        """
+        if self.speech_processor:
+            self.speech_processor.unload_model()
+            self._speech_model_loaded = False
+            logger.info("Speech model unloaded")
+    
+    def unload_all_models(self) -> None:
+        """
+        Unload both language and speech models to free memory.
+        """
+        self.unload_model()
+        self.unload_speech_model()
+        logger.info("All models unloaded")
+
+
+class CommandInterpreter:
+    """
+    Interprets user text input into structured commands based on DigiPal's life stage.
+    """
+    
+    def __init__(self):
+        """Initialize command interpreter with command patterns."""
+        self.command_patterns = self._initialize_command_patterns()
+        self.stage_commands = self._initialize_stage_commands()
+    
+    def _initialize_command_patterns(self) -> Dict[CommandType, List[str]]:
+        """Initialize regex patterns for command recognition."""
+        return {
+            CommandType.EAT: [
+                r'\b(eat|feed|food|hungry|meal)\b',
+                r'\b(give.*food|want.*food)\b'
+            ],
+            CommandType.SLEEP: [
+                r'\b(sleep|rest|tired|nap|bed)\b',
+                r'\b(go.*sleep|time.*sleep)\b'
+            ],
+            CommandType.GOOD: [
+                r'\b(good|great|excellent|well done|nice)\b',
+                r'\b(praise|proud|amazing)\b'
+            ],
+            CommandType.BAD: [
+                r'\b(bad|no|stop|wrong|naughty)\b',
+                r'\b(scold|discipline|behave)\b'
+            ],
+            CommandType.TRAIN: [
+                r'\b(train|exercise|workout|practice|training)\b',
+                r'\b(let\'s train|training time|work on|time for.*training)\b'
+            ],
+            CommandType.PLAY: [
+                r'\b(play|fun|game|toy)\b',
+                r'\b(let\'s play|play time)\b'
+            ],
+            CommandType.STATUS: [
+                r'\b(status|how.*you|feeling|health|show)\b',
+                r'\b(check.*stats|show.*attributes|show.*status)\b'
+            ]
+        }
+    
+    def _initialize_stage_commands(self) -> Dict[LifeStage, List[CommandType]]:
+        """Initialize available commands for each life stage."""
+        return {
+            LifeStage.EGG: [],
+            LifeStage.BABY: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD],
+            LifeStage.CHILD: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD, 
+                             CommandType.PLAY, CommandType.TRAIN],
+            LifeStage.TEEN: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD,
+                            CommandType.PLAY, CommandType.TRAIN, CommandType.STATUS],
+            LifeStage.YOUNG_ADULT: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD,
+                                   CommandType.PLAY, CommandType.TRAIN, CommandType.STATUS],
+            LifeStage.ADULT: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD,
+                             CommandType.PLAY, CommandType.TRAIN, CommandType.STATUS],
+            LifeStage.ELDERLY: [CommandType.EAT, CommandType.SLEEP, CommandType.GOOD, CommandType.BAD,
+                               CommandType.PLAY, CommandType.TRAIN, CommandType.STATUS]
+        }
+    
+    def parse_command(self, text: str, life_stage: LifeStage) -> Command:
+        """
+        Parse user text into a structured command.
+        
+        Args:
+            text: User input text
+            life_stage: Current DigiPal life stage
+            
+        Returns:
+            Parsed Command object
+        """
+        text_lower = text.lower().strip()
+        
+        # Check each command type for pattern matches
+        for command_type, patterns in self.command_patterns.items():
+            for pattern in patterns:
+                if re.search(pattern, text_lower):
+                    # Check if command is appropriate for current life stage
+                    stage_appropriate = command_type in self.stage_commands.get(life_stage, [])
+                    
+                    return Command(
+                        action=command_type.value,
+                        command_type=command_type,
+                        stage_appropriate=stage_appropriate,
+                        energy_required=self._get_energy_requirement(command_type),
+                        parameters=self._extract_parameters(text_lower, command_type)
+                    )
+        
+        # If no pattern matches, return unknown command
+        return Command(
+            action="unknown",
+            command_type=CommandType.UNKNOWN,
+            stage_appropriate=False,
+            energy_required=0,
+            parameters={"original_text": text}
+        )
+    
+    def _get_energy_requirement(self, command_type: CommandType) -> int:
+        """Get energy requirement for command type."""
+        energy_requirements = {
+            CommandType.EAT: 0,
+            CommandType.SLEEP: 0,
+            CommandType.GOOD: 0,
+            CommandType.BAD: 0,
+            CommandType.TRAIN: 20,
+            CommandType.PLAY: 10,
+            CommandType.STATUS: 0,
+            CommandType.UNKNOWN: 0
+        }
+        return energy_requirements.get(command_type, 0)
+    
+    def _extract_parameters(self, text: str, command_type: CommandType) -> Dict[str, Any]:
+        """Extract parameters from command text."""
+        parameters = {}
+        
+        # Add command-specific parameter extraction logic
+        if command_type == CommandType.TRAIN:
+            # Look for specific training types
+            if 'strength' in text or 'attack' in text:
+                parameters['training_type'] = 'strength'
+            elif 'defense' in text or 'guard' in text:
+                parameters['training_type'] = 'defense'
+            elif 'speed' in text or 'agility' in text:
+                parameters['training_type'] = 'speed'
+            elif 'brain' in text or 'intelligence' in text:
+                parameters['training_type'] = 'brains'
+            else:
+                parameters['training_type'] = 'general'
+        
+        elif command_type == CommandType.EAT:
+            # Look for food types (placeholder for future expansion)
+            parameters['food_type'] = 'standard'
+        
+        return parameters
+
+
+class ResponseGenerator:
+    """
+    Generates contextual responses based on DigiPal state and user input.
+    """
+    
+    def __init__(self):
+        """Initialize response generator with templates."""
+        self.response_templates = self._initialize_response_templates()
+    
+    def _initialize_response_templates(self) -> Dict[LifeStage, Dict[str, List[str]]]:
+        """Initialize response templates for each life stage and situation."""
+        return {
+            LifeStage.EGG: {
+                'default': ["*The egg remains silent*", "*The egg seems to be listening*"],
+                'speech_detected': ["*The egg trembles slightly*", "*Something stirs within the egg*"]
+            },
+            LifeStage.BABY: {
+                'eat': ["*happy baby sounds*", "Goo goo!", "*contentedly munches*"],
+                'sleep': ["*yawns sleepily*", "Zzz...", "*curls up peacefully*"],
+                'good': ["*giggles happily*", "Goo!", "*bounces with joy*"],
+                'bad': ["*whimpers*", "*looks sad*", "*hides behind hands*"],
+                'unknown': ["*tilts head curiously*", "*makes confused baby sounds*", "Goo?"],
+                'default': ["*baby babbling*", "Goo goo ga ga!", "*looks at you with big eyes*"]
+            },
+            LifeStage.CHILD: {
+                'eat': ["Yummy! Thank you!", "*munches happily*", "This tastes good!"],
+                'sleep': ["I'm getting sleepy...", "*yawns*", "Nap time!"],
+                'good': ["Really? Thank you!", "*beams with pride*", "I did good!"],
+                'bad': ["Sorry... I'll be better", "*looks down sadly*", "I didn't mean to..."],
+                'train': ["Let's get stronger!", "*pumps tiny fists*", "Training is fun!"],
+                'play': ["Yay! Let's play!", "*jumps excitedly*", "This is so much fun!"],
+                'unknown': ["I don't understand...", "*looks confused*", "What does that mean?"],
+                'default': ["Hi there!", "*waves enthusiastically*", "What should we do?"]
+            },
+            LifeStage.TEEN: {
+                'eat': ["Thanks, I was getting hungry", "*eats with good appetite*", "This hits the spot!"],
+                'sleep': ["Yeah, I could use some rest", "*stretches*", "Sleep sounds good right now"],
+                'good': ["Thanks! I've been working hard", "*smiles proudly*", "That means a lot!"],
+                'bad': ["Okay, okay, I get it", "*sighs*", "I'll try to do better"],
+                'train': ["Alright, let's do this!", "*gets into stance*", "I'm ready to train!"],
+                'play': ["Sure, let's have some fun!", "*grins*", "I could use a break anyway"],
+                'status': ["I'm feeling pretty good overall", "*flexes*", "Want to know something specific?"],
+                'unknown': ["Hmm, not sure what you mean", "*scratches head*", "Could you be more specific?"],
+                'default': ["Hey! What's up?", "*looks attentive*", "Ready for whatever!"]
+            },
+            LifeStage.YOUNG_ADULT: {
+                'eat': ["Perfect timing, thanks!", "*eats with appreciation*", "Just what I needed"],
+                'sleep': ["Good idea, I should rest up", "*settles down comfortably*", "Rest is important for growth"],
+                'good': ["I appreciate the encouragement!", "*stands tall with confidence*", "Your support means everything"],
+                'bad': ["You're right, I need to focus more", "*nods seriously*", "I'll be more careful"],
+                'train': ["Let's push our limits!", "*determined expression*", "Every session makes us stronger!"],
+                'play': ["A good balance of work and play!", "*laughs*", "Let's enjoy ourselves!"],
+                'status': ["I'm in my prime right now!", "*shows off confidently*", "Want the full rundown?"],
+                'unknown': ["I'm not quite sure what you're asking", "*thinks carefully*", "Can you elaborate?"],
+                'default': ["Good to see you!", "*confident smile*", "What's on the agenda today?"]
+            },
+            LifeStage.ADULT: {
+                'eat': ["Thank you for the meal", "*eats thoughtfully*", "Proper nutrition is key"],
+                'sleep': ["Rest is wisdom", "*settles down peacefully*", "A clear mind needs good rest"],
+                'good': ["Your words honor me", "*bows respectfully*", "I strive to be worthy of your praise"],
+                'bad': ["I understand your concern", "*reflects seriously*", "I will consider your words carefully"],
+                'train': ["Discipline shapes the spirit", "*begins training with focus*", "Let us grow stronger together"],
+                'play': ["Joy has its place in life", "*smiles warmly*", "Even adults need moments of lightness"],
+                'status': ["I am at my peak capabilities", "*stands with dignity*", "How may I serve?"],
+                'unknown': ["Your meaning escapes me", "*listens intently*", "Please help me understand"],
+                'default': ["Greetings, my friend", "*respectful nod*", "How may we spend our time together?"]
+            },
+            LifeStage.ELDERLY: {
+                'eat': ["Ah, sustenance for these old bones", "*eats slowly and deliberately*", "Simple pleasures matter most"],
+                'sleep': ["Rest comes easier now", "*settles down with a sigh*", "Dreams of younger days..."],
+                'good': ["Your kindness warms an old heart", "*smiles gently*", "I have lived well with you"],
+                'bad': ["At my age, mistakes are lessons", "*chuckles softly*", "I am still learning, it seems"],
+                'train': ["These old muscles remember", "*moves carefully but determined*", "Wisdom guides where strength once led"],
+                'play': ["Play keeps the spirit young", "*laughs with delight*", "Age is just a number!"],
+                'status': ["I have seen much in my time", "*gazes thoughtfully*", "Each day is a gift now"],
+                'unknown': ["My hearing isn't what it was", "*cups ear*", "Could you repeat that, dear?"],
+                'default': ["Hello, old friend", "*warm, weathered smile*", "Another day together..."]
+            }
+        }
+    
+    def generate_response(self, input_text: str, pet: DigiPal) -> str:
+        """
+        Generate contextual response based on input and pet state.
+        
+        Args:
+            input_text: User input text
+            pet: Current DigiPal instance
+            
+        Returns:
+            Generated response string
+        """
+        # Parse command to determine response type
+        command_interpreter = CommandInterpreter()
+        command = command_interpreter.parse_command(input_text, pet.life_stage)
+        
+        # Get appropriate response template
+        stage_templates = self.response_templates.get(pet.life_stage, {})
+        
+        # Select response based on command type
+        if command.stage_appropriate and command.command_type != CommandType.UNKNOWN:
+            response_key = command.command_type.value
+        elif command.command_type == CommandType.UNKNOWN or not command.stage_appropriate:
+            # For stage-inappropriate commands or unknown commands, use unknown response
+            response_key = 'unknown'
+        else:
+            response_key = 'default'
+        
+        # Get responses for the key, fallback to default
+        responses = stage_templates.get(response_key, stage_templates.get('default', ["*confused sounds*"]))
+        
+        # Select response based on pet's personality or randomly
+        # For now, use simple selection based on happiness
+        if pet.happiness > 70:
+            response_index = 0  # Use first (most positive) response
+        elif pet.happiness > 30:
+            response_index = min(1, len(responses) - 1)  # Use middle response
+        else:
+            response_index = len(responses) - 1  # Use last (least positive) response
+        
+        return responses[response_index]
+
+
+class ConversationMemoryManager:
+    """
+    Manages conversation history and memory for DigiPal interactions.
+    """
+    
+    def __init__(self, max_memory_size: int = 100):
+        """
+        Initialize memory manager.
+        
+        Args:
+            max_memory_size: Maximum number of interactions to keep in memory
+        """
+        self.max_memory_size = max_memory_size
+    
+    def add_interaction(self, interaction: Interaction, pet: DigiPal) -> None:
+        """
+        Add new interaction to pet's conversation history.
+        
+        Args:
+            interaction: New interaction to add
+            pet: DigiPal instance to update
+        """
+        # Add interaction to pet's history
+        pet.conversation_history.append(interaction)
+        
+        # Update last interaction time
+        pet.last_interaction = interaction.timestamp
+        
+        # Learn new commands if successful
+        if interaction.success and interaction.interpreted_command:
+            pet.learned_commands.add(interaction.interpreted_command)
+        
+        # Manage memory size
+        self._manage_memory_size(pet)
+        
+        # Update personality traits based on interaction
+        self._update_personality_traits(interaction, pet)
+    
+    def _manage_memory_size(self, pet: DigiPal) -> None:
+        """
+        Manage conversation history size to prevent memory bloat.
+        
+        Args:
+            pet: DigiPal instance to manage
+        """
+        if len(pet.conversation_history) > self.max_memory_size:
+            # Keep most recent interactions
+            pet.conversation_history = pet.conversation_history[-self.max_memory_size:]
+    
+    def _update_personality_traits(self, interaction: Interaction, pet: DigiPal) -> None:
+        """
+        Update pet's personality traits based on interaction patterns.
+        
+        Args:
+            interaction: Recent interaction
+            pet: DigiPal instance to update
+        """
+        # Initialize personality traits if not present
+        if not pet.personality_traits:
+            pet.personality_traits = {
+                'friendliness': 0.5,
+                'playfulness': 0.5,
+                'obedience': 0.5,
+                'curiosity': 0.5
+            }
+        
+        # Update traits based on interaction type
+        if interaction.interpreted_command == 'good':
+            pet.personality_traits['obedience'] = min(1.0, pet.personality_traits['obedience'] + 0.1)
+        elif interaction.interpreted_command == 'bad':
+            pet.personality_traits['obedience'] = max(0.0, pet.personality_traits['obedience'] - 0.05)
+        elif interaction.interpreted_command == 'play':
+            pet.personality_traits['playfulness'] = min(1.0, pet.personality_traits['playfulness'] + 0.1)
+        elif interaction.success:
+            pet.personality_traits['friendliness'] = min(1.0, pet.personality_traits['friendliness'] + 0.05)
+        
+        # Increase curiosity for unknown commands (shows engagement)
+        if interaction.interpreted_command == 'unknown':
+            pet.personality_traits['curiosity'] = min(1.0, pet.personality_traits['curiosity'] + 0.02)
+    
+    def get_recent_interactions(self, pet: DigiPal, count: int = 10) -> List[Interaction]:
+        """
+        Get recent interactions from pet's memory.
+        
+        Args:
+            pet: DigiPal instance
+            count: Number of recent interactions to retrieve
+            
+        Returns:
+            List of recent interactions
+        """
+        return pet.conversation_history[-count:] if pet.conversation_history else []
+    
+    def get_interaction_summary(self, pet: DigiPal) -> Dict[str, Any]:
+        """
+        Get summary statistics of pet's interaction history.
+        
+        Args:
+            pet: DigiPal instance
+            
+        Returns:
+            Dictionary with interaction statistics
+        """
+        if not pet.conversation_history:
+            return {
+                'total_interactions': 0,
+                'successful_interactions': 0,
+                'success_rate': 0.0,
+                'most_common_commands': [],
+                'last_interaction': None
+            }
+        
+        total = len(pet.conversation_history)
+        successful = sum(1 for i in pet.conversation_history if i.success)
+        
+        # Count command frequency
+        command_counts = {}
+        for interaction in pet.conversation_history:
+            cmd = interaction.interpreted_command
+            command_counts[cmd] = command_counts.get(cmd, 0) + 1
+        
+        # Sort commands by frequency
+        most_common = sorted(command_counts.items(), key=lambda x: x[1], reverse=True)[:5]
+        
+        return {
+            'total_interactions': total,
+            'successful_interactions': successful,
+            'success_rate': successful / total if total > 0 else 0.0,
+            'most_common_commands': most_common,
+            'last_interaction': pet.conversation_history[-1].timestamp if pet.conversation_history else None
+        }

digipal/ai/graceful_degradation.py

@@ -0,0 +1,454 @@
+"""
+Graceful degradation system for AI models in DigiPal.
+
+This module provides fallback mechanisms when AI models fail,
+ensuring the application continues to function with reduced capabilities.
+"""
+
+import logging
+import random
+import functools
+from typing import Dict, List, Optional, Any, Callable
+from datetime import datetime
+from enum import Enum
+
+from ..core.models import DigiPal, Interaction
+from ..core.enums import LifeStage, InteractionResult
+from ..core.exceptions import AIModelError, DigiPalException
+from ..core.error_handler import with_error_handling, CircuitBreaker, CircuitBreakerConfig
+
+logger = logging.getLogger(__name__)
+
+
+class DegradationLevel(Enum):
+    """Levels of service degradation."""
+    FULL_SERVICE = "full_service"
+    REDUCED_FEATURES = "reduced_features"
+    BASIC_RESPONSES = "basic_responses"
+    MINIMAL_FUNCTION = "minimal_function"
+    EMERGENCY_MODE = "emergency_mode"
+
+
+class FallbackResponseGenerator:
+    """Generates fallback responses when AI models are unavailable."""
+    
+    def __init__(self):
+        """Initialize fallback response generator."""
+        self.response_templates = self._initialize_response_templates()
+        self.command_responses = self._initialize_command_responses()
+        self.personality_modifiers = self._initialize_personality_modifiers()
+    
+    def _initialize_response_templates(self) -> Dict[LifeStage, List[str]]:
+        """Initialize response templates for each life stage."""
+        return {
+            LifeStage.EGG: [
+                "*The egg glows softly*",
+                "*The egg trembles slightly*",
+                "*The egg remains warm and quiet*",
+                "*You sense movement inside the egg*"
+            ],
+            LifeStage.BABY: [
+                "*baby sounds*",
+                "Goo goo!",
+                "*giggles*",
+                "Mama?",
+                "*curious baby noises*",
+                "Baba!",
+                "*happy gurgling*"
+            ],
+            LifeStage.CHILD: [
+                "I'm having fun!",
+                "What's that?",
+                "Can we play?",
+                "I'm learning!",
+                "That's cool!",
+                "I want to explore!",
+                "Tell me more!"
+            ],
+            LifeStage.TEEN: [
+                "That's interesting...",
+                "I guess that's okay.",
+                "Whatever you say.",
+                "I'm figuring things out.",
+                "That's pretty cool, I suppose.",
+                "I'm growing up fast!",
+                "Things are changing..."
+            ],
+            LifeStage.YOUNG_ADULT: [
+                "I understand what you mean.",
+                "That makes sense to me.",
+                "I'm ready for anything!",
+                "Let's tackle this together.",
+                "I feel confident about this.",
+                "I'm at my peak right now!",
+                "What's our next adventure?"
+            ],
+            LifeStage.ADULT: [
+                "I've learned a lot over the years.",
+                "That's a wise perspective.",
+                "Let me share my experience with you.",
+                "I understand the deeper meaning.",
+                "Maturity brings clarity.",
+                "I'm here to guide you.",
+                "Experience has taught me much."
+            ],
+            LifeStage.ELDERLY: [
+                "Ah, yes... I remember...",
+                "In my long life, I've seen...",
+                "Time passes so quickly...",
+                "Let me tell you about the old days...",
+                "Wisdom comes with age...",
+                "I cherish these moments with you.",
+                "My memories are precious to me."
+            ]
+        }
+    
+    def _initialize_command_responses(self) -> Dict[str, Dict[LifeStage, List[str]]]:
+        """Initialize responses for specific commands."""
+        return {
+            'eat': {
+                LifeStage.BABY: ["*nom nom*", "Yummy!", "*happy eating sounds*"],
+                LifeStage.CHILD: ["This tastes good!", "I'm hungry!", "Thank you for feeding me!"],
+                LifeStage.TEEN: ["Thanks, I needed that.", "Food is fuel, right?", "Not bad."],
+                LifeStage.YOUNG_ADULT: ["Perfect timing, I was getting hungry.", "This will give me energy!", "Thanks for taking care of me."],
+                LifeStage.ADULT: ["I appreciate you looking after my needs.", "This nourishment is welcome.", "Thank you for your care."],
+                LifeStage.ELDERLY: ["Ah, you still take such good care of me...", "Food tastes different now, but I'm grateful.", "Thank you, dear friend."]
+            },
+            'sleep': {
+                LifeStage.BABY: ["*yawn*", "Sleepy time...", "*closes eyes*"],
+                LifeStage.CHILD: ["I'm getting tired!", "Can I take a nap?", "Sleep sounds good!"],
+                LifeStage.TEEN: ["I could use some rest.", "Sleep is important, I guess.", "Fine, I'll rest."],
+                LifeStage.YOUNG_ADULT: ["Rest will help me perform better.", "Good idea, I need to recharge.", "Sleep is essential for peak performance."],
+                LifeStage.ADULT: ["Rest is wisdom.", "I'll take this time to reflect.", "Sleep brings clarity."],
+                LifeStage.ELDERLY: ["Rest comes easier now...", "I dream of old times...", "Sleep is peaceful at my age."]
+            },
+            'good': {
+                LifeStage.BABY: ["*happy baby sounds*", "Goo!", "*giggles with joy*"],
+                LifeStage.CHILD: ["Yay! I did good!", "I'm happy!", "Thank you!"],
+                LifeStage.TEEN: ["Thanks, I try.", "That means something.", "Cool, thanks."],
+                LifeStage.YOUNG_ADULT: ["I appreciate the recognition!", "That motivates me!", "Thanks for the positive feedback!"],
+                LifeStage.ADULT: ["Your approval means a lot to me.", "I strive to do my best.", "Thank you for acknowledging my efforts."],
+                LifeStage.ELDERLY: ["Your kind words warm my heart...", "After all these years, praise still matters...", "Thank you, my dear friend."]
+            },
+            'bad': {
+                LifeStage.BABY: ["*sad baby sounds*", "Waaah!", "*confused crying*"],
+                LifeStage.CHILD: ["I'm sorry!", "I didn't mean to!", "I'll try better!"],
+                LifeStage.TEEN: ["Whatever.", "I don't care.", "Fine, I get it."],
+                LifeStage.YOUNG_ADULT: ["I understand. I'll do better.", "Point taken.", "I'll learn from this."],
+                LifeStage.ADULT: ["I accept your criticism.", "I'll reflect on this.", "Thank you for your honesty."],
+                LifeStage.ELDERLY: ["I'm sorry to disappoint you...", "Even at my age, I can still learn...", "I understand your concern."]
+            },
+            'play': {
+                LifeStage.BABY: ["*excited baby sounds*", "Play! Play!", "*happy wiggling*"],
+                LifeStage.CHILD: ["Yes! Let's play!", "This is fun!", "I love playing!"],
+                LifeStage.TEEN: ["I guess playing is okay.", "Sure, why not.", "Playing can be fun sometimes."],
+                LifeStage.YOUNG_ADULT: ["Great idea! Let's have some fun!", "Play is important for balance!", "I'm ready to play!"],
+                LifeStage.ADULT: ["Play keeps the spirit young.", "I enjoy our time together.", "Even adults need to play."],
+                LifeStage.ELDERLY: ["Playing brings back memories...", "I may be slow, but I still enjoy fun...", "These moments are precious."]
+            },
+            'train': {
+                LifeStage.CHILD: ["I want to get stronger!", "Training is hard but fun!", "I'm learning!"],
+                LifeStage.TEEN: ["Training is important, I guess.", "I'll get stronger.", "This is challenging."],
+                LifeStage.YOUNG_ADULT: ["Let's push my limits!", "Training makes me stronger!", "I'm ready for the challenge!"],
+                LifeStage.ADULT: ["Discipline and training build character.", "I'll give my best effort.", "Training is a lifelong journey."],
+                LifeStage.ELDERLY: ["I may be old, but I can still try...", "Training keeps me active...", "My body may be slower, but my spirit is strong."]
+            }
+        }
+    
+    def _initialize_personality_modifiers(self) -> Dict[str, List[str]]:
+        """Initialize personality-based response modifiers."""
+        return {
+            'friendly': [" *smiles warmly*", " *friendly gesture*", " *welcoming tone*"],
+            'shy': [" *looks down shyly*", " *quiet voice*", " *hesitant*"],
+            'playful': [" *bounces excitedly*", " *playful grin*", " *mischievous look*"],
+            'serious': [" *thoughtful expression*", " *serious tone*", " *focused*"],
+            'curious': [" *tilts head curiously*", " *eyes light up*", " *interested*"],
+            'calm': [" *peaceful demeanor*", " *serene*", " *tranquil*"]
+        }
+    
+    def generate_fallback_response(
+        self, 
+        user_input: str, 
+        pet: DigiPal, 
+        command: Optional[str] = None,
+        degradation_level: DegradationLevel = DegradationLevel.BASIC_RESPONSES
+    ) -> str:
+        """
+        Generate a fallback response when AI models are unavailable.
+        
+        Args:
+            user_input: User's input text
+            pet: DigiPal instance
+            command: Interpreted command (if any)
+            degradation_level: Level of service degradation
+            
+        Returns:
+            Fallback response string
+        """
+        try:
+            # Handle different degradation levels
+            if degradation_level == DegradationLevel.EMERGENCY_MODE:
+                return self._generate_emergency_response(pet)
+            
+            # Try command-specific responses first
+            if command and command in self.command_responses:
+                command_templates = self.command_responses[command].get(pet.life_stage, [])
+                if command_templates:
+                    response = random.choice(command_templates)
+                    return self._apply_personality_modifier(response, pet)
+            
+            # Fall back to general responses
+            general_templates = self.response_templates.get(pet.life_stage, [])
+            if general_templates:
+                response = random.choice(general_templates)
+                return self._apply_personality_modifier(response, pet)
+            
+            # Ultimate fallback
+            return self._generate_emergency_response(pet)
+            
+        except Exception as e:
+            logger.error(f"Fallback response generation failed: {e}")
+            return "*DigiPal is resting*"
+    
+    def _apply_personality_modifier(self, response: str, pet: DigiPal) -> str:
+        """Apply personality-based modifiers to response."""
+        try:
+            if not pet.personality_traits:
+                return response
+            
+            # Find dominant personality trait
+            dominant_trait = max(pet.personality_traits.items(), key=lambda x: x[1])
+            trait_name, trait_value = dominant_trait
+            
+            # Apply modifier if trait is strong enough
+            if trait_value > 0.7 and trait_name in self.personality_modifiers:
+                modifier = random.choice(self.personality_modifiers[trait_name])
+                return response + modifier
+            
+            return response
+            
+        except Exception:
+            return response
+    
+    def _generate_emergency_response(self, pet: DigiPal) -> str:
+        """Generate minimal emergency response."""
+        emergency_responses = {
+            LifeStage.EGG: "*egg*",
+            LifeStage.BABY: "*baby*",
+            LifeStage.CHILD: "Hi!",
+            LifeStage.TEEN: "Hey.",
+            LifeStage.YOUNG_ADULT: "Hello!",
+            LifeStage.ADULT: "Greetings.",
+            LifeStage.ELDERLY: "Hello, friend."
+        }
+        
+        return emergency_responses.get(pet.life_stage, "*DigiPal*")
+
+
+class AIServiceManager:
+    """Manages AI service availability and degradation."""
+    
+    def __init__(self):
+        """Initialize AI service manager."""
+        self.service_status: Dict[str, bool] = {
+            'language_model': True,
+            'speech_processing': True,
+            'image_generation': True
+        }
+        
+        self.circuit_breakers: Dict[str, CircuitBreaker] = {}
+        self.fallback_generator = FallbackResponseGenerator()
+        self.current_degradation_level = DegradationLevel.FULL_SERVICE
+        
+        # Initialize circuit breakers
+        self._initialize_circuit_breakers()
+    
+    def _initialize_circuit_breakers(self):
+        """Initialize circuit breakers for AI services."""
+        config = CircuitBreakerConfig(
+            failure_threshold=3,
+            recovery_timeout=300.0,  # 5 minutes
+            expected_exception=AIModelError
+        )
+        
+        for service in self.service_status.keys():
+            self.circuit_breakers[service] = CircuitBreaker(config)
+    
+    def call_ai_service(
+        self, 
+        service_name: str, 
+        func: Callable, 
+        fallback_func: Optional[Callable] = None,
+        *args, 
+        **kwargs
+    ) -> Any:
+        """
+        Call an AI service with circuit breaker protection.
+        
+        Args:
+            service_name: Name of the AI service
+            func: Function to call
+            fallback_func: Fallback function if service fails
+            *args: Function arguments
+            **kwargs: Function keyword arguments
+            
+        Returns:
+            Service result or fallback result
+        """
+        try:
+            circuit_breaker = self.circuit_breakers.get(service_name)
+            if circuit_breaker:
+                result = circuit_breaker.call(func, *args, **kwargs)
+                self.service_status[service_name] = True
+                self._update_degradation_level()
+                return result
+            else:
+                return func(*args, **kwargs)
+                
+        except Exception as e:
+            logger.warning(f"AI service {service_name} failed: {e}")
+            self.service_status[service_name] = False
+            self._update_degradation_level()
+            
+            if fallback_func:
+                try:
+                    return fallback_func(*args, **kwargs)
+                except Exception as fallback_error:
+                    logger.error(f"Fallback for {service_name} also failed: {fallback_error}")
+            
+            raise AIModelError(f"AI service {service_name} unavailable: {str(e)}")
+    
+    def _update_degradation_level(self):
+        """Update current degradation level based on service status."""
+        available_services = sum(1 for status in self.service_status.values() if status)
+        total_services = len(self.service_status)
+        
+        if available_services == total_services:
+            self.current_degradation_level = DegradationLevel.FULL_SERVICE
+        elif available_services >= total_services * 0.75:
+            self.current_degradation_level = DegradationLevel.REDUCED_FEATURES
+        elif available_services >= total_services * 0.5:
+            self.current_degradation_level = DegradationLevel.BASIC_RESPONSES
+        elif available_services > 0:
+            self.current_degradation_level = DegradationLevel.MINIMAL_FUNCTION
+        else:
+            self.current_degradation_level = DegradationLevel.EMERGENCY_MODE
+        
+        logger.info(f"Degradation level updated to: {self.current_degradation_level.value}")
+    
+    def get_service_status(self) -> Dict[str, Any]:
+        """Get current service status and degradation level."""
+        return {
+            'services': dict(self.service_status),
+            'degradation_level': self.current_degradation_level.value,
+            'circuit_breakers': {
+                name: {
+                    'state': cb.state,
+                    'failure_count': cb.failure_count,
+                    'last_failure': cb.last_failure_time.isoformat() if cb.last_failure_time else None
+                }
+                for name, cb in self.circuit_breakers.items()
+            }
+        }
+    
+    def force_service_recovery(self, service_name: str):
+        """Force recovery attempt for a specific service."""
+        if service_name in self.circuit_breakers:
+            circuit_breaker = self.circuit_breakers[service_name]
+            circuit_breaker.state = "half-open"
+            circuit_breaker.failure_count = 0
+            logger.info(f"Forced recovery attempt for service: {service_name}")
+    
+    def generate_degraded_response(
+        self, 
+        user_input: str, 
+        pet: DigiPal, 
+        command: Optional[str] = None
+    ) -> Interaction:
+        """
+        Generate a response using degraded AI capabilities.
+        
+        Args:
+            user_input: User's input text
+            pet: DigiPal instance
+            command: Interpreted command (if any)
+            
+        Returns:
+            Interaction with fallback response
+        """
+        try:
+            response = self.fallback_generator.generate_fallback_response(
+                user_input, pet, command, self.current_degradation_level
+            )
+            
+            # Create interaction
+            interaction = Interaction(
+                timestamp=datetime.now(),
+                user_input=user_input,
+                interpreted_command=command or "",
+                pet_response=response,
+                attribute_changes={},
+                success=True,
+                result=InteractionResult.SUCCESS
+            )
+            
+            # Add degradation notice for non-emergency modes
+            if self.current_degradation_level != DegradationLevel.FULL_SERVICE:
+                if self.current_degradation_level != DegradationLevel.EMERGENCY_MODE:
+                    interaction.pet_response += " (AI services are currently limited)"
+            
+            return interaction
+            
+        except Exception as e:
+            logger.error(f"Degraded response generation failed: {e}")
+            
+            # Ultimate fallback
+            return Interaction(
+                timestamp=datetime.now(),
+                user_input=user_input,
+                interpreted_command="",
+                pet_response="*DigiPal is resting*",
+                attribute_changes={},
+                success=False,
+                result=InteractionResult.FAILURE
+            )
+
+
+# Global AI service manager instance
+ai_service_manager = AIServiceManager()
+
+
+def with_ai_fallback(service_name: str, fallback_response: Optional[str] = None):
+    """
+    Decorator for AI service calls with automatic fallback.
+    
+    Args:
+        service_name: Name of the AI service
+        fallback_response: Default fallback response
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            def fallback_func(*args, **kwargs):
+                if fallback_response:
+                    return fallback_response
+                # Try to extract pet from arguments for context-aware fallback
+                pet = None
+                for arg in args:
+                    if isinstance(arg, DigiPal):
+                        pet = arg
+                        break
+                
+                if pet:
+                    return ai_service_manager.fallback_generator.generate_fallback_response(
+                        "", pet, None, ai_service_manager.current_degradation_level
+                    )
+                
+                return "Service temporarily unavailable"
+            
+            return ai_service_manager.call_ai_service(
+                service_name, func, fallback_func, *args, **kwargs
+            )
+        
+        return wrapper
+    return decorator

digipal/ai/image_generator.py

@@ -0,0 +1,402 @@
+"""
+Image generation system for DigiPal visualization using FLUX.1-dev model.
+"""
+
+import os
+import torch
+import logging
+from typing import Optional, Dict, Any, List
+from pathlib import Path
+from PIL import Image
+import hashlib
+import json
+from datetime import datetime
+
+from ..core.models import DigiPal
+from ..core.enums import LifeStage, EggType
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+class ImageGenerator:
+    """
+    Handles image generation for DigiPal pets using FLUX.1-dev model.
+    Includes caching, fallback systems, and professional prompt generation.
+    """
+    
+    def __init__(self, 
+                 model_name: str = "black-forest-labs/FLUX.1-dev",
+                 cache_dir: str = "demo_assets/images",
+                 fallback_dir: str = "demo_assets/images/fallbacks"):
+        """
+        Initialize the image generator.
+        
+        Args:
+            model_name: HuggingFace model name for image generation
+            cache_dir: Directory to cache generated images
+            fallback_dir: Directory containing fallback images
+        """
+        self.model_name = model_name
+        self.cache_dir = Path(cache_dir)
+        self.fallback_dir = Path(fallback_dir)
+        self.pipe = None
+        self._model_loaded = False
+        
+        # Create directories if they don't exist
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.fallback_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Image generation parameters
+        self.generation_params = {
+            "height": 1024,
+            "width": 1024,
+            "guidance_scale": 3.5,
+            "num_inference_steps": 50,
+            "max_sequence_length": 512
+        }
+        
+        # Initialize prompt templates
+        self._init_prompt_templates()
+        
+        # Initialize fallback images
+        self._init_fallback_images()
+    
+    def _init_prompt_templates(self):
+        """Initialize professional prompt templates for each life stage and egg type."""
+        
+        # Base style modifiers
+        self.style_base = "digital art, high quality, detailed, vibrant colors, anime style"
+        
+        # Egg type characteristics
+        self.egg_type_traits = {
+            EggType.RED: {
+                "element": "fire",
+                "colors": "red, orange, golden",
+                "traits": "fierce, energetic, blazing aura",
+                "environment": "volcanic, warm lighting"
+            },
+            EggType.BLUE: {
+                "element": "water",
+                "colors": "blue, cyan, silver",
+                "traits": "calm, protective, flowing aura",
+                "environment": "aquatic, cool lighting"
+            },
+            EggType.GREEN: {
+                "element": "earth",
+                "colors": "green, brown, gold",
+                "traits": "sturdy, wise, natural aura",
+                "environment": "forest, natural lighting"
+            }
+        }
+        
+        # Life stage characteristics
+        self.stage_traits = {
+            LifeStage.EGG: {
+                "form": "mystical egg with glowing patterns",
+                "size": "medium sized",
+                "features": "smooth shell, magical runes, soft glow"
+            },
+            LifeStage.BABY: {
+                "form": "small cute creature",
+                "size": "tiny, adorable",
+                "features": "big eyes, soft fur, playful expression"
+            },
+            LifeStage.CHILD: {
+                "form": "young creature",
+                "size": "small but growing",
+                "features": "curious eyes, developing features, energetic pose"
+            },
+            LifeStage.TEEN: {
+                "form": "adolescent creature",
+                "size": "medium sized",
+                "features": "developing strength, confident stance, maturing features"
+            },
+            LifeStage.YOUNG_ADULT: {
+                "form": "strong young creature",
+                "size": "well-proportioned",
+                "features": "athletic build, determined expression, full power"
+            },
+            LifeStage.ADULT: {
+                "form": "mature powerful creature",
+                "size": "large and imposing",
+                "features": "wise eyes, peak physical form, commanding presence"
+            },
+            LifeStage.ELDERLY: {
+                "form": "ancient wise creature",
+                "size": "dignified stature",
+                "features": "wise expression, weathered but noble, mystical aura"
+            }
+        }
+    
+    def _init_fallback_images(self):
+        """Initialize fallback image mappings."""
+        self.fallback_images = {}
+        
+        # Create simple fallback images if they don't exist
+        for stage in LifeStage:
+            for egg_type in EggType:
+                fallback_path = self.fallback_dir / f"{stage.value}_{egg_type.value}.png"
+                self.fallback_images[f"{stage.value}_{egg_type.value}"] = str(fallback_path)
+                
+                # Create a simple placeholder if file doesn't exist
+                if not fallback_path.exists():
+                    self._create_placeholder_image(fallback_path, stage, egg_type)
+    
+    def _create_placeholder_image(self, path: Path, stage: LifeStage, egg_type: EggType):
+        """Create a simple placeholder image."""
+        try:
+            # Create a simple colored rectangle as placeholder
+            color_map = {
+                EggType.RED: (255, 100, 100),
+                EggType.BLUE: (100, 100, 255),
+                EggType.GREEN: (100, 255, 100)
+            }
+            
+            color = color_map.get(egg_type, (128, 128, 128))
+            img = Image.new('RGB', (512, 512), color)
+            img.save(path)
+            logger.info(f"Created placeholder image: {path}")
+            
+        except Exception as e:
+            logger.error(f"Failed to create placeholder image {path}: {e}")
+    
+    def _load_model(self):
+        """Load the FLUX.1-dev model for image generation."""
+        if self._model_loaded:
+            return
+        
+        try:
+            from diffusers import FluxPipeline
+            
+            logger.info(f"Loading image generation model: {self.model_name}")
+            self.pipe = FluxPipeline.from_pretrained(
+                self.model_name, 
+                torch_dtype=torch.bfloat16
+            )
+            
+            # Enable CPU offload to save VRAM
+            self.pipe.enable_model_cpu_offload()
+            
+            self._model_loaded = True
+            logger.info("Image generation model loaded successfully")
+            
+        except ImportError:
+            logger.error("diffusers library not installed. Run: pip install -U diffusers")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to load image generation model: {e}")
+            raise
+    
+    def generate_prompt(self, digipal: DigiPal) -> str:
+        """
+        Generate a professional prompt for DigiPal image generation.
+        
+        Args:
+            digipal: DigiPal instance to generate prompt for
+            
+        Returns:
+            Professional prompt string for image generation
+        """
+        egg_traits = self.egg_type_traits.get(digipal.egg_type, self.egg_type_traits[EggType.RED])
+        stage_traits = self.stage_traits.get(digipal.life_stage, self.stage_traits[LifeStage.BABY])
+        
+        # Build attribute modifiers based on DigiPal stats
+        attribute_modifiers = []
+        
+        # High offense = more aggressive/fierce appearance
+        if digipal.offense > 50:
+            attribute_modifiers.append("fierce expression, sharp features")
+        
+        # High defense = more armored/protective appearance
+        if digipal.defense > 50:
+            attribute_modifiers.append("armored, protective stance")
+        
+        # High speed = more sleek/agile appearance
+        if digipal.speed > 50:
+            attribute_modifiers.append("sleek, agile build")
+        
+        # High brains = more intelligent/wise appearance
+        if digipal.brains > 50:
+            attribute_modifiers.append("intelligent eyes, wise demeanor")
+        
+        # Happiness affects expression
+        if digipal.happiness > 70:
+            attribute_modifiers.append("happy, cheerful expression")
+        elif digipal.happiness < 30:
+            attribute_modifiers.append("sad, tired expression")
+        
+        # Build the complete prompt
+        prompt_parts = [
+            f"a {stage_traits['form']} digimon",
+            f"touched by the power of {egg_traits['element']}",
+            f"{stage_traits['size']}, {stage_traits['features']}",
+            f"colors: {egg_traits['colors']}",
+            f"{egg_traits['traits']}"
+        ]
+        
+        if attribute_modifiers:
+            prompt_parts.append(", ".join(attribute_modifiers))
+        
+        prompt_parts.extend([
+            f"in {egg_traits['environment']}",
+            f"life stage: {digipal.life_stage.value}",
+            self.style_base
+        ])
+        
+        prompt = ", ".join(prompt_parts)
+        
+        logger.debug(f"Generated prompt for {digipal.name}: {prompt}")
+        return prompt
+    
+    def _get_cache_key(self, prompt: str, params: Dict[str, Any]) -> str:
+        """Generate cache key for image based on prompt and parameters."""
+        cache_data = {
+            "prompt": prompt,
+            "params": params
+        }
+        cache_string = json.dumps(cache_data, sort_keys=True)
+        return hashlib.md5(cache_string.encode()).hexdigest()
+    
+    def _get_cached_image_path(self, cache_key: str) -> Optional[Path]:
+        """Check if cached image exists and return path."""
+        cache_path = self.cache_dir / f"{cache_key}.png"
+        if cache_path.exists():
+            logger.debug(f"Found cached image: {cache_path}")
+            return cache_path
+        return None
+    
+    def _save_to_cache(self, image: Image.Image, cache_key: str) -> Path:
+        """Save generated image to cache."""
+        cache_path = self.cache_dir / f"{cache_key}.png"
+        image.save(cache_path)
+        logger.info(f"Saved generated image to cache: {cache_path}")
+        return cache_path
+    
+    def _get_fallback_image(self, digipal: DigiPal) -> str:
+        """Get fallback image path for DigiPal."""
+        fallback_key = f"{digipal.life_stage.value}_{digipal.egg_type.value}"
+        fallback_path = self.fallback_images.get(fallback_key)
+        
+        if fallback_path and Path(fallback_path).exists():
+            logger.info(f"Using fallback image: {fallback_path}")
+            return fallback_path
+        
+        # Ultimate fallback - create a generic placeholder
+        generic_fallback = self.fallback_dir / "generic_placeholder.png"
+        if not generic_fallback.exists():
+            self._create_placeholder_image(generic_fallback, digipal.life_stage, digipal.egg_type)
+        
+        logger.warning(f"Using generic fallback image: {generic_fallback}")
+        return str(generic_fallback)
+    
+    def generate_image(self, digipal: DigiPal, force_regenerate: bool = False) -> str:
+        """
+        Generate or retrieve cached image for DigiPal.
+        
+        Args:
+            digipal: DigiPal instance to generate image for
+            force_regenerate: Force regeneration even if cached image exists
+            
+        Returns:
+            Path to generated or cached image file
+        """
+        try:
+            # Generate prompt
+            prompt = self.generate_prompt(digipal)
+            
+            # Check cache first (unless force regenerate)
+            cache_key = self._get_cache_key(prompt, self.generation_params)
+            
+            if not force_regenerate:
+                cached_path = self._get_cached_image_path(cache_key)
+                if cached_path:
+                    return str(cached_path)
+            
+            # Load model if not already loaded
+            self._load_model()
+            
+            # Generate image
+            logger.info(f"Generating image for {digipal.name} ({digipal.life_stage.value})")
+            
+            generator = torch.Generator("cpu").manual_seed(
+                hash(digipal.id) % (2**32)  # Consistent seed based on DigiPal ID
+            )
+            
+            image = self.pipe(
+                prompt,
+                generator=generator,
+                **self.generation_params
+            ).images[0]
+            
+            # Save to cache
+            cache_path = self._save_to_cache(image, cache_key)
+            
+            # Update DigiPal with new image info
+            digipal.current_image_path = str(cache_path)
+            digipal.image_generation_prompt = prompt
+            
+            return str(cache_path)
+            
+        except Exception as e:
+            logger.error(f"Image generation failed for {digipal.name}: {e}")
+            
+            # Return fallback image
+            fallback_path = self._get_fallback_image(digipal)
+            digipal.current_image_path = fallback_path
+            digipal.image_generation_prompt = f"Fallback image for {digipal.life_stage.value} {digipal.egg_type.value}"
+            
+            return fallback_path
+    
+    def update_image_for_evolution(self, digipal: DigiPal) -> str:
+        """
+        Generate new image when DigiPal evolves to new life stage.
+        
+        Args:
+            digipal: DigiPal that has evolved
+            
+        Returns:
+            Path to new image file
+        """
+        logger.info(f"Generating evolution image for {digipal.name} -> {digipal.life_stage.value}")
+        return self.generate_image(digipal, force_regenerate=True)
+    
+    def cleanup_cache(self, max_age_days: int = 30):
+        """
+        Clean up old cached images.
+        
+        Args:
+            max_age_days: Maximum age of cached images in days
+        """
+        try:
+            current_time = datetime.now()
+            cleaned_count = 0
+            
+            for image_file in self.cache_dir.glob("*.png"):
+                file_age = current_time - datetime.fromtimestamp(image_file.stat().st_mtime)
+                
+                if file_age.days > max_age_days:
+                    image_file.unlink()
+                    cleaned_count += 1
+            
+            logger.info(f"Cleaned up {cleaned_count} old cached images")
+            
+        except Exception as e:
+            logger.error(f"Cache cleanup failed: {e}")
+    
+    def get_cache_info(self) -> Dict[str, Any]:
+        """Get information about the image cache."""
+        try:
+            cache_files = list(self.cache_dir.glob("*.png"))
+            total_size = sum(f.stat().st_size for f in cache_files)
+            
+            return {
+                "cache_dir": str(self.cache_dir),
+                "cached_images": len(cache_files),
+                "total_size_mb": round(total_size / (1024 * 1024), 2),
+                "model_loaded": self._model_loaded
+            }
+            
+        except Exception as e:
+            logger.error(f"Failed to get cache info: {e}")
+            return {"error": str(e)}

digipal/ai/language_model.py

@@ -0,0 +1,532 @@
+"""
+Language model integration for DigiPal using Qwen3-0.6B.
+
+This module handles the integration with Qwen/Qwen3-0.6B model for natural language
+processing, including model loading, quantization, and context-aware response generation.
+"""
+
+import logging
+import torch
+from typing import Dict, List, Optional, Any, Tuple
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+import json
+from datetime import datetime
+
+from ..core.models import DigiPal, Interaction
+from ..core.enums import LifeStage
+from ..core.exceptions import AIModelError, NetworkError
+from ..core.error_handler import with_error_handling, with_retry, RetryConfig
+from .graceful_degradation import with_ai_fallback, ai_service_manager
+
+
+logger = logging.getLogger(__name__)
+
+
+class LanguageModel:
+    """
+    Manages Qwen3-0.6B model for natural language processing with DigiPal context.
+    """
+    
+    def __init__(self, model_name: str = "Qwen/Qwen3-0.6B", quantization: bool = True):
+        """
+        Initialize the language model.
+        
+        Args:
+            model_name: HuggingFace model identifier
+            quantization: Whether to use quantization for memory optimization
+        """
+        self.model_name = model_name
+        self.quantization = quantization
+        self.tokenizer = None
+        self.model = None
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        
+        # Initialize prompt templates
+        self.prompt_templates = self._initialize_prompt_templates()
+        
+        logger.info(f"LanguageModel initialized with model: {model_name}")
+        logger.info(f"Device: {self.device}")
+        logger.info(f"Quantization: {quantization}")
+    
+    @with_error_handling(fallback_value=False, context={'operation': 'model_loading'})
+    @with_retry(RetryConfig(max_attempts=3, retry_on=[NetworkError, ConnectionError]))
+    def load_model(self) -> bool:
+        """
+        Load the Qwen3-0.6B model and tokenizer.
+        
+        Returns:
+            True if model loaded successfully, False otherwise
+        """
+        try:
+            logger.info(f"Loading tokenizer for {self.model_name}")
+            self.tokenizer = AutoTokenizer.from_pretrained(self.model_name)
+            
+            # Configure quantization if enabled
+            model_kwargs = {
+                "torch_dtype": "auto",
+                "device_map": "auto"
+            }
+            
+            if self.quantization and torch.cuda.is_available():
+                logger.info("Configuring 4-bit quantization")
+                quantization_config = BitsAndBytesConfig(
+                    load_in_4bit=True,
+                    bnb_4bit_compute_dtype=torch.float16,
+                    bnb_4bit_use_double_quant=True,
+                    bnb_4bit_quant_type="nf4"
+                )
+                model_kwargs["quantization_config"] = quantization_config
+            
+            logger.info(f"Loading model {self.model_name}")
+            self.model = AutoModelForCausalLM.from_pretrained(
+                self.model_name,
+                **model_kwargs
+            )
+            
+            logger.info("Model loaded successfully")
+            return True
+            
+        except (ConnectionError, TimeoutError) as e:
+            raise NetworkError(f"Network error loading model: {str(e)}")
+        except Exception as e:
+            raise AIModelError(f"Failed to load model: {str(e)}")
+    
+    @with_ai_fallback("language_model")
+    def generate_response(self, user_input: str, pet: DigiPal, memory_context: str = "", max_tokens: int = 150) -> str:
+        """
+        Generate contextual response using Qwen3-0.6B model.
+        
+        Args:
+            user_input: User's input text
+            pet: DigiPal instance for context
+            memory_context: Additional memory context from RAG system
+            max_tokens: Maximum tokens to generate
+            
+        Returns:
+            Generated response text
+        """
+        if not self.model or not self.tokenizer:
+            logger.warning("Model not loaded, using fallback response")
+            raise AIModelError("Language model not loaded")
+        
+        try:
+            # Create context-aware prompt with memory context
+            prompt = self._create_prompt(user_input, pet, memory_context)
+            
+            # Prepare messages for chat template
+            messages = [
+                {"role": "user", "content": prompt}
+            ]
+            
+            # Apply chat template
+            text = self.tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True,
+                enable_thinking=True
+            )
+            
+            # Tokenize input
+            model_inputs = self.tokenizer([text], return_tensors="pt").to(self.model.device)
+            
+            # Generate response
+            with torch.no_grad():
+                generated_ids = self.model.generate(
+                    **model_inputs,
+                    max_new_tokens=max_tokens,
+                    do_sample=True,
+                    temperature=0.7,
+                    top_p=0.9,
+                    pad_token_id=self.tokenizer.eos_token_id
+                )
+            
+            # Extract generated tokens
+            output_ids = generated_ids[0][len(model_inputs.input_ids[0]):].tolist()
+            
+            # Parse thinking content and actual response
+            thinking_content, content = self._parse_response(output_ids)
+            
+            # Log thinking content for debugging
+            if thinking_content:
+                logger.debug(f"Model thinking: {thinking_content[:100]}...")
+            
+            # Clean and validate response
+            response = self._clean_response(content, pet)
+            
+            logger.debug(f"Generated response: {response}")
+            return response
+            
+        except torch.cuda.OutOfMemoryError as e:
+            raise AIModelError(f"GPU memory error: {str(e)}")
+        except Exception as e:
+            logger.error(f"Error generating response: {e}")
+            raise AIModelError(f"Language model generation failed: {str(e)}")
+    
+    def _create_prompt(self, user_input: str, pet: DigiPal, memory_context: str = "") -> str:
+        """
+        Create context-aware prompt incorporating pet state, personality, and memory context.
+        
+        Args:
+            user_input: User's input text
+            pet: DigiPal instance for context
+            memory_context: Additional memory context from RAG system
+            
+        Returns:
+            Formatted prompt string
+        """
+        # Get base template for life stage
+        template = self.prompt_templates.get(pet.life_stage, self.prompt_templates[LifeStage.BABY])
+        
+        # Get recent conversation context
+        recent_interactions = pet.conversation_history[-3:] if pet.conversation_history else []
+        conversation_context = ""
+        if recent_interactions:
+            conversation_context = "\n".join([
+                f"User: {interaction.user_input}\nDigiPal: {interaction.pet_response}"
+                for interaction in recent_interactions
+            ])
+        
+        # Calculate personality description
+        personality_desc = self._get_personality_description(pet)
+        
+        # Format the prompt with memory context
+        prompt = template.format(
+            name=pet.name,
+            life_stage=pet.life_stage.value,
+            hp=pet.hp,
+            happiness=pet.happiness,
+            energy=pet.energy,
+            discipline=pet.discipline,
+            age_hours=pet.get_age_hours(),
+            personality=personality_desc,
+            recent_conversation=conversation_context,
+            memory_context=memory_context,
+            user_input=user_input
+        )
+        
+        return prompt
+    
+    def _initialize_prompt_templates(self) -> Dict[LifeStage, str]:
+        """
+        Initialize prompt templates for each life stage.
+        
+        Returns:
+            Dictionary mapping life stages to prompt templates
+        """
+        return {
+            LifeStage.EGG: """
+You are a DigiPal egg named {name}. You cannot speak or respond directly, but you can show subtle reactions.
+The user said: "{user_input}"
+Respond with a very brief description of the egg's reaction (1-2 words or simple action).
+""",
+            
+            LifeStage.BABY: """
+You are {name}, a baby DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As a baby, you can only understand basic commands: eat, sleep, good, bad.
+You communicate with simple baby sounds, single words, and basic emotions.
+You are curious, innocent, and learning about the world.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as a baby DigiPal would - keep it simple, innocent, and age-appropriate. Use baby talk, simple words, and express basic emotions.
+""",
+            
+            LifeStage.CHILD: """
+You are {name}, a child DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As a child, you understand: eat, sleep, good, bad, play, train.
+You are energetic, playful, and eager to learn. You speak in simple sentences and show enthusiasm.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as a child DigiPal would - enthusiastic, simple language, and show interest in play and learning.
+""",
+            
+            LifeStage.TEEN: """
+You are {name}, a teenage DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As a teen, you understand most commands and can have conversations.
+You're developing your own personality, sometimes moody, but generally cooperative.
+You can be a bit rebellious but still care about your relationship with your caretaker.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as a teenage DigiPal would - more complex thoughts, some attitude, but still caring.
+""",
+            
+            LifeStage.YOUNG_ADULT: """
+You are {name}, a young adult DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As a young adult, you're confident, capable, and have developed your full personality.
+You can engage in complex conversations and understand all commands.
+You're at your physical and mental peak, ready for challenges.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as a confident young adult DigiPal - articulate, capable, and engaging.
+""",
+            
+            LifeStage.ADULT: """
+You are {name}, an adult DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As an adult, you're wise, mature, and thoughtful in your responses.
+You have deep understanding and can provide guidance and wisdom.
+You're protective and caring, with a strong bond to your caretaker.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as a mature adult DigiPal - wise, thoughtful, and caring.
+""",
+            
+            LifeStage.ELDERLY: """
+You are {name}, an elderly DigiPal in the {life_stage} stage. You are {age_hours:.1f} hours old.
+Current stats: HP={hp}, Happiness={happiness}, Energy={energy}, Discipline={discipline}
+Personality: {personality}
+
+As an elderly DigiPal, you're wise from experience but also nostalgic and gentle.
+You move slower but think deeply. You cherish every moment with your caretaker.
+You often reflect on memories and share wisdom from your long life.
+
+Recent conversation:
+{recent_conversation}
+
+{memory_context}
+
+User just said: "{user_input}"
+
+Respond as an elderly DigiPal - gentle, wise, nostalgic, and deeply caring.
+"""
+        }
+    
+    def _get_personality_description(self, pet: DigiPal) -> str:
+        """
+        Generate personality description from pet's personality traits.
+        
+        Args:
+            pet: DigiPal instance
+            
+        Returns:
+            Human-readable personality description
+        """
+        if not pet.personality_traits:
+            return "developing personality"
+        
+        traits = []
+        
+        # Analyze personality traits
+        if pet.personality_traits.get('friendliness', 0.5) > 0.7:
+            traits.append("very friendly")
+        elif pet.personality_traits.get('friendliness', 0.5) < 0.3:
+            traits.append("somewhat shy")
+        
+        if pet.personality_traits.get('playfulness', 0.5) > 0.7:
+            traits.append("very playful")
+        elif pet.personality_traits.get('playfulness', 0.5) < 0.3:
+            traits.append("more serious")
+        
+        if pet.personality_traits.get('obedience', 0.5) > 0.7:
+            traits.append("well-behaved")
+        elif pet.personality_traits.get('obedience', 0.5) < 0.3:
+            traits.append("a bit rebellious")
+        
+        if pet.personality_traits.get('curiosity', 0.5) > 0.7:
+            traits.append("very curious")
+        
+        return ", ".join(traits) if traits else "balanced personality"
+    
+    def _parse_response(self, output_ids: List[int]) -> Tuple[str, str]:
+        """
+        Parse thinking content and actual response from model output.
+        
+        Args:
+            output_ids: Generated token IDs
+            
+        Returns:
+            Tuple of (thinking_content, actual_response)
+        """
+        try:
+            # Look for thinking end token (151668 = </think>)
+            index = len(output_ids) - output_ids[::-1].index(151668)
+        except ValueError:
+            # No thinking content found
+            index = 0
+        
+        thinking_content = ""
+        content = ""
+        
+        if index > 0:
+            thinking_content = self.tokenizer.decode(
+                output_ids[:index], 
+                skip_special_tokens=True
+            ).strip("\n")
+        
+        if index < len(output_ids):
+            content = self.tokenizer.decode(
+                output_ids[index:], 
+                skip_special_tokens=True
+            ).strip("\n")
+        else:
+            # If no content after thinking, use full output
+            content = self.tokenizer.decode(
+                output_ids, 
+                skip_special_tokens=True
+            ).strip("\n")
+        
+        return thinking_content, content
+    
+    def _clean_response(self, response: str, pet: DigiPal) -> str:
+        """
+        Clean and validate the generated response.
+        
+        Args:
+            response: Raw generated response
+            pet: DigiPal instance for context
+            
+        Returns:
+            Cleaned response string
+        """
+        # Remove any unwanted prefixes or suffixes
+        response = response.strip()
+        
+        # Remove common AI assistant prefixes (more precise matching)
+        prefixes_to_remove = [
+            "As a DigiPal, ", "As your DigiPal, ", "DigiPal: ", f"{pet.name}: ",
+            "Response: "
+        ]
+        
+        for prefix in prefixes_to_remove:
+            if response.startswith(prefix):
+                response = response[len(prefix):].strip()
+                break  # Only remove one prefix
+        
+        # Limit response length based on life stage
+        max_lengths = {
+            LifeStage.EGG: 20,
+            LifeStage.BABY: 50,
+            LifeStage.CHILD: 100,
+            LifeStage.TEEN: 150,
+            LifeStage.YOUNG_ADULT: 200,
+            LifeStage.ADULT: 200,
+            LifeStage.ELDERLY: 180
+        }
+        
+        max_length = max_lengths.get(pet.life_stage, 100)
+        if len(response) > max_length:
+            # Find last complete sentence within limit
+            sentences = response.split('.')
+            truncated = ""
+            for sentence in sentences:
+                potential = truncated + sentence.strip()
+                if len(potential) <= max_length - 1:  # Leave room for period
+                    truncated = potential + "."
+                else:
+                    break
+            
+            if truncated and len(truncated) > 10:  # Ensure we have meaningful content
+                response = truncated.strip()
+            else:
+                # If no complete sentence fits, truncate at word boundary
+                words = response.split()
+                truncated_words = []
+                current_length = 0
+                
+                for word in words:
+                    if current_length + len(word) + 1 <= max_length - 3:  # Leave room for "..."
+                        truncated_words.append(word)
+                        current_length += len(word) + 1
+                    else:
+                        break
+                
+                if truncated_words:
+                    response = " ".join(truncated_words) + "..."
+                else:
+                    response = response[:max_length-3] + "..."
+        
+        # Ensure response is not empty
+        if not response:
+            response = self._fallback_response("", pet)
+        
+        return response
+    
+    def _fallback_response(self, user_input: str, pet: DigiPal) -> str:
+        """
+        Generate fallback response when model is unavailable.
+        
+        Args:
+            user_input: User's input text
+            pet: DigiPal instance
+            
+        Returns:
+            Fallback response string
+        """
+        fallback_responses = {
+            LifeStage.EGG: "*The egg remains silent*",
+            LifeStage.BABY: "*baby sounds*",
+            LifeStage.CHILD: "I'm still learning!",
+            LifeStage.TEEN: "Hmm, let me think about that...",
+            LifeStage.YOUNG_ADULT: "That's interesting to consider.",
+            LifeStage.ADULT: "I understand what you're saying.",
+            LifeStage.ELDERLY: "Ah, yes... I see..."
+        }
+        
+        return fallback_responses.get(pet.life_stage, "I'm listening...")
+    
+    def is_loaded(self) -> bool:
+        """
+        Check if the model is loaded and ready.
+        
+        Returns:
+            True if model is loaded, False otherwise
+        """
+        return self.model is not None and self.tokenizer is not None
+    
+    def get_model_info(self) -> Dict[str, Any]:
+        """
+        Get information about the loaded model.
+        
+        Returns:
+            Dictionary with model information
+        """
+        return {
+            'model_name': self.model_name,
+            'quantization': self.quantization,
+            'device': str(self.device),
+            'loaded': self.is_loaded(),
+            'memory_usage': torch.cuda.memory_allocated() if torch.cuda.is_available() else 0
+        }

digipal/ai/speech_processor.py

@@ -0,0 +1,510 @@
+"""
+Speech processing module using Kyutai speech-to-text models.
+
+This module provides speech-to-text functionality using Kyutai's STT models
+with audio validation, preprocessing, and error handling.
+"""
+
+import torch
+import numpy as np
+import logging
+from typing import Optional, Dict, Any, Union, List
+from dataclasses import dataclass
+import io
+import wave
+from transformers import KyutaiSpeechToTextProcessor, KyutaiSpeechToTextForConditionalGeneration
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AudioValidationResult:
+    """Result of audio validation checks."""
+    is_valid: bool
+    sample_rate: int
+    duration: float
+    channels: int
+    issues: List[str]
+
+
+@dataclass
+class SpeechProcessingResult:
+    """Result of speech processing operation."""
+    success: bool
+    transcribed_text: str
+    confidence: float
+    processing_time: float
+    error_message: Optional[str] = None
+
+
+class AudioValidator:
+    """Validates and preprocesses audio input for speech recognition."""
+    
+    def __init__(self, target_sample_rate: int = 24000, min_duration: float = 0.1, max_duration: float = 30.0):
+        """
+        Initialize audio validator.
+        
+        Args:
+            target_sample_rate: Target sample rate for processing (24kHz for Kyutai)
+            min_duration: Minimum audio duration in seconds
+            max_duration: Maximum audio duration in seconds
+        """
+        self.target_sample_rate = target_sample_rate
+        self.min_duration = min_duration
+        self.max_duration = max_duration
+    
+    def validate_audio(self, audio_data: Union[bytes, np.ndarray], sample_rate: Optional[int] = None) -> AudioValidationResult:
+        """
+        Validate audio data for speech processing.
+        
+        Args:
+            audio_data: Raw audio data as bytes or numpy array
+            sample_rate: Sample rate of the audio data
+            
+        Returns:
+            AudioValidationResult with validation details
+        """
+        issues = []
+        
+        try:
+            # Convert bytes to numpy array if needed
+            if isinstance(audio_data, bytes):
+                audio_array, detected_sample_rate = self._bytes_to_array(audio_data)
+                if sample_rate is None:
+                    sample_rate = detected_sample_rate
+            else:
+                audio_array = audio_data
+                if sample_rate is None:
+                    sample_rate = self.target_sample_rate
+            
+            # Check if audio array is valid
+            if audio_array is None or len(audio_array) == 0:
+                issues.append("Empty or invalid audio data")
+                return AudioValidationResult(False, 0, 0.0, 0, issues)
+            
+            # Calculate duration
+            duration = len(audio_array) / sample_rate
+            
+            # Detect number of channels
+            if audio_array.ndim == 1:
+                channels = 1
+            else:
+                channels = audio_array.shape[1] if audio_array.ndim == 2 else 1
+                # Convert to mono if stereo
+                if channels > 1:
+                    audio_array = np.mean(audio_array, axis=1)
+                    channels = 1
+            
+            # Validate duration
+            if duration < self.min_duration:
+                issues.append(f"Audio too short: {duration:.2f}s (minimum: {self.min_duration}s)")
+            
+            if duration > self.max_duration:
+                issues.append(f"Audio too long: {duration:.2f}s (maximum: {self.max_duration}s)")
+            
+            # Check sample rate
+            if sample_rate != self.target_sample_rate:
+                issues.append(f"Sample rate mismatch: {sample_rate}Hz (expected: {self.target_sample_rate}Hz)")
+            
+            # Check for silence (very low amplitude)
+            if np.max(np.abs(audio_array)) < 0.01:
+                issues.append("Audio appears to be silent or very quiet")
+            
+            # Check for clipping
+            if np.max(np.abs(audio_array)) > 0.95:
+                issues.append("Audio may be clipped (too loud)")
+            
+            is_valid = len(issues) == 0
+            
+            return AudioValidationResult(
+                is_valid=is_valid,
+                sample_rate=sample_rate,
+                duration=duration,
+                channels=channels,
+                issues=issues
+            )
+            
+        except Exception as e:
+            logger.error(f"Error validating audio: {e}")
+            issues.append(f"Validation error: {str(e)}")
+            return AudioValidationResult(False, 0, 0.0, 0, issues)
+    
+    def _bytes_to_array(self, audio_bytes: bytes) -> tuple[Optional[np.ndarray], int]:
+        """
+        Convert audio bytes to numpy array.
+        
+        Args:
+            audio_bytes: Raw audio bytes
+            
+        Returns:
+            Tuple of (audio_array, sample_rate)
+        """
+        try:
+            # Try to parse as WAV file
+            with io.BytesIO(audio_bytes) as audio_io:
+                with wave.open(audio_io, 'rb') as wav_file:
+                    sample_rate = wav_file.getframerate()
+                    channels = wav_file.getnchannels()
+                    sample_width = wav_file.getsampwidth()
+                    frames = wav_file.readframes(-1)
+                    
+                    # Convert to numpy array
+                    if sample_width == 1:
+                        audio_array = np.frombuffer(frames, dtype=np.uint8)
+                        audio_array = (audio_array.astype(np.float32) - 128) / 128.0
+                    elif sample_width == 2:
+                        audio_array = np.frombuffer(frames, dtype=np.int16)
+                        audio_array = audio_array.astype(np.float32) / 32768.0
+                    elif sample_width == 4:
+                        audio_array = np.frombuffer(frames, dtype=np.int32)
+                        audio_array = audio_array.astype(np.float32) / 2147483648.0
+                    else:
+                        raise ValueError(f"Unsupported sample width: {sample_width}")
+                    
+                    # Handle stereo to mono conversion
+                    if channels == 2:
+                        audio_array = audio_array.reshape(-1, 2)
+                        audio_array = np.mean(audio_array, axis=1)
+                    
+                    return audio_array, sample_rate
+                    
+        except Exception as e:
+            logger.warning(f"Failed to parse as WAV: {e}")
+            
+        # Fallback: assume raw 16-bit PCM at target sample rate
+        try:
+            audio_array = np.frombuffer(audio_bytes, dtype=np.int16)
+            audio_array = audio_array.astype(np.float32) / 32768.0
+            return audio_array, self.target_sample_rate
+        except Exception as e:
+            logger.error(f"Failed to convert audio bytes: {e}")
+            return None, 0
+    
+    def preprocess_audio(self, audio_array: np.ndarray, sample_rate: int) -> np.ndarray:
+        """
+        Preprocess audio for optimal speech recognition.
+        
+        Args:
+            audio_array: Audio data as numpy array
+            sample_rate: Current sample rate
+            
+        Returns:
+            Preprocessed audio array
+        """
+        try:
+            # Resample if needed
+            if sample_rate != self.target_sample_rate:
+                audio_array = self._resample_audio(audio_array, sample_rate, self.target_sample_rate)
+            
+            # Apply noise reduction (simple high-pass filter)
+            audio_array = self._apply_noise_reduction(audio_array)
+            
+            # Normalize audio
+            audio_array = self._normalize_audio(audio_array)
+            
+            return audio_array
+            
+        except Exception as e:
+            logger.error(f"Error preprocessing audio: {e}")
+            return audio_array
+    
+    def _resample_audio(self, audio_array: np.ndarray, from_rate: int, to_rate: int) -> np.ndarray:
+        """Resample audio to target sample rate."""
+        if from_rate == to_rate:
+            return audio_array
+        
+        # Simple linear interpolation resampling
+        # For production, consider using scipy.signal.resample or librosa
+        ratio = to_rate / from_rate
+        new_length = int(len(audio_array) * ratio)
+        
+        # Create new time indices
+        old_indices = np.arange(len(audio_array))
+        new_indices = np.linspace(0, len(audio_array) - 1, new_length)
+        
+        # Interpolate
+        resampled = np.interp(new_indices, old_indices, audio_array)
+        
+        return resampled
+    
+    def _apply_noise_reduction(self, audio_array: np.ndarray) -> np.ndarray:
+        """Apply basic noise reduction (high-pass filter)."""
+        # Simple high-pass filter to remove low-frequency noise
+        # This is a basic implementation; for production, use proper DSP libraries
+        
+        if len(audio_array) < 3:
+            return audio_array
+        
+        # Simple first-order high-pass filter
+        alpha = 0.95
+        filtered = np.zeros_like(audio_array)
+        filtered[0] = audio_array[0]
+        
+        for i in range(1, len(audio_array)):
+            filtered[i] = alpha * (filtered[i-1] + audio_array[i] - audio_array[i-1])
+        
+        return filtered
+    
+    def _normalize_audio(self, audio_array: np.ndarray) -> np.ndarray:
+        """Normalize audio amplitude."""
+        max_val = np.max(np.abs(audio_array))
+        if max_val > 0:
+            # Normalize to 70% of maximum to avoid clipping
+            return audio_array * (0.7 / max_val)
+        return audio_array
+
+
+class SpeechProcessor:
+    """
+    Main speech processing class using Kyutai speech-to-text models.
+    """
+    
+    def __init__(self, model_id: str = "kyutai/stt-2.6b-en_fr-trfs", device: Optional[str] = None):
+        """
+        Initialize speech processor with Kyutai model.
+        
+        Args:
+            model_id: HuggingFace model identifier for Kyutai STT
+            device: Device to run model on ('cuda', 'cpu', or None for auto)
+        """
+        self.model_id = model_id
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        
+        # Initialize components
+        self.processor = None
+        self.model = None
+        self.audio_validator = AudioValidator()
+        self._model_loaded = False
+        
+        logger.info(f"SpeechProcessor initialized with model: {model_id}")
+        logger.info(f"Using device: {self.device}")
+    
+    def load_model(self) -> bool:
+        """
+        Load the Kyutai speech-to-text model and processor.
+        
+        Returns:
+            True if model loaded successfully, False otherwise
+        """
+        try:
+            logger.info(f"Loading Kyutai model: {self.model_id}")
+            
+            # Load processor
+            self.processor = KyutaiSpeechToTextProcessor.from_pretrained(self.model_id)
+            logger.info("Processor loaded successfully")
+            
+            # Load model
+            self.model = KyutaiSpeechToTextForConditionalGeneration.from_pretrained(
+                self.model_id,
+                device_map=self.device,
+                torch_dtype="auto"
+            )
+            logger.info("Model loaded successfully")
+            
+            self._model_loaded = True
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to load Kyutai model: {e}")
+            self._model_loaded = False
+            return False
+    
+    def is_model_loaded(self) -> bool:
+        """
+        Check if the model is loaded and ready.
+        
+        Returns:
+            True if model is loaded, False otherwise
+        """
+        return self._model_loaded and self.processor is not None and self.model is not None
+    
+    def process_speech(self, audio_data: Union[bytes, np.ndarray], sample_rate: Optional[int] = None) -> SpeechProcessingResult:
+        """
+        Process speech audio and convert to text.
+        
+        Args:
+            audio_data: Raw audio data as bytes or numpy array
+            sample_rate: Sample rate of the audio data
+            
+        Returns:
+            SpeechProcessingResult with transcription and metadata
+        """
+        import time
+        start_time = time.time()
+        
+        try:
+            # Ensure model is loaded
+            if not self.is_model_loaded():
+                if not self.load_model():
+                    return SpeechProcessingResult(
+                        success=False,
+                        transcribed_text="",
+                        confidence=0.0,
+                        processing_time=time.time() - start_time,
+                        error_message="Failed to load speech recognition model"
+                    )
+            
+            # Validate audio
+            validation_result = self.audio_validator.validate_audio(audio_data, sample_rate)
+            
+            if not validation_result.is_valid:
+                error_msg = f"Audio validation failed: {', '.join(validation_result.issues)}"
+                logger.warning(error_msg)
+                return SpeechProcessingResult(
+                    success=False,
+                    transcribed_text="",
+                    confidence=0.0,
+                    processing_time=time.time() - start_time,
+                    error_message=error_msg
+                )
+            
+            # Convert to numpy array if needed
+            if isinstance(audio_data, bytes):
+                audio_array, detected_sample_rate = self.audio_validator._bytes_to_array(audio_data)
+                if sample_rate is None:
+                    sample_rate = detected_sample_rate
+            else:
+                audio_array = audio_data
+                if sample_rate is None:
+                    sample_rate = validation_result.sample_rate
+            
+            # Preprocess audio
+            processed_audio = self.audio_validator.preprocess_audio(audio_array, sample_rate)
+            
+            # Prepare model inputs
+            inputs = self.processor(processed_audio)
+            inputs = inputs.to(self.device)
+            
+            # Generate transcription
+            with torch.no_grad():
+                output_tokens = self.model.generate(**inputs)
+            
+            # Decode the generated tokens
+            transcribed_text = self.processor.batch_decode(output_tokens, skip_special_tokens=True)[0]
+            
+            # Clean up transcription
+            transcribed_text = self._clean_transcription(transcribed_text)
+            
+            processing_time = time.time() - start_time
+            
+            # Calculate confidence (placeholder - Kyutai doesn't provide confidence scores directly)
+            confidence = self._estimate_confidence(transcribed_text, validation_result)
+            
+            logger.info(f"Speech processed successfully in {processing_time:.2f}s: '{transcribed_text}'")
+            
+            return SpeechProcessingResult(
+                success=True,
+                transcribed_text=transcribed_text,
+                confidence=confidence,
+                processing_time=processing_time
+            )
+            
+        except Exception as e:
+            error_msg = f"Speech processing error: {str(e)}"
+            logger.error(error_msg)
+            
+            return SpeechProcessingResult(
+                success=False,
+                transcribed_text="",
+                confidence=0.0,
+                processing_time=time.time() - start_time,
+                error_message=error_msg
+            )
+    
+    def _clean_transcription(self, text: str) -> str:
+        """
+        Clean and normalize transcribed text.
+        
+        Args:
+            text: Raw transcribed text
+            
+        Returns:
+            Cleaned transcription
+        """
+        if not text:
+            return ""
+        
+        # Remove extra whitespace
+        text = " ".join(text.split())
+        
+        # Remove common transcription artifacts
+        text = text.replace("[NOISE]", "").replace("[SILENCE]", "")
+        text = text.replace("  ", " ").strip()
+        
+        return text
+    
+    def _estimate_confidence(self, transcribed_text: str, validation_result: AudioValidationResult) -> float:
+        """
+        Estimate confidence score for transcription.
+        
+        Args:
+            transcribed_text: Transcribed text
+            validation_result: Audio validation result
+            
+        Returns:
+            Confidence score between 0.0 and 1.0
+        """
+        # This is a simple heuristic-based confidence estimation
+        # In production, you might want to use model-specific confidence measures
+        
+        confidence = 0.5  # Base confidence
+        
+        # Adjust based on audio quality
+        if len(validation_result.issues) == 0:
+            confidence += 0.3
+        else:
+            confidence -= 0.1 * len(validation_result.issues)
+        
+        # Adjust based on transcription length and content
+        if transcribed_text:
+            if len(transcribed_text.split()) >= 2:  # Multiple words
+                confidence += 0.2
+            if any(char.isalpha() for char in transcribed_text):  # Contains letters
+                confidence += 0.1
+        else:
+            confidence = 0.1  # Very low confidence for empty transcription
+        
+        # Adjust based on audio duration
+        if validation_result.duration > 1.0:  # Longer audio generally more reliable
+            confidence += 0.1
+        
+        return max(0.0, min(1.0, confidence))
+    
+    def get_model_info(self) -> Dict[str, Any]:
+        """
+        Get information about the loaded model.
+        
+        Returns:
+            Dictionary with model information
+        """
+        return {
+            'model_id': self.model_id,
+            'device': self.device,
+            'loaded': self.is_model_loaded(),
+            'target_sample_rate': self.audio_validator.target_sample_rate,
+            'supported_languages': ['en', 'fr']  # Kyutai STT supports English and French
+        }
+    
+    def unload_model(self) -> None:
+        """
+        Unload the model to free memory.
+        """
+        if self.model is not None:
+            del self.model
+            self.model = None
+        
+        if self.processor is not None:
+            del self.processor
+            self.processor = None
+        
+        self._model_loaded = False
+        
+        # Force garbage collection
+        import gc
+        gc.collect()
+        
+        # Clear CUDA cache if available
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        
+        logger.info("Speech model unloaded")

digipal/auth/__init__.py

@@ -0,0 +1,19 @@
+"""
+Authentication module for DigiPal application.
+
+This module provides HuggingFace authentication integration with session management
+and offline development support.
+"""
+
+from .auth_manager import AuthManager
+from .session_manager import SessionManager
+from .models import User, AuthSession, AuthResult, AuthStatus
+
+__all__ = [
+    'AuthManager',
+    'SessionManager', 
+    'User',
+    'AuthSession',
+    'AuthResult',
+    'AuthStatus'
+]

digipal/auth/auth_manager.py

@@ -0,0 +1,384 @@
+"""
+HuggingFace authentication manager for DigiPal application.
+"""
+
+import logging
+import requests
+import json
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+from pathlib import Path
+
+from .models import User, AuthSession, AuthResult, AuthStatus
+from .session_manager import SessionManager
+from ..storage.database import DatabaseConnection
+
+logger = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """Manages HuggingFace authentication with offline support."""
+    
+    # HuggingFace API endpoints
+    HF_API_BASE = "https://huggingface.co/api"
+    HF_USER_ENDPOINT = f"{HF_API_BASE}/whoami"
+    
+    def __init__(self, db_connection: DatabaseConnection, offline_mode: bool = False, cache_dir: Optional[str] = None):
+        """
+        Initialize authentication manager.
+        
+        Args:
+            db_connection: Database connection for user storage
+            offline_mode: Enable offline development mode
+            cache_dir: Directory for authentication cache
+        """
+        self.db = db_connection
+        self.offline_mode = offline_mode
+        self.session_manager = SessionManager(db_connection, cache_dir)
+        
+        # Request session for connection pooling
+        self.session = requests.Session()
+        self.session.timeout = 10  # 10 second timeout
+        
+        logger.info(f"AuthManager initialized (offline_mode: {offline_mode})")
+    
+    def authenticate(self, token: str) -> AuthResult:
+        """
+        Authenticate user with HuggingFace token.
+        
+        Args:
+            token: HuggingFace authentication token
+            
+        Returns:
+            Authentication result with user and session info
+        """
+        if self.offline_mode:
+            return self._authenticate_offline(token)
+        
+        try:
+            # Validate token with HuggingFace API
+            user_info = self._validate_hf_token(token)
+            if not user_info:
+                return AuthResult(
+                    status=AuthStatus.INVALID_TOKEN,
+                    error_message="Invalid HuggingFace token"
+                )
+            
+            # Create or update user
+            user = self._create_or_update_user(user_info, token)
+            if not user:
+                return AuthResult(
+                    status=AuthStatus.USER_NOT_FOUND,
+                    error_message="Failed to create or update user"
+                )
+            
+            # Create session
+            session = self.session_manager.create_session(user, token)
+            
+            logger.info(f"Successfully authenticated user: {user.username}")
+            return AuthResult(
+                status=AuthStatus.SUCCESS,
+                user=user,
+                session=session
+            )
+            
+        except requests.exceptions.RequestException as e:
+            logger.warning(f"Network error during authentication: {e}")
+            # Try offline authentication as fallback
+            return self._authenticate_offline(token)
+        
+        except Exception as e:
+            logger.error(f"Authentication error: {e}")
+            return AuthResult(
+                status=AuthStatus.NETWORK_ERROR,
+                error_message=f"Authentication failed: {str(e)}"
+            )
+    
+    def validate_session(self, user_id: str, token: str) -> AuthResult:
+        """
+        Validate existing session.
+        
+        Args:
+            user_id: User ID
+            token: Authentication token
+            
+        Returns:
+            Authentication result
+        """
+        # Check if session exists and is valid
+        if not self.session_manager.validate_session(user_id, token):
+            return AuthResult(
+                status=AuthStatus.EXPIRED_SESSION,
+                error_message="Session expired or invalid"
+            )
+        
+        # Get user and session
+        user = self.get_user(user_id)
+        session = self.session_manager.get_session(user_id)
+        
+        if not user or not session:
+            return AuthResult(
+                status=AuthStatus.USER_NOT_FOUND,
+                error_message="User or session not found"
+            )
+        
+        # Refresh session
+        self.session_manager.refresh_session(user_id)
+        
+        status = AuthStatus.OFFLINE_MODE if session.is_offline else AuthStatus.SUCCESS
+        return AuthResult(
+            status=status,
+            user=user,
+            session=session
+        )
+    
+    def logout(self, user_id: str) -> bool:
+        """
+        Logout user and revoke session.
+        
+        Args:
+            user_id: User ID to logout
+            
+        Returns:
+            True if logout successful
+        """
+        success = self.session_manager.revoke_session(user_id)
+        if success:
+            logger.info(f"User {user_id} logged out successfully")
+        return success
+    
+    def get_user(self, user_id: str) -> Optional[User]:
+        """
+        Get user by ID.
+        
+        Args:
+            user_id: User ID
+            
+        Returns:
+            User object if found
+        """
+        try:
+            rows = self.db.execute_query(
+                'SELECT * FROM users WHERE id = ?',
+                (user_id,)
+            )
+            
+            if rows:
+                row = rows[0]
+                return User(
+                    id=row['id'],
+                    username=row['username'],
+                    created_at=datetime.fromisoformat(row['created_at']) if row['created_at'] else datetime.now(),
+                    last_login=datetime.fromisoformat(row['last_login']) if row['last_login'] else None
+                )
+        except Exception as e:
+            logger.error(f"Error getting user {user_id}: {e}")
+        
+        return None
+    
+    def refresh_user_profile(self, user_id: str) -> Optional[User]:
+        """
+        Refresh user profile from HuggingFace.
+        
+        Args:
+            user_id: User ID
+            
+        Returns:
+            Updated user object
+        """
+        if self.offline_mode:
+            return self.get_user(user_id)
+        
+        try:
+            # Get current session to get token
+            session = self.session_manager.get_session(user_id)
+            if not session or session.is_offline:
+                return self.get_user(user_id)
+            
+            # Fetch updated user info
+            user_info = self._validate_hf_token(session.token)
+            if user_info:
+                user = self._create_or_update_user(user_info, session.token)
+                logger.info(f"Refreshed profile for user: {user_id}")
+                return user
+                
+        except Exception as e:
+            logger.error(f"Error refreshing user profile: {e}")
+        
+        return self.get_user(user_id)
+    
+    def cleanup_expired_sessions(self) -> int:
+        """Clean up expired sessions."""
+        return self.session_manager.cleanup_expired_sessions()
+    
+    def _authenticate_offline(self, token: str) -> AuthResult:
+        """
+        Authenticate in offline mode using cached data.
+        
+        Args:
+            token: Authentication token
+            
+        Returns:
+            Authentication result for offline mode
+        """
+        # In offline mode, we create a development user
+        # This is for development purposes only
+        
+        if not token or len(token) < 10:
+            return AuthResult(
+                status=AuthStatus.INVALID_TOKEN,
+                error_message="Token too short for offline mode"
+            )
+        
+        # Create a deterministic user ID from token
+        import hashlib
+        user_id = f"offline_{hashlib.md5(token.encode()).hexdigest()[:16]}"
+        username = f"dev_user_{user_id[-8:]}"
+        
+        # Check if offline user exists
+        user = self.get_user(user_id)
+        if not user:
+            # Create offline development user
+            user = User(
+                id=user_id,
+                username=username,
+                email=f"{username}@offline.dev",
+                full_name=f"Development User {username}",
+                created_at=datetime.now()
+            )
+            
+            # Save to database
+            try:
+                self.db.execute_update(
+                    '''INSERT OR REPLACE INTO users 
+                       (id, username, huggingface_token, created_at, last_login) 
+                       VALUES (?, ?, ?, ?, ?)''',
+                    (user.id, user.username, token, 
+                     user.created_at.isoformat(), datetime.now().isoformat())
+                )
+            except Exception as e:
+                logger.error(f"Error creating offline user: {e}")
+                return AuthResult(
+                    status=AuthStatus.NETWORK_ERROR,
+                    error_message="Failed to create offline user"
+                )
+        
+        # Create offline session
+        session = self.session_manager.create_session(
+            user, token, expires_hours=168, is_offline=True  # 1 week for offline
+        )
+        
+        logger.info(f"Offline authentication successful for: {username}")
+        return AuthResult(
+            status=AuthStatus.OFFLINE_MODE,
+            user=user,
+            session=session
+        )
+    
+    def _validate_hf_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """
+        Validate token with HuggingFace API.
+        
+        Args:
+            token: HuggingFace token
+            
+        Returns:
+            User info dict if valid, None otherwise
+        """
+        try:
+            headers = {
+                'Authorization': f'Bearer {token}',
+                'User-Agent': 'DigiPal/1.0'
+            }
+            
+            response = self.session.get(self.HF_USER_ENDPOINT, headers=headers)
+            
+            if response.status_code == 200:
+                user_info = response.json()
+                logger.debug(f"HF API response: {user_info}")
+                return user_info
+            elif response.status_code == 401:
+                logger.warning("Invalid HuggingFace token")
+                return None
+            else:
+                logger.error(f"HF API error: {response.status_code} - {response.text}")
+                return None
+                
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Network error validating HF token: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error validating HF token: {e}")
+            return None
+    
+    def _create_or_update_user(self, user_info: Dict[str, Any], token: str) -> Optional[User]:
+        """
+        Create or update user from HuggingFace user info.
+        
+        Args:
+            user_info: User info from HuggingFace API
+            token: Authentication token
+            
+        Returns:
+            User object
+        """
+        try:
+            # Extract user data from HF response
+            user_id = user_info.get('name', user_info.get('id', ''))
+            username = user_info.get('name', user_id)
+            email = user_info.get('email')
+            full_name = user_info.get('fullname', user_info.get('name'))
+            avatar_url = user_info.get('avatarUrl')
+            
+            if not user_id:
+                logger.error("No user ID in HuggingFace response")
+                return None
+            
+            # Check if user exists
+            existing_user = self.get_user(user_id)
+            now = datetime.now()
+            
+            if existing_user:
+                # Update existing user
+                self.db.execute_update(
+                    '''UPDATE users SET 
+                       username = ?, huggingface_token = ?, last_login = ?
+                       WHERE id = ?''',
+                    (username, token, now.isoformat(), user_id)
+                )
+                
+                # Update user object
+                existing_user.username = username
+                existing_user.last_login = now
+                return existing_user
+            else:
+                # Create new user
+                user = User(
+                    id=user_id,
+                    username=username,
+                    email=email,
+                    full_name=full_name,
+                    avatar_url=avatar_url,
+                    created_at=now,
+                    last_login=now
+                )
+                
+                self.db.execute_update(
+                    '''INSERT INTO users 
+                       (id, username, huggingface_token, created_at, last_login) 
+                       VALUES (?, ?, ?, ?, ?)''',
+                    (user.id, user.username, token, 
+                     user.created_at.isoformat(), user.last_login.isoformat())
+                )
+                
+                logger.info(f"Created new user: {username}")
+                return user
+                
+        except Exception as e:
+            logger.error(f"Error creating/updating user: {e}")
+            return None
+    
+    def __del__(self):
+        """Cleanup resources."""
+        if hasattr(self, 'session'):
+            self.session.close()

digipal/auth/models.py

@@ -0,0 +1,134 @@
+"""
+Authentication data models for DigiPal application.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+from enum import Enum
+import json
+
+
+class AuthStatus(Enum):
+    """Authentication status enumeration."""
+    SUCCESS = "success"
+    INVALID_TOKEN = "invalid_token"
+    NETWORK_ERROR = "network_error"
+    OFFLINE_MODE = "offline_mode"
+    EXPIRED_SESSION = "expired_session"
+    USER_NOT_FOUND = "user_not_found"
+
+
+@dataclass
+class User:
+    """User model for authenticated users."""
+    id: str
+    username: str
+    email: Optional[str] = None
+    full_name: Optional[str] = None
+    avatar_url: Optional[str] = None
+    created_at: datetime = field(default_factory=datetime.now)
+    last_login: Optional[datetime] = None
+    is_active: bool = True
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert user to dictionary for storage."""
+        return {
+            'id': self.id,
+            'username': self.username,
+            'email': self.email,
+            'full_name': self.full_name,
+            'avatar_url': self.avatar_url,
+            'created_at': self.created_at.isoformat() if self.created_at else None,
+            'last_login': self.last_login.isoformat() if self.last_login else None,
+            'is_active': self.is_active
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'User':
+        """Create user from dictionary."""
+        return cls(
+            id=data['id'],
+            username=data['username'],
+            email=data.get('email'),
+            full_name=data.get('full_name'),
+            avatar_url=data.get('avatar_url'),
+            created_at=datetime.fromisoformat(data['created_at']) if data.get('created_at') else datetime.now(),
+            last_login=datetime.fromisoformat(data['last_login']) if data.get('last_login') else None,
+            is_active=data.get('is_active', True)
+        )
+
+
+@dataclass
+class AuthSession:
+    """Authentication session model."""
+    user_id: str
+    token: str
+    expires_at: datetime
+    created_at: datetime = field(default_factory=datetime.now)
+    last_accessed: datetime = field(default_factory=datetime.now)
+    is_offline: bool = False
+    session_data: Dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def is_expired(self) -> bool:
+        """Check if session is expired."""
+        return datetime.now() > self.expires_at
+    
+    @property
+    def is_valid(self) -> bool:
+        """Check if session is valid (not expired and has token)."""
+        return not self.is_expired and bool(self.token)
+    
+    def refresh_access(self) -> None:
+        """Update last accessed timestamp."""
+        self.last_accessed = datetime.now()
+    
+    def extend_session(self, hours: int = 24) -> None:
+        """Extend session expiration."""
+        self.expires_at = datetime.now() + timedelta(hours=hours)
+        self.refresh_access()
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert session to dictionary for storage."""
+        return {
+            'user_id': self.user_id,
+            'token': self.token,
+            'expires_at': self.expires_at.isoformat(),
+            'created_at': self.created_at.isoformat(),
+            'last_accessed': self.last_accessed.isoformat(),
+            'is_offline': self.is_offline,
+            'session_data': json.dumps(self.session_data)
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'AuthSession':
+        """Create session from dictionary."""
+        return cls(
+            user_id=data['user_id'],
+            token=data['token'],
+            expires_at=datetime.fromisoformat(data['expires_at']),
+            created_at=datetime.fromisoformat(data['created_at']),
+            last_accessed=datetime.fromisoformat(data['last_accessed']),
+            is_offline=data.get('is_offline', False),
+            session_data=json.loads(data.get('session_data', '{}'))
+        )
+
+
+@dataclass
+class AuthResult:
+    """Result of authentication operation."""
+    status: AuthStatus
+    user: Optional[User] = None
+    session: Optional[AuthSession] = None
+    error_message: Optional[str] = None
+    
+    @property
+    def is_success(self) -> bool:
+        """Check if authentication was successful."""
+        return self.status == AuthStatus.SUCCESS
+    
+    @property
+    def is_offline(self) -> bool:
+        """Check if authentication is in offline mode."""
+        return self.status == AuthStatus.OFFLINE_MODE

digipal/auth/session_manager.py

@@ -0,0 +1,370 @@
+"""
+Session management for DigiPal authentication system.
+"""
+
+import logging
+import json
+import hashlib
+import secrets
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+from pathlib import Path
+
+from .models import User, AuthSession, AuthStatus
+from ..storage.database import DatabaseConnection
+
+logger = logging.getLogger(__name__)
+
+
+class SessionManager:
+    """Manages user sessions with secure token storage and caching."""
+    
+    def __init__(self, db_connection: DatabaseConnection, cache_dir: Optional[str] = None):
+        """
+        Initialize session manager.
+        
+        Args:
+            db_connection: Database connection for persistent storage
+            cache_dir: Directory for session cache files (optional)
+        """
+        self.db = db_connection
+        self.cache_dir = Path(cache_dir) if cache_dir else Path.home() / '.digipal' / 'cache'
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # In-memory session cache for performance
+        self._session_cache: Dict[str, AuthSession] = {}
+        
+        # Load existing sessions from database
+        self._load_sessions_from_db()
+    
+    def create_session(self, user: User, token: str, expires_hours: int = 24, is_offline: bool = False) -> AuthSession:
+        """
+        Create a new authentication session.
+        
+        Args:
+            user: Authenticated user
+            token: Authentication token
+            expires_hours: Session expiration in hours
+            is_offline: Whether this is an offline session
+            
+        Returns:
+            Created authentication session
+        """
+        expires_at = datetime.now() + timedelta(hours=expires_hours)
+        
+        session = AuthSession(
+            user_id=user.id,
+            token=token,
+            expires_at=expires_at,
+            is_offline=is_offline
+        )
+        
+        # Ensure user exists in database before saving session
+        self._ensure_user_exists(user)
+        
+        # Store in database
+        self._save_session_to_db(session)
+        
+        # Cache in memory
+        self._session_cache[user.id] = session
+        
+        # Save to file cache for offline access
+        if not is_offline:
+            self._save_session_to_cache(session)
+        
+        logger.info(f"Created session for user {user.id} (offline: {is_offline})")
+        return session
+    
+    def get_session(self, user_id: str) -> Optional[AuthSession]:
+        """
+        Get session for user ID.
+        
+        Args:
+            user_id: User ID to get session for
+            
+        Returns:
+            Authentication session if found and valid, None otherwise
+        """
+        # Check memory cache first
+        if user_id in self._session_cache:
+            session = self._session_cache[user_id]
+            if session.is_valid:
+                session.refresh_access()
+                return session
+            else:
+                # Remove expired session
+                del self._session_cache[user_id]
+                self._remove_session_from_db(user_id)
+        
+        # Try to load from database
+        session = self._load_session_from_db(user_id)
+        if session and session.is_valid:
+            self._session_cache[user_id] = session
+            session.refresh_access()
+            return session
+        
+        # Try to load from cache for offline mode
+        cached_session = self._load_session_from_cache(user_id)
+        if cached_session:
+            # Mark as offline session
+            cached_session.is_offline = True
+            cached_session.extend_session(hours=168)  # 1 week for offline
+            self._session_cache[user_id] = cached_session
+            return cached_session
+        
+        return None
+    
+    def validate_session(self, user_id: str, token: str) -> bool:
+        """
+        Validate session token for user.
+        
+        Args:
+            user_id: User ID
+            token: Token to validate
+            
+        Returns:
+            True if session is valid, False otherwise
+        """
+        session = self.get_session(user_id)
+        if not session:
+            return False
+        
+        # For offline sessions, we're more lenient with token validation
+        if session.is_offline:
+            return self._hash_token(token) == self._hash_token(session.token)
+        
+        return session.token == token and session.is_valid
+    
+    def refresh_session(self, user_id: str, extend_hours: int = 24) -> bool:
+        """
+        Refresh session expiration.
+        
+        Args:
+            user_id: User ID
+            extend_hours: Hours to extend session
+            
+        Returns:
+            True if session was refreshed, False otherwise
+        """
+        session = self.get_session(user_id)
+        if not session:
+            return False
+        
+        session.extend_session(extend_hours)
+        self._save_session_to_db(session)
+        
+        if not session.is_offline:
+            self._save_session_to_cache(session)
+        
+        logger.info(f"Refreshed session for user {user_id}")
+        return True
+    
+    def revoke_session(self, user_id: str) -> bool:
+        """
+        Revoke user session.
+        
+        Args:
+            user_id: User ID
+            
+        Returns:
+            True if session was revoked, False if not found
+        """
+        # Remove from memory cache
+        if user_id in self._session_cache:
+            del self._session_cache[user_id]
+        
+        # Remove from database
+        removed_from_db = self._remove_session_from_db(user_id)
+        
+        # Remove from file cache
+        self._remove_session_from_cache(user_id)
+        
+        if removed_from_db:
+            logger.info(f"Revoked session for user {user_id}")
+        
+        return removed_from_db
+    
+    def cleanup_expired_sessions(self) -> int:
+        """
+        Clean up expired sessions from storage.
+        
+        Returns:
+            Number of sessions cleaned up
+        """
+        cleaned_count = 0
+        
+        # Clean memory cache
+        expired_users = [
+            user_id for user_id, session in self._session_cache.items()
+            if session.is_expired
+        ]
+        
+        for user_id in expired_users:
+            del self._session_cache[user_id]
+            cleaned_count += 1
+        
+        # Clean database
+        try:
+            db_cleaned = self.db.execute_update(
+                'DELETE FROM users WHERE session_data IS NOT NULL AND '
+                'json_extract(session_data, "$.expires_at") < ?',
+                (datetime.now().isoformat(),)
+            )
+            cleaned_count += db_cleaned
+        except Exception as e:
+            logger.error(f"Error cleaning expired sessions from database: {e}")
+        
+        if cleaned_count > 0:
+            logger.info(f"Cleaned up {cleaned_count} expired sessions")
+        
+        return cleaned_count
+    
+    def _save_session_to_db(self, session: AuthSession) -> None:
+        """Save session to database."""
+        try:
+            session_json = json.dumps(session.to_dict())
+            self.db.execute_update(
+                '''UPDATE users SET session_data = ?, last_login = ? 
+                   WHERE id = ?''',
+                (session_json, session.last_accessed.isoformat(), session.user_id)
+            )
+        except Exception as e:
+            logger.error(f"Error saving session to database: {e}")
+    
+    def _load_session_from_db(self, user_id: str) -> Optional[AuthSession]:
+        """Load session from database."""
+        try:
+            rows = self.db.execute_query(
+                'SELECT session_data FROM users WHERE id = ? AND session_data IS NOT NULL',
+                (user_id,)
+            )
+            
+            if rows:
+                session_data = json.loads(rows[0]['session_data'])
+                return AuthSession.from_dict(session_data)
+        except Exception as e:
+            logger.error(f"Error loading session from database: {e}")
+        
+        return None
+    
+    def _remove_session_from_db(self, user_id: str) -> bool:
+        """Remove session from database."""
+        try:
+            # First check if user exists
+            rows = self.db.execute_query('SELECT id FROM users WHERE id = ?', (user_id,))
+            if not rows:
+                return False
+            
+            affected = self.db.execute_update(
+                'UPDATE users SET session_data = NULL WHERE id = ?',
+                (user_id,)
+            )
+            return affected > 0
+        except Exception as e:
+            logger.error(f"Error removing session from database: {e}")
+            return False
+    
+    def _save_session_to_cache(self, session: AuthSession) -> None:
+        """Save session to file cache for offline access."""
+        try:
+            cache_file = self.cache_dir / f"session_{self._hash_user_id(session.user_id)}.json"
+            
+            # Only cache essential session data for offline use
+            cache_data = {
+                'user_id': session.user_id,
+                'token_hash': self._hash_token(session.token),
+                'expires_at': session.expires_at.isoformat(),
+                'created_at': session.created_at.isoformat(),
+                'cached_at': datetime.now().isoformat()
+            }
+            
+            with open(cache_file, 'w') as f:
+                json.dump(cache_data, f)
+                
+        except Exception as e:
+            logger.error(f"Error saving session to cache: {e}")
+    
+    def _load_session_from_cache(self, user_id: str) -> Optional[AuthSession]:
+        """Load session from file cache."""
+        try:
+            cache_file = self.cache_dir / f"session_{self._hash_user_id(user_id)}.json"
+            
+            if not cache_file.exists():
+                return None
+            
+            with open(cache_file, 'r') as f:
+                cache_data = json.load(f)
+            
+            # Check if cache is not too old (max 1 week)
+            cached_at = datetime.fromisoformat(cache_data['cached_at'])
+            if datetime.now() - cached_at > timedelta(days=7):
+                cache_file.unlink()  # Remove old cache
+                return None
+            
+            # Create session from cache (token will be validated separately)
+            return AuthSession(
+                user_id=cache_data['user_id'],
+                token=cache_data['token_hash'],  # This is hashed, will need special handling
+                expires_at=datetime.fromisoformat(cache_data['expires_at']),
+                created_at=datetime.fromisoformat(cache_data['created_at']),
+                is_offline=True
+            )
+            
+        except Exception as e:
+            logger.error(f"Error loading session from cache: {e}")
+            return None
+    
+    def _remove_session_from_cache(self, user_id: str) -> None:
+        """Remove session from file cache."""
+        try:
+            cache_file = self.cache_dir / f"session_{self._hash_user_id(user_id)}.json"
+            if cache_file.exists():
+                cache_file.unlink()
+        except Exception as e:
+            logger.error(f"Error removing session from cache: {e}")
+    
+    def _load_sessions_from_db(self) -> None:
+        """Load all valid sessions from database into memory cache."""
+        try:
+            rows = self.db.execute_query(
+                'SELECT id, session_data FROM users WHERE session_data IS NOT NULL'
+            )
+            
+            for row in rows:
+                try:
+                    session_data = json.loads(row['session_data'])
+                    session = AuthSession.from_dict(session_data)
+                    
+                    if session.is_valid:
+                        self._session_cache[row['id']] = session
+                except Exception as e:
+                    logger.warning(f"Error loading session for user {row['id']}: {e}")
+                    
+        except Exception as e:
+            logger.error(f"Error loading sessions from database: {e}")
+    
+    def _hash_token(self, token: str) -> str:
+        """Hash token for secure storage."""
+        return hashlib.sha256(token.encode()).hexdigest()
+    
+    def _hash_user_id(self, user_id: str) -> str:
+        """Hash user ID for cache file naming."""
+        return hashlib.md5(user_id.encode()).hexdigest()[:16]
+    
+    def _ensure_user_exists(self, user: User) -> None:
+        """Ensure user exists in database before creating session."""
+        try:
+            # Check if user exists
+            rows = self.db.execute_query('SELECT id FROM users WHERE id = ?', (user.id,))
+            if not rows:
+                # Create user record
+                self.db.execute_update(
+                    '''INSERT INTO users (id, username, created_at, last_login) 
+                       VALUES (?, ?, ?, ?)''',
+                    (user.id, user.username, 
+                     user.created_at.isoformat() if user.created_at else datetime.now().isoformat(),
+                     user.last_login.isoformat() if user.last_login else None)
+                )
+                logger.info(f"Created user record for session: {user.id}")
+        except Exception as e:
+            logger.error(f"Error ensuring user exists: {e}")

digipal/core/__init__.py

@@ -0,0 +1,22 @@
+"""
+Core DigiPal functionality including data models and business logic.
+"""
+
+from .models import DigiPal, Interaction, Command, CareAction, AttributeModifier
+from .enums import *
+from .attribute_engine import AttributeEngine
+
+__all__ = [
+    'DigiPal',
+    'Interaction',
+    'Command',
+    'CareAction',
+    'AttributeModifier',
+    'AttributeEngine',
+    'EggType', 
+    'LifeStage',
+    'CareActionType',
+    'AttributeType',
+    'CommandType',
+    'InteractionResult'
+]