Add Perfect Demo Environment for HF Spaces - Complete multi-agent trace with rich analysis and auto-loading system

backend/app.py

@@ -82,6 +82,23 @@ async def startup_event():
         if os.getenv("SPACE_ID"):
             logger.info("🔒 HF Spaces: Using in-memory database for user privacy")
             logger.info("📝 Note: Data will be cleared when container restarts")
+            
+            # Load perfect demo data for HF Spaces
+            try:
+                from backend.database.demo_data_loader import load_demo_trace_for_hf_spaces
+                from backend.database import SessionLocal
+                
+                # Create database session for demo loading
+                with SessionLocal() as demo_session:
+                    demo_loaded = load_demo_trace_for_hf_spaces(demo_session)
+                    if demo_loaded:
+                        logger.info("🎯 Perfect demonstration trace loaded for immediate user experience")
+                    else:
+                        logger.info("⚠️ Demo trace loading skipped - users will start with empty database")
+                        
+            except Exception as demo_error:
+                logger.warning(f"Demo data loading failed (non-critical): {demo_error}")
+                
         else:
             logger.info("💾 Local development: Using persistent database")
             

backend/database/demo_data_loader.py

@@ -0,0 +1,135 @@
+"""
+Demo Data Loader for HF Spaces
+Automatically loads a perfect demonstration trace with rich analysis results
+"""
+
+import os
+import json
+import logging
+from pathlib import Path
+from typing import Dict, Any
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+def load_demo_trace_for_hf_spaces(db_session):
+    """
+    Load demonstration trace data for HF Spaces to provide immediate user experience
+    Only runs in HF Spaces environment with in-memory database
+    """
+    
+    # Only load demo data in HF Spaces environment
+    if not os.getenv("SPACE_ID"):
+        logger.info("Not in HF Spaces environment, skipping demo data loading")
+        return False
+        
+    try:
+        # Get demo trace file path
+        demo_file = Path(__file__).parent.parent.parent / "datasets" / "demo" / "perfect_demo_trace.json"
+        
+        if not demo_file.exists():
+            logger.warning(f"Demo trace file not found at {demo_file}")
+            return False
+            
+        # Load demo trace data
+        with open(demo_file, 'r', encoding='utf-8') as f:
+            demo_data = json.load(f)
+            
+        logger.info("📊 Loading perfect demonstration trace for HF Spaces...")
+        
+        # Import the trace using the existing save_trace utility
+        from backend.database.utils import save_trace
+        
+        # Convert demo data to trace format
+        trace_content = json.dumps(demo_data, indent=2)
+        
+        # Create the trace record
+        trace = save_trace(
+            session=db_session,
+            content=trace_content,
+            filename="perfect_demo_trace.json",
+            title="🚀 Perfect Demo: E-commerce Recommendation System Optimization",
+            description="Complete multi-agent analysis of a failing recommendation system with performance recovery, failure analysis, and optimization strategies. Demonstrates model drift detection, infrastructure scaling, and systematic problem-solving.",
+            trace_type="demo",
+            trace_source="hf_spaces_demo",
+            tags=["demo", "multi-agent", "optimization", "failure-analysis", "e-commerce", "ml-system"]
+        )
+        
+        logger.info(f"✅ Demo trace loaded successfully: {trace.trace_id}")
+        logger.info(f"📈 Title: {trace.title}")
+        logger.info(f"🏷️  Tags: {', '.join(trace.tags) if trace.tags else 'none'}")
+        
+        # Process the trace to generate knowledge graph
+        logger.info("🧠 Generating knowledge graph from demo trace...")
+        
+        try:
+            # Import and use the knowledge graph generation
+            from agentgraph.methods.production.multi_agent_knowledge_extractor import create_knowledge_graph
+            
+            # Extract knowledge graph from the trace
+            kg_result = create_knowledge_graph(trace_content)
+            
+            if kg_result and "final_kg" in kg_result:
+                # Save the knowledge graph
+                from backend.database.utils import save_knowledge_graph
+                
+                kg_record = save_knowledge_graph(
+                    session=db_session,
+                    trace_id=trace.trace_id,
+                    knowledge_graph_data=kg_result["final_kg"],
+                    metadata={
+                        "demo_type": "perfect_example",
+                        "generated_at": datetime.now().isoformat(),
+                        "entities_count": len(kg_result["final_kg"].get("entities", [])),
+                        "relations_count": len(kg_result["final_kg"].get("relations", [])),
+                        "analysis_depth": "comprehensive",
+                        "optimization_identified": True,
+                        "failure_patterns_detected": 3
+                    }
+                )
+                
+                logger.info(f"🎯 Knowledge graph generated successfully: {kg_record.kg_id}")
+                logger.info(f"📊 Entities: {len(kg_result['final_kg'].get('entities', []))}")
+                logger.info(f"🔗 Relations: {len(kg_result['final_kg'].get('relations', []))}")
+                
+            else:
+                logger.warning("Knowledge graph generation returned empty result")
+                
+        except Exception as kg_error:
+            logger.error(f"Failed to generate knowledge graph from demo trace: {kg_error}")
+            # Don't fail the whole demo loading process
+            
+        # Add some summary stats for the UI
+        logger.info("🎉 Perfect demo environment ready!")
+        logger.info("👤 Users will see: Rich trace analysis, failure detection, optimization strategies")
+        logger.info("🔍 Features demonstrated: Multi-agent collaboration, system optimization, performance recovery")
+        
+        return True
+        
+    except FileNotFoundError:
+        logger.error(f"Demo trace file not found: {demo_file}")
+        return False
+    except json.JSONDecodeError as e:
+        logger.error(f"Invalid JSON in demo trace file: {e}")
+        return False
+    except Exception as e:
+        logger.error(f"Failed to load demo trace: {e}")
+        return False
+
+
+def get_demo_stats():
+    """Get statistics about the loaded demo data for display"""
+    return {
+        "demo_loaded": True,
+        "trace_title": "Perfect Demo: E-commerce Recommendation System Optimization", 
+        "agent_count": 4,
+        "optimization_steps": 8,
+        "failures_analyzed": 3,
+        "performance_improvements": {
+            "model_accuracy": "+18%",
+            "inference_latency": "-39%", 
+            "system_cpu": "-35%",
+            "cache_hit_rate": "+48%"
+        },
+        "business_impact": "$1.8-2.1M monthly revenue recovery"
+    }

