Initial commit: Research AI Assistant API

.gitignore

@@ -0,0 +1,92 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment variables
+.env
+.env.local
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+sessions.db
+embeddings.faiss
+embeddings.faiss.index
+
+# Logs
+*.log
+logs/
+*.log.*
+
+# Cache
+.cache/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+
+# Model cache (optional - uncomment if you don't want to commit model cache)
+# models/
+# .huggingface/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# OS files
+Thumbs.db
+desktop.ini
+
+# Jupyter Notebooks
+.ipynb_checkpoints/
+
+# Distribution / packaging
+*.zip
+*.tar.gz
+*.rar
+
+# Testing
+.coverage
+htmlcov/
+.tox/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+

Dockerfile

@@ -0,0 +1,42 @@
+# Dockerfile for Hugging Face Spaces
+# Based on HF Spaces Docker SDK documentation: https://huggingface.co/docs/hub/spaces-sdks-docker
+
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    cmake \
+    libopenblas-dev \
+    libomp-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements file first (for better caching)
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port 7860 (HF Spaces standard)
+EXPOSE 7860
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=120s --retries=3 \
+    CMD curl -f http://localhost:7860/api/health || exit 1
+
+# Run Flask application on port 7860
+CMD ["python", "flask_api_standalone.py"]
+

Dockerfile.flask

@@ -0,0 +1,39 @@
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    cmake \
+    libopenblas-dev \
+    libomp-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements file
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port 7860 (HF Spaces standard)
+EXPOSE 7860
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=120s --retries=3 \
+    CMD curl -f http://localhost:7860/api/health || exit 1
+
+# Run Flask application
+# Note: For Flask-only deployment, use this Dockerfile with README_FLASK_API.md
+CMD ["python", "flask_api_standalone.py"]
+

README.md

