Upload 34 files

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+car_manual/Function[[:space:]]of[[:space:]]Active[[:space:]]Distance[[:space:]]Assist[[:space:]]DISTRONIC.pdf filter=lfs diff=lfs merge=lfs -text
+car_manual/Function[[:space:]]of[[:space:]]Active[[:space:]]Lane[[:space:]]Change[[:space:]]Assist.pdf filter=lfs diff=lfs merge=lfs -text
+car_manual/Function[[:space:]]of[[:space:]]Active[[:space:]]Steering[[:space:]]Assist.pdf filter=lfs diff=lfs merge=lfs -text
+car_manual/Function[[:space:]]of[[:space:]]Active[[:space:]]Stop-and-Go[[:space:]]Assist.pdf filter=lfs diff=lfs merge=lfs -text

car_manual/Function of Active Distance Assist DISTRONIC.pdf

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

car_manual/Function of Active Lane Change Assist.pdf

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

car_manual/Function of Active Steering Assist.pdf

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

car_manual/Function of Active Stop-and-Go Assist.pdf

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

config/vector_store_config.json

@@ -0,0 +1,6 @@
+{
+  "id": "vs_69022a9edd74819199bf9a34a83e877b",
+  "name": "mercedes_manual_store_local",
+  "created_at": 1761749663,
+  "file_count": 0
+}

modules/cold_start_onboarding.py

@@ -0,0 +1,186 @@
+"""
+Cold start onboarding module
+Used to collect initial information from new users
+"""
+
+import gradio as gr
+from typing import Dict, List
+try:
+    from modules.personalized_learning import UserProfilingSystem
+except ImportError:
+    # Fallback for direct import
+    from personalized_learning import UserProfilingSystem
+
+def create_onboarding_interface(user_profiling: UserProfilingSystem, available_topics: List[str]):
+    """Create cold start onboarding interface"""
+    
+    def process_onboarding(user_id: str, background: str, learning_style: str, 
+                          learning_pace: str, learning_goals: List[str],
+                          knowledge_survey: Dict[str, float]) -> Dict:
+        """Process cold start data collection"""
+        
+        # Build onboarding data
+        onboarding_data = {
+            'learning_style': learning_style,
+            'learning_pace': learning_pace,
+            'background_experience': background,
+            'learning_goals': learning_goals if learning_goals else [],
+            'initial_knowledge_survey': knowledge_survey,
+            'initial_assessment_completed': True
+        }
+        
+        # Complete cold start setup
+        profile = user_profiling.complete_onboarding(user_id, onboarding_data)
+        
+        return {
+            "status": "success",
+            "message": f"Onboarding completed for {user_id}",
+            "profile_summary": user_profiling.get_profile_summary(user_id)
+        }
+    
+    def create_onboarding_form():
+        """Create cold start form"""
+        with gr.Blocks(title="Welcome! Let's Get Started") as onboarding:
+            gr.Markdown("# 🎯 Welcome to Personalized Learning!")
+            gr.Markdown("We need some information to create your personalized learning path.")
+            
+            with gr.Row():
+                user_id_input = gr.Textbox(
+                    label="User ID",
+                    placeholder="Enter your user ID",
+                    value="new_user"
+                )
+            
+            with gr.Accordion("📋 Step 1: Background Information", open=True):
+                background_input = gr.Radio(
+                    label="What's your experience with ADAS systems?",
+                    choices=[
+                        ("Beginner - I'm new to ADAS systems", "beginner"),
+                        ("Intermediate - I know some basics", "intermediate"),
+                        ("Experienced - I have good knowledge", "experienced")
+                    ],
+                    value="beginner"
+                )
+            
+            with gr.Accordion("🎨 Step 2: Learning Preferences", open=True):
+                learning_style_input = gr.Radio(
+                    label="How do you prefer to learn?",
+                    choices=[
+                        ("Visual - I like diagrams and illustrations", "visual"),
+                        ("Textual - I prefer reading and explanations", "textual"),
+                        ("Practical - I learn by doing", "practical"),
+                        ("Mixed - I like a combination", "mixed")
+                    ],
+                    value="mixed"
+                )
+                
+                learning_pace_input = gr.Radio(
+                    label="What's your preferred learning pace?",
+                    choices=[
+                        ("Slow - I like to take my time", "slow"),
+                        ("Medium - Normal pace is fine", "medium"),
+                        ("Fast - I want to learn quickly", "fast")
+                    ],
+                    value="medium"
+                )
+            
+            with gr.Accordion("🎯 Step 3: Learning Goals", open=True):
+                learning_goals_input = gr.CheckboxGroup(
+                    label="What are your learning goals? (Select all that apply)",
+                    choices=[
+                        "Understand basic ADAS functions",
+                        "Learn how to operate ADAS features",
+                        "Master advanced ADAS capabilities",
+                        "Troubleshoot ADAS issues",
+                        "Prepare for certification",
+                        "General knowledge improvement"
+                    ],
+                    value=["Understand basic ADAS functions"]
+                )
+            
+            with gr.Accordion("📊 Step 4: Initial Knowledge Assessment", open=True):
+                gr.Markdown("Rate your familiarity with each topic (0 = No knowledge, 1 = Expert)")
+                
+                knowledge_sliders = {}
+                for topic in available_topics:
+                    # Simplify topic name for display
+                    display_name = topic.replace("Function of ", "").replace(" Assist", "")
+                    knowledge_sliders[topic] = gr.Slider(
+                        label=display_name,
+                        minimum=0.0,
+                        maximum=1.0,
+                        value=0.0,
+                        step=0.1
+                    )
+            
+            with gr.Row():
+                submit_btn = gr.Button("Complete Setup", variant="primary")
+            
+            output_result = gr.JSON(label="Setup Result")
+            
+            def submit_onboarding(user_id: str, background: str, learning_style: str,
+                                 learning_pace: str, learning_goals: List[str],
+                                 **knowledge_values):
+                """Submit cold start data"""
+                # Build knowledge survey dictionary
+                knowledge_survey = {}
+                for topic in available_topics:
+                    knowledge_survey[topic] = knowledge_values.get(topic, 0.0)
+                
+                # Process background selection (extract value from tuple)
+                if isinstance(background, tuple):
+                    background = background[1] if len(background) > 1 else background[0]
+                
+                if isinstance(learning_style, tuple):
+                    learning_style = learning_style[1] if len(learning_style) > 1 else learning_style[0]
+                
+                if isinstance(learning_pace, tuple):
+                    learning_pace = learning_pace[1] if len(learning_pace) > 1 else learning_pace[0]
+                
+                result = process_onboarding(
+                    user_id, background, learning_style, learning_pace,
+                    learning_goals, knowledge_survey
+                )
+                return result
+            
+            # Build input list
+            inputs = [user_id_input, background_input, learning_style_input, 
+                     learning_pace_input, learning_goals_input] + list(knowledge_sliders.values())
+            
+            submit_btn.click(
+                submit_onboarding,
+                inputs=inputs,
+                outputs=output_result
+            )
+        
+        return onboarding
+    
+    return create_onboarding_form()
+
+
+def check_and_show_onboarding(user_profiling: UserProfilingSystem, user_id: str) -> bool:
+    """Check if cold start interface needs to be shown"""
+    return user_profiling.is_cold_start(user_id)
+
+
+def get_onboarding_data_summary(user_profiling: UserProfilingSystem, user_id: str) -> Dict:
+    """Get summary of data collected during cold start"""
+    if user_profiling.is_cold_start(user_id):
+        return {
+            "status": "cold_start",
+            "message": "User has not completed onboarding"
+        }
+    
+    profile = user_profiling.get_or_create_profile(user_id)
+    
+    return {
+        "status": "completed",
+        "has_completed_onboarding": profile.has_completed_onboarding,
+        "background_experience": profile.background_experience,
+        "learning_style": profile.learning_style,
+        "learning_pace": profile.learning_pace,
+        "learning_goals": profile.learning_goals if profile.learning_goals else [],
+        "initial_knowledge_survey": profile.initial_knowledge_survey if profile.initial_knowledge_survey else {},
+        "initial_assessment_completed": profile.initial_assessment_completed
+    }
+

modules/integrate_personalized_learning.py

