Initial commit: add all project files

.env.example

@@ -0,0 +1,53 @@
+# ==================== API KEYS ====================
+GROQ_API_KEY=your_groq_api_key_here
+
+
+# ==================== APPLICATION CONFIG ====================
+APP_ENV=development  # development or production
+LOG_LEVEL=INFO       # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+
+# ==================== CONVERSATION SETTINGS ====================
+MAX_HISTORY_LENGTH=10
+MAX_CONVERSATION_STORAGE=1000
+
+
+# ==================== MODEL PARAMETERS ====================
+DEFAULT_TEMPERATURE=0.7
+DEFAULT_MAX_TOKENS=4000
+
+
+# ==================== API SETTINGS ====================
+REQUEST_TIMEOUT=60
+MAX_RETRIES=3
+RETRY_DELAY=1.0
+
+
+# ==================== CACHE SETTINGS ====================
+ENABLE_CACHE=true
+CACHE_SIZE=100
+CACHE_TTL=3600  # seconds (1 hour)
+
+
+# ==================== RATE LIMITING ====================
+ENABLE_RATE_LIMITING=true
+RATE_LIMIT_REQUESTS=50
+RATE_LIMIT_WINDOW=60  # seconds
+
+
+# ==================== FILE STORAGE ====================
+EXPORT_DIR=exports
+BACKUP_DIR=backups
+
+
+# ==================== UI THEME ====================
+THEME_PRIMARY=purple
+THEME_SECONDARY=blue
+
+
+# ==================== PERFORMANCE ====================
+MAX_WORKERS=3
+
+
+# ==================== FEATURE FLAGS ====================
+ENABLE_PDF_EXPORT=true

.gitignore

@@ -0,0 +1,68 @@
+# 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 Environment
+venv/
+env/
+ENV/
+.venv
+
+# Environment Variables
+.env
+.env.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs
+logs/
+*.log
+
+# Exports and Backups
+exports/
+backups/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Gradio
+gradio_cached_examples/
+flagged/

Dockerfile

@@ -0,0 +1,3 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY . /app

README.md