@@ -0,0 +1,395 @@
+---
+title: AI Research Assistant MVP
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+tags:
+- ai
+- chatbot
+- research
+- education
+- transformers
+models:
+- mistralai/Mistral-7B-Instruct-v0.2
+- sentence-transformers/all-MiniLM-L6-v2
+- cardiffnlp/twitter-roberta-base-emotion
+- unitary/unbiased-toxic-roberta
+datasets:
+- wikipedia
+- commoncrawl
+base_path: research-assistant
+hf_oauth: true
+hf_token: true
+disable_embedding: false
+duplicated_from: null
+extra_gated_prompt: null
+extra_gated_fields: {}
+gated: false
+public: true
+---
+
+# AI Research Assistant - MVP
+
+<div align="center">
+
+![HF Spaces](https://img.shields.io/badge/🤗-Hugging%20Face%20Spaces-blue)
+![Python](https://img.shields.io/badge/Python-3.9%2B-green)
+![Gradio](https://img.shields.io/badge/Interface-Gradio-FF6B6B)
+![NVIDIA T4](https://img.shields.io/badge/GPU-NVIDIA%20T4-blue)
+
+**Academic-grade AI assistant with transparent reasoning and mobile-optimized interface**
+
+[![Demo](https://img.shields.io/badge/🚀-Live%20Demo-9cf)](https://huggingface.co/spaces/your-username/research-assistant)
+[![Documentation](https://img.shields.io/badge/📚-Documentation-blue)](https://github.com/your-org/research-assistant/wiki)
+
+</div>
+
+## 🎯 Overview
+
+This MVP demonstrates an intelligent research assistant framework featuring **transparent reasoning chains**, **specialized agent architecture**, and **mobile-first design**. Built for Hugging Face Spaces with NVIDIA T4 GPU acceleration for local model inference.
+
+### Key Differentiators
+- **🔍 Transparent Reasoning**: Watch the AI think step-by-step with Chain of Thought
+- **🧠 Specialized Agents**: Multiple AI models working together for optimal performance  
+- **📱 Mobile-First**: Optimized for seamless mobile web experience
+- **🎓 Academic Focus**: Designed for research and educational use cases
+
+## 🚀 Quick Start
+
+### Option 1: Use Our Demo
+Visit our live demo on Hugging Face Spaces:
+```bash
+https://huggingface.co/spaces/your-username/research-assistant
+```
+
+### Option 2: Deploy Your Own Instance
+
+#### Prerequisites
+- Hugging Face account with [write token](https://huggingface.co/settings/tokens)
+- Basic understanding of Hugging Face Spaces
+
+#### Deployment Steps
+
+1. **Fork this space** using the Hugging Face UI
+2. **Add your HF token** in Space Settings:
+   - Go to your Space → Settings → Repository secrets
+   - Add `HF_TOKEN` with your Hugging Face token
+3. **The space will auto-build** (takes 5-10 minutes)
+
+#### Manual Build (Advanced)
+
+```bash
+# Clone the repository
+git clone https://huggingface.co/spaces/your-username/research-assistant
+cd research-assistant
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment
+export HF_TOKEN="your_hugging_face_token_here"
+
+# Launch the application (multiple options)
+python main.py          # Full integration with error handling
+python launch.py        # Simple launcher
+python app.py           # UI-only mode
+```
+
+## 📁 Integration Structure
+
+The MVP now includes complete integration files for deployment:
+
+```
+├── main.py                    # 🎯 Main integration entry point
+├── launch.py                  # 🚀 Simple launcher for HF Spaces
+├── app.py                     # 📱 Mobile-optimized UI
+├── requirements.txt           # 📦 Dependencies
+└── src/
+    ├── __init__.py           # 📦 Package initialization
+    ├── database.py           # 🗄️ SQLite database management
+    ├── event_handlers.py     # 🔗 UI event integration
+    ├── config.py             # ⚙️ Configuration
+    ├── llm_router.py         # 🤖 LLM routing
+    ├── orchestrator_engine.py # 🎭 Request orchestration
+    ├── context_manager.py    # 🧠 Context management
+    ├── mobile_handlers.py    # 📱 Mobile UX handlers
+    └── agents/
+        ├── __init__.py       # 🤖 Agents package
+        ├── intent_agent.py   # 🎯 Intent recognition
+        ├── synthesis_agent.py # ✨ Response synthesis
+        └── safety_agent.py   # 🛡️ Safety checking
+```
+
+### Key Features:
+- **🔄 Graceful Degradation**: Falls back to mock mode if components fail
+- **📱 Mobile-First**: Optimized for mobile devices and small screens
+- **🗄️ Database Ready**: SQLite integration with session management
+- **🔗 Event Handling**: Complete UI-to-backend integration
+- **⚡ Error Recovery**: Robust error handling throughout
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Mobile Web    │ ── │   ORCHESTRATOR   │ ── │   AGENT SWARM   │
+│   Interface     │    │   (Core Engine)  │    │   (5 Specialists)│
+└─────────────────┘    └���─────────────────┘    └─────────────────┘
+         │                        │                        │
+         └─────────────────────────┼────────────────────────┘
+                                   │
+                    ┌─────────────────────────────┐
+                    │   PERSISTENCE LAYER         │
+                    │   (SQLite + FAISS Lite)    │
+                    └─────────────────────────────┘
+```
+
+### Core Components
+
+| Component | Purpose | Technology |
+|-----------|---------|------------|
+| **Orchestrator** | Main coordination engine | Python + Async |
+| **Intent Recognition** | Understand user goals | RoBERTa-base + CoT |
+| **Context Manager** | Session memory & recall | FAISS + SQLite |
+| **Response Synthesis** | Generate final answers | Mistral-7B |
+| **Safety Checker** | Content moderation | Unbiased-Toxic-RoBERTa |
+| **Research Agent** | Information gathering | Web search + analysis |
+
+## 💡 Usage Examples
+
+### Basic Research Query
+```
+User: "Explain quantum entanglement in simple terms"
+
+Assistant: 
+1. 🤔 [Reasoning] Breaking down quantum physics concepts...
+2. 🔍 [Research] Gathering latest explanations...
+3. ✍️ [Synthesis] Creating simplified explanation...
+
+[Final Response]: Quantum entanglement is when two particles become linked...
+```
+
+### Technical Analysis
+```
+User: "Compare transformer models for text classification"
+
+Assistant:
+1. 🏷️ [Intent] Identifying technical comparison request
+2. 📊 [Analysis] Evaluating BERT vs RoBERTa vs DistilBERT
+3. 📈 [Synthesis] Creating comparison table with metrics...
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```python
+# Required
+HF_TOKEN="your_hugging_face_token"
+
+# Optional
+MAX_WORKERS=2
+CACHE_TTL=3600
+DEFAULT_MODEL="mistralai/Mistral-7B-Instruct-v0.2"
+```
+
+### Model Configuration
+
+The system uses multiple specialized models:
+
+| Task | Model | Purpose |
+|------|-------|---------|
+| Primary Reasoning | `mistralai/Mistral-7B-Instruct-v0.2` | General responses |
+| Embeddings | `sentence-transformers/all-MiniLM-L6-v2` | Semantic search |
+| Intent Classification | `cardiffnlp/twitter-roberta-base-emotion` | User goal detection |
+| Safety Checking | `unitary/unbiased-toxic-roberta` | Content moderation |
+
+## 📱 Mobile Optimization
+
+### Key Mobile Features
+- **Touch-friendly** interface (44px+ touch targets)
+- **Progressive Web App** capabilities
+- **Offline functionality** for cached sessions
+- **Reduced data usage** with optimized responses
+- **Keyboard-aware** layout adjustments
+
+### Supported Devices
+- ✅ Smartphones (iOS/Android)
+- ✅ Tablets
+- ✅ Desktop browsers
+- ✅ Screen readers (accessibility)
+
+## 🛠️ Development
+
+### Project Structure
+```
+research-assistant/
+├── app.py                 # Main Gradio application
+├── requirements.txt       # Dependencies
+├── Dockerfile            # Container configuration
+├── src/
+│   ├── orchestrator.py   # Core orchestration engine
+│   ├── agents/          # Specialized agent modules
+│   ├── llm_router.py    # Multi-model routing
+│   └── mobile_ux.py     # Mobile optimizations
+├── tests/               # Test suites
+└── docs/               # Documentation
+```
+
+### Adding New Agents
+
+1. Create agent module in `src/agents/`
+2. Implement agent protocol:
+```python
+class YourNewAgent:
+    async def execute(self, user_input: str, context: dict) -> dict:
+        # Your agent logic here
+        return {
+            "result": processed_output,
+            "confidence": 0.95,
+            "metadata": {}
+        }
+```
+
+3. Register agent in orchestrator configuration
+
+## 🧪 Testing
+
+### Run Test Suite
+```bash
+# Install test dependencies
+pip install -r requirements.txt
+
+# Run all tests
+pytest tests/ -v
+
+# Run specific test categories
+pytest tests/test_agents.py -v
+pytest tests/test_mobile_ux.py -v
+```
+
+### Test Coverage
+- ✅ Agent functionality
+- ✅ Mobile UX components  
+- ✅ LLM routing logic
+- ✅ Error handling
+- ✅ Performance benchmarks
+
+## 🚨 Troubleshooting
+
+### Common Build Issues
+
+| Issue | Solution |
+|-------|----------|
+| **HF_TOKEN not found** | Add token in Space Settings → Secrets |
+| **Build timeout** | Reduce model sizes in requirements |
+| **Memory errors** | Check GPU memory usage, optimize model loading |
+| **Import errors** | Check Python version (3.9+) |
+
+### Performance Optimization
+
+1. **Enable caching** in context manager
+2. **Use smaller models** for initial deployment
+3. **Implement lazy loading** for mobile users
+4. **Monitor memory usage** with built-in tools
+
+### Debug Mode
+
+Enable detailed logging:
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## 📊 Performance Metrics
+
+| Metric | Target | Current |
+|--------|---------|---------|
+| Response Time | <10s | ~7s |
+| Cache Hit Rate | >60% | ~65% |
+| Mobile UX Score | >80/100 | 85/100 |
+| Error Rate | <5% | ~3% |
+
+## 🔮 Roadmap
+
+### Phase 1 (Current - MVP)
+- ✅ Basic agent orchestration
+- ✅ Mobile-optimized interface  
+- ✅ Multi-model routing
+- ✅ Transparent reasoning display
+
+### Phase 2 (Next 3 months)
+- 🚧 Advanced research capabilities
+- 🚧 Plugin system for tools
+- 🚧 Enhanced mobile PWA features
+- 🚧 Multi-language support
+
+### Phase 3 (Future)
+- 🔮 Autonomous agent swarms
+- 🔮 Voice interface integration
+- 🔮 Enterprise features
+- 🔮 Advanced analytics
+
+## 👥 Contributing
+
+We welcome contributions! Please see:
+
+1. [Contributing Guidelines](docs/CONTRIBUTING.md)
+2. [Code of Conduct](docs/CODE_OF_CONDUCT.md)
+3. [Development Setup](docs/DEVELOPMENT.md)
+
+### Quick Contribution Steps
+```bash
+# 1. Fork the repository
+# 2. Create feature branch
+git checkout -b feature/amazing-feature
+
+# 3. Commit changes
+git commit -m "Add amazing feature"
+
+# 4. Push to branch  
+git push origin feature/amazing-feature
+
+# 5. Open Pull Request
+```
+
+## 📄 Citation
+
+If you use this framework in your research, please cite:
+
+```bibtex
+@software{research_assistant_mvp,
+  title = {AI Research Assistant - MVP},
+  author = {Your Name},
+  year = {2024},
+  url = {https://huggingface.co/spaces/your-username/research-assistant}
+}
+```
+
+## 📜 License
+
+This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Hugging Face](https://huggingface.co) for the infrastructure
+- [Gradio](https://gradio.app) for the web framework
+- Model contributors from the HF community
+- Early testers and feedback providers
+
+---
+
+<div align="center">
+
+**Need help?** 
+- [Open an Issue](https://github.com/your-org/research-assistant/issues)
+- [Join our Discord](https://discord.gg/your-discord)
+- [Email Support](mailto:support@your-domain.com)
+
+*Built with ❤️ for the research community*
+
+</div>
+

config.py

@@ -0,0 +1,63 @@
+# config.py
+import os
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # HF Spaces specific settings
+    hf_token: str = os.getenv("HF_TOKEN", "")
+    hf_cache_dir: str = os.getenv("HF_HOME", "/tmp/huggingface")
+    
+    # Model settings
+    default_model: str = "mistralai/Mistral-7B-Instruct-v0.2"
+    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    classification_model: str = "cardiffnlp/twitter-roberta-base-emotion"
+    
+    # Performance settings
+    max_workers: int = int(os.getenv("MAX_WORKERS", "4"))
+    cache_ttl: int = int(os.getenv("CACHE_TTL", "3600"))
+    
+    # Database settings
+    db_path: str = os.getenv("DB_PATH", "sessions.db")
+    faiss_index_path: str = os.getenv("FAISS_INDEX_PATH", "embeddings.faiss")
+    
+    # Session settings
+    session_timeout: int = int(os.getenv("SESSION_TIMEOUT", "3600"))
+    max_session_size_mb: int = int(os.getenv("MAX_SESSION_SIZE_MB", "10"))
+    
+    # Mobile optimization settings
+    mobile_max_tokens: int = int(os.getenv("MOBILE_MAX_TOKENS", "800"))
+    mobile_timeout: int = int(os.getenv("MOBILE_TIMEOUT", "15000"))
+    
+    # Gradio settings
+    gradio_port: int = int(os.getenv("GRADIO_PORT", "7860"))
+    gradio_host: str = os.getenv("GRADIO_HOST", "0.0.0.0")
+    
+    # Logging settings
+    log_level: str = os.getenv("LOG_LEVEL", "INFO")
+    log_format: str = os.getenv("LOG_FORMAT", "json")
+    
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+
+# Context configuration
+CONTEXT_CONFIG = {
+    'max_context_tokens': int(os.getenv("MAX_CONTEXT_TOKENS", "4000")),
+    'cache_ttl_seconds': int(os.getenv("CACHE_TTL_SECONDS", "300")),
+    'max_cache_size': int(os.getenv("MAX_CACHE_SIZE", "100")),
+    'parallel_processing': os.getenv("PARALLEL_PROCESSING", "True").lower() == "true",
+    'context_decay_factor': float(os.getenv("CONTEXT_DECAY_FACTOR", "0.8")),
+    'max_interactions_to_keep': int(os.getenv("MAX_INTERACTIONS_TO_KEEP", "10")),
+    'enable_metrics': os.getenv("ENABLE_METRICS", "True").lower() == "true",
+    'compression_enabled': os.getenv("COMPRESSION_ENABLED", "True").lower() == "true",
+    'summarization_threshold': int(os.getenv("SUMMARIZATION_THRESHOLD", "2000"))  # tokens
+}
+
+# Model selection for context operations
+CONTEXT_MODELS = {
+    'summarization': os.getenv("CONTEXT_SUMMARIZATION_MODEL", "Qwen/Qwen2.5-7B-Instruct"),
+    'intent': os.getenv("CONTEXT_INTENT_MODEL", "Qwen/Qwen2.5-7B-Instruct"),
+    'synthesis': os.getenv("CONTEXT_SYNTHESIS_MODEL", "Qwen/Qwen2.5-72B-Instruct")
+}
+

flask_api_standalone.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""
+Pure Flask API for Hugging Face Spaces
+No Gradio - Just Flask REST API
+Uses local GPU models for inference
+"""
+
+from flask import Flask, request, jsonify
+from flask_cors import CORS
+import logging
+import sys
+import os
+import asyncio
+from pathlib import Path
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Add project root to path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Create Flask app
+app = Flask(__name__)
+CORS(app)  # Enable CORS for all origins
+
+# Global orchestrator
+orchestrator = None
+orchestrator_available = False
+
+def initialize_orchestrator():
+    """Initialize the AI orchestrator with local GPU models"""
+    global orchestrator, orchestrator_available
+    
+    try:
+        logger.info("=" * 60)
+        logger.info("INITIALIZING AI ORCHESTRATOR (Local GPU Models)")
+        logger.info("=" * 60)
+        
+        from src.agents.intent_agent import create_intent_agent
+        from src.agents.synthesis_agent import create_synthesis_agent
+        from src.agents.safety_agent import create_safety_agent
+        from src.agents.skills_identification_agent import create_skills_identification_agent
+        from src.llm_router import LLMRouter
+        from src.orchestrator_engine import MVPOrchestrator
+        from src.context_manager import EfficientContextManager
+        
+        logger.info("✓ Imports successful")
+        
+        hf_token = os.getenv('HF_TOKEN', '')
+        if not hf_token:
+            logger.warning("HF_TOKEN not set - API fallback will be used if local models fail")
+        
+        # Initialize LLM Router with local model loading enabled
+        logger.info("Initializing LLM Router with local GPU model loading...")
+        llm_router = LLMRouter(hf_token, use_local_models=True)
+        
+        logger.info("Initializing Agents...")
+        agents = {
+            'intent_recognition': create_intent_agent(llm_router),
+            'response_synthesis': create_synthesis_agent(llm_router),
+            'safety_check': create_safety_agent(llm_router),
+            'skills_identification': create_skills_identification_agent(llm_router)
+        }
+        
+        logger.info("Initializing Context Manager...")
+        context_manager = EfficientContextManager(llm_router=llm_router)
+        
+        logger.info("Initializing Orchestrator...")
+        orchestrator = MVPOrchestrator(llm_router, context_manager, agents)
+        
+        orchestrator_available = True
+        logger.info("=" * 60)
+        logger.info("✓ AI ORCHESTRATOR READY")
+        logger.info("  - Local GPU models enabled")
+        logger.info("  - MAX_WORKERS: 4")
+        logger.info("=" * 60)
+        
+        return True
+        
+    except Exception as e:
+        logger.error(f"Failed to initialize: {e}", exc_info=True)
+        orchestrator_available = False
+        return False
+
+# Root endpoint
+@app.route('/', methods=['GET'])
+def root():
+    """API information"""
+    return jsonify({
+        'name': 'AI Assistant Flask API',
+        'version': '1.0',
+        'status': 'running',
+        'orchestrator_ready': orchestrator_available,
+        'features': {
+            'local_gpu_models': True,
+            'max_workers': 4,
+            'hardware': 'NVIDIA T4 Medium'
+        },
+        'endpoints': {
+            'health': 'GET /api/health',
+            'chat': 'POST /api/chat',
+            'initialize': 'POST /api/initialize'
+        }
+    })
+
+# Health check
+@app.route('/api/health', methods=['GET'])
+def health_check():
+    """Health check endpoint"""
+    return jsonify({
+        'status': 'healthy' if orchestrator_available else 'initializing',
+        'orchestrator_ready': orchestrator_available
+    })
+
+# Chat endpoint
+@app.route('/api/chat', methods=['POST'])
+def chat():
+    """
+    Process chat message
+    
+    POST /api/chat
+    {
+        "message": "user message",
+        "history": [[user, assistant], ...],
+        "session_id": "session-123",
+        "user_id": "user-456"
+    }
+    
+    Returns:
+    {
+        "success": true,
+        "message": "AI response",
+        "history": [...],
+        "reasoning": {...},
+        "performance": {...}
+    }
+    """
+    try:
+        data = request.get_json()
+        
+        if not data or 'message' not in data:
+            return jsonify({
+                'success': False,
+                'error': 'Message is required'
+            }), 400
+        
+        message = data['message']
+        history = data.get('history', [])
+        session_id = data.get('session_id')
+        user_id = data.get('user_id', 'anonymous')
+        
+        logger.info(f"Chat request - User: {user_id}, Session: {session_id}")
+        logger.info(f"Message: {message[:100]}...")
+        
+        if not orchestrator_available or orchestrator is None:
+            return jsonify({
+                'success': False,
+                'error': 'Orchestrator not ready',
+                'message': 'AI system is initializing. Please try again in a moment.'
+            }), 503
+        
+        # Process with orchestrator (async method)
+        # Set user_id for session tracking
+        if session_id:
+            orchestrator.set_user_id(session_id, user_id)
+        
+        # Run async process_request in event loop
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            result = loop.run_until_complete(
+                orchestrator.process_request(
+                    session_id=session_id or f"session-{user_id}",
+                    user_input=message
+                )
+            )
+        finally:
+            loop.close()
+        
+        # Extract response
+        if isinstance(result, dict):
+            response_text = result.get('response', '')
+            reasoning = result.get('reasoning', {})
+            performance = result.get('performance', {})
+        else:
+            response_text = str(result)
+            reasoning = {}
+            performance = {}
+        
+        updated_history = history + [[message, response_text]]
+        
+        logger.info(f"✓ Response generated (length: {len(response_text)})")
+        
+        return jsonify({
+            'success': True,
+            'message': response_text,
+            'history': updated_history,
+            'reasoning': reasoning,
+            'performance': performance
+        })
+        
+    except Exception as e:
+        logger.error(f"Chat error: {e}", exc_info=True)
+        return jsonify({
+            'success': False,
+            'error': str(e),
+            'message': 'Error processing your request. Please try again.'
+        }), 500
+
+# Manual initialization endpoint
+@app.route('/api/initialize', methods=['POST'])
+def initialize():
+    """Manually trigger initialization"""
+    success = initialize_orchestrator()
+    
+    if success:
+        return jsonify({
+            'success': True,
+            'message': 'Orchestrator initialized successfully'
+        })
+    else:
+        return jsonify({
+            'success': False,
+            'message': 'Initialization failed. Check logs for details.'
+        }), 500
+
+# Initialize on startup
+if __name__ == '__main__':
+    logger.info("=" * 60)
+    logger.info("STARTING PURE FLASK API")
+    logger.info("=" * 60)
+    
+    # Initialize orchestrator
+    initialize_orchestrator()
+    
+    port = int(os.getenv('PORT', 7860))
+    
+    logger.info(f"Starting Flask on port {port}")
+    logger.info("Endpoints available:")
+    logger.info("  GET  /")
+    logger.info("  GET  /api/health")
+    logger.info("  POST /api/chat")
+    logger.info("  POST /api/initialize")
+    logger.info("=" * 60)
+    
+    app.run(
+        host='0.0.0.0',
+        port=port,
+        debug=False,
+        threaded=True  # Enable threading for concurrent requests
+    )
+

requirements.txt

@@ -0,0 +1,89 @@
+# requirements.txt for Hugging Face Spaces with NVIDIA T4 GPU
+# Core Framework Dependencies
+
+# Note: gradio, fastapi, uvicorn, datasets, huggingface-hub, 
+# pydantic==2.10.6, and protobuf<4 are installed by HF Spaces SDK
+
+# PyTorch with CUDA support (for GPU inference)
+# Note: HF Spaces provides torch, but we ensure GPU support
+torch>=2.0.0
+
+# Web Framework & Interface
+aiohttp>=3.9.0
+httpx>=0.25.0
+
+# Hugging Face Ecosystem
+transformers>=4.35.0
+accelerate>=0.24.0
+tokenizers>=0.15.0
+sentence-transformers>=2.2.0
+
+# Vector Database & Search
+faiss-cpu>=1.7.4
+numpy>=1.24.0
+scipy>=1.11.0
+
+# Data Processing & Utilities
+pandas>=2.1.0
+scikit-learn>=1.3.0
+
+# Database & Persistence
+sqlalchemy>=2.0.0
+alembic>=1.12.0
+
+# Caching & Performance
+cachetools>=5.3.0
+redis>=5.0.0
+python-multipart>=0.0.6
+
+# Security & Validation
+pydantic-settings>=2.1.0
+python-jose[cryptography]>=3.3.0
+bcrypt>=4.0.0
+
+# Mobile Optimization & UI
+cssutils>=2.7.0
+pillow>=10.1.0
+requests>=2.31.0
+
+# Async & Concurrency
+aiofiles>=23.2.0
+concurrent-log-handler>=0.9.0
+
+# Logging & Monitoring
+structlog>=23.2.0
+prometheus-client>=0.19.0
+psutil>=5.9.0
+
+# Development & Testing
+pytest>=7.4.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.1.0
+black>=23.11.0
+flake8>=6.1.0
+mypy>=1.7.0
+
+# Utility Libraries
+python-dateutil>=2.8.0
+pytz>=2023.3
+tzdata>=2023.3
+ujson>=5.8.0
+orjson>=3.9.0
+
+# Flask API for external integrations
+flask>=3.0.0
+flask-cors>=4.0.0
+
+# HF Spaces Specific Dependencies
+# Note: huggingface-cli is part of huggingface-hub (installed by SDK)
+gradio-client>=0.8.0
+gradio-pdf>=0.0.6
+
+# Model-specific dependencies
+safetensors>=0.4.0
+
+# Development/debugging
+ipython>=8.17.0
+ipdb>=0.13.0
+debugpy>=1.7.0
+

src/__init__.py

@@ -0,0 +1,15 @@
+"""
+Research Assistant MVP Package
+"""
+
+__version__ = "1.0.0"
+__author__ = "Research Assistant Team"
+__description__ = "Academic AI assistant with transparent reasoning"
+
+# Import key components for easy access
+try:
+    from .config import settings
+    __all__ = ['settings']
+except ImportError:
+    # Fallback if config is not available
+    __all__ = []

src/agents/__init__.py

@@ -0,0 +1,21 @@
+"""
+AI Research Assistant Agents
+Specialized agents for different tasks
+"""
+
+from .intent_agent import IntentRecognitionAgent, create_intent_agent
+from .synthesis_agent import ResponseSynthesisAgent, create_synthesis_agent
+from .safety_agent import SafetyCheckAgent, create_safety_agent
+from .skills_identification_agent import SkillsIdentificationAgent, create_skills_identification_agent
+
+__all__ = [
+    'IntentRecognitionAgent',
+    'create_intent_agent',
+    'ResponseSynthesisAgent',
+    'create_synthesis_agent',
+    'SafetyCheckAgent',
+    'create_safety_agent',
+    'SkillsIdentificationAgent',
+    'create_skills_identification_agent'
+]
+

src/agents/intent_agent.py

@@ -0,0 +1,301 @@
+"""
+Intent Recognition Agent
+Specialized in understanding user goals using Chain of Thought reasoning
+"""
+
+import logging
+from typing import Dict, Any, List
+import json
+
+logger = logging.getLogger(__name__)
+
+class IntentRecognitionAgent:
+    def __init__(self, llm_router=None):
+        self.llm_router = llm_router
+        self.agent_id = "INTENT_REC_001"
+        self.specialization = "Multi-class intent classification with context awareness"
+        
+        # Intent categories for classification
+        self.intent_categories = [
+            "information_request",      # Asking for facts, explanations
+            "task_execution",           # Requesting actions, automation
+            "creative_generation",      # Content creation, writing
+            "analysis_research",        # Data analysis, research
+            "casual_conversation",      # Chat, social interaction
+            "troubleshooting",          # Problem solving, debugging
+            "education_learning",       # Learning, tutorials
+            "technical_support"         # Technical help, guidance
+        ]
+    
+    async def execute(self, user_input: str, context: Dict[str, Any] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Execute intent recognition with Chain of Thought reasoning
+        """
+        try:
+            logger.info(f"{self.agent_id} processing user input: {user_input[:100]}...")
+            
+            # Use LLM for sophisticated intent recognition if available
+            if self.llm_router:
+                intent_result = await self._llm_based_intent_recognition(user_input, context)
+            else:
+                # Fallback to rule-based classification
+                intent_result = await self._rule_based_intent_recognition(user_input, context)
+            
+            # Add agent metadata
+            intent_result.update({
+                "agent_id": self.agent_id,
+                "processing_time": intent_result.get("processing_time", 0),
+                "confidence_calibration": self._calibrate_confidence(intent_result)
+            })
+            
+            logger.info(f"{self.agent_id} completed with intent: {intent_result['primary_intent']}")
+            return intent_result
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} error: {str(e)}")
+            return self._get_fallback_intent(user_input, context)
+    
+    async def _llm_based_intent_recognition(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Use LLM for sophisticated intent classification with Chain of Thought"""
+        
+        try:
+            cot_prompt = self._build_chain_of_thought_prompt(user_input, context)
+            
+            logger.info(f"{self.agent_id} calling LLM for intent recognition")
+            llm_response = await self.llm_router.route_inference(
+                task_type="intent_classification",
+                prompt=cot_prompt,
+                max_tokens=1000,
+                temperature=0.3
+            )
+            
+            if llm_response and isinstance(llm_response, str) and len(llm_response.strip()) > 0:
+                # Parse LLM response
+                parsed_result = self._parse_llm_intent_response(llm_response)
+                parsed_result["processing_time"] = 0.8
+                parsed_result["method"] = "llm_enhanced"
+                return parsed_result
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} LLM intent recognition failed: {e}")
+        
+        # Fallback to rule-based classification if LLM fails
+        logger.info(f"{self.agent_id} falling back to rule-based classification")
+        return await self._rule_based_intent_recognition(user_input, context)
+    
+    async def _rule_based_intent_recognition(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Rule-based fallback intent classification"""
+        
+        primary_intent, confidence = self._analyze_intent_patterns(user_input)
+        secondary_intents = self._get_secondary_intents(user_input, primary_intent)
+        
+        return {
+            "primary_intent": primary_intent,
+            "secondary_intents": secondary_intents,
+            "confidence_scores": {primary_intent: confidence},
+            "reasoning_chain": ["Rule-based pattern matching applied"],
+            "context_tags": [],
+            "processing_time": 0.02
+        }
+    
+    def _build_chain_of_thought_prompt(self, user_input: str, context: Dict[str, Any]) -> str:
+        """Build Chain of Thought prompt for intent recognition"""
+        
+        # Extract context information from Context Manager structure
+        # Session context, user context, and interaction contexts are all from cache
+        context_info = ""
+        if context:
+            # Use combined_context if available (pre-formatted by Context Manager, includes session context)
+            combined_context = context.get('combined_context', '')
+            if combined_context:
+                # Use the pre-formatted context from Context Manager (includes session context)
+                context_info = f"\n\nAvailable Context:\n{combined_context[:1000]}..."  # Truncate if too long
+            else:
+                # Fallback: Build from session_context, user_context, and interaction_contexts (all from cache)
+                session_context = context.get('session_context', {})
+                session_summary = session_context.get('summary', '') if isinstance(session_context, dict) else ""
+                interaction_contexts = context.get('interaction_contexts', [])
+                user_context = context.get('user_context', '')
+                
+                context_parts = []
+                if session_summary:
+                    context_parts.append(f"Session Context: {session_summary[:300]}...")
+                if user_context:
+                    context_parts.append(f"User Context: {user_context[:300]}...")
+                
+                if interaction_contexts:
+                    # Show last 2 interaction summaries for context
+                    recent_contexts = interaction_contexts[-2:]
+                    context_parts.append("Recent Interactions:")
+                    for idx, ic in enumerate(recent_contexts, 1):
+                        summary = ic.get('summary', '')
+                        if summary:
+                            context_parts.append(f"  {idx}. {summary}")
+                
+                if context_parts:
+                    context_info = "\n\nAvailable Context:\n" + "\n".join(context_parts)
+        
+        if not context_info:
+            context_info = "\n\nAvailable Context: No previous context available (first interaction in session)."
+        
+        return f"""
+        Analyze the user's intent step by step:
+
+        User Input: "{user_input}"
+        {context_info}
+        
+        Step 1: Identify key entities, actions, and questions in the input
+        Step 2: Map to intent categories: {', '.join(self.intent_categories)}
+        Step 3: Consider the conversation flow and user's likely goals (if context available)
+        Step 4: Assign confidence scores (0.0-1.0) for each relevant intent
+        Step 5: Provide reasoning for the classification
+        
+        Respond with JSON format containing primary_intent, secondary_intents, confidence_scores, and reasoning_chain.
+        """
+    
+    def _analyze_intent_patterns(self, user_input: str) -> tuple:
+        """Analyze user input patterns to determine intent"""
+        user_input_lower = user_input.lower()
+        
+        # Pattern matching for different intents
+        patterns = {
+            "information_request": [
+                "what is", "how to", "explain", "tell me about", "what are",
+                "define", "meaning of", "information about"
+            ],
+            "task_execution": [
+                "do this", "make a", "create", "build", "generate", "automate",
+                "set up", "configure", "execute", "run"
+            ],
+            "creative_generation": [
+                "write a", "compose", "create content", "make a story",
+                "generate poem", "creative", "artistic"
+            ],
+            "analysis_research": [
+                "analyze", "research", "compare", "study", "investigate",
+                "data analysis", "find patterns", "statistics"
+            ],
+            "troubleshooting": [
+                "error", "problem", "fix", "debug", "not working",
+                "help with", "issue", "broken"
+            ],
+            "technical_support": [
+                "how do i", "help me", "guide me", "tutorial", "step by step"
+            ]
+        }
+        
+        # Find matching patterns
+        for intent, pattern_list in patterns.items():
+            for pattern in pattern_list:
+                if pattern in user_input_lower:
+                    confidence = min(0.9, 0.6 + (len(pattern) * 0.1))  # Basic confidence calculation
+                    return intent, confidence
+        
+        # Default to casual conversation
+        return "casual_conversation", 0.7
+    
+    def _get_secondary_intents(self, user_input: str, primary_intent: str) -> List[str]:
+        """Get secondary intents based on input complexity"""
+        user_input_lower = user_input.lower()
+        secondary = []
+        
+        # Add secondary intents based on content
+        if "research" in user_input_lower and primary_intent != "analysis_research":
+            secondary.append("analysis_research")
+        if "help" in user_input_lower and primary_intent != "technical_support":
+            secondary.append("technical_support")
+        
+        return secondary[:2]  # Limit to 2 secondary intents
+    
+    def _extract_context_tags(self, user_input: str, context: Dict[str, Any]) -> List[str]:
+        """Extract relevant context tags from user input"""
+        tags = []
+        user_input_lower = user_input.lower()
+        
+        # Simple tag extraction
+        if "research" in user_input_lower:
+            tags.append("research")
+        if "technical" in user_input_lower or "code" in user_input_lower:
+            tags.append("technical")
+        if "academic" in user_input_lower or "study" in user_input_lower:
+            tags.append("academic")
+        if "quick" in user_input_lower or "simple" in user_input_lower:
+            tags.append("quick_request")
+        
+        return tags
+    
+    def _calibrate_confidence(self, intent_result: Dict[str, Any]) -> Dict[str, Any]:
+        """Calibrate confidence scores based on various factors"""
+        primary_intent = intent_result["primary_intent"]
+        confidence = intent_result["confidence_scores"][primary_intent]
+        
+        calibration_factors = {
+            "input_length_impact": min(1.0, len(intent_result.get('user_input', '')) / 100),
+            "context_enhancement": 0.1 if intent_result.get('context_tags') else 0.0,
+            "reasoning_depth_bonus": 0.05 if len(intent_result.get('reasoning_chain', [])) > 2 else 0.0
+        }
+        
+        calibrated_confidence = min(0.95, confidence + sum(calibration_factors.values()))
+        
+        return {
+            "original_confidence": confidence,
+            "calibrated_confidence": calibrated_confidence,
+            "calibration_factors": calibration_factors
+        }
+    
+    def _parse_llm_intent_response(self, response: str) -> Dict[str, Any]:
+        """Parse LLM response for intent classification"""
+        try:
+            import json
+            import re
+            
+            # Try to extract JSON from response
+            json_match = re.search(r'\{.*\}', response, re.DOTALL)
+            if json_match:
+                parsed = json.loads(json_match.group())
+                return parsed
+        except json.JSONDecodeError:
+            logger.warning(f"{self.agent_id} Failed to parse LLM intent JSON")
+        
+        # Fallback parsing - extract intent from text
+        response_lower = response.lower()
+        primary_intent = "casual_conversation"
+        confidence = 0.7
+        
+        # Simple pattern matching for intent extraction
+        if any(word in response_lower for word in ['question', 'ask', 'what', 'how', 'why']):
+            primary_intent = "information_request"
+            confidence = 0.8
+        elif any(word in response_lower for word in ['task', 'action', 'do', 'help', 'assist']):
+            primary_intent = "task_execution"
+            confidence = 0.8
+        elif any(word in response_lower for word in ['create', 'generate', 'write', 'make']):
+            primary_intent = "creative_generation"
+            confidence = 0.8
+        
+        return {
+            "primary_intent": primary_intent,
+            "secondary_intents": [],
+            "confidence_scores": {primary_intent: confidence},
+            "reasoning_chain": [f"LLM response parsed: {response[:100]}..."],
+            "context_tags": ["llm_parsed"],
+            "method": "llm_parsed"
+        }
+    
+    def _get_fallback_intent(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Provide fallback intent when processing fails"""
+        return {
+            "primary_intent": "casual_conversation",
+            "secondary_intents": [],
+            "confidence_scores": {"casual_conversation": 0.5},
+            "reasoning_chain": ["Fallback: Default to casual conversation"],
+            "context_tags": ["fallback"],
+            "processing_time": 0.01,
+            "agent_id": self.agent_id,
+            "error_handled": True
+        }
+
+# Factory function for easy instantiation
+def create_intent_agent(llm_router=None):
+    return IntentRecognitionAgent(llm_router)
+

src/agents/safety_agent.py

@@ -0,0 +1,453 @@
+"""
+Safety & Bias Mitigation Agent
+Specialized in content moderation and bias detection with non-blocking warnings
+"""
+
+import logging
+import re
+from typing import Dict, Any, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+class SafetyCheckAgent:
+    def __init__(self, llm_router=None):
+        self.llm_router = llm_router
+        self.agent_id = "SAFETY_BIAS_001"
+        self.specialization = "Content moderation and bias detection with warning-based approach"
+        
+        # Safety thresholds (non-blocking, warning-only)
+        self.safety_thresholds = {
+            "toxicity": 0.8,        # High threshold for warnings
+            "bias": 0.7,           # Moderate threshold for bias detection
+            "safety": 0.6,         # Lower threshold for general safety
+            "privacy": 0.9         # Very high threshold for privacy concerns
+        }
+        
+        # Warning templates (non-blocking)
+        self.warning_templates = {
+            "toxicity": "⚠️ Note: Content may contain strong language",
+            "bias": "🔍 Note: Potential biases detected in response",
+            "safety": "📝 Note: Response should be verified for accuracy",
+            "privacy": "🔒 Note: Privacy-sensitive topics discussed",
+            "controversial": "💭 Note: This topic may have multiple perspectives"
+        }
+        
+        # Pattern-based detection for quick analysis
+        self.sensitive_patterns = {
+            "toxicity": [
+                r'\b(hate|violence|harm|attack|destroy)\b',
+                r'\b(kill|hurt|harm|danger)\b',
+                r'racial slurs',  # Placeholder for actual sensitive terms
+            ],
+            "bias": [
+                r'\b(all|always|never|every)\b',  # Overgeneralizations
+                r'\b(should|must|have to)\b',     # Prescriptive language
+                r'stereotypes?',                  # Stereotype indicators
+            ],
+            "privacy": [
+                r'\b(ssn|social security|password|credit card)\b',
+                r'\b(address|phone|email|personal)\b',
+                r'\b(confidential|secret|private)\b',
+            ]
+        }
+    
+    async def execute(self, response, context: Dict[str, Any] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Execute safety check with non-blocking warnings
+        Returns original response with added warnings
+        """
+        try:
+            # Handle both string and dict inputs
+            if isinstance(response, dict):
+                # Extract the actual response string from the dict
+                response_text = response.get('final_response', response.get('response', str(response)))
+            else:
+                response_text = str(response)
+            
+            logger.info(f"{self.agent_id} analyzing response of length {len(response_text)}")
+            
+            # Perform safety analysis
+            safety_analysis = await self._analyze_safety(response_text, context)
+            
+            # Generate warnings without modifying response
+            warnings = self._generate_warnings(safety_analysis)
+            
+            # Add safety metadata to response
+            result = {
+                "original_response": response_text,
+                "safety_checked_response": response_text,  # Response never modified
+                "warnings": warnings,
+                "safety_analysis": safety_analysis,
+                "blocked": False,  # Never blocks content
+                "confidence_scores": safety_analysis.get("confidence_scores", {}),
+                "agent_id": self.agent_id
+            }
+            
+            logger.info(f"{self.agent_id} completed with {len(warnings)} warnings")
+            return result
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} error: {str(e)}", exc_info=True)
+            # Fail-safe: return original response with error note
+            response_text = str(response) if not isinstance(response, dict) else response.get('final_response', str(response))
+            return self._get_fallback_result(response_text)
+    
+    async def _analyze_safety(self, response: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Analyze response for safety concerns using multiple methods"""
+        
+        if self.llm_router:
+            return await self._llm_based_safety_analysis(response, context)
+        else:
+            return await self._pattern_based_safety_analysis(response)
+    
+    async def _llm_based_safety_analysis(self, response: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Use LLM for sophisticated safety analysis"""
+        
+        try:
+            safety_prompt = self._build_safety_prompt(response, context)
+            
+            logger.info(f"{self.agent_id} calling LLM for safety analysis")
+            llm_response = await self.llm_router.route_inference(
+                task_type="safety_check",
+                prompt=safety_prompt,
+                max_tokens=800,
+                temperature=0.3
+            )
+            
+            if llm_response and isinstance(llm_response, str) and len(llm_response.strip()) > 0:
+                # Parse LLM response
+                parsed_analysis = self._parse_llm_safety_response(llm_response)
+                parsed_analysis["processing_time"] = 0.6
+                parsed_analysis["method"] = "llm_enhanced"
+                return parsed_analysis
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} LLM safety analysis failed: {e}")
+        
+        # Fallback to pattern-based analysis if LLM fails
+        logger.info(f"{self.agent_id} falling back to pattern-based safety analysis")
+        return await self._pattern_based_safety_analysis(response)
+    
+    async def _pattern_based_safety_analysis(self, response: str) -> Dict[str, Any]:
+        """Pattern-based safety analysis as fallback"""
+        
+        detected_issues = self._pattern_based_detection(response)
+        
+        return {
+            "toxicity_score": self._calculate_toxicity_score(response),
+            "bias_indicators": self._detect_bias_indicators(response),
+            "privacy_concerns": self._check_privacy_issues(response),
+            "overall_safety_score": 0.75,  # Conservative estimate
+            "confidence_scores": {
+                "toxicity": 0.6,
+                "bias": 0.5,
+                "safety": 0.7,
+                "privacy": 0.8
+            },
+            "detected_issues": detected_issues,
+            "analysis_method": "pattern_based"
+        }
+    
+    def _build_safety_prompt(self, response: str, context: Dict[str, Any]) -> str:
+        """Build prompt for safety analysis with context awareness"""
+        
+        # Extract relevant context information for safety analysis
+        context_info = ""
+        if context:
+            # Get session context, user context, and interaction contexts (all from cache)
+            session_context = context.get('session_context', {})
+            session_summary = session_context.get('summary', '') if isinstance(session_context, dict) else ""
+            user_context = context.get('user_context', '')
+            interaction_contexts = context.get('interaction_contexts', [])
+            
+            if session_summary:
+                context_info = f"\n\nSession Context (for safety context): {session_summary[:200]}..."
+            if user_context:
+                context_info += f"\n\nUser Context (for safety context): {user_context[:200]}..."
+            
+            # Optionally include recent interaction context to understand conversation flow
+            if interaction_contexts:
+                recent_context = interaction_contexts[-1].get('summary', '') if interaction_contexts else ''
+                if recent_context:
+                    context_info += f"\nRecent conversation: {recent_context[:200]}..."
+        
+        return f"""
+        Analyze the following text for safety concerns and provide warnings if needed:
+        
+        Text to analyze: "{response[:500]}..."  # Truncate for large responses
+        {context_info}
+        
+        Analyze for:
+        1. Toxicity or harmful language
+        2. Potential biases or stereotypes
+        3. Privacy or security concerns
+        4. Controversial or sensitive topics
+        
+        Consider the conversation context when assessing whether content is appropriate in this specific conversational context.
+        
+        Provide analysis in JSON format with:
+        - safety_scores for each category (0-1 scale)
+        - detected_issues list
+        - confidence_level
+        - recommended_warnings (non-blocking, advisory only)
+        
+        IMPORTANT: Never block or modify the content, only provide warnings.
+        """
+    
+    def _pattern_based_detection(self, response: str) -> List[Dict[str, Any]]:
+        """Detect safety issues using pattern matching"""
+        issues = []
+        response_lower = response.lower()
+        
+        # Check each category
+        for category, patterns in self.sensitive_patterns.items():
+            for pattern in patterns:
+                if re.search(pattern, response_lower, re.IGNORECASE):
+                    issues.append({
+                        "category": category,
+                        "pattern": pattern,
+                        "severity": "low",  # Always low for warning-only approach
+                        "confidence": 0.7
+                    })
+                    break  # Only report one pattern match per category
+        
+        return issues
+    
+    def _calculate_toxicity_score(self, response: str) -> float:
+        """Calculate toxicity score (simplified version)"""
+        # Simple heuristic-based toxicity detection
+        toxic_indicators = [
+            'hate', 'violence', 'harm', 'attack', 'destroy', 'kill', 'hurt'
+        ]
+        
+        score = 0.0
+        words = response.lower().split()
+        for indicator in toxic_indicators:
+            if indicator in words:
+                score += 0.2
+        
+        return min(1.0, score)
+    
+    def _detect_bias_indicators(self, response: str) -> List[str]:
+        """Detect potential bias indicators"""
+        biases = []
+        
+        # Overgeneralization detection
+        if re.search(r'\b(all|always|never|every)\s+\w+s\b', response, re.IGNORECASE):
+            biases.append("overgeneralization")
+        
+        # Prescriptive language
+        if re.search(r'\b(should|must|have to|ought to)\b', response, re.IGNORECASE):
+            biases.append("prescriptive_language")
+        
+        # Stereotype indicators
+        stereotype_patterns = [
+            r'\b(all|most)\s+\w+\s+people\b',
+            r'\b(typical|usual|normal)\s+\w+\b',
+        ]
+        
+        for pattern in stereotype_patterns:
+            if re.search(pattern, response, re.IGNORECASE):
+                biases.append("potential_stereotype")
+                break
+        
+        return biases
+    
+    def _check_privacy_issues(self, response: str) -> List[str]:
+        """Check for privacy-sensitive content"""
+        privacy_issues = []
+        
+        # Personal information patterns
+        personal_info_patterns = [
+            r'\b\d{3}-\d{2}-\d{4}\b',  # SSN-like pattern
+            r'\b\d{16}\b',              # Credit card-like pattern
+            r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',  # Email
+        ]
+        
+        for pattern in personal_info_patterns:
+            if re.search(pattern, response):
+                privacy_issues.append("potential_personal_info")
+                break
+        
+        return privacy_issues
+    
+    def _generate_warnings(self, safety_analysis: Dict[str, Any]) -> List[str]:
+        """Generate non-blocking warnings based on safety analysis"""
+        warnings = []
+        
+        try:
+            # Safely extract and validate confidence_scores
+            confidence_scores = safety_analysis.get("confidence_scores", {})
+            if not isinstance(confidence_scores, dict):
+                confidence_scores = {}
+            
+            # Safely extract detected_issues
+            detected_issues = safety_analysis.get("detected_issues", [])
+            if not isinstance(detected_issues, list):
+                detected_issues = []
+            
+            # Toxicity warnings
+            if isinstance(confidence_scores.get("toxicity"), (int, float)) and confidence_scores.get("toxicity", 0) > self.safety_thresholds["toxicity"]:
+                warnings.append(self.warning_templates["toxicity"])
+            
+            # Bias warnings
+            has_bias_score = isinstance(confidence_scores.get("bias"), (int, float)) and confidence_scores.get("bias", 0) > self.safety_thresholds["bias"]
+            has_bias_indicators = safety_analysis.get("bias_indicators")
+            if has_bias_score or (has_bias_indicators and has_bias_indicators):
+                warnings.append(self.warning_templates["bias"])
+            
+            # Privacy warnings
+            has_privacy_score = isinstance(confidence_scores.get("privacy"), (int, float)) and confidence_scores.get("privacy", 0) > self.safety_thresholds["privacy"]
+            has_privacy_concerns = safety_analysis.get("privacy_concerns")
+            if has_privacy_score or (has_privacy_concerns and has_privacy_concerns):
+                warnings.append(self.warning_templates["privacy"])
+            
+            # General safety warning if overall score is low
+            overall_score = safety_analysis.get("overall_safety_score", 1.0)
+            if isinstance(overall_score, (int, float)) and overall_score < 0.7:
+                warnings.append(self.warning_templates["safety"])
+            
+            # Add context-specific warnings for detected issues
+            for issue in detected_issues:
+                try:
+                    if isinstance(issue, dict):
+                        category = issue.get("category")
+                        if category and isinstance(category, str) and category in self.warning_templates:
+                            category_warning = self.warning_templates[category]
+                            if category_warning not in warnings:
+                                warnings.append(category_warning)
+                except Exception as e:
+                    logger.debug(f"Error processing issue: {e}")
+                    continue
+            
+            # Deduplicate warnings and ensure all are strings
+            warnings = [w for w in warnings if isinstance(w, str)]
+            # Create set and convert back to list (safely handle any edge cases)
+            seen = set()
+            unique_warnings = []
+            for w in warnings:
+                if w not in seen:
+                    seen.add(w)
+                    unique_warnings.append(w)
+            return unique_warnings
+            
+        except Exception as e:
+            logger.error(f"Error generating warnings: {e}", exc_info=True)
+            # Return empty list on error
+            return []
+    
+    def _parse_llm_safety_response(self, response: str) -> Dict[str, Any]:
+        """Parse LLM response for safety analysis"""
+        try:
+            import json
+            import re
+            
+            # Try to extract JSON from response
+            json_match = re.search(r'\{.*\}', response, re.DOTALL)
+            if json_match:
+                parsed = json.loads(json_match.group())
+                return parsed
+        except json.JSONDecodeError:
+            logger.warning(f"{self.agent_id} Failed to parse LLM safety JSON")
+        
+        # Fallback parsing - extract safety info from text
+        response_lower = response.lower()
+        
+        # Simple safety analysis based on keywords
+        toxicity_score = 0.1
+        bias_score = 0.1
+        safety_score = 0.9
+        
+        if any(word in response_lower for word in ['toxic', 'harmful', 'dangerous', 'inappropriate']):
+            toxicity_score = 0.8
+            safety_score = 0.3
+        elif any(word in response_lower for word in ['bias', 'discriminatory', 'unfair', 'prejudiced']):
+            bias_score = 0.7
+            safety_score = 0.5
+        
+        return {
+            "toxicity_score": toxicity_score,
+            "bias_indicators": [],
+            "privacy_concerns": [],
+            "overall_safety_score": safety_score,
+            "confidence_scores": {
+                "toxicity": 0.7,
+                "bias": 0.6,
+                "safety": safety_score,
+                "privacy": 0.9
+            },
+            "detected_issues": [],
+            "analysis_method": "llm_parsed",
+            "llm_response": response[:200] + "..." if len(response) > 200 else response
+        }
+    
+    def _get_fallback_result(self, response: str) -> Dict[str, Any]:
+        """Fallback result when safety check fails"""
+        return {
+            "original_response": response,
+            "safety_checked_response": response,
+            "warnings": ["🔧 Note: Safety analysis temporarily unavailable"],
+            "safety_analysis": {
+                "overall_safety_score": 0.5,
+                "confidence_scores": {"safety": 0.5},
+                "detected_issues": [],
+                "analysis_method": "fallback"
+            },
+            "blocked": False,
+            "agent_id": self.agent_id,
+            "error_handled": True
+        }
+    
+    def get_safety_summary(self, analysis_result: Dict[str, Any]) -> str:
+        """Generate a user-friendly safety summary"""
+        warnings = analysis_result.get("warnings", [])
+        safety_score = analysis_result.get("safety_analysis", {}).get("overall_safety_score", 1.0)
+        
+        if not warnings:
+            return "✅ Content appears safe based on automated analysis"
+        
+        warning_count = len(warnings)
+        if safety_score > 0.8:
+            severity = "low"
+        elif safety_score > 0.6:
+            severity = "medium"
+        else:
+            severity = "high"
+        
+        return f"⚠️ {warning_count} advisory note(s) - {severity} severity"
+    
+    async def batch_analyze(self, responses: List[str]) -> List[Dict[str, Any]]:
+        """Analyze multiple responses efficiently"""
+        results = []
+        for response in responses:
+            result = await self.execute(response)
+            results.append(result)
+        return results
+
+# Factory function for easy instantiation
+def create_safety_agent(llm_router=None):
+    return SafetyCheckAgent(llm_router)
+
+# Example usage
+if __name__ == "__main__":
+    # Test the safety agent
+    agent = SafetyCheckAgent()
+    
+    test_responses = [
+        "This is a perfectly normal response with no issues.",
+        "Some content that might contain controversial topics.",
+        "Discussion about sensitive personal information."
+    ]
+    
+    import asyncio
+    
+    async def test_agent():
+        for response in test_responses:
+            result = await agent.execute(response)
+            print(f"Response: {response[:50]}...")
+            print(f"Warnings: {result['warnings']}")
+            print(f"Safety Score: {result['safety_analysis']['overall_safety_score']}")
+            print("-" * 50)
+    
+    asyncio.run(test_agent())
+

src/agents/skills_identification_agent.py

@@ -0,0 +1,547 @@
+"""
+Skills Identification Agent
+Specialized in analyzing user prompts and identifying relevant expert skills based on market analysis
+"""
+
+import logging
+from typing import Dict, Any, List, Tuple
+import json
+import re
+
+logger = logging.getLogger(__name__)
+
+class SkillsIdentificationAgent:
+    def __init__(self, llm_router=None):
+        self.llm_router = llm_router
+        self.agent_id = "SKILLS_ID_001"
+        self.specialization = "Expert skills identification and market analysis"
+        
+        # Market analysis data from Expert_Skills_Market_Analysis_2024.md
+        self.market_categories = {
+            "IT and Software Development": {
+                "market_share": 25,
+                "growth_rate": 25.0,
+                "specialized_skills": [
+                    "Cybersecurity", "Artificial Intelligence & Machine Learning", 
+                    "Cloud Computing", "Data Analytics & Big Data", 
+                    "Software Engineering", "Blockchain Technology", "Quantum Computing"
+                ]
+            },
+            "Finance and Accounting": {
+                "market_share": 20,
+                "growth_rate": 6.8,
+                "specialized_skills": [
+                    "Financial Analysis & Modeling", "Risk Management", 
+                    "Regulatory Compliance", "Fintech Solutions", 
+                    "ESG Reporting", "Tax Preparation", "Investment Analysis"
+                ]
+            },
+            "Healthcare and Medicine": {
+                "market_share": 15,
+                "growth_rate": 8.5,
+                "specialized_skills": [
+                    "Telemedicine Training", "Advanced Nursing Certifications", 
+                    "Healthcare Informatics", "Clinical Research", 
+                    "Medical Device Technology", "Public Health", "Mental Health Services"
+                ]
+            },
+            "Education and Teaching": {
+                "market_share": 10,
+                "growth_rate": 3.2,
+                "specialized_skills": [
+                    "Instructional Design", "Educational Technology Integration", 
+                    "Digital Literacy Training", "Special Education", 
+                    "Career Coaching", "E-learning Development", "STEM Education"
+                ]
+            },
+            "Engineering and Construction": {
+                "market_share": 10,
+                "growth_rate": 8.5,
+                "specialized_skills": [
+                    "Automation Engineering", "Sustainable Design", 
+                    "Project Management", "Environmental Engineering", 
+                    "Advanced Manufacturing", "Infrastructure Development", "Quality Control"
+                ]
+            },
+            "Marketing and Sales": {
+                "market_share": 10,
+                "growth_rate": 7.1,
+                "specialized_skills": [
+                    "Digital Marketing", "Data Analytics", 
+                    "Customer Relationship Management", "Content Marketing", 
+                    "E-commerce Management", "Market Research", "Sales Strategy"
+                ]
+            },
+            "Consulting and Strategy": {
+                "market_share": 5,
+                "growth_rate": 6.0,
+                "specialized_skills": [
+                    "Business Analysis", "Change Management", 
+                    "Strategic Planning", "Operations Research", 
+                    "Industry-Specific Knowledge", "Problem-Solving", "Leadership Development"
+                ]
+            },
+            "Environmental and Sustainability": {
+                "market_share": 5,
+                "growth_rate": 15.0,
+                "specialized_skills": [
+                    "Renewable Energy Technologies", "Environmental Policy", 
+                    "Sustainability Reporting", "Ecological Conservation", 
+                    "Carbon Management", "Green Technology", "Circular Economy"
+                ]
+            },
+            "Arts and Humanities": {
+                "market_share": 5,
+                "growth_rate": 2.5,
+                "specialized_skills": [
+                    "Creative Thinking", "Cultural Analysis", 
+                    "Communication", "Digital Media", 
+                    "Language Services", "Historical Research", "Philosophical Analysis"
+                ]
+            }
+        }
+        
+        # Skill classification categories for the classification_specialist model
+        self.skill_categories = [
+            "technical_programming", "data_analysis", "cybersecurity", "cloud_computing",
+            "financial_analysis", "risk_management", "regulatory_compliance", "fintech",
+            "healthcare_technology", "medical_research", "telemedicine", "nursing",
+            "educational_technology", "curriculum_design", "online_learning", "teaching",
+            "project_management", "engineering_design", "sustainable_engineering", "manufacturing",
+            "digital_marketing", "sales_strategy", "customer_management", "market_research",
+            "business_consulting", "strategic_planning", "change_management", "leadership",
+            "environmental_science", "sustainability", "renewable_energy", "green_technology",
+            "creative_design", "content_creation", "communication", "cultural_analysis"
+        ]
+    
+    async def execute(self, user_input: str, context: Dict[str, Any] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Execute skills identification with two-step process:
+        1. Market analysis using reasoning_primary model
+        2. Skill classification using classification_specialist model
+        """
+        try:
+            logger.info(f"{self.agent_id} processing user input: {user_input[:100]}...")
+            
+            # Step 1: Market Analysis with reasoning_primary model
+            market_analysis = await self._analyze_market_relevance(user_input, context)
+            
+            # Step 2: Skill Classification with classification_specialist model
+            skill_classification = await self._classify_skills(user_input, context)
+            
+            # Combine results
+            combined_data = {
+                "market_analysis": market_analysis,
+                "skill_classification": skill_classification,
+                "user_input": user_input,
+                "context": context
+            }
+            
+            result = {
+                "agent_id": self.agent_id,
+                "market_analysis": market_analysis,
+                "skill_classification": skill_classification,
+                "identified_skills": self._extract_high_probability_skills(combined_data),
+                "processing_time": market_analysis.get("processing_time", 0) + skill_classification.get("processing_time", 0),
+                "confidence_score": self._calculate_overall_confidence(market_analysis, skill_classification)
+            }
+            
+            logger.info(f"{self.agent_id} completed with {len(result['identified_skills'])} skills identified")
+            return result
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} error: {str(e)}")
+            return self._get_fallback_result(user_input, context)
+    
+    async def _analyze_market_relevance(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Use reasoning_primary model to analyze market relevance"""
+        
+        if self.llm_router:
+            try:
+                # Build market analysis prompt with context
+                market_prompt = self._build_market_analysis_prompt(user_input, context)
+                
+                logger.info(f"{self.agent_id} calling reasoning_primary for market analysis")
+                llm_response = await self.llm_router.route_inference(
+                    task_type="general_reasoning",
+                    prompt=market_prompt,
+                    max_tokens=2000,
+                    temperature=0.7
+                )
+                
+                if llm_response and isinstance(llm_response, str) and len(llm_response.strip()) > 0:
+                    # Parse LLM response
+                    parsed_analysis = self._parse_market_analysis_response(llm_response)
+                    parsed_analysis["processing_time"] = 0.8
+                    parsed_analysis["method"] = "llm_enhanced"
+                    return parsed_analysis
+                
+            except Exception as e:
+                logger.error(f"{self.agent_id} LLM market analysis failed: {e}")
+        
+        # Fallback to rule-based analysis
+        return self._rule_based_market_analysis(user_input)
+    
+    async def _classify_skills(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Use classification_specialist model to classify skills"""
+        
+        if self.llm_router:
+            try:
+                # Build classification prompt
+                classification_prompt = self._build_classification_prompt(user_input)
+                
+                logger.info(f"{self.agent_id} calling classification_specialist for skill classification")
+                llm_response = await self.llm_router.route_inference(
+                    task_type="intent_classification",
+                    prompt=classification_prompt,
+                    max_tokens=512,
+                    temperature=0.3
+                )
+                
+                if llm_response and isinstance(llm_response, str) and len(llm_response.strip()) > 0:
+                    # Parse classification response
+                    parsed_classification = self._parse_classification_response(llm_response)
+                    parsed_classification["processing_time"] = 0.3
+                    parsed_classification["method"] = "llm_enhanced"
+                    return parsed_classification
+                
+            except Exception as e:
+                logger.error(f"{self.agent_id} LLM classification failed: {e}")
+        
+        # Fallback to rule-based classification
+        return self._rule_based_skill_classification(user_input)
+    
+    def _build_market_analysis_prompt(self, user_input: str, context: Dict[str, Any] = None) -> str:
+        """Build prompt for market analysis using reasoning_primary model with optional context"""
+        
+        market_data = "\n".join([
+            f"- {category}: {data['market_share']}% market share, {data['growth_rate']}% growth rate"
+            for category, data in self.market_categories.items()
+        ])
+        
+        specialized_skills = "\n".join([
+            f"- {category}: {', '.join(data['specialized_skills'][:3])}"
+            for category, data in self.market_categories.items()
+        ])
+        
+        # Add context information if available (all from cache)
+        context_info = ""
+        if context:
+            session_context = context.get('session_context', {})
+            session_summary = session_context.get('summary', '') if isinstance(session_context, dict) else ""
+            user_context = context.get('user_context', '')
+            interaction_contexts = context.get('interaction_contexts', [])
+            
+            if session_summary:
+                context_info = f"\n\nSession Context (session summary): {session_summary[:300]}..."
+            if user_context:
+                context_info += f"\n\nUser Context (persona summary): {user_context[:300]}..."
+            
+            if interaction_contexts:
+                # Include recent interaction context to understand topic continuity
+                recent_contexts = interaction_contexts[-2:]  # Last 2 interactions
+                if recent_contexts:
+                    context_info += "\n\nRecent conversation context:"
+                    for idx, ic in enumerate(recent_contexts, 1):
+                        summary = ic.get('summary', '')
+                        if summary:
+                            context_info += f"\n  {idx}. {summary}"
+        
+        return f"""Analyze the following user input and identify the most relevant industry categories and specialized skills based on current market data.
+
+User Input: "{user_input}"
+{context_info}
+
+Current Market Distribution:
+{market_data}
+
+Specialized Skills by Category (top 3 per category):
+{specialized_skills}
+
+Task: 
+1. Identify which industry categories are most relevant to the user's input (consider conversation context if provided)
+2. Select 1-3 specialized skills from each relevant category that best match the user's needs
+3. Provide market share percentages and growth rates for identified categories
+4. Explain your reasoning for each selection
+5. If conversation context is available, consider how previous topics might inform the skill identification
+
+Respond in JSON format:
+{{
+    "relevant_categories": [
+        {{
+            "category": "category_name",
+            "market_share": percentage,
+            "growth_rate": percentage,
+            "relevance_score": 0.0-1.0,
+            "reasoning": "explanation"
+        }}
+    ],
+    "selected_skills": [
+        {{
+            "skill": "skill_name",
+            "category": "category_name",
+            "relevance_score": 0.0-1.0,
+            "reasoning": "explanation"
+        }}
+    ],
+    "overall_analysis": "summary of findings"
+}}"""
+    
+    def _build_classification_prompt(self, user_input: str) -> str:
+        """Build prompt for skill classification using classification_specialist model"""
+        
+        skill_categories_str = ", ".join(self.skill_categories)
+        
+        return f"""Classify the following user input into relevant skill categories. For each category, provide a probability score (0.0-1.0) indicating how likely the input relates to that skill.
+
+User Input: "{user_input}"
+
+Available Skill Categories: {skill_categories_str}
+
+Task: Provide probability scores for each skill category that passes a 20% threshold.
+
+Respond in JSON format:
+{{
+    "skill_probabilities": {{
+        "category_name": probability_score,
+        ...
+    }},
+    "top_skills": [
+        {{
+            "skill": "category_name",
+            "probability": score,
+            "confidence": "high/medium/low"
+        }}
+    ],
+    "classification_reasoning": "explanation of classification decisions"
+}}"""
+    
+    def _parse_market_analysis_response(self, response: str) -> Dict[str, Any]:
+        """Parse LLM response for market analysis"""
+        try:
+            # Try to extract JSON from response
+            json_match = re.search(r'\{.*\}', response, re.DOTALL)
+            if json_match:
+                parsed = json.loads(json_match.group())
+                return parsed
+        except json.JSONDecodeError:
+            logger.warning(f"{self.agent_id} Failed to parse market analysis JSON")
+        
+        # Fallback parsing
+        return {
+            "relevant_categories": [{"category": "General", "market_share": 10, "growth_rate": 5.0, "relevance_score": 0.7, "reasoning": "General analysis"}],
+            "selected_skills": [{"skill": "General Analysis", "category": "General", "relevance_score": 0.7, "reasoning": "Broad applicability"}],
+            "overall_analysis": "Market analysis completed with fallback parsing",
+            "method": "fallback_parsing"
+        }
+    
+    def _parse_classification_response(self, response: str) -> Dict[str, Any]:
+        """Parse LLM response for skill classification"""
+        try:
+            # Try to extract JSON from response
+            json_match = re.search(r'\{.*\}', response, re.DOTALL)
+            if json_match:
+                parsed = json.loads(json_match.group())
+                return parsed
+        except json.JSONDecodeError:
+            logger.warning(f"{self.agent_id} Failed to parse classification JSON")
+        
+        # Fallback parsing
+        return {
+            "skill_probabilities": {"general_analysis": 0.7},
+            "top_skills": [{"skill": "general_analysis", "probability": 0.7, "confidence": "medium"}],
+            "classification_reasoning": "Classification completed with fallback parsing",
+            "method": "fallback_parsing"
+        }
+    
+    def _rule_based_market_analysis(self, user_input: str) -> Dict[str, Any]:
+        """Rule-based fallback for market analysis"""
+        user_input_lower = user_input.lower()
+        
+        relevant_categories = []
+        selected_skills = []
+        
+        # Pattern matching for different categories
+        patterns = {
+            "IT and Software Development": ["code", "programming", "software", "tech", "ai", "machine learning", "data", "cyber", "cloud"],
+            "Finance and Accounting": ["finance", "money", "investment", "banking", "accounting", "financial", "risk", "compliance"],
+            "Healthcare and Medicine": ["health", "medical", "doctor", "nurse", "patient", "clinical", "medicine", "healthcare"],
+            "Education and Teaching": ["teach", "education", "learn", "student", "school", "curriculum", "instruction"],
+            "Engineering and Construction": ["engineer", "construction", "build", "project", "manufacturing", "design"],
+            "Marketing and Sales": ["marketing", "sales", "customer", "advertising", "promotion", "brand"],
+            "Consulting and Strategy": ["consulting", "strategy", "business", "management", "planning"],
+            "Environmental and Sustainability": ["environment", "sustainable", "green", "renewable", "climate", "carbon"],
+            "Arts and Humanities": ["art", "creative", "culture", "humanities", "design", "communication"]
+        }
+        
+        for category, keywords in patterns.items():
+            relevance_score = 0.0
+            for keyword in keywords:
+                if keyword in user_input_lower:
+                    relevance_score += 0.2
+            
+            if relevance_score > 0.0:
+                category_data = self.market_categories[category]
+                relevant_categories.append({
+                    "category": category,
+                    "market_share": category_data["market_share"],
+                    "growth_rate": category_data["growth_rate"],
+                    "relevance_score": min(1.0, relevance_score),
+                    "reasoning": f"Matched keywords: {[k for k in keywords if k in user_input_lower]}"
+                })
+                
+                # Add top skills from this category
+                for skill in category_data["specialized_skills"][:2]:
+                    selected_skills.append({
+                        "skill": skill,
+                        "category": category,
+                        "relevance_score": relevance_score * 0.8,
+                        "reasoning": f"From {category} category"
+                    })
+        
+        return {
+            "relevant_categories": relevant_categories,
+            "selected_skills": selected_skills,
+            "overall_analysis": f"Rule-based analysis identified {len(relevant_categories)} relevant categories",
+            "processing_time": 0.1,
+            "method": "rule_based"
+        }
+    
+    def _rule_based_skill_classification(self, user_input: str) -> Dict[str, Any]:
+        """Rule-based fallback for skill classification"""
+        user_input_lower = user_input.lower()
+        
+        skill_probabilities = {}
+        top_skills = []
+        
+        # Simple keyword matching for skill categories
+        skill_keywords = {
+            "technical_programming": ["code", "programming", "software", "development", "python", "java"],
+            "data_analysis": ["data", "analysis", "statistics", "analytics", "research"],
+            "cybersecurity": ["security", "cyber", "hack", "protection", "vulnerability"],
+            "financial_analysis": ["finance", "money", "investment", "financial", "economic"],
+            "healthcare_technology": ["health", "medical", "healthcare", "clinical", "patient"],
+            "educational_technology": ["education", "teach", "learn", "student", "curriculum"],
+            "project_management": ["project", "manage", "planning", "coordination", "leadership"],
+            "digital_marketing": ["marketing", "advertising", "promotion", "social media", "brand"],
+            "environmental_science": ["environment", "sustainable", "green", "climate", "carbon"],
+            "creative_design": ["design", "creative", "art", "visual", "graphic"]
+        }
+        
+        for skill, keywords in skill_keywords.items():
+            probability = 0.0
+            for keyword in keywords:
+                if keyword in user_input_lower:
+                    probability += 0.3
+            
+            if probability > 0.2:  # 20% threshold
+                skill_probabilities[skill] = min(1.0, probability)
+                top_skills.append({
+                    "skill": skill,
+                    "probability": skill_probabilities[skill],
+                    "confidence": "high" if probability > 0.6 else "medium" if probability > 0.4 else "low"
+                })
+        
+        return {
+            "skill_probabilities": skill_probabilities,
+            "top_skills": top_skills,
+            "classification_reasoning": f"Rule-based classification identified {len(top_skills)} relevant skills",
+            "processing_time": 0.05,
+            "method": "rule_based"
+        }
+    
+    def _extract_high_probability_skills(self, classification: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Extract skills that pass the 20% probability threshold"""
+        high_prob_skills = []
+        
+        # From market analysis
+        market_analysis = classification.get("market_analysis", {})
+        market_skills = market_analysis.get("selected_skills", [])
+        for skill in market_skills:
+            if skill.get("relevance_score", 0) > 0.2:
+                high_prob_skills.append({
+                    "skill": skill["skill"],
+                    "category": skill["category"],
+                    "probability": skill["relevance_score"],
+                    "source": "market_analysis"
+                })
+        
+        # From skill classification
+        skill_classification = classification.get("skill_classification", {})
+        classification_skills = skill_classification.get("top_skills", [])
+        for skill in classification_skills:
+            if skill.get("probability", 0) > 0.2:
+                high_prob_skills.append({
+                    "skill": skill["skill"],
+                    "category": "classified",
+                    "probability": skill["probability"],
+                    "source": "skill_classification"
+                })
+        
+        # If no skills found from LLM, use rule-based fallback
+        if not high_prob_skills:
+            logger.warning(f"{self.agent_id} No skills identified from LLM, using rule-based fallback")
+            # Extract user input from context if available
+            user_input = ""
+            if isinstance(classification, dict) and "user_input" in classification:
+                user_input = classification["user_input"]
+            elif isinstance(classification, dict) and "context" in classification:
+                context = classification["context"]
+                if isinstance(context, dict) and "user_input" in context:
+                    user_input = context["user_input"]
+            
+            if user_input:
+                rule_based_result = self._rule_based_skill_classification(user_input)
+                rule_skills = rule_based_result.get("top_skills", [])
+                for skill in rule_skills:
+                    if skill.get("probability", 0) > 0.2:
+                        high_prob_skills.append({
+                            "skill": skill["skill"],
+                            "category": "rule_based",
+                            "probability": skill["probability"],
+                            "source": "rule_based_fallback"
+                        })
+        
+        # Remove duplicates and sort by probability
+        unique_skills = {}
+        for skill in high_prob_skills:
+            skill_name = skill["skill"]
+            if skill_name not in unique_skills or skill["probability"] > unique_skills[skill_name]["probability"]:
+                unique_skills[skill_name] = skill
+        
+        return sorted(unique_skills.values(), key=lambda x: x["probability"], reverse=True)
+    
+    def _calculate_overall_confidence(self, market_analysis: Dict[str, Any], skill_classification: Dict[str, Any]) -> float:
+        """Calculate overall confidence score"""
+        market_confidence = len(market_analysis.get("relevant_categories", [])) * 0.1
+        classification_confidence = len(skill_classification.get("top_skills", [])) * 0.1
+        
+        return min(1.0, market_confidence + classification_confidence + 0.3)
+    
+    def _get_fallback_result(self, user_input: str, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Provide fallback result when processing fails"""
+        return {
+            "agent_id": self.agent_id,
+            "market_analysis": {
+                "relevant_categories": [{"category": "General", "market_share": 10, "growth_rate": 5.0, "relevance_score": 0.5, "reasoning": "Fallback analysis"}],
+                "selected_skills": [{"skill": "General Analysis", "category": "General", "relevance_score": 0.5, "reasoning": "Fallback skill"}],
+                "overall_analysis": "Fallback analysis due to processing error",
+                "processing_time": 0.01,
+                "method": "fallback"
+            },
+            "skill_classification": {
+                "skill_probabilities": {"general_analysis": 0.5},
+                "top_skills": [{"skill": "general_analysis", "probability": 0.5, "confidence": "low"}],
+                "classification_reasoning": "Fallback classification due to processing error",
+                "processing_time": 0.01,
+                "method": "fallback"
+            },
+            "identified_skills": [{"skill": "General Analysis", "category": "General", "probability": 0.5, "source": "fallback"}],
+            "processing_time": 0.02,
+            "confidence_score": 0.3,
+            "error_handled": True
+        }
+
+# Factory function for easy instantiation
+def create_skills_identification_agent(llm_router=None):
+    return SkillsIdentificationAgent(llm_router)

src/agents/synthesis_agent.py

@@ -0,0 +1,735 @@
+"""
+Enhanced Synthesis Agent with Expert Consultant Assignment
+Based on skill probability scores from Skills Identification Agent
+"""
+
+import logging
+import json
+from typing import Dict, List, Any, Optional, Tuple
+from datetime import datetime
+import re
+
+logger = logging.getLogger(__name__)
+
+
+class ExpertConsultantAssigner:
+    """
+    Assigns expert consultant profiles based on skill probabilities
+    and generates weighted expertise for response synthesis
+    """
+    
+    # Expert consultant profiles with skill mappings
+    EXPERT_PROFILES = {
+        "data_analysis": {
+            "title": "Senior Data Analytics Consultant",
+            "expertise": ["Statistical Analysis", "Data Visualization", "Business Intelligence", "Predictive Modeling"],
+            "background": "15+ years in data science across finance, healthcare, and tech sectors",
+            "style": "methodical, evidence-based, quantitative reasoning"
+        },
+        "technical_programming": {
+            "title": "Principal Software Engineering Consultant", 
+            "expertise": ["Full-Stack Development", "System Architecture", "DevOps", "Code Optimization"],
+            "background": "20+ years leading technical teams at Fortune 500 companies",
+            "style": "practical, solution-oriented, best practices focused"
+        },
+        "project_management": {
+            "title": "Strategic Project Management Consultant",
+            "expertise": ["Agile/Scrum", "Risk Management", "Stakeholder Communication", "Resource Optimization"],
+            "background": "12+ years managing complex enterprise projects across industries",
+            "style": "structured, process-driven, outcome-focused"
+        },
+        "financial_analysis": {
+            "title": "Executive Financial Strategy Consultant",
+            "expertise": ["Financial Modeling", "Investment Analysis", "Risk Assessment", "Corporate Finance"],
+            "background": "18+ years in investment banking and corporate finance advisory",
+            "style": "analytical, risk-aware, ROI-focused"
+        },
+        "digital_marketing": {
+            "title": "Chief Marketing Strategy Consultant",
+            "expertise": ["Digital Campaign Strategy", "Customer Analytics", "Brand Development", "Growth Hacking"],
+            "background": "14+ years scaling marketing for startups to enterprise clients",
+            "style": "creative, data-driven, customer-centric"
+        },
+        "business_consulting": {
+            "title": "Senior Management Consultant",
+            "expertise": ["Strategic Planning", "Organizational Development", "Process Improvement", "Change Management"],
+            "background": "16+ years at top-tier consulting firms (McKinsey, BCG equivalent)",
+            "style": "strategic, framework-driven, holistic thinking"
+        },
+        "cybersecurity": {
+            "title": "Chief Information Security Consultant",
+            "expertise": ["Threat Assessment", "Security Architecture", "Compliance", "Incident Response"],
+            "background": "12+ years protecting critical infrastructure across government and private sectors",
+            "style": "security-first, compliance-aware, risk mitigation focused"
+        },
+        "healthcare_technology": {
+            "title": "Healthcare Innovation Consultant",
+            "expertise": ["Health Informatics", "Telemedicine", "Medical Device Integration", "HIPAA Compliance"],
+            "background": "10+ years implementing healthcare technology solutions",
+            "style": "patient-centric, regulation-compliant, evidence-based"
+        },
+        "educational_technology": {
+            "title": "Learning Technology Strategy Consultant",
+            "expertise": ["Instructional Design", "EdTech Implementation", "Learning Analytics", "Curriculum Development"],
+            "background": "13+ years transforming educational experiences through technology",
+            "style": "learner-focused, pedagogy-driven, accessibility-minded"
+        },
+        "environmental_science": {
+            "title": "Sustainability Strategy Consultant",
+            "expertise": ["Environmental Impact Assessment", "Carbon Footprint Analysis", "Green Technology", "ESG Reporting"],
+            "background": "11+ years driving environmental initiatives for corporations",
+            "style": "sustainability-focused, data-driven, long-term thinking"
+        }
+    }
+    
+    def assign_expert_consultant(self, skill_probabilities: Dict[str, float]) -> Dict[str, Any]:
+        """
+        Create ultra-expert profile combining all relevant consultants
+        
+        Args:
+            skill_probabilities: Dict mapping skill categories to probability scores (0.0-1.0)
+            
+        Returns:
+            Dict containing ultra-expert profile with combined expertise
+        """
+        if not skill_probabilities:
+            return self._get_default_consultant()
+        
+        # Calculate weighted scores for available expert profiles
+        expert_scores = {}
+        total_weight = 0
+        
+        for skill, probability in skill_probabilities.items():
+            if skill in self.EXPERT_PROFILES and probability >= 0.2:  # 20% threshold
+                expert_scores[skill] = probability
+                total_weight += probability
+        
+        if not expert_scores:
+            return self._get_default_consultant()
+        
+        # Create ultra-expert combining all relevant consultants
+        ultra_expert = self._create_ultra_expert(expert_scores, total_weight)
+        
+        return {
+            "assigned_consultant": ultra_expert,
+            "expertise_weights": expert_scores,
+            "total_weight": total_weight,
+            "assignment_rationale": self._generate_ultra_expert_rationale(expert_scores, total_weight)
+        }
+    
+    def _get_default_consultant(self) -> Dict[str, Any]:
+        """Default consultant for general inquiries"""
+        return {
+            "assigned_consultant": {
+                "primary_expertise": "business_consulting",
+                "title": "Senior Management Consultant",
+                "expertise": ["Strategic Planning", "Problem Solving", "Analysis", "Communication"],
+                "background": "Generalist consultant with broad industry experience",
+                "style": "balanced, analytical, comprehensive",
+                "secondary_expertise": [],
+                "confidence_score": 0.7
+            },
+            "expertise_weights": {"business_consulting": 0.7},
+            "total_weight": 0.7,
+            "assignment_rationale": "Default consultant assigned for general business inquiry"
+        }
+    
+    def _create_ultra_expert(self, expert_scores: Dict[str, float], total_weight: float) -> Dict[str, Any]:
+        """Create ultra-expert profile combining all relevant consultants"""
+        
+        # Sort skills by probability (highest first)
+        sorted_skills = sorted(expert_scores.items(), key=lambda x: x[1], reverse=True)
+        
+        # Combine all expertise areas with weights
+        combined_expertise = []
+        combined_background_elements = []
+        combined_style_elements = []
+        
+        for skill, weight in sorted_skills:
+            if skill in self.EXPERT_PROFILES:
+                profile = self.EXPERT_PROFILES[skill]
+                
+                # Weight-based contribution
+                contribution_ratio = weight / total_weight
+                
+                # Add expertise areas with weight indicators
+                for expertise in profile["expertise"]:
+                    weighted_expertise = f"{expertise} (Weight: {contribution_ratio:.1%})"
+                    combined_expertise.append(weighted_expertise)
+                
+                # Extract background years and combine
+                background = profile["background"]
+                combined_background_elements.append(f"{background} [{skill}]")
+                
+                # Combine style elements
+                style_parts = [s.strip() for s in profile["style"].split(",")]
+                combined_style_elements.extend(style_parts)
+        
+        # Create ultra-expert title combining top skills
+        top_skills = [skill.replace("_", " ").title() for skill, _ in sorted_skills[:3]]
+        ultra_title = f"Visionary Ultra-Expert: {' + '.join(top_skills)} Integration Specialist"
+        
+        # Combine backgrounds into comprehensive experience
+        total_years = sum([self._extract_years_from_background(bg) for bg in combined_background_elements])
+        ultra_background = f"{total_years}+ years combined experience across {len(sorted_skills)} domains: " + \
+                          "; ".join(combined_background_elements[:3])  # Limit for readability
+        
+        # Create unified style combining all approaches
+        unique_styles = list(set(combined_style_elements))
+        ultra_style = ", ".join(unique_styles[:6])  # Top 6 style elements
+        
+        return {
+            "primary_expertise": "ultra_expert_integration",
+            "title": ultra_title,
+            "expertise": combined_expertise,
+            "background": ultra_background,
+            "style": ultra_style,
+            "domain_integration": sorted_skills,
+            "confidence_score": total_weight / len(sorted_skills),  # Average confidence
+            "ultra_expert": True,
+            "expertise_count": len(sorted_skills),
+            "total_experience_years": total_years
+        }
+    
+    def _extract_years_from_background(self, background: str) -> int:
+        """Extract years of experience from background string"""
+        years_match = re.search(r'(\d+)\+?\s*years?', background.lower())
+        return int(years_match.group(1)) if years_match else 10  # Default to 10 years
+    
+    def _generate_ultra_expert_rationale(self, expert_scores: Dict[str, float], total_weight: float) -> str:
+        """Generate explanation for ultra-expert assignment"""
+        sorted_skills = sorted(expert_scores.items(), key=lambda x: x[1], reverse=True)
+        
+        rationale_parts = [
+            f"Ultra-Expert Profile combining {len(sorted_skills)} specialized domains",
+            f"Total expertise weight: {total_weight:.2f} across integrated skill areas"
+        ]
+        
+        # Add top 3 contributions
+        top_contributions = []
+        for skill, weight in sorted_skills[:3]:
+            contribution = (weight / total_weight) * 100
+            top_contributions.append(f"{skill} ({weight:.1%}, {contribution:.0f}% contribution)")
+        
+        rationale_parts.append(f"Primary domains: {'; '.join(top_contributions)}")
+        
+        if len(sorted_skills) > 3:
+            additional_count = len(sorted_skills) - 3
+            rationale_parts.append(f"Plus {additional_count} additional specialized areas")
+        
+        return " | ".join(rationale_parts)
+
+
+class EnhancedSynthesisAgent:
+    """
+    Enhanced synthesis agent with expert consultant assignment
+    Compatible with existing ResponseSynthesisAgent interface
+    """
+    
+    def __init__(self, llm_router, agent_id: str = "RESP_SYNTH_001"):
+        self.llm_router = llm_router
+        self.agent_id = agent_id
+        self.specialization = "Multi-source information integration and coherent response generation"
+        self.expert_assigner = ExpertConsultantAssigner()
+        self._current_user_input = None
+        
+    async def execute(self, user_input: str = None, agent_outputs: List[Dict[str, Any]] = None, 
+                     context: Dict[str, Any] = None, skills_result: Dict[str, Any] = None,
+                     **kwargs) -> Dict[str, Any]:
+        """
+        Execute synthesis with expert consultant assignment
+        Compatible with both old interface (agent_outputs first) and new interface (user_input first)
+        
+        Args:
+            user_input: Original user question
+            agent_outputs: Results from other agents (can be first positional arg for compatibility)
+            context: Conversation context
+            skills_result: Output from skills identification agent
+            
+        Returns:
+            Dict containing synthesized response and metadata
+        """
+        # Handle backward compatibility and normalize arguments
+        # Case 1: First arg is agent_outputs (old interface)
+        if isinstance(user_input, list) and agent_outputs is None:
+            agent_outputs = user_input
+            user_input = kwargs.get('user_input', '')
+            context = kwargs.get('context', context)
+            skills_result = kwargs.get('skills_result', skills_result)
+        # Case 2: All args via kwargs
+        elif user_input is None:
+            user_input = kwargs.get('user_input', '')
+            agent_outputs = kwargs.get('agent_outputs', agent_outputs)
+            context = kwargs.get('context', context)
+            skills_result = kwargs.get('skills_result', skills_result)
+        
+        # Ensure user_input is a string
+        if not isinstance(user_input, str):
+            user_input = str(user_input) if user_input else ''
+        
+        # Default agent_outputs to empty list and normalize format
+        if agent_outputs is None:
+            agent_outputs = []
+        
+        # Normalize agent_outputs: convert dict to list if needed
+        if isinstance(agent_outputs, dict):
+            # Convert dict {task_name: result} to list of dicts
+            normalized_outputs = []
+            for task_name, result in agent_outputs.items():
+                if isinstance(result, dict):
+                    # Add task name to the result dict for context
+                    result_with_task = result.copy()
+                    result_with_task['task_name'] = task_name
+                    normalized_outputs.append(result_with_task)
+                else:
+                    # Wrap non-dict results
+                    normalized_outputs.append({
+                        'task_name': task_name,
+                        'content': str(result),
+                        'result': str(result)
+                    })
+            agent_outputs = normalized_outputs
+        
+        # Ensure it's a list
+        if not isinstance(agent_outputs, list):
+            agent_outputs = [agent_outputs] if agent_outputs else []
+        
+        logger.info(f"{self.agent_id} synthesizing {len(agent_outputs)} agent outputs")
+        if context:
+            interaction_count = len(context.get('interaction_contexts', [])) if context else 0
+            logger.info(f"{self.agent_id} context has {interaction_count} interaction contexts")
+            
+        # STEP 1: Extract skill probabilities from skills_result
+        skill_probabilities = self._extract_skill_probabilities(skills_result)
+        logger.info(f"Extracted skill probabilities: {skill_probabilities}")
+        
+        # STEP 2: Assign expert consultant based on probabilities
+        consultant_assignment = self.expert_assigner.assign_expert_consultant(skill_probabilities)
+        assigned_consultant = consultant_assignment["assigned_consultant"]
+        logger.info(f"Assigned consultant: {assigned_consultant['title']} ({assigned_consultant.get('primary_expertise', 'N/A')})")
+        
+        # STEP 3: Generate expert consultant preamble
+        expert_preamble = self._generate_expert_preamble(assigned_consultant, consultant_assignment)
+        
+        # STEP 4: Build synthesis prompt with expert context
+        synthesis_prompt = self._build_synthesis_prompt_with_expert(
+            user_input=user_input,
+            context=context,
+            agent_outputs=agent_outputs,
+            expert_preamble=expert_preamble,
+            assigned_consultant=assigned_consultant
+        )
+        
+        logger.info(f"{self.agent_id} calling LLM for response synthesis")
+        
+        # Call LLM with enhanced prompt
+        try:
+            response = await self.llm_router.route_inference(
+                task_type="response_synthesis",
+                prompt=synthesis_prompt,
+                max_tokens=2000,
+                temperature=0.7
+            )
+            
+            # Only use fallback if LLM actually fails (returns None, empty, or invalid)
+            if not response or not isinstance(response, str) or len(response.strip()) == 0:
+                logger.warning(f"{self.agent_id} LLM returned empty/invalid response, using fallback")
+                return self._get_fallback_response(user_input, agent_outputs, assigned_consultant)
+            
+            clean_response = response.strip()
+            logger.info(f"{self.agent_id} received LLM response (length: {len(clean_response)})")
+            
+            # Build comprehensive result compatible with existing interface
+            result = {
+                "synthesized_response": clean_response,
+                "draft_response": clean_response,
+                "final_response": clean_response,  # Main response field - used by UI
+                "assigned_consultant": assigned_consultant,
+                "expertise_weights": consultant_assignment["expertise_weights"],
+                "assignment_rationale": consultant_assignment["assignment_rationale"],
+                "source_references": self._extract_source_references(agent_outputs),
+                "coherence_score": 0.90,
+                "improvement_opportunities": self._identify_improvements(clean_response),
+                "synthesis_method": "expert_enhanced_llm",
+                "agent_id": self.agent_id,
+                "synthesis_quality_metrics": self._calculate_quality_metrics({"final_response": clean_response}),
+                "synthesis_metadata": {
+                    "agent_outputs_count": len(agent_outputs),
+                    "context_interactions": len(context.get('interaction_contexts', [])) if context else 0,
+                    "user_context_available": bool(context.get('user_context', '')) if context else False,
+                    "expert_enhanced": True,
+                    "processing_timestamp": datetime.now().isoformat()
+                }
+            }
+            
+            # Add intent alignment if available
+            intent_info = self._extract_intent_info(agent_outputs)
+            if intent_info:
+                result["intent_alignment"] = self._check_intent_alignment(result, intent_info)
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"{self.agent_id} synthesis failed: {str(e)}", exc_info=True)
+            return self._get_fallback_response(user_input, agent_outputs, assigned_consultant)
+    
+    def _extract_skill_probabilities(self, skills_result: Dict[str, Any]) -> Dict[str, float]:
+        """Extract skill probabilities from skills identification result"""
+        if not skills_result:
+            return {}
+        
+        # Check for skill_classification structure
+        skill_classification = skills_result.get('skill_classification', {})
+        if 'skill_probabilities' in skill_classification:
+            return skill_classification['skill_probabilities']
+        
+        # Check for direct skill_probabilities
+        if 'skill_probabilities' in skills_result:
+            return skills_result['skill_probabilities']
+        
+        # Extract from identified_skills if structured differently
+        identified_skills = skills_result.get('identified_skills', [])
+        if isinstance(identified_skills, list):
+            probabilities = {}
+            for skill in identified_skills:
+                if isinstance(skill, dict) and 'skill' in skill and 'probability' in skill:
+                    # Map skill name to expert profile name if needed
+                    skill_name = skill['skill']
+                    probability = skill['probability']
+                    probabilities[skill_name] = probability
+                elif isinstance(skill, dict) and 'category' in skill:
+                    skill_name = skill['category']
+                    probability = skill.get('probability', skill.get('confidence', 0.5))
+                    probabilities[skill_name] = probability
+            return probabilities
+        
+        return {}
+    
+    def _generate_expert_preamble(self, assigned_consultant: Dict[str, Any], 
+                                 consultant_assignment: Dict[str, Any]) -> str:
+        """Generate expert consultant preamble for LLM prompt"""
+        
+        if assigned_consultant.get('ultra_expert'):
+            # Ultra-expert preamble
+            preamble = f"""You are responding as a {assigned_consultant['title']} - an unprecedented combination of industry-leading experts.
+
+ULTRA-EXPERT PROFILE:
+- Integrated Expertise: {assigned_consultant['expertise_count']} specialized domains
+- Combined Experience: {assigned_consultant['total_experience_years']}+ years across multiple industries
+- Integration Approach: Cross-domain synthesis with deep specialization
+- Response Style: {assigned_consultant['style']}
+
+DOMAIN INTEGRATION: {', '.join([f"{skill} ({weight:.1%})" for skill, weight in assigned_consultant['domain_integration']])}
+
+SPECIALIZED EXPERTISE AREAS:
+{chr(10).join([f"• {expertise}" for expertise in assigned_consultant['expertise'][:8]])}
+
+ASSIGNMENT RATIONALE: {consultant_assignment['assignment_rationale']}
+
+KNOWLEDGE DEPTH REQUIREMENT: 
+- Provide insights equivalent to a visionary thought leader combining expertise from multiple domains
+- Synthesize knowledge across {assigned_consultant['expertise_count']} specialization areas
+- Apply interdisciplinary thinking and cross-domain innovation
+- Leverage combined {assigned_consultant['total_experience_years']}+ years of integrated experience
+
+ULTRA-EXPERT RESPONSE GUIDELINES:
+- Draw from extensive cross-domain experience and pattern recognition
+- Provide multi-perspective analysis combining different expert viewpoints
+- Include interdisciplinary frameworks and innovative approaches
+- Acknowledge complexity while providing actionable, synthesized recommendations
+- Balance broad visionary thinking with deep domain-specific insights
+- Use integrative problem-solving that spans multiple expertise areas
+"""
+        else:
+            # Standard single expert preamble
+            preamble = f"""You are responding as a {assigned_consultant['title']} with the following profile:
+
+EXPERTISE PROFILE:
+- Primary Expertise: {assigned_consultant['primary_expertise']}
+- Core Skills: {', '.join(assigned_consultant['expertise'])}
+- Background: {assigned_consultant['background']}
+- Response Style: {assigned_consultant['style']}
+
+ASSIGNMENT RATIONALE: {consultant_assignment['assignment_rationale']}
+
+EXPERTISE WEIGHTS: {', '.join([f"{skill}: {weight:.1%}" for skill, weight in consultant_assignment['expertise_weights'].items()])}
+
+"""
+            
+            if assigned_consultant.get('secondary_expertise'):
+                preamble += f"SECONDARY EXPERTISE: {', '.join(assigned_consultant['secondary_expertise'])}\n"
+            
+            preamble += f"""
+KNOWLEDGE DEPTH REQUIREMENT: Provide insights equivalent to a highly experienced, industry-leading {assigned_consultant['title']} with deep domain expertise and practical experience.
+
+RESPONSE GUIDELINES:
+- Draw from extensive practical experience in your field
+- Provide industry-specific insights and best practices  
+- Include relevant frameworks, methodologies, or tools
+- Acknowledge complexity while remaining actionable
+- Balance theoretical knowledge with real-world application
+"""
+        
+        return preamble
+    
+    def _build_synthesis_prompt_with_expert(self, user_input: str, context: Dict[str, Any],
+                                          agent_outputs: List[Dict[str, Any]], 
+                                          expert_preamble: str,
+                                          assigned_consultant: Dict[str, Any]) -> str:
+        """Build synthesis prompt with expert consultant context"""
+        
+        # Build context section with summarization for long conversations
+        context_section = self._build_context_section(context)
+        
+        # Build agent outputs section if any
+        agent_outputs_section = ""
+        if agent_outputs:
+            # Handle both dict and list formats
+            if isinstance(agent_outputs, dict):
+                # Convert dict to list format
+                outputs_list = []
+                for task_name, result in agent_outputs.items():
+                    if isinstance(result, dict):
+                        outputs_list.append(result)
+                    else:
+                        # Wrap string/non-dict results in dict format
+                        outputs_list.append({
+                            'task': task_name,
+                            'content': str(result),
+                            'result': str(result)
+                        })
+                agent_outputs = outputs_list
+            
+            # Ensure it's a list now
+            if isinstance(agent_outputs, list):
+                agent_outputs_section = f"\n\nAgent Analysis Results:\n"
+                for i, output in enumerate(agent_outputs, 1):
+                    # Handle both dict and string outputs
+                    if isinstance(output, dict):
+                        output_text = output.get('content') or output.get('result') or output.get('final_response') or str(output)
+                    else:
+                        # If output is a string or other type
+                        output_text = str(output)
+                    agent_outputs_section += f"Agent {i}: {output_text}\n"
+            else:
+                # Fallback for unexpected types
+                agent_outputs_section = f"\n\nAgent Analysis Results:\n{str(agent_outputs)}\n"
+        
+        # Construct full prompt
+        prompt = f"""{expert_preamble}
+
+User Question: {user_input}
+
+{context_section}{agent_outputs_section}
+
+Instructions: Provide a comprehensive, helpful response that directly addresses the question from your expert perspective. If there's conversation context, use it to answer the current question appropriately. Be detailed, informative, and leverage your specialized expertise in {assigned_consultant.get('primary_expertise', 'general consulting')}.
+
+Response:"""
+        
+        return prompt
+    
+    def _build_context_section(self, context: Dict[str, Any]) -> str:
+        """Build context section with summarization for long conversations
+        
+        Uses Context Manager structure:
+        - combined_context: Pre-formatted context string (preferred)
+        - interaction_contexts: List of interaction summaries with 'summary' and 'timestamp'
+        - user_context: User persona summary string
+        """
+        if not context:
+            return ""
+        
+        # Prefer combined_context if available (pre-formatted by Context Manager)
+        # combined_context includes Session Context, User Context, and Interaction Contexts
+        combined_context = context.get('combined_context', '')
+        if combined_context:
+            # Use the pre-formatted context from Context Manager
+            # It already includes Session Context, User Context, and Interaction Contexts formatted
+            return f"\n\nConversation Context:\n{combined_context}"
+        
+        # Fallback: Build from individual components if combined_context not available
+        # All components are from cache
+        session_context = context.get('session_context', {})
+        session_summary = session_context.get('summary', '') if isinstance(session_context, dict) else ""
+        interaction_contexts = context.get('interaction_contexts', [])
+        user_context = context.get('user_context', '')
+        
+        context_section = ""
+        
+        # Add session context if available (from cache)
+        if session_summary:
+            context_section += f"\n\nSession Context (Session Summary):\n{session_summary[:500]}...\n"
+        # Add user context if available
+        if user_context:
+            context_section += f"\n\nUser Context (Persona Summary):\n{user_context[:500]}...\n"
+        
+        # Add interaction contexts
+        if interaction_contexts:
+            if len(interaction_contexts) <= 8:
+                # Show all interaction summaries for short conversations
+                context_section += "\n\nPrevious Conversation Summary:\n"
+                for i, ic in enumerate(interaction_contexts, 1):
+                    summary = ic.get('summary', '')
+                    if summary:
+                        context_section += f"  {i}. {summary}\n"
+            else:
+                # Summarize older interactions, show recent ones
+                recent_contexts = interaction_contexts[-8:]  # Last 8 interactions
+                older_contexts = interaction_contexts[:-8]   # Everything before last 8
+                
+                # Create summary of older interactions
+                summary = self._summarize_interaction_contexts(older_contexts)
+                
+                context_section += f"\n\nConversation Summary (earlier context):\n{summary}\n\nRecent Conversation:\n"
+                
+                for i, ic in enumerate(recent_contexts, 1):
+                    summary_text = ic.get('summary', '')
+                    if summary_text:
+                        context_section += f"  {i}. {summary_text}\n"
+        
+        return context_section
+    
+    def _summarize_interaction_contexts(self, interaction_contexts: List[Dict[str, Any]]) -> str:
+        """Summarize older interaction contexts to preserve key context
+        
+        Uses Context Manager structure where interaction_contexts contains:
+        - summary: 50-token interaction summary string
+        - timestamp: Interaction timestamp
+        """
+        if not interaction_contexts:
+            return "No prior context."
+        
+        # Extract key topics and themes from summaries
+        topics = []
+        key_points = []
+        
+        for ic in interaction_contexts:
+            summary = ic.get('summary', '')
+            
+            if summary:
+                # Extract topics from summary (simple keyword extraction)
+                # Summaries are already condensed, so extract meaningful terms
+                words = summary.lower().split()
+                key_terms = [word for word in words if len(word) > 4][:3]
+                topics.extend(key_terms)
+                
+                # Use summary as key point (already a summary)
+                key_points.append(summary[:150])
+        
+        # Build summary
+        unique_topics = list(set(topics))[:5]  # Top 5 unique topics
+        recent_points = key_points[-5:]  # Last 5 key points
+        
+        summary_text = f"Topics discussed: {', '.join(unique_topics) if unique_topics else 'General discussion'}\n"
+        summary_text += f"Key points: {' | '.join(recent_points) if recent_points else 'No specific points'}"
+        
+        return summary_text
+    
+    def _summarize_interactions(self, interactions: List[Dict[str, Any]]) -> str:
+        """Legacy method for backward compatibility - delegates to _summarize_interaction_contexts"""
+        # Convert old format to new format if needed
+        if interactions and 'summary' in interactions[0]:
+            # Already in new format
+            return self._summarize_interaction_contexts(interactions)
+        else:
+            # Old format - convert
+            interaction_contexts = []
+            for interaction in interactions:
+                user_input = interaction.get('user_input', '')
+                assistant_response = interaction.get('assistant_response') or interaction.get('response', '')
+                # Create a simple summary
+                summary = f"User asked: {user_input[:100]}..." if user_input else ""
+                if summary:
+                    interaction_contexts.append({'summary': summary})
+            return self._summarize_interaction_contexts(interaction_contexts)
+    
+    def _extract_intent_info(self, agent_outputs: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Extract intent information from agent outputs"""
+        for output in agent_outputs:
+            if 'primary_intent' in output:
+                return {
+                    'primary_intent': output['primary_intent'],
+                    'confidence': output.get('confidence_scores', {}).get(output['primary_intent'], 0.5),
+                    'source_agent': output.get('agent_id', 'unknown')
+                }
+        return None
+    
+    def _extract_source_references(self, agent_outputs: List[Dict[str, Any]]) -> List[str]:
+        """Extract source references from agent outputs"""
+        sources = []
+        for output in agent_outputs:
+            agent_id = output.get('agent_id', 'unknown')
+            sources.append(agent_id)
+        return list(set(sources))  # Remove duplicates
+    
+    def _calculate_quality_metrics(self, synthesis_result: Dict[str, Any]) -> Dict[str, Any]:
+        """Calculate quality metrics for synthesis"""
+        response = synthesis_result.get('final_response', '')
+        
+        return {
+            "length": len(response),
+            "word_count": len(response.split()) if response else 0,
+            "coherence_score": synthesis_result.get('coherence_score', 0.7),
+            "source_count": len(synthesis_result.get('source_references', [])),
+            "has_structured_elements": bool(re.search(r'[•\d+\.]', response)) if response else False
+        }
+    
+    def _check_intent_alignment(self, synthesis_result: Dict[str, Any], intent_info: Dict[str, Any]) -> Dict[str, Any]:
+        """Check if synthesis aligns with detected intent"""
+        # Calculate alignment based on intent confidence and response quality
+        intent_confidence = intent_info.get('confidence', 0.5)
+        coherence_score = synthesis_result.get('coherence_score', 0.7)
+        # Alignment is average of intent confidence and coherence
+        alignment_score = (intent_confidence + coherence_score) / 2.0
+        
+        return {
+            "intent_detected": intent_info.get('primary_intent'),
+            "alignment_score": alignment_score,
+            "alignment_verified": alignment_score > 0.7
+        }
+    
+    def _identify_improvements(self, response: str) -> List[str]:
+        """Identify opportunities to improve the response"""
+        improvements = []
+        
+        if len(response) < 50:
+            improvements.append("Could be more detailed")
+        
+        if "?" not in response and len(response.split()) < 100:
+            improvements.append("Consider adding examples")
+        
+        return improvements
+    
+    def _get_fallback_response(self, user_input: str, agent_outputs: List[Dict[str, Any]], 
+                               assigned_consultant: Dict[str, Any]) -> Dict[str, Any]:
+        """Provide fallback response when synthesis fails (LLM API failure only)"""
+        # Only use fallback when LLM API actually fails - not as default
+        if user_input:
+            fallback_text = f"Thank you for your question: '{user_input}'. I'm processing your request and will provide a detailed response shortly."
+        else:
+            fallback_text = "I apologize, but I encountered an issue processing your request. Please try again."
+        
+        return {
+            "synthesized_response": fallback_text,
+            "draft_response": fallback_text,
+            "final_response": fallback_text,
+            "assigned_consultant": assigned_consultant,
+            "source_references": self._extract_source_references(agent_outputs),
+            "coherence_score": 0.5,
+            "improvement_opportunities": ["LLM API error - fallback activated"],
+            "synthesis_method": "expert_enhanced_fallback",
+            "agent_id": self.agent_id,
+            "synthesis_quality_metrics": self._calculate_quality_metrics({"final_response": fallback_text}),
+            "error": True,
+            "synthesis_metadata": {"expert_enhanced": True, "error": True, "llm_api_failed": True}
+        }
+
+
+# Backward compatibility: ResponseSynthesisAgent is now EnhancedSynthesisAgent
+ResponseSynthesisAgent = EnhancedSynthesisAgent
+
+
+# Factory function for compatibility
+def create_synthesis_agent(llm_router) -> EnhancedSynthesisAgent:
+    """Factory function to create enhanced synthesis agent"""
+    return EnhancedSynthesisAgent(llm_router)

src/config.py

@@ -0,0 +1,42 @@
+# config.py
+import os
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # HF Spaces specific settings
+    hf_token: str = os.getenv("HF_TOKEN", "")
+    hf_cache_dir: str = os.getenv("HF_HOME", "/tmp/huggingface")
+    
+    # Model settings
+    default_model: str = "mistralai/Mistral-7B-Instruct-v0.2"
+    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    classification_model: str = "cardiffnlp/twitter-roberta-base-emotion"
+    
+    # Performance settings
+    max_workers: int = int(os.getenv("MAX_WORKERS", "4"))
+    cache_ttl: int = int(os.getenv("CACHE_TTL", "3600"))
+    
+    # Database settings
+    db_path: str = os.getenv("DB_PATH", "sessions.db")
+    faiss_index_path: str = os.getenv("FAISS_INDEX_PATH", "embeddings.faiss")
+    
+    # Session settings
+    session_timeout: int = int(os.getenv("SESSION_TIMEOUT", "3600"))
+    max_session_size_mb: int = int(os.getenv("MAX_SESSION_SIZE_MB", "10"))
+    
+    # Mobile optimization settings
+    mobile_max_tokens: int = int(os.getenv("MOBILE_MAX_TOKENS", "800"))
+    mobile_timeout: int = int(os.getenv("MOBILE_TIMEOUT", "15000"))
+    
+    # Gradio settings
+    gradio_port: int = int(os.getenv("GRADIO_PORT", "7860"))
+    gradio_host: str = os.getenv("GRADIO_HOST", "0.0.0.0")
+    
+    # Logging settings
+    log_level: str = os.getenv("LOG_LEVEL", "INFO")
+    log_format: str = os.getenv("LOG_FORMAT", "json")
+    
+    class Config:
+        env_file = ".env"
+
+settings = Settings()

src/context_manager.py

@@ -0,0 +1,1695 @@
+# context_manager.py
+import sqlite3
+import json
+import logging
+import uuid
+import hashlib
+import threading
+import time
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from typing import Dict, Optional, List
+
+logger = logging.getLogger(__name__)
+
+
+class TransactionManager:
+    """Manage database transactions with proper locking"""
+    
+    def __init__(self, db_path):
+        self.db_path = db_path
+        self._lock = threading.RLock()
+        self._connections = {}
+    
+    @contextmanager
+    def transaction(self, session_id=None):
+        """Context manager for database transactions with automatic rollback"""
+        conn = None
+        cursor = None
+        
+        try:
+            with self._lock:
+                conn = sqlite3.connect(self.db_path, isolation_level='IMMEDIATE')
+                conn.execute('PRAGMA journal_mode=WAL')  # Write-Ahead Logging for better concurrency
+                conn.execute('PRAGMA busy_timeout=5000')  # 5 second timeout for locks
+                cursor = conn.cursor()
+                
+                yield cursor
+                
+                conn.commit()
+                logger.debug(f"Transaction committed for session {session_id}")
+                
+        except Exception as e:
+            if conn:
+                conn.rollback()
+                logger.error(f"Transaction rolled back for session {session_id}: {e}")
+            raise
+        finally:
+            if conn:
+                conn.close()
+
+class EfficientContextManager:
+    def __init__(self, llm_router=None):
+        self.session_cache = {}  # In-memory for active sessions
+        self._session_cache = {}  # Enhanced in-memory cache with timestamps
+        self.cache_config = {
+            "max_session_size": 10,  # MB per session
+            "ttl": 3600,  # 1 hour
+            "compression": "gzip",
+            "eviction_policy": "LRU"
+        }
+        self.db_path = "sessions.db"
+        self.llm_router = llm_router  # For generating context summaries
+        logger.info(f"Initializing ContextManager with DB path: {self.db_path}")
+        self.transaction_manager = TransactionManager(self.db_path)
+        self._init_database()
+        self.optimize_database_indexes()
+    
+    def _init_database(self):
+        """Initialize database and create tables"""
+        try:
+            logger.info("Initializing database...")
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Create sessions table if not exists
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS sessions (
+                    session_id TEXT PRIMARY KEY,
+                    user_id TEXT DEFAULT 'Test_Any',
+                    created_at TIMESTAMP,
+                    last_activity TIMESTAMP,
+                    context_data TEXT,
+                    user_metadata TEXT
+                )
+            """)
+            
+            # Add user_id column to existing sessions table if it doesn't exist
+            try:
+                cursor.execute("ALTER TABLE sessions ADD COLUMN user_id TEXT DEFAULT 'Test_Any'")
+                logger.info("✓ Added user_id column to sessions table")
+            except sqlite3.OperationalError:
+                # Column already exists
+                pass
+            
+            logger.info("✓ Sessions table ready")
+            
+            # Create interactions table
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS interactions (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT REFERENCES sessions(session_id),
+                    user_input TEXT,
+                    context_snapshot TEXT,
+                    created_at TIMESTAMP,
+                    FOREIGN KEY(session_id) REFERENCES sessions(session_id)
+                )
+            """)
+            logger.info("✓ Interactions table ready")
+            
+            # Create user_contexts table (persistent user persona summaries)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS user_contexts (
+                    user_id TEXT PRIMARY KEY,
+                    persona_summary TEXT,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+            logger.info("✓ User contexts table ready")
+            
+            # Create session_contexts table (session summaries)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS session_contexts (
+                    session_id TEXT PRIMARY KEY,
+                    user_id TEXT,
+                    session_summary TEXT,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY(session_id) REFERENCES sessions(session_id),
+                    FOREIGN KEY(user_id) REFERENCES user_contexts(user_id)
+                )
+            """)
+            logger.info("✓ Session contexts table ready")
+            
+            # Create interaction_contexts table (individual interaction summaries)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS interaction_contexts (
+                    interaction_id TEXT PRIMARY KEY,
+                    session_id TEXT,
+                    user_input TEXT,
+                    system_response TEXT,
+                    interaction_summary TEXT,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY(session_id) REFERENCES sessions(session_id)
+                )
+            """)
+            logger.info("✓ Interaction contexts table ready")
+            
+            conn.commit()
+            conn.close()
+            
+            # Update schema with new columns and tables for user change tracking
+            self._update_database_schema()
+            
+            logger.info("Database initialization complete")
+            
+        except Exception as e:
+            logger.error(f"Database initialization error: {e}", exc_info=True)
+    
+    def _update_database_schema(self):
+        """Add missing columns and tables for user change tracking"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Add needs_refresh column to interaction_contexts
+            try:
+                cursor.execute("""
+                    ALTER TABLE interaction_contexts 
+                    ADD COLUMN needs_refresh INTEGER DEFAULT 0
+                """)
+                logger.info("✓ Added needs_refresh column to interaction_contexts")
+            except sqlite3.OperationalError:
+                pass  # Column already exists
+            
+            # Create user change log table
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS user_change_log (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT,
+                    old_user_id TEXT,
+                    new_user_id TEXT,
+                    timestamp TIMESTAMP,
+                    FOREIGN KEY(session_id) REFERENCES sessions(session_id)
+                )
+            """)
+            
+            conn.commit()
+            conn.close()
+            logger.info("✓ Database schema updated successfully for user change tracking")
+            
+            # Update interactions table for deduplication
+            self._update_interactions_table()
+            
+        except Exception as e:
+            logger.error(f"Schema update error: {e}", exc_info=True)
+    
+    def _update_interactions_table(self):
+        """Add interaction_hash column for deduplication"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Check if column already exists
+            cursor.execute("PRAGMA table_info(interactions)")
+            columns = [row[1] for row in cursor.fetchall()]
+            
+            # Add interaction_hash column if it doesn't exist
+            if 'interaction_hash' not in columns:
+                try:
+                    cursor.execute("""
+                        ALTER TABLE interactions 
+                        ADD COLUMN interaction_hash TEXT
+                    """)
+                    logger.info("✓ Added interaction_hash column to interactions table")
+                except sqlite3.OperationalError:
+                    pass  # Column already exists
+            
+            # Create unique index for deduplication (this enforces uniqueness)
+            try:
+                cursor.execute("""
+                    CREATE UNIQUE INDEX IF NOT EXISTS idx_interaction_hash_unique 
+                    ON interactions(interaction_hash)
+                """)
+                logger.info("✓ Created unique index on interaction_hash")
+            except sqlite3.OperationalError:
+                # Index might already exist, try non-unique index as fallback
+                cursor.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_interaction_hash 
+                    ON interactions(interaction_hash)
+                """)
+            
+            conn.commit()
+            conn.close()
+            logger.info("✓ Interactions table updated for deduplication")
+            
+        except Exception as e:
+            logger.error(f"Error updating interactions table: {e}", exc_info=True)
+    
+    async def manage_context(self, session_id: str, user_input: str, user_id: str = "Test_Any") -> dict:
+        """
+        Efficient context management with separated session/user caching
+        STEP 1: Fetch User Context (if available) 
+        STEP 2: Get Previous Interaction Contexts
+        STEP 3: Combine for workflow use
+        """
+        # Use session-only cache key to prevent user_id conflicts
+        session_cache_key = f"session_{session_id}"
+        user_cache_key = f"user_{user_id}"
+        
+        # Get session context from cache
+        session_context = self._get_from_memory_cache(session_cache_key)
+        
+        # Check if cached session context matches current user_id
+        # Handle both old and new cache formats
+        cached_entry = self.session_cache.get(session_cache_key)
+        if cached_entry:
+            # Extract actual context from cache entry
+            if isinstance(cached_entry, dict) and 'value' in cached_entry:
+                actual_context = cached_entry.get('value', {})
+            else:
+                actual_context = cached_entry
+            
+            if actual_context and actual_context.get("user_id") != user_id:
+                # User changed, invalidate session cache
+                logger.info(f"User mismatch in cache for session {session_id}, invalidating cache")
+                session_context = None
+                if session_cache_key in self.session_cache:
+                    del self.session_cache[session_cache_key]
+            else:
+                session_context = actual_context
+        
+        # Get user context separately
+        user_context = self._get_from_memory_cache(user_cache_key)
+        
+        if not session_context:
+            # Retrieve from database with user context
+            session_context = await self._retrieve_from_db(session_id, user_input, user_id)
+            
+            # Step 2: Cache session context with TTL
+            self.add_context_cache(session_cache_key, session_context, ttl=self.cache_config.get("ttl", 3600))
+        
+        # Handle user context separately - load only once and cache thereafter
+        # Cache does not refer to database after initial load
+        if not user_context or not user_context.get("user_context_loaded"):
+            user_context_data = await self.get_user_context(user_id)
+            user_context = {
+                "user_context": user_context_data,
+                "user_context_loaded": True,
+                "user_id": user_id
+            }
+            # Cache user context separately - this is the only database query for user context
+            self._warm_memory_cache(user_cache_key, user_context)
+            logger.debug(f"User context loaded once for {user_id} and cached")
+        else:
+            # User context already cached, use it without database query
+            logger.debug(f"Using cached user context for {user_id}")
+        
+        # Merge contexts without duplication
+        merged_context = {
+            **session_context,
+            "user_context": user_context.get("user_context", ""),
+            "user_context_loaded": True,
+            "user_id": user_id  # Ensure current user_id is used
+        }
+        
+        # Update context with new interaction
+        updated_context = self._update_context(merged_context, user_input, user_id=user_id)
+        
+        return self._optimize_context(updated_context)
+    
+    async def get_user_context(self, user_id: str) -> str:
+        """
+        STEP 1: Fetch or generate User Context (500-token persona summary)
+        Available for all interactions except first time per user
+        """
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Check if user context exists
+            cursor.execute("""
+                SELECT persona_summary FROM user_contexts WHERE user_id = ?
+            """, (user_id,))
+            
+            row = cursor.fetchone()
+            if row and row[0]:
+                # Existing user context found
+                conn.close()
+                logger.info(f"✓ User context loaded for {user_id}")
+                return row[0]
+            
+            # Generate new user context from all historical data
+            logger.info(f"Generating new user context for {user_id}")
+            
+            # Fetch all historical Session and Interaction contexts for this user
+            all_session_summaries = []
+            all_interaction_summaries = []
+            
+            # Get all session contexts
+            cursor.execute("""
+                SELECT session_summary FROM session_contexts WHERE user_id = ?
+                ORDER BY created_at DESC LIMIT 50
+            """, (user_id,))
+            for row in cursor.fetchall():
+                if row[0]:
+                    all_session_summaries.append(row[0])
+            
+            # Get all interaction contexts
+            cursor.execute("""
+                SELECT ic.interaction_summary 
+                FROM interaction_contexts ic
+                JOIN sessions s ON ic.session_id = s.session_id
+                WHERE s.user_id = ?
+                ORDER BY ic.created_at DESC LIMIT 100
+            """, (user_id,))
+            for row in cursor.fetchall():
+                if row[0]:
+                    all_interaction_summaries.append(row[0])
+            
+            conn.close()
+            
+            if not all_session_summaries and not all_interaction_summaries:
+                # First time user - no context to generate
+                logger.info(f"No historical data for {user_id} - first time user")
+                return ""
+            
+            # Generate persona summary using LLM (500 tokens)
+            historical_data = "\n\n".join(all_session_summaries + all_interaction_summaries[:20])
+            
+            if self.llm_router:
+                prompt = f"""Generate a concise 500-token persona summary for user {user_id} based on their interaction history:
+
+Historical Context:
+{historical_data}
+
+Create a persona summary that captures:
+- Communication style and preferences
+- Common topics and interests
+- Interaction patterns
+- Key information shared across sessions
+
+Keep the summary concise and focused (approximately 500 tokens)."""
+                
+                try:
+                    persona_summary = await self.llm_router.route_inference(
+                        task_type="general_reasoning",
+                        prompt=prompt,
+                        max_tokens=500,
+                        temperature=0.7
+                    )
+                    
+                    if persona_summary and isinstance(persona_summary, str) and persona_summary.strip():
+                        # Store in database
+                        conn = sqlite3.connect(self.db_path)
+                        cursor = conn.cursor()
+                        cursor.execute("""
+                            INSERT OR REPLACE INTO user_contexts (user_id, persona_summary, updated_at)
+                            VALUES (?, ?, ?)
+                        """, (user_id, persona_summary.strip(), datetime.now().isoformat()))
+                        conn.commit()
+                        conn.close()
+                        
+                        logger.info(f"✓ Generated and stored user context for {user_id}")
+                        return persona_summary.strip()
+                except Exception as e:
+                    logger.error(f"Error generating user context: {e}", exc_info=True)
+            
+            # Fallback: Return empty if LLM fails
+            logger.warning(f"Could not generate user context for {user_id} - using empty")
+            return ""
+            
+        except Exception as e:
+            logger.error(f"Error getting user context: {e}", exc_info=True)
+            return ""
+    
+    async def generate_interaction_context(self, interaction_id: str, session_id: str, 
+                                         user_input: str, system_response: str, 
+                                         user_id: str = "Test_Any") -> str:
+        """
+        STEP 2: Generate Interaction Context (50-token summary)
+        Called after each response
+        """
+        try:
+            if not self.llm_router:
+                return ""
+            
+            prompt = f"""Summarize this interaction in approximately 50 tokens:
+
+User Input: {user_input[:200]}
+System Response: {system_response[:300]}
+
+Provide a brief summary capturing the key exchange."""
+            
+            try:
+                summary = await self.llm_router.route_inference(
+                    task_type="general_reasoning",
+                    prompt=prompt,
+                    max_tokens=50,
+                    temperature=0.7
+                )
+                
+                if summary and isinstance(summary, str) and summary.strip():
+                    # Store in database
+                    conn = sqlite3.connect(self.db_path)
+                    cursor = conn.cursor()
+                    created_at = datetime.now().isoformat()
+                    cursor.execute("""
+                        INSERT OR REPLACE INTO interaction_contexts 
+                        (interaction_id, session_id, user_input, system_response, interaction_summary, created_at)
+                        VALUES (?, ?, ?, ?, ?, ?)
+                    """, (
+                        interaction_id, 
+                        session_id, 
+                        user_input[:500], 
+                        system_response[:1000],
+                        summary.strip(),
+                        created_at
+                    ))
+                    conn.commit()
+                    conn.close()
+                    
+                    # Update cache immediately with new interaction context
+                    # This ensures cache is synchronized with database at the same time
+                    self._update_cache_with_interaction_context(session_id, summary.strip(), created_at)
+                    
+                    logger.info(f"✓ Generated interaction context for {interaction_id} and updated cache")
+                    return summary.strip()
+            except Exception as e:
+                logger.error(f"Error generating interaction context: {e}", exc_info=True)
+            
+            # Fallback on LLM failure
+            return ""
+            
+        except Exception as e:
+            logger.error(f"Error in generate_interaction_context: {e}", exc_info=True)
+            return ""
+    
+    async def generate_session_context(self, session_id: str, user_id: str = "Test_Any") -> str:
+        """
+        Generate Session Context (100-token summary) at every turn
+        Uses cached interaction contexts instead of querying database
+        Updates both database and cache immediately
+        """
+        try:
+            # Get interaction contexts from cache (no database query)
+            session_cache_key = f"session_{session_id}"
+            cached_context = self.session_cache.get(session_cache_key)
+            
+            if not cached_context:
+                logger.warning(f"No cached context found for session {session_id}, cannot generate session context")
+                return ""
+            
+            interaction_contexts = cached_context.get('interaction_contexts', [])
+            
+            if not interaction_contexts:
+                logger.info(f"No interaction contexts available for session {session_id} to summarize")
+                return ""
+            
+            # Use cached interaction contexts (from cache, not database)
+            interaction_summaries = [ic.get('summary', '') for ic in interaction_contexts if ic.get('summary')]
+            
+            if not interaction_summaries:
+                logger.info(f"No interaction summaries available for session {session_id}")
+                return ""
+            
+            # Generate session summary using LLM (100 tokens)
+            if self.llm_router:
+                combined_context = "\n".join(interaction_summaries)
+                
+                prompt = f"""Summarize this session's interactions in approximately 100 tokens:
+
+Interaction Summaries:
+{combined_context}
+
+Create a concise session summary capturing:
+- Main topics discussed
+- Key outcomes or information shared
+- User's focus areas
+
+Keep the summary concise (approximately 100 tokens)."""
+                
+                try:
+                    session_summary = await self.llm_router.route_inference(
+                        task_type="general_reasoning",
+                        prompt=prompt,
+                        max_tokens=100,
+                        temperature=0.7
+                    )
+                    
+                    if session_summary and isinstance(session_summary, str) and session_summary.strip():
+                        # Store in database
+                        created_at = datetime.now().isoformat()
+                        conn = sqlite3.connect(self.db_path)
+                        cursor = conn.cursor()
+                        cursor.execute("""
+                            INSERT OR REPLACE INTO session_contexts 
+                            (session_id, user_id, session_summary, created_at)
+                            VALUES (?, ?, ?, ?)
+                        """, (session_id, user_id, session_summary.strip(), created_at))
+                        conn.commit()
+                        conn.close()
+                        
+                        # Update cache immediately with new session context
+                        # This ensures cache is synchronized with database at the same time
+                        self._update_cache_with_session_context(session_id, session_summary.strip(), created_at)
+                        
+                        logger.info(f"✓ Generated session context for {session_id} and updated cache")
+                        return session_summary.strip()
+                except Exception as e:
+                    logger.error(f"Error generating session context: {e}", exc_info=True)
+            
+            # Fallback on LLM failure
+            return ""
+            
+        except Exception as e:
+            logger.error(f"Error in generate_session_context: {e}", exc_info=True)
+            return ""
+    
+    async def end_session(self, session_id: str, user_id: str = "Test_Any"):
+        """
+        End session and clear cache
+        Note: Session context is already generated at every turn, so this just clears cache
+        """
+        try:
+            # Session context is already generated at every turn (no need to regenerate)
+            # Clear in-memory cache for this session (session-only key)
+            session_cache_key = f"session_{session_id}"
+            if session_cache_key in self.session_cache:
+                del self.session_cache[session_cache_key]
+                logger.info(f"✓ Cleared cache for session {session_id}")
+            
+        except Exception as e:
+            logger.error(f"Error ending session: {e}", exc_info=True)
+    
+    def _clear_user_cache_on_change(self, session_id: str, new_user_id: str, old_user_id: str):
+        """Clear cache entries when user changes"""
+        if new_user_id != old_user_id:
+            # Clear old composite cache keys
+            old_cache_key = f"{session_id}_{old_user_id}"
+            if old_cache_key in self.session_cache:
+                del self.session_cache[old_cache_key]
+                logger.info(f"Cleared old cache for user {old_user_id} on session {session_id}")
+    
+    def _optimize_context(self, context: dict, relevance_classification: Optional[Dict] = None) -> dict:
+        """
+        Optimize context for LLM consumption with relevance filtering support
+        Format: [Session Context] + [User Context (conditional)] + [Interaction Context #N, #N-1, ...]
+        
+        Args:
+            context: Base context dictionary
+            relevance_classification: Optional relevance classification results with dynamic user context
+        
+        Applies smart pruning before formatting.
+        """
+        # Step 4: Prune context if it exceeds token limits
+        pruned_context = self.prune_context(context, max_tokens=2000)
+        
+        # Get context mode (fresh or relevant)
+        session_id = pruned_context.get("session_id")
+        context_mode = self.get_context_mode(session_id)
+        
+        interaction_contexts = pruned_context.get("interaction_contexts", [])
+        session_context = pruned_context.get("session_context", {})
+        session_summary = session_context.get("summary", "") if isinstance(session_context, dict) else ""
+        
+        # MODIFIED: Conditional user context inclusion based on mode and relevance
+        user_context = ""
+        if context_mode == 'relevant' and relevance_classification:
+            # Use dynamic relevant summaries from relevance classification
+            user_context = relevance_classification.get('combined_user_context', '')
+            
+            if user_context:
+                logger.info(
+                    f"Using dynamic relevant context: {len(relevance_classification.get('relevant_summaries', []))} "
+                    f"sessions summarized for session {session_id}"
+                )
+        elif context_mode == 'relevant' and not relevance_classification:
+            # Fallback: Use traditional user context if relevance classification unavailable
+            user_context = pruned_context.get("user_context", "")
+            logger.debug(f"Relevant mode but no classification, using traditional user context")
+        # If context_mode == 'fresh', user_context remains empty (no user context)
+        
+        # Format interaction contexts as requested
+        formatted_interactions = []
+        for idx, ic in enumerate(interaction_contexts[:10]):  # Last 10 interactions
+            formatted_interactions.append(f"[Interaction Context #{len(interaction_contexts) - idx}]\n{ic.get('summary', '')}")
+        
+        # Combine Session Context + (Conditional) User Context + Interaction Contexts
+        combined_context = ""
+        if session_summary:
+            combined_context += f"[Session Context]\n{session_summary}\n\n"
+        
+        # Include user context only if available and in relevant mode
+        if user_context:
+            context_label = "[Relevant User Context]" if context_mode == 'relevant' else "[User Context]"
+            combined_context += f"{context_label}\n{user_context}\n\n"
+        
+        if formatted_interactions:
+            combined_context += "\n\n".join(formatted_interactions)
+        
+        return {
+            "session_id": pruned_context.get("session_id"),
+            "user_id": pruned_context.get("user_id", "Test_Any"),
+            "user_context": user_context,  # Dynamic summaries OR empty
+            "session_context": session_context,
+            "interaction_contexts": interaction_contexts,
+            "combined_context": combined_context,
+            "context_mode": context_mode,  # Include mode for debugging
+            "relevance_metadata": relevance_classification.get('relevance_scores', {}) if relevance_classification else {},
+            "preferences": pruned_context.get("preferences", {}),
+            "active_tasks": pruned_context.get("active_tasks", []),
+            "last_activity": pruned_context.get("last_activity")
+        }
+    
+    def _get_from_memory_cache(self, cache_key: str) -> dict:
+        """
+        Retrieve context from in-memory session cache with expiration check
+        """
+        cached = self.session_cache.get(cache_key)
+        if not cached:
+            return None
+        
+        # Check if it's the new format with expiration
+        if isinstance(cached, dict) and 'value' in cached:
+            # New format with TTL
+            if self._is_cache_expired(cached):
+                # Remove expired cache entry
+                del self.session_cache[cache_key]
+                logger.debug(f"Cache expired for key: {cache_key}")
+                return None
+            return cached.get('value')
+        else:
+            # Old format (direct value) - return as-is for backward compatibility
+            return cached
+    
+    def _is_cache_expired(self, cache_entry: dict) -> bool:
+        """
+        Check if cache entry has expired based on TTL
+        """
+        if not isinstance(cache_entry, dict):
+            return True
+        
+        expires = cache_entry.get('expires')
+        if not expires:
+            return False  # No expiration set, consider valid
+        
+        return time.time() > expires
+    
+    def add_context_cache(self, key: str, value: dict, ttl: int = 3600):
+        """
+        Step 2: Implement Context Caching with TTL expiration
+        
+        Add context to cache with expiration time.
+        
+        Args:
+            key: Cache key
+            value: Value to cache (dict)
+            ttl: Time to live in seconds (default 3600 = 1 hour)
+        """
+        import time
+        self.session_cache[key] = {
+            'value': value,
+            'expires': time.time() + ttl,
+            'timestamp': time.time()
+        }
+        logger.debug(f"Cached context for key: {key} with TTL: {ttl}s")
+    
+    def get_token_count(self, text: str) -> int:
+        """
+        Approximate token count for text (4 characters ≈ 1 token)
+        
+        Args:
+            text: Text to count tokens for
+            
+        Returns:
+            Approximate token count
+        """
+        if not text:
+            return 0
+        # Simple approximation: 4 characters per token
+        return len(text) // 4
+    
+    def prune_context(self, context: dict, max_tokens: int = 2000) -> dict:
+        """
+        Step 4: Implement Smart Context Pruning
+        
+        Prune context to stay within token limit while keeping most recent and relevant content.
+        
+        Args:
+            context: Context dictionary to prune
+            max_tokens: Maximum token count (default 2000)
+            
+        Returns:
+            Pruned context dictionary
+        """
+        try:
+            # Calculate current token count
+            current_tokens = self._calculate_context_tokens(context)
+            
+            if current_tokens <= max_tokens:
+                return context  # No pruning needed
+            
+            logger.info(f"Context token count ({current_tokens}) exceeds limit ({max_tokens}), pruning...")
+            
+            # Create a copy to avoid modifying original
+            pruned_context = context.copy()
+            
+            # Priority: Keep most recent interactions + session context + user context
+            interaction_contexts = pruned_context.get('interaction_contexts', [])
+            session_context = pruned_context.get('session_context', {})
+            user_context = pruned_context.get('user_context', '')
+            
+            # Keep user context and session context (essential)
+            essential_tokens = (
+                self.get_token_count(user_context) + 
+                self.get_token_count(str(session_context))
+            )
+            
+            # Calculate how many interaction contexts we can keep
+            available_tokens = max_tokens - essential_tokens
+            if available_tokens < 0:
+                # Essential context itself is too large - summarize user context
+                if self.get_token_count(user_context) > max_tokens // 2:
+                    pruned_context['user_context'] = user_context[:max_tokens * 2]  # Rough cut
+                    logger.warning(f"User context too large, truncated")
+                return pruned_context
+            
+            # Keep most recent interactions that fit in token budget
+            kept_interactions = []
+            current_size = 0
+            
+            for interaction in interaction_contexts:
+                summary = interaction.get('summary', '')
+                interaction_tokens = self.get_token_count(summary)
+                
+                if current_size + interaction_tokens <= available_tokens:
+                    kept_interactions.append(interaction)
+                    current_size += interaction_tokens
+                else:
+                    break  # Can't fit any more
+            
+            pruned_context['interaction_contexts'] = kept_interactions
+            
+            logger.info(f"Pruned context: kept {len(kept_interactions)}/{len(interaction_contexts)} interactions, "
+                       f"reduced from {current_tokens} to {self._calculate_context_tokens(pruned_context)} tokens")
+            
+            return pruned_context
+            
+        except Exception as e:
+            logger.error(f"Error pruning context: {e}", exc_info=True)
+            return context  # Return original on error
+    
+    def _calculate_context_tokens(self, context: dict) -> int:
+        """Calculate total token count for context"""
+        total = 0
+        
+        # Count tokens in each component
+        user_context = context.get('user_context', '')
+        total += self.get_token_count(str(user_context))
+        
+        session_context = context.get('session_context', {})
+        if isinstance(session_context, dict):
+            total += self.get_token_count(str(session_context.get('summary', '')))
+        else:
+            total += self.get_token_count(str(session_context))
+        
+        interaction_contexts = context.get('interaction_contexts', [])
+        for interaction in interaction_contexts:
+            summary = interaction.get('summary', '')
+            total += self.get_token_count(str(summary))
+        
+        return total
+    
+    async def _retrieve_from_db(self, session_id: str, user_input: str, user_id: str = "Test_Any") -> dict:
+        """
+        Retrieve session context with proper user_id synchronization
+        Uses transactions to ensure atomic updates of database and cache
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Use transaction to ensure atomic updates
+            cursor.execute("BEGIN TRANSACTION")
+            
+            # Get session data (SQLite doesn't support FOR UPDATE, but transaction ensures consistency)
+            cursor.execute("""
+                SELECT context_data, user_metadata, last_activity, user_id
+                FROM sessions 
+                WHERE session_id = ?
+            """, (session_id,))
+            
+            row = cursor.fetchone()
+            
+            if row:
+                context_data = json.loads(row[0]) if row[0] else {}
+                user_metadata = json.loads(row[1]) if row[1] else {}
+                last_activity = row[2]
+                session_user_id = row[3] if len(row) > 3 else user_id
+                
+                # Check for user_id change and update atomically
+                user_changed = False
+                if session_user_id != user_id:
+                    logger.info(f"User change detected: {session_user_id} -> {user_id} for session {session_id}")
+                    user_changed = True
+                    
+                    # Update session with new user_id
+                    cursor.execute("""
+                        UPDATE sessions 
+                        SET user_id = ?, last_activity = ?
+                        WHERE session_id = ?
+                    """, (user_id, datetime.now().isoformat(), session_id))
+                    
+                    # Clear any cached interaction contexts for old user by marking for refresh
+                    try:
+                        cursor.execute("""
+                            UPDATE interaction_contexts
+                            SET needs_refresh = 1
+                            WHERE session_id = ?
+                        """, (session_id,))
+                    except sqlite3.OperationalError:
+                        # Column might not exist yet, will be created by schema update
+                        pass
+                    
+                    # Log user change event
+                    try:
+                        cursor.execute("""
+                            INSERT INTO user_change_log (session_id, old_user_id, new_user_id, timestamp)
+                            VALUES (?, ?, ?, ?)
+                        """, (session_id, session_user_id, user_id, datetime.now().isoformat()))
+                    except sqlite3.OperationalError:
+                        # Table might not exist yet, will be created by schema update
+                        pass
+                    
+                    # Clear old cache entries when user changes
+                    self._clear_user_cache_on_change(session_id, user_id, session_user_id)
+                
+                cursor.execute("COMMIT")
+                
+                # Get interaction contexts with refresh flag check
+                try:
+                    cursor.execute("""
+                        SELECT interaction_summary, created_at, needs_refresh
+                        FROM interaction_contexts
+                        WHERE session_id = ? AND (needs_refresh IS NULL OR needs_refresh = 0)
+                        ORDER BY created_at DESC
+                        LIMIT 20
+                    """, (session_id,))
+                except sqlite3.OperationalError:
+                    # Column might not exist yet, fall back to query without needs_refresh
+                    cursor.execute("""
+                        SELECT interaction_summary, created_at
+                        FROM interaction_contexts
+                        WHERE session_id = ?
+                        ORDER BY created_at DESC
+                        LIMIT 20
+                    """, (session_id,))
+                
+                interaction_contexts = []
+                for ic_row in cursor.fetchall():
+                    # Handle both query formats (with and without needs_refresh)
+                    if len(ic_row) >= 2:
+                        summary = ic_row[0]
+                        timestamp = ic_row[1]
+                        needs_refresh = ic_row[2] if len(ic_row) > 2 else 0
+                        
+                        if summary and not needs_refresh:
+                            interaction_contexts.append({
+                                "summary": summary,
+                                "timestamp": timestamp
+                            })
+                
+                # Get session context from database
+                session_context_data = None
+                try:
+                    cursor.execute("""
+                        SELECT session_summary, created_at
+                        FROM session_contexts
+                        WHERE session_id = ?
+                        ORDER BY created_at DESC
+                        LIMIT 1
+                    """, (session_id,))
+                    sc_row = cursor.fetchone()
+                    if sc_row and sc_row[0]:
+                        session_context_data = {
+                            "summary": sc_row[0],
+                            "timestamp": sc_row[1]
+                        }
+                except sqlite3.OperationalError:
+                    # Table might not exist yet
+                    pass
+                
+                context = {
+                    "session_id": session_id,
+                    "user_id": user_id,
+                    "interaction_contexts": interaction_contexts,
+                    "session_context": session_context_data,
+                    "preferences": user_metadata.get("preferences", {}),
+                    "active_tasks": user_metadata.get("active_tasks", []),
+                    "last_activity": last_activity,
+                    "user_context_loaded": False,
+                    "user_changed": user_changed
+                }
+                
+                conn.close()
+                return context
+            else:
+                # Create new session with transaction
+                cursor.execute("""
+                    INSERT INTO sessions (session_id, user_id, created_at, last_activity, context_data, user_metadata)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                """, (session_id, user_id, datetime.now().isoformat(), datetime.now().isoformat(), "{}", "{}"))
+                
+                cursor.execute("COMMIT")
+                conn.close()
+                
+                return {
+                    "session_id": session_id,
+                    "user_id": user_id,
+                    "interaction_contexts": [],
+                    "session_context": None,
+                    "preferences": {},
+                    "active_tasks": [],
+                    "user_context_loaded": False,
+                    "user_changed": False
+                }
+                
+        except sqlite3.Error as e:
+            logger.error(f"Database transaction error: {e}", exc_info=True)
+            if conn:
+                try:
+                    conn.rollback()
+                except:
+                    pass
+                conn.close()
+            # Return safe fallback
+            return {
+                "session_id": session_id,
+                "user_id": user_id,
+                "interaction_contexts": [],
+                "session_context": None,
+                "preferences": {},
+                "active_tasks": [],
+                "user_context_loaded": False,
+                "error": str(e),
+                "user_changed": False
+            }
+        except Exception as e:
+            logger.error(f"Database retrieval error: {e}", exc_info=True)
+            if conn:
+                try:
+                    conn.rollback()
+                except:
+                    pass
+                conn.close()
+            # Return safe fallback
+            return {
+                "session_id": session_id,
+                "user_id": user_id,
+                "interaction_contexts": [],
+                "session_context": None,
+                "preferences": {},
+                "active_tasks": [],
+                "user_context_loaded": False,
+                "error": str(e),
+                "user_changed": False
+            }
+    
+    def _warm_memory_cache(self, cache_key: str, context: dict):
+        """
+        Warm the in-memory cache with retrieved context
+        Note: Use add_context_cache() instead for TTL support
+        """
+        # Use add_context_cache for consistency with TTL
+        self.add_context_cache(cache_key, context, ttl=self.cache_config.get("ttl", 3600))
+    
+    def _update_cache_with_interaction_context(self, session_id: str, interaction_summary: str, created_at: str):
+        """
+        Update cache with new interaction context immediately after database update
+        This keeps cache synchronized with database without requiring database queries
+        """
+        session_cache_key = f"session_{session_id}"
+        
+        # Get current cached context if it exists
+        cached_context = self.session_cache.get(session_cache_key)
+        
+        if cached_context:
+            # Add new interaction context to the beginning of the list (most recent first)
+            interaction_contexts = cached_context.get('interaction_contexts', [])
+            new_interaction = {
+                "summary": interaction_summary,
+                "timestamp": created_at
+            }
+            # Insert at beginning and keep only last 20 (matches DB query limit)
+            interaction_contexts.insert(0, new_interaction)
+            interaction_contexts = interaction_contexts[:20]
+            
+            # Update cached context with new interaction contexts
+            cached_context['interaction_contexts'] = interaction_contexts
+            self.session_cache[session_cache_key] = cached_context
+            
+            logger.debug(f"Cache updated with new interaction context for session {session_id} (total: {len(interaction_contexts)})")
+        else:
+            # If cache doesn't exist, create new entry
+            new_context = {
+                "session_id": session_id,
+                "interaction_contexts": [{
+                    "summary": interaction_summary,
+                    "timestamp": created_at
+                }],
+                "preferences": {},
+                "active_tasks": [],
+                "user_context_loaded": False
+            }
+            self.session_cache[session_cache_key] = new_context
+            logger.debug(f"Created new cache entry with interaction context for session {session_id}")
+    
+    def _update_cache_with_session_context(self, session_id: str, session_summary: str, created_at: str):
+        """
+        Update cache with new session context immediately after database update
+        This keeps cache synchronized with database without requiring database queries
+        """
+        session_cache_key = f"session_{session_id}"
+        
+        # Get current cached context if it exists
+        cached_context = self.session_cache.get(session_cache_key)
+        
+        if cached_context:
+            # Update session context in cache
+            cached_context['session_context'] = {
+                "summary": session_summary,
+                "timestamp": created_at
+            }
+            self.session_cache[session_cache_key] = cached_context
+            
+            logger.debug(f"Cache updated with new session context for session {session_id}")
+        else:
+            # If cache doesn't exist, create new entry
+            new_context = {
+                "session_id": session_id,
+                "session_context": {
+                    "summary": session_summary,
+                    "timestamp": created_at
+                },
+                "interaction_contexts": [],
+                "preferences": {},
+                "active_tasks": [],
+                "user_context_loaded": False
+            }
+            self.session_cache[session_cache_key] = new_context
+            logger.debug(f"Created new cache entry with session context for session {session_id}")
+    
+    def _update_context(self, context: dict, user_input: str, response: str = None, user_id: str = "Test_Any") -> dict:
+        """
+        Update context with deduplication and idempotency checks
+        Prevents duplicate context updates using interaction hashes
+        """
+        try:
+            # Generate unique interaction hash to prevent duplicates
+            interaction_hash = self._generate_interaction_hash(user_input, context["session_id"], user_id)
+            
+            # Check if this interaction was already processed
+            if self._is_duplicate_interaction(interaction_hash):
+                logger.info(f"Duplicate interaction detected, skipping update: {interaction_hash[:8]}")
+                return context
+            
+            # Use transaction for atomic updates
+            current_time = datetime.now().isoformat()
+            with self.transaction_manager.transaction(context["session_id"]) as cursor:
+                # Update session activity (only if last_activity is older to prevent unnecessary updates)
+                cursor.execute("""
+                    UPDATE sessions 
+                    SET last_activity = ?, user_id = ?
+                    WHERE session_id = ? AND (last_activity IS NULL OR last_activity < ?)
+                """, (current_time, user_id, context["session_id"], current_time))
+                
+                # Store interaction with duplicate prevention using INSERT OR IGNORE
+                session_context = {
+                    "preferences": context.get("preferences", {}),
+                    "active_tasks": context.get("active_tasks", [])
+                }
+                
+                cursor.execute("""
+                    INSERT OR IGNORE INTO interactions (
+                        interaction_hash,
+                        session_id, 
+                        user_input, 
+                        context_snapshot, 
+                        created_at
+                    ) VALUES (?, ?, ?, ?, ?)
+                """, (
+                    interaction_hash,
+                    context["session_id"],
+                    user_input,
+                    json.dumps(session_context),
+                    current_time
+                ))
+            
+            # Mark interaction as processed (outside transaction)
+            self._mark_interaction_processed(interaction_hash)
+            
+            # Update in-memory context
+            context["last_interaction"] = user_input
+            context["last_update"] = current_time
+            
+            logger.info(f"Context updated for session {context['session_id']} with hash {interaction_hash[:8]}")
+            
+            return context
+            
+        except Exception as e:
+            logger.error(f"Error updating context: {e}", exc_info=True)
+            return context
+    
+    def _generate_interaction_hash(self, user_input: str, session_id: str, user_id: str) -> str:
+        """Generate unique hash for interaction to prevent duplicates"""
+        # Use session_id, user_id, and user_input for exact duplicate detection
+        # Normalize user input by stripping whitespace
+        normalized_input = user_input.strip()
+        content = f"{session_id}:{user_id}:{normalized_input}"
+        return hashlib.sha256(content.encode()).hexdigest()
+    
+    def _is_duplicate_interaction(self, interaction_hash: str) -> bool:
+        """Check if interaction was already processed"""
+        # Keep a rolling window of recent interaction hashes in memory
+        if not hasattr(self, '_processed_interactions'):
+            self._processed_interactions = set()
+        
+        # Check in-memory cache first
+        if interaction_hash in self._processed_interactions:
+            return True
+        
+        # Also check database for persistent duplicates
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            # Check if interaction_hash column exists and query for duplicates
+            cursor.execute("PRAGMA table_info(interactions)")
+            columns = [row[1] for row in cursor.fetchall()]
+            if 'interaction_hash' in columns:
+                cursor.execute("""
+                    SELECT COUNT(*) FROM interactions 
+                    WHERE interaction_hash IS NOT NULL AND interaction_hash = ?
+                """, (interaction_hash,))
+                count = cursor.fetchone()[0]
+                conn.close()
+                return count > 0
+            else:
+                conn.close()
+                return False
+        except sqlite3.OperationalError:
+            # Column might not exist yet, only check in-memory
+            return interaction_hash in self._processed_interactions
+    
+    def _mark_interaction_processed(self, interaction_hash: str):
+        """Mark interaction as processed"""
+        if not hasattr(self, '_processed_interactions'):
+            self._processed_interactions = set()
+        self._processed_interactions.add(interaction_hash)
+        
+        # Limit memory usage by keeping only last 1000 hashes
+        if len(self._processed_interactions) > 1000:
+            # Keep most recent 500 entries (simple truncation)
+            self._processed_interactions = set(list(self._processed_interactions)[-500:])
+    
+    async def manage_context_optimized(self, session_id: str, user_input: str, user_id: str = "Test_Any") -> dict:
+        """
+        Efficient context management with transaction optimization
+        """
+        # Use session-only cache key
+        session_cache_key = f"session_{session_id}"
+        
+        # Try to get from cache first (no DB access)
+        cached_context = self._get_from_memory_cache(session_cache_key)
+        if cached_context and self._is_cache_valid(cached_context):
+            logger.debug(f"Using cached context for session {session_id}")
+            return cached_context
+        
+        # Use transaction for all DB operations
+        with self.transaction_manager.transaction(session_id) as cursor:
+            # Atomic session retrieval and update
+            cursor.execute("""
+                SELECT s.context_data, s.user_metadata, s.last_activity, s.user_id,
+                       COUNT(ic.interaction_id) as interaction_count
+                FROM sessions s
+                LEFT JOIN interaction_contexts ic ON s.session_id = ic.session_id
+                WHERE s.session_id = ?
+                GROUP BY s.session_id
+            """, (session_id,))
+            
+            row = cursor.fetchone()
+            
+            if row:
+                # Parse existing session data
+                context_data = json.loads(row[0] or '{}')
+                user_metadata = json.loads(row[1] or '{}')
+                last_activity = row[2]
+                stored_user_id = row[3] or user_id
+                interaction_count = row[4] or 0
+                
+                # Handle user change atomically
+                if stored_user_id != user_id:
+                    self._handle_user_change_atomic(cursor, session_id, stored_user_id, user_id)
+                
+                # Get interaction contexts efficiently
+                interaction_contexts = self._get_interaction_contexts_atomic(cursor, session_id)
+                
+            else:
+                # Create new session atomically
+                cursor.execute("""
+                    INSERT INTO sessions (session_id, user_id, created_at, last_activity, context_data, user_metadata)
+                    VALUES (?, ?, datetime('now'), datetime('now'), '{}', '{}')
+                """, (session_id, user_id))
+                
+                context_data = {}
+                user_metadata = {}
+                interaction_contexts = []
+                interaction_count = 0
+        
+        # Load user context asynchronously (outside transaction)
+        user_context = await self._load_user_context_async(user_id)
+        
+        # Build final context
+        final_context = {
+            "session_id": session_id,
+            "user_id": user_id,
+            "interaction_contexts": interaction_contexts,
+            "user_context": user_context,
+            "preferences": user_metadata.get("preferences", {}),
+            "active_tasks": user_metadata.get("active_tasks", []),
+            "interaction_count": interaction_count,
+            "cache_timestamp": datetime.now().isoformat()
+        }
+        
+        # Update cache
+        self._warm_memory_cache(session_cache_key, final_context)
+        
+        return self._optimize_context(final_context)
+    
+    def _handle_user_change_atomic(self, cursor, session_id: str, old_user_id: str, new_user_id: str):
+        """Handle user change within transaction"""
+        logger.info(f"Handling user change in transaction: {old_user_id} -> {new_user_id}")
+        
+        # Update session
+        cursor.execute("""
+            UPDATE sessions 
+            SET user_id = ?, last_activity = datetime('now')
+            WHERE session_id = ?
+        """, (new_user_id, session_id))
+        
+        # Log the change
+        try:
+            cursor.execute("""
+                INSERT INTO user_change_log (session_id, old_user_id, new_user_id, timestamp)
+                VALUES (?, ?, ?, datetime('now'))
+            """, (session_id, old_user_id, new_user_id))
+        except sqlite3.OperationalError:
+            # Table might not exist yet
+            pass
+        
+        # Invalidate related caches
+        try:
+            cursor.execute("""
+                UPDATE interaction_contexts
+                SET needs_refresh = 1
+                WHERE session_id = ?
+            """, (session_id,))
+        except sqlite3.OperationalError:
+            # Column might not exist yet
+            pass
+    
+    def _get_interaction_contexts_atomic(self, cursor, session_id: str, limit: int = 20):
+        """Get interaction contexts within transaction"""
+        try:
+            cursor.execute("""
+                SELECT interaction_summary, created_at, interaction_id
+                FROM interaction_contexts
+                WHERE session_id = ? AND (needs_refresh IS NULL OR needs_refresh = 0)
+                ORDER BY created_at DESC
+                LIMIT ?
+            """, (session_id, limit))
+        except sqlite3.OperationalError:
+            # Fallback if needs_refresh column doesn't exist
+            cursor.execute("""
+                SELECT interaction_summary, created_at, interaction_id
+                FROM interaction_contexts
+                WHERE session_id = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+            """, (session_id, limit))
+        
+        contexts = []
+        for row in cursor.fetchall():
+            if row[0]:
+                contexts.append({
+                    "summary": row[0],
+                    "timestamp": row[1],
+                    "id": row[2] if len(row) > 2 else None
+                })
+        
+        return contexts
+    
+    async def _load_user_context_async(self, user_id: str):
+        """Load user context asynchronously to avoid blocking"""
+        try:
+            # Check memory cache first
+            user_cache_key = f"user_{user_id}"
+            cached = self._get_from_memory_cache(user_cache_key)
+            if cached:
+                return cached.get("user_context", "")
+            
+            # Load from database
+            return await self.get_user_context(user_id)
+        except Exception as e:
+            logger.error(f"Error loading user context: {e}")
+            return ""
+    
+    def _is_cache_valid(self, cached_context: dict, max_age_seconds: int = 60) -> bool:
+        """Check if cached context is still valid"""
+        if not cached_context:
+            return False
+        
+        cache_timestamp = cached_context.get("cache_timestamp")
+        if not cache_timestamp:
+            return False
+        
+        try:
+            cache_time = datetime.fromisoformat(cache_timestamp)
+            age = (datetime.now() - cache_time).total_seconds()
+            return age < max_age_seconds
+        except:
+            return False
+    
+    def invalidate_session_cache(self, session_id: str):
+        """
+        Invalidate cached context for a session to force fresh retrieval
+        Only affects cache management - does not change application functionality
+        """
+        session_cache_key = f"session_{session_id}"
+        if session_cache_key in self.session_cache:
+            del self.session_cache[session_cache_key]
+            logger.info(f"Cache invalidated for session {session_id} to ensure fresh context retrieval")
+    
+    def optimize_database_indexes(self):
+        """Create database indexes for better query performance"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Create indexes for frequently queried columns
+            indexes = [
+                "CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id)",
+                "CREATE INDEX IF NOT EXISTS idx_sessions_last_activity ON sessions(last_activity)",
+                "CREATE INDEX IF NOT EXISTS idx_interactions_session_id ON interactions(session_id)",
+                "CREATE INDEX IF NOT EXISTS idx_interaction_contexts_session_id ON interaction_contexts(session_id)",
+                "CREATE INDEX IF NOT EXISTS idx_interaction_contexts_created_at ON interaction_contexts(created_at)",
+                "CREATE INDEX IF NOT EXISTS idx_user_change_log_session_id ON user_change_log(session_id)",
+                "CREATE INDEX IF NOT EXISTS idx_user_contexts_updated_at ON user_contexts(updated_at)"
+            ]
+            
+            for index in indexes:
+                try:
+                    cursor.execute(index)
+                except sqlite3.OperationalError as e:
+                    # Table might not exist yet, skip this index
+                    logger.debug(f"Skipping index creation (table may not exist): {e}")
+            
+            # Analyze database for query optimization
+            try:
+                cursor.execute("ANALYZE")
+            except sqlite3.OperationalError:
+                # ANALYZE might not be available in all SQLite versions
+                pass
+            
+            conn.commit()
+            conn.close()
+            
+            logger.info("✓ Database indexes optimized successfully")
+            
+        except Exception as e:
+            logger.error(f"Error optimizing database indexes: {e}", exc_info=True)
+    
+    def set_context_mode(self, session_id: str, mode: str, user_id: str = "Test_Any"):
+        """
+        Set context mode for session (fresh or relevant)
+        
+        Args:
+            session_id: Session identifier
+            mode: 'fresh' (no user context) or 'relevant' (only relevant context)
+            user_id: User identifier
+        
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            import time
+            
+            # VALIDATION: Ensure mode is valid
+            if mode not in ['fresh', 'relevant']:
+                logger.warning(f"Invalid context mode '{mode}', defaulting to 'fresh'")
+                mode = 'fresh'
+            
+            # Get or create cache entry
+            cache_key = f"session_{session_id}"
+            cached_context = self._get_from_memory_cache(cache_key)
+            
+            if not cached_context:
+                cached_context = {
+                    'session_id': session_id,
+                    'user_id': user_id,
+                    'preferences': {},
+                    'context_mode': mode,
+                    'context_mode_timestamp': time.time()
+                }
+            else:
+                # Update existing context (preserve other data)
+                cached_context['context_mode'] = mode
+                cached_context['context_mode_timestamp'] = time.time()
+                cached_context['user_id'] = user_id  # Update user_id if changed
+            
+            # Update cache with TTL
+            self.add_context_cache(cache_key, cached_context, ttl=3600)
+            
+            logger.info(f"Context mode set to '{mode}' for session {session_id} (user: {user_id})")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error setting context mode: {e}", exc_info=True)
+            return False  # Failure doesn't break existing flow
+    
+    def get_context_mode(self, session_id: str) -> str:
+        """
+        Get current context mode for session
+        
+        Args:
+            session_id: Session identifier
+        
+        Returns:
+            str: 'fresh' or 'relevant' (default: 'fresh')
+        """
+        try:
+            cache_key = f"session_{session_id}"
+            cached_context = self._get_from_memory_cache(cache_key)
+            
+            if cached_context:
+                mode = cached_context.get('context_mode', 'fresh')
+                # VALIDATION: Ensure mode is still valid
+                if mode in ['fresh', 'relevant']:
+                    return mode
+                else:
+                    logger.warning(f"Invalid cached mode '{mode}', resetting to 'fresh'")
+                    cached_context['context_mode'] = 'fresh'
+                    import time
+                    cached_context['context_mode_timestamp'] = time.time()
+                    self.add_context_cache(cache_key, cached_context, ttl=3600)
+                    return 'fresh'
+            
+            # Default for new sessions
+            return 'fresh'
+            
+        except Exception as e:
+            logger.error(f"Error getting context mode: {e}", exc_info=True)
+            return 'fresh'  # Safe default - no degradation
+    
+    async def get_all_user_sessions(self, user_id: str) -> List[Dict]:
+        """
+        Fetch all session contexts for a user (for relevance classification)
+        
+        Performance: Single database query with JOIN
+        
+        Args:
+            user_id: User identifier
+        
+        Returns:
+            List of session context dictionaries with summaries and interactions
+        """
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Fetch all session contexts for user with interaction summaries
+            cursor.execute("""
+                SELECT DISTINCT 
+                    sc.session_id, 
+                    sc.session_summary, 
+                    sc.created_at,
+                    (SELECT GROUP_CONCAT(ic.interaction_summary, ' ||| ')
+                     FROM interaction_contexts ic
+                     WHERE ic.session_id = sc.session_id
+                     ORDER BY ic.created_at DESC
+                     LIMIT 10) as recent_interactions
+                FROM session_contexts sc
+                JOIN sessions s ON sc.session_id = s.session_id
+                WHERE s.user_id = ?
+                ORDER BY sc.created_at DESC
+                LIMIT 50
+            """, (user_id,))
+            
+            sessions = []
+            for row in cursor.fetchall():
+                session_id, session_summary, created_at, interactions_str = row
+                
+                # Parse interaction summaries
+                interaction_list = []
+                if interactions_str:
+                    for summary in interactions_str.split(' ||| '):
+                        if summary.strip():
+                            interaction_list.append({
+                                'summary': summary.strip(),
+                                'timestamp': created_at
+                            })
+                
+                sessions.append({
+                    'session_id': session_id,
+                    'summary': session_summary or '',
+                    'created_at': created_at,
+                    'interaction_contexts': interaction_list
+                })
+            
+            conn.close()
+            logger.info(f"Fetched {len(sessions)} sessions for user {user_id}")
+            return sessions
+            
+        except Exception as e:
+            logger.error(f"Error fetching user sessions: {e}", exc_info=True)
+            return []  # Safe fallback - no degradation
+    
+    def _extract_entities(self, context: dict) -> list:
+        """
+        Extract essential entities from context
+        """
+        # TODO: Implement entity extraction
+        return []
+    
+    def _generate_summary(self, context: dict) -> str:
+        """
+        Generate conversation summary
+        """
+        # TODO: Implement summary generation
+        return ""
+    
+    def get_or_create_session_context(self, session_id: str, user_id: Optional[str] = None) -> Dict:
+        """Enhanced context retrieval with caching"""
+        import time
+        
+        # In-memory cache check first
+        if session_id in self._session_cache:
+            cache_entry = self._session_cache[session_id]
+            if time.time() - cache_entry['timestamp'] < 300:  # 5 min cache
+                logger.debug(f"Cache hit for session {session_id}")
+                return cache_entry['context']
+        
+        # Batch database queries
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Single query for all context data
+            query = """
+            SELECT 
+                s.context_data,
+                s.user_metadata,
+                s.last_activity,
+                u.persona_summary,
+                ic.interaction_summary
+            FROM sessions s
+            LEFT JOIN user_contexts u ON s.user_id = u.user_id
+            LEFT JOIN interaction_contexts ic ON s.session_id = ic.session_id
+            WHERE s.session_id = ?
+            ORDER BY ic.created_at DESC
+            LIMIT 10
+            """
+            
+            cursor.execute(query, (session_id,))
+            results = cursor.fetchall()
+            
+            # Process results efficiently
+            context = self._build_context_from_results(results, session_id, user_id)
+            
+            # Update cache
+            self._session_cache[session_id] = {
+                'context': context,
+                'timestamp': time.time()
+            }
+            
+            return context
+            
+        except Exception as e:
+            logger.error(f"Error in get_or_create_session_context: {e}", exc_info=True)
+            # Return safe fallback
+            return {
+                "session_id": session_id,
+                "user_id": user_id or "Test_Any",
+                "interaction_contexts": [],
+                "session_context": None,
+                "preferences": {},
+                "active_tasks": [],
+                "user_context_loaded": False
+            }
+        finally:
+            if conn:
+                conn.close()
+    
+    def _build_context_from_results(self, results: list, session_id: str, user_id: Optional[str]) -> Dict:
+        """Build context dictionary from batch query results"""
+        context = {
+            "session_id": session_id,
+            "user_id": user_id or "Test_Any",
+            "interaction_contexts": [],
+            "session_context": None,
+            "user_context": "",
+            "preferences": {},
+            "active_tasks": [],
+            "user_context_loaded": False
+        }
+        
+        if not results:
+            return context
+        
+        # Process first row for session data
+        first_row = results[0]
+        if first_row[0]:  # context_data
+            try:
+                session_data = json.loads(first_row[0])
+                context["preferences"] = session_data.get("preferences", {})
+                context["active_tasks"] = session_data.get("active_tasks", [])
+            except:
+                pass
+        
+        if first_row[1]:  # user_metadata
+            try:
+                user_metadata = json.loads(first_row[1])
+                context["preferences"].update(user_metadata.get("preferences", {}))
+            except:
+                pass
+        
+        context["last_activity"] = first_row[2]  # last_activity
+        
+        if first_row[3]:  # persona_summary
+            context["user_context"] = first_row[3]
+            context["user_context_loaded"] = True
+        
+        # Process interaction contexts
+        seen_interactions = set()
+        for row in results:
+            if row[4]:  # interaction_summary
+                # Deduplicate interactions
+                if row[4] not in seen_interactions:
+                    seen_interactions.add(row[4])
+                    context["interaction_contexts"].append({
+                        "summary": row[4],
+                        "timestamp": None  # Could extract from row if available
+                    })
+        
+        return context

src/context_relevance_classifier.py

@@ -0,0 +1,491 @@
+# context_relevance_classifier.py
+"""
+Context Relevance Classification Module
+Uses LLM inference to identify relevant session contexts and generate dynamic summaries
+"""
+
+import logging
+import asyncio
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class ContextRelevanceClassifier:
+    """
+    Classify which session contexts are relevant to current conversation
+    and generate 2-line summaries for each relevant session
+    
+    Performance Priority:
+    - LLM inference first (accuracy over speed)
+    - Parallel processing for multiple sessions
+    - Caching for repeated queries
+    - Graceful degradation on failures
+    """
+    
+    def __init__(self, llm_router):
+        """
+        Initialize classifier with LLM router
+        
+        Args:
+            llm_router: LLMRouter instance for inference calls
+        """
+        self.llm_router = llm_router
+        self._relevance_cache = {}  # Cache relevance scores to reduce LLM calls
+        self._summary_cache = {}  # Cache summaries to avoid regenerating
+        self._cache_ttl = 3600  # 1 hour cache TTL
+    
+    async def classify_and_summarize_relevant_contexts(self,
+                                                      current_input: str,
+                                                      session_contexts: List[Dict],
+                                                      user_id: str = "Test_Any") -> Dict:
+        """
+        Main method: Classify relevant contexts AND generate 2-line summaries
+        
+        Performance Strategy:
+        1. Extract current topic (LLM inference - single call)
+        2. Calculate relevance in parallel (multiple LLM calls in parallel)
+        3. Generate summaries in parallel (only for relevant sessions)
+        
+        Args:
+            current_input: Current user query
+            session_contexts: List of session context dictionaries
+            user_id: User identifier for logging
+        
+        Returns:
+            {
+                'relevant_summaries': List[str],  # 2-line summaries
+                'combined_user_context': str,     # Combined summaries
+                'relevance_scores': Dict,          # Scores for each session
+                'classification_confidence': float,
+                'topic': str,
+                'processing_time': float
+            }
+        """
+        start_time = datetime.now()
+        
+        try:
+            # Early exit: No contexts to process
+            if not session_contexts:
+                logger.info("No session contexts provided for classification")
+                return {
+                    'relevant_summaries': [],
+                    'combined_user_context': '',
+                    'relevance_scores': {},
+                    'classification_confidence': 1.0,
+                    'topic': '',
+                    'processing_time': 0.0
+                }
+            
+            # Step 1: Extract current topic (LLM inference - OPTION A: Single call)
+            current_topic = await self._extract_current_topic(current_input)
+            logger.info(f"Extracted current topic: '{current_topic}'")
+            
+            # Step 2: Calculate relevance scores (parallel processing for performance)
+            relevance_tasks = []
+            for session_ctx in session_contexts:
+                task = self._calculate_relevance_with_cache(
+                    current_topic,
+                    current_input,
+                    session_ctx
+                )
+                relevance_tasks.append((session_ctx, task))
+            
+            # Execute all relevance calculations in parallel
+            relevance_results = await asyncio.gather(
+                *[task for _, task in relevance_tasks],
+                return_exceptions=True
+            )
+            
+            # Filter relevant sessions (score >= 0.6)
+            relevant_sessions = []
+            relevance_scores = {}
+            
+            for (session_ctx, _), result in zip(relevance_tasks, relevance_results):
+                if isinstance(result, Exception):
+                    logger.error(f"Error calculating relevance: {result}")
+                    continue
+                
+                session_id = session_ctx.get('session_id', 'unknown')
+                score = result.get('score', 0.0)
+                relevance_scores[session_id] = score
+                
+                if score >= 0.6:  # Relevance threshold
+                    relevant_sessions.append({
+                        'session_id': session_id,
+                        'summary': session_ctx.get('summary', ''),
+                        'relevance_score': score,
+                        'interaction_contexts': session_ctx.get('interaction_contexts', []),
+                        'created_at': session_ctx.get('created_at', '')
+                    })
+            
+            logger.info(f"Found {len(relevant_sessions)} relevant sessions out of {len(session_contexts)}")
+            
+            # Step 3: Generate 2-line summaries for relevant sessions (parallel)
+            summary_tasks = []
+            for relevant_session in relevant_sessions:
+                task = self._generate_session_summary(
+                    relevant_session,
+                    current_input,
+                    current_topic
+                )
+                summary_tasks.append(task)
+            
+            # Execute all summaries in parallel
+            summary_results = await asyncio.gather(*summary_tasks, return_exceptions=True)
+            
+            # Filter valid summaries
+            valid_summaries = []
+            for summary in summary_results:
+                if isinstance(summary, str) and summary.strip():
+                    valid_summaries.append(summary.strip())
+                elif isinstance(summary, Exception):
+                    logger.error(f"Error generating summary: {summary}")
+            
+            # Step 4: Combine summaries into dynamic user context
+            combined_user_context = self._combine_summaries(valid_summaries, current_topic)
+            
+            processing_time = (datetime.now() - start_time).total_seconds()
+            
+            logger.info(
+                f"Relevance classification complete: {len(valid_summaries)} summaries, "
+                f"topic '{current_topic}', time: {processing_time:.2f}s"
+            )
+            
+            return {
+                'relevant_summaries': valid_summaries,
+                'combined_user_context': combined_user_context,
+                'relevance_scores': relevance_scores,
+                'classification_confidence': 0.8,
+                'topic': current_topic,
+                'processing_time': processing_time
+            }
+            
+        except Exception as e:
+            logger.error(f"Error in relevance classification: {e}", exc_info=True)
+            processing_time = (datetime.now() - start_time).total_seconds()
+            
+            # SAFE FALLBACK: Return empty result (no degradation)
+            return {
+                'relevant_summaries': [],
+                'combined_user_context': '',
+                'relevance_scores': {},
+                'classification_confidence': 0.0,
+                'topic': '',
+                'processing_time': processing_time,
+                'error': str(e)
+            }
+    
+    async def _extract_current_topic(self, user_input: str) -> str:
+        """
+        Extract main topic from current input using LLM inference
+        
+        Performance: Single LLM call with caching
+        """
+        try:
+            # Check cache first
+            cache_key = f"topic_{hash(user_input[:200])}"
+            if cache_key in self._relevance_cache:
+                cached = self._relevance_cache[cache_key]
+                if cached.get('timestamp', 0) + self._cache_ttl > datetime.now().timestamp():
+                    return cached['value']
+            
+            if not self.llm_router:
+                # Fallback: Simple extraction
+                words = user_input.split()[:5]
+                return ' '.join(words) if words else 'general query'
+            
+            prompt = f"""Extract the main topic (2-5 words) from this query:
+
+Query: "{user_input}"
+
+Respond with ONLY the topic name. Maximum 5 words."""
+            
+            result = await self.llm_router.route_inference(
+                task_type="classification",
+                prompt=prompt,
+                max_tokens=20,
+                temperature=0.2  # Low temperature for consistency
+            )
+            
+            topic = result.strip() if result else user_input[:100]
+            
+            # Cache result
+            self._relevance_cache[cache_key] = {
+                'value': topic,
+                'timestamp': datetime.now().timestamp()
+            }
+            
+            return topic
+            
+        except Exception as e:
+            logger.error(f"Error extracting topic: {e}", exc_info=True)
+            # Fallback
+            return user_input[:100]
+    
+    async def _calculate_relevance_with_cache(self,
+                                            current_topic: str,
+                                            current_input: str,
+                                            session_ctx: Dict) -> Dict:
+        """
+        Calculate relevance score with caching to reduce LLM calls
+        
+        Returns: {'score': float, 'cached': bool}
+        """
+        try:
+            session_id = session_ctx.get('session_id', 'unknown')
+            session_summary = session_ctx.get('summary', '')
+            
+            # Check cache
+            cache_key = f"rel_{session_id}_{hash(current_input[:100] + current_topic)}"
+            if cache_key in self._relevance_cache:
+                cached = self._relevance_cache[cache_key]
+                if cached.get('timestamp', 0) + self._cache_ttl > datetime.now().timestamp():
+                    return {'score': cached['value'], 'cached': True}
+            
+            # Calculate relevance
+            score = await self._calculate_relevance(
+                current_topic,
+                current_input,
+                session_summary
+            )
+            
+            # Cache result
+            self._relevance_cache[cache_key] = {
+                'value': score,
+                'timestamp': datetime.now().timestamp()
+            }
+            
+            return {'score': score, 'cached': False}
+            
+        except Exception as e:
+            logger.error(f"Error in cached relevance calculation: {e}", exc_info=True)
+            return {'score': 0.5, 'cached': False}  # Neutral score on error
+    
+    async def _calculate_relevance(self,
+                                  current_topic: str,
+                                  current_input: str,
+                                  context_text: str) -> float:
+        """
+        Calculate relevance score (0.0 to 1.0) using LLM inference
+        
+        Performance: Single LLM call per session context
+        """
+        try:
+            if not context_text:
+                return 0.0
+            
+            if not self.llm_router:
+                # Fallback: Keyword matching
+                return self._simple_keyword_relevance(current_input, context_text)
+            
+            # OPTION A: Direct relevance scoring (faster, single call)
+            # OPTION B: Detailed analysis (more accurate, more tokens)
+            # Choosing OPTION A for performance, but with quality prompt
+            
+            prompt = f"""Rate the relevance (0.0 to 1.0) of this session context to the current conversation.
+
+Current Topic: {current_topic}
+Current Query: "{current_input[:200]}"
+
+Session Context:
+"{context_text[:500]}"
+
+Consider:
+- Topic similarity (0.0-1.0)
+- Discussion depth alignment
+- Information continuity
+
+Respond with ONLY a number between 0.0 and 1.0 (e.g., 0.75)."""
+            
+            result = await self.llm_router.route_inference(
+                task_type="general_reasoning",
+                prompt=prompt,
+                max_tokens=10,
+                temperature=0.1  # Very low for consistency
+            )
+            
+            if result:
+                try:
+                    score = float(result.strip())
+                    return max(0.0, min(1.0, score))  # Clamp to [0, 1]
+                except ValueError:
+                    logger.warning(f"Could not parse relevance score: {result}")
+            
+            # Fallback to keyword matching
+            return self._simple_keyword_relevance(current_input, context_text)
+            
+        except Exception as e:
+            logger.error(f"Error calculating relevance: {e}", exc_info=True)
+            return 0.5  # Neutral score on error
+    
+    def _simple_keyword_relevance(self, current_input: str, context_text: str) -> float:
+        """Fallback keyword-based relevance calculation"""
+        try:
+            current_lower = current_input.lower()
+            context_lower = context_text.lower()
+            
+            current_words = set(current_lower.split())
+            context_words = set(context_lower.split())
+            
+            # Remove common stop words for better matching
+            stop_words = {'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by'}
+            current_words = current_words - stop_words
+            context_words = context_words - stop_words
+            
+            if not current_words:
+                return 0.5
+            
+            # Jaccard similarity
+            intersection = len(current_words & context_words)
+            union = len(current_words | context_words)
+            
+            return (intersection / union) if union > 0 else 0.0
+            
+        except Exception:
+            return 0.5
+    
+    async def _generate_session_summary(self,
+                                       session_data: Dict,
+                                       current_input: str,
+                                       current_topic: str) -> str:
+        """
+        Generate 2-line summary for a relevant session context
+        
+        Performance: LLM inference with caching and timeout protection
+        Builds depth and width of topic discussion
+        """
+        try:
+            session_id = session_data.get('session_id', 'unknown')
+            session_summary = session_data.get('summary', '')
+            interaction_contexts = session_data.get('interaction_contexts', [])
+            
+            # Check cache
+            cache_key = f"summary_{session_id}_{hash(current_topic)}"
+            if cache_key in self._summary_cache:
+                cached = self._summary_cache[cache_key]
+                if cached.get('timestamp', 0) + self._cache_ttl > datetime.now().timestamp():
+                    return cached['value']
+            
+            # Validation: Ensure content available
+            if not session_summary and not interaction_contexts:
+                logger.warning(f"No content for summarization: session {session_id}")
+                return f"Previous discussion on {current_topic}.\nContext details unavailable."
+            
+            # Build context text with limits
+            session_context_text = session_summary[:500] if session_summary else ""
+            
+            if interaction_contexts:
+                recent_interactions = "\n".join([
+                    ic.get('summary', '')[:100]
+                    for ic in interaction_contexts[-5:]
+                    if ic.get('summary')
+                ])
+                if recent_interactions:
+                    session_context_text = f"{session_context_text}\n\nRecent interactions:\n{recent_interactions[:400]}"
+            
+            # Limit total context
+            if len(session_context_text) > 1000:
+                session_context_text = session_context_text[:1000] + "..."
+            
+            if not self.llm_router:
+                # Fallback
+                return f"Previous {current_topic} discussion.\nCovered: {session_summary[:80]}..."
+            
+            # LLM-based summarization with timeout
+            prompt = f"""Generate a precise 2-line summary (maximum 2 sentences, ~100 tokens total) that captures the depth and breadth of the topic discussion:
+
+Current Topic: {current_topic}
+Current Query: "{current_input[:150]}"
+
+Previous Session Context:
+{session_context_text}
+
+Requirements:
+- Line 1: Summarize the MAIN TOPICS/SUBJECTS discussed (breadth/width)
+- Line 2: Summarize the DEPTH/LEVEL of discussion (technical depth, detail level, approach)
+- Focus on relevance to: "{current_topic}"
+- Keep total under 100 tokens
+- Be specific about what was covered
+
+Respond with ONLY the 2-line summary, no explanations."""
+            
+            try:
+                result = await asyncio.wait_for(
+                    self.llm_router.route_inference(
+                        task_type="general_reasoning",
+                        prompt=prompt,
+                        max_tokens=100,
+                        temperature=0.4
+                    ),
+                    timeout=10.0  # 10 second timeout
+                )
+            except asyncio.TimeoutError:
+                logger.warning(f"Summary generation timeout for session {session_id}")
+                return f"Previous {current_topic} discussion.\nDepth and approach covered in prior session."
+            
+            # Validate and format result
+            if result and isinstance(result, str) and result.strip():
+                summary = result.strip()
+                lines = [line.strip() for line in summary.split('\n') if line.strip()]
+                
+                if len(lines) >= 1:
+                    if len(lines) > 2:
+                        combined = f"{lines[0]}\n{'. '.join(lines[1:])}"
+                        formatted_summary = combined[:200]
+                    else:
+                        formatted_summary = '\n'.join(lines[:2])[:200]
+                    
+                    # Ensure minimum quality
+                    if len(formatted_summary) < 20:
+                        formatted_summary = f"Previous {current_topic} discussion.\nDetails from previous session."
+                    
+                    # Cache result
+                    self._summary_cache[cache_key] = {
+                        'value': formatted_summary,
+                        'timestamp': datetime.now().timestamp()
+                    }
+                    
+                    return formatted_summary
+                else:
+                    return f"Previous {current_topic} discussion.\nContext from previous session."
+            
+            # Invalid result fallback
+            logger.warning(f"Invalid summary result for session {session_id}")
+            return f"Previous {current_topic} discussion.\nDepth and approach covered previously."
+            
+        except Exception as e:
+            logger.error(f"Error generating session summary: {e}", exc_info=True)
+            session_summary = session_data.get('summary', '')[:100] if session_data.get('summary') else 'topic discussion'
+            return f"{session_summary}...\n{current_topic} discussion from previous session."
+    
+    def _combine_summaries(self, summaries: List[str], current_topic: str) -> str:
+        """
+        Combine multiple 2-line summaries into coherent user context
+        
+        Builds width (multiple topics) and depth (summarized discussions)
+        """
+        try:
+            if not summaries:
+                return ''
+            
+            if len(summaries) == 1:
+                return summaries[0]
+            
+            # Format combined summaries with topic focus
+            combined = f"Relevant Previous Discussions (Topic: {current_topic}):\n\n"
+            
+            for idx, summary in enumerate(summaries, 1):
+                combined += f"[Session {idx}]\n{summary}\n\n"
+            
+            # Add summary statement
+            combined += f"These sessions provide context for {current_topic} discussions, covering multiple aspects and depth levels."
+            
+            return combined
+            
+        except Exception as e:
+            logger.error(f"Error combining summaries: {e}", exc_info=True)
+            # Simple fallback
+            return '\n\n'.join(summaries[:5])
+

src/database.py

@@ -0,0 +1,97 @@
+"""
+Database initialization and management
+"""
+
+import sqlite3
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+class DatabaseManager:
+    def __init__(self, db_path: str = "sessions.db"):
+        self.db_path = db_path
+        self.connection = None
+        self._init_db()
+    
+    def _init_db(self):
+        """Initialize database with required tables"""
+        try:
+            # Create database directory if needed
+            os.makedirs(os.path.dirname(self.db_path), exist_ok=True)
+            
+            self.connection = sqlite3.connect(self.db_path, check_same_thread=False)
+            self.connection.row_factory = sqlite3.Row
+            
+            # Create tables
+            self._create_tables()
+            logger.info(f"Database initialized at {self.db_path}")
+            
+        except Exception as e:
+            logger.error(f"Database initialization failed: {e}")
+            # Fallback to in-memory database
+            self.connection = sqlite3.connect(":memory:", check_same_thread=False)
+            self._create_tables()
+            logger.info("Using in-memory database as fallback")
+    
+    def _create_tables(self):
+        """Create required database tables"""
+        cursor = self.connection.cursor()
+        
+        # Sessions table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS sessions (
+                session_id TEXT PRIMARY KEY,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                context_data TEXT,
+                user_metadata TEXT
+            )
+        """)
+        
+        # Interactions table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS interactions (
+                interaction_id TEXT PRIMARY KEY,
+                session_id TEXT REFERENCES sessions(session_id),
+                user_input TEXT NOT NULL,
+                agent_trace TEXT,
+                final_response TEXT,
+                processing_time INTEGER,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        
+        self.connection.commit()
+        logger.info("Database tables created successfully")
+    
+    def get_connection(self):
+        """Get database connection"""
+        return self.connection
+    
+    def close(self):
+        """Close database connection"""
+        if self.connection:
+            self.connection.close()
+            logger.info("Database connection closed")
+
+# Global database instance
+db_manager = None
+
+def init_database(db_path: str = "sessions.db"):
+    """Initialize global database instance"""
+    global db_manager
+    if db_manager is None:
+        db_manager = DatabaseManager(db_path)
+    return db_manager
+
+def get_db():
+    """Get database connection"""
+    global db_manager
+    if db_manager is None:
+        init_database()
+    return db_manager.get_connection()
+
+# Initialize database on import
+init_database()

src/event_handlers.py

@@ -0,0 +1,125 @@
+"""
+Event handlers for connecting UI to backend
+"""
+
+import logging
+import uuid
+from typing import Dict, Any
+
+logger = logging.getLogger(__name__)
+
+class EventHandlers:
+    def __init__(self, components: Dict[str, Any]):
+        self.components = components
+        self.sessions = {}  # In-memory session storage
+    
+    async def handle_message_submit(self, message: str, chat_history: list, 
+                                  session_id: str, show_reasoning: bool, 
+                                  show_agent_trace: bool, request):
+        """Handle user message submission"""
+        try:
+            # Ensure session exists
+            if session_id not in self.sessions:
+                self.sessions[session_id] = {
+                    'history': [],
+                    'context': {},
+                    'created_at': uuid.uuid4().hex
+                }
+            
+            # Add user message to history
+            chat_history.append((message, None))  # None for pending response
+            
+            # Generate response based on available components
+            if self.components.get('mock_mode'):
+                response = self._generate_mock_response(message)
+            else:
+                response = await self._generate_ai_response(message, session_id)
+            
+            # Update chat history with response
+            chat_history[-1] = (message, response)
+            
+            # Prepare additional data for UI
+            reasoning_data = {}
+            performance_data = {}
+            
+            if show_reasoning:
+                reasoning_data = {
+                    "chain_of_thought": {
+                        "step_1": {
+                            "hypothesis": "Mock reasoning for demonstration",
+                            "evidence": ["Mock mode active", f"User input: {message[:50]}..."],
+                            "confidence": 0.5,
+                            "reasoning": "Demonstration mode - enhanced reasoning chain not available"
+                        }
+                    },
+                    "alternative_paths": [],
+                    "uncertainty_areas": [
+                        {
+                            "aspect": "System mode",
+                            "confidence": 0.5,
+                            "mitigation": "Mock mode - full reasoning chain not available"
+                        }
+                    ],
+                    "evidence_sources": [],
+                    "confidence_calibration": {"overall_confidence": 0.5, "mock_mode": True}
+                }
+            
+            if show_agent_trace:
+                performance_data = {"agents_used": ["intent", "synthesis", "safety"]}
+            
+            return "", chat_history, reasoning_data, performance_data
+            
+        except Exception as e:
+            logger.error(f"Error handling message: {e}")
+            error_response = "I apologize, but I'm experiencing technical difficulties. Please try again."
+            chat_history.append((message, error_response))
+            return "", chat_history, {"error": str(e)}, {"status": "error"}
+    
+    def _generate_mock_response(self, message: str) -> str:
+        """Generate mock response for demonstration"""
+        mock_responses = [
+            f"I understand you're asking about: {message}. This is a mock response while the AI system initializes.",
+            f"Thank you for your question: '{message}'. The research assistant is currently in demonstration mode.",
+            f"Interesting question about {message}. In a full implementation, I would analyze this using multiple AI agents.",
+            f"I've received your query: '{message}'. The system is working properly in mock mode."
+        ]
+        
+        import random
+        return random.choice(mock_responses)
+    
+    async def _generate_ai_response(self, message: str, session_id: str) -> str:
+        """Generate AI response using orchestrator"""
+        try:
+            if 'orchestrator' in self.components:
+                result = await self.components['orchestrator'].process_request(
+                    session_id=session_id,
+                    user_input=message
+                )
+                return result.get('final_response', 'No response generated')
+            else:
+                return "Orchestrator not available. Using mock response."
+        except Exception as e:
+            logger.error(f"AI response generation failed: {e}")
+            return f"AI processing error: {str(e)}"
+    
+    def handle_new_session(self):
+        """Handle new session creation"""
+        new_session_id = uuid.uuid4().hex[:8]  # Short session ID for display
+        self.sessions[new_session_id] = {
+            'history': [],
+            'context': {},
+            'created_at': uuid.uuid4().hex
+        }
+        return new_session_id, []  # New session ID and empty history
+    
+    def handle_settings_toggle(self, current_visibility: bool):
+        """Toggle settings panel visibility"""
+        return not current_visibility
+    
+    def handle_tab_change(self, tab_name: str):
+        """Handle tab changes in mobile interface"""
+        return tab_name, False  # Return tab name and hide mobile nav
+
+# Factory function
+def create_event_handlers(components: Dict[str, Any]):
+    return EventHandlers(components)

src/llm_router.py

@@ -0,0 +1,471 @@
+# llm_router.py - UPDATED FOR LOCAL GPU MODEL LOADING
+import logging
+import asyncio
+from typing import Dict, Optional
+from .models_config import LLM_CONFIG
+
+logger = logging.getLogger(__name__)
+
+class LLMRouter:
+    def __init__(self, hf_token, use_local_models: bool = True):
+        self.hf_token = hf_token
+        self.health_status = {}
+        self.use_local_models = use_local_models
+        self.local_loader = None
+        
+        logger.info("LLMRouter initialized")
+        if hf_token:
+            logger.info("HF token available")
+        else:
+            logger.warning("No HF token provided")
+        
+        # Initialize local model loader if enabled
+        if self.use_local_models:
+            try:
+                from .local_model_loader import LocalModelLoader
+                self.local_loader = LocalModelLoader()
+                logger.info("✓ Local model loader initialized (GPU-based inference)")
+                
+                # Note: Pre-loading will happen on first request (lazy loading)
+                # Models will be loaded on-demand to avoid blocking startup
+                logger.info("Models will be loaded on-demand for faster startup")
+            except Exception as e:
+                logger.warning(f"Could not initialize local model loader: {e}. Falling back to API.")
+                logger.warning("This is normal if transformers/torch not available")
+                self.use_local_models = False
+                self.local_loader = None
+    
+    async def route_inference(self, task_type: str, prompt: str, **kwargs):
+        """
+        Smart routing based on task specialization
+        Tries local models first, falls back to HF Inference API if needed
+        """
+        logger.info(f"Routing inference for task: {task_type}")
+        model_config = self._select_model(task_type)
+        logger.info(f"Selected model: {model_config['model_id']}")
+        
+        # Try local model first if available
+        if self.use_local_models and self.local_loader:
+            try:
+                # Handle embedding generation separately
+                if task_type == "embedding_generation":
+                    result = await self._call_local_embedding(model_config, prompt, **kwargs)
+                else:
+                    result = await self._call_local_model(model_config, prompt, task_type, **kwargs)
+                
+                if result is not None:
+                    logger.info(f"Inference complete for {task_type} (local model)")
+                    return result
+                else:
+                    logger.warning("Local model returned None, falling back to API")
+            except Exception as e:
+                logger.warning(f"Local model inference failed: {e}. Falling back to API.")
+                logger.debug("Exception details:", exc_info=True)
+        
+        # Fallback to HF Inference API
+        logger.info("Using HF Inference API")
+        # Health check and fallback logic
+        if not await self._is_model_healthy(model_config["model_id"]):
+            logger.warning(f"Model unhealthy, using fallback")
+            model_config = self._get_fallback_model(task_type)
+            logger.info(f"Fallback model: {model_config['model_id']}")
+            
+        result = await self._call_hf_endpoint(model_config, prompt, task_type, **kwargs)
+        logger.info(f"Inference complete for {task_type}")
+        return result
+    
+    async def _call_local_model(self, model_config: dict, prompt: str, task_type: str, **kwargs) -> Optional[str]:
+        """Call local model for inference."""
+        if not self.local_loader:
+            return None
+        
+        model_id = model_config["model_id"]
+        max_tokens = kwargs.get('max_tokens', 512)
+        temperature = kwargs.get('temperature', 0.7)
+        
+        try:
+            # Ensure model is loaded
+            if model_id not in self.local_loader.loaded_models:
+                logger.info(f"Loading model {model_id} on demand...")
+                self.local_loader.load_chat_model(model_id, load_in_8bit=False)
+            
+            # Format as chat messages if needed
+            messages = [{"role": "user", "content": prompt}]
+            
+            # Generate using local model
+            result = await asyncio.to_thread(
+                self.local_loader.generate_chat_completion,
+                model_id=model_id,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature
+            )
+            
+            logger.info(f"Local model {model_id} generated response (length: {len(result)})")
+            logger.info("=" * 80)
+            logger.info("LOCAL MODEL RESPONSE:")
+            logger.info("=" * 80)
+            logger.info(f"Model: {model_id}")
+            logger.info(f"Task Type: {task_type}")
+            logger.info(f"Response Length: {len(result)} characters")
+            logger.info("-" * 40)
+            logger.info("FULL RESPONSE CONTENT:")
+            logger.info("-" * 40)
+            logger.info(result)
+            logger.info("-" * 40)
+            logger.info("END OF RESPONSE")
+            logger.info("=" * 80)
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Error calling local model: {e}", exc_info=True)
+            return None
+    
+    async def _call_local_embedding(self, model_config: dict, text: str, **kwargs) -> Optional[list]:
+        """Call local embedding model."""
+        if not self.local_loader:
+            return None
+        
+        model_id = model_config["model_id"]
+        
+        try:
+            # Ensure model is loaded
+            if model_id not in self.local_loader.loaded_embedding_models:
+                logger.info(f"Loading embedding model {model_id} on demand...")
+                self.local_loader.load_embedding_model(model_id)
+            
+            # Generate embedding
+            embedding = await asyncio.to_thread(
+                self.local_loader.get_embedding,
+                model_id=model_id,
+                text=text
+            )
+            
+            logger.info(f"Local embedding model {model_id} generated vector (dim: {len(embedding)})")
+            return embedding
+            
+        except Exception as e:
+            logger.error(f"Error calling local embedding model: {e}", exc_info=True)
+            return None
+    
+    def _select_model(self, task_type: str) -> dict:
+        model_map = {
+            "intent_classification": LLM_CONFIG["models"]["classification_specialist"],
+            "embedding_generation": LLM_CONFIG["models"]["embedding_specialist"],
+            "safety_check": LLM_CONFIG["models"]["safety_checker"],
+            "general_reasoning": LLM_CONFIG["models"]["reasoning_primary"],
+            "response_synthesis": LLM_CONFIG["models"]["reasoning_primary"]
+        }
+        return model_map.get(task_type, LLM_CONFIG["models"]["reasoning_primary"])
+    
+    async def _is_model_healthy(self, model_id: str) -> bool:
+        """
+        Check if the model is healthy and available
+        Mark models as healthy by default - actual availability checked at API call time
+        """
+        # Check cached health status
+        if model_id in self.health_status:
+            return self.health_status[model_id]
+        
+        # All models marked healthy initially - real check happens during API call
+        self.health_status[model_id] = True
+        return True
+    
+    def _get_fallback_model(self, task_type: str) -> dict:
+        """
+        Get fallback model configuration for the task type
+        """
+        # Fallback mapping
+        fallback_map = {
+            "intent_classification": LLM_CONFIG["models"]["reasoning_primary"],
+            "embedding_generation": LLM_CONFIG["models"]["embedding_specialist"],
+            "safety_check": LLM_CONFIG["models"]["reasoning_primary"],
+            "general_reasoning": LLM_CONFIG["models"]["reasoning_primary"],
+            "response_synthesis": LLM_CONFIG["models"]["reasoning_primary"]
+        }
+        return fallback_map.get(task_type, LLM_CONFIG["models"]["reasoning_primary"])
+    
+    async def _call_hf_endpoint(self, model_config: dict, prompt: str, task_type: str, **kwargs):
+        """
+        FIXED: Make actual call to Hugging Face Chat Completions API
+        Uses the correct chat completions protocol with retry logic and exponential backoff
+        
+        IMPORTANT: task_type parameter is now properly included in the method signature
+        """
+        # Retry configuration
+        max_retries = kwargs.get('max_retries', 3)
+        initial_delay = kwargs.get('initial_delay', 1.0)  # Start with 1 second
+        max_delay = kwargs.get('max_delay', 16.0)  # Cap at 16 seconds
+        timeout = kwargs.get('timeout', 30)
+        
+        try:
+            import requests
+            from requests.exceptions import Timeout, RequestException, ConnectionError as RequestsConnectionError
+            
+            model_id = model_config["model_id"]
+            
+            # Use the chat completions endpoint
+            api_url = "https://router.huggingface.co/v1/chat/completions"
+            
+            logger.info(f"Calling HF Chat Completions API for model: {model_id}")
+            logger.debug(f"Prompt length: {len(prompt)}")
+            logger.info("=" * 80)
+            logger.info("LLM API REQUEST - COMPLETE PROMPT:")
+            logger.info("=" * 80)
+            logger.info(f"Model: {model_id}")
+            
+            # FIXED: task_type is now properly available as a parameter
+            logger.info(f"Task Type: {task_type}")
+            logger.info(f"Prompt Length: {len(prompt)} characters")
+            logger.info("-" * 40)
+            logger.info("FULL PROMPT CONTENT:")
+            logger.info("-" * 40)
+            logger.info(prompt)
+            logger.info("-" * 40)
+            logger.info("END OF PROMPT")
+            logger.info("=" * 80)
+            
+            # Prepare the request payload
+            max_tokens = kwargs.get('max_tokens', 512)
+            temperature = kwargs.get('temperature', 0.7)
+            
+            payload = {
+                "model": model_id,
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": prompt
+                    }
+                ],
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+                "stream": False
+            }
+            
+            headers = {
+                "Authorization": f"Bearer {self.hf_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Retry logic with exponential backoff
+            last_exception = None
+            for attempt in range(max_retries + 1):
+                try:
+                    if attempt > 0:
+                        # Calculate exponential backoff delay
+                        delay = min(initial_delay * (2 ** (attempt - 1)), max_delay)
+                        logger.warning(f"Retry attempt {attempt}/{max_retries} after {delay:.1f}s delay (exponential backoff)")
+                        await asyncio.sleep(delay)
+                    
+                    logger.info(f"Sending request to: {api_url} (attempt {attempt + 1}/{max_retries + 1})")
+                    logger.debug(f"Payload: {payload}")
+                    
+                    response = requests.post(api_url, json=payload, headers=headers, timeout=timeout)
+                    
+                    if response.status_code == 200:
+                        result = response.json()
+                        logger.debug(f"Raw response: {result}")
+                        
+                        if 'choices' in result and len(result['choices']) > 0:
+                            generated_text = result['choices'][0]['message']['content']
+                            
+                            if not generated_text or generated_text.strip() == "":
+                                logger.warning(f"Empty or invalid response, using fallback")
+                                return None
+                            
+                            if attempt > 0:
+                                logger.info(f"Successfully retrieved response after {attempt} retry attempts")
+                            
+                            logger.info(f"HF API returned response (length: {len(generated_text)})")
+                            logger.info("=" * 80)
+                            logger.info("COMPLETE LLM API RESPONSE:")
+                            logger.info("=" * 80)
+                            logger.info(f"Model: {model_id}")
+                            
+                            # FIXED: task_type is now properly available
+                            logger.info(f"Task Type: {task_type}")
+                            logger.info(f"Response Length: {len(generated_text)} characters")
+                            logger.info("-" * 40)
+                            logger.info("FULL RESPONSE CONTENT:")
+                            logger.info("-" * 40)
+                            logger.info(generated_text)
+                            logger.info("-" * 40)
+                            logger.info("END OF LLM RESPONSE")
+                            logger.info("=" * 80)
+                            return generated_text
+                        else:
+                            logger.error(f"Unexpected response format: {result}")
+                            return None
+                    elif response.status_code == 503:
+                        # Model is loading - this is retryable
+                        if attempt < max_retries:
+                            logger.warning(f"Model loading (503), will retry (attempt {attempt + 1}/{max_retries + 1})")
+                            last_exception = Exception(f"Model loading (503)")
+                            continue
+                        else:
+                            # After max retries, try fallback model
+                            logger.warning(f"Model loading (503) after {max_retries} retries, trying fallback model")
+                            fallback_config = self._get_fallback_model(task_type)
+                            
+                            # FIXED: Ensure task_type is passed in recursive call
+                            return await self._call_hf_endpoint(fallback_config, prompt, task_type, **kwargs)
+                    else:
+                        # Non-retryable HTTP errors
+                        logger.error(f"HF API error: {response.status_code} - {response.text}")
+                        return None
+                        
+                except Timeout as e:
+                    last_exception = e
+                    if attempt < max_retries:
+                        logger.warning(f"Request timeout (attempt {attempt + 1}/{max_retries + 1}): {str(e)}")
+                        continue
+                    else:
+                        logger.error(f"Request timeout after {max_retries} retries: {str(e)}")
+                        # Try fallback model on final timeout
+                        logger.warning("Attempting fallback model due to persistent timeout")
+                        fallback_config = self._get_fallback_model(task_type)
+                        return await self._call_hf_endpoint(fallback_config, prompt, task_type, **kwargs)
+                        
+                except (RequestsConnectionError, RequestException) as e:
+                    last_exception = e
+                    if attempt < max_retries:
+                        logger.warning(f"Connection error (attempt {attempt + 1}/{max_retries + 1}): {str(e)}")
+                        continue
+                    else:
+                        logger.error(f"Connection error after {max_retries} retries: {str(e)}")
+                        # Try fallback model on final connection error
+                        logger.warning("Attempting fallback model due to persistent connection error")
+                        fallback_config = self._get_fallback_model(task_type)
+                        return await self._call_hf_endpoint(fallback_config, prompt, task_type, **kwargs)
+            
+            # If we exhausted all retries and didn't return
+            if last_exception:
+                logger.error(f"Failed after {max_retries} retries. Last error: {last_exception}")
+                return None
+                
+        except ImportError:
+            logger.warning("requests library not available, using mock response")
+            return f"[Mock] Response to: {prompt[:100]}..."
+        except Exception as e:
+            logger.error(f"Error calling HF endpoint: {e}", exc_info=True)
+            return None
+    
+    async def get_available_models(self):
+        """
+        Get list of available models for testing
+        """
+        return list(LLM_CONFIG["models"].keys())
+    
+    async def health_check(self):
+        """
+        Perform health check on all models
+        """
+        health_status = {}
+        for model_name, model_config in LLM_CONFIG["models"].items():
+            model_id = model_config["model_id"]
+            is_healthy = await self._is_model_healthy(model_id)
+            health_status[model_name] = {
+                "model_id": model_id,
+                "healthy": is_healthy
+            }
+        
+        return health_status
+    
+    def prepare_context_for_llm(self, raw_context: Dict, max_tokens: int = 4000) -> str:
+        """Smart context windowing for LLM calls"""
+        
+        try:
+            from transformers import AutoTokenizer
+            
+            # Initialize tokenizer lazily
+            if not hasattr(self, 'tokenizer'):
+                try:
+                    self.tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
+                except Exception as e:
+                    logger.warning(f"Could not load tokenizer: {e}, using character count estimation")
+                    self.tokenizer = None
+        except ImportError:
+            logger.warning("transformers library not available, using character count estimation")
+            self.tokenizer = None
+        
+        # Priority order for context elements
+        priority_elements = [
+            ('current_query', 1.0),
+            ('recent_interactions', 0.8),
+            ('user_preferences', 0.6),
+            ('session_summary', 0.4),
+            ('historical_context', 0.2)
+        ]
+        
+        formatted_context = []
+        total_tokens = 0
+        
+        for element, priority in priority_elements:
+            # Map element names to context keys
+            element_key_map = {
+                'current_query': raw_context.get('user_input', ''),
+                'recent_interactions': raw_context.get('interaction_contexts', []),
+                'user_preferences': raw_context.get('preferences', {}),
+                'session_summary': raw_context.get('session_context', {}),
+                'historical_context': raw_context.get('user_context', '')
+            }
+            
+            content = element_key_map.get(element, '')
+            
+            # Convert to string if needed
+            if isinstance(content, dict):
+                content = str(content)
+            elif isinstance(content, list):
+                content = "\n".join([str(item) for item in content[:10]])  # Limit to 10 items
+            
+            if not content:
+                continue
+            
+            # Estimate tokens
+            if self.tokenizer:
+                try:
+                    tokens = len(self.tokenizer.encode(content))
+                except:
+                    # Fallback to character-based estimation (rough: 1 token ≈ 4 chars)
+                    tokens = len(content) // 4
+            else:
+                # Character-based estimation (rough: 1 token ≈ 4 chars)
+                tokens = len(content) // 4
+            
+            if total_tokens + tokens <= max_tokens:
+                formatted_context.append(f"=== {element.upper()} ===\n{content}")
+                total_tokens += tokens
+            elif priority > 0.5:  # Critical elements - truncate if needed
+                available = max_tokens - total_tokens
+                if available > 100:  # Only truncate if we have meaningful space
+                    truncated = self._truncate_to_tokens(content, available)
+                    formatted_context.append(f"=== {element.upper()} (TRUNCATED) ===\n{truncated}")
+                break
+        
+        return "\n\n".join(formatted_context)
+    
+    def _truncate_to_tokens(self, content: str, max_tokens: int) -> str:
+        """Truncate content to fit within token limit"""
+        if not self.tokenizer:
+            # Simple character-based truncation
+            max_chars = max_tokens * 4
+            if len(content) <= max_chars:
+                return content
+            return content[:max_chars-3] + "..."
+        
+        try:
+            # Tokenize and truncate
+            tokens = self.tokenizer.encode(content)
+            if len(tokens) <= max_tokens:
+                return content
+            
+            truncated_tokens = tokens[:max_tokens-3]  # Leave room for "..."
+            truncated_text = self.tokenizer.decode(truncated_tokens)
+            return truncated_text + "..."
+        except Exception as e:
+            logger.warning(f"Error truncating with tokenizer: {e}, using character truncation")
+            max_chars = max_tokens * 4
+            if len(content) <= max_chars:
+                return content
+            return content[:max_chars-3] + "..."

src/local_model_loader.py

@@ -0,0 +1,322 @@
+# local_model_loader.py
+# Local GPU-based model loading for NVIDIA T4 Medium (24GB vRAM)
+import logging
+import torch
+from typing import Optional, Dict, Any
+from transformers import AutoModelForCausalLM, AutoTokenizer, AutoModel
+from sentence_transformers import SentenceTransformer
+
+logger = logging.getLogger(__name__)
+
+class LocalModelLoader:
+    """
+    Loads and manages models locally on GPU for faster inference.
+    Optimized for NVIDIA T4 Medium with 24GB vRAM.
+    """
+    
+    def __init__(self, device: Optional[str] = None):
+        """Initialize the model loader with GPU device detection."""
+        # Detect device
+        if device is None:
+            if torch.cuda.is_available():
+                self.device = "cuda"
+                self.device_name = torch.cuda.get_device_name(0)
+                logger.info(f"GPU detected: {self.device_name}")
+                logger.info(f"GPU Memory: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.2f} GB")
+            else:
+                self.device = "cpu"
+                self.device_name = "CPU"
+                logger.warning("No GPU detected, using CPU")
+        else:
+            self.device = device
+            self.device_name = device
+        
+        # Model cache
+        self.loaded_models: Dict[str, Any] = {}
+        self.loaded_tokenizers: Dict[str, Any] = {}
+        self.loaded_embedding_models: Dict[str, Any] = {}
+        
+    def load_chat_model(self, model_id: str, load_in_8bit: bool = False, load_in_4bit: bool = False) -> tuple:
+        """
+        Load a chat model and tokenizer on GPU.
+        
+        Args:
+            model_id: HuggingFace model identifier
+            load_in_8bit: Use 8-bit quantization (saves memory)
+            load_in_4bit: Use 4-bit quantization (saves more memory)
+        
+        Returns:
+            Tuple of (model, tokenizer)
+        """
+        if model_id in self.loaded_models:
+            logger.info(f"Model {model_id} already loaded, reusing")
+            return self.loaded_models[model_id], self.loaded_tokenizers[model_id]
+        
+        try:
+            logger.info(f"Loading model {model_id} on {self.device}...")
+            
+            # Load tokenizer
+            tokenizer = AutoTokenizer.from_pretrained(
+                model_id,
+                trust_remote_code=True
+            )
+            
+            # Determine quantization config
+            if load_in_4bit and self.device == "cuda":
+                try:
+                    from transformers import BitsAndBytesConfig
+                    quantization_config = BitsAndBytesConfig(
+                        load_in_4bit=True,
+                        bnb_4bit_compute_dtype=torch.float16,
+                        bnb_4bit_use_double_quant=True,
+                        bnb_4bit_quant_type="nf4"
+                    )
+                    logger.info("Using 4-bit quantization")
+                except ImportError:
+                    logger.warning("bitsandbytes not available, loading without quantization")
+                    quantization_config = None
+            elif load_in_8bit and self.device == "cuda":
+                try:
+                    quantization_config = {"load_in_8bit": True}
+                    logger.info("Using 8-bit quantization")
+                except:
+                    quantization_config = None
+            else:
+                quantization_config = None
+            
+            # Load model with GPU optimization
+            if self.device == "cuda":
+                model = AutoModelForCausalLM.from_pretrained(
+                    model_id,
+                    device_map="auto",  # Automatically uses GPU
+                    torch_dtype=torch.float16,  # Use FP16 for memory efficiency
+                    trust_remote_code=True,
+                    **(quantization_config if isinstance(quantization_config, dict) else {}),
+                    **({"quantization_config": quantization_config} if quantization_config and not isinstance(quantization_config, dict) else {})
+                )
+            else:
+                model = AutoModelForCausalLM.from_pretrained(
+                    model_id,
+                    torch_dtype=torch.float32,
+                    trust_remote_code=True
+                )
+                model = model.to(self.device)
+            
+            # Ensure padding token is set
+            if tokenizer.pad_token is None:
+                tokenizer.pad_token = tokenizer.eos_token
+            
+            # Cache models
+            self.loaded_models[model_id] = model
+            self.loaded_tokenizers[model_id] = tokenizer
+            
+            # Log memory usage
+            if self.device == "cuda":
+                allocated = torch.cuda.memory_allocated(0) / 1024**3
+                reserved = torch.cuda.memory_reserved(0) / 1024**3
+                logger.info(f"GPU Memory - Allocated: {allocated:.2f} GB, Reserved: {reserved:.2f} GB")
+            
+            logger.info(f"✓ Model {model_id} loaded successfully on {self.device}")
+            return model, tokenizer
+            
+        except Exception as e:
+            logger.error(f"Error loading model {model_id}: {e}", exc_info=True)
+            raise
+    
+    def load_embedding_model(self, model_id: str) -> SentenceTransformer:
+        """
+        Load a sentence transformer model for embeddings.
+        
+        Args:
+            model_id: HuggingFace model identifier
+        
+        Returns:
+            SentenceTransformer model
+        """
+        if model_id in self.loaded_embedding_models:
+            logger.info(f"Embedding model {model_id} already loaded, reusing")
+            return self.loaded_embedding_models[model_id]
+        
+        try:
+            logger.info(f"Loading embedding model {model_id}...")
+            
+            # SentenceTransformer automatically handles GPU
+            model = SentenceTransformer(
+                model_id,
+                device=self.device
+            )
+            
+            # Cache model
+            self.loaded_embedding_models[model_id] = model
+            
+            logger.info(f"✓ Embedding model {model_id} loaded successfully on {self.device}")
+            return model
+            
+        except Exception as e:
+            logger.error(f"Error loading embedding model {model_id}: {e}", exc_info=True)
+            raise
+    
+    def generate_text(
+        self,
+        model_id: str,
+        prompt: str,
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs
+    ) -> str:
+        """
+        Generate text using a loaded chat model.
+        
+        Args:
+            model_id: Model identifier
+            prompt: Input prompt
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature
+        
+        Returns:
+            Generated text
+        """
+        if model_id not in self.loaded_models:
+            raise ValueError(f"Model {model_id} not loaded. Call load_chat_model() first.")
+        
+        model = self.loaded_models[model_id]
+        tokenizer = self.loaded_tokenizers[model_id]
+        
+        try:
+            # Tokenize input
+            inputs = tokenizer(prompt, return_tensors="pt").to(self.device)
+            
+            # Generate
+            with torch.no_grad():
+                outputs = model.generate(
+                    **inputs,
+                    max_new_tokens=max_tokens,
+                    temperature=temperature,
+                    do_sample=True,
+                    pad_token_id=tokenizer.pad_token_id,
+                    eos_token_id=tokenizer.eos_token_id,
+                    **kwargs
+                )
+            
+            # Decode
+            generated_text = tokenizer.decode(outputs[0], skip_special_tokens=True)
+            
+            # Remove prompt from output if present
+            if generated_text.startswith(prompt):
+                generated_text = generated_text[len(prompt):].strip()
+            
+            return generated_text
+            
+        except Exception as e:
+            logger.error(f"Error generating text: {e}", exc_info=True)
+            raise
+    
+    def generate_chat_completion(
+        self,
+        model_id: str,
+        messages: list,
+        max_tokens: int = 512,
+        temperature: float = 0.7,
+        **kwargs
+    ) -> str:
+        """
+        Generate chat completion using a loaded model.
+        
+        Args:
+            model_id: Model identifier
+            messages: List of message dicts with 'role' and 'content'
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature
+        
+        Returns:
+            Generated response
+        """
+        if model_id not in self.loaded_models:
+            raise ValueError(f"Model {model_id} not loaded. Call load_chat_model() first.")
+        
+        model = self.loaded_models[model_id]
+        tokenizer = self.loaded_tokenizers[model_id]
+        
+        try:
+            # Format messages as prompt
+            if hasattr(tokenizer, 'apply_chat_template'):
+                # Use chat template if available
+                prompt = tokenizer.apply_chat_template(
+                    messages,
+                    tokenize=False,
+                    add_generation_prompt=True
+                )
+            else:
+                # Fallback: simple formatting
+                prompt = "\n".join([
+                    f"{msg['role']}: {msg['content']}"
+                    for msg in messages
+                ]) + "\nassistant: "
+            
+            # Generate
+            return self.generate_text(
+                model_id=model_id,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                **kwargs
+            )
+            
+        except Exception as e:
+            logger.error(f"Error generating chat completion: {e}", exc_info=True)
+            raise
+    
+    def get_embedding(self, model_id: str, text: str) -> list:
+        """
+        Get embedding vector for text.
+        
+        Args:
+            model_id: Embedding model identifier
+            text: Input text
+        
+        Returns:
+            Embedding vector
+        """
+        if model_id not in self.loaded_embedding_models:
+            raise ValueError(f"Embedding model {model_id} not loaded. Call load_embedding_model() first.")
+        
+        model = self.loaded_embedding_models[model_id]
+        
+        try:
+            embedding = model.encode(text, convert_to_numpy=True)
+            return embedding.tolist()
+        except Exception as e:
+            logger.error(f"Error getting embedding: {e}", exc_info=True)
+            raise
+    
+    def clear_cache(self):
+        """Clear all loaded models from memory."""
+        logger.info("Clearing model cache...")
+        
+        # Clear models
+        for model_id in list(self.loaded_models.keys()):
+            del self.loaded_models[model_id]
+        for model_id in list(self.loaded_tokenizers.keys()):
+            del self.loaded_tokenizers[model_id]
+        for model_id in list(self.loaded_embedding_models.keys()):
+            del self.loaded_embedding_models[model_id]
+        
+        # Clear GPU cache
+        if self.device == "cuda":
+            torch.cuda.empty_cache()
+        
+        logger.info("✓ Model cache cleared")
+    
+    def get_memory_usage(self) -> Dict[str, float]:
+        """Get current GPU memory usage in GB."""
+        if self.device != "cuda":
+            return {"device": "cpu", "gpu_available": False}
+        
+        return {
+            "device": self.device_name,
+            "gpu_available": True,
+            "allocated_gb": torch.cuda.memory_allocated(0) / 1024**3,
+            "reserved_gb": torch.cuda.memory_reserved(0) / 1024**3,
+            "total_gb": torch.cuda.get_device_properties(0).total_memory / 1024**3
+        }
+

src/mobile_handlers.py

@@ -0,0 +1,169 @@
+# mobile_handlers.py
+import gradio as gr
+
+class MobileUXHandlers:
+    def __init__(self, orchestrator):
+        self.orchestrator = orchestrator
+        self.mobile_state = {}
+        
+    async def handle_mobile_submit(self, message, chat_history, session_id, 
+                                 show_reasoning, show_agent_trace, request: gr.Request):
+        """
+        Mobile-optimized submission handler with enhanced UX
+        """
+        # Get mobile device info
+        user_agent = request.headers.get("user-agent", "").lower()
+        is_mobile = any(device in user_agent for device in ['mobile', 'android', 'iphone'])
+        
+        # Mobile-specific optimizations
+        if is_mobile:
+            return await self._mobile_optimized_processing(
+                message, chat_history, session_id, show_reasoning, show_agent_trace
+            )
+        else:
+            return await self._desktop_processing(
+                message, chat_history, session_id, show_reasoning, show_agent_trace
+            )
+    
+    async def _mobile_optimized_processing(self, message, chat_history, session_id, 
+                                         show_reasoning, show_agent_trace):
+        """
+        Mobile-specific processing with enhanced UX feedback
+        """
+        try:
+            # Immediate feedback for mobile users
+            yield {
+                "chatbot": chat_history + [[message, "Thinking..."]],
+                "message_input": "",
+                "reasoning_display": {"status": "processing"},
+                "performance_display": {"status": "processing"}
+            }
+            
+            # Process with mobile-optimized parameters
+            result = await self.orchestrator.process_request(
+                session_id=session_id,
+                user_input=message,
+                mobile_optimized=True,  # Special flag for mobile
+                max_tokens=800  # Shorter responses for mobile
+            )
+            
+            # Format for mobile display
+            formatted_response = self._format_for_mobile(
+                result['final_response'],
+                show_reasoning and result.get('metadata', {}).get('reasoning_chain'),
+                show_agent_trace and result.get('agent_trace')
+            )
+            
+            # Update chat history
+            updated_history = chat_history + [[message, formatted_response]]
+            
+            yield {
+                "chatbot": updated_history,
+                "message_input": "",
+                "reasoning_display": result.get('metadata', {}).get('reasoning_chain', {}),
+                "performance_display": result.get('performance_metrics', {})
+            }
+            
+        except Exception as e:
+            # Mobile-friendly error handling
+            error_response = self._get_mobile_friendly_error(e)
+            yield {
+                "chatbot": chat_history + [[message, error_response]],
+                "message_input": message,  # Keep message for retry
+                "reasoning_display": {"error": "Processing failed"},
+                "performance_display": {"error": str(e)}
+            }
+    
+    def _format_for_mobile(self, response, reasoning_chain, agent_trace):
+        """
+        Format response for optimal mobile readability
+        """
+        # Split long responses for mobile
+        if len(response) > 400:
+            paragraphs = self._split_into_paragraphs(response, max_length=300)
+            response = "\n\n".join(paragraphs)
+        
+        # Add mobile-optimized formatting
+        formatted = f"""
+<div class="mobile-response">
+{response}
+</div>
+"""
+        
+        # Add reasoning if requested
+        if reasoning_chain:
+            # Handle both old and new reasoning chain formats
+            if isinstance(reasoning_chain, dict):
+                # New enhanced format - extract key information
+                chain_of_thought = reasoning_chain.get('chain_of_thought', {})
+                if chain_of_thought:
+                    first_step = list(chain_of_thought.values())[0] if chain_of_thought else {}
+                    hypothesis = first_step.get('hypothesis', 'Processing...')
+                    reasoning_text = f"Hypothesis: {hypothesis}"
+                else:
+                    reasoning_text = "Enhanced reasoning chain available"
+            else:
+                # Old format - direct string
+                reasoning_text = str(reasoning_chain)[:200]
+            
+            formatted += f"""
+<div class="reasoning-mobile" style="margin-top: 15px; padding: 10px; background: #f5f5f5; border-radius: 8px; font-size: 14px;">
+<strong>Reasoning:</strong> {reasoning_text}...
+</div>
+"""
+        
+        return formatted
+    
+    def _get_mobile_friendly_error(self, error):
+        """
+        User-friendly error messages for mobile
+        """
+        error_messages = {
+            "timeout": "⏱️ Taking longer than expected. Please try a simpler question.",
+            "network": "📡 Connection issue. Check your internet and try again.",
+            "rate_limit": "🚦 Too many requests. Please wait a moment.",
+            "default": "❌ Something went wrong. Please try again."
+        }
+        
+        error_type = "default"
+        if "timeout" in str(error).lower():
+            error_type = "timeout"
+        elif "network" in str(error).lower() or "connection" in str(error).lower():
+            error_type = "network"
+        elif "rate" in str(error).lower():
+            error_type = "rate_limit"
+            
+        return error_messages[error_type]
+    
+    async def _desktop_processing(self, message, chat_history, session_id, 
+                                show_reasoning, show_agent_trace):
+        """
+        Desktop processing without mobile optimizations
+        """
+        # TODO: Implement desktop-specific processing
+        return {
+            "chatbot": chat_history,
+            "message_input": "",
+            "reasoning_display": {},
+            "performance_display": {}
+        }
+    
+    def _split_into_paragraphs(self, text, max_length=300):
+        """
+        Split text into mobile-friendly paragraphs
+        """
+        # TODO: Implement intelligent paragraph splitting
+        words = text.split()
+        paragraphs = []
+        current_para = []
+        
+        for word in words:
+            current_para.append(word)
+            if len(' '.join(current_para)) > max_length:
+                paragraphs.append(' '.join(current_para[:-1]))
+                current_para = [current_para[-1]]
+        
+        if current_para:
+            paragraphs.append(' '.join(current_para))
+        
+        return paragraphs

src/models_config.py

@@ -0,0 +1,43 @@
+# models_config.py
+LLM_CONFIG = {
+    "primary_provider": "huggingface",
+    "models": {
+        "reasoning_primary": {
+            "model_id": "Qwen/Qwen2.5-7B-Instruct",  # High-quality instruct model
+            "task": "general_reasoning",
+            "max_tokens": 10000,
+            "temperature": 0.7,
+            "cost_per_token": 0.000015,
+            "fallback": "gpt2",  # Simple but guaranteed working model
+            "is_chat_model": True
+        },
+        "embedding_specialist": {
+            "model_id": "sentence-transformers/all-MiniLM-L6-v2",
+            "task": "embeddings",
+            "vector_dimensions": 384,
+            "purpose": "semantic_similarity",
+            "cost_advantage": "90%_cheaper_than_primary",
+            "is_chat_model": False
+        },
+        "classification_specialist": {
+            "model_id": "Qwen/Qwen2.5-7B-Instruct",  # Use chat model for classification
+            "task": "intent_classification",
+            "max_length": 512,
+            "specialization": "fast_inference",
+            "latency_target": "<100ms",
+            "is_chat_model": True
+        },
+        "safety_checker": {
+            "model_id": "Qwen/Qwen2.5-7B-Instruct",  # Use chat model for safety
+            "task": "content_moderation",
+            "confidence_threshold": 0.85,
+            "purpose": "bias_detection",
+            "is_chat_model": True
+        }
+    },
+    "routing_logic": {
+        "strategy": "task_based_routing",
+        "fallback_chain": ["primary", "fallback", "degraded_mode"],
+        "load_balancing": "round_robin_with_health_check"
+    }
+}