@@ -0,0 +1,326 @@
+"""
+Integrate personalized learning pathway functionality into Gradio interface
+"""
+
+import gradio as gr
+import json
+from datetime import datetime
+from personalized_learning import (
+    UserProfilingSystem, 
+    LearningPathGenerator, 
+    AdaptiveLearningEngine
+)
+
+# Initialize system components
+def initialize_personalized_learning(available_topics: list, client):
+    """Initialize personalized learning system"""
+    user_profiling = UserProfilingSystem()
+    learning_path_generator = LearningPathGenerator(user_profiling, available_topics)
+    adaptive_engine = AdaptiveLearningEngine(user_profiling, learning_path_generator)
+    
+    return user_profiling, learning_path_generator, adaptive_engine
+
+# Create personalized learning path tab
+def create_personalized_learning_tab(adaptive_engine, user_profiling, query_rag_model, 
+                                     generate_multiple_choice_questions, client):
+    """Create personalized learning path tab"""
+    
+    with gr.TabItem("Personalized Learning Path"):
+        gr.Markdown("## 🎯 Your Personalized Learning Journey")
+        gr.Markdown("Get a customized learning path based on your knowledge profile and performance.")
+        
+        # User ID input
+        with gr.Row():
+            user_id_input = gr.Textbox(
+                label="User ID",
+                placeholder="Enter your user ID (e.g., user_001)",
+                value="default_user"
+            )
+            load_profile_btn = gr.Button("Load My Profile")
+        
+        # User profile display
+        with gr.Column(visible=False) as profile_container:
+            profile_summary = gr.Markdown()
+            
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### 📊 Knowledge Profile")
+                    knowledge_level_display = gr.JSON()
+                
+                with gr.Column():
+                    gr.Markdown("### 📈 Learning Statistics")
+                    learning_stats = gr.JSON()
+        
+        # Learning path section
+        with gr.Row():
+            focus_areas_input = gr.CheckboxGroup(
+                label="Focus Areas (Optional)",
+                choices=[],
+                value=[],
+                interactive=True
+            )
+            generate_path_btn = gr.Button("Generate Learning Path", variant="primary")
+        
+        # Learning path visualization
+        with gr.Column(visible=False) as path_container:
+            gr.Markdown("### 🗺️ Your Learning Path")
+            
+            path_progress = gr.HTML()
+            path_visualization = gr.HTML()
+            
+            # Current node information
+            with gr.Row():
+                with gr.Column():
+                    current_node_info = gr.Markdown()
+                with gr.Column():
+                    next_action_btn = gr.Button("Start This Node", variant="primary")
+                    skip_node_btn = gr.Button("Skip This Node")
+            
+            # Recommendations section
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### 💡 Recommendations")
+                    recommendations_display = gr.JSON()
+        
+        # Learning activity history
+        with gr.Column(visible=False) as history_container:
+            gr.Markdown("### 📚 Learning History")
+            learning_history = gr.Dataframe(
+                headers=["Date", "Topic", "Activity", "Score"],
+                interactive=False
+            )
+        
+        # Handler functions
+        def load_user_profile(user_id):
+            """Load user profile"""
+            if not user_id:
+                return (
+                    gr.update(visible=False),  # profile_container
+                    "",  # profile_summary
+                    {},  # knowledge_level_display
+                    {},  # learning_stats
+                    [],  # focus_areas_input choices
+                    gr.update(visible=False)  # path_container
+                )
+            
+            profile = user_profiling.get_or_create_profile(user_id)
+            summary = user_profiling.get_profile_summary(user_id)
+            
+            # Generate summary text
+            summary_text = f"""
+### 👤 User Profile: {user_id}
+
+**Learning Style:** {summary['learning_style'].title()}  
+**Learning Pace:** {summary['learning_pace'].title()}  
+**Overall Progress:** {summary['overall_progress']:.1%}  
+**Total Questions Asked:** {summary['total_questions']}  
+**Total Tests Completed:** {summary['total_tests']}
+
+**Strong Areas:** {', '.join(summary['strong_areas']) if summary['strong_areas'] else 'None yet'}  
+**Areas Needing Improvement:** {', '.join(summary['weak_areas']) if summary['weak_areas'] else 'None yet'}
+"""
+            
+            # Prepare knowledge level data
+            knowledge_data = summary['knowledge_level']
+            if not knowledge_data:
+                knowledge_data = {"No topics learned yet": 0.0}
+            
+            # Prepare statistics data
+            stats_data = {
+                "Total Questions": summary['total_questions'],
+                "Total Tests": summary['total_tests'],
+                "Preferred Topics": summary['preferred_topics'][:5] if summary['preferred_topics'] else [],
+                "Overall Progress": f"{summary['overall_progress']:.1%}"
+            }
+            
+            # Update focus areas options
+            all_topics = list(set(list(knowledge_data.keys()) + 
+                                 summary['preferred_topics'] + 
+                                 summary['weak_areas']))
+            
+            return (
+                gr.update(visible=True),
+                summary_text,
+                knowledge_data,
+                stats_data,
+                all_topics,
+                gr.update(visible=False)
+            )
+        
+        def generate_learning_path(user_id, focus_areas):
+            """Generate learning path"""
+            if not user_id:
+                return (
+                    gr.update(visible=False),
+                    "",
+                    "",
+                    "",
+                    {},
+                    gr.update(visible=False)
+                )
+            
+            path = adaptive_engine.create_or_update_path(user_id, focus_areas if focus_areas else None)
+            
+            # Generate path visualization HTML
+            vis_data = adaptive_engine.get_path_visualization_data(user_id)
+            
+            # Create progress bar
+            progress_html = f"""
+            <div style="width:100%; background-color:#f0f0f0; border-radius:5px; overflow:hidden; margin:20px 0;">
+                <div style="width:{path.completion_percentage*100}%; background-color:#4CAF50; height:30px; border-radius:5px; display:flex; align-items:center; justify-content:center; color:white; font-weight:bold;">
+                    {path.completion_percentage*100:.1f}% Complete
+                </div>
+            </div>
+            <p><strong>Total Nodes:</strong> {len(path.nodes)} | <strong>Completed:</strong> {sum(1 for n in path.nodes if n.status == 'completed')} | <strong>Estimated Time:</strong> {path.estimated_total_time} minutes</p>
+            """
+            
+            # Create path visualization
+            path_html = "<div style='margin:20px 0;'>"
+            path_html += "<h4>Learning Path Structure:</h4>"
+            path_html += "<div style='display:flex; flex-direction:column; gap:10px;'>"
+            
+            for i, node in enumerate(path.nodes):
+                status_color = {
+                    "completed": "#4CAF50",
+                    "in_progress": "#2196F3",
+                    "pending": "#9E9E9E",
+                    "skipped": "#FF9800"
+                }.get(node.status, "#9E9E9E")
+                
+                is_current = i == path.current_node_index
+                highlight = "border: 3px solid #FF5722; padding: 10px;" if is_current else "padding: 10px;"
+                
+                path_html += f"""
+                <div style='{highlight} background-color:white; border-left: 5px solid {status_color}; border-radius:5px; margin:5px 0;'>
+                    <div style='display:flex; justify-content:space-between; align-items:center;'>
+                        <div>
+                            <strong>{node.topic}</strong> - {node.bloom_level.title()} ({node.content_type})
+                            <br>
+                            <small>Difficulty: {node.difficulty:.2f} | Time: {node.estimated_time} min</small>
+                        </div>
+                        <div style='color:{status_color}; font-weight:bold;'>
+                            {node.status.title()}
+                        </div>
+                    </div>
+                </div>
+                """
+            
+            path_html += "</div></div>"
+            
+            # Current node information
+            if path.current_node_index < len(path.nodes):
+                current_node = path.nodes[path.current_node_index]
+                current_node_info = f"""
+### Current Learning Node
+
+**Topic:** {current_node.topic}  
+**Bloom Level:** {current_node.bloom_level.title()}  
+**Content Type:** {current_node.content_type.title()}  
+**Difficulty:** {current_node.difficulty:.2f}  
+**Estimated Time:** {current_node.estimated_time} minutes
+
+**Status:** {current_node.status.title()}
+"""
+            else:
+                current_node_info = "### Learning Path Complete! 🎉"
+            
+            # Get recommendations
+            recommendations = adaptive_engine.get_recommendations(user_id)
+            
+            return (
+                gr.update(visible=True),
+                progress_html,
+                path_html,
+                current_node_info,
+                recommendations,
+                gr.update(visible=True)
+            )
+        
+        def start_current_node(user_id):
+            """Start current node"""
+            path = adaptive_engine.get_active_path(user_id)
+            if not path or path.current_node_index >= len(path.nodes):
+                return "No active node to start."
+            
+            current_node = path.nodes[path.current_node_index]
+            return f"Starting learning node: {current_node.topic} - {current_node.bloom_level}"
+        
+        # Bind events
+        load_profile_btn.click(
+            load_user_profile,
+            inputs=[user_id_input],
+            outputs=[profile_container, profile_summary, knowledge_level_display, 
+                    learning_stats, focus_areas_input, path_container]
+        )
+        
+        generate_path_btn.click(
+            generate_learning_path,
+            inputs=[user_id_input, focus_areas_input],
+            outputs=[path_container, path_progress, path_visualization, 
+                    current_node_info, recommendations_display, history_container]
+        )
+        
+        next_action_btn.click(
+            start_current_node,
+            inputs=[user_id_input],
+            outputs=[]
+        )
+        
+        # Auto-load default user
+        user_id_input.change(
+            load_user_profile,
+            inputs=[user_id_input],
+            outputs=[profile_container, profile_summary, knowledge_level_display, 
+                    learning_stats, focus_areas_input, path_container]
+        )
+    
+    return {
+        "adaptive_engine": adaptive_engine,
+        "user_profiling": user_profiling
+    }
+
+# Integrate with existing testing functionality
+def integrate_with_testing(adaptive_engine, user_profiling, test_results, user_id):
+    """Integrate test results into personalized learning system"""
+    if not user_id or not test_results:
+        return
+    
+    # Extract topic from test results (assuming test results contain topic information)
+    topic = test_results[0].get('topic', 'unknown') if test_results else 'unknown'
+    
+    # Update user profile
+    profile = user_profiling.update_from_test_results(user_id, topic, test_results)
+    
+    # Update learning path
+    path = adaptive_engine.get_active_path(user_id)
+    if path:
+        # Calculate average score
+        scores = [1.0 if r.get('is_correct', False) else 0.0 for r in test_results]
+        avg_score = sum(scores) / len(scores) if scores else 0.5
+        
+        # Find corresponding node and mark as completed
+        for node in path.nodes:
+            if node.topic == topic and node.status == "in_progress":
+                adaptive_engine.complete_node(user_id, node.node_id, avg_score)
+                break
+
+# Integrate with Q&A functionality
+def integrate_with_qa(user_profiling, user_id, question):
+    """Integrate Q&A history into personalized learning system"""
+    if not user_id or not question:
+        return
+    
+    # Simple topic extraction (can be improved based on actual needs)
+    topic = None
+    if "distronic" in question.lower() or "distance" in question.lower():
+        topic = "DISTRONIC"
+    elif "lane" in question.lower():
+        topic = "Lane Change Assist"
+    elif "steering" in question.lower():
+        topic = "Steering Assist"
+    elif "stop" in question.lower() or "go" in question.lower():
+        topic = "Stop-and-Go Assist"
+    
+    # Update user profile
+    user_profiling.update_from_question(user_id, question, topic)
+

modules/personalized_learning.py