datasets/demo/perfect_demo_trace.json

@@ -0,0 +1,288 @@
+{
+  "trace_metadata": {
+    "trace_id": "demo_trace_001",
+    "task": "Analyze and optimize a failing e-commerce recommendation system",
+    "timestamp": "2024-08-31T12:00:00Z",
+    "duration": "18.5 minutes",
+    "total_agents": 4,
+    "total_tool_calls": 12,
+    "status": "completed_with_optimizations"
+  },
+  "agent_interactions": [
+    {
+      "step": 1,
+      "timestamp": "2024-08-31T12:00:00Z",
+      "agent": "TaskPlanner",
+      "role": "system",
+      "content": "Received task: Analyze failing e-commerce recommendation system with 23% CTR drop. Planning multi-agent approach with Data Analyst, ML Engineer, and System Optimizer.",
+      "reasoning": "Complex system analysis requires specialized agents for data investigation, model evaluation, and system optimization.",
+      "next_agents": ["DataAnalyst", "MLEngineer"]
+    },
+    {
+      "step": 2,
+      "timestamp": "2024-08-31T12:01:30Z",
+      "agent": "DataAnalyst",
+      "role": "assistant",
+      "content": "Analyzing recommendation system performance data. Checking user interaction patterns, conversion rates, and system metrics.",
+      "tool_calls": [
+        {
+          "tool": "database_query",
+          "input": "SELECT user_id, item_id, click_through_rate, conversion_rate FROM recommendations WHERE date >= '2024-08-01'",
+          "output": "Retrieved 45,892 recommendation records. Average CTR: 23.1% (down from 46.3%). Conversion rate: 3.2% (down from 7.8%)",
+          "success": true
+        }
+      ],
+      "findings": [
+        "CTR dropped significantly starting August 15th",
+        "Most affected category: Electronics (67% CTR drop)",
+        "Peak failure times: 2-4 PM and 8-10 PM (high traffic periods)"
+      ],
+      "reasoning": "Data shows clear performance degradation pattern. Need to investigate model and infrastructure causes."
+    },
+    {
+      "step": 3,
+      "timestamp": "2024-08-31T12:04:15Z",
+      "agent": "MLEngineer",
+      "role": "assistant", 
+      "content": "Evaluating recommendation model performance and feature engineering pipeline.",
+      "tool_calls": [
+        {
+          "tool": "model_evaluation",
+          "input": "Evaluate current recommendation model accuracy and latency",
+          "output": "Model accuracy: 0.73 (down from 0.89). Average inference time: 145ms (up from 67ms)",
+          "success": true
+        },
+        {
+          "tool": "feature_analysis",
+          "input": "Analyze feature drift and data quality issues",
+          "output": "ERROR: Feature pipeline timeout. 23% of features showing null values. Embedding service responding slowly.",
+          "success": false,
+          "error": "Feature pipeline instability detected"
+        }
+      ],
+      "findings": [
+        "Model accuracy degraded by 18%",
+        "Inference latency increased 2.2x",
+        "Feature pipeline showing instability",
+        "Embedding service bottleneck identified"
+      ],
+      "reasoning": "Performance issues stem from both model degradation and infrastructure problems. Need system optimization.",
+      "escalation": "SystemOptimizer",
+      "priority": "high"
+    },
+    {
+      "step": 4,
+      "timestamp": "2024-08-31T12:07:45Z",
+      "agent": "SystemOptimizer",
+      "role": "assistant",
+      "content": "Investigating system architecture and infrastructure bottlenecks affecting recommendation performance.",
+      "tool_calls": [
+        {
+          "tool": "system_monitoring",
+          "input": "Check CPU, memory, and network utilization for recommendation services",
+          "output": "CPU: 87% avg (recommendation service), Memory: 92% (embedding cache), Network: 340ms avg latency to ML models",
+          "success": true
+        },
+        {
+          "tool": "database_performance",
+          "input": "Analyze database query performance and connection pools",
+          "output": "Average query time: 890ms (up 4x). Connection pool: 98% utilization. 12 slow queries identified.",
+          "success": true
+        },
+        {
+          "tool": "caching_analysis",
+          "input": "Evaluate recommendation cache hit rates and invalidation patterns", 
+          "output": "Cache hit rate: 34% (down from 78%). Cache invalidation frequency: 340% increase due to model updates",
+          "success": true
+        }
+      ],
+      "findings": [
+        "Recommendation service under severe load (87% CPU)",
+        "Embedding cache nearly full (92% memory usage)",
+        "Database queries 4x slower than baseline", 
+        "Cache hit rate dropped from 78% to 34%",
+        "Frequent cache invalidations due to model update strategy"
+      ],
+      "reasoning": "System bottlenecks are cascading - high memory usage affects caching, slow queries increase CPU load, poor cache performance increases database pressure."
+    },
+    {
+      "step": 5,
+      "timestamp": "2024-08-31T12:12:20Z",
+      "agent": "TaskPlanner",
+      "role": "system",
+      "content": "Synthesizing findings from all agents. Root causes identified: model drift, infrastructure overload, and cache inefficiency.",
+      "synthesis": {
+        "root_causes": [
+          "Model performance degraded due to data drift and feature pipeline issues",
+          "Infrastructure cannot handle current load with increased latency",
+          "Cache strategy inefficient due to frequent model updates"
+        ],
+        "impact_analysis": {
+          "business_impact": "23% CTR drop = ~$2.3M monthly revenue loss",
+          "user_experience": "Poor recommendations leading to decreased engagement",
+          "system_stability": "High resource utilization risking system failures"
+        }
+      }
+    },
+    {
+      "step": 6,
+      "timestamp": "2024-08-31T12:14:00Z",
+      "agent": "MLEngineer",
+      "role": "assistant",
+      "content": "Proposing model optimization strategy based on identified issues.",
+      "optimization_plan": {
+        "immediate_fixes": [
+          "Retrain model with recent data to address drift",
+          "Optimize feature pipeline to reduce null values",
+          "Implement model compression to reduce inference time"
+        ],
+        "tool_calls": [
+          {
+            "tool": "model_retraining",
+            "input": "Retrain recommendation model with last 30 days of clean data",
+            "output": "New model accuracy: 0.86 (+13%). Inference time: 89ms (-39%)",
+            "success": true
+          }
+        ]
+      },
+      "expected_improvements": {
+        "accuracy": "+13% (from 0.73 to 0.86)",
+        "latency": "-39% (from 145ms to 89ms)", 
+        "CTR_projection": "+15-20% improvement expected"
+      }
+    },
+    {
+      "step": 7,
+      "timestamp": "2024-08-31T12:16:30Z",
+      "agent": "SystemOptimizer", 
+      "role": "assistant",
+      "content": "Implementing infrastructure optimizations to support improved model performance.",
+      "optimization_actions": [
+        {
+          "action": "Scale embedding cache cluster",
+          "tool_calls": [
+            {
+              "tool": "infrastructure_scaling",
+              "input": "Add 2 cache nodes and optimize memory allocation",
+              "output": "Cache cluster scaled. Memory utilization: 67% (-25%). Hit rate projected: 82%",
+              "success": true
+            }
+          ]
+        },
+        {
+          "action": "Optimize database queries",
+          "tool_calls": [
+            {
+              "tool": "query_optimization", 
+              "input": "Add indexes and optimize slow query patterns",
+              "output": "12 queries optimized. Average query time: 210ms (-76%)",
+              "success": true
+            }
+          ]
+        },
+        {
+          "action": "Implement smart cache invalidation",
+          "details": "Reduced invalidation frequency by 60% using incremental updates"
+        }
+      ],
+      "performance_gains": {
+        "cpu_utilization": "-35% (from 87% to 57%)",
+        "query_performance": "-76% latency improvement",
+        "cache_hit_rate": "+48% (from 34% to 82%)"
+      }
+    },
+    {
+      "step": 8,
+      "timestamp": "2024-08-31T12:18:30Z",
+      "agent": "TaskPlanner",
+      "role": "system",
+      "content": "Final optimization results and monitoring recommendations.",
+      "final_results": {
+        "performance_improvements": {
+          "model_accuracy": "0.86 (+18% from degraded state)",
+          "inference_latency": "89ms (-39% improvement)",
+          "system_cpu": "57% (-35% improvement)", 
+          "cache_hit_rate": "82% (+48% improvement)",
+          "projected_ctr": "38-42% (+15-19% improvement)"
+        },
+        "business_impact": {
+          "estimated_revenue_recovery": "$1.8-2.1M monthly",
+          "user_experience_score": "+25% improvement expected",
+          "system_reliability": "High load handling capacity restored"
+        },
+        "monitoring_recommendations": [
+          "Set up alerts for model accuracy below 0.80",
+          "Monitor cache hit rate - alert if below 75%",
+          "Track feature pipeline health continuously",
+          "Implement gradual model rollback capability"
+        ],
+        "failure_prevention": [
+          "Automated model performance monitoring",
+          "Infrastructure auto-scaling triggers",
+          "Feature pipeline redundancy",
+          "A/B testing framework for safe model updates"
+        ]
+      }
+    }
+  ],
+  "failure_analysis": {
+    "identified_failures": [
+      {
+        "type": "model_drift",
+        "severity": "high",
+        "impact": "18% accuracy loss",
+        "root_cause": "Training data staleness and feature pipeline degradation",
+        "prevention": "Automated retraining triggers and feature monitoring"
+      },
+      {
+        "type": "infrastructure_bottleneck", 
+        "severity": "critical",
+        "impact": "2.2x latency increase",
+        "root_cause": "Insufficient cache capacity and database optimization",
+        "prevention": "Auto-scaling policies and performance monitoring"
+      },
+      {
+        "type": "tool_failure",
+        "severity": "medium", 
+        "impact": "Feature analysis timeout in step 3",
+        "root_cause": "Feature pipeline instability under load",
+        "prevention": "Pipeline redundancy and timeout handling"
+      }
+    ],
+    "optimization_opportunities": [
+      {
+        "area": "model_deployment",
+        "opportunity": "Implement blue-green deployment for safer model updates",
+        "potential_impact": "Zero-downtime updates, reduced risk of performance degradation"
+      },
+      {
+        "area": "caching_strategy",
+        "opportunity": "Machine learning-based cache pre-warming",
+        "potential_impact": "90%+ cache hit rate, 50% further latency reduction"
+      },
+      {
+        "area": "monitoring",
+        "opportunity": "Predictive performance alerting using ML",
+        "potential_impact": "Prevent issues before they impact users"
+      }
+    ]
+  },
+  "knowledge_extraction": {
+    "key_entities": [
+      "RecommendationSystem", "MLModel", "DataPipeline", "CacheCluster", 
+      "DatabaseQuery", "UserEngagement", "SystemPerformance", "ModelAccuracy"
+    ],
+    "critical_relationships": [
+      "ModelDrift -> PerformanceDegradation",
+      "InfrastructureBottleneck -> LatencyIncrease", 
+      "CacheInvalidation -> DatabaseLoad",
+      "ModelOptimization -> AccuracyImprovement",
+      "SystemScaling -> PerformanceRecovery"
+    ],
+    "success_patterns": [
+      "MultiAgentCollaboration -> ComprehensiveAnalysis",
+      "DataDrivenOptimization -> MeasurableImprovements",
+      "InfrastructureScaling -> SystemStability"
+    ]
+  }
+}

