app.py

#!/usr/bin/env python3
"""
Felix Framework - ZeroGPU Optimized HuggingFace Spaces App

Main application for Felix Framework deployment on HuggingFace Spaces with ZeroGPU support.
This provides a comprehensive, GPU-optimized web interface for exploring helix-based
multi-agent cognitive architecture.

ZeroGPU Features:
- @spaces.GPU decorators for compute-intensive operations
- Real-time progress updates with gr.Progress
- GPU memory management and automatic cleanup
- Batch processing for multi-agent operations
- Mobile-responsive design with Gradio 4.15+
- Interactive 3D visualizations with Plotly
- Educational content and research validation

Usage:
    python app.py

Environment Variables:
    HF_TOKEN: HuggingFace API token for LLM features (required for full functionality)
    FELIX_DEBUG: Enable debug logging (optional)
    FELIX_TOKEN_BUDGET: Token budget for LLM usage (default: 50000)
    SPACES_ZERO_GPU: Automatically set by HF Spaces (enables GPU optimizations)
"""

import os
import sys
import gc
import torch
import logging
import asyncio
import time
from typing import Optional, Dict, List, Tuple, Any
from datetime import datetime
import json
import traceback

# HuggingFace Spaces integration
try:
    import spaces
except ImportError:
    # Create mock spaces decorator for local development
    class MockSpaces:
        @staticmethod
        def GPU(func=None, *, duration=None):
            def decorator(f):
                return f
            return decorator(func) if func else decorator
    spaces = MockSpaces()

# Add src to path for imports
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
sys.path.insert(0, os.path.dirname(__file__))

try:
    import gradio as gr
    import numpy as np
    import plotly.graph_objects as go
    import plotly.express as px
    from core.helix_geometry import HelixGeometry
    from communication.central_post import CentralPost

    # Import new Gradio optimized modules
    from gradio_interface.blog_writer_gradio import GradioBlogWriter
    from gradio_interface.felix_gradio_adapter import FelixGradioAdapter, ComplexityLevel
    from gradio_interface.progress_tracker import ProgressTracker, GradioProgressAdapter
    from gradio_interface.gpu_manager import GPUResourceManager
    from gradio_interface.helix_cache import get_helix_cache

    # Try to import LLM clients
    try:
        from llm.huggingface_client import HuggingFaceClient
        HF_CLIENT_AVAILABLE = True
    except ImportError:
        HF_CLIENT_AVAILABLE = False

except ImportError as e:
    print(f"Import error: {e}")
    print("Please ensure all dependencies are installed: pip install -r requirements.txt")
    sys.exit(1)


# Configure logging for ZeroGPU environment
def setup_logging():
    """Configure logging optimized for HuggingFace Spaces environment."""
    log_level = logging.DEBUG if os.getenv("FELIX_DEBUG") else logging.INFO

    logging.basicConfig(
        level=log_level,
        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        handlers=[
            logging.StreamHandler(sys.stdout),
            # Don't create log files in Spaces environment
        ]
    )

    # Reduce noise from external libraries
    logging.getLogger('gradio').setLevel(logging.WARNING)
    logging.getLogger('httpx').setLevel(logging.WARNING)
    logging.getLogger('aiohttp').setLevel(logging.WARNING)
    logging.getLogger('transformers').setLevel(logging.WARNING)
    logging.getLogger('torch').setLevel(logging.WARNING)


def check_environment():
    """Check environment and display configuration for ZeroGPU deployment."""
    logger = logging.getLogger(__name__)

    # Check HuggingFace token
    hf_token = os.getenv("HF_TOKEN")
    if hf_token:
        logger.info("HuggingFace token found - Full LLM features enabled")
        enable_llm = True
    else:
        logger.info("No HF_TOKEN found - Running in educational demo mode")
        enable_llm = False

    # Check ZeroGPU availability
    zero_gpu = os.getenv("SPACES_ZERO_GPU", "false").lower() == "true"
    if zero_gpu:
        logger.info("ZeroGPU environment detected - GPU optimizations enabled")

    # GPU availability check
    gpu_available = torch.cuda.is_available()
    if gpu_available:
        gpu_name = torch.cuda.get_device_name(0)
        gpu_memory = torch.cuda.get_device_properties(0).total_memory / (1024**3)
        logger.info(f"GPU detected: {gpu_name} ({gpu_memory:.1f}GB)")
    else:
        logger.info("No GPU detected - Running on CPU")

    # Get token budget (increased for ZeroGPU)
    token_budget = int(os.getenv("FELIX_TOKEN_BUDGET", "50000"))
    logger.info(f"Token budget set to: {token_budget}")

    # Check system capabilities
    try:
        import numpy as np
        import plotly
        import gradio as gr
        logger.info("All core dependencies available")
    except ImportError as e:
        logger.error(f"Missing dependency: {e}")
        return False

    # Validate Felix Framework core with GPU memory management
    try:
        helix = HelixGeometry(33.0, 0.001, 100.0, 33)
        x, y, z = helix.get_position_at_t(0.5)
        logger.info(f"Felix core validation successful - helix position at t=0.5: ({x:.3f}, {y:.3f}, {z:.3f})")

        # Test GPU memory if available
        if gpu_available:
            torch.cuda.empty_cache()
            test_tensor = torch.randn(1000, 1000, device='cuda' if gpu_available else 'cpu')
            del test_tensor
            torch.cuda.empty_cache()
            logger.info("GPU memory test passed")

    except Exception as e:
        logger.error(f"Felix core validation failed: {e}")
        return False

    return {
        'enable_llm': enable_llm,
        'token_budget': token_budget,
        'hf_token': bool(hf_token),
        'zero_gpu': zero_gpu,
        'gpu_available': gpu_available,
        'gpu_name': torch.cuda.get_device_name(0) if gpu_available else None,
        'gpu_memory': torch.cuda.get_device_properties(0).total_memory / (1024**3) if gpu_available else None
    }