@@ -0,0 +1,794 @@
+"""
+Personalized Learning Pathway System
+Implements adaptive learning capabilities that customize instruction based on comprehensive user profiling
+"""
+
+import json
+import os
+import pandas as pd
+import numpy as np
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Tuple
+from dataclasses import dataclass, asdict
+from collections import defaultdict
+import pickle
+
+@dataclass
+class UserProfile:
+    """User profile data structure"""
+    user_id: str
+    knowledge_level: Dict[str, float]  # Knowledge level for each topic (0-1)
+    learning_style: str  # "visual", "textual", "practical", "mixed"
+    learning_pace: str  # "slow", "medium", "fast"
+    preferred_topics: List[str]
+    weak_areas: List[str]
+    strong_areas: List[str]
+    test_scores: Dict[str, List[float]]  # Historical test scores
+    question_history: List[Dict]  # Question and answer history
+    learning_time: Dict[str, float]  # Learning time for each topic (minutes)
+    last_activity: str
+    total_questions_asked: int
+    total_tests_completed: int
+    bloom_level_performance: Dict[str, Dict[str, float]]  # Bloom level performance for each topic
+    created_at: str
+    updated_at: str
+    # Cold start related fields
+    has_completed_onboarding: bool = False  # Whether onboarding is completed
+    background_experience: str = ""  # Background experience (e.g., "experienced", "beginner", "intermediate")
+    learning_goals: List[str] = None  # Learning goals, None requires special handling
+    initial_assessment_completed: bool = False  # Whether initial assessment is completed
+    initial_knowledge_survey: Dict[str, float] = None  # Initial knowledge survey results, None requires special handling
+
+@dataclass
+class LearningPathNode:
+    """Learning path node"""
+    node_id: str
+    topic: str
+    bloom_level: str  # "remember", "understand", "apply", "analyze", "evaluate", "create"
+    difficulty: float  # 0-1
+    prerequisites: List[str]  # Prerequisite node IDs
+    estimated_time: int  # Estimated time (minutes)
+    content_type: str  # "reading", "quiz", "practical", "review"
+    status: str  # "pending", "in_progress", "completed", "skipped"
+    completion_date: Optional[str] = None
+    score: Optional[float] = None
+
+@dataclass
+class LearningPath:
+    """Learning path"""
+    path_id: str
+    user_id: str
+    nodes: List[LearningPathNode]
+    current_node_index: int
+    completion_percentage: float
+    created_at: str
+    updated_at: str
+    estimated_total_time: int
+
+
+class UserProfilingSystem:
+    """User profiling system"""
+    
+    def __init__(self, storage_dir: str = "user_data"):
+        self.storage_dir = storage_dir
+        os.makedirs(storage_dir, exist_ok=True)
+        self.profiles_file = os.path.join(storage_dir, "user_profiles.json")
+        self.profiles = self._load_profiles()
+    
+    def _load_profiles(self) -> Dict[str, UserProfile]:
+        """Load user profiles"""
+        if os.path.exists(self.profiles_file):
+            try:
+                with open(self.profiles_file, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+                    return {uid: UserProfile(**profile) for uid, profile in data.items()}
+            except Exception as e:
+                print(f"Error loading profiles: {e}")
+        return {}
+    
+    def _save_profiles(self):
+        """Save user profiles"""
+        try:
+            with open(self.profiles_file, 'w', encoding='utf-8') as f:
+                data = {uid: asdict(profile) for uid, profile in self.profiles.items()}
+                json.dump(data, f, indent=2, ensure_ascii=False)
+        except Exception as e:
+            print(f"Error saving profiles: {e}")
+    
+    def get_or_create_profile(self, user_id: str) -> UserProfile:
+        """Get or create user profile (cold start)"""
+        if user_id not in self.profiles:
+            self.profiles[user_id] = UserProfile(
+                user_id=user_id,
+                knowledge_level={},
+                learning_style="mixed",
+                learning_pace="medium",
+                preferred_topics=[],
+                weak_areas=[],
+                strong_areas=[],
+                test_scores={},
+                question_history=[],
+                learning_time={},
+                last_activity=datetime.now().isoformat(),
+                total_questions_asked=0,
+                total_tests_completed=0,
+                bloom_level_performance={},
+                created_at=datetime.now().isoformat(),
+                updated_at=datetime.now().isoformat(),
+                has_completed_onboarding=False,
+                background_experience="",
+                learning_goals=None,
+                initial_assessment_completed=False,
+                initial_knowledge_survey=None
+            )
+            self._save_profiles()
+        return self.profiles[user_id]
+    
+    def is_cold_start(self, user_id: str) -> bool:
+        """Check if user is in cold start state"""
+        if user_id not in self.profiles:
+            return True
+        profile = self.profiles[user_id]
+        return not profile.has_completed_onboarding
+    
+    def complete_onboarding(self, user_id: str, onboarding_data: Dict):
+        """Complete cold start setup and collect initial user information
+        
+        Information collected during cold start:
+        1. Learning preferences:
+           - learning_style: Learning style preference
+           - learning_pace: Learning pace preference
+        2. Background information:
+           - background_experience: Background experience
+           - learning_goals: List of learning goals
+        3. Initial knowledge assessment:
+           - initial_knowledge_survey: Initial familiarity with each topic (0-1)
+           - initial_assessment_completed: Whether initial assessment is completed
+        """
+        profile = self.get_or_create_profile(user_id)
+        
+        # Update learning style
+        if 'learning_style' in onboarding_data:
+            profile.learning_style = onboarding_data['learning_style']
+        
+        # Update learning pace
+        if 'learning_pace' in onboarding_data:
+            profile.learning_pace = onboarding_data['learning_pace']
+        
+        # Update background experience
+        if 'background_experience' in onboarding_data:
+            profile.background_experience = onboarding_data['background_experience']
+        
+        # Update learning goals
+        if 'learning_goals' in onboarding_data:
+            profile.learning_goals = onboarding_data['learning_goals']
+        
+        # Update initial knowledge survey
+        if 'initial_knowledge_survey' in onboarding_data:
+            profile.initial_knowledge_survey = onboarding_data['initial_knowledge_survey']
+            # Convert initial survey results to knowledge level
+            profile.knowledge_level = onboarding_data['initial_knowledge_survey'].copy()
+        
+        # Update preferred topics (based on initial survey, select topics with lower familiarity)
+        if 'initial_knowledge_survey' in onboarding_data:
+            survey = onboarding_data['initial_knowledge_survey']
+            # Select topics with lower familiarity as learning focus
+            low_knowledge_topics = [topic for topic, level in survey.items() if level < 0.5]
+            profile.preferred_topics = low_knowledge_topics[:3]  # Take top 3
+        
+        # Update initial assessment status
+        if 'initial_assessment_completed' in onboarding_data:
+            profile.initial_assessment_completed = onboarding_data['initial_assessment_completed']
+        
+        # Mark cold start as completed
+        profile.has_completed_onboarding = True
+        profile.updated_at = datetime.now().isoformat()
+        
+        self._save_profiles()
+        return profile
+    
+    def update_from_test_results(self, user_id: str, topic: str, test_results: List[Dict]):
+        """Update user profile from test results"""
+        profile = self.get_or_create_profile(user_id)
+        
+        # Calculate average score
+        scores = [r.get('score', 1.0 if r.get('is_correct', False) else 0.0) 
+                  for r in test_results]
+        avg_score = np.mean(scores) if scores else 0.5
+        
+        # Update knowledge level
+        if topic not in profile.knowledge_level:
+            profile.knowledge_level[topic] = avg_score
+        else:
+            # Weighted average (give more weight to latest results)
+            profile.knowledge_level[topic] = 0.7 * avg_score + 0.3 * profile.knowledge_level[topic]
+        
+        # Update test score history
+        if topic not in profile.test_scores:
+            profile.test_scores[topic] = []
+        profile.test_scores[topic].append(avg_score)
+        
+        # Update Bloom level performance
+        if topic not in profile.bloom_level_performance:
+            profile.bloom_level_performance[topic] = {}
+        
+        for result in test_results:
+            level = result.get('level', 'unknown')
+            is_correct = result.get('is_correct', False)
+            score = 1.0 if is_correct else 0.0
+            
+            if level not in profile.bloom_level_performance[topic]:
+                profile.bloom_level_performance[topic][level] = []
+            profile.bloom_level_performance[topic][level].append(score)
+        
+        # Calculate average performance for each Bloom level
+        for level in profile.bloom_level_performance[topic]:
+            scores = profile.bloom_level_performance[topic][level]
+            profile.bloom_level_performance[topic][level] = np.mean(scores) if scores else 0.0
+        
+        # Update weak and strong areas
+        self._update_weak_strong_areas(profile)
+        
+        # Update learning pace
+        profile.learning_pace = self._calculate_learning_pace(profile)
+        
+        profile.total_tests_completed += 1
+        profile.last_activity = datetime.now().isoformat()
+        profile.updated_at = datetime.now().isoformat()
+        
+        self._save_profiles()
+        return profile
+    
+    def update_from_question(self, user_id: str, question: str, topic: Optional[str] = None):
+        """Update user profile from question history"""
+        profile = self.get_or_create_profile(user_id)
+        
+        profile.question_history.append({
+            "question": question,
+            "topic": topic,
+            "timestamp": datetime.now().isoformat()
+        })
+        
+        # Analyze question type to infer learning style
+        profile.learning_style = self._infer_learning_style(profile.question_history)
+        
+        # Update preferred topics
+        if topic:
+            if topic not in profile.preferred_topics:
+                profile.preferred_topics.append(topic)
+            # Sort by frequency
+            topic_counts = defaultdict(int)
+            for q in profile.question_history:
+                if q.get('topic'):
+                    topic_counts[q['topic']] += 1
+            profile.preferred_topics = sorted(topic_counts.items(), key=lambda x: x[1], reverse=True)[:5]
+            profile.preferred_topics = [t[0] for t in profile.preferred_topics]
+        
+        profile.total_questions_asked += 1
+        profile.last_activity = datetime.now().isoformat()
+        profile.updated_at = datetime.now().isoformat()
+        
+        self._save_profiles()
+        return profile
+    
+    def update_learning_time(self, user_id: str, topic: str, minutes: float):
+        """Update learning time"""
+        profile = self.get_or_create_profile(user_id)
+        
+        if topic not in profile.learning_time:
+            profile.learning_time[topic] = 0.0
+        profile.learning_time[topic] += minutes
+        
+        profile.last_activity = datetime.now().isoformat()
+        profile.updated_at = datetime.now().isoformat()
+        
+        self._save_profiles()
+        return profile
+    
+    def _update_weak_strong_areas(self, profile: UserProfile):
+        """Update weak and strong areas"""
+        # Topics with knowledge level below 0.6 are weak areas
+        weak = [topic for topic, level in profile.knowledge_level.items() if level < 0.6]
+        # Topics with knowledge level above 0.8 are strong areas
+        strong = [topic for topic, level in profile.knowledge_level.items() if level >= 0.8]
+        
+        profile.weak_areas = weak
+        profile.strong_areas = strong
+    
+    def _calculate_learning_pace(self, profile: UserProfile) -> str:
+        """Calculate learning pace"""
+        if not profile.test_scores:
+            return "medium"
+        
+        # Calculate test completion speed
+        total_tests = profile.total_tests_completed
+        if total_tests == 0:
+            return "medium"
+        
+        # Analyze performance changes in recent tests
+        recent_scores = []
+        for topic_scores in profile.test_scores.values():
+            if topic_scores:
+                recent_scores.extend(topic_scores[-3:])  # Last 3 tests
+        
+        if not recent_scores:
+            return "medium"
+        
+        # If recent scores improve quickly, likely a fast-paced learner
+        if len(recent_scores) >= 3:
+            improvement = recent_scores[-1] - recent_scores[0]
+            if improvement > 0.3:
+                return "fast"
+            elif improvement < -0.1:
+                return "slow"
+        
+        return "medium"
+    
+    def _infer_learning_style(self, question_history: List[Dict]) -> str:
+        """Infer learning style from question history"""
+        if not question_history:
+            return "mixed"
+        
+        # Analyze question keywords
+        visual_keywords = ["how", "what does", "show", "visual", "diagram", "illustration"]
+        practical_keywords = ["how to", "step", "procedure", "activate", "use", "operate"]
+        textual_keywords = ["what is", "explain", "define", "describe", "meaning"]
+        
+        visual_count = sum(1 for q in question_history 
+                          if any(kw in q.get('question', '').lower() for kw in visual_keywords))
+        practical_count = sum(1 for q in question_history 
+                             if any(kw in q.get('question', '').lower() for kw in practical_keywords))
+        textual_count = sum(1 for q in question_history 
+                           if any(kw in q.get('question', '').lower() for kw in textual_keywords))
+        
+        total = len(question_history)
+        if total == 0:
+            return "mixed"
+        
+        visual_ratio = visual_count / total
+        practical_ratio = practical_count / total
+        textual_ratio = textual_count / total
+        
+        max_ratio = max(visual_ratio, practical_ratio, textual_ratio)
+        if max_ratio > 0.4:
+            if visual_ratio == max_ratio:
+                return "visual"
+            elif practical_ratio == max_ratio:
+                return "practical"
+            else:
+                return "textual"
+        
+        return "mixed"
+    
+    def get_profile_summary(self, user_id: str) -> Dict:
+        """Get user profile summary"""
+        profile = self.get_or_create_profile(user_id)
+        
+        return {
+            "user_id": profile.user_id,
+            "knowledge_level": profile.knowledge_level,
+            "learning_style": profile.learning_style,
+            "learning_pace": profile.learning_pace,
+            "preferred_topics": profile.preferred_topics,
+            "weak_areas": profile.weak_areas,
+            "strong_areas": profile.strong_areas,
+            "total_questions": profile.total_questions_asked,
+            "total_tests": profile.total_tests_completed,
+            "overall_progress": self._calculate_overall_progress(profile)
+        }
+    
+    def _calculate_overall_progress(self, profile: UserProfile) -> float:
+        """Calculate overall progress"""
+        if not profile.knowledge_level:
+            return 0.0
+        return np.mean(list(profile.knowledge_level.values()))
+
+
+class LearningPathGenerator:
+    """Learning path generator"""
+    
+    def __init__(self, user_profiling: UserProfilingSystem, available_topics: List[str]):
+        self.user_profiling = user_profiling
+        self.available_topics = available_topics
+        self.bloom_levels = ["remember", "understand", "apply", "analyze", "evaluate", "create"]
+    
+    def generate_path(self, user_id: str, focus_areas: Optional[List[str]] = None) -> LearningPath:
+        """Generate personalized learning path"""
+        profile = self.user_profiling.get_or_create_profile(user_id)
+        
+        # Determine topics to learn
+        topics_to_learn = self._determine_topics(profile, focus_areas)
+        
+        # Generate learning nodes
+        nodes = []
+        node_id_counter = 0
+        
+        for topic in topics_to_learn:
+            topic_level = profile.knowledge_level.get(topic, 0.0)
+            bloom_performance = profile.bloom_level_performance.get(topic, {})
+            
+            # Generate nodes for different Bloom levels for each topic
+            for bloom_level in self.bloom_levels:
+                # Check if this node is needed
+                if not self._needs_node(profile, topic, bloom_level, topic_level, bloom_performance):
+                    continue
+                
+                node = LearningPathNode(
+                    node_id=f"node_{node_id_counter}",
+                    topic=topic,
+                    bloom_level=bloom_level,
+                    difficulty=self._calculate_difficulty(topic_level, bloom_level),
+                    prerequisites=self._get_prerequisites(nodes, topic, bloom_level),
+                    estimated_time=self._estimate_time(bloom_level, profile.learning_pace),
+                    content_type=self._determine_content_type(bloom_level, profile.learning_style),
+                    status="pending"
+                )
+                nodes.append(node)
+                node_id_counter += 1
+        
+        # Sort nodes (considering prerequisites)
+        ordered_nodes = self._topological_sort(nodes)
+        
+        # Calculate total time
+        total_time = sum(node.estimated_time for node in ordered_nodes)
+        
+        path = LearningPath(
+            path_id=f"path_{user_id}_{datetime.now().strftime('%Y%m%d%H%M%S')}",
+            user_id=user_id,
+            nodes=ordered_nodes,
+            current_node_index=0,
+            completion_percentage=0.0,
+            created_at=datetime.now().isoformat(),
+            updated_at=datetime.now().isoformat(),
+            estimated_total_time=total_time
+        )
+        
+        return path
+    
+    def _determine_topics(self, profile: UserProfile, focus_areas: Optional[List[str]]) -> List[str]:
+        """Determine topics to learn"""
+        if focus_areas:
+            return focus_areas
+        
+        # Prioritize weak areas
+        topics = profile.weak_areas.copy()
+        
+        # Add unlearned topics
+        for topic in self.available_topics:
+            if topic not in profile.knowledge_level and topic not in topics:
+                topics.append(topic)
+        
+        # If no weak areas, recommend preferred or strong area related topics
+        if not topics:
+            topics = profile.preferred_topics[:3] if profile.preferred_topics else self.available_topics[:3]
+        
+        return topics[:5]  # Limit to maximum 5 topics
+    
+    def _needs_node(self, profile: UserProfile, topic: str, bloom_level: str, 
+                   topic_level: float, bloom_performance: Dict) -> bool:
+        """Determine if a node is needed"""
+        # If performance at this Bloom level is already good, skip
+        level_performance = bloom_performance.get(bloom_level, 0.0)
+        if level_performance >= 0.8:
+            return False
+        
+        # Decide based on knowledge level
+        if topic_level < 0.3 and bloom_level in ["analyze", "evaluate", "create"]:
+            return False  # Insufficient foundational knowledge, learn basics first
+        
+        return True
+    
+    def _calculate_difficulty(self, topic_level: float, bloom_level: str) -> float:
+        """Calculate node difficulty"""
+        bloom_weights = {
+            "remember": 0.2,
+            "understand": 0.3,
+            "apply": 0.5,
+            "analyze": 0.7,
+            "evaluate": 0.85,
+            "create": 1.0
+        }
+        
+        base_difficulty = bloom_weights.get(bloom_level, 0.5)
+        # Adjust based on current knowledge level
+        adjusted = base_difficulty * (1 - topic_level * 0.3)
+        return min(1.0, max(0.1, adjusted))
+    
+    def _get_prerequisites(self, existing_nodes: List[LearningPathNode], 
+                          topic: str, bloom_level: str) -> List[str]:
+        """Get prerequisites"""
+        prereqs = []
+        
+        # Lower Bloom levels of the same topic are prerequisites
+        bloom_order = ["remember", "understand", "apply", "analyze", "evaluate", "create"]
+        current_index = bloom_order.index(bloom_level) if bloom_level in bloom_order else 0
+        
+        for node in existing_nodes:
+            if node.topic == topic:
+                node_index = bloom_order.index(node.bloom_level) if node.bloom_level in bloom_order else 0
+                if node_index < current_index:
+                    prereqs.append(node.node_id)
+        
+        return prereqs
+    
+    def _estimate_time(self, bloom_level: str, learning_pace: str) -> int:
+        """Estimate learning time (minutes)"""
+        base_times = {
+            "remember": 10,
+            "understand": 15,
+            "apply": 20,
+            "analyze": 25,
+            "evaluate": 30,
+            "create": 35
+        }
+        
+        base_time = base_times.get(bloom_level, 20)
+        
+        pace_multipliers = {
+            "slow": 1.5,
+            "medium": 1.0,
+            "fast": 0.7
+        }
+        
+        return int(base_time * pace_multipliers.get(learning_pace, 1.0))
+    
+    def _determine_content_type(self, bloom_level: str, learning_style: str) -> str:
+        """Determine content type"""
+        # Decide based on learning style and Bloom level
+        if learning_style == "visual":
+            if bloom_level in ["remember", "understand"]:
+                return "reading"
+            else:
+                return "practical"
+        elif learning_style == "practical":
+            return "practical"
+        elif learning_style == "textual":
+            return "reading"
+        else:
+            # mixed
+            if bloom_level in ["apply", "analyze", "evaluate", "create"]:
+                return "quiz"
+            return "reading"
+    
+    def _topological_sort(self, nodes: List[LearningPathNode]) -> List[LearningPathNode]:
+        """Topological sort to ensure prerequisites are completed first"""
+        # Create node mapping
+        node_map = {node.node_id: node for node in nodes}
+        
+        # Calculate in-degree
+        in_degree = {node.node_id: len(node.prerequisites) for node in nodes}
+        
+        # Find nodes without prerequisites
+        queue = [node.node_id for node in nodes if in_degree[node.node_id] == 0]
+        result = []
+        
+        while queue:
+            current_id = queue.pop(0)
+            current_node = node_map[current_id]
+            result.append(current_node)
+            
+            # Update in-degree of other nodes
+            for node in nodes:
+                if current_id in node.prerequisites:
+                    in_degree[node.node_id] -= 1
+                    if in_degree[node.node_id] == 0:
+                        queue.append(node.node_id)
+        
+        # Add remaining nodes (may have circular dependencies)
+        remaining = [node for node in nodes if node not in result]
+        result.extend(remaining)
+        
+        return result
+
+
+class AdaptiveLearningEngine:
+    """Adaptive learning engine"""
+    
+    def __init__(self, user_profiling: UserProfilingSystem, learning_path_generator: LearningPathGenerator):
+        self.user_profiling = user_profiling
+        self.learning_path_generator = learning_path_generator
+        self.paths_file = os.path.join("user_data", "learning_paths.json")
+        self.paths = self._load_paths()
+    
+    def _load_paths(self) -> Dict[str, LearningPath]:
+        """Load learning paths"""
+        if os.path.exists(self.paths_file):
+            try:
+                with open(self.paths_file, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+                    paths = {}
+                    for pid, path_data in data.items():
+                        nodes = [LearningPathNode(**node) for node in path_data['nodes']]
+                        path = LearningPath(
+                            path_id=path_data['path_id'],
+                            user_id=path_data['user_id'],
+                            nodes=nodes,
+                            current_node_index=path_data['current_node_index'],
+                            completion_percentage=path_data['completion_percentage'],
+                            created_at=path_data['created_at'],
+                            updated_at=path_data['updated_at'],
+                            estimated_total_time=path_data['estimated_total_time']
+                        )
+                        paths[pid] = path
+                    return paths
+            except Exception as e:
+                print(f"Error loading paths: {e}")
+        return {}
+    
+    def _save_paths(self):
+        """Save learning paths"""
+        try:
+            os.makedirs("user_data", exist_ok=True)
+            with open(self.paths_file, 'w', encoding='utf-8') as f:
+                data = {}
+                for pid, path in self.paths.items():
+                    path_dict = asdict(path)
+                    data[pid] = path_dict
+                json.dump(data, f, indent=2, ensure_ascii=False)
+        except Exception as e:
+            print(f"Error saving paths: {e}")
+    
+    def create_or_update_path(self, user_id: str, focus_areas: Optional[List[str]] = None) -> LearningPath:
+        """Create or update learning path"""
+        # Check if there is an active path
+        active_path = self.get_active_path(user_id)
+        
+        if active_path and active_path.completion_percentage < 1.0:
+            # Update existing path
+            return self._update_path(active_path)
+        else:
+            # Create new path
+            path = self.learning_path_generator.generate_path(user_id, focus_areas)
+            self.paths[path.path_id] = path
+            self._save_paths()
+            return path
+    
+    def get_active_path(self, user_id: str) -> Optional[LearningPath]:
+        """Get user's current active path"""
+        user_paths = [p for p in self.paths.values() if p.user_id == user_id]
+        if not user_paths:
+            return None
+        
+        # Return the latest incomplete path
+        active = [p for p in user_paths if p.completion_percentage < 1.0]
+        if active:
+            return max(active, key=lambda p: p.created_at)
+        
+        # If no incomplete paths, return the latest one
+        return max(user_paths, key=lambda p: p.created_at)
+    
+    def complete_node(self, user_id: str, node_id: str, score: float):
+        """Complete a node"""
+        path = self.get_active_path(user_id)
+        if not path:
+            return None
+        
+        # Find node and mark as completed
+        for node in path.nodes:
+            if node.node_id == node_id:
+                node.status = "completed"
+                node.score = score
+                node.completion_date = datetime.now().isoformat()
+                break
+        
+        # Update path progress
+        completed = sum(1 for n in path.nodes if n.status == "completed")
+        path.completion_percentage = completed / len(path.nodes) if path.nodes else 0.0
+        
+        # Update current node index
+        for i, node in enumerate(path.nodes):
+            if node.status not in ["completed", "skipped"]:
+                path.current_node_index = i
+                break
+        
+        path.updated_at = datetime.now().isoformat()
+        self._save_paths()
+        
+        # Update user profile
+        current_node = path.nodes[path.current_node_index] if path.current_node_index < len(path.nodes) else None
+        if current_node:
+            self.user_profiling.update_learning_time(
+                user_id, 
+                current_node.topic, 
+                current_node.estimated_time
+            )
+        
+        return path
+    
+    def _update_path(self, path: LearningPath) -> LearningPath:
+        """Update path based on user performance"""
+        profile = self.user_profiling.get_or_create_profile(path.user_id)
+        
+        # Check if path needs adjustment
+        for node in path.nodes:
+            if node.status == "pending":
+                # Check if already mastered
+                topic_level = profile.knowledge_level.get(node.topic, 0.0)
+                bloom_perf = profile.bloom_level_performance.get(node.topic, {}).get(node.bloom_level, 0.0)
+                
+                if bloom_perf >= 0.8:
+                    # Already mastered, can skip
+                    node.status = "skipped"
+                    node.completion_date = datetime.now().isoformat()
+        
+        # Recalculate progress
+        completed = sum(1 for n in path.nodes if n.status in ["completed", "skipped"])
+        path.completion_percentage = completed / len(path.nodes) if path.nodes else 0.0
+        
+        path.updated_at = datetime.now().isoformat()
+        self._save_paths()
+        
+        return path
+    
+    def get_recommendations(self, user_id: str) -> Dict:
+        """Get learning recommendations"""
+        profile = self.user_profiling.get_or_create_profile(user_id)
+        path = self.get_active_path(user_id)
+        
+        recommendations = {
+            "next_node": None,
+            "suggested_topics": [],
+            "review_topics": [],
+            "challenge_topics": []
+        }
+        
+        # Recommend next node
+        if path and path.current_node_index < len(path.nodes):
+            next_node = path.nodes[path.current_node_index]
+            recommendations["next_node"] = {
+                "node_id": next_node.node_id,
+                "topic": next_node.topic,
+                "bloom_level": next_node.bloom_level,
+                "content_type": next_node.content_type,
+                "estimated_time": next_node.estimated_time
+            }
+        
+        # Recommend topics for review
+        recommendations["review_topics"] = profile.weak_areas[:3]
+        
+        # Recommend challenge topics (advanced content for strong areas)
+        for topic in profile.strong_areas[:2]:
+            if topic not in recommendations["challenge_topics"]:
+                recommendations["challenge_topics"].append(topic)
+        
+        # Recommend new topics
+        all_topics = set(self.learning_path_generator.available_topics)
+        learned_topics = set(profile.knowledge_level.keys())
+        new_topics = list(all_topics - learned_topics)[:3]
+        recommendations["suggested_topics"] = new_topics
+        
+        return recommendations
+    
+    def get_path_visualization_data(self, user_id: str) -> Dict:
+        """Get path visualization data"""
+        path = self.get_active_path(user_id)
+        if not path:
+            return {"nodes": [], "edges": []}
+        
+        nodes_data = []
+        edges_data = []
+        
+        for node in path.nodes:
+            nodes_data.append({
+                "id": node.node_id,
+                "topic": node.topic,
+                "bloom_level": node.bloom_level,
+                "status": node.status,
+                "difficulty": node.difficulty,
+                "score": node.score
+            })
+            
+            # Add edges (prerequisites)
+            for prereq_id in node.prerequisites:
+                edges_data.append({
+                    "source": prereq_id,
+                    "target": node.node_id
+                })
+        
+        return {
+            "nodes": nodes_data,
+            "edges": edges_data,
+            "completion_percentage": path.completion_percentage,
+            "current_node_index": path.current_node_index
+        }
+

modules/proactive_learning.py

@@ -0,0 +1,522 @@
+"""
+Proactive Learning Assistance Module (Phase 1)
+Implements intelligent prompting suggestions, context-aware follow-up questions, and critical knowledge gap identification
+"""
+
+import json
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+from openai import OpenAI
+
+
+class KnowledgeGapAnalyzer:
+    """Analyzes user knowledge gaps, especially critical safety-related gaps"""
+    
+    # Safety-critical ADAS features that require high knowledge levels
+    SAFETY_CRITICAL_FEATURES = [
+        "Function of Active Distance Assist DISTRONIC",
+        "Function of Active Stop-and-Go Assist",
+        "Function of Active Steering Assist"
+    ]
+    
+    # Knowledge level thresholds
+    CRITICAL_GAP_THRESHOLD = 0.5  # Below this is considered a critical gap for safety features
+    WEAK_AREA_THRESHOLD = 0.6  # Below this is considered a weak area
+    
+    def __init__(self, available_topics: List[str]):
+        self.available_topics = available_topics
+    
+    def identify_critical_gaps(self, user_profile) -> List[str]:
+        """
+        Identify critical knowledge gaps that could impact safety
+        
+        Returns:
+            List of topics with critical knowledge gaps
+        """
+        critical_gaps = []
+        knowledge_level = user_profile.knowledge_level if hasattr(user_profile, 'knowledge_level') else {}
+        
+        for topic in self.available_topics:
+            level = knowledge_level.get(topic, 0.0)
+            
+            # Check if it's a safety-critical feature with low knowledge
+            if topic in self.SAFETY_CRITICAL_FEATURES and level < self.CRITICAL_GAP_THRESHOLD:
+                critical_gaps.append(topic)
+        
+        return critical_gaps
+    
+    def identify_weak_areas(self, user_profile) -> List[str]:
+        """
+        Identify all weak areas (not just critical)
+        
+        Returns:
+            List of topics with weak knowledge levels
+        """
+        weak_areas = []
+        knowledge_level = user_profile.knowledge_level if hasattr(user_profile, 'knowledge_level') else {}
+        
+        for topic in self.available_topics:
+            level = knowledge_level.get(topic, 0.0)
+            if level < self.WEAK_AREA_THRESHOLD:
+                weak_areas.append(topic)
+        
+        return weak_areas
+    
+    def get_gap_priority(self, user_profile) -> List[Tuple[str, float]]:
+        """
+        Get knowledge gaps with priority scores
+        
+        Returns:
+            List of (topic, priority_score) tuples, sorted by priority
+        """
+        gaps = []
+        knowledge_level = user_profile.knowledge_level if hasattr(user_profile, 'knowledge_level') else {}
+        
+        for topic in self.available_topics:
+            level = knowledge_level.get(topic, 0.0)
+            
+            # Calculate priority score
+            priority = 0.0
+            
+            # Safety-critical features get higher priority
+            if topic in self.SAFETY_CRITICAL_FEATURES:
+                priority += 2.0
+            
+            # Lower knowledge level = higher priority
+            priority += (1.0 - level) * 1.5
+            
+            # Check if it's in weak areas
+            if hasattr(user_profile, 'weak_areas') and topic in user_profile.weak_areas:
+                priority += 0.5
+            
+            gaps.append((topic, priority))
+        
+        # Sort by priority (descending)
+        gaps.sort(key=lambda x: x[1], reverse=True)
+        return gaps
+
+
+class PromptSuggestionGenerator:
+    """Generates intelligent prompt suggestions based on user profile and learning history"""
+    
+    def __init__(self, client: OpenAI, rag_engine, knowledge_gap_analyzer: KnowledgeGapAnalyzer, 
+                 available_topics: List[str]):
+        self.client = client
+        self.rag_engine = rag_engine
+        self.gap_analyzer = knowledge_gap_analyzer
+        self.available_topics = available_topics
+    
+    def generate_suggestions(self, user_id: str, user_profile, learning_path=None, 
+                            context: Optional[str] = None, max_suggestions: int = 5) -> List[Dict[str, str]]:
+        """
+        Generate prompt suggestions based on multiple criteria
+        
+        Args:
+            user_id: User ID
+            user_profile: UserProfile object
+            learning_path: Optional LearningPath object
+            context: Optional context (e.g., recent question)
+            max_suggestions: Maximum number of suggestions to return
+            
+        Returns:
+            List of suggestion dictionaries with 'question' and 'reason' keys
+        """
+        suggestions = []
+        
+        # 1. Based on critical knowledge gaps
+        critical_gaps = self.gap_analyzer.identify_critical_gaps(user_profile)
+        for topic in critical_gaps[:2]:  # Top 2 critical gaps
+            question = self._generate_question_for_topic(topic, "beginner")
+            if question:
+                suggestions.append({
+                    "question": question,
+                    "reason": f"Critical Safety Feature: Your understanding of {topic.replace('Function of ', '')} needs improvement",
+                    "priority": "high",
+                    "type": "critical_gap"
+                })
+        
+        # 2. Based on learning path
+        if learning_path and hasattr(learning_path, 'nodes') and learning_path.nodes:
+            current_node = None
+            if learning_path.current_node_index < len(learning_path.nodes):
+                current_node = learning_path.nodes[learning_path.current_node_index]
+            
+            if current_node and current_node.status != "completed":
+                question = self._generate_question_for_topic(current_node.topic, current_node.bloom_level)
+                if question:
+                    suggestions.append({
+                        "question": question,
+                        "reason": f"Learning Path: Current learning node - {current_node.topic}",
+                        "priority": "medium",
+                        "type": "learning_path"
+                    })
+        
+        # 3. Based on weak areas
+        weak_areas = self.gap_analyzer.identify_weak_areas(user_profile)
+        for topic in weak_areas[:2]:  # Top 2 weak areas
+            if topic not in critical_gaps:  # Avoid duplicates
+                question = self._generate_question_for_topic(topic, "understand")
+                if question:
+                    suggestions.append({
+                        "question": question,
+                        "reason": f"Weak Area: Recommend strengthening understanding of {topic.replace('Function of ', '')}",
+                        "priority": "medium",
+                        "type": "weak_area"
+                    })
+        
+        # 4. Based on recent questions (if context provided)
+        if context:
+            related_questions = self._generate_related_questions(context)
+            for q in related_questions[:2]:
+                suggestions.append({
+                    "question": q,
+                    "reason": "Related Question: Explore deeper into the topic you just asked about",
+                    "priority": "low",
+                    "type": "related"
+                })
+        
+        # 5. Based on unlearned topics
+        knowledge_level = user_profile.knowledge_level if hasattr(user_profile, 'knowledge_level') else {}
+        unlearned_topics = [t for t in self.available_topics if t not in knowledge_level]
+        for topic in unlearned_topics[:1]:  # Top 1 unlearned topic
+            question = self._generate_question_for_topic(topic, "remember")
+            if question:
+                suggestions.append({
+                    "question": question,
+                    "reason": f"New Topic: Start learning {topic.replace('Function of ', '')}",
+                    "priority": "low",
+                    "type": "new_topic"
+                })
+        
+        # Rank and filter suggestions
+        suggestions = self._rank_suggestions(suggestions)
+        return suggestions[:max_suggestions]
+    
+    def _generate_question_for_topic(self, topic: str, level: str = "understand") -> Optional[str]:
+        """Generate a question for a specific topic"""
+        try:
+            # Use RAG to get topic information
+            query = f"What are the key points about {topic}?"
+            answer, _ = self.rag_engine.query(query)
+            
+            # Generate question using LLM
+            prompt = f"""Based on the following information about {topic}, generate a single, clear question that a user might ask to learn about this topic.
+
+The question should be at a {level} level (from Bloom's taxonomy).
+
+Information:
+{answer[:500]}  # Limit context to avoid token limits
+
+Generate only the question text, nothing else. The question should be:
+- Clear and specific
+- Appropriate for someone learning about ADAS systems
+- In Chinese or English (match the user's language preference)
+
+Question:"""
+            
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are a helpful assistant that generates educational questions."},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=0.7,
+                max_tokens=100
+            )
+            
+            question = response.choices[0].message.content.strip()
+            # Remove quotes if present
+            question = question.strip('"').strip("'")
+            return question
+        except Exception as e:
+            print(f"Error generating question for topic {topic}: {e}")
+            # Fallback to simple question
+            topic_clean = topic.replace("Function of ", "").replace(" Assist", "")
+            return f"What is {topic_clean} and how does it work?"
+    
+    def _generate_related_questions(self, context: str) -> List[str]:
+        """Generate related questions based on context"""
+        try:
+            prompt = f"""Based on the following question or context, generate 2-3 related follow-up questions that would help deepen understanding.
+
+Context: {context[:300]}
+
+Generate 2-3 questions, one per line. Questions should:
+- Build upon the context
+- Help explore related concepts
+- Be clear and specific
+
+Questions:"""
+            
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are a helpful assistant that generates educational follow-up questions."},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=0.7,
+                max_tokens=200
+            )
+            
+            questions_text = response.choices[0].message.content.strip()
+            questions = [q.strip().strip('-').strip() for q in questions_text.split('\n') if q.strip()]
+            return questions[:3]
+        except Exception as e:
+            print(f"Error generating related questions: {e}")
+            return []
+    
+    def _rank_suggestions(self, suggestions: List[Dict]) -> List[Dict]:
+        """Rank suggestions by priority"""
+        priority_weights = {"high": 3, "medium": 2, "low": 1}
+        suggestions.sort(key=lambda x: priority_weights.get(x.get("priority", "low"), 1), reverse=True)
+        return suggestions
+
+
+class FollowUpQuestionGenerator:
+    """Generates context-aware follow-up questions based on RAG answers"""
+    
+    def __init__(self, client: OpenAI, rag_engine):
+        self.client = client
+        self.rag_engine = rag_engine
+        
+        self.bloom_levels = ["remember", "understand", "apply", "analyze", "evaluate", "create"]
+    
+    def generate_follow_up_questions(self, answer: str, user_profile, 
+                                     max_questions: int = 5) -> List[Dict[str, str]]:
+        """
+        Generate follow-up questions based on the answer provided
+        
+        Args:
+            answer: The RAG answer text
+            user_profile: UserProfile object
+            max_questions: Maximum number of questions to generate
+            
+        Returns:
+            List of question dictionaries with 'question' and 'bloom_level' keys
+        """
+        questions = []
+        
+        # Determine user's current Bloom level (default to understand)
+        current_bloom = self._infer_user_bloom_level(user_profile)
+        current_index = self.bloom_levels.index(current_bloom) if current_bloom in self.bloom_levels else 1
+        
+        # Generate questions for next 2-3 Bloom levels
+        target_levels = self.bloom_levels[current_index:current_index + 3]
+        
+        for level in target_levels[:2]:  # Limit to 2 levels
+            level_questions = self._generate_questions_by_bloom(answer, level)
+            questions.extend(level_questions[:2])  # 2 questions per level
+        
+        # Also generate related concept questions
+        related_questions = self._generate_related_concept_questions(answer)
+        questions.extend(related_questions[:1])
+        
+        return questions[:max_questions]
+    
+    def _infer_user_bloom_level(self, user_profile) -> str:
+        """Infer user's current Bloom taxonomy level based on profile"""
+        # Check recent test performance
+        if hasattr(user_profile, 'bloom_level_performance') and user_profile.bloom_level_performance:
+            # Find the highest level where user has good performance
+            for level in reversed(self.bloom_levels):
+                for topic_perf in user_profile.bloom_level_performance.values():
+                    if level in topic_perf and topic_perf[level] >= 0.7:
+                        return level
+        
+        # Default based on overall progress
+        if hasattr(user_profile, 'knowledge_level') and user_profile.knowledge_level:
+            avg_level = sum(user_profile.knowledge_level.values()) / len(user_profile.knowledge_level.values())
+            if avg_level < 0.3:
+                return "remember"
+            elif avg_level < 0.6:
+                return "understand"
+            else:
+                return "apply"
+        
+        return "understand"  # Default
+    
+    def _generate_questions_by_bloom(self, answer: str, bloom_level: str) -> List[Dict[str, str]]:
+        """Generate questions at a specific Bloom taxonomy level"""
+        try:
+            bloom_descriptions = {
+                "remember": "test basic recall of facts and information",
+                "understand": "test explanation and interpretation of concepts",
+                "apply": "test application of knowledge in practical situations",
+                "analyze": "test analysis of relationships and structure",
+                "evaluate": "test evaluation and judgment based on criteria",
+                "create": "test creation of new ideas or solutions"
+            }
+            
+            prompt = f"""Based on the following answer about ADAS systems, generate 2 follow-up questions at the {bloom_level} level of Bloom's taxonomy.
+
+Bloom level description: {bloom_descriptions.get(bloom_level, '')}
+
+Answer text:
+{answer[:800]}  # Limit context
+
+Generate 2 questions that:
+- Build upon the information in the answer
+- Are at the {bloom_level} level
+- Help deepen understanding
+- Are clear and specific
+
+Output format: One question per line, no numbering or bullets.
+
+Questions:"""
+            
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are an educational assistant that generates follow-up questions."},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=0.7,
+                max_tokens=200
+            )
+            
+            questions_text = response.choices[0].message.content.strip()
+            question_list = [q.strip().strip('-').strip() for q in questions_text.split('\n') if q.strip()]
+            
+            return [{"question": q, "bloom_level": bloom_level} for q in question_list[:2]]
+        except Exception as e:
+            print(f"Error generating questions by Bloom level: {e}")
+            return []
+    
+    def _generate_related_concept_questions(self, answer: str) -> List[Dict[str, str]]:
+        """Generate questions about related concepts"""
+        try:
+            prompt = f"""Based on the following answer, generate 1 question about a related ADAS concept that would help the user understand the broader context.
+
+Answer:
+{answer[:500]}
+
+Generate 1 question about a related concept or feature that connects to the information provided.
+
+Question:"""
+            
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are an educational assistant."},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=0.7,
+                max_tokens=100
+            )
+            
+            question = response.choices[0].message.content.strip().strip('"').strip("'")
+            return [{"question": question, "bloom_level": "understand"}]
+        except Exception as e:
+            print(f"Error generating related concept question: {e}")
+            return []
+
+
+class ProactiveLearningEngine:
+    """Main engine for proactive learning assistance"""
+    
+    def __init__(self, client: OpenAI, rag_engine, user_profiling, adaptive_engine=None, 
+                 available_topics: List[str] = None):
+        self.client = client
+        self.rag_engine = rag_engine
+        self.user_profiling = user_profiling
+        self.adaptive_engine = adaptive_engine
+        self.available_topics = available_topics or []
+        
+        # Initialize components
+        self.gap_analyzer = KnowledgeGapAnalyzer(self.available_topics)
+        self.suggestion_generator = PromptSuggestionGenerator(
+            client, rag_engine, self.gap_analyzer, self.available_topics
+        )
+        self.followup_generator = FollowUpQuestionGenerator(client, rag_engine)
+    
+    def get_prompt_suggestions(self, user_id: str, context: Optional[str] = None, 
+                              max_suggestions: int = 5) -> List[Dict[str, str]]:
+        """
+        Get prompt suggestions for a user
+        
+        Args:
+            user_id: User ID
+            context: Optional context (e.g., recent question)
+            max_suggestions: Maximum number of suggestions
+            
+        Returns:
+            List of suggestion dictionaries
+        """
+        if not self.user_profiling:
+            return []
+        
+        user_profile = self.user_profiling.get_or_create_profile(user_id)
+        
+        # Get learning path if available
+        learning_path = None
+        if self.adaptive_engine:
+            learning_path = self.adaptive_engine.get_active_path(user_id)
+        
+        return self.suggestion_generator.generate_suggestions(
+            user_id, user_profile, learning_path, context, max_suggestions
+        )
+    
+    def get_follow_up_questions(self, user_id: str, answer: str, 
+                                max_questions: int = 5) -> List[Dict[str, str]]:
+        """
+        Get follow-up questions based on an answer
+        
+        Args:
+            user_id: User ID
+            answer: The RAG answer text
+            max_questions: Maximum number of questions
+            
+        Returns:
+            List of question dictionaries
+        """
+        if not self.user_profiling:
+            return []
+        
+        user_profile = self.user_profiling.get_or_create_profile(user_id)
+        return self.followup_generator.generate_follow_up_questions(
+            answer, user_profile, max_questions
+        )
+    
+    def get_critical_gaps(self, user_id: str) -> List[str]:
+        """
+        Get critical knowledge gaps for a user
+        
+        Args:
+            user_id: User ID
+            
+        Returns:
+            List of topics with critical gaps
+        """
+        if not self.user_profiling:
+            return []
+        
+        user_profile = self.user_profiling.get_or_create_profile(user_id)
+        return self.gap_analyzer.identify_critical_gaps(user_profile)
+    
+    def analyze_user_state(self, user_id: str) -> Dict:
+        """
+        Analyze user's current learning state
+        
+        Args:
+            user_id: User ID
+            
+        Returns:
+            Dictionary with analysis results
+        """
+        if not self.user_profiling:
+            return {}
+        
+        user_profile = self.user_profiling.get_or_create_profile(user_id)
+        
+        critical_gaps = self.gap_analyzer.identify_critical_gaps(user_profile)
+        weak_areas = self.gap_analyzer.identify_weak_areas(user_profile)
+        gap_priorities = self.gap_analyzer.get_gap_priority(user_profile)
+        
+        return {
+            "critical_gaps": critical_gaps,
+            "weak_areas": weak_areas,
+            "gap_priorities": gap_priorities[:5],  # Top 5
+            "total_gaps": len(weak_areas),
+            "critical_gaps_count": len(critical_gaps)
+        }
+