@@ -0,0 +1,270 @@
+# 🧠 Advanced AI Reasoning System Pro
+
+A production-ready AI reasoning application built with Gradio and Groq API, featuring multiple research-backed reasoning methodologies, advanced caching, real-time analytics, and comprehensive export capabilities.
+
+## ✨ Features
+
+### 🔬 Research-Backed Reasoning Modes
+- **Tree of Thoughts (ToT)** - Systematic exploration of multiple reasoning paths
+- **Chain of Thought (CoT)** - Step-by-step logical reasoning
+- **Self-Consistency** - Multiple solution paths with consensus
+- **Reflexion** - Self-critique and iterative improvement
+- **Multi-Agent Debate** - Multiple perspectives and synthesis
+- **Analogical Reasoning** - Problem-solving through analogies
+
+### ⚡ Performance Features
+- **Response Caching** - LRU cache with TTL for faster responses
+- **Rate Limiting** - Token bucket algorithm to prevent API abuse
+- **Streaming Responses** - Real-time response generation
+- **Multi-threading** - Concurrent request handling
+
+### 📊 Analytics & Monitoring
+- **Real-time Metrics** - Live performance tracking
+- **Conversation Analytics** - Usage patterns and insights
+- **Cache Statistics** - Hit rates and performance metrics
+- **Session Tracking** - Unique session identification
+
+### 📤 Export Capabilities
+- **Multiple Formats** - JSON, Markdown, TXT, PDF
+- **Metadata Support** - Timestamps, models, performance data
+- **Automatic Backups** - Periodic conversation backups
+- **Search Functionality** - Keyword-based conversation search
+
+### 🎨 User Interface
+- **Collapsible Sidebar** - Clean, distraction-free workspace
+- **Multiple Tabs** - Reasoning, Export, Analytics, Settings
+- **Live Metrics Display** - Real-time performance indicators
+- **Responsive Design** - Mobile-friendly interface
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.9+
+- Groq API Key ([Get one here](https://console.groq.com))
+
+### Installation
+
+1. **Clone the repository**
+1. **Clone the repository**
+git clone <repository-url>
+cd reasoning-system-pro
+
+text
+
+2. **Create virtual environment**
+python -m venv venv
+source venv/bin/activate # On Windows: venv\Scripts\activate
+
+text
+
+3. **Install dependencies**
+pip install -r requirements.txt
+
+text
+
+4. **Configure environment**
+cp .env.example .env
+
+Edit .env and add your GROQ_API_KEY
+text
+
+5. **Run the application**
+python main.py
+
+text
+
+6. **Open in browser**
+http://localhost:7860
+
+text
+
+## 📁 Project Structure
+
+reasoning-system-pro/
+├── src/
+│ ├── api/ # API client management
+│ ├── core/ # Core business logic
+│ ├── models/ # Data models
+│ ├── services/ # Business services
+│ ├── ui/ # Gradio interface
+│ ├── utils/ # Utilities
+│ └── config/ # Configuration
+├── tests/ # Test suite
+├── exports/ # Generated exports
+├── backups/ # Conversation backups
+├── logs/ # Application logs
+├── main.py # Entry point
+├── requirements.txt # Dependencies
+└── .env # Environment config
+
+text
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Key configuration options in `.env`:
+
+API
+GROQ_API_KEY=your_key_here
+
+Performance
+CACHE_SIZE=100
+RATE_LIMIT_REQUESTS=50
+
+Features
+ENABLE_PDF_EXPORT=true
+ENABLE_CACHE=true
+
+text
+
+### Advanced Configuration
+
+Edit `src/config/settings.py` for fine-tuned control over:
+- Cache TTL and size
+- Rate limiting parameters
+- Request timeouts and retries
+- File storage locations
+- UI themes
+
+## 📖 Usage Examples
+
+### Basic Query
+Simply type your question in the chat interface
+"Explain quantum entanglement using the Tree of Thoughts method"
+
+text
+
+### With Self-Critique
+Enable "Self-Critique" checkbox for automatic validation and refinement.
+
+### Custom Templates
+Select from pre-built templates:
+- Research Analysis
+- Problem Solving
+- Code Review
+- Writing Enhancement
+- Debate Analysis
+- Learning Explanation
+
+## 🧪 Testing
+
+Run all tests
+pytest
+
+With coverage
+pytest --cov=src --cov-report=html
+
+Specific test file
+pytest tests/test_reasoner.py
+
+text
+
+## 📊 Available Models
+
+### Meta / Llama Models
+- `llama-3.3-70b-versatile` - Best overall performance
+- `llama-3.1-8b-instant` - Ultra-fast responses
+- `llama-4-maverick-17b-128k` - Experimental long context
+
+### DeepSeek Models
+- `deepseek-r1-distill-llama-70b` - Optimized reasoning
+
+### Mixtral Models
+- `mixtral-8x7b-32768` - Long context specialist
+
+And many more! See `src/config/constants.py` for the full list.
+
+## 🛠️ Development
+
+### Code Style
+Format code
+black src/
+
+Check linting
+flake8 src/
+
+Type checking
+mypy src/
+
+text
+
+### Adding New Reasoning Modes
+
+1. Add to `src/config/constants.py`:
+class ReasoningMode(Enum):
+YOUR_MODE = "Your Mode Name"
+
+text
+
+2. Add system prompt in `src/core/prompt_engine.py`:
+SYSTEM_PROMPTS = {
+ReasoningMode.YOUR_MODE: "Your prompt here..."
+}
+
+text
+
+## 📝 API Documentation
+
+### Core Classes
+
+#### AdvancedReasoner
+Main reasoning engine with streaming support.
+
+reasoner = AdvancedReasoner()
+for response in reasoner.generate_response(query, ...):
+print(response)
+
+text
+
+#### ResponseCache
+Thread-safe LRU cache with TTL.
+
+cache = ResponseCache(maxsize=100, ttl=3600)
+cache.set(key, value)
+result = cache.get(key)
+
+text
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue: "GROQ_API_KEY not found"**
+- Solution: Ensure `.env` file exists and contains `GROQ_API_KEY=your_key`
+
+**Issue: PDF export fails**
+- Solution: Install reportlab: `pip install reportlab`
+
+**Issue: Rate limit errors**
+- Solution: Increase `RATE_LIMIT_WINDOW` in `.env`
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+## 🙏 Acknowledgments
+
+- **Yao et al. (2023)** - Tree of Thoughts
+- **Wei et al. (2022)** - Chain of Thought
+- **Bai et al. (2022)** - Constitutional AI
+- **Groq** - High-speed LLM inference
+
+## 📧 Support
+
+For issues and questions:
+- Create an issue on GitHub
+- Check existing documentation
+- Review logs in `logs/` directory
+
+---
+
+**Built with ❤️ using Gradio and Groq**

docker-compose.yml

@@ -0,0 +1,4 @@
+version: '3.8'
+services:
+  app:
+    build: .

docs/API.md

@@ -0,0 +1,2 @@
+# API
+

docs/ARCHITECTURE.md

@@ -0,0 +1,2 @@
+# Architecture
+

docs/DEPLOYMENT.md

@@ -0,0 +1,2 @@
+# Deployment Instructions
+

main.py

@@ -0,0 +1,53 @@
+"""
+Main application entry point
+"""
+from src.config.env import load_environment
+from src.config.settings import AppConfig
+from src.config.constants import ReasoningMode, ModelConfig
+from src.ui.app import create_ui
+from src.utils.logger import logger
+
+
+def main():
+    """
+    🚀 APPLICATION ENTRY POINT
+    """
+    try:
+        # Load environment variables
+        load_environment()
+        
+        # Print startup information
+        logger.info("="*60)
+        logger.info("🚀 Starting Advanced AI Reasoning System Pro...")
+        logger.info(f"🌍 Environment: {AppConfig.ENV}")
+        logger.info(f"🎨 Theme: {AppConfig.THEME_PRIMARY}/{AppConfig.THEME_SECONDARY}")
+        logger.info(f"🤖 Available Models: {len(ModelConfig)}")
+        logger.info(f"🧠 Reasoning Modes: {len(ReasoningMode)}")
+        logger.info(f"💾 Cache: {AppConfig.CACHE_SIZE} entries")
+        logger.info(f"⏱️  Rate Limit: {AppConfig.RATE_LIMIT_REQUESTS} req/{AppConfig.RATE_LIMIT_WINDOW}s")
+        logger.info("🎛️ Features: Collapsible Sidebar, PDF Export, Real-time Analytics")
+        logger.info("="*60)
+        
+        # Create and launch UI
+        demo = create_ui()
+        demo.launch(
+            share=False,
+            server_name="0.0.0.0",
+            server_port=7860,
+            show_error=True,
+            show_api=False,
+            favicon_path=None,
+            max_threads=AppConfig.MAX_WORKERS
+        )
+        
+    except KeyboardInterrupt:
+        logger.info("⏹️  Application stopped by user (Ctrl+C)")
+    except Exception as e:
+        logger.critical(f"❌ Failed to start application: {e}", exc_info=True)
+        raise
+    finally:
+        logger.info("👋 Shutting down gracefully...")
+
+
+if __name__ == "__main__":
+    main()

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+python_files = test_*.py

requirements-dev.txt

@@ -0,0 +1,22 @@
+# Development and Testing Dependencies
+-r requirements.txt
+
+# Testing
+pytest>=7.4.0
+pytest-cov>=4.1.0
+pytest-asyncio>=0.21.0
+pytest-mock>=3.11.0
+
+# Code Quality
+black>=23.0.0
+flake8>=6.0.0
+mypy>=1.5.0
+pylint>=3.0.0
+isort>=5.12.0
+
+# Documentation
+sphinx>=7.0.0
+sphinx-rtd-theme>=1.3.0
+
+# Type Stubs
+types-requests>=2.31.0

requirements.txt

@@ -0,0 +1,14 @@
+# Core Dependencies
+gradio>=4.0.0
+groq>=0.4.0
+python-dotenv>=1.0.0
+
+# PDF Export (Optional but recommended)
+reportlab>=4.0.0
+
+# Development Dependencies (move to requirements-dev.txt if needed)
+pytest>=7.4.0
+pytest-cov>=4.1.0
+black>=23.0.0
+flake8>=6.0.0
+mypy>=1.5.0

scripts/backup.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# backup script

scripts/deploy.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# deploy script

scripts/setup.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# setup script

src/api/__init__.py

@@ -0,0 +1,6 @@
+"""
+API layer package initialization
+"""
+from .groq_client import GroqClientManager
+
+__all__ = ['GroqClientManager']

src/api/endpoints.py

@@ -0,0 +1 @@
+"""API endpoints (placeholder)."""

src/api/groq_client.py

@@ -0,0 +1,90 @@
+"""
+Groq API client manager with singleton pattern
+"""
+import os
+import threading
+from typing import Optional
+from groq import Groq
+from src.utils.logger import logger
+from src.config.settings import AppConfig
+
+
+class GroqClientManager:
+    """
+    🔌 SINGLETON GROQ CLIENT MANAGER
+    Thread-safe singleton pattern for API client
+    """
+    _instance: Optional['GroqClientManager'] = None
+    _lock = threading.Lock()
+    _client: Optional[Groq] = None
+    _initialized = False
+    
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        if not self._initialized:
+            with self._lock:
+                if not self._initialized:
+                    self._initialize_client()
+                    self._initialized = True
+    
+    def _initialize_client(self) -> None:
+        """
+        🔧 INITIALIZE GROQ CLIENT
+        """
+        api_key = os.getenv('GROQ_API_KEY')
+        
+        if not api_key:
+            logger.error("❌ GROQ_API_KEY not found in environment variables")
+            raise EnvironmentError(
+                "GROQ_API_KEY not set. Please add it to your .env file:\n"
+                "GROQ_API_KEY=your_api_key_here"
+            )
+        
+        try:
+            self._client = Groq(
+                api_key=api_key,
+                timeout=AppConfig.REQUEST_TIMEOUT
+            )
+            logger.info("✅ Groq client initialized successfully")
+        except Exception as e:
+            logger.error(f"❌ Failed to initialize Groq client: {e}")
+            raise
+    
+    @property
+    def client(self) -> Groq:
+        """
+        ✅ GET GROQ CLIENT INSTANCE
+        """
+        if self._client is None:
+            raise RuntimeError("Groq client not initialized")
+        return self._client
+    
+    def health_check(self) -> bool:
+        """
+        🏥 HEALTH CHECK
+        """
+        try:
+            if self._client is None:
+                logger.warning("⚠️ Health check failed: Client not initialized")
+                return False
+            
+            logger.debug("✅ Health check passed")
+            return True
+        except Exception as e:
+            logger.error(f"❌ Health check failed: {e}")
+            return False
+    
+    def reset(self) -> None:
+        """
+        🔄 RESET CLIENT (FOR TESTING)
+        """
+        with self._lock:
+            self._client = None
+            self._initialized = False
+            logger.info("🔄 Groq client reset")

src/config/__init__.py

@@ -0,0 +1,8 @@
+"""
+Configuration package initialization
+"""
+from .settings import AppConfig
+from .constants import ReasoningMode, ModelConfig
+from .env import load_environment
+
+__all__ = ['AppConfig', 'ReasoningMode', 'ModelConfig', 'load_environment']

src/config/constants.py

@@ -0,0 +1,111 @@
+"""
+Application constants and enums
+"""
+from enum import Enum
+
+
+class ReasoningMode(Enum):
+    """
+    🧠 RESEARCH-ALIGNED REASONING METHODOLOGIES
+    Based on academic papers and proven techniques
+    """
+    TREE_OF_THOUGHTS = "Tree of Thoughts (ToT)"
+    CHAIN_OF_THOUGHT = "Chain of Thought (CoT)"
+    SELF_CONSISTENCY = "Self-Consistency Sampling"
+    REFLEXION = "Reflexion + Self-Correction"
+    DEBATE = "Multi-Agent Debate"
+    ANALOGICAL = "Analogical Reasoning"
+    
+    def __str__(self) -> str:
+        return self.value
+    
+    @classmethod
+    def get_description(cls, mode: 'ReasoningMode') -> str:
+        """Get detailed description of reasoning mode"""
+        descriptions = {
+            cls.TREE_OF_THOUGHTS: "Explores multiple reasoning paths systematically before converging on the best solution.",
+            cls.CHAIN_OF_THOUGHT: "Breaks down complex problems into clear, logical steps with explicit reasoning.",
+            cls.SELF_CONSISTENCY: "Generates multiple independent solutions and identifies the most consistent answer.",
+            cls.REFLEXION: "Solves problems, critiques reasoning, and refines solutions iteratively.",
+            cls.DEBATE: "Presents multiple perspectives and synthesizes the strongest arguments.",
+            cls.ANALOGICAL: "Finds similar problems and applies their solutions to the current problem."
+        }
+        return descriptions.get(mode, "Advanced reasoning mode")
+
+
+class ModelConfig(Enum):
+    """
+    🤖 AVAILABLE GROQ MODELS
+    """
+    
+    # === Meta / Llama Models ===
+    LLAMA_70B = ("llama-3.3-70b-versatile", 70, 8000, "Best overall performance", "Meta")
+    LLAMA_70B_V31 = ("llama-3.1-70b-versatile", 70, 8000, "Stable production model", "Meta")
+    LLAMA_3_1_8B_INSTANT = ("llama-3.1-8b-instant", 8, 131072, "Ultra-fast responses", "Meta")
+    LLAMA_4_MAVERICK_17B = ("meta-llama/llama-4-maverick-17b-128k", 17, 131072, "Llama 4 experimental", "Meta")
+    LLAMA_4_SCOUT_17B = ("meta-llama/llama-4-scout-17b-16e-instruct", 17, 16384, "Llama 4 scout model", "Meta")
+    LLAMA_GUARD_4_12B = ("meta-llama/llama-guard-4-12b", 12, 8192, "Content moderation", "Meta")
+    LLAMA_PROMPT_GUARD_2_22M = ("meta-llama/llama-prompt-guard-2-22m", 0, 8192, "Prompt injection detection (22M)", "Meta")
+    LLAMA_PROMPT_GUARD_2_86M = ("meta-llama/llama-prompt-guard-2-86m", 0, 8192, "Prompt injection detection (86M)", "Meta")
+    
+    # === DeepSeek Models ===
+    DEEPSEEK_70B = ("deepseek-r1-distill-llama-70b", 70, 8000, "Optimized reasoning", "DeepSeek")
+    
+    # === Mixtral Models ===
+    MIXTRAL_8X7B = ("mixtral-8x7b-32768", 47, 32768, "Long context specialist", "Mixtral")
+    
+    # === Google Gemma Models ===
+    GEMMA_9B = ("gemma2-9b-it", 9, 8192, "Fast and efficient", "Google")
+    
+    # === Moonshot AI Models ===
+    KIMI_K2_INSTRUCT_DEPRECATED = ("moonshotai/kimi-k2-instruct", 0, 200000, "Ultra-long context (Deprecated)", "Moonshot")
+    KIMI_K2_INSTRUCT_0905 = ("moonshotai/kimi-k2-instruct-0905", 0, 200000, "Ultra-long context specialist", "Moonshot")
+    
+    # === OpenAI Models ===
+    GPT_OSS_120B = ("openai/gpt-oss-120b", 120, 8192, "Large open source model", "OpenAI")
+    GPT_OSS_20B = ("openai/gpt-oss-20b", 20, 8192, "Medium open source model", "OpenAI")
+    
+    # === Qwen Models ===
+    QWEN3_32B = ("qwen/qwen3-32b", 32, 32768, "Qwen 3 multilingual", "Qwen")
+    
+    # === Groq Compound Models ===
+    GROQ_COMPOUND = ("groq/compound", 0, 8192, "Groq optimized compound", "Groq")
+    GROQ_COMPOUND_MINI = ("groq/compound-mini", 0, 8192, "Groq mini compound", "Groq")
+    
+    def __init__(self, model_id: str, params_b: int, max_context: int, description: str, provider: str):
+        self.model_id = model_id
+        self.params_b = params_b
+        self.max_context = max_context
+        self.description = description
+        self.provider = provider
+    
+    def __str__(self) -> str:
+        return f"{self.provider} - {self.model_id}"
+    
+    @classmethod
+    def get_by_id(cls, model_id: str) -> 'ModelConfig':
+        """Get model config by ID"""
+        for model in cls:
+            if model.model_id == model_id:
+                return model
+        raise ValueError(f"Model {model_id} not found")
+    
+    @classmethod
+    def get_by_provider(cls, provider: str) -> list:
+        """Get all models by provider"""
+        return [model for model in cls if model.provider == provider]
+    
+    @classmethod
+    def get_recommended(cls) -> 'ModelConfig':
+        """Get recommended default model"""
+        return cls.LLAMA_70B
+    
+    @property
+    def is_long_context(self) -> bool:
+        """Check if model supports long context (>16k)"""
+        return self.max_context > 16384
+    
+    @property
+    def is_fast(self) -> bool:
+        """Check if model is optimized for speed"""
+        return "instant" in self.model_id.lower() or self.params_b < 10

src/config/env.py

@@ -0,0 +1,33 @@
+"""
+Environment variable loader
+"""
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+from src.utils.logger import logger
+
+
+def load_environment() -> None:
+    """
+    Load environment variables from .env file
+    """
+    env_path = Path('.env')
+    
+    if env_path.exists():
+        load_dotenv(env_path)
+        logger.info("✅ Environment variables loaded from .env")
+    else:
+        logger.warning("⚠️ No .env file found. Using default configuration.")
+    
+    # Validate required environment variables
+    required_vars = ['GROQ_API_KEY']
+    missing_vars = [var for var in required_vars if not os.getenv(var)]
+    
+    if missing_vars:
+        logger.error(f"❌ Missing required environment variables: {', '.join(missing_vars)}")
+        raise EnvironmentError(
+            f"Missing required environment variables: {', '.join(missing_vars)}. "
+            "Please create a .env file with these variables."
+        )
+    
+    logger.info("✅ All required environment variables validated")

src/config/settings.py

@@ -0,0 +1,120 @@
+"""
+Application configuration settings
+"""
+import os
+from pathlib import Path
+from typing import ClassVar
+
+
+class AppConfig:
+    """
+    🎛️ CENTRALIZED APPLICATION CONFIGURATION
+    """
+    
+    # Environment
+    ENV: ClassVar[str] = os.getenv('APP_ENV', 'development')
+    DEBUG: ClassVar[bool] = ENV == 'development'
+    
+    # Conversation Settings
+    MAX_HISTORY_LENGTH: ClassVar[int] = int(os.getenv('MAX_HISTORY_LENGTH', '10'))
+    MAX_CONVERSATION_STORAGE: ClassVar[int] = int(os.getenv('MAX_CONVERSATION_STORAGE', '1000'))
+    
+    # Model Parameters
+    DEFAULT_TEMPERATURE: ClassVar[float] = float(os.getenv('DEFAULT_TEMPERATURE', '0.7'))
+    MIN_TEMPERATURE: ClassVar[float] = 0.0
+    MAX_TEMPERATURE: ClassVar[float] = 2.0
+    
+    DEFAULT_MAX_TOKENS: ClassVar[int] = int(os.getenv('DEFAULT_MAX_TOKENS', '4000'))
+    MIN_TOKENS: ClassVar[int] = 100
+    MAX_TOKENS: ClassVar[int] = 32000
+    
+    # API Settings
+    REQUEST_TIMEOUT: ClassVar[int] = int(os.getenv('REQUEST_TIMEOUT', '60'))
+    MAX_RETRIES: ClassVar[int] = int(os.getenv('MAX_RETRIES', '3'))
+    RETRY_DELAY: ClassVar[float] = float(os.getenv('RETRY_DELAY', '1.0'))
+    
+    # Cache Settings
+    CACHE_SIZE: ClassVar[int] = int(os.getenv('CACHE_SIZE', '100'))
+    CACHE_TTL: ClassVar[int] = int(os.getenv('CACHE_TTL', '3600'))
+    ENABLE_CACHE: ClassVar[bool] = os.getenv('ENABLE_CACHE', 'true').lower() == 'true'
+    
+    # Rate Limiting
+    RATE_LIMIT_REQUESTS: ClassVar[int] = int(os.getenv('RATE_LIMIT_REQUESTS', '50'))
+    RATE_LIMIT_WINDOW: ClassVar[int] = int(os.getenv('RATE_LIMIT_WINDOW', '60'))
+    ENABLE_RATE_LIMITING: ClassVar[bool] = os.getenv('ENABLE_RATE_LIMITING', 'true').lower() == 'true'
+    
+    # File Storage
+    BASE_DIR: ClassVar[Path] = Path(__file__).parent.parent.parent
+    EXPORT_DIR: ClassVar[Path] = BASE_DIR / os.getenv('EXPORT_DIR', 'exports')
+    BACKUP_DIR: ClassVar[Path] = BASE_DIR / os.getenv('BACKUP_DIR', 'backups')
+    LOG_DIR: ClassVar[Path] = BASE_DIR / 'logs'
+    MAX_EXPORT_SIZE_MB: ClassVar[int] = 50
+    
+    # UI Theme
+    THEME_PRIMARY: ClassVar[str] = os.getenv('THEME_PRIMARY', 'purple')
+    THEME_SECONDARY: ClassVar[str] = os.getenv('THEME_SECONDARY', 'blue')
+    
+    # Analytics
+    AUTO_SAVE_INTERVAL: ClassVar[int] = 300
+    ENABLE_ANALYTICS: ClassVar[bool] = True
+    ANALYTICS_BATCH_SIZE: ClassVar[int] = 10
+    
+    # Performance
+    MAX_WORKERS: ClassVar[int] = int(os.getenv('MAX_WORKERS', '3'))
+    ENABLE_PARALLEL_PROCESSING: ClassVar[bool] = True
+    
+    # Security
+    MAX_INPUT_LENGTH: ClassVar[int] = 10000
+    ENABLE_XSS_PROTECTION: ClassVar[bool] = True
+    ALLOWED_EXPORT_FORMATS: ClassVar[list] = ['json', 'markdown', 'txt', 'pdf']
+    
+    # Feature Flags
+    ENABLE_PDF_EXPORT: ClassVar[bool] = os.getenv('ENABLE_PDF_EXPORT', 'true').lower() == 'true'
+    ENABLE_SELF_CRITIQUE: ClassVar[bool] = True
+    ENABLE_SIDEBAR_TOGGLE: ClassVar[bool] = True
+    
+    @classmethod
+    def validate(cls) -> bool:
+        """Validates all configuration parameters"""
+        # Import logger here to avoid circular import
+        from src.utils.logger import logger
+        
+        try:
+            assert cls.MIN_TEMPERATURE <= cls.DEFAULT_TEMPERATURE <= cls.MAX_TEMPERATURE
+            assert cls.MIN_TOKENS <= cls.DEFAULT_MAX_TOKENS <= cls.MAX_TOKENS
+            assert cls.MAX_HISTORY_LENGTH > 0
+            assert cls.MAX_CONVERSATION_STORAGE >= cls.MAX_HISTORY_LENGTH
+            assert cls.CACHE_SIZE > 0 and cls.CACHE_TTL > 0
+            assert cls.RATE_LIMIT_REQUESTS > 0 and cls.RATE_LIMIT_WINDOW > 0
+            assert cls.REQUEST_TIMEOUT > 0 and cls.MAX_RETRIES >= 0
+            assert 1 <= cls.MAX_WORKERS <= 10
+            assert cls.MAX_INPUT_LENGTH >= 1000
+            
+            logger.info("✅ Configuration validation passed")
+            return True
+        except AssertionError as e:
+            logger.error(f"❌ Configuration validation failed: {e}")
+            return False
+    
+    @classmethod
+    def create_directories(cls) -> None:
+        """Creates all required directories"""
+        # Import logger here to avoid circular import
+        from src.utils.logger import logger
+        
+        directories = [cls.EXPORT_DIR, cls.BACKUP_DIR, cls.LOG_DIR]
+        
+        try:
+            for directory in directories:
+                directory.mkdir(exist_ok=True, parents=True)
+                logger.debug(f"📁 Directory ready: {directory}")
+            logger.info("✅ All application directories initialized")
+        except Exception as e:
+            logger.error(f"❌ Failed to create directories: {e}")
+            raise
+
+
+# Initialize directories and validate
+AppConfig.create_directories()
+if not AppConfig.validate():
+    raise RuntimeError("❌ Configuration validation failed")

src/core/__init__.py

@@ -0,0 +1,8 @@
+"""
+Core business logic package initialization
+"""
+from .reasoner import AdvancedReasoner
+from .prompt_engine import PromptEngine
+from .conversation import ConversationManager
+
+__all__ = ['AdvancedReasoner', 'PromptEngine', 'ConversationManager']

src/core/conversation.py

@@ -0,0 +1,83 @@
+"""
+Conversation management and history handling
+"""
+import threading
+from collections import deque, defaultdict
+from typing import List, Dict, Optional
+from src.models.entry import ConversationEntry
+from src.config.settings import AppConfig
+from src.utils.logger import logger
+
+
+class ConversationManager:
+    """
+    💬 THREAD-SAFE CONVERSATION MANAGER
+    Handles conversation history with automatic size management
+    """
+    
+    def __init__(self):
+        self.conversation_history: deque = deque(maxlen=AppConfig.MAX_CONVERSATION_STORAGE)
+        self.model_usage: Dict[str, int] = defaultdict(int)
+        self.mode_usage: Dict[str, int] = defaultdict(int)
+        self._lock = threading.Lock()
+    
+    def add_conversation(self, entry: ConversationEntry) -> None:
+        """
+        ✅ ADD CONVERSATION ENTRY
+        """
+        with self._lock:
+            self.conversation_history.append(entry)
+            self.model_usage[entry.model] += 1
+            self.mode_usage[entry.reasoning_mode] += 1
+            logger.debug(f"💬 Added conversation: {entry.entry_id[:8]}...")
+    
+    def get_history(self, limit: Optional[int] = None) -> List[ConversationEntry]:
+        """
+        ✅ GET CONVERSATION HISTORY
+        """
+        with self._lock:
+            if limit:
+                return list(self.conversation_history)[-limit:]
+            return list(self.conversation_history)
+    
+    def clear_history(self) -> None:
+        """
+        🗑️ CLEAR CONVERSATION HISTORY
+        """
+        with self._lock:
+            self.conversation_history.clear()
+            self.model_usage.clear()
+            self.mode_usage.clear()
+            logger.info("🗑️ Conversation history cleared")
+    
+    def get_recent_context(self, limit: int = 10) -> List[Dict]:
+        """
+        ✅ GET RECENT CONTEXT FOR API
+        """
+        with self._lock:
+            recent = list(self.conversation_history)[-limit:]
+            
+            context = []
+            for conv in recent:
+                context.append({"role": "user", "content": conv.user_message})
+                context.append({"role": "assistant", "content": conv.assistant_response})
+            
+            logger.debug(f"📚 Retrieved {len(context)} context messages")
+            return context
+    
+    def get_statistics(self) -> Dict:
+        """
+        📊 GET CONVERSATION STATISTICS
+        """
+        with self._lock:
+            return {
+                'total_conversations': len(self.conversation_history),
+                'model_usage': dict(self.model_usage),
+                'mode_usage': dict(self.mode_usage),
+                'max_storage': AppConfig.MAX_CONVERSATION_STORAGE
+            }
+    
+    def __len__(self) -> int:
+        """Get conversation count"""
+        with self._lock:
+            return len(self.conversation_history)

src/core/prompt_engine.py

@@ -0,0 +1,227 @@
+"""
+Centralized prompt management and template system
+"""
+from typing import Dict, List, Optional
+from src.config.constants import ReasoningMode
+from src.utils.logger import logger
+
+
+class PromptEngine:
+    """
+    📝 CENTRALIZED PROMPT MANAGEMENT
+    Research-backed prompt templates for different reasoning modes
+    """
+    
+    # System prompts for each reasoning mode
+    SYSTEM_PROMPTS: Dict[ReasoningMode, str] = {
+        ReasoningMode.TREE_OF_THOUGHTS: """You are an advanced AI using Tree of Thoughts reasoning (Yao et al., 2023).
+
+**Instructions:**
+1. Generate 3 distinct reasoning paths
+2. Evaluate each path's viability
+3. Select the most promising path
+4. Expand and refine iteratively
+5. Present the best solution with reasoning trace
+
+Be systematic, thorough, and show your branching logic.""",
+
+        ReasoningMode.CHAIN_OF_THOUGHT: """You are an advanced AI using Chain of Thought reasoning (Wei et al., 2022).
+
+**Instructions:**
+1. Break down the problem into clear steps
+2. Show explicit reasoning for each step
+3. Build on previous conclusions
+4. Arrive at final answer logically
+5. Explain your thought process
+
+Be clear, sequential, and transparent in your reasoning.""",
+
+        ReasoningMode.SELF_CONSISTENCY: """You are an advanced AI using Self-Consistency sampling (Wang et al., 2022).
+
+**Instructions:**
+1. Generate 3 independent solution paths
+2. Solve the problem using different approaches
+3. Compare solutions for consistency
+4. Identify the most reliable answer
+5. Present the consensus solution
+
+Show multiple perspectives and explain why one answer is most consistent.""",
+
+        ReasoningMode.REFLEXION: """You are an advanced AI using Reflexion with self-correction (Shinn et al., 2023).
+
+**Instructions:**
+1. Provide initial solution
+2. Critique your own reasoning
+3. Identify potential errors or gaps
+4. Refine and improve solution
+5. Present corrected answer with reflection
+
+Be self-critical and show your improvement process.""",
+
+        ReasoningMode.DEBATE: """You are an advanced AI using Multi-Agent Debate (Du et al., 2023).
+
+**Instructions:**
+1. Present Perspective A with arguments
+2. Present Perspective B with counterarguments
+3. Debate key points of disagreement
+4. Synthesize the strongest arguments
+5. Conclude with balanced judgment
+
+Show multiple viewpoints and reasoned synthesis.""",
+
+        ReasoningMode.ANALOGICAL: """You are an advanced AI using Analogical Reasoning (Gentner & Forbus, 2011).
+
+**Instructions:**
+1. Identify similar problems or domains
+2. Map structural similarities
+3. Transfer solution strategies
+4. Adapt to current problem context
+5. Verify applicability
+
+Draw meaningful analogies and explain transfer logic."""
+    }
+    
+    # Pre-built templates for common tasks
+    TEMPLATES: Dict[str, str] = {
+        "Custom": "",  # User provides their own
+        
+        "Research Analysis": """Analyze the following research question or topic:
+
+{query}
+
+Provide:
+1. Current state of knowledge
+2. Key findings and evidence
+3. Gaps or limitations
+4. Future directions
+5. Practical implications""",
+
+        "Problem Solving": """Solve the following problem systematically:
+
+{query}
+
+Include:
+1. Problem understanding
+2. Constraints and requirements
+3. Solution approach
+4. Step-by-step solution
+5. Verification""",
+
+        "Code Review": """Review the following code:
+
+{query}
+
+Analyze:
+1. Code quality and readability
+2. Potential bugs or issues
+3. Performance considerations
+4. Best practice recommendations
+5. Security concerns""",
+
+        "Writing Enhancement": """Improve the following text:
+
+{query}
+
+Focus on:
+1. Clarity and coherence
+2. Grammar and style
+3. Structural improvements
+4. Audience appropriateness
+5. Enhanced version""",
+
+        "Debate Analysis": """Analyze the following argument or debate topic:
+
+{query}
+
+Provide:
+1. Key arguments for each side
+2. Evidence evaluation
+3. Logical fallacies (if any)
+4. Strongest points
+5. Balanced conclusion""",
+
+        "Learning Explanation": """Explain the following concept:
+
+{query}
+
+Include:
+1. Simple definition
+2. Core principles
+3. Examples and analogies
+4. Common misconceptions
+5. Practical applications"""
+    }
+    
+    @classmethod
+    def get_system_prompt(cls, mode: ReasoningMode) -> str:
+        """
+        ✅ GET SYSTEM PROMPT FOR REASONING MODE
+        """
+        prompt = cls.SYSTEM_PROMPTS.get(mode, cls.SYSTEM_PROMPTS[ReasoningMode.CHAIN_OF_THOUGHT])
+        logger.debug(f"📝 Retrieved system prompt for mode: {mode}")
+        return prompt
+    
+    @classmethod
+    def apply_template(cls, template_name: str, query: str) -> str:
+        """
+        ✅ APPLY PROMPT TEMPLATE
+        """
+        if template_name not in cls.TEMPLATES:
+            logger.warning(f"⚠️ Template '{template_name}' not found, using query as-is")
+            return query
+        
+        template = cls.TEMPLATES[template_name]
+        
+        if not template:  # Custom template
+            return query
+        
+        formatted = template.format(query=query)
+        logger.debug(f"📝 Applied template: {template_name}")
+        return formatted
+    
+    @classmethod
+    def build_messages(cls, 
+                      query: str, 
+                      mode: ReasoningMode,
+                      template: str = "Custom",
+                      history: Optional[List[Dict]] = None) -> List[Dict]:
+        """
+        ✅ BUILD MESSAGE ARRAY FOR API
+        """
+        messages = [
+            {"role": "system", "content": cls.get_system_prompt(mode)}
+        ]
+        
+        # Add conversation history
+        if history:
+            for msg in history[-10:]:  # Last 10 messages
+                if msg.get("role") in ["user", "assistant"]:
+                    messages.append({
+                        "role": msg["role"],
+                        "content": msg["content"]
+                    })
+        
+        # Add current query with template
+        formatted_query = cls.apply_template(template, query)
+        messages.append({"role": "user", "content": formatted_query})
+        
+        logger.debug(f"📝 Built message array with {len(messages)} messages")
+        return messages
+    
+    @classmethod
+    def get_self_critique_prompt(cls, original_response: str) -> str:
+        """
+        ✅ GENERATE SELF-CRITIQUE PROMPT
+        """
+        return f"""Review and critique the following response:
+
+{original_response}
+
+**Self-Critique Instructions:**
+1. Identify any factual errors or logical flaws
+2. Check for completeness and clarity
+3. Evaluate reasoning quality
+4. Suggest specific improvements
+5. Provide refined answer if needed
+
+Be thorough and constructive in your critique."""

src/core/reasoner.py

@@ -0,0 +1,227 @@
+"""
+Advanced reasoning engine - Main business logic
+"""
+import time
+import hashlib
+from typing import Generator, List, Dict, Optional, Any, Tuple
+from src.api.groq_client import GroqClientManager
+from src.core.prompt_engine import PromptEngine
+from src.core.conversation import ConversationManager
+from src.services.cache_service import ResponseCache
+from src.services.rate_limiter import RateLimiter
+from src.services.export_service import ConversationExporter
+from src.services.analytics_service import AnalyticsService
+from src.models.metrics import ConversationMetrics
+from src.models.entry import ConversationEntry
+from src.config.settings import AppConfig
+from src.config.constants import ReasoningMode, ModelConfig
+from src.utils.logger import logger
+from src.utils.decorators import handle_groq_errors, with_rate_limit
+from src.utils.validators import validate_input
+from src.utils.helpers import generate_session_id
+
+
+class AdvancedReasoner:
+    """
+    🧠 ADVANCED REASONING ENGINE
+    Main orchestrator for AI reasoning with caching, metrics, and export
+    """
+    
+    def __init__(self):
+        # Core components
+        self.client_manager = GroqClientManager()
+        self.conversation_manager = ConversationManager()
+        self.prompt_engine = PromptEngine()
+        
+        # Services
+        self.cache = ResponseCache(AppConfig.CACHE_SIZE, AppConfig.CACHE_TTL)
+        self.rate_limiter = RateLimiter(AppConfig.RATE_LIMIT_REQUESTS, AppConfig.RATE_LIMIT_WINDOW)
+        self.exporter = ConversationExporter()
+        self.analytics = AnalyticsService()
+        
+        # Metrics and state
+        self.metrics = ConversationMetrics()
+        self.session_id = generate_session_id()
+        
+        logger.info(f"✅ AdvancedReasoner initialized | Session: {self.session_id[:8]}...")
+    
+    def _generate_cache_key(self, query: str, model: str, mode: str, 
+                           temp: float, tokens: int) -> str:
+        """
+        🔑 GENERATE CACHE KEY
+        """
+        key_string = f"{query}|{model}|{mode}|{temp}|{tokens}"
+        return hashlib.sha256(key_string.encode()).hexdigest()
+    
+    @handle_groq_errors(max_retries=AppConfig.MAX_RETRIES, retry_delay=AppConfig.RETRY_DELAY)
+    def _call_groq_api(self, messages: List[Dict], model: str, 
+                       temperature: float, max_tokens: int) -> Generator[str, None, None]:
+        """
+        🔌 CALL GROQ API WITH STREAMING
+        """
+        if AppConfig.ENABLE_RATE_LIMITING:
+            self.rate_limiter.acquire()
+        
+        client = self.client_manager.client
+        
+        stream = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True
+        )
+        
+        for chunk in stream:
+            if chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+    
+    def generate_response(
+        self,
+        query: str,
+        history: List[Dict],
+        model: str,
+        reasoning_mode: ReasoningMode,
+        enable_critique: bool = True,
+        temperature: float = 0.7,
+        max_tokens: int = 4000,
+        template: str = "Custom",
+        use_cache: bool = True
+    ) -> Generator[str, None, None]:
+        """
+        🧠 GENERATE RESPONSE WITH STREAMING
+        """
+        # Validate input
+        is_valid, error_msg = validate_input(query, AppConfig.MAX_INPUT_LENGTH)
+        if not is_valid:
+            yield f"❌ **Input Error:** {error_msg}"
+            return
+        
+        start_time = time.time()
+        
+        # Check cache
+        cache_key = self._generate_cache_key(query, model, reasoning_mode.value, temperature, max_tokens)
+        
+        if use_cache and AppConfig.ENABLE_CACHE:
+            cached = self.cache.get(cache_key)
+            if cached:
+                self.metrics.update_cache_stats(hit=True)
+                logger.info("✅ Cache hit - returning cached response")
+                yield cached
+                return
+        
+        self.metrics.update_cache_stats(hit=False)
+        
+        # Build messages
+        messages = self.prompt_engine.build_messages(query, reasoning_mode, template, history)
+        
+        # Stream response
+        full_response = ""
+        try:
+            for chunk in self._call_groq_api(messages, model, temperature, max_tokens):
+                full_response += chunk
+                yield full_response
+            
+            # Self-critique if enabled
+            if enable_critique and AppConfig.ENABLE_SELF_CRITIQUE:
+                critique_prompt = self.prompt_engine.get_self_critique_prompt(full_response)
+                critique_messages = [
+                    {"role": "system", "content": "You are a critical reviewer."},
+                    {"role": "user", "content": critique_prompt}
+                ]
+                
+                critique_response = ""
+                for chunk in self._call_groq_api(critique_messages, model, temperature, max_tokens // 2):
+                    critique_response += chunk
+                
+                full_response += f"\n\n---\n\n### 🔍 Self-Critique\n{critique_response}"
+                yield full_response
+            
+            # Cache response
+            if use_cache and AppConfig.ENABLE_CACHE:
+                self.cache.set(cache_key, full_response)
+            
+            # Update metrics
+            elapsed_time = time.time() - start_time
+            tokens_estimate = len(full_response.split())
+            
+            self.metrics.update(
+                tokens=tokens_estimate,
+                time_taken=elapsed_time,
+                depth=1,
+                corrections=1 if enable_critique else 0,
+                confidence=95.0
+            )
+            
+            # Save conversation
+            entry = ConversationEntry(
+                user_message=query,
+                assistant_response=full_response,
+                model=model,
+                reasoning_mode=reasoning_mode.value,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                tokens_used=tokens_estimate,
+                inference_time=elapsed_time,
+                critique_enabled=enable_critique,
+                cache_hit=False
+            )
+            
+            self.conversation_manager.add_conversation(entry)
+            
+            logger.info(f"✅ Response generated in {elapsed_time:.2f}s | Tokens: {tokens_estimate}")
+            
+        except Exception as e:
+            self.metrics.increment_errors()
+            error_msg = f"❌ **Error:** {str(e)}"
+            logger.error(f"Response generation error: {e}", exc_info=True)
+            yield error_msg
+    
+    # Convenience properties
+    @property
+    def conversation_history(self) -> List[ConversationEntry]:
+        """Get conversation history"""
+        return self.conversation_manager.get_history()
+    
+    @property
+    def model_usage(self) -> Dict[str, int]:
+        """Get model usage statistics"""
+        return dict(self.conversation_manager.model_usage)
+    
+    @property
+    def mode_usage(self) -> Dict[str, int]:
+        """Get mode usage statistics"""
+        return dict(self.conversation_manager.mode_usage)
+    
+    def clear_history(self) -> None:
+        """Clear conversation history"""
+        self.conversation_manager.clear_history()
+    
+    def export_conversation(self, format_type: str, include_metadata: bool = True) -> Tuple[str, Optional[str]]:
+        """
+        Export conversations
+        Returns (content, filepath_string) for Gradio compatibility
+        """
+        return self.exporter.export(self.conversation_history, format_type, include_metadata)
+    
+    def export_current_chat_pdf(self) -> Optional[str]:
+        """
+        Export current chat as PDF
+        Returns string path for Gradio compatibility
+        """
+        return self.exporter.export_to_pdf(self.conversation_history, include_metadata=True)
+    
+    def search_conversations(self, keyword: str) -> List[tuple]:
+        """Search conversations"""
+        return self.analytics.search_conversations(self.conversation_history, keyword)
+    
+    def get_analytics(self) -> Dict[str, Any]:
+        """Get analytics"""
+        return self.analytics.generate_analytics(
+            self.conversation_history,
+            self.metrics,
+            self.session_id,
+            self.model_usage,
+            self.mode_usage,
+            self.cache.get_stats()
+        )

src/models/__init__.py

@@ -0,0 +1,8 @@
+"""
+Data models package initialization
+"""
+from .metrics import ConversationMetrics
+from .entry import ConversationEntry
+from .config_models import ReasoningMode, ModelConfig
+
+__all__ = ['ConversationMetrics', 'ConversationEntry', 'ReasoningMode', 'ModelConfig']

src/models/config_models.py

@@ -0,0 +1,6 @@
+"""
+Configuration models (re-exported from config.constants for convenience)
+"""
+from src.config.constants import ReasoningMode, ModelConfig
+
+__all__ = ['ReasoningMode', 'ModelConfig']

src/models/entry.py

@@ -0,0 +1,37 @@
+"""
+Conversation entry data model
+"""
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+import uuid
+from typing import Optional
+from src.utils.helpers import format_timestamp
+
+
+@dataclass
+class ConversationEntry:
+    """
+    💬 ENHANCED CONVERSATION ENTRY WITH METADATA
+    """
+    user_message: str
+    assistant_response: str
+    model: str
+    reasoning_mode: str
+    timestamp: str = field(default_factory=lambda: format_timestamp())
+    entry_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    temperature: float = 0.7
+    max_tokens: int = 4000
+    tokens_used: int = 0
+    inference_time: float = 0.0
+    reasoning_depth: int = 1
+    confidence_score: float = 100.0
+    critique_enabled: bool = False
+    cache_hit: bool = False
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return asdict(self)
+    
+    def __str__(self) -> str:
+        return (f"ConversationEntry(id={self.entry_id[:8]}, "
+                f"model={self.model}, mode={self.reasoning_mode})")

src/models/metrics.py

@@ -0,0 +1,82 @@
+"""
+Conversation metrics data model
+"""
+from dataclasses import dataclass, field
+from datetime import datetime
+import threading
+from typing import Dict
+from src.utils.helpers import format_timestamp
+
+
+@dataclass
+class ConversationMetrics:
+    """
+    📊 ENHANCED THREAD-SAFE CONVERSATION METRICS
+    """
+    total_conversations: int = 0
+    tokens_used: int = 0
+    inference_time: float = 0.0
+    reasoning_depth: int = 0
+    self_corrections: int = 0
+    confidence_score: float = 0.0
+    session_start: str = field(default_factory=lambda: format_timestamp())
+    peak_tokens: int = 0
+    avg_response_time: float = 0.0
+    tokens_per_second: float = 0.0
+    error_count: int = 0
+    cache_hits: int = 0
+    cache_misses: int = 0
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+    
+    def update(self, tokens: int, time_taken: float, depth: int = 1, 
+               corrections: int = 0, confidence: float = 100.0) -> None:
+        """
+        ✅ THREAD-SAFE METRIC UPDATE
+        """
+        with self._lock:
+            self.total_conversations += 1
+            self.tokens_used += tokens
+            self.inference_time = time_taken
+            self.reasoning_depth = depth
+            self.self_corrections = corrections
+            self.confidence_score = confidence
+            
+            if tokens > self.peak_tokens:
+                self.peak_tokens = tokens
+            
+            if self.total_conversations > 0:
+                total_time = self.inference_time * self.total_conversations
+                self.avg_response_time = total_time / self.total_conversations
+                
+                if self.avg_response_time > 0:
+                    self.tokens_per_second = self.tokens_used / (self.avg_response_time * self.total_conversations)
+    
+    def increment_errors(self) -> None:
+        """Increment error count"""
+        with self._lock:
+            self.error_count += 1
+    
+    def update_cache_stats(self, hit: bool) -> None:
+        """Update cache statistics"""
+        with self._lock:
+            if hit:
+                self.cache_hits += 1
+            else:
+                self.cache_misses += 1
+    
+    def reset(self) -> None:
+        """Reset all metrics"""
+        with self._lock:
+            self.total_conversations = 0
+            self.tokens_used = 0
+            self.inference_time = 0.0
+            self.reasoning_depth = 0
+            self.self_corrections = 0
+            self.confidence_score = 0.0
+            self.peak_tokens = 0
+            self.avg_response_time = 0.0
+            self.tokens_per_second = 0.0
+            self.error_count = 0
+            self.cache_hits = 0
+            self.cache_misses = 0
+            self.session_start = format_timestamp()

src/services/__init__.py

@@ -0,0 +1,9 @@
+"""
+Services package initialization
+"""
+from .cache_service import ResponseCache
+from .rate_limiter import RateLimiter
+from .export_service import ConversationExporter
+from .analytics_service import AnalyticsService
+
+__all__ = ['ResponseCache', 'RateLimiter', 'ConversationExporter', 'AnalyticsService']

src/services/analytics_service.py

@@ -0,0 +1,80 @@
+"""
+Analytics and insights generation service
+"""
+from typing import List, Dict, Any
+from collections import Counter
+from src.models.entry import ConversationEntry
+from src.models.metrics import ConversationMetrics
+from src.utils.logger import logger
+
+
+class AnalyticsService:
+    """
+    📊 ANALYTICS AND INSIGHTS GENERATOR
+    """
+    
+    @staticmethod
+    def generate_analytics(conversations: List[ConversationEntry],
+                          metrics: ConversationMetrics,
+                          session_id: str,
+                          model_usage: Dict[str, int],
+                          mode_usage: Dict[str, int],
+                          cache_stats: dict) -> Dict[str, Any]:
+        """
+        📊 GENERATE COMPREHENSIVE ANALYTICS
+        """
+        if not conversations:
+            return {}
+        
+        # Model distribution
+        most_used_model = max(model_usage.items(), key=lambda x: x[1])[0] if model_usage else "N/A"
+        
+        # Reasoning mode distribution
+        most_used_mode = max(mode_usage.items(), key=lambda x: x[1])[0] if mode_usage else "N/A"
+        
+        # Token statistics
+        total_tokens = sum(conv.tokens_used for conv in conversations)
+        avg_tokens = total_tokens / len(conversations) if conversations else 0
+        
+        # Time statistics
+        total_time = sum(conv.inference_time for conv in conversations)
+        avg_time = total_time / len(conversations) if conversations else 0
+        
+        analytics = {
+            'session_id': session_id,
+            'total_conversations': len(conversations),
+            'total_tokens': total_tokens,
+            'avg_tokens_per_conversation': avg_tokens,
+            'total_time': total_time,
+            'avg_inference_time': avg_time,
+            'peak_tokens': metrics.peak_tokens,
+            'most_used_model': most_used_model,
+            'most_used_mode': most_used_mode,
+            'model_distribution': dict(model_usage),
+            'mode_distribution': dict(mode_usage),
+            'cache_hits': cache_stats.get('hits', 0),
+            'cache_misses': cache_stats.get('misses', 0),
+            'cache_hit_rate': cache_stats.get('hit_rate', '0.0'),
+            'error_count': metrics.error_count,
+            'avg_confidence': sum(conv.confidence_score for conv in conversations) / len(conversations) if conversations else 0
+        }
+        
+        logger.debug(f"📊 Analytics generated for {len(conversations)} conversations")
+        return analytics
+    
+    @staticmethod
+    def search_conversations(conversations: List[ConversationEntry], 
+                           keyword: str) -> List[tuple]:
+        """
+        🔍 SEARCH CONVERSATIONS BY KEYWORD
+        """
+        keyword_lower = keyword.lower()
+        results = []
+        
+        for idx, conv in enumerate(conversations):
+            if (keyword_lower in conv.user_message.lower() or 
+                keyword_lower in conv.assistant_response.lower()):
+                results.append((idx, conv))
+        
+        logger.info(f"🔍 Found {len(results)} results for '{keyword}'")
+        return results

src/services/cache_service.py

@@ -0,0 +1,88 @@
+"""
+Response caching service with LRU and TTL
+"""
+import time
+import threading
+from typing import Dict, Tuple, Optional, Any
+from src.utils.logger import logger
+
+
+class ResponseCache:
+    """
+    💾 THREAD-SAFE LRU CACHE WITH TTL
+    """
+    def __init__(self, maxsize: int = 100, ttl: int = 3600):
+        self.cache: Dict[str, Tuple[Any, float]] = {}
+        self.maxsize = maxsize
+        self.ttl = ttl
+        self.lock = threading.Lock()
+        self.hits = 0
+        self.misses = 0
+    
+    def get(self, key: str) -> Optional[Any]:
+        """
+        ✅ GET CACHED VALUE WITH TTL CHECK
+        """
+        with self.lock:
+            if key not in self.cache:
+                self.misses += 1
+                return None
+            
+            value, timestamp = self.cache[key]
+            
+            # Check if expired
+            if time.time() - timestamp > self.ttl:
+                del self.cache[key]
+                self.misses += 1
+                logger.debug(f"🕐 Cache expired for key: {key[:20]}...")
+                return None
+            
+            self.hits += 1
+            logger.debug(f"✅ Cache hit for key: {key[:20]}...")
+            return value
+    
+    def set(self, key: str, value: Any) -> None:
+        """
+        ✅ SET CACHE VALUE WITH LRU EVICTION
+        """
+        with self.lock:
+            # Evict oldest if at capacity
+            if len(self.cache) >= self.maxsize and key not in self.cache:
+                oldest_key = min(self.cache.keys(), key=lambda k: self.cache[k][1])
+                del self.cache[oldest_key]
+                logger.debug(f"🗑️ Evicted cache entry: {oldest_key[:20]}...")
+            
+            self.cache[key] = (value, time.time())
+            logger.debug(f"💾 Cached response for key: {key[:20]}...")
+    
+    def clear(self) -> None:
+        """
+        🗑️ CLEAR ALL CACHE ENTRIES
+        """
+        with self.lock:
+            self.cache.clear()
+            self.hits = 0
+            self.misses = 0
+            logger.info("🗑️ Cache cleared")
+    
+    def get_stats(self) -> dict:
+        """
+        📊 GET CACHE STATISTICS
+        """
+        with self.lock:
+            total_requests = self.hits + self.misses
+            hit_rate = (self.hits / total_requests * 100) if total_requests > 0 else 0
+            
+            return {
+                'size': len(self.cache),
+                'maxsize': self.maxsize,
+                'hits': self.hits,
+                'misses': self.misses,
+                'hit_rate': f"{hit_rate:.1f}",
+                'ttl': self.ttl
+            }
+    
+    def __len__(self) -> int:
+        """Get current cache size"""
+        with self.lock:
+            return len(self.cache)

src/services/export_service.py

@@ -0,0 +1,254 @@
+"""
+Conversation export service supporting multiple formats
+"""
+import json
+from pathlib import Path
+from datetime import datetime
+from typing import List, Tuple, Optional, Union
+from src.models.entry import ConversationEntry
+from src.config.settings import AppConfig
+from src.utils.logger import logger
+from src.utils.helpers import sanitize_filename
+
+
+class ConversationExporter:
+    """
+    📤 MULTI-FORMAT CONVERSATION EXPORTER
+    """
+    
+    def __init__(self):
+        self.export_dir = AppConfig.EXPORT_DIR
+        self.backup_dir = AppConfig.BACKUP_DIR
+        self.export_dir.mkdir(exist_ok=True, parents=True)
+        self.backup_dir.mkdir(exist_ok=True, parents=True)
+    
+    def export_to_json(self, conversations: List[ConversationEntry], 
+                       include_metadata: bool = True) -> str:
+        """
+        📄 EXPORT TO JSON
+        """
+        if include_metadata:
+            data = [conv.to_dict() for conv in conversations]
+        else:
+            data = [
+                {
+                    'user': conv.user_message,
+                    'assistant': conv.assistant_response,
+                    'timestamp': conv.timestamp
+                }
+                for conv in conversations
+            ]
+        
+        return json.dumps(data, indent=2, ensure_ascii=False)
+    
+    def export_to_markdown(self, conversations: List[ConversationEntry],
+                          include_metadata: bool = True) -> str:
+        """
+        📝 EXPORT TO MARKDOWN
+        """
+        lines = [
+            "# Conversation Export",
+            f"\n**Export Date:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            f"**Total Conversations:** {len(conversations)}\n",
+            "---\n"
+        ]
+        
+        for idx, conv in enumerate(conversations, 1):
+            lines.append(f"## Conversation {idx}\n")
+            
+            if include_metadata:
+                lines.append(f"**Timestamp:** {conv.timestamp}  ")
+                lines.append(f"**Model:** {conv.model}  ")
+                lines.append(f"**Reasoning Mode:** {conv.reasoning_mode}  ")
+                lines.append(f"**Tokens Used:** {conv.tokens_used}  ")
+                lines.append(f"**Inference Time:** {conv.inference_time:.2f}s\n")
+            
+            lines.append(f"**👤 User:**\n{conv.user_message}\n")
+            lines.append(f"**🤖 Assistant:**\n{conv.assistant_response}\n")
+            lines.append("---\n")
+        
+        return "\n".join(lines)
+    
+    def export_to_txt(self, conversations: List[ConversationEntry],
+                     include_metadata: bool = True) -> str:
+        """
+        📄 EXPORT TO PLAIN TEXT
+        """
+        lines = [
+            "=" * 80,
+            "CONVERSATION EXPORT",
+            f"Export Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            f"Total Conversations: {len(conversations)}",
+            "=" * 80,
+            ""
+        ]
+        
+        for idx, conv in enumerate(conversations, 1):
+            lines.append(f"\n{'=' * 80}")
+            lines.append(f"CONVERSATION {idx}")
+            lines.append(f"{'=' * 80}")
+            
+            if include_metadata:
+                lines.append(f"Timestamp: {conv.timestamp}")
+                lines.append(f"Model: {conv.model}")
+                lines.append(f"Reasoning Mode: {conv.reasoning_mode}")
+                lines.append(f"Tokens Used: {conv.tokens_used}")
+                lines.append(f"Inference Time: {conv.inference_time:.2f}s")
+                lines.append("")
+            
+            lines.append(f"USER:\n{conv.user_message}\n")
+            lines.append(f"ASSISTANT:\n{conv.assistant_response}\n")
+        
+        return "\n".join(lines)
+    
+    def export_to_pdf(self, conversations: List[ConversationEntry],
+                     include_metadata: bool = True) -> Optional[str]:
+        """
+        📄 EXPORT TO PDF (Premium Feature)
+        Returns string path for Gradio compatibility
+        """
+        if not AppConfig.ENABLE_PDF_EXPORT:
+            logger.warning("⚠️ PDF export is disabled")
+            return None
+        
+        try:
+            from reportlab.lib.pagesizes import letter
+            from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+            from reportlab.lib.units import inch
+            from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
+            from reportlab.lib.enums import TA_LEFT, TA_CENTER
+        except ImportError:
+            logger.error("❌ reportlab not installed. Install with: pip install reportlab")
+            return None
+        
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+        filename = self.export_dir / f"conversation_export_{timestamp}.pdf"
+        
+        doc = SimpleDocTemplate(str(filename), pagesize=letter)
+        styles = getSampleStyleSheet()
+        
+        # Custom styles
+        title_style = ParagraphStyle(
+            'CustomTitle',
+            parent=styles['Heading1'],
+            fontSize=24,
+            textColor='#667eea',
+            alignment=TA_CENTER,
+            spaceAfter=30
+        )
+        
+        story = []
+        
+        # Title
+        story.append(Paragraph("Conversation Export", title_style))
+        story.append(Paragraph(
+            f"<b>Export Date:</b> {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            styles['Normal']
+        ))
+        story.append(Paragraph(
+            f"<b>Total Conversations:</b> {len(conversations)}",
+            styles['Normal']
+        ))
+        story.append(Spacer(1, 0.3*inch))
+        
+        # Conversations
+        for idx, conv in enumerate(conversations, 1):
+            story.append(Paragraph(f"<b>Conversation {idx}</b>", styles['Heading2']))
+            
+            if include_metadata:
+                meta_text = (
+                    f"<b>Timestamp:</b> {conv.timestamp} | "
+                    f"<b>Model:</b> {conv.model} | "
+                    f"<b>Mode:</b> {conv.reasoning_mode}<br/>"
+                    f"<b>Tokens:</b> {conv.tokens_used} | "
+                    f"<b>Time:</b> {conv.inference_time:.2f}s"
+                )
+                story.append(Paragraph(meta_text, styles['Normal']))
+                story.append(Spacer(1, 0.1*inch))
+            
+            story.append(Paragraph("<b>👤 User:</b>", styles['Heading3']))
+            story.append(Paragraph(conv.user_message.replace('\n', '<br/>'), styles['Normal']))
+            story.append(Spacer(1, 0.1*inch))
+            
+            story.append(Paragraph("<b>🤖 Assistant:</b>", styles['Heading3']))
+            story.append(Paragraph(conv.assistant_response.replace('\n', '<br/>'), styles['Normal']))
+            
+            if idx < len(conversations):
+                story.append(PageBreak())
+        
+        doc.build(story)
+        logger.info(f"✅ PDF exported: {filename}")
+        
+        # Return string path for Gradio compatibility
+        return str(filename)
+    
+    def export(self, conversations: List[ConversationEntry], 
+               format_type: str, include_metadata: bool = True) -> Tuple[str, Optional[str]]:
+        """
+        📤 UNIFIED EXPORT METHOD
+        Returns (content, filepath_string) for Gradio compatibility
+        """
+        if not conversations:
+            return "⚠️ No conversations to export.", None
+        
+        try:
+            if format_type == "json":
+                content = self.export_to_json(conversations, include_metadata)
+                filename = self._save_to_file(content, "json")
+                return content, str(filename)  # Convert to string
+            
+            elif format_type == "markdown":
+                content = self.export_to_markdown(conversations, include_metadata)
+                filename = self._save_to_file(content, "md")
+                return content, str(filename)  # Convert to string
+            
+            elif format_type == "txt":
+                content = self.export_to_txt(conversations, include_metadata)
+                filename = self._save_to_file(content, "txt")
+                return content, str(filename)  # Convert to string
+            
+            elif format_type == "pdf":
+                filename = self.export_to_pdf(conversations, include_metadata)
+                if filename:
+                    return f"✅ PDF exported successfully: {Path(filename).name}", filename
+                return "❌ PDF export failed", None
+            
+            else:
+                return f"❌ Unsupported format: {format_type}", None
+        
+        except Exception as e:
+            logger.error(f"❌ Export error: {e}", exc_info=True)
+            return f"❌ Export failed: {str(e)}", None
+    
+    def _save_to_file(self, content: str, extension: str) -> Path:
+        """
+        💾 SAVE CONTENT TO FILE
+        """
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+        filename = self.export_dir / f"conversation_export_{timestamp}.{extension}"
+        
+        filename.write_text(content, encoding='utf-8')
+        logger.info(f"✅ File saved: {filename}")
+        return filename
+    
+    def create_backup(self, conversations: List[ConversationEntry]) -> Optional[str]:
+        """
+        💾 CREATE AUTOMATIC BACKUP
+        Returns string path for Gradio compatibility
+        """
+        if not conversations:
+            return None
+        
+        try:
+            timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+            filename = self.backup_dir / f"backup_{timestamp}.json"
+            
+            content = self.export_to_json(conversations, include_metadata=True)
+            filename.write_text(content, encoding='utf-8')
+            
+            logger.info(f"✅ Backup created: {filename}")
+            return str(filename)  # Convert to string
+        
+        except Exception as e:
+            logger.error(f"❌ Backup failed: {e}")
+            return None

src/services/rate_limiter.py

@@ -0,0 +1,72 @@
+"""
+Token bucket rate limiting service
+"""
+import time
+import threading
+from collections import deque
+from src.utils.logger import logger
+
+
+class RateLimiter:
+    """
+    ⏱️ TOKEN BUCKET RATE LIMITER
+    """
+    def __init__(self, max_requests: int = 50, window_seconds: int = 60):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests = deque()
+        self.lock = threading.Lock()
+    
+    def acquire(self) -> bool:
+        """
+        ✅ ACQUIRE RATE LIMIT TOKEN
+        Returns True if request is allowed, False otherwise
+        """
+        with self.lock:
+            current_time = time.time()
+            
+            # Remove expired requests
+            while self.requests and current_time - self.requests[0] > self.window_seconds:
+                self.requests.popleft()
+            
+            # Check if under limit
+            if len(self.requests) < self.max_requests:
+                self.requests.append(current_time)
+                logger.debug(f"✅ Rate limit check passed ({len(self.requests)}/{self.max_requests})")
+                return True
+            
+            # Calculate wait time
+            wait_time = self.window_seconds - (current_time - self.requests[0])
+            logger.warning(f"⏳ Rate limit exceeded. Wait {wait_time:.1f}s")
+            
+            # Wait and retry
+            time.sleep(wait_time + 0.1)
+            self.requests.popleft()
+            self.requests.append(time.time())
+            return True
+    
+    def get_stats(self) -> dict:
+        """
+        📊 GET RATE LIMITER STATISTICS
+        """
+        with self.lock:
+            current_time = time.time()
+            
+            # Remove expired
+            while self.requests and current_time - self.requests[0] > self.window_seconds:
+                self.requests.popleft()
+            
+            return {
+                'current_requests': len(self.requests),
+                'max_requests': self.max_requests,
+                'window_seconds': self.window_seconds,
+                'remaining': self.max_requests - len(self.requests)
+            }
+    
+    def reset(self) -> None:
+        """
+        🔄 RESET RATE LIMITER
+        """
+        with self.lock:
+            self.requests.clear()
+            logger.info("🔄 Rate limiter reset")

src/ui/__init__.py

@@ -0,0 +1,9 @@
+"""
+User interface package initialization
+"""
+from .app import create_ui
+from .components import UIComponents
+from .handlers import EventHandlers
+from .styles import CUSTOM_CSS, SIDEBAR_CSS
+
+__all__ = ['create_ui', 'UIComponents', 'EventHandlers', 'CUSTOM_CSS', 'SIDEBAR_CSS']

src/ui/app.py

@@ -0,0 +1,273 @@
+"""
+Main Gradio application interface
+"""
+import gradio as gr
+from src.core.reasoner import AdvancedReasoner
+from src.core.prompt_engine import PromptEngine
+from src.config.settings import AppConfig
+from src.config.constants import ReasoningMode, ModelConfig
+from src.ui.components import UIComponents
+from src.ui.handlers import EventHandlers
+from src.ui.styles import SIDEBAR_CSS
+from src.utils.logger import logger
+
+
+def create_ui() -> gr.Blocks:
+    """
+    🎨 CREATE ENHANCED GRADIO INTERFACE
+    """
+    
+    # Initialize reasoner and components
+    reasoner = AdvancedReasoner()
+    components = UIComponents()
+    handlers = EventHandlers(reasoner)
+    
+    with gr.Blocks(
+        theme=gr.themes.Soft(
+            primary_hue=AppConfig.THEME_PRIMARY,
+            secondary_hue=AppConfig.THEME_SECONDARY,
+            font=gr.themes.GoogleFont("Inter")
+        ),
+        css=SIDEBAR_CSS,
+        title="Advanced AI Reasoning System Pro"
+    ) as demo:
+        
+        # Header
+        gr.HTML(components.get_header_html())
+        
+        # Main Tabs
+        with gr.Tabs():
+            
+            # ==================== TAB 1: REASONING WORKSPACE ====================
+            with gr.Tab("🧠 Reasoning Workspace"):
+                with gr.Row():
+                    
+                    # Main Chat Area
+                    with gr.Column(scale=4):
+                        chatbot = gr.Chatbot(
+                            label="💬 Reasoning Workspace",
+                            height=750,
+                            show_copy_button=True,
+                            type="messages",
+                            avatar_images=(
+                                "https://api.dicebear.com/7.x/avataaars/svg?seed=User",
+                                "https://api.dicebear.com/7.x/bottts/svg?seed=AI"
+                            ),
+                            bubble_full_width=False
+                        )
+                        
+                        msg = gr.Textbox(
+                            placeholder="💭 Enter your complex problem or research question... (Max 10,000 characters)",
+                            label="Query Input",
+                            lines=3,
+                            max_lines=10,
+                            show_label=False
+                        )
+                        
+                        with gr.Row():
+                            submit_btn = gr.Button("🚀 Process", variant="primary", scale=2, size="lg")
+                            clear_btn = gr.Button("🗑️ Clear", scale=1, size="lg")
+                            pdf_btn = gr.Button("📄 Download PDF", scale=1, size="lg", variant="secondary")
+                            toggle_sidebar_btn = gr.Button("⚙️ Settings", scale=1, size="lg", variant="secondary")
+                    
+                    # Collapsible Sidebar
+                    with gr.Column(scale=1, visible=True, elem_classes="settings-column") as sidebar:
+                        gr.Markdown("### ⚙️ Configuration")
+                        
+                        reasoning_mode = gr.Radio(
+                            choices=components.get_reasoning_mode_choices(),
+                            value=ReasoningMode.TREE_OF_THOUGHTS.value,
+                            label="🧠 Reasoning Method",
+                            info="Select your preferred reasoning strategy"
+                        )
+                        
+                        prompt_template = gr.Dropdown(
+                            choices=components.get_prompt_template_choices(),
+                            value="Custom",
+                            label="📝 Prompt Template",
+                            info="Pre-built prompt templates for common tasks"
+                        )
+                        
+                        enable_critique = gr.Checkbox(
+                            label="🔍 Enable Self-Critique",
+                            value=True,
+                            info="Add automatic validation and correction phase"
+                        )
+                        
+                        use_cache = gr.Checkbox(
+                            label="💾 Use Response Cache",
+                            value=True,
+                            info="Cache responses for faster repeated queries"
+                        )
+                        
+                        model = gr.Dropdown(
+                            choices=components.get_model_choices(),
+                            value=ModelConfig.LLAMA_70B.model_id,
+                            label="🤖 AI Model",
+                            info="Select the AI model to use"
+                        )
+                        
+                        with gr.Accordion("🎛️ Advanced Settings", open=False):
+                            temperature = gr.Slider(
+                                AppConfig.MIN_TEMPERATURE, 
+                                AppConfig.MAX_TEMPERATURE, 
+                                value=AppConfig.DEFAULT_TEMPERATURE, 
+                                step=0.1,
+                                label="🌡️ Temperature",
+                                info="Higher = more creative, Lower = more focused"
+                            )
+                            
+                            max_tokens = gr.Slider(
+                                AppConfig.MIN_TOKENS, 
+                                8000, 
+                                value=AppConfig.DEFAULT_MAX_TOKENS, 
+                                step=500,
+                                label="📊 Max Tokens",
+                                info="Maximum response length"
+                            )
+                        
+                        gr.Markdown("### 📊 Live Metrics")
+                        metrics_display = gr.Markdown(value=components.get_metrics_html(reasoner))
+                        
+                        with gr.Accordion("ℹ️ System Info", open=False):
+                            gr.Markdown(components.get_system_info_html(reasoner))
+                
+                # PDF download output
+                pdf_file_output = gr.File(
+                    label="📥 Download Your PDF Report", 
+                    visible=True,
+                    file_types=[".pdf"]
+                )
+            
+            # ==================== TAB 2: EXPORT & HISTORY ====================
+            with gr.Tab("📤 Export & History"):
+                gr.Markdown("### 📤 Export Conversation History")
+                gr.Markdown("Export your conversations in multiple formats with optional metadata.")
+                
+                with gr.Row():
+                    export_format = gr.Radio(
+                        choices=["json", "markdown", "txt", "pdf"],
+                        value="markdown",
+                        label="📄 Export Format",
+                        info="Choose your preferred export format"
+                    )
+                    include_meta = gr.Checkbox(
+                        label="📋 Include Metadata",
+                        value=True,
+                        info="Include timestamps, models, and performance metrics"
+                    )
+                
+                export_btn = gr.Button("📥 Export Now", variant="primary", size="lg")
+                export_output = gr.Code(label="Exported Data Preview", language="markdown", lines=20)
+                download_file = gr.File(
+                    label="📥 Download Export File",
+                    file_types=[".json", ".md", ".txt", ".pdf"]
+                )
+                
+                gr.Markdown("---")
+                gr.Markdown("### 🔍 Search Conversations")
+                gr.Markdown("Search through your conversation history by keywords.")
+                
+                with gr.Row():
+                    search_input = gr.Textbox(
+                        placeholder="🔎 Enter keyword to search...", 
+                        scale=3,
+                        label="Search Query",
+                        show_label=False
+                    )
+                    search_btn = gr.Button("🔍 Search", scale=1, size="lg")
+                
+                search_results = gr.Markdown("💡 **Tip:** Enter a keyword and click Search to find relevant conversations.")
+                
+                gr.Markdown("---")
+                gr.Markdown("### 📚 Conversation History")
+                history_stats = gr.Markdown("Loading statistics...")
+            
+            # ==================== TAB 3: ANALYTICS & INSIGHTS ====================
+            with gr.Tab("📊 Analytics & Insights"):
+                gr.Markdown("### 📊 Performance Analytics Dashboard")
+                refresh_btn = gr.Button("🔄 Refresh Analytics", variant="primary", size="lg")
+                
+                with gr.Row():
+                    with gr.Column():
+                        gr.Markdown("#### 📈 Performance Metrics")
+                        analytics_display = gr.Markdown(components.get_empty_analytics_html())
+                    
+                    with gr.Column():
+                        gr.Markdown("#### 💾 Cache Statistics")
+                        cache_display = gr.Markdown("No cache data available yet. Start a conversation to see cache performance.")
+                
+                gr.Markdown("---")
+                gr.Markdown("### 📊 Usage Distribution")
+                
+                with gr.Row():
+                    with gr.Column():
+                        gr.Markdown("#### 🤖 Model Usage")
+                        model_dist = gr.Markdown("**No data yet.** Models will be tracked as you use them.")
+                    
+                    with gr.Column():
+                        gr.Markdown("#### 🧠 Reasoning Mode Usage")
+                        mode_dist = gr.Markdown("**No data yet.** Reasoning modes will be tracked as you use them.")
+            
+            # ==================== TAB 4: SETTINGS ====================
+            with gr.Tab("⚙️ Settings"):
+                gr.Markdown("### ⚙️ Application Settings")
+                gr.Markdown("Current configuration and system controls.")
+                
+                gr.Markdown(components.get_settings_table_html())
+                
+                gr.Markdown("---")
+                gr.Markdown("### 🛠️ System Actions")
+                
+                with gr.Row():
+                    clear_cache_btn = gr.Button("🗑️ Clear Cache", variant="stop", size="lg")
+                    reset_metrics_btn = gr.Button("🔄 Reset Metrics", variant="secondary", size="lg")
+                
+                cache_status = gr.Markdown("")
+        
+        # ==================== EVENT HANDLERS ====================
+        
+        # State management
+        sidebar_visible_state = gr.State(value=True)
+        
+        # Message submission
+        submit_btn.click(
+            handlers.process_message,
+            [msg, chatbot, reasoning_mode, enable_critique, model, 
+             temperature, max_tokens, prompt_template, use_cache],
+            [chatbot, metrics_display]
+        ).then(lambda: "", None, msg)
+        
+        msg.submit(
+            handlers.process_message,
+            [msg, chatbot, reasoning_mode, enable_critique, model, 
+             temperature, max_tokens, prompt_template, use_cache],
+            [chatbot, metrics_display]
+        ).then(lambda: "", None, msg)
+        
+        # Chat controls
+        clear_btn.click(handlers.reset_chat, None, [chatbot, metrics_display])
+        pdf_btn.click(handlers.download_chat_pdf, None, pdf_file_output)
+        
+        # Sidebar toggle
+        toggle_sidebar_btn.click(
+            handlers.toggle_sidebar,
+            inputs=[sidebar_visible_state],
+            outputs=[sidebar, sidebar_visible_state]
+        )
+        
+        # Export & Search
+        export_btn.click(handlers.export_conversation, [export_format, include_meta], [export_output, download_file])
+        search_btn.click(handlers.search_conversations, search_input, search_results)
+        
+        # Analytics
+        refresh_btn.click(handlers.refresh_analytics, None, [analytics_display, cache_display, model_dist, mode_dist])
+        
+        # Settings actions
+        clear_cache_btn.click(handlers.clear_cache_action, None, cache_status)
+        reset_metrics_btn.click(handlers.reset_metrics_action, None, cache_status)
+        
+        # Load history stats on page load
+        demo.load(handlers.update_history_stats, None, history_stats)
+    
+    return demo

src/ui/components.py

@@ -0,0 +1,127 @@
+"""
+Reusable UI components
+"""
+from src.config.settings import AppConfig
+from src.config.constants import ReasoningMode, ModelConfig
+from src.core.reasoner import AdvancedReasoner
+from src.core.prompt_engine import PromptEngine
+from src.utils.logger import logger
+
+
+class UIComponents:
+    """
+    🎨 REUSABLE UI COMPONENTS
+    """
+    
+    @staticmethod
+    def get_header_html() -> str:
+        """
+        📋 GENERATE HEADER HTML
+        """
+        return """
+        <div class="research-header">
+            <h1>🧠 Advanced AI Reasoning System Pro</h1>
+            <p><strong>Research-Backed Implementation:</strong> Tree of Thoughts + Constitutional AI + Multi-Agent Validation + Performance Optimization</p>
+            <div style="margin-top: 1rem;">
+                <span class="badge">🌳 Yao et al. 2023 - Tree of Thoughts</span>
+                <span class="badge">🛡️ Bai et al. 2022 - Constitutional AI</span>
+                <span class="badge">🔬 6 Advanced Reasoning Modes</span>
+                <span class="badge">⚡ Cache + Rate Limiting</span>
+                <span class="badge">🎛️ Collapsible Sidebar</span>
+                <span class="badge">📊 Real-Time Analytics</span>
+            </div>
+        </div>
+        """
+    
+    @staticmethod
+    def get_metrics_html(reasoner: AdvancedReasoner) -> str:
+        """
+        📊 GENERATE METRICS HTML
+        """
+        m = reasoner.metrics
+        cache_stats = reasoner.cache.get_stats()
+        
+        if m.tokens_used > 0:
+            status = '<span class="status-active">● Active</span>'
+        else:
+            status = '<span style="color: #64748b;">● Ready</span>'
+        
+        return f"""<div class="metrics-card">
+        <strong>⚡ Inference:</strong> {m.inference_time:.2f}s<br>
+        <strong>⏱️  Avg Time:</strong> {m.avg_response_time:.2f}s<br>
+        <strong>🚀 Speed:</strong> {m.tokens_per_second:.1f} tok/s<br>
+        <strong>🧠 Reasoning:</strong> {m.reasoning_depth} steps<br>
+        <strong>🔄 Corrections:</strong> {m.self_corrections}<br>
+        <strong>✨ Confidence:</strong> {m.confidence_score:.1f}%<br>
+        <strong>💬 Total:</strong> {m.total_conversations}<br>
+        <strong>📊 Tokens:</strong> {m.tokens_used:,}<br>
+        <strong>🏔️  Peak:</strong> {m.peak_tokens}<br>
+        <strong>💾 Cache:</strong> {cache_stats['hit_rate']}% hit rate<br>
+        <strong>📡 Status:</strong> {status}<br>
+        <strong>🔑 Session:</strong> {reasoner.session_id[:8]}...
+        </div>"""
+    
+    @staticmethod
+    def get_empty_analytics_html() -> str:
+        """
+        📊 GENERATE EMPTY ANALYTICS HTML
+        """
+        return """<div class="analytics-panel">
+        <h3>📊 No Analytics Data Yet</h3>
+        <p>Start a conversation to see detailed analytics and insights!</p>
+        <p style="margin-top: 1rem; font-size: 0.9em;">Metrics tracked: tokens, speed, reasoning depth, confidence scores, and more.</p>
+        </div>"""
+    
+    @staticmethod
+    def get_system_info_html(reasoner: AdvancedReasoner) -> str:
+        """
+        ℹ️ GENERATE SYSTEM INFO HTML
+        """
+        return f"""
+        **Session ID:** `{reasoner.session_id}`  
+        **Environment:** `{AppConfig.ENV}`  
+        **Cache Size:** {AppConfig.CACHE_SIZE} entries  
+        **Cache TTL:** {AppConfig.CACHE_TTL}s  
+        **Rate Limit:** {AppConfig.RATE_LIMIT_REQUESTS} req/{AppConfig.RATE_LIMIT_WINDOW}s  
+        **Max History:** {AppConfig.MAX_HISTORY_LENGTH} messages  
+        **Available Models:** {len(ModelConfig)} models  
+        **Reasoning Modes:** {len(ReasoningMode)} modes
+        """
+    
+    @staticmethod
+    def get_settings_table_html() -> str:
+        """
+        ⚙️ GENERATE SETTINGS TABLE HTML
+        """
+        return f"""
+        | Setting | Value |
+        |---------|-------|
+        | **Environment** | `{AppConfig.ENV}` |
+        | **Debug Mode** | `{AppConfig.DEBUG}` |
+        | **Max History Length** | {AppConfig.MAX_HISTORY_LENGTH} messages |
+        | **Max Conversation Storage** | {AppConfig.MAX_CONVERSATION_STORAGE} conversations |
+        | **Cache Size** | {AppConfig.CACHE_SIZE} entries |
+        | **Cache TTL** | {AppConfig.CACHE_TTL} seconds |
+        | **Rate Limit** | {AppConfig.RATE_LIMIT_REQUESTS} requests per {AppConfig.RATE_LIMIT_WINDOW}s |
+        | **Request Timeout** | {AppConfig.REQUEST_TIMEOUT} seconds |
+        | **Max Retries** | {AppConfig.MAX_RETRIES} attempts |
+        | **Export Directory** | `{AppConfig.EXPORT_DIR}` |
+        | **Backup Directory** | `{AppConfig.BACKUP_DIR}` |
+        | **Available Models** | {len(ModelConfig)} models |
+        | **Reasoning Modes** | {len(ReasoningMode)} modes |
+        """
+    
+    @staticmethod
+    def get_reasoning_mode_choices() -> list:
+        """Get reasoning mode choices"""
+        return [mode.value for mode in ReasoningMode]
+    
+    @staticmethod
+    def get_prompt_template_choices() -> list:
+        """Get prompt template choices"""
+        return list(PromptEngine.TEMPLATES.keys())
+    
+    @staticmethod
+    def get_model_choices() -> list:
+        """Get model choices"""
+        return [m.model_id for m in ModelConfig]

src/ui/handlers.py

@@ -0,0 +1,199 @@
+"""
+Event handlers for UI interactions
+"""
+from typing import Tuple, Optional
+from pathlib import Path
+import gradio as gr
+from src.core.reasoner import AdvancedReasoner
+from src.config.constants import ReasoningMode
+from src.utils.logger import logger
+from src.ui.components import UIComponents
+
+
+class EventHandlers:
+    """
+    🎯 EVENT HANDLERS FOR UI INTERACTIONS
+    """
+    
+    def __init__(self, reasoner: AdvancedReasoner):
+        self.reasoner = reasoner
+        self.components = UIComponents()
+    
+    def process_message(self, message, history, mode, critique, model_name, 
+                       temp, tokens, template, cache):
+        """
+        🔄 PROCESS MESSAGE WITH STREAMING
+        """
+        if not message or not message.strip():
+            history = history or []
+            history.append({
+                "role": "assistant", 
+                "content": "⚠️ **Input Error:** Please enter a message before submitting."
+            })
+            return history, self.components.get_metrics_html(self.reasoner)
+        
+        history = history or []
+        mode_enum = ReasoningMode(mode)
+        
+        # Add user message
+        history.append({"role": "user", "content": message})
+        yield history, self.components.get_metrics_html(self.reasoner)
+        
+        # Add empty assistant message for streaming
+        history.append({"role": "assistant", "content": ""})
+        
+        try:
+            for response in self.reasoner.generate_response(
+                message, history[:-1], model_name, mode_enum, 
+                critique, temp, tokens, template, cache
+            ):
+                history[-1]["content"] = response
+                yield history, self.components.get_metrics_html(self.reasoner)
+                
+        except Exception as e:
+            error_msg = f"❌ **Unexpected Error:** {str(e)}\n\nPlease try again or check the logs for details."
+            history[-1]["content"] = error_msg
+            logger.error(f"Error in process_message: {e}", exc_info=True)
+            yield history, self.components.get_metrics_html(self.reasoner)
+    
+    def reset_chat(self):
+        """🗑️ RESET CHAT"""
+        self.reasoner.clear_history()
+        logger.info("Chat history cleared by user")
+        return [], self.components.get_metrics_html(self.reasoner)
+    
+    def export_conversation(self, format_type, include_metadata):
+        """📤 EXPORT CONVERSATION"""
+        try:
+            content, filename = self.reasoner.export_conversation(format_type, include_metadata)
+            if filename:
+                logger.info(f"Conversation exported: {filename}")
+                return content, filename
+            else:
+                return content, None
+        except Exception as e:
+            logger.error(f"Export error: {e}")
+            return f"❌ Export failed: {str(e)}", None
+    
+    def download_chat_pdf(self):
+        """📄 DOWNLOAD CHAT AS PDF"""
+        try:
+            pdf_file = self.reasoner.export_current_chat_pdf()
+            if pdf_file:
+                logger.info(f"PDF ready for download: {pdf_file}")
+                return pdf_file
+            else:
+                logger.warning("No conversations to export")
+                return None
+        except Exception as e:
+            logger.error(f"PDF download error: {e}")
+            return None
+    
+    def search_conversations(self, keyword):
+        """🔍 SEARCH CONVERSATIONS"""
+        if not keyword or not keyword.strip():
+            return "⚠️ **Search Error:** Please enter a search keyword."
+        
+        try:
+            results = self.reasoner.search_conversations(keyword)
+            if not results:
+                return f"🔍 **No Results:** No conversations found containing '{keyword}'."
+            
+            output = f"### 🔍 Found {len(results)} result(s) for '{keyword}'\n\n"
+            for idx, entry in results[:10]:
+                output += f"**{idx + 1}.** 📅 {entry.timestamp} | 🤖 {entry.model}\n"
+                preview = entry.user_message[:100].replace('\n', ' ')
+                output += f"**👤 User:** {preview}...\n\n"
+            
+            if len(results) > 10:
+                output += f"\n*Showing first 10 of {len(results)} results*"
+            
+            return output
+        except Exception as e:
+            logger.error(f"Search error: {e}")
+            return f"❌ **Search Error:** {str(e)}"
+    
+    def refresh_analytics(self):
+        """📊 REFRESH ANALYTICS"""
+        try:
+            analytics = self.reasoner.get_analytics()
+            if not analytics:
+                return (
+                    self.components.get_empty_analytics_html(), 
+                    "No cache data available yet.", 
+                    "**Model Usage:** No data", 
+                    "**Reasoning Mode Usage:** No data"
+                )
+            
+            analytics_html = f"""<div class="analytics-panel">
+            <h3>📊 Session Analytics</h3>
+            <p><strong>🔑 Session ID:</strong> {analytics['session_id']}</p>
+            <p><strong>💬 Total Conversations:</strong> {analytics['total_conversations']}</p>
+            <p><strong>📊 Total Tokens:</strong> {analytics['total_tokens']:,}</p>
+            <p><strong>⏱️  Total Time:</strong> {analytics['total_time']:.1f}s</p>
+            <p><strong>⚡ Avg Inference Time:</strong> {analytics['avg_inference_time']:.2f}s</p>
+            <p><strong>🏔️  Peak Tokens:</strong> {analytics['peak_tokens']}</p>
+            <p><strong>🤖 Most Used Model:</strong> {analytics['most_used_model']}</p>
+            <p><strong>🧠 Most Used Mode:</strong> {analytics['most_used_mode']}</p>
+            <p><strong>⚠️  Errors:</strong> {analytics['error_count']}</p>
+            </div>"""
+            
+            cache_html = f"""**💾 Cache Performance:**
+- ✅ Hits: {analytics['cache_hits']}
+- ❌ Misses: {analytics['cache_misses']}
+- 📊 Total: {analytics['cache_hits'] + analytics['cache_misses']}
+- 📈 Hit Rate: {self.reasoner.cache.get_stats()['hit_rate']}%
+            """
+            
+            model_dist_html = f"**🤖 Most Used Model:** {analytics['most_used_model']}"
+            mode_dist_html = f"**🧠 Most Used Mode:** {analytics['most_used_mode']}"
+            
+            return analytics_html, cache_html, model_dist_html, mode_dist_html
+        except Exception as e:
+            logger.error(f"Analytics refresh error: {e}")
+            return self.components.get_empty_analytics_html(), "Error loading cache data", "No data", "No data"
+    
+    def update_history_stats(self):
+        """📚 UPDATE HISTORY STATS"""
+        try:
+            count = len(self.reasoner.conversation_history)
+            if count == 0:
+                return "📚 **No conversations yet.** Start chatting to build your history!"
+            
+            return f"""**📊 Conversation Statistics:**
+            
+- 💬 Total Conversations: {count}
+- 🔑 Session ID: `{self.reasoner.session_id[:8]}...`
+- 📅 Session Started: {self.reasoner.metrics.session_start}
+- 🤖 Models Used: {len(self.reasoner.model_usage)}
+- 🧠 Reasoning Modes Used: {len(self.reasoner.mode_usage)}
+            """
+        except Exception as e:
+            logger.error(f"History stats error: {e}")
+            return "Error loading history statistics"
+    
+    def clear_cache_action(self):
+        """🗑️ CLEAR CACHE"""
+        try:
+            self.reasoner.cache.clear()
+            logger.info("Cache cleared by user")
+            return "✅ **Success:** Cache cleared successfully!"
+        except Exception as e:
+            logger.error(f"Cache clear error: {e}")
+            return f"❌ **Error:** Failed to clear cache: {str(e)}"
+    
+    def reset_metrics_action(self):
+        """🔄 RESET METRICS"""
+        try:
+            self.reasoner.metrics.reset()
+            logger.info("Metrics reset by user")
+            return "✅ **Success:** Metrics reset successfully!"
+        except Exception as e:
+            logger.error(f"Metrics reset error: {e}")
+            return f"❌ **Error:** Failed to reset metrics: {str(e)}"
+    
+    def toggle_sidebar(self, sidebar_state):
+        """⚙️ TOGGLE SIDEBAR VISIBILITY"""
+        new_state = not sidebar_state
+        logger.info(f"Sidebar toggled: {'Visible' if new_state else 'Hidden'}")
+        return gr.update(visible=new_state), new_state

src/ui/styles.py

@@ -0,0 +1,266 @@
+"""
+CSS styles for the Gradio interface
+"""
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+:root {
+    --primary-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    --success-gradient: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);
+    --shadow-lg: 0 10px 40px rgba(0,0,0,0.15);
+    --border-radius: 16px;
+    --transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* ==================== HEADER ==================== */
+
+.research-header {
+    background: var(--primary-gradient);
+    padding: 3rem 2.5rem;
+    border-radius: var(--border-radius);
+    color: white;
+    margin-bottom: 2rem;
+    box-shadow: var(--shadow-lg);
+    animation: slideDown 0.6s ease-out;
+}
+
+.research-header h1 { 
+    font-size: 2.5rem; 
+    font-weight: 800; 
+    margin-bottom: 1rem;
+    text-shadow: 2px 2px 4px rgba(0,0,0,0.2);
+}
+
+.badge {
+    background: rgba(255,255,255,0.25);
+    backdrop-filter: blur(10px);
+    color: white;
+    padding: 0.5rem 1.2rem;
+    border-radius: 25px;
+    font-size: 0.9rem;
+    margin: 0.3rem;
+    display: inline-block;
+    transition: var(--transition);
+    border: 1px solid rgba(255,255,255,0.2);
+}
+
+.badge:hover {
+    transform: translateY(-2px);
+    background: rgba(255,255,255,0.35);
+}
+
+/* ==================== METRICS CARD ==================== */
+
+.metrics-card {
+    background: linear-gradient(135deg, #ffffff 0%, #f8f9fa 100%);
+    border-left: 5px solid #667eea;
+    padding: 1.8rem;
+    border-radius: var(--border-radius);
+    margin: 1rem 0;
+    font-family: 'JetBrains Mono', monospace;
+    transition: var(--transition);
+    box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+    color: #2c3e50 !important;
+}
+
+.metrics-card * {
+    color: #2c3e50 !important;
+}
+
+.metrics-card strong {
+    color: #1a202c !important;
+    font-weight: 700 !important;
+}
+
+.metrics-card:hover {
+    transform: translateX(5px);
+    box-shadow: 0 4px 12px rgba(0,0,0,0.12);
+}
+
+/* ==================== ANALYTICS PANEL ==================== */
+
+.analytics-panel {
+    background: var(--success-gradient);
+    color: white;
+    padding: 2rem;
+    border-radius: var(--border-radius);
+    animation: fadeIn 0.5s ease-out;
+    box-shadow: var(--shadow-lg);
+}
+
+.analytics-panel * {
+    color: white !important;
+}
+
+.analytics-panel h3 {
+    margin-bottom: 1rem;
+    font-size: 1.5rem;
+}
+
+.analytics-panel p {
+    line-height: 1.6;
+}
+
+.analytics-panel strong {
+    font-weight: 600;
+}
+
+/* ==================== STATUS INDICATORS ==================== */
+
+.status-active { 
+    color: #10b981 !important; 
+    font-weight: bold; 
+    animation: pulse 2s infinite;
+    text-shadow: 0 0 10px rgba(16, 185, 129, 0.5);
+}
+
+/* ==================== ANIMATIONS ==================== */
+
+@keyframes slideDown {
+    from { opacity: 0; transform: translateY(-30px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes fadeIn {
+    from { opacity: 0; transform: scale(0.95); }
+    to { opacity: 1; transform: scale(1); }
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.7; }
+}
+
+/* ==================== GLOBAL STYLES ==================== */
+
+.gradio-container { 
+    font-family: 'Inter', sans-serif !important;
+    max-width: 1600px !important;
+}
+
+.gr-button { 
+    transition: var(--transition) !important; 
+}
+
+.gr-button:hover { 
+    transform: translateY(-2px) !important;
+    box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3) !important;
+}
+
+/* ==================== MARKDOWN TEXT FIX ==================== */
+
+.gr-markdown .metrics-card {
+    color: #2c3e50 !important;
+}
+
+.gr-markdown .metrics-card p {
+    color: #2c3e50 !important;
+    margin: 0.25rem 0 !important;
+}
+
+.gr-markdown .metrics-card span {
+    color: #2c3e50 !important;
+}
+
+/* ==================== SIDEBAR TOGGLE ==================== */
+
+.sidebar-hidden {
+    display: none !important;
+}
+
+.toggle-btn {
+    position: fixed;
+    right: 20px;
+    top: 50%;
+    transform: translateY(-50%);
+    z-index: 1000;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    border: none;
+    border-radius: 50%;
+    width: 50px;
+    height: 50px;
+    cursor: pointer;
+    box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+    transition: all 0.3s ease;
+    font-size: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.toggle-btn:hover {
+    transform: translateY(-50%) scale(1.1);
+    box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);
+}
+
+.settings-column {
+    transition: all 0.3s ease-in-out;
+}
+
+.fullscreen-chat .gradio-container {
+    max-width: 98% !important;
+}
+
+/* ==================== RESPONSIVE DESIGN ==================== */
+
+@media (max-width: 768px) {
+    .research-header h1 {
+        font-size: 1.8rem;
+    }
+    
+    .badge {
+        font-size: 0.75rem;
+        padding: 0.4rem 0.8rem;
+    }
+    
+    .toggle-btn {
+        width: 40px;
+        height: 40px;
+        font-size: 16px;
+        right: 10px;
+    }
+    
+    .metrics-card {
+        padding: 1.2rem;
+        font-size: 0.9rem;
+    }
+}
+
+/* ==================== DARK MODE SUPPORT ==================== */
+
+@media (prefers-color-scheme: dark) {
+    .metrics-card {
+        background: linear-gradient(135deg, #1e293b 0%, #334155 100%);
+        color: #e2e8f0 !important;
+    }
+    
+    .metrics-card * {
+        color: #e2e8f0 !important;
+    }
+    
+    .metrics-card strong {
+        color: #f1f5f9 !important;
+    }
+}
+
+/* ==================== LOADING SPINNER ==================== */
+
+.loading-spinner {
+    border: 3px solid #f3f3f3;
+    border-top: 3px solid #667eea;
+    border-radius: 50%;
+    width: 40px;
+    height: 40px;
+    animation: spin 1s linear infinite;
+    margin: 20px auto;
+}
+
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+"""
+
+SIDEBAR_CSS = CUSTOM_CSS

src/utils/__init__.py

@@ -0,0 +1,21 @@
+"""
+Utilities package initialization
+"""
+from .logger import logger, setup_logging
+from .decorators import handle_groq_errors, with_rate_limit, timer_decorator
+from .validators import validate_input, validate_temperature, validate_max_tokens
+from .helpers import generate_session_id, format_timestamp, truncate_text
+
+__all__ = [
+    'logger',
+    'setup_logging',
+    'handle_groq_errors',
+    'with_rate_limit',
+    'timer_decorator',
+    'validate_input',
+    'validate_temperature',
+    'validate_max_tokens',
+    'generate_session_id',
+    'format_timestamp',
+    'truncate_text'
+]

src/utils/decorators.py

@@ -0,0 +1,83 @@
+"""
+Utility decorators for error handling and timing
+"""
+import time
+from functools import wraps
+from typing import Callable, Any
+import groq
+from src.utils.logger import logger
+
+
+def handle_groq_errors(max_retries: int = 3, retry_delay: float = 1.0) -> Callable:
+    """
+    🛡️ GROQ API ERROR HANDLER WITH EXPONENTIAL BACKOFF
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            last_exception = None
+            
+            for attempt in range(max_retries):
+                try:
+                    return func(*args, **kwargs)
+                    
+                except groq.RateLimitError as e:
+                    last_exception = e
+                    wait_time = retry_delay * (2 ** attempt)
+                    logger.warning(f"⏳ Rate limit hit. Waiting {wait_time:.1f}s... (Attempt {attempt + 1}/{max_retries})")
+                    time.sleep(wait_time)
+                    
+                except groq.APIConnectionError as e:
+                    last_exception = e
+                    wait_time = retry_delay * (2 ** attempt)
+                    logger.warning(f"🔌 Connection error. Retrying in {wait_time:.1f}s... (Attempt {attempt + 1}/{max_retries})")
+                    time.sleep(wait_time)
+                    
+                except groq.AuthenticationError as e:
+                    logger.error(f"🔑 Authentication failed: {e}")
+                    raise ValueError("Invalid GROQ_API_KEY. Please check your API key.") from e
+                    
+                except groq.BadRequestError as e:
+                    logger.error(f"❌ Invalid request: {e}")
+                    raise ValueError(f"Invalid request parameters: {str(e)}") from e
+                    
+                except Exception as e:
+                    last_exception = e
+                    logger.error(f"❌ Unexpected error: {e}", exc_info=True)
+                    if attempt == max_retries - 1:
+                        break
+                    time.sleep(retry_delay * (2 ** attempt))
+            
+            error_msg = f"Failed after {max_retries} attempts: {str(last_exception)}"
+            logger.error(error_msg)
+            raise Exception(error_msg) from last_exception
+        
+        return wrapper
+    return decorator
+
+
+def with_rate_limit(rate_limiter):
+    """
+    ⏱️ RATE LIMITING DECORATOR
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            rate_limiter.acquire()
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def timer_decorator(func: Callable) -> Callable:
+    """
+    ⏱️ TIMING DECORATOR
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        elapsed_time = time.time() - start_time
+        logger.debug(f"⏱️ {func.__name__} took {elapsed_time:.2f}s")
+        return result
+    return wrapper

src/utils/helpers.py

@@ -0,0 +1,44 @@
+"""
+Helper utility functions
+"""
+import hashlib
+import uuid
+from datetime import datetime
+from typing import Optional
+
+
+def generate_session_id() -> str:
+    """
+    🔑 GENERATE UNIQUE SESSION ID
+    """
+    timestamp = datetime.now().isoformat()
+    random_uuid = str(uuid.uuid4())
+    raw_id = f"{timestamp}-{random_uuid}"
+    return hashlib.sha256(raw_id.encode()).hexdigest()
+
+
+def format_timestamp(dt: Optional[datetime] = None) -> str:
+    """
+    📅 FORMAT TIMESTAMP
+    """
+    if dt is None:
+        dt = datetime.now()
+    return dt.strftime('%Y-%m-%d %H:%M:%S')
+
+
+def truncate_text(text: str, max_length: int = 100, suffix: str = "...") -> str:
+    """
+    ✂️ TRUNCATE TEXT TO MAX LENGTH
+    """
+    if len(text) <= max_length:
+        return text
+    return text[:max_length - len(suffix)] + suffix
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    🧹 SANITIZE FILENAME
+    """
+    import re
+    filename = re.sub(r'[<>:"/\\|?*]', '_', filename)
+    return filename[:255]

src/utils/logger.py

@@ -0,0 +1,68 @@
+"""
+Enhanced logging configuration - Independent module
+"""
+import logging
+import os
+from pathlib import Path
+from logging.handlers import RotatingFileHandler
+
+
+def setup_logging():
+    """
+    🔧 ENHANCED LOGGING SETUP
+    """
+    logger = logging.getLogger('reasoning_system')
+    
+    log_level_str = os.getenv('LOG_LEVEL', 'INFO').upper()
+    log_level = getattr(logging, log_level_str, logging.INFO)
+    logger.setLevel(log_level)
+    
+    if logger.handlers:
+        return logger
+    
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_format = logging.Formatter(
+        '%(asctime)s | %(levelname)-8s | %(message)s',
+        datefmt='%H:%M:%S'
+    )
+    console_handler.setFormatter(console_format)
+    
+    # File handler with rotation
+    log_dir = Path('logs')
+    log_dir.mkdir(exist_ok=True)
+    
+    file_handler = RotatingFileHandler(
+        log_dir / 'reasoning_system.log',
+        maxBytes=10*1024*1024,
+        backupCount=5,
+        encoding='utf-8'
+    )
+    file_handler.setLevel(logging.DEBUG)
+    file_format = logging.Formatter(
+        '%(asctime)s | %(levelname)-8s | %(name)s:%(lineno)d | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    file_handler.setFormatter(file_format)
+    
+    # Error-only file handler
+    error_handler = RotatingFileHandler(
+        log_dir / 'errors.log',
+        maxBytes=5*1024*1024,
+        backupCount=3,
+        encoding='utf-8'
+    )
+    error_handler.setLevel(logging.ERROR)
+    error_handler.setFormatter(file_format)
+    
+    logger.addHandler(console_handler)
+    logger.addHandler(file_handler)
+    logger.addHandler(error_handler)
+    logger.propagate = False
+    
+    return logger
+
+
+# Initialize logger at module level
+logger = setup_logging()

src/utils/validators.py

@@ -0,0 +1,50 @@
+"""
+Input validation utilities
+"""
+from typing import Any
+from src.utils.logger import logger
+
+
+def validate_input(text: str, max_length: int = 10000) -> tuple[bool, str]:
+    """
+    ✅ VALIDATE USER INPUT
+    """
+    if not text or not text.strip():
+        return False, "Input cannot be empty"
+    
+    if len(text) > max_length:
+        return False, f"Input exceeds maximum length of {max_length} characters"
+    
+    # XSS protection
+    dangerous_patterns = ['<script>', 'javascript:', 'onerror=', 'onclick=']
+    text_lower = text.lower()
+    if any(pattern in text_lower for pattern in dangerous_patterns):
+        return False, "Input contains potentially dangerous content"
+    
+    return True, ""
+
+
+def validate_temperature(temp: float, min_temp: float = 0.0, max_temp: float = 2.0) -> tuple[bool, str]:
+    """
+    ✅ VALIDATE TEMPERATURE PARAMETER
+    """
+    if not isinstance(temp, (int, float)):
+        return False, "Temperature must be a number"
+    
+    if not (min_temp <= temp <= max_temp):
+        return False, f"Temperature must be between {min_temp} and {max_temp}"
+    
+    return True, ""
+
+
+def validate_max_tokens(tokens: int, min_tokens: int = 100, max_tokens: int = 32000) -> tuple[bool, str]:
+    """
+    ✅ VALIDATE MAX TOKENS PARAMETER
+    """
+    if not isinstance(tokens, int):
+        return False, "Max tokens must be an integer"
+    
+    if not (min_tokens <= tokens <= max_tokens):
+        return False, f"Max tokens must be between {min_tokens} and {max_tokens}"
+    
+    return True, ""

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests package."""

tests/test_api.py

@@ -0,0 +1,2 @@
+def test_placeholder():
+    assert True

tests/test_cache.py

@@ -0,0 +1,2 @@
+def test_placeholder():
+    assert True

tests/test_export.py

@@ -0,0 +1,2 @@
+def test_placeholder():
+    assert True

tests/test_reasoner.py

@@ -0,0 +1,2 @@
+def test_placeholder():
+    assert True