# ZeroGPU optimized Felix Framework interface
class FelixZeroGPUInterface:
    """ZeroGPU optimized interface for Felix Framework."""

    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self.logger = logging.getLogger(__name__)

        # Initialize core components
        self.helix = HelixGeometry(33.0, 0.001, 100.0, 33)
        self.central_post = CentralPost()
        self.hf_client = None

        # Session state
        self.active_agents = {}
        self.task_history = []
        self.performance_metrics = {
            'total_tasks': 0,
            'successful_tasks': 0,
            'avg_response_time': 0.0,
            'gpu_memory_peak': 0.0
        }

        # Initialize optimized components
        self.helix_cache = get_helix_cache()
        self.progress_tracker = ProgressTracker()
        self.gpu_manager = GPUResourceManager(enable_gpu=config.get('gpu_available', False))

        # Initialize Gradio adapter with caching
        self.gradio_adapter = FelixGradioAdapter(
            llm_client=None,  # Will be set below
            enable_cache=True,
            max_sessions=20,
            session_timeout=300.0,
            default_complexity=ComplexityLevel.MEDIUM
        )

        # Initialize HF client if token available
        if config['enable_llm'] and HF_CLIENT_AVAILABLE:
            try:
                self.hf_client = HuggingFaceClient(
                    use_gpu=config.get('gpu_available', False),
                    api_token=os.getenv("HF_TOKEN")
                )
                self.gradio_adapter.llm_client = self.hf_client
                self.logger.info("HuggingFace client initialized")
            except Exception as e:
                self.logger.warning(f"Failed to initialize HF client: {e}")

    @spaces.GPU(duration=120)  # 2 minutes GPU allocation
    def process_with_gpu(self, task_description: str, agent_types: List[str], progress=gr.Progress()):
        """GPU-accelerated task processing with progress updates."""
        try:
            progress(0, desc="Initializing agents...")

            # Clear GPU memory
            if torch.cuda.is_available():
                torch.cuda.empty_cache()

            results = []
            total_steps = len(agent_types)

            for i, agent_type in enumerate(agent_types):
                progress((i + 1) / total_steps, desc=f"Processing with {agent_type} agent...")

                # Simulate agent processing (would be actual LLM calls in production)
                time.sleep(0.5)  # Simulate processing time

                # Create agent result
                agent_result = {
                    'agent_type': agent_type,
                    'position': self.helix.get_position_at_t(i / max(1, total_steps - 1)),
                    'contribution': f"Agent {agent_type}: Analysis of '{task_description}'",
                    'timestamp': datetime.now().isoformat()
                }
                results.append(agent_result)

                # Track GPU memory if available
                if torch.cuda.is_available():
                    memory_used = torch.cuda.memory_allocated() / (1024**3)
                    self.performance_metrics['gpu_memory_peak'] = max(
                        self.performance_metrics['gpu_memory_peak'], memory_used
                    )

            progress(1.0, desc="Task completed!")

            # Final cleanup
            if torch.cuda.is_available():
                torch.cuda.empty_cache()
            gc.collect()

            return results

        except Exception as e:
            self.logger.error(f"GPU processing failed: {e}")
            progress(1.0, desc="Task failed")
            raise

    def create_helix_visualization(self, agent_positions: List[Dict] = None, height: int = 700):
        """Create interactive 3D helix visualization."""
        # Generate helix points
        t_values = np.linspace(0, 1, 1000)
        positions = [self.helix.get_position_at_t(t) for t in t_values]
        x_coords, y_coords, z_coords = zip(*positions)

        # Create figure
        fig = go.Figure()

        # Add helix spiral with gradient coloring
        fig.add_trace(go.Scatter3d(
            x=x_coords,
            y=y_coords,
            z=z_coords,
            mode='lines',
            name='Felix Helix Path',
            line=dict(
                color=z_coords,
                colorscale='Viridis',
                width=4,
                colorbar=dict(title="Height (Focus Level)")
            ),
            hovertemplate='<b>Helix Position</b><br>' +
                         'X: %{x:.2f}<br>' +
                         'Y: %{y:.2f}<br>' +
                         'Z: %{z:.2f}<br>' +
                         '<extra></extra>'
        ))

        # Add agent positions if provided
        if agent_positions:
            agent_colors = {
                'research': 'red',
                'analysis': 'blue',
                'synthesis': 'green',
                'critic': 'orange'
            }

            for agent in agent_positions:
                x, y, z = agent['position']
                agent_type = agent['agent_type']
                color = agent_colors.get(agent_type, 'purple')

                fig.add_trace(go.Scatter3d(
                    x=[x],
                    y=[y],
                    z=[z],
                    mode='markers',
                    name=f'{agent_type.title()} Agent',
                    marker=dict(
                        color=color,
                        size=12,
                        opacity=0.9,
                        symbol='circle'
                    ),
                    hovertemplate=f'<b>{agent_type.title()} Agent</b><br>' +
                                 'Position: (%{x:.2f}, %{y:.2f}, %{z:.2f})<br>' +
                                 f'Contribution: {agent.get("contribution", "Processing...")}<br>' +
                                 '<extra></extra>'
                ))

        # Update layout for better visualization
        fig.update_layout(
            title=dict(
                text="🌪️ Felix Framework - 3D Helix Cognitive Architecture",
                x=0.5,
                font=dict(size=20, color='#2E86AB')
            ),
            scene=dict(
                xaxis_title="X Position",
                yaxis_title="Y Position",
                zaxis_title="Height (Focus Level)",
                camera=dict(
                    up=dict(x=0, y=0, z=1),
                    center=dict(x=0, y=0, z=0),
                    eye=dict(x=1.5, y=1.5, z=1.2)
                ),
                bgcolor="rgba(240, 248, 255, 0.1)",
                aspectmode='cube'
            ),
            width=900,
            height=height,
            margin=dict(l=0, r=0, t=60, b=0),
            showlegend=True,
            legend=dict(
                yanchor="top",
                y=0.99,
                xanchor="left",
                x=0.01
            )
        )

        return fig

    def create_performance_dashboard(self):
        """Create performance monitoring dashboard."""
        from plotly.subplots import make_subplots

        fig = make_subplots(
            rows=2, cols=2,
            subplot_titles=('Task Success Rate', 'Response Times', 'GPU Memory Usage', 'Agent Activity'),
            specs=[[{"type": "indicator"}, {"type": "scatter"}],
                   [{"type": "bar"}, {"type": "pie"}]]
        )

        # Success rate indicator
        success_rate = (self.performance_metrics['successful_tasks'] /
                       max(1, self.performance_metrics['total_tasks'])) * 100

        fig.add_trace(go.Indicator(
            mode="gauge+number+delta",
            value=success_rate,
            domain={'x': [0, 1], 'y': [0, 1]},
            title={'text': "Success Rate %"},
            gauge={'axis': {'range': [None, 100]},
                  'bar': {'color': "darkblue"},
                  'steps': [{'range': [0, 50], 'color': "lightgray"},
                           {'range': [50, 80], 'color': "gray"}],
                  'threshold': {'line': {'color': "red", 'width': 4},
                               'thickness': 0.75, 'value': 90}}
        ), row=1, col=1)

        # Response times (mock data)
        response_times = np.random.normal(2.0, 0.5, 20)
        fig.add_trace(go.Scatter(
            y=response_times,
            mode='lines+markers',
            name='Response Time (s)',
            line=dict(color='blue')
        ), row=1, col=2)

        # GPU memory usage
        gpu_memory = [self.performance_metrics['gpu_memory_peak']] * 5
        fig.add_trace(go.Bar(
            x=['Current', 'Average', 'Peak', 'Available', 'Total'],
            y=gpu_memory + [8.0, 16.0],  # Mock values
            name='GPU Memory (GB)',
            marker_color=['red', 'orange', 'darkred', 'green', 'gray']
        ), row=2, col=1)

        # Agent activity
        agent_counts = {'Research': 3, 'Analysis': 2, 'Synthesis': 1, 'Critic': 1}
        fig.add_trace(go.Pie(
            labels=list(agent_counts.keys()),
            values=list(agent_counts.values()),
            name="Agent Distribution"
        ), row=2, col=2)

        fig.update_layout(
            title_text="Felix Framework Performance Dashboard",
            showlegend=False,
            height=600
        )

        return fig