modules/scenario_contextualization/__init__.py

@@ -0,0 +1,5 @@
+"""
+Scenario-Based Contextualization Module
+Provides scenario context integration for ADAS RAG system
+"""
+

modules/scenario_contextualization/database/__init__.py

@@ -0,0 +1,4 @@
+"""
+Scenario Database Module
+"""
+

modules/scenario_contextualization/database/scenario_database.py

@@ -0,0 +1,105 @@
+"""
+Scenario Database Management
+"""
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+from collections import defaultdict
+
+from .scenario_models import ADASScenario
+
+
+class ScenarioDatabase:
+    """Scenario database management"""
+    
+    def __init__(self, data_file: str = "data/scenarios/initial_scenarios.json"):
+        self.data_file = Path(data_file)
+        self.scenarios: Dict[str, ADASScenario] = {}
+        self.index = {}
+        self._load_scenarios()
+        self._build_index()
+    
+    def _load_scenarios(self):
+        """Load scenarios from JSON file"""
+        if not self.data_file.exists():
+            print(f"⚠️ Scenario database file not found: {self.data_file}")
+            print("   Run 'python scripts/create_initial_scenarios.py' to create initial scenarios")
+            return
+        
+        try:
+            with open(self.data_file, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+            
+            scenarios_list = data.get("scenarios", [])
+            for scenario_data in scenarios_list:
+                scenario = ADASScenario.from_dict(scenario_data)
+                self.scenarios[scenario.scenario_id] = scenario
+            
+            print(f"✅ Loaded {len(self.scenarios)} scenarios from {self.data_file}")
+        except Exception as e:
+            print(f"❌ Error loading scenarios: {e}")
+    
+    def _build_index(self):
+        """Build index to speed up queries"""
+        self.index = {
+            'by_feature': defaultdict(list),
+            'by_type': defaultdict(list),
+            'by_source': defaultdict(list),
+            'by_tag': defaultdict(list)
+        }
+        
+        for scenario in self.scenarios.values():
+            self.index['by_feature'][scenario.adas_feature].append(scenario.scenario_id)
+            self.index['by_type'][scenario.scenario_type].append(scenario.scenario_id)
+            for source in scenario.source:
+                self.index['by_source'][source].append(scenario.scenario_id)
+            for tag in scenario.tags:
+                self.index['by_tag'][tag].append(scenario.scenario_id)
+    
+    def get_by_id(self, scenario_id: str) -> Optional[ADASScenario]:
+        """Get scenario by ID"""
+        return self.scenarios.get(scenario_id)
+    
+    def get_all(self) -> List[ADASScenario]:
+        """Get all scenarios"""
+        return list(self.scenarios.values())
+    
+    def filter_by_features(self, features: List[str]) -> List[ADASScenario]:
+        """Filter scenarios by ADAS features"""
+        if not features:
+            return []
+        
+        scenario_ids = set()
+        for feature in features:
+            if feature in self.index['by_feature']:
+                scenario_ids.update(self.index['by_feature'][feature])
+        
+        return [self.scenarios[sid] for sid in scenario_ids if sid in self.scenarios]
+    
+    def filter_by_type(self, scenario_type: str) -> List[ADASScenario]:
+        """Filter scenarios by type"""
+        scenario_ids = self.index['by_type'].get(scenario_type, [])
+        return [self.scenarios[sid] for sid in scenario_ids if sid in self.scenarios]
+    
+    def full_text_search(self, query: str, top_k: int = 10) -> List[ADASScenario]:
+        """Simple full-text search (based on keyword matching)"""
+        query_lower = query.lower()
+        query_words = set(query_lower.split())
+        
+        scored_scenarios = []
+        for scenario in self.scenarios.values():
+            # Calculate match score
+            text = f"{scenario.title} {scenario.description} {' '.join(scenario.tags)}".lower()
+            text_words = set(text.split())
+            
+            # Calculate intersection
+            matches = len(query_words & text_words)
+            if matches > 0:
+                score = matches / len(query_words)  # Simple match rate
+                scored_scenarios.append((score, scenario))
+        
+        # Sort and return top k
+        scored_scenarios.sort(key=lambda x: x[0], reverse=True)
+        return [s for _, s in scored_scenarios[:top_k]]
+

modules/scenario_contextualization/database/scenario_models.py

@@ -0,0 +1,153 @@
+"""
+Scenario Data Models
+"""
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict
+from datetime import datetime
+
+
+@dataclass
+class BoundaryCondition:
+    """Boundary condition"""
+    condition: str  # Condition description
+    impact: str     # Impact description
+    details: Optional[str] = None  # Additional details
+
+
+@dataclass
+class AppropriateResponse:
+    """Appropriate response"""
+    response: str    # Response action
+    rationale: str  # Rationale
+    details: Optional[str] = None  # Additional details
+
+
+@dataclass
+class ScenarioMetadata:
+    """Scenario metadata"""
+    created_at: str
+    updated_at: str
+    views: int = 0
+    quality_score: float = 0.0
+    verified: bool = False
+    source_urls: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ADASScenario:
+    """Complete ADAS scenario data model"""
+    # Basic information
+    scenario_id: str
+    title: str
+    description: str
+    
+    # Classification information
+    adas_feature: str  # Related ADAS feature
+    scenario_type: str  # "boundary_condition", "historical_incident", "hypothetical_edge_case"
+    source: List[str]  # Data source
+    severity_level: str  # "low", "medium", "high"
+    
+    # Scenario content
+    boundary_conditions: List[BoundaryCondition]
+    appropriate_responses: List[AppropriateResponse]
+    educational_principles: List[str]
+    
+    # Generalization information
+    manufacturer_specific: bool
+    generalization: str  # Generalized universal principle
+    
+    # Metadata (must come before fields with default values)
+    metadata: ScenarioMetadata
+    
+    # Related information (fields with default values must come last)
+    related_features: List[str] = field(default_factory=list)
+    related_scenarios: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> 'ADASScenario':
+        """Create scenario object from dictionary"""
+        # Convert boundary conditions
+        boundary_conditions = [
+            BoundaryCondition(**bc) if isinstance(bc, dict) else bc
+            for bc in data.get("boundary_conditions", [])
+        ]
+        
+        # Convert appropriate responses
+        appropriate_responses = [
+            AppropriateResponse(**ar) if isinstance(ar, dict) else ar
+            for ar in data.get("appropriate_responses", [])
+        ]
+        
+        # Convert metadata
+        metadata = ScenarioMetadata(**data.get("metadata", {}))
+        
+        return cls(
+            scenario_id=data["scenario_id"],
+            title=data["title"],
+            description=data["description"],
+            adas_feature=data["adas_feature"],
+            scenario_type=data["scenario_type"],
+            source=data.get("source", []),
+            severity_level=data.get("severity_level", "medium"),
+            boundary_conditions=boundary_conditions,
+            appropriate_responses=appropriate_responses,
+            educational_principles=data.get("educational_principles", []),
+            manufacturer_specific=data.get("manufacturer_specific", False),
+            generalization=data.get("generalization", ""),
+            metadata=metadata,
+            related_features=data.get("related_features", []),
+            related_scenarios=data.get("related_scenarios", []),
+            tags=data.get("tags", [])
+        )
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return {
+            "scenario_id": self.scenario_id,
+            "title": self.title,
+            "description": self.description,
+            "adas_feature": self.adas_feature,
+            "scenario_type": self.scenario_type,
+            "source": self.source,
+            "severity_level": self.severity_level,
+            "boundary_conditions": [
+                {
+                    "condition": bc.condition,
+                    "impact": bc.impact,
+                    "details": bc.details
+                }
+                for bc in self.boundary_conditions
+            ],
+            "appropriate_responses": [
+                {
+                    "response": ar.response,
+                    "rationale": ar.rationale,
+                    "details": ar.details
+                }
+                for ar in self.appropriate_responses
+            ],
+            "educational_principles": self.educational_principles,
+            "manufacturer_specific": self.manufacturer_specific,
+            "generalization": self.generalization,
+            "related_features": self.related_features,
+            "related_scenarios": self.related_scenarios,
+            "tags": self.tags,
+            "metadata": {
+                "created_at": self.metadata.created_at,
+                "updated_at": self.metadata.updated_at,
+                "views": self.metadata.views,
+                "quality_score": self.metadata.quality_score,
+                "verified": self.metadata.verified,
+                "source_urls": self.metadata.source_urls
+            }
+        }
+
+
+@dataclass
+class RankedScenario:
+    """Scenario with relevance score"""
+    scenario: ADASScenario
+    relevance_score: float
+    match_reasons: List[str] = field(default_factory=list)
+

modules/scenario_contextualization/formatting/__init__.py

@@ -0,0 +1,4 @@
+"""
+Scenario Formatting Module
+"""
+

modules/scenario_contextualization/formatting/constructive_formatter.py

@@ -0,0 +1,152 @@
+"""
+Constructive Scenario Formatter
+Formats scenarios in an educational, constructive way
+"""
+from typing import List
+from ..database.scenario_models import ADASScenario, RankedScenario
+
+
+class FormattedScenario:
+    """Formatted scenario"""
+    def __init__(
+        self,
+        title: str,
+        adas_feature: str,
+        boundary_conditions: List[str],
+        appropriate_responses: List[str],
+        educational_principle: str,
+        relevance_hint: str = "",
+        full_scenario_link: str = ""
+    ):
+        self.title = title
+        self.adas_feature = adas_feature
+        self.boundary_conditions = boundary_conditions
+        self.appropriate_responses = appropriate_responses
+        self.educational_principle = educational_principle
+        self.relevance_hint = relevance_hint
+        self.full_scenario_link = full_scenario_link
+
+
+class ConstructiveFormatter:
+    """Constructive scenario formatter"""
+    
+    def format_scenario(self, ranked_scenario: RankedScenario) -> FormattedScenario:
+        """
+        Format a single scenario
+        
+        Principles:
+        - Avoid detailed incident descriptions
+        - Emphasize boundary conditions and appropriate responses
+        - Provide educational principles
+        - Use positive, constructive language
+        """
+        scenario = ranked_scenario.scenario
+        
+        # Format boundary conditions
+        boundary_conditions = self._format_boundary_conditions(scenario)
+        
+        # Format appropriate responses
+        appropriate_responses = self._format_responses(scenario)
+        
+        # Extract educational principle
+        educational_principle = self._format_principle(scenario)
+        
+        # Generate relevance hint
+        relevance_hint = self._generate_relevance_hint(ranked_scenario)
+        
+        return FormattedScenario(
+            title=scenario.title,
+            adas_feature=scenario.adas_feature,
+            boundary_conditions=boundary_conditions,
+            appropriate_responses=appropriate_responses,
+            educational_principle=educational_principle,
+            relevance_hint=relevance_hint,
+            full_scenario_link=f"/scenario/{scenario.scenario_id}"
+        )
+    
+    def _format_boundary_conditions(self, scenario: ADASScenario) -> List[str]:
+        """Format boundary conditions using constructive language"""
+        formatted = []
+        for bc in scenario.boundary_conditions:
+            # Use constructive language: emphasize "may" rather than "failed"
+            condition_text = f"• {bc.condition}: {bc.impact}"
+            if bc.details:
+                condition_text += f" ({bc.details})"
+            formatted.append(condition_text)
+        return formatted
+    
+    def _format_responses(self, scenario: ADASScenario) -> List[str]:
+        """Format appropriate responses, emphasizing correct actions"""
+        formatted = []
+        for ar in scenario.appropriate_responses:
+            response_text = f"• {ar.response}: {ar.rationale}"
+            if ar.details:
+                response_text += f" ({ar.details})"
+            formatted.append(response_text)
+        return formatted
+    
+    def _format_principle(self, scenario: ADASScenario) -> str:
+        """Format educational principle"""
+        if scenario.educational_principles:
+            # Use first principle, or combine multiple principles
+            if len(scenario.educational_principles) == 1:
+                return scenario.educational_principles[0]
+            else:
+                return " ".join(scenario.educational_principles[:2])  # Max two principles
+        elif scenario.generalization:
+            return scenario.generalization
+        else:
+            return "Understanding system limitations helps ensure safe operation."
+    
+    def _generate_relevance_hint(self, ranked_scenario: RankedScenario) -> str:
+        """Generate relevance hint"""
+        if ranked_scenario.match_reasons:
+            reasons = ", ".join(ranked_scenario.match_reasons[:2])  # Max two reasons
+            return f"Relevant because: {reasons}"
+        return ""
+    
+    def format_scenarios_for_ui(self, ranked_scenarios: List[RankedScenario]) -> str:
+        """
+        Format multiple scenarios as HTML for UI display
+        
+        Returns:
+            str: HTML formatted scenario cards
+        """
+        if not ranked_scenarios:
+            return ""
+        
+        formatted_scenarios = [self.format_scenario(rs) for rs in ranked_scenarios]
+        
+        html_parts = []
+        for i, fs in enumerate(formatted_scenarios, 1):
+            scenario_html = f"""
+            <div style="margin-bottom: 20px; padding: 15px; border: 1px solid #ddd; border-radius: 8px; background-color: #f9f9f9;">
+                <h4 style="margin-top: 0; color: #333;">{fs.title}</h4>
+                <p style="margin: 5px 0; color: #666; font-size: 0.9em;">Related to: <strong>{fs.adas_feature}</strong></p>
+                
+                <div style="margin: 15px 0;">
+                    <strong style="color: #d9534f;">⚠️ Boundary Conditions:</strong>
+                    <ul style="margin: 5px 0; padding-left: 20px;">
+                        {''.join(f'<li style="margin: 5px 0;">{bc}</li>' for bc in fs.boundary_conditions)}
+                    </ul>
+                </div>
+                
+                <div style="margin: 15px 0;">
+                    <strong style="color: #5cb85c;">✅ Appropriate Responses:</strong>
+                    <ul style="margin: 5px 0; padding-left: 20px;">
+                        {''.join(f'<li style="margin: 5px 0;">{ar}</li>' for ar in fs.appropriate_responses)}
+                    </ul>
+                </div>
+                
+                <div style="margin: 15px 0;">
+                    <strong style="color: #337ab7;">📖 Educational Principle:</strong>
+                    <p style="margin: 5px 0; font-style: italic;">{fs.educational_principle}</p>
+                </div>
+                
+                {f'<p style="margin: 5px 0; font-size: 0.85em; color: #999;">{fs.relevance_hint}</p>' if fs.relevance_hint else ''}
+            </div>
+            """
+            html_parts.append(scenario_html)
+        
+        return "".join(html_parts)
+

modules/scenario_contextualization/integration/__init__.py

@@ -0,0 +1,4 @@
+"""
+Scenario Integration Module
+"""
+

modules/scenario_contextualization/integration/enhanced_rag_engine.py

@@ -0,0 +1,94 @@
+"""
+Enhanced RAG Engine
+Integrates scenario contextualization into RAG queries
+"""
+from typing import Tuple, Optional
+from openai import OpenAI
+
+from src.rag_query import RAGQueryEngine
+from .feature_extractor import ADASFeatureExtractor
+from ..retrieval.scenario_retriever import ScenarioRetriever
+from ..formatting.constructive_formatter import ConstructiveFormatter
+
+
+class EnhancedAnswer:
+    """Enhanced answer with scenario context"""
+    def __init__(
+        self,
+        answer: str,
+        sources: str,
+        scenarios_html: Optional[str] = None,
+        scenario_count: int = 0
+    ):
+        self.answer = answer
+        self.sources = sources
+        self.scenarios_html = scenarios_html
+        self.scenario_count = scenario_count
+
+
+class EnhancedRAGEngine:
+    """
+    Enhanced RAG engine with scenario contextualization integration
+    """
+    def __init__(
+        self,
+        base_rag_engine: RAGQueryEngine,
+        scenario_retriever: ScenarioRetriever,
+        feature_extractor: ADASFeatureExtractor,
+        formatter: ConstructiveFormatter
+    ):
+        self.base_rag = base_rag_engine
+        self.scenario_retriever = scenario_retriever
+        self.feature_extractor = feature_extractor
+        self.formatter = formatter
+    
+    def query(
+        self,
+        query: str,
+        user_id: Optional[str] = None,
+        user_context: Optional[dict] = None
+    ) -> EnhancedAnswer:
+        """
+        Execute enhanced query
+        
+        Args:
+            query: User query
+            user_id: User ID (optional, for personalization)
+            user_context: User context (optional)
+        
+        Returns:
+            EnhancedAnswer: Contains standard answer and scenario context
+        """
+        # 1. Standard RAG query
+        base_answer, sources = self.base_rag.query(query)
+        
+        # 2. Extract ADAS features
+        adas_features = self.feature_extractor.extract(query)
+        
+        # 3. Retrieve relevant scenarios (if related features found)
+        scenarios_html = None
+        scenario_count = 0
+        if adas_features:
+            try:
+                ranked_scenarios = self.scenario_retriever.retrieve(
+                    query=query,
+                    adas_features=adas_features,
+                    max_results=3,
+                    user_context=user_context
+                )
+                
+                if ranked_scenarios:
+                    # 4. Format scenarios
+                    scenarios_html = self.formatter.format_scenarios_for_ui(ranked_scenarios)
+                    scenario_count = len(ranked_scenarios)
+            except Exception as e:
+                print(f"⚠️ Error retrieving scenarios: {e}")
+                # Continue execution, scenario retrieval failure doesn't affect standard answer
+        
+        return EnhancedAnswer(
+            answer=base_answer,
+            sources=sources,
+            scenarios_html=scenarios_html,
+            scenario_count=scenario_count
+        )
+

modules/scenario_contextualization/integration/feature_extractor.py

@@ -0,0 +1,95 @@
+"""
+ADAS Feature Extractor
+Extracts ADAS features from user queries
+"""
+import json
+from typing import List, Optional
+from openai import OpenAI
+
+
+# ADAS feature keywords mapping
+ADAS_FEATURES_KEYWORDS = {
+    "DISTRONIC": ["distronic", "distance assist", "adaptive cruise", "acc", "cruise control", "following distance"],
+    "Active Lane Change Assist": ["lane change", "lca", "lane change assist", "change lane", "lane switching"],
+    "Active Steering Assist": ["steering assist", "lane keeping", "lka", "lane keep", "steering", "lane centering"],
+    "Active Stop-and-Go Assist": ["stop and go", "traffic jam", "low speed", "stop-and-go", "traffic assist"]
+}
+
+
+class ADASFeatureExtractor:
+    """ADAS feature extractor"""
+    
+    def __init__(self, use_llm: bool = False, client: Optional[OpenAI] = None):
+        """
+        Args:
+            use_llm: Whether to use LLM extraction (more accurate but slower)
+            client: OpenAI client (if use_llm=True)
+        """
+        self.use_llm = use_llm
+        self.client = client
+    
+    def extract(self, query: str) -> List[str]:
+        """
+        Extract ADAS features from query
+        
+        Args:
+            query: User query text
+        
+        Returns:
+            List[str]: List of extracted ADAS features
+        """
+        if self.use_llm and self.client:
+            return self._extract_with_llm(query)
+        else:
+            return self._extract_with_keywords(query)
+    
+    def _extract_with_keywords(self, query: str) -> List[str]:
+        """Extract features using keyword matching (fast method)"""
+        query_lower = query.lower()
+        matched_features = []
+        
+        for feature, keywords in ADAS_FEATURES_KEYWORDS.items():
+            if any(kw in query_lower for kw in keywords):
+                matched_features.append(feature)
+        
+        return matched_features
+    
+    def _extract_with_llm(self, query: str) -> List[str]:
+        """Extract features using LLM (more accurate method)"""
+        if not self.client:
+            return self._extract_with_keywords(query)
+        
+        try:
+            available_features = list(ADAS_FEATURES_KEYWORDS.keys())
+            
+            prompt = f"""
+            Extract ADAS features mentioned in this query: "{query}"
+            
+            Available features:
+            {chr(10).join(f'- {f}' for f in available_features)}
+            
+            Return a JSON object with a "features" array containing the feature names.
+            If no features are mentioned, return an empty array.
+            """
+            
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are an expert in ADAS systems. Extract ADAS features from user queries."},
+                    {"role": "user", "content": prompt}
+                ],
+                response_format={"type": "json_object"},
+                temperature=0.1
+            )
+            
+            result = json.loads(response.choices[0].message.content)
+            features = result.get("features", [])
+            
+            # Validate extracted features against available list
+            valid_features = [f for f in features if f in available_features]
+            return valid_features if valid_features else self._extract_with_keywords(query)
+            
+        except Exception as e:
+            print(f"⚠️ Error in LLM feature extraction: {e}")
+            return self._extract_with_keywords(query)
+