frontend/src/components/features/workspace/DashboardView.tsx

@@ -4,6 +4,7 @@ import { DashboardVisualization } from "../dashboard/DashboardVisualization";
 import { EntityRelationAnalysisModal } from "../dashboard/modals/EntityRelationAnalysisModal";
 import { TinyTrendChart } from "@/components/shared/TinyTrendChart";
 import { EntityRelationTreeChart } from "@/components/shared/EntityRelationTreeChart";
+import { DemoBanner } from "@/components/shared/DemoBanner";
 import {
   generateTrendData,
   calculateFailureCount,
@@ -76,6 +77,9 @@ export function DashboardView() {
 
       {/* Content with relative positioning */}
       <div className="relative z-10 flex flex-col gap-6 h-full">
+        {/* Demo Banner for HF Spaces */}
+        <DemoBanner />
+        
         {/* Error State */}
         {error && (
           <Card className="border-destructive/50 bg-destructive/10">

frontend/src/components/shared/DemoBanner.tsx

@@ -0,0 +1,113 @@
+import React from "react";
+import { Card, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { 
+  Sparkles, 
+  TrendingUp, 
+  Zap, 
+  Target, 
+  ArrowRight,
+  Users,
+  BarChart3
+} from "lucide-react";
+import { useAgentGraph } from "@/context/AgentGraphContext";
+import { IS_HF_SPACES } from "@/lib/config";
+
+export function DemoBanner() {
+  const { actions } = useAgentGraph();
+
+  // Only show on HF Spaces
+  if (!IS_HF_SPACES) {
+    return null;
+  }
+
+  const handleExploreDemo = () => {
+    // Navigate to traces view to show the loaded demo trace
+    actions.setActiveView("traces");
+  };
+
+  return (
+    <Card className="border-2 border-blue-200 bg-gradient-to-r from-blue-50 to-indigo-50 mb-6">
+      <CardContent className="p-6">
+        <div className="flex items-start justify-between">
+          <div className="flex-1">
+            {/* Header */}
+            <div className="flex items-center gap-2 mb-3">
+              <Sparkles className="h-5 w-5 text-blue-600" />
+              <h3 className="text-lg font-semibold text-blue-900">
+                🚀 Perfect Demo Environment Ready
+              </h3>
+              <Badge variant="secondary" className="bg-blue-100 text-blue-700">
+                Pre-loaded Demo
+              </Badge>
+            </div>
+
+            {/* Description */}
+            <p className="text-gray-700 mb-4 leading-relaxed">
+              Explore a complete <strong>multi-agent system analysis</strong> of a failing e-commerce 
+              recommendation system. See how AI agents collaborate to identify problems, 
+              implement optimizations, and recover system performance.
+            </p>
+
+            {/* Key Features Grid */}
+            <div className="grid grid-cols-2 md:grid-cols-4 gap-4 mb-4">
+              <div className="flex items-center gap-2 text-sm text-gray-600">
+                <Users className="h-4 w-4 text-blue-500" />
+                <span>4 AI Agents</span>
+              </div>
+              <div className="flex items-center gap-2 text-sm text-gray-600">
+                <Target className="h-4 w-4 text-green-500" />
+                <span>3 Failures Analyzed</span>
+              </div>
+              <div className="flex items-center gap-2 text-sm text-gray-600">
+                <TrendingUp className="h-4 w-4 text-orange-500" />
+                <span>Performance +39%</span>
+              </div>
+              <div className="flex items-center gap-2 text-sm text-gray-600">
+                <BarChart3 className="h-4 w-4 text-purple-500" />
+                <span>$2.1M Recovery</span>
+              </div>
+            </div>
+
+            {/* Highlights */}
+            <div className="flex flex-wrap gap-2 mb-4">
+              <Badge variant="outline" className="border-green-200 text-green-700 bg-green-50">
+                <Zap className="h-3 w-3 mr-1" />
+                Model Optimization
+              </Badge>
+              <Badge variant="outline" className="border-orange-200 text-orange-700 bg-orange-50">
+                <TrendingUp className="h-3 w-3 mr-1" />
+                System Scaling
+              </Badge>
+              <Badge variant="outline" className="border-purple-200 text-purple-700 bg-purple-50">
+                <Target className="h-3 w-3 mr-1" />
+                Failure Recovery
+              </Badge>
+            </div>
+          </div>
+
+          {/* Action Button */}
+          <div className="ml-4 flex-shrink-0">
+            <Button 
+              onClick={handleExploreDemo}
+              className="bg-blue-600 hover:bg-blue-700 text-white shadow-md"
+            >
+              Explore Demo
+              <ArrowRight className="h-4 w-4 ml-2" />
+            </Button>
+          </div>
+        </div>
+
+        {/* Bottom note */}
+        <div className="mt-4 pt-4 border-t border-blue-200">
+          <p className="text-xs text-blue-600 flex items-center gap-1">
+            <Sparkles className="h-3 w-3" />
+            This demonstration shows AgentGraph's complete analysis capabilities. 
+            Upload your own traces to analyze real AI agent interactions!
+          </p>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

frontend/src/components/shared/modals/PrivacyNoticeModal.tsx

@@ -19,7 +19,7 @@ export function PrivacyNoticeModal() {
   useEffect(() => {
     // Only show on HF Spaces and if not seen before
     if (!IS_HF_SPACES) return;
-    
+
     const hasSeenNotice = localStorage.getItem(PRIVACY_NOTICE_KEY);
     if (hasSeenNotice) return;