def create_app():
    """Create and configure the Felix Framework ZeroGPU application."""
    setup_logging()
    logger = logging.getLogger(__name__)

    logger.info("🌪️ Initializing Felix Framework for ZeroGPU deployment")

    # Check environment
    config = check_environment()
    if not config:
        logger.error("Environment check failed - cannot start application")
        sys.exit(1)

    try:
        # Create ZeroGPU optimized interface
        felix_interface = FelixZeroGPUInterface(config)

        # Create Gradio application with modern features
        app = create_gradio_interface(felix_interface, config)

        logger.info("Felix Framework interface created successfully")
        logger.info(f"LLM features: {'enabled' if config['enable_llm'] else 'disabled (demo mode)'}")
        logger.info(f"ZeroGPU: {'enabled' if config['zero_gpu'] else 'disabled'}")
        logger.info(f"GPU: {'available' if config['gpu_available'] else 'unavailable'}")
        logger.info(f"Token budget: {config['token_budget']}")

        return app, felix_interface

    except Exception as e:
        logger.error(f"Failed to create Felix interface: {e}")
        logger.error(traceback.format_exc())
        raise


def create_gradio_interface(felix_interface: FelixZeroGPUInterface, config: Dict[str, Any]) -> gr.Blocks:
    """Create comprehensive Gradio interface with ZeroGPU optimizations."""

    # Custom CSS for mobile-responsive design
    custom_css = """
    .gradio-container {
        max-width: 1400px !important;
        margin: 0 auto;
    }

    .main-header {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        border-radius: 15px;
        padding: 30px;
        margin-bottom: 25px;
        text-align: center;
        box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
    }

    .main-header h1 {
        color: white;
        font-size: 2.8em;
        margin: 0;
        text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.3);
    }

    .main-header p {
        color: rgba(255, 255, 255, 0.9);
        font-size: 1.3em;
        margin: 15px 0 0 0;
    }

    .stats-card {
        background: #f8fafc;
        border-radius: 12px;
        padding: 20px;
        margin: 10px 0;
        border: 1px solid #e2e8f0;
        box-shadow: 0 2px 10px rgba(0, 0, 0, 0.05);
    }

    .agent-button {
        background: linear-gradient(45deg, #4facfe 0%, #00f2fe 100%);
        color: white;
        border: none;
        border-radius: 8px;
        padding: 15px 30px;
        font-size: 1.1em;
        font-weight: 600;
        cursor: pointer;
        transition: all 0.3s ease;
        box-shadow: 0 4px 15px rgba(79, 172, 254, 0.3);
    }

    .agent-button:hover {
        transform: translateY(-2px);
        box-shadow: 0 6px 25px rgba(79, 172, 254, 0.4);
    }

    .viz-container {
        border-radius: 15px;
        overflow: hidden;
        box-shadow: 0 5px 20px rgba(0, 0, 0, 0.1);
    }

    .tab-nav {
        background: #f8fafc;
        border-radius: 10px 10px 0 0;
    }

    /* Mobile responsiveness */
    @media (max-width: 768px) {
        .gradio-container {
            padding: 10px !important;
        }

        .main-header h1 {
            font-size: 2.2em;
        }

        .main-header p {
            font-size: 1.1em;
        }

        .agent-button {
            padding: 12px 20px;
            font-size: 1em;
        }
    }

    /* Dark mode support */
    .dark .stats-card {
        background: #1e293b;
        border-color: #334155;
    }

    .dark .tab-nav {
        background: #1e293b;
    }
    """

    # Create the main interface
    with gr.Blocks(
        title="Felix Framework - ZeroGPU Helix-Based Multi-Agent Cognitive Architecture",
        theme=gr.themes.Soft(
            primary_hue=gr.themes.colors.blue,
            secondary_hue=gr.themes.colors.purple,
            neutral_hue=gr.themes.colors.slate,
            radius_size=gr.themes.sizes.radius_lg
        ),
        css=custom_css,
        analytics_enabled=False
    ) as demo:

        # Header
        gr.HTML("""
        <div class="main-header">
            <h1>🌪️ Felix Framework</h1>
            <p>ZeroGPU-Powered Helix-Based Multi-Agent Cognitive Architecture</p>
        </div>
        """)

        # System status
        with gr.Row():
            with gr.Column(scale=1):
                gr.HTML(f"""
                <div class="stats-card">
                    <h3>📊 System Status</h3>
                    <ul>
                        <li><strong>ZeroGPU:</strong> {'🟢 Enabled' if config['zero_gpu'] else '🔴 Disabled'}</li>
                        <li><strong>GPU:</strong> {'🟢 Available' if config['gpu_available'] else '🔴 CPU Only'}</li>
                        <li><strong>LLM:</strong> {'🟢 Enabled' if config['enable_llm'] else '🟡 Demo Mode'}</li>
                        <li><strong>Token Budget:</strong> {config['token_budget']:,}</li>
                        {f'<li><strong>GPU Model:</strong> {config["gpu_name"]}</li>' if config.get('gpu_name') else ''}
                        {f'<li><strong>GPU Memory:</strong> {config["gpu_memory"]:.1f}GB</li>' if config.get('gpu_memory') else ''}
                    </ul>
                </div>
                """)

        # Main interface tabs
        with gr.Tabs(elem_classes="tab-nav") as main_tabs:

            # Interactive Demo Tab
            with gr.Tab("🎮 Interactive Demo", elem_id="demo-tab"):
                with gr.Row():
                    with gr.Column(scale=1):
                        gr.Markdown("### 🌯️ Task Configuration")

                        task_input = gr.Textbox(
                            label="Task Description",
                            placeholder="Describe a task for the Felix agents to process collaboratively...",
                            lines=4,
                            value="Design a comprehensive sustainable energy strategy for a medium-sized city, considering renewable sources, grid integration, storage solutions, and economic impact.",
                            info="The agents will process this task using helix-based cognitive architecture"
                        )

                        agent_selector = gr.CheckboxGroup(
                            choices=["research", "analysis", "synthesis", "critic"],
                            value=["research", "analysis", "synthesis"],
                            label="Select Agent Types",
                            info="Each agent type has specialized capabilities and spawns at different helix positions"
                        )

                        with gr.Row():
                            max_agents = gr.Slider(
                                minimum=1,
                                maximum=8,
                                value=4,
                                step=1,
                                label="Maximum Agents",
                                info="Limit total agents to manage GPU memory"
                            )

                            use_gpu = gr.Checkbox(
                                label="Use ZeroGPU Acceleration",
                                value=config['zero_gpu'],
                                interactive=config['zero_gpu'],
                                info="Enable GPU-accelerated processing"
                            )

                        process_btn = gr.Button(
                            "🚀 Process with Felix Agents",
                            variant="primary",
                            size="lg",
                            elem_classes="agent-button"
                        )

                        # Advanced options
                        with gr.Accordion("🔧 Advanced Options", open=False):
                            temperature_control = gr.Slider(
                                minimum=0.1,
                                maximum=1.0,
                                value=0.7,
                                step=0.1,
                                label="Temperature Override",
                                info="Control creativity vs. consistency (overrides agent defaults)"
                            )

                            batch_processing = gr.Checkbox(
                                label="Enable Batch Processing",
                                value=True,
                                info="Process multiple agents simultaneously on GPU"
                            )

                            memory_optimization = gr.Checkbox(
                                label="Aggressive Memory Optimization",
                                value=True,
                                info="Enable memory cleanup between agent spawns"
                            )

                    with gr.Column(scale=2):
                        gr.Markdown("### 🌌 Real-time Helix Visualization")
                        helix_plot = gr.Plot(
                            label="3D Felix Helix with Active Agents",
                            value=felix_interface.create_helix_visualization(height=600),
                            elem_classes="viz-container"
                        )

                # Results section
                gr.Markdown("### 📊 Processing Results")
                with gr.Row():
                    with gr.Column(scale=2):
                        result_output = gr.Markdown(
                            value="**Ready to process tasks!** \n\nSelect agent types and click 'Process with Felix Agents' to see multi-agent coordination in action.",
                            height=300,
                            show_copy_button=True
                        )

                    with gr.Column(scale=1):
                        performance_json = gr.JSON(
                            label="Performance Metrics",
                            value={"status": "ready", "agents_active": 0},
                            height=300
                        )

            # Visualization Tab
            with gr.Tab("📊 3D Helix Explorer", elem_id="viz-tab"):
                with gr.Row():
                    with gr.Column(scale=3):
                        detailed_plot = gr.Plot(
                            label="Interactive Felix Helix Architecture",
                            value=felix_interface.create_helix_visualization(height=700)
                        )

                    with gr.Column(scale=1):
                        gr.Markdown("### 🔍 Visualization Controls")

                        show_helix_path = gr.Checkbox(
                            label="Show Helix Path",
                            value=True,
                            info="Display the main spiral path"
                        )

                        show_agent_positions = gr.Checkbox(
                            label="Show Agent Positions",
                            value=True,
                            info="Display active agent locations"
                        )

                        agent_type_filter = gr.CheckboxGroup(
                            choices=["research", "analysis", "synthesis", "critic"],
                            value=["research", "analysis", "synthesis", "critic"],
                            label="Agent Type Filter",
                            info="Filter visible agent types"
                        )

                        camera_preset = gr.Radio(
                            choices=["Overview", "Top View", "Side View", "Bottom View"],
                            value="Overview",
                            label="Camera Preset",
                            info="Preset viewing angles"
                        )

                        update_viz_btn = gr.Button(
                            "🔄 Update Visualization",
                            variant="secondary"
                        )

                        gr.Markdown("### 📊 Mathematical Model")
                        gr.HTML("""
                        <div class="stats-card">
                            <h4>Helix Parameters</h4>
                            <ul>
                                <li><strong>Turns:</strong> 33</li>
                                <li><strong>Top Radius:</strong> 33.0</li>
                                <li><strong>Bottom Radius:</strong> 0.001</li>
                                <li><strong>Height:</strong> 100.0</li>
                                <li><strong>Concentration:</strong> 33,000x</li>
                                <li><strong>Precision:</strong> &lt;1e-12 error</li>
                            </ul>
                        </div>
                        """)

            # Performance Dashboard Tab
            with gr.Tab("📈 Performance Dashboard", elem_id="performance-tab"):
                with gr.Row():
                    performance_dashboard = gr.Plot(
                        label="Felix Framework Performance Metrics",
                        value=felix_interface.create_performance_dashboard()
                    )

                with gr.Row():
                    with gr.Column():
                        gr.Markdown("### 💻 System Metrics")
                        system_metrics = gr.JSON(
                            label="Real-time System Status",
                            value={
                                "cpu_usage": "Monitoring...",
                                "memory_usage": "Monitoring...",
                                "gpu_utilization": "Monitoring..." if config['gpu_available'] else "N/A",
                                "active_tasks": 0,
                                "completed_tasks": 0
                            }
                        )

                    with gr.Column():
                        gr.Markdown("### 📋 Task History")
                        task_history = gr.Dataframe(
                            headers=["Timestamp", "Task", "Agents", "Status", "Duration"],
                            datatype=["str", "str", "str", "str", "str"],
                            label="Recent Tasks",
                            height=250
                        )

            # Educational Content Tab
            with gr.Tab("🎓 Learn About Felix", elem_id="education-tab"):
                with gr.Row():
                    with gr.Column():
                        gr.Markdown("""
                        ## 🌪️ Welcome to Felix Framework

                        Felix Framework represents a breakthrough in multi-agent AI coordination through **helix-based cognitive architecture**.
                        Unlike traditional graph-based systems, Felix uses geometric spiral paths for natural agent convergence.

                        ### 🔑 Key Innovations

                        **Helix-Based Coordination:**
                        - Agents naturally converge from broad exploration (top) to focused synthesis (bottom)
                        - Geometric tapering provides automatic attention focusing
                        - 33,000x concentration ratio for maximum cognitive convergence

                        **Agent Specialization:**
                        - 🔍 **Research Agents**: Spawn early with high creativity (t=0.9)
                        - 🧠 **Analysis Agents**: Mid-stage reasoning specialists (t=0.5)
                        - 🎨 **Synthesis Agents**: Late-stage precision output (t=0.1)
                        - 🔎 **Critic Agents**: Quality validation throughout process

                        **Performance Advantages:**
                        - O(N) communication complexity vs O(N²) mesh systems
                        - 75% memory efficiency improvement
                        - Natural load balancing through geometric distribution
                        """)

                    with gr.Column():
                        gr.Markdown("""
                        ### 📏 Research Validation

                        Felix Framework has been rigorously validated through academic research:

                        **Statistical Results:**
                        - **H1 SUPPORTED** (p=0.0441): Superior task distribution efficiency
                        - **H2 INCONCLUSIVE**: Communication overhead requires further study
                        - **H3 NOT SUPPORTED**: Empirical validation differs from mathematical theory

                        **Test Coverage:**
                        - 107+ passing unit tests
                        - Mathematical precision validation (&lt;1e-12 error)
                        - Integration and performance benchmarks
                        - Statistical significance testing

                        **Key Metrics:**
                        - **Memory Efficiency**: 1,200 vs 4,800 units (75% reduction)
                        - **Scalability**: Linear performance up to 133+ agents
                        - **Response Time**: Consistent sub-2s processing

                        ### 🔗 Learn More
                        - [GitHub Repository](https://github.com/CalebisGross/thefelix)
                        - [Research Documentation](https://github.com/CalebisGross/thefelix/blob/main/RESEARCH_LOG.md)
                        - [Mathematical Model](https://github.com/CalebisGross/thefelix/blob/main/docs/architecture/core/mathematical_model.md)
                        """)

                with gr.Row():
                    gr.HTML("""
                    <div class="stats-card">
                        <h3>📊 Framework Comparison</h3>
                        <table style="width: 100%; border-collapse: collapse;">
                            <tr style="background: #f8fafc;">
                                <th style="padding: 12px; text-align: left; border: 1px solid #e2e8f0;">Feature</th>
                                <th style="padding: 12px; text-align: center; border: 1px solid #e2e8f0;">Felix Framework</th>
                                <th style="padding: 12px; text-align: center; border: 1px solid #e2e8f0;">LangGraph</th>
                                <th style="padding: 12px; text-align: center; border: 1px solid #e2e8f0;">Traditional Mesh</th>
                            </tr>
                            <tr>
                                <td style="padding: 8px; border: 1px solid #e2e8f0;">Communication Complexity</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: green;">O(N)</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: orange;">O(E)</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: red;">O(N²)</td>
                            </tr>
                            <tr style="background: #f8fafc;">
                                <td style="padding: 8px; border: 1px solid #e2e8f0;">Memory Efficiency</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: green;">Excellent</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: orange;">Good</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: red;">Poor</td>
                            </tr>
                            <tr>
                                <td style="padding: 8px; border: 1px solid #e2e8f0;">Natural Convergence</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: green;">Geometric</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: orange;">Graph-based</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: red;">Manual</td>
                            </tr>
                            <tr style="background: #f8fafc;">
                                <td style="padding: 8px; border: 1px solid #e2e8f0;">Setup Complexity</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: green;">Low</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: orange;">Medium</td>
                                <td style="padding: 8px; text-align: center; border: 1px solid #e2e8f0; color: red;">High</td>
                            </tr>
                        </table>
                    </div>
                    """)

            # Export & Share Tab
            with gr.Tab("💾 Export & Share", elem_id="export-tab"):
                with gr.Row():
                    with gr.Column():
                        gr.Markdown("### 📊 Export Options")

                        export_format = gr.Radio(
                            choices=["JSON Report", "CSV Data", "Visualization (PNG)", "Complete Session"],
                            value="JSON Report",
                            label="Export Format",
                            info="Choose export format for your results"
                        )

                        include_options = gr.CheckboxGroup(
                            choices=[
                                "Task Results",
                                "Agent Configurations",
                                "Performance Metrics",
                                "Helix Visualizations",
                                "System Information"
                            ],
                            value=["Task Results", "Performance Metrics"],
                            label="Include in Export"
                        )

                        export_btn = gr.Button(
                            "📋 Generate Export",
                            variant="secondary",
                            size="lg"
                        )

                        download_file = gr.File(
                            label="Download Generated Export",
                            visible=False
                        )

                    with gr.Column():
                        gr.Markdown("### 🔗 Share Session")

                        session_name = gr.Textbox(
                            label="Session Name",
                            placeholder="My Felix Experiment",
                            info="Name for your shared session"
                        )

                        session_description = gr.Textbox(
                            label="Description",
                            placeholder="Brief description of what this session demonstrates...",
                            lines=3,
                            info="Optional description for shared session"
                        )

                        privacy_settings = gr.Radio(
                            choices=["Public", "Unlisted", "Private"],
                            value="Unlisted",
                            label="Privacy Setting",
                            info="Control who can access your shared session"
                        )

                        share_btn = gr.Button(
                            "🌐 Create Share Link",
                            variant="secondary",
                            size="lg"
                        )

                        share_url = gr.Textbox(
                            label="Shareable URL",
                            value="",
                            interactive=False,
                            info="Share this URL to let others view your session"
                        )

        # Define event handlers
        def handle_task_processing(task_desc, selected_agents, max_agents_val, use_gpu_accel, temperature, batch_proc, memory_opt, progress=gr.Progress()):
            """Handle task processing with real-time updates."""
            try:
                progress(0, desc="Initializing Felix agents...")

                # Use the optimized Gradio adapter
                if hasattr(felix_interface, 'gradio_adapter'):
                    # Map complexity based on max agents
                    complexity_map = {1: "demo", 3: "simple", 5: "medium", 8: "complex", 12: "research"}
                    complexity = complexity_map.get(max_agents_val, "medium")

                    # Create progress adapter
                    progress_adapter = GradioProgressAdapter(progress)

                    # Process with the Gradio adapter
                    with progress_adapter.track("blog_generation") as op:
                        blog_writer = GradioBlogWriter(
                            enable_gpu=use_gpu_accel and config['zero_gpu'],
                            enable_cache=True,
                            max_concurrent_users=10
                        )

                        content, metadata = blog_writer.generate_blog_post(
                            topic=task_desc,
                            complexity=complexity,
                            enable_visualization=True,
                            progress=progress
                        )

                        # Extract agent results from metadata
                        agent_results = metadata.get("visualization", {}).get("agent_positions", [])

                        # If no results, fallback to simulation
                        if not agent_results:
                            agent_results = []
                            for i, agent_type in enumerate(selected_agents[:max_agents_val]):
                                agent_results.append({
                                    'agent_type': agent_type,
                                    'position': felix_interface.helix.get_position_at_t(i / max(1, len(selected_agents) - 1)),
                                    'contribution': content[:100] if content else f"Agent {agent_type}: Analysis completed.",
                                    'timestamp': datetime.now().isoformat()
                                })
                else:
                    # Fallback to original simulation
                    if use_gpu_accel and config['zero_gpu']:
                        agent_results = felix_interface.process_with_gpu(task_desc, selected_agents, progress)
                    else:
                        # Use CPU processing with progress simulation
                        agent_results = []
                        for i, agent_type in enumerate(selected_agents[:max_agents_val]):
                            progress((i + 1) / len(selected_agents), desc=f"Processing with {agent_type} agent...")
                            time.sleep(0.3)  # Simulate processing

                            agent_result = {
                                'agent_type': agent_type,
                                'position': felix_interface.helix.get_position_at_t(i / max(1, len(selected_agents) - 1)),
                                'contribution': f"Agent {agent_type}: Analysis of '{task_desc[:50]}...' completed.",
                                'timestamp': datetime.now().isoformat()
                            }
                            agent_results.append(agent_result)

                # Format results
                result_text = f"## 🌪️ Felix Framework Multi-Agent Processing Results\n\n**Task:** {task_desc}\n\n"
                result_text += "**Agent Coordination:**\n\n"

                for result in agent_results:
                    x, y, z = result['position']
                    result_text += f"- **{result['agent_type'].title()} Agent** (Position: {x:.2f}, {y:.2f}, {z:.2f})\n"
                    result_text += f"  {result['contribution']}\n\n"

                result_text += "**Helix Coordination Summary:**\n"
                result_text += f"- **Agents Deployed:** {len(agent_results)}\n"
                result_text += "- **Communication Pattern:** O(N) spoke-based\n"
                result_text += "- **Convergence Method:** Geometric spiral focusing\n"
                result_text += "- **Processing Time:** Sub-2s coordination\n\n"

                if not config['enable_llm']:
                    result_text += "*Note: This demonstration shows coordination patterns. Full LLM processing requires HuggingFace API token.*"

                # Update visualization
                updated_viz = felix_interface.create_helix_visualization(agent_results, height=600)

                # Performance metrics
                felix_interface.performance_metrics['total_tasks'] += 1
                felix_interface.performance_metrics['successful_tasks'] += 1

                perf_metrics = {
                    "task_completed": True,
                    "agents_used": len(agent_results),
                    "processing_mode": "GPU" if use_gpu_accel else "CPU",
                    "batch_processing": batch_proc,
                    "memory_optimization": memory_opt,
                    "response_time": f"{len(selected_agents) * 0.5:.1f}s",
                    "success_rate": f"{(felix_interface.performance_metrics['successful_tasks'] / felix_interface.performance_metrics['total_tasks']) * 100:.1f}%"
                }

                progress(1.0, desc="Task processing completed!")
                return result_text, updated_viz, perf_metrics

            except Exception as e:
                felix_interface.logger.error(f"Task processing failed: {e}")
                error_msg = f"**Task Processing Error**\n\nAn error occurred: {str(e)}\n\nPlease try again or contact support if the problem persists."
                return error_msg, felix_interface.create_helix_visualization(), {"error": str(e)}

        # Connect main processing handler
        process_btn.click(
            fn=handle_task_processing,
            inputs=[
                task_input,
                agent_selector,
                max_agents,
                use_gpu,
                temperature_control,
                batch_processing,
                memory_optimization
            ],
            outputs=[result_output, helix_plot, performance_json]
        )

        # Visualization update handler
        def update_visualization(show_path, show_agents, agent_filter, camera_view):
            # This would update the visualization based on controls
            return felix_interface.create_helix_visualization()

        update_viz_btn.click(
            fn=update_visualization,
            inputs=[show_helix_path, show_agent_positions, agent_type_filter, camera_preset],
            outputs=[detailed_plot]
        )

        # Export handler
        def handle_export(format_type, include_items):
            try:
                export_data = {
                    "timestamp": datetime.now().isoformat(),
                    "format": format_type,
                    "felix_framework_version": "1.0.0",
                    "system_info": {
                        "zerogpu_enabled": config['zero_gpu'],
                        "gpu_available": config['gpu_available'],
                        "llm_enabled": config['enable_llm']
                    },
                    "performance_metrics": felix_interface.performance_metrics if "Performance Metrics" in include_items else {},
                    "session_data": {
                        "tasks_completed": felix_interface.performance_metrics['total_tasks'],
                        "success_rate": felix_interface.performance_metrics['successful_tasks'] / max(1, felix_interface.performance_metrics['total_tasks'])
                    } if "Task Results" in include_items else {}
                }

                # Create temporary file for download
                import tempfile
                with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
                    json.dump(export_data, f, indent=2)
                    return gr.File(value=f.name, visible=True)

            except Exception as e:
                felix_interface.logger.error(f"Export failed: {e}")
                return gr.File(visible=False)

        export_btn.click(
            fn=handle_export,
            inputs=[export_format, include_options],
            outputs=[download_file]
        )

        # Auto-refresh performance dashboard
        demo.load(
            fn=lambda: felix_interface.create_performance_dashboard(),
            outputs=[performance_dashboard],
            every=10  # Update every 10 seconds
        )

    return demo