modules/scenario_contextualization/retrieval/__init__.py

@@ -0,0 +1,4 @@
+"""
+Scenario Retrieval Module
+"""
+

modules/scenario_contextualization/retrieval/scenario_retriever.py

@@ -0,0 +1,154 @@
+"""
+Scenario Retriever
+Retrieves relevant scenarios using semantic search and feature filtering
+"""
+from typing import List, Optional, Dict
+from openai import OpenAI
+
+from ..database.scenario_database import ScenarioDatabase
+from ..database.scenario_models import ADASScenario, RankedScenario
+
+
+class ScenarioRetriever:
+    """Scenario retrieval engine"""
+    
+    def __init__(
+        self,
+        scenario_database: ScenarioDatabase,
+        scenario_vector_store_id: Optional[str] = None,
+        client: Optional[OpenAI] = None
+    ):
+        """
+        Args:
+            scenario_database: Scenario database
+            scenario_vector_store_id: Scenario vector store ID (optional, if using semantic search)
+            client: OpenAI client (if using vector search)
+        """
+        self.database = scenario_database
+        self.vector_store_id = scenario_vector_store_id
+        self.client = client
+    
+    def retrieve(
+        self,
+        query: str,
+        adas_features: List[str],
+        max_results: int = 3,
+        user_context: Optional[Dict] = None
+    ) -> List[RankedScenario]:
+        """
+        Retrieve relevant scenarios
+        
+        Args:
+            query: User query
+            adas_features: List of extracted ADAS features
+            max_results: Maximum number of results to return
+            user_context: User context (optional, for personalization)
+        
+        Returns:
+            List[RankedScenario]: Sorted list of scenarios
+        """
+        # 1. Feature filtering
+        feature_filtered = self.database.filter_by_features(adas_features)
+        
+        # 2. Full-text search (if feature filtering results are insufficient)
+        if len(feature_filtered) < max_results:
+            text_results = self.database.full_text_search(query, top_k=max_results * 2)
+            # Merge results
+            all_candidates = list(set(feature_filtered + text_results))
+        else:
+            all_candidates = feature_filtered
+        
+        # 3. Relevance scoring
+        scored = self._score_relevance(all_candidates, query, adas_features)
+        
+        # 4. User context adjustment (if available)
+        if user_context:
+            scored = self._adjust_for_user_context(scored, user_context)
+        
+        # 5. Sort and return top N
+        scored.sort(key=lambda x: x.relevance_score, reverse=True)
+        return scored[:max_results]
+    
+    def _score_relevance(
+        self,
+        scenarios: List[ADASScenario],
+        query: str,
+        adas_features: List[str]
+    ) -> List[RankedScenario]:
+        """
+        Calculate scenario relevance score
+        
+        Factors:
+        1. Feature match (30%)
+        2. Text similarity (40%)
+        3. Scenario type weight (20%)
+        4. Scenario quality score (10%)
+        """
+        ranked = []
+        query_lower = query.lower()
+        
+        for scenario in scenarios:
+            score = 0.0
+            match_reasons = []
+            
+            # 1. Feature match (30%)
+            feature_weight = 0.3
+            if scenario.adas_feature in adas_features:
+                feature_match = 1.0
+                match_reasons.append(f"Matches feature: {scenario.adas_feature}")
+            else:
+                feature_match = 0.0
+            score += feature_match * feature_weight
+            
+            # 2. Text similarity (40%)
+            semantic_weight = 0.4
+            # Simple keyword matching
+            scenario_text = f"{scenario.title} {scenario.description} {' '.join(scenario.tags)}".lower()
+            query_words = set(query_lower.split())
+            scenario_words = set(scenario_text.split())
+            common_words = query_words & scenario_words
+            if query_words:
+                text_similarity = len(common_words) / len(query_words)
+                if text_similarity > 0.1:
+                    match_reasons.append(f"Text similarity: {text_similarity:.2f}")
+            else:
+                text_similarity = 0.0
+            score += text_similarity * semantic_weight
+            
+            # 3. Scenario type weight (20%)
+            type_weight = 0.2
+            type_weights = {
+                "boundary_condition": 1.0,
+                "historical_incident": 0.8,
+                "hypothetical_edge_case": 0.9
+            }
+            type_score = type_weights.get(scenario.scenario_type, 0.5)
+            score += type_score * type_weight
+            
+            # 4. Scenario quality score (10%)
+            quality_weight = 0.1
+            quality_score = scenario.metadata.quality_score
+            score += quality_score * quality_weight
+            
+            ranked.append(RankedScenario(
+                scenario=scenario,
+                relevance_score=score,
+                match_reasons=match_reasons
+            ))
+        
+        return ranked
+    
+    def _adjust_for_user_context(
+        self,
+        ranked_scenarios: List[RankedScenario],
+        user_context: Dict
+    ) -> List[RankedScenario]:
+        """
+        Adjust relevance scores based on user context
+        
+        Example: If user is a beginner, prioritize basic scenarios
+        """
+        # Personalization adjustment logic can be implemented here
+        # Currently returns as-is
+        return ranked_scenarios
+