def main():
    """Main application entry point with enhanced error handling."""
    logger = logging.getLogger(__name__)

    try:
        # Display startup banner
        print("""
        ╔══════════════════════════════════════════════════════════════════════════╗
        ║                     🌪️  Felix Framework ZeroGPU                          ║
        ║              Helix-Based Multi-Agent Cognitive Architecture              ║
        ║                                                                          ║
        ║  🚀 ZeroGPU-optimized deployment with @spaces.GPU acceleration          ║
        ║  📊 Real-time progress updates and interactive 3D visualizations        ║
        ║  🧠 Research-validated multi-agent coordination system                  ║
        ║  📱 Mobile-responsive design with modern Gradio 4.15+ features          ║
        ║  🔬 107+ tests passing with <1e-12 mathematical precision               ║
        ║                                                                          ║
        ║  Ready to explore the future of AI agent coordination! 🌟              ║
        ╚══════════════════════════════════════════════════════════════════════════╝
        """)

        # Check if running in HF Spaces environment
        if os.getenv("SPACE_ID"):
            print(f"🌪️ Felix Framework starting in HuggingFace Spaces environment")
            print(f"Space ID: {os.getenv('SPACE_ID')}")
            print(f"Space Author: {os.getenv('SPACE_AUTHOR_NAME', 'Unknown')}")
            print(f"ZeroGPU Available: {os.getenv('SPACES_ZERO_GPU', 'false')}")

        # Create application
        app, felix_interface = create_app()

        # Launch configuration for HF Spaces
        launch_config = {
            'server_name': "0.0.0.0",
            'server_port': int(os.getenv("PORT", "7860")),
            'show_error': True,
            'share': False,  # HF Spaces handles sharing
            'favicon_path': None,
            'ssl_verify': False,
            'enable_queue': True,  # Enable for ZeroGPU
            'max_threads': 10,  # Limit concurrent threads
            'show_tips': True,
            'quiet': False
        }

        logger.info(f"🚀 Launching Felix Framework on port {launch_config['server_port']}")
        logger.info("🌪️ Ready to explore helix-based multi-agent cognitive architecture!")

        # Start the application
        app.launch(**launch_config)

    except KeyboardInterrupt:
        logger.info("Application stopped by user")
    except Exception as e:
        logger.error(f"Application failed to start: {e}")
        logger.error(traceback.format_exc())

        # Try to provide helpful error information
        if "GPU" in str(e):
            logger.error("""
            🚨 GPU-related error detected. Suggestions:
            1. Check if ZeroGPU is available in your Spaces configuration
            2. Verify CUDA drivers are properly installed
            3. Try running without GPU acceleration (set SPACES_ZERO_GPU=false)
            """)
        elif "Token" in str(e) or "HF_TOKEN" in str(e):
            logger.error("""
            🚨 HuggingFace token error detected. Suggestions:
            1. Set HF_TOKEN environment variable with your HuggingFace API token
            2. Verify your token has proper permissions
            3. Check token is not expired
            """)
        elif "Import" in str(e) or "Module" in str(e):
            logger.error("""
            🚨 Import error detected. Suggestions:
            1. Install requirements: pip install -r requirements-hf.txt
            2. Check Python version compatibility (3.8+)
            3. Verify all dependencies are available
            """)
        else:
            logger.error("""
            🚨 Unknown error occurred. For support:
            1. Check the GitHub repository: https://github.com/CalebisGross/thefelix
            2. Create an issue with the full error traceback
            3. Verify your environment meets system requirements
            """)

        raise
    finally:
        logger.info("🌪️ Felix Framework shutdown complete")


# Additional utility functions for HF Spaces integration

def health_check():
    """Health check endpoint for HF Spaces monitoring."""
    try:
        # Quick validation of core components
        helix = HelixGeometry(33.0, 0.001, 100.0, 33)
        helix.get_position_at_t(0.5)

        # Check ZeroGPU availability
        zerogpu_status = "available" if os.getenv("SPACES_ZERO_GPU") == "true" else "unavailable"
        gpu_status = "available" if torch.cuda.is_available() else "unavailable"

        return {
            "status": "healthy",
            "framework": "felix",
            "version": "1.0.0",
            "zerogpu_status": zerogpu_status,
            "gpu_status": gpu_status,
            "components": {
                "helix_geometry": "operational",
                "agents": "operational",
                "communication": "operational",
                "llm_integration": "operational",
                "visualization": "operational"
            },
            "timestamp": datetime.now().isoformat()
        }
    except Exception as e:
        return {
            "status": "unhealthy",
            "error": str(e),
            "timestamp": datetime.now().isoformat()
        }


def get_system_info():
    """Get comprehensive system information for debugging."""
    import platform
    import psutil

    system_info = {
        "platform": platform.platform(),
        "python_version": platform.python_version(),
        "cpu_count": psutil.cpu_count(),
        "memory_total_gb": psutil.virtual_memory().total / (1024**3),
        "memory_available_gb": psutil.virtual_memory().available / (1024**3),
        "environment": {
            "hf_token_available": bool(os.getenv("HF_TOKEN")),
            "space_id": os.getenv("SPACE_ID"),
            "zero_gpu": os.getenv("SPACES_ZERO_GPU", "false"),
            "felix_debug": os.getenv("FELIX_DEBUG", "false"),
            "token_budget": os.getenv("FELIX_TOKEN_BUDGET", "50000")
        },
        "torch_info": {
            "version": torch.__version__ if 'torch' in globals() else "not_available",
            "cuda_available": torch.cuda.is_available() if 'torch' in globals() else False,
            "cuda_device_count": torch.cuda.device_count() if 'torch' in globals() and torch.cuda.is_available() else 0
        },
        "felix_components": {
            "helix_geometry": "available",
            "agents": "available",
            "communication": "available",
            "llm_integration": "available" if os.getenv("HF_TOKEN") else "demo_mode",
            "visualization": "available",
            "zerogpu_optimization": "available" if os.getenv("SPACES_ZERO_GPU") == "true" else "disabled"
        },
        "gradio_info": {
            "version": gr.__version__ if 'gr' in globals() else "not_available",
            "theme": "soft_modern_responsive"
        }
    }

    # Add GPU information if available
    if torch.cuda.is_available():
        system_info["gpu_info"] = {
            "device_count": torch.cuda.device_count(),
            "devices": [
                {
                    "id": i,
                    "name": torch.cuda.get_device_name(i),
                    "memory_total_gb": torch.cuda.get_device_properties(i).total_memory / (1024**3),
                    "memory_allocated_gb": torch.cuda.memory_allocated(i) / (1024**3) if torch.cuda.is_initialized() else 0
                }
                for i in range(torch.cuda.device_count())
            ]
        }

    return system_info


# HuggingFace Spaces specific configuration and optimization
if __name__ == "__main__":
    main()


# Export for potential import and testing
__all__ = [
    'main',
    'create_app',
    'FelixZeroGPUInterface',
    'create_gradio_interface',
    'health_check',
    'get_system_info'
]