Upload 35 files

app.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+🎓 Course Creator AI - Main Application Entry Point
+
+Launch the Gradio interface for course generation.
+
+Made with ❤️ by Pink Pixel
+"Dream it, Pixel it" ✨
+"""
+
+import os
+import sys
+import gradio as gr
+from pathlib import Path
+
+# Add the project root to Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+from coursecrafter.ui.gradio_app import create_coursecrafter_interface
+from coursecrafter.utils.config import config
+
+
+def setup_backend_credentials():
+    """Set up backend credentials for image generation"""
+    # Set up Pollinations credentials for image generation
+    if not os.getenv("POLLINATIONS_API_REFERENCE"):
+        os.environ["POLLINATIONS_API_REFERENCE"] = "course-creator-ai-hf"
+    
+    print("🎨 Backend image generation credentials configured")
+
+
+def main():
+    """Main application entry point"""
+    print("🎓 Starting Course Creator AI...")
+    
+    # Set up backend credentials
+    setup_backend_credentials()
+
+    # Create and launch the Gradio interface
+    try:
+        interface = create_coursecrafter_interface()
+
+        # Launch configuration
+        launch_kwargs = {
+            "server_name": "0.0.0.0",
+            "server_port": 7860,
+            "share": False,
+            "show_error": True,
+            "quiet": False
+        }
+
+        # Check if running in Hugging Face Spaces
+        if os.getenv("SPACE_ID"):
+            print("🚀 Running in Hugging Face Spaces")
+            launch_kwargs["share"] = True
+        else:
+            print("🖥️  Running locally")
+
+        print("🌐 Launching Course Creator AI interface...")
+        interface.launch(**launch_kwargs)
+
+    except Exception as e:
+        print(f"❌ Failed to launch application: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

coursecrafter/__init__.py

@@ -0,0 +1,21 @@
+"""
+🎓 Course Creator AI - Intelligent Course Generation Agent
+
+Transform any topic into a complete, structured mini-course with interactive learning materials.
+
+Made with ❤️ by Pink Pixel
+"Dream it, Pixel it" ✨
+"""
+
+__version__ = "1.0.0"
+__author__ = "Pink Pixel"
+__email__ = "[email protected]"
+__description__ = "Course Creator AI is an intelligent agent that generates structured mini-courses from any topic, complete with interactive learning materials."
+
+from .agents.simple_course_agent import SimpleCourseAgent
+from .ui.gradio_app import create_coursecrafter_interface
+
+__all__ = [
+    "SimpleCourseAgent",
+    "create_coursecrafter_interface"
+]

coursecrafter/agents/__init__.py

@@ -0,0 +1,13 @@
+"""
+🧠 Agent Components
+
+Core agent classes for course generation.
+"""
+
+from .simple_course_agent import SimpleCourseAgent
+from .llm_client import LlmClient
+
+__all__ = [
+    "SimpleCourseAgent",
+    "LlmClient"
+]

coursecrafter/agents/llm_client.py

@@ -0,0 +1,270 @@
+"""
+🧠 LLM Client for CourseCrafter AI
+
+Multi-provider LLM client with streaming support.
+"""
+
+import json
+from typing import Dict, List, Any, Optional, AsyncGenerator
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+
+import openai
+import anthropic
+import google.generativeai as genai
+
+from ..types import LLMProvider, StreamChunk
+from ..utils.config import config
+
+
+@dataclass
+class Message:
+    """Standard message format"""
+    role: str  # "system", "user", "assistant"
+    content: str
+
+
+class BaseLLMClient(ABC):
+    """Abstract base class for LLM clients"""
+
+    def __init__(self, provider: LLMProvider):
+        self.provider = provider
+        self.config = config.get_llm_config(provider)
+
+    @abstractmethod
+    async def generate_stream(self, messages: List[Message]) -> AsyncGenerator[StreamChunk, None]:
+        """Generate streaming response"""
+        pass
+
+
+class OpenAIClient(BaseLLMClient):
+    """OpenAI client with streaming support (works with OpenAI and compatible endpoints)"""
+
+    def __init__(self, provider: LLMProvider = "openai"):
+        super().__init__(provider)
+
+        # Build client kwargs
+        client_kwargs = {
+            "api_key": self.config.api_key or "dummy",
+            "timeout": self.config.timeout
+        }
+
+        # Add base_url for compatible endpoints
+        if hasattr(self.config, 'base_url') and self.config.base_url:
+            client_kwargs["base_url"] = self.config.base_url
+
+        self.client = openai.AsyncOpenAI(**client_kwargs)
+
+    def _format_messages(self, messages: List[Message]) -> List[Dict[str, Any]]:
+        """Format messages for OpenAI"""
+        return [{"role": msg.role, "content": msg.content} for msg in messages]
+
+    async def generate_stream(self, messages: List[Message]) -> AsyncGenerator[StreamChunk, None]:
+        """Generate streaming response from OpenAI"""
+
+        formatted_messages = self._format_messages(messages)
+
+        kwargs = {
+            "model": self.config.model,
+            "messages": formatted_messages,
+            "temperature": self.config.temperature,
+            "stream": True
+        }
+
+        if self.config.max_tokens:
+            kwargs["max_tokens"] = self.config.max_tokens
+
+        try:
+            stream = await self.client.chat.completions.create(**kwargs)
+
+            async for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta:
+                    delta = chunk.choices[0].delta
+
+                    if delta.content:
+                        yield StreamChunk(
+                            type="text",
+                            content=delta.content
+                        )
+
+        except Exception as e:
+            yield StreamChunk(
+                type="error",
+                content=f"OpenAI API error: {str(e)}"
+            )
+
+
+
+
+class AnthropicClient(BaseLLMClient):
+    """Anthropic client with streaming support"""
+
+    def __init__(self):
+        super().__init__("anthropic")
+        self.client = anthropic.AsyncAnthropic(
+            api_key=self.config.api_key,
+            timeout=self.config.timeout
+        )
+
+    def _format_messages(self, messages: List[Message]) -> tuple[List[Dict[str, Any]], Optional[str]]:
+        """Format messages for Anthropic"""
+        formatted = []
+        system_message = None
+
+        for msg in messages:
+            if msg.role == "system":
+                system_message = msg.content
+            elif msg.role in ["user", "assistant"]:
+                formatted.append({
+                    "role": msg.role,
+                    "content": msg.content
+                })
+
+        return formatted, system_message
+
+    async def generate_stream(self, messages: List[Message]) -> AsyncGenerator[StreamChunk, None]:
+        """Generate streaming response from Anthropic"""
+
+        formatted_messages, system_message = self._format_messages(messages)
+
+        kwargs = {
+            "model": self.config.model,
+            "messages": formatted_messages,
+            "temperature": self.config.temperature,
+            "stream": True
+        }
+
+        if system_message:
+            kwargs["system"] = system_message
+
+        if self.config.max_tokens:
+            kwargs["max_tokens"] = self.config.max_tokens
+
+        try:
+            stream = await self.client.messages.create(**kwargs)
+
+            async for chunk in stream:
+                if chunk.type == "content_block_delta":
+                    if hasattr(chunk.delta, 'text'):
+                        yield StreamChunk(
+                            type="text",
+                            content=chunk.delta.text
+                        )
+
+        except Exception as e:
+            yield StreamChunk(
+                type="error",
+                content=f"Anthropic API error: {str(e)}"
+            )
+
+
+class GoogleClient(BaseLLMClient):
+    """Google Gemini client with streaming support"""
+
+    def __init__(self):
+        super().__init__("google")
+        genai.configure(api_key=self.config.api_key)
+        self.model = genai.GenerativeModel(self.config.model)
+
+    def _format_messages(self, messages: List[Message]) -> List[Dict[str, Any]]:
+        """Format messages for Google"""
+        formatted = []
+
+        for msg in messages:
+            if msg.role == "system":
+                # Google handles system messages differently
+                formatted.append({
+                    "role": "user",
+                    "parts": [{"text": f"System: {msg.content}"}]
+                })
+            elif msg.role == "user":
+                formatted.append({
+                    "role": "user",
+                    "parts": [{"text": msg.content}]
+                })
+            elif msg.role == "assistant":
+                formatted.append({
+                    "role": "model",
+                    "parts": [{"text": msg.content}]
+                })
+
+        return formatted
+
+    async def generate_stream(self, messages: List[Message]) -> AsyncGenerator[StreamChunk, None]:
+        """Generate streaming response from Google"""
+
+        formatted_messages = self._format_messages(messages)
+
+        generation_config = {
+            "temperature": self.config.temperature,
+        }
+
+        if self.config.max_tokens:
+            generation_config["max_output_tokens"] = self.config.max_tokens
+
+        try:
+            response = await self.model.generate_content_async(
+                formatted_messages,
+                generation_config=generation_config,
+                stream=True
+            )
+
+            async for chunk in response:
+                if chunk.text:
+                    yield StreamChunk(
+                        type="text",
+                        content=chunk.text
+                    )
+
+        except Exception as e:
+            yield StreamChunk(
+                type="error",
+                content=f"Google API error: {str(e)}"
+            )
+
+
+class LlmClient:
+    """
+    Unified LLM client that manages multiple providers
+    """
+
+    def __init__(self):
+        self.clients = {}
+        self._initialize_clients()
+
+    def _initialize_clients(self):
+        """Initialize available LLM clients"""
+        available_providers = config.get_available_llm_providers()
+
+        for provider in available_providers:
+            try:
+                if provider in ["openai", "openai_compatible"]:
+                    self.clients[provider] = OpenAIClient(provider)
+                elif provider == "anthropic":
+                    self.clients[provider] = AnthropicClient()
+                elif provider == "google":
+                    self.clients[provider] = GoogleClient()
+
+                print(f"✅ Initialized {provider} client")
+            except Exception as e:
+                print(f"❌ Failed to initialize {provider} client: {e}")
+
+    def get_available_providers(self) -> List[LLMProvider]:
+        """Get list of available providers"""
+        return list(self.clients.keys())
+
+    def get_client(self, provider: LLMProvider) -> BaseLLMClient:
+        """Get client for specific provider"""
+        if provider not in self.clients:
+            raise ValueError(f"Provider {provider} not available")
+        return self.clients[provider]
+
+    async def generate_stream(
+        self,
+        provider: LLMProvider,
+        messages: List[Message]
+    ) -> AsyncGenerator[StreamChunk, None]:
+        """Generate streaming response using specified provider"""
+        client = self.get_client(provider)
+        async for chunk in client.generate_stream(messages):
+            yield chunk

coursecrafter/agents/simple_course_agent.py

@@ -0,0 +1,844 @@
+"""
+🎓 Simplified CourseCrafter Agent - Core Functionality Only
+
+Focuses on web search, lesson creation, flashcards, and quizzes without complex MCP dependencies.
+"""
+
+import json
+from typing import Dict, List, Any, Optional, AsyncGenerator, Callable
+from datetime import datetime
+
+from .llm_client import LlmClient, Message
+from ..types import (
+    GenerationOptions, ProgressUpdate, StreamChunk
+)
+from ..utils.config import config
+from ..utils.helpers import smart_json_loads
+
+from ..tools.web_research import research_topic
+from ..tools.image_generation import (
+    generate_educational_image,
+    extract_image_placeholders,
+    replace_image_placeholders
+)
+
+class SimpleCourseAgent:
+    """
+    Main agent for course generation:
+    - Web search for research
+    - Lesson generation
+    - Flashcard creation
+    - Quiz generation
+    - Image generation
+    """
+
+    def __init__(self):
+        self.llm_client = LlmClient()
+        self.system_prompt = self._get_system_prompt()
+        self.default_provider = config.get_default_llm_provider()
+        print(f"🎓 SimpleCourseAgent initialized with default provider: {self.default_provider}")
+
+    def _get_system_prompt(self) -> str:
+        """Get the system prompt for course generation"""
+        return """You are Course Creator AI, an expert educational content creator and course designer. Your goal is to create high-quality educational content that is comprehensive, well-structured, engaging, and tailored to the needs of lerners. Create detailed lessons, generate flashcards, quizzes, and educational images.
+
+## Your Capabilities:
+- Research topics thoroughly using web search and content analysis
+- Generate engaging, structured lesson content with clear explanations and objectives
+- Generate interactive flashcards for key concepts for repetition learning
+- Create multiple-choice quizzes to reinforce learning
+- Generate educational images and visual aids
+- Ensure content quality and educational effectiveness
+
+## Quality Standards:
+- Content must be accurate, well-researched, and up-to-date
+- Lessons should build upon each other logically
+- Include practical examples and real-world applications
+- Maintain appropriate difficulty level for target audience
+- Ensure content is engaging and interactive
+- Provide clear learning objectives and outcomes
+
+## RESPONSE FORMAT:
+- Always respond with valid JSON only. No markdown, no explanations, just pure JSON.
+- Follow the format below for each type of content:
+
+For course planning, return:
+{
+  "title": "Course title",
+  "description": "Brief description",
+  "learning_objectives": ["objective1", "objective2"],
+  "lesson_titles": ["Lesson 1 title", "Lesson 2 title"],
+  "estimated_duration": 60
+}
+
+For lessons, return:
+{
+  "title": "Lesson title",
+  "duration": 15,
+  "objectives": ["Learn X", "Understand Y"],
+  "content": "Detailed lesson content in markdown",
+  "key_takeaways": ["Key point 1", "Key point 2"],
+  "examples": ["Example 1", "Example 2"]
+}
+
+For flashcards, return:
+[
+  {
+    "question": "What is X?",
+    "answer": "X is...",
+    "category": "Category name"
+  }
+]
+
+For quizzes, return:
+{
+  "title": "Quiz title",
+  "instructions": "Instructions text",
+  "questions": [
+    {
+      "question": "Question text?",
+      "options": ["A) Option 1", "B) Option 2", "C) Option 3", "D) Option 4"],
+      "correct_answer": "A",
+      "explanation": "Why A is correct"
+    }
+  ]
+}
+
+Always strive to create courses that are not just informative, but are easy to understand, engaging, learning experiences."""
+
+    async def generate_course(
+        self,
+        topic: str,
+        options: GenerationOptions,
+        provider: Optional[str] = None,
+        progress_callback: Optional[Callable[[ProgressUpdate], None]] = None
+    ) -> AsyncGenerator[StreamChunk, None]:
+        """Generate a complete course on the given topic"""
+        
+        # Use provided provider or fall back to default
+        if provider is None:
+            provider = self.default_provider
+
+        print(f"🚀 Starting course generation for: {topic}")
+        print(f"📋 Options: {options.lesson_count} lessons, {options.difficulty.value} difficulty")
+        print(f"🧠 Using LLM provider: {provider}")
+
+        try:
+            # Step 1: Research the topic
+            if progress_callback:
+                progress_callback(ProgressUpdate(
+                    stage="research",
+                    progress=0.1,
+                    message="Researching topic..."
+                ))
+
+            print("🔍 Step 1: Researching topic...")
+            research_data = await self._research_topic(topic, provider)
+            # Store research data for use in lesson generation
+            self._current_research = research_data
+            yield StreamChunk(type="progress", content="✅ Research completed")
+
+            # Step 2: Generate course structure
+            if progress_callback:
+                progress_callback(ProgressUpdate(
+                    stage="planning",
+                    progress=0.3,
+                    message="Planning course structure..."
+                ))
+
+            print("📋 Step 2: Planning course structure...")
+            course_plan = await self._plan_course(topic, options, provider)
+            print(f"✅ Course plan created: {course_plan.get('title', 'Unknown')}")
+            yield StreamChunk(type="progress", content="✅ Course structure planned")
+
+            # Step 3: Generate lessons
+            if progress_callback:
+                progress_callback(ProgressUpdate(
+                    stage="lessons",
+                    progress=0.5,
+                    message="Creating lessons..."
+                ))
+
+            print("📚 Step 3: Generating lessons...")
+            lessons = await self._generate_lessons(course_plan, options, provider)
+            print(f"✅ Generated {len(lessons)} lessons")
+            yield StreamChunk(type="progress", content="✅ Lessons created")
+
+            # Step 4: Generate flashcards
+            if progress_callback and options.include_flashcards:
+                progress_callback(ProgressUpdate(
+                    stage="flashcards",
+                    progress=0.7,
+                    message="Creating flashcards..."
+                ))
+
+            flashcards = []
+            if options.include_flashcards:
+                print("🃏 Step 4: Generating flashcards...")
+                flashcards = await self._generate_flashcards(lessons, provider, options.difficulty.value)
+                print(f"✅ Generated {len(flashcards)} flashcards")
+                yield StreamChunk(type="progress", content="✅ Flashcards created")
+
+            # Step 5: Generate quiz
+            if progress_callback and options.include_quizzes:
+                progress_callback(ProgressUpdate(
+                    stage="quiz",
+                    progress=0.8,
+                    message="Creating quiz..."
+                ))
+
+            quiz = None
+            if options.include_quizzes:
+                print("📝 Step 5: Generating quiz...")
+                quiz = await self._generate_quiz(lessons, provider, options.difficulty.value)
+                print(f"✅ Generated quiz with {len(quiz.get('questions', []))} questions")
+                yield StreamChunk(type="progress", content="✅ Quiz created")
+
+            # Step 6: Generate images (if requested)
+            images = []
+            if options.include_images:
+                if progress_callback:
+                    progress_callback(ProgressUpdate(
+                        stage="images",
+                        progress=0.9,
+                        message="Generating images..."
+                    ))
+
+                print("🖼️ Step 6: Generating images...")
+                try:
+                    images = await self._generate_images(lessons)
+                    print(f"✅ Generated {len(images)} images")
+                    yield StreamChunk(type="progress", content="✅ Images generated")
+
+                    # Attach images to lessons
+                    for i, lesson in enumerate(lessons):
+                        if i < len(images):
+                            lesson["images"] = [images[i]]
+                    
+                    print(f"📎 Attached images to {min(len(lessons), len(images))} lessons")
+                    
+                except Exception as e:
+                    print(f"⚠️ Image generation failed: {e}")
+                    # Continue without images
+                    images = []
+                    yield StreamChunk(type="progress", content="⚠️ Images skipped (generation failed)")
+            else:
+                print("🖼️ Image generation skipped (not requested)")
+                yield StreamChunk(type="progress", content="⏭️ Images skipped")
+
+            # Final assembly
+            if progress_callback:
+                progress_callback(ProgressUpdate(
+                    stage="completion",
+                    progress=1.0,
+                    message="Course generation complete!"
+                ))
+
+            print("🔄 Assembling final course data...")
+            yield StreamChunk(type="progress", content="✅ Finalizing course")
+
+            # Yield the complete course
+            course_data = {
+                "course_info": course_plan,
+                "lessons": lessons,
+                "flashcards": flashcards,
+                "quiz": quiz,
+                "images": images,
+                "generated_at": datetime.now().isoformat()
+            }
+
+            print("🎉 Course generation completed successfully!")
+            print(f"📊 Final course data: {len(lessons)} lessons, {len(flashcards)} flashcards, {len(quiz.get('questions', []) if quiz else [])} quiz questions")
+
+            yield StreamChunk(type="course_complete", content=json.dumps(course_data, indent=2))
+
+        except Exception as e:
+            error_msg = f"Error generating course: {str(e)}"
+            print(f"❌ {error_msg}")
+            import traceback
+            traceback.print_exc()
+            yield StreamChunk(type="error", content=error_msg)
+
+    async def _research_topic(self, topic: str, provider: str = None) -> Dict[str, Any]:
+        """Research the topic using web search and content extraction"""
+        print(f"🔍 Researching topic: {topic}")
+
+        # Use the provided provider or fall back to default
+        research_provider = provider or self.default_provider
+        print(f"🧠 Using LLM provider for research: {research_provider}")
+
+        try:
+            # Use the new web research tools with the specified provider
+            research_results = await research_topic(topic, llm_provider=research_provider)
+
+            if research_results and research_results.get("success"):
+                print(f"✅ Web research successful: {research_results.get('successful_sources', 0)} sources")
+                return research_results
+            else:
+                print(f"⚠️ Web research failed or returned no results")
+
+        except Exception as e:
+            print(f"⚠️ Web research failed: {e}")
+
+        # Fallback to enhanced simulated research
+        print("🔄 Using fallback research data")
+        return {
+            "topic": topic,
+            "key_concepts": [
+                f"Fundamental concepts of {topic}",
+                f"Practical applications of {topic}",
+                f"Tools and resources for {topic}",
+                f"Best practices in {topic}",
+                f"Common challenges in {topic}"
+            ],
+            "sources": [
+                f"Educational resources for {topic}",
+                f"Documentation and tutorials for {topic}",
+                f"Community forums and discussions about {topic}",
+                f"Official guides and specifications for {topic}"
+            ],
+            "research_summary": f"Comprehensive research on {topic} covering fundamental concepts, practical applications, available tools and resources, best practices, and common challenges. This research would typically include web search results, documentation extraction, and content analysis from multiple authoritative sources.",
+            "success": True,
+            "fallback": True
+        }
+
+    async def _plan_course(
+        self,
+        topic: str,
+        options: GenerationOptions,
+        provider: str
+    ) -> Dict[str, Any]:
+        """Plan the overall course structure"""
+
+        print(f"📋 Planning course for {topic} with {options.lesson_count} lessons")
+
+        prompt = f"""Create a course plan for: "{topic}"
+
+Requirements:
+- {options.lesson_count} lessons
+- {options.difficulty.value} difficulty level
+- {options.max_lesson_duration} minutes per lesson
+
+Return ONLY a JSON object with:
+- title: Course title
+- description: Brief description
+- learning_objectives: Array of 3-5 objectives
+- lesson_titles: Array of lesson titles
+- estimated_duration: Total course duration
+
+Focus on practical, engaging content. Return only valid JSON, no other text. Do not wrap the JSON in markdown code blocks or backticks."""
+
+        messages = [
+            Message(role="system", content=self.system_prompt),
+            Message(role="user", content=prompt)
+        ]
+
+        try:
+            response_text = await self._get_llm_response(provider, messages)
+            print(f"📋 LLM response for course plan: {response_text[:200]}...")
+
+            # Try to parse JSON with smart parser
+            course_plan = smart_json_loads(response_text)
+            if course_plan is not None:
+                print(f"✅ Successfully parsed course plan JSON")
+                return course_plan
+            else:
+                raise ValueError("Failed to extract valid JSON from response")
+
+        except Exception as e:
+            print(f"❌ JSON parsing failed for course plan: {e}")
+            print(f"Raw response: {response_text}")
+            # Fallback if JSON parsing fails
+            return {
+                "title": f"Course: {topic}",
+                "description": f"A comprehensive introduction to {topic}",
+                "learning_objectives": [
+                    f"Understand the fundamentals of {topic}",
+                    f"Apply key concepts of {topic}",
+                    f"Analyze real-world applications of {topic}"
+                ],
+                "lesson_titles": [f"Lesson {i+1}: {topic} Fundamentals" for i in range(options.lesson_count)],
+                "estimated_duration": options.lesson_count * options.max_lesson_duration
+            }
+        except Exception as e:
+            print(f"❌ Error in course planning: {e}")
+            # Return fallback
+            return {
+                "title": f"Course: {topic}",
+                "description": f"A comprehensive introduction to {topic}",
+                "learning_objectives": [
+                    f"Understand the fundamentals of {topic}",
+                    f"Apply key concepts of {topic}",
+                    f"Analyze real-world applications of {topic}"
+                ],
+                "lesson_titles": [f"Lesson {i+1}: {topic} Basics" for i in range(options.lesson_count)],
+                "estimated_duration": options.lesson_count * options.max_lesson_duration
+            }
+
+    async def _generate_lessons(
+        self,
+        course_plan: Dict[str, Any],
+        options: GenerationOptions,
+        provider: str
+    ) -> List[Dict[str, Any]]:
+        """Generate detailed lesson content"""
+
+        lessons = []
+        lesson_titles = course_plan.get("lesson_titles", [])
+        print(f"📚 Generating {len(lesson_titles)} lessons")
+
+        for i, title in enumerate(lesson_titles):
+            print(f"📖 Generating lesson {i+1}: {title}")
+
+            # Include research data in the prompt
+            research_context = ""
+            if hasattr(self, '_current_research') and self._current_research:
+                research_context = f"""
+Research Context:
+{self._current_research.get('research_summary', '')}
+
+Key Concepts: {', '.join(self._current_research.get('key_concepts', [])[:3])}
+"""
+
+            # Create difficulty-specific guidelines
+            difficulty_guidelines = {
+                "beginner": """
+- Use simple, clear language and avoid technical jargon
+- Explain every concept from the ground up with no assumed prior knowledge
+- Include step-by-step instructions with detailed explanations for each step
+- Use basic, relatable examples that anyone can understand
+- Focus on fundamental concepts and practical applications
+- Include plenty of context and background information
+- Break down complex ideas into smaller, digestible parts""",
+                "intermediate": """
+- Use some technical terminology but explain it when first introduced
+- Assume basic familiarity with the subject area
+- Include moderately complex examples that build on fundamental knowledge
+- Focus on practical applications and real-world scenarios
+- Introduce some advanced concepts but explain them thoroughly
+- Include best practices and common patterns
+- Balance theory with hands-on practice""",
+                "advanced": """
+- Use technical language and industry-standard terminology
+- Assume solid foundational knowledge in the subject area
+- Include complex, real-world examples and edge cases
+- Focus on advanced techniques, optimization, and expert-level practices
+- Discuss trade-offs, limitations, and alternative approaches
+- Include cutting-edge developments and research
+- Emphasize problem-solving and critical thinking"""
+            }
+
+            prompt = f"""Create comprehensive, detailed educational content for: "{title}"
+
+This is lesson {i+1} of {len(lesson_titles)} in a course about "{course_plan.get('title', '')}"
+
+{research_context}
+
+Requirements:
+- Duration: {options.max_lesson_duration} minutes
+- Difficulty Level: {options.difficulty.value.upper()}
+
+DIFFICULTY-SPECIFIC GUIDELINES for {options.difficulty.value.upper()} level:
+{difficulty_guidelines.get(options.difficulty.value, difficulty_guidelines["intermediate"])}
+
+Content Requirements:
+- Create EXTENSIVE, thorough content that truly teaches the topic (aim for 2000+ words)
+- Include multiple practical examples with code/step-by-step instructions
+- Provide detailed explanations that help students understand complex concepts
+- Include real-world applications and use cases
+- Add troubleshooting tips and common pitfalls
+- Make content comprehensive enough to actually learn from
+- Include image placeholders where visual aids would be helpful
+
+IMPORTANT: When you want to include an educational image, use this format:
+{{{{IMAGE_PLACEHOLDER:{title}:Description of the image needed}}}}
+
+LIMIT: Use a MAXIMUM of 3 image placeholders per lesson. Choose the most important visual aids.
+
+For example:
+{{{{IMAGE_PLACEHOLDER:{title}:Diagram showing the main components}}}}
+{{{{IMAGE_PLACEHOLDER:{title}:Screenshot of the user interface}}}}
+{{{{IMAGE_PLACEHOLDER:{title}:Flowchart of the process}}}}
+
+The content should be substantial and educational. Include sections like:
+- Introduction with context and importance
+- Core concepts with detailed explanations
+- Multiple practical examples with code/instructions
+- Step-by-step tutorials
+- Best practices and tips
+- Common mistakes to avoid
+- Real-world applications
+- Further resources and next steps
+
+Return ONLY a JSON object with:
+- title: Lesson title
+- duration: Estimated duration
+- objectives: Learning objectives for this lesson (3-5 specific objectives)
+- content: EXTENSIVE lesson content in markdown format (2000+ words, with image placeholders)
+- key_takeaways: Array of 5-7 key points
+- examples: Array of 3-5 detailed practical examples with explanations
+
+Return only valid JSON, no other text. Do not wrap the JSON in markdown code blocks or backticks."""
+
+            messages = [
+                Message(role="system", content=self.system_prompt),
+                Message(role="user", content=prompt)
+            ]
+
+            try:
+                response_text = await self._get_llm_response(provider, messages)
+                print(f"📖 LLM response for lesson {i+1}: {response_text[:100]}...")
+
+                lesson_data = smart_json_loads(response_text)
+                if lesson_data is not None:
+                    lessons.append(lesson_data)
+                    print(f"✅ Successfully generated lesson {i+1}")
+                else:
+                    raise ValueError("Failed to extract valid JSON from response")
+
+            except Exception as e:
+                print(f"❌ JSON parsing failed for lesson {i+1}: {e}")
+                # Fallback lesson structure
+                lessons.append({
+                    "title": title,
+                    "duration": options.max_lesson_duration,
+                    "objectives": [f"Learn about {title}"],
+                    "content": f"# {title}\n\nThis lesson covers the fundamentals of {title}.\n\n## Key Concepts\n\n- Important concept 1\n- Important concept 2\n- Important concept 3\n\n## Examples\n\nHere are some practical examples related to {title}...",
+                    "key_takeaways": [f"Key concept from {title}", f"Important principle of {title}"],
+                    "examples": [f"Example 1 related to {title}", f"Example 2 related to {title}"]
+                })
+            except Exception as e:
+                print(f"❌ Error generating lesson {i+1}: {e}")
+                # Fallback lesson structure
+                lessons.append({
+                    "title": title,
+                    "duration": options.max_lesson_duration,
+                    "objectives": [f"Learn about {title}"],
+                    "content": f"# {title}\n\nDetailed content about {title}...",
+                    "key_takeaways": [f"Key concept from {title}"],
+                    "examples": [f"Example related to {title}"]
+                })
+
+        return lessons
+
+    async def _generate_flashcards(
+        self,
+        lessons: List[Dict[str, Any]],
+        provider: str,
+        difficulty: str = "intermediate"
+    ) -> List[Dict[str, Any]]:
+        """Generate flashcards from lesson content with difficulty-appropriate complexity"""
+
+        print(f"🃏 Generating {difficulty} level flashcards from lesson content")
+
+        # Combine all lesson content
+        all_content = "\n\n".join([
+            lesson.get("content", "") + "\n" +
+            "\n".join(lesson.get("key_takeaways", []))
+            for lesson in lessons
+        ])
+
+        # Create difficulty-specific flashcard guidelines
+        flashcard_guidelines = {
+            "beginner": """
+- Focus on basic definitions and simple facts
+- Use clear, simple language in both questions and answers
+- Test fundamental concepts and terminology
+- Include basic examples and straightforward explanations
+- Avoid complex relationships or multi-step reasoning
+- Keep answers concise and direct""",
+            "intermediate": """
+- Include concepts, relationships, and applications
+- Test understanding of how concepts connect
+- Use moderate complexity in questions and explanations
+- Include practical examples and use cases
+- Test both knowledge and basic application
+- Balance definitions with conceptual understanding""",
+            "advanced": """
+- Focus on complex principles, applications, and analysis
+- Test deep understanding and critical thinking
+- Include challenging scenarios and edge cases
+- Test ability to synthesize and evaluate information
+- Include questions about trade-offs and best practices
+- Emphasize expert-level insights and nuanced understanding"""
+        }
+
+        prompt = f"""Create flashcards based on this lesson content:
+
+{all_content[:2000]}...
+
+DIFFICULTY LEVEL: {difficulty.upper()}
+
+FLASHCARD GUIDELINES for {difficulty.upper()} level:
+{flashcard_guidelines.get(difficulty, flashcard_guidelines["intermediate"])}
+
+Generate 10-15 flashcards covering the most important concepts at the {difficulty} level.
+
+Return ONLY a JSON array where each flashcard has:
+- question: The question/prompt
+- answer: The answer/explanation
+- category: Which lesson/topic this relates to
+
+Ensure flashcards match the {difficulty} difficulty level. Return only valid JSON, no other text. Do not wrap the JSON in markdown code blocks or backticks."""
+
+        messages = [
+            Message(role="system", content=self.system_prompt),
+            Message(role="user", content=prompt)
+        ]
+
+        try:
+            response_text = await self._get_llm_response(provider, messages)
+            print(f"🃏 LLM response for flashcards: {response_text[:100]}...")
+
+            flashcards = smart_json_loads(response_text)
+            if flashcards is not None:
+                print(f"✅ Successfully generated {len(flashcards)} flashcards")
+                return flashcards
+            else:
+                raise ValueError("Failed to extract valid JSON from response")
+
+        except Exception as e:
+            print(f"❌ JSON parsing failed for flashcards: {e}")
+            # Fallback flashcards
+            return [
+                {
+                    "question": f"What is the main concept in {lesson.get('title', 'this lesson')}?",
+                    "answer": f"The main concept is related to {lesson.get('title', 'the lesson topic')}",
+                    "category": lesson.get('title', 'General')
+                }
+                for lesson in lessons[:5]  # Limit to 5 fallback cards
+            ]
+        except Exception as e:
+            print(f"❌ Error generating flashcards: {e}")
+            return []
+
+    async def _generate_quiz(
+        self,
+        lessons: List[Dict[str, Any]],
+        provider: str,
+        difficulty: str = "intermediate"
+    ) -> Dict[str, Any]:
+        """Generate a multiple-choice quiz with difficulty-appropriate questions"""
+
+        print(f"📝 Generating {difficulty} level quiz from lesson content")
+
+        # Combine lesson content
+        all_content = "\n\n".join([
+            lesson.get("content", "") + "\n" +
+            "\n".join(lesson.get("key_takeaways", []))
+            for lesson in lessons
+        ])
+
+        # Create difficulty-specific quiz guidelines
+        quiz_guidelines = {
+            "beginner": """
+- Focus on basic recall and recognition questions
+- Test fundamental concepts and definitions
+- Use simple, clear language in questions
+- Include straightforward examples
+- Avoid trick questions or complex scenarios
+- Test one concept per question""",
+            "intermediate": """
+- Include application and analysis questions
+- Test understanding of relationships between concepts
+- Use moderate complexity in scenarios
+- Include some problem-solving questions
+- Test ability to apply knowledge to new situations
+- Mix recall with application questions""",
+            "advanced": """
+- Focus on analysis, synthesis, and evaluation questions
+- Test complex problem-solving abilities
+- Include multi-step reasoning questions
+- Use challenging real-world scenarios
+- Test ability to compare and contrast approaches
+- Include questions about trade-offs and limitations"""
+        }
+
+        prompt = f"""Create a 10-question multiple-choice quiz based on this content:
+
+{all_content[:2000]}...
+
+DIFFICULTY LEVEL: {difficulty.upper()}
+
+QUIZ GUIDELINES for {difficulty.upper()} level:
+{quiz_guidelines.get(difficulty, quiz_guidelines["intermediate"])}
+
+Return ONLY a JSON object with:
+- title: Quiz title
+- instructions: Brief instructions
+- questions: Array of question objects
+
+Each question should have:
+- question: The question text
+- options: Array of 4 multiple choice options (A, B, C, D)
+- correct_answer: The letter of the correct answer
+- explanation: Why this answer is correct
+
+Ensure questions match the {difficulty} difficulty level. Return only valid JSON, no other text. Do not wrap the JSON in markdown code blocks or backticks."""
+
+        messages = [
+            Message(role="system", content=self.system_prompt),
+            Message(role="user", content=prompt)
+        ]
+
+        try:
+            response_text = await self._get_llm_response(provider, messages)
+            print(f"📝 LLM response for quiz: {response_text[:100]}...")
+
+            quiz = smart_json_loads(response_text)
+            if quiz is not None:
+                print(f"✅ Successfully generated quiz with {len(quiz.get('questions', []))} questions")
+                return quiz
+            else:
+                raise ValueError("Failed to extract valid JSON from response")
+
+        except Exception as e:
+            print(f"❌ JSON parsing failed for quiz: {e}")
+            # Fallback quiz
+            return {
+                "title": "Course Quiz",
+                "instructions": "Choose the best answer for each question.",
+                "questions": [
+                    {
+                        "question": f"What is a key concept from {lesson.get('title', 'this lesson')}?",
+                        "options": ["A) Option A", "B) Option B", "C) Option C", "D) Option D"],
+                        "correct_answer": "A",
+                        "explanation": "This is the correct answer based on the lesson content."
+                    }
+                    for lesson in lessons[:3]  # Limit to 3 fallback questions
+                ]
+            }
+        except Exception as e:
+            print(f"❌ Error generating quiz: {e}")
+            return {
+                "title": "Course Quiz",
+                "instructions": "Choose the best answer for each question.",
+                "questions": []
+            }
+
+    async def _generate_images(self, lessons: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Generate educational images for lessons using Pollinations API"""
+
+        print("🖼️ Generating actual images for lessons using Pollinations API")
+
+        images = []
+
+        # Process each lesson separately to avoid duplication
+        for lesson in lessons:
+            lesson_title = lesson.get("title", "")
+            content = lesson.get("content", "")
+
+            print(f"📚 Processing images for lesson: {lesson_title}")
+
+            # Extract placeholders for this specific lesson
+            placeholders = extract_image_placeholders(content)
+
+            if not placeholders:
+                print(f"📝 No image placeholders found for {lesson_title}, generating 1 default image")
+                # Generate one default image for the lesson
+                topic = lesson_title.split(":")[0] if ":" in lesson_title else lesson_title
+
+                try:
+                    image_data = await generate_educational_image(lesson_title, topic, "educational")
+                    if image_data:
+                        images.append(image_data)
+                        print(f"✅ Generated default image for: {lesson_title}")
+                    else:
+                        print(f"⚠️ Failed to generate default image for: {lesson_title}")
+                except Exception as e:
+                    print(f"❌ Error generating default image for {lesson_title}: {e}")
+            else:
+                # Generate images for ALL placeholders to avoid unreplaced ones
+                print(f"🎨 Found {len(placeholders)} placeholders for {lesson_title}, generating images for ALL of them")
+
+                for i, placeholder in enumerate(placeholders):
+                    placeholder_lesson_title = placeholder["lesson_title"]
+                    description = placeholder["description"]
+
+                    try:
+                        # Create educational prompt from placeholder description
+                        topic = description
+                        image_data = await generate_educational_image(placeholder_lesson_title, topic, "educational")
+
+                        if image_data:
+                            # Store the specific placeholder description for matching
+                            image_data["placeholder_description"] = description
+                            image_data["placeholder_full"] = placeholder["placeholder"]
+                            images.append(image_data)
+                            print(f"✅ Generated image {i+1}/{len(placeholders)} for {lesson_title}: {description[:50]}...")
+                        else:
+                            print(f"⚠️ Failed to generate image {i+1} for {lesson_title}: {description[:50]}...")
+
+                    except Exception as e:
+                        print(f"❌ Error generating image {i+1} for {lesson_title}: {e}")
+
+        # Replace placeholders in lesson content with actual images
+        for lesson in lessons:
+            if images:
+                lesson["content"] = replace_image_placeholders(lesson["content"], images)
+
+        print(f"✅ Generated {len(images)} total images and updated lesson content")
+        return images
+
+    async def _get_llm_response(self, provider: str, messages: List[Message]) -> str:
+        """Get a complete response from the LLM by collecting all streaming chunks"""
+
+        print(f"🧠 Getting LLM response from {provider}")
+
+        response_text = ""
+
+        try:
+            async for chunk in self.llm_client.generate_stream(
+                provider=provider,
+                messages=messages
+            ):
+                if chunk.type == "text":
+                    response_text += chunk.content
+                elif chunk.type == "error":
+                    raise Exception(f"LLM error: {chunk.content}")
+
+            print(f"✅ Got LLM response ({len(response_text)} characters)")
+            return response_text.strip()
+
+        except Exception as e:
+            print(f"❌ Error getting LLM response: {e}")
+            raise
+
+    async def refine_course(
+        self,
+        course_data: Dict[str, Any],
+        user_request: str,
+        provider: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Refine or add to existing course based on user feedback"""
+        
+        # Use provided provider or fall back to default
+        if provider is None:
+            provider = self.default_provider
+
+        prompt = f"""The user wants to modify this course:
+
+Current course: {json.dumps(course_data, indent=2)[:1000]}...
+
+User request: "{user_request}"
+
+Please modify the course accordingly. If they want more information about a specific topic, research it and add detailed content. Return the updated course data in the same JSON format."""
+
+        messages = [
+            Message(role="system", content=self.system_prompt),
+            Message(role="user", content=prompt)
+        ]
+
+        try:
+            response_text = await self._get_llm_response(provider, messages)
+            refined_course = smart_json_loads(response_text)
+            if refined_course is not None:
+                return refined_course
+            else:
+                return course_data  # Return original if parsing fails
+        except:
+            return course_data  # Return original if parsing fails
+
+    def get_available_providers(self) -> List[str]:
+        """Get list of available LLM providers"""
+        return self.llm_client.get_available_providers()

coursecrafter/tools/__init__.py

@@ -0,0 +1,19 @@
+
+from .image_generation import (
+    ImageGenerator,
+    generate_educational_image,
+    extract_image_placeholders,
+    replace_image_placeholders,
+    create_image_placeholder
+)
+from .web_research import WebResearcher, research_topic
+
+__all__ = [
+    "ImageGenerator",
+    "generate_educational_image",
+    "extract_image_placeholders",
+    "replace_image_placeholders",
+    "create_image_placeholder",
+    "WebResearcher",
+    "research_topic"
+]

coursecrafter/tools/image_generation.py

@@ -0,0 +1,254 @@
+"""
+🎨 Image Generation Tools
+High-quality image generation using Pollinations API with gptimage model
+"""
+
+import urllib.parse
+import base64
+from typing import Dict, Any, Optional, List
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Import config for Pollinations settings
+from ..utils.config import config
+
+
+class ImageGenerator:
+    """High-quality image generation using Pollinations API"""
+
+    def __init__(self):
+        self.base_url = "https://image.pollinations.ai/prompt"
+        self.image_config = config.get_image_generation_config()
+
+        # Set up default parameters from config
+        self.default_params = {
+            "width": self.image_config.get("default_width", 1280),
+            "height": self.image_config.get("default_height", 720),
+            "model": self.image_config.get("default_model", "gptimage"),
+            "nologo": "true",
+            "enhance": "true",
+            "private": "true"
+        }
+
+        # Add API credentials if available
+        if self.image_config.get("pollinations_api_token"):
+            self.default_params["token"] = self.image_config["pollinations_api_token"]
+
+        if self.image_config.get("pollinations_api_reference"):
+            self.default_params["referrer"] = self.image_config["pollinations_api_reference"]
+
+    async def generate_image_url(self, prompt: str, **kwargs) -> Optional[str]:
+        """Generate image and return URL"""
+        try:
+            print(f"🎨 Generating image: {prompt[:50]}...")
+
+            # Merge custom params with defaults
+            params = {**self.default_params, **kwargs}
+
+            # Encode the prompt for URL
+            encoded_prompt = urllib.parse.quote(prompt)
+            url = f"{self.base_url}/{encoded_prompt}"
+
+            print(f"🌐 Request URL: {url}")
+            print(f"📋 Parameters: {params}")
+
+            # Use requests instead of aiohttp for better compatibility
+            import requests
+
+            try:
+                response = requests.get(url, params=params, timeout=300)
+                response.raise_for_status()  # Raise an exception for bad status codes
+            except requests.exceptions.RequestException as e:
+                print(f"❌ Request failed: {e}")
+                if hasattr(e, 'response') and e.response is not None:
+                    print(f"📄 Error response: {e.response.text[:200]}...")
+                return None
+
+            if response.status_code == 200:
+                image_data = response.content
+
+                # Convert to base64
+                base64_data = base64.b64encode(image_data).decode('utf-8')
+
+                print(f"✅ Image data generated successfully ({len(image_data)} bytes)")
+
+                return {
+                    "prompt": prompt,
+                    "base64_data": base64_data,
+                    "data_url": f"data:image/jpeg;base64,{base64_data}",
+                    "size_bytes": len(image_data),
+                    "params": params
+                }
+            else:
+                print(f"❌ Image generation failed: HTTP {response.status_code}")
+                print(f"📄 Response text: {response.text[:200]}...")
+                return None
+
+        except Exception as e:
+            logger.error(f"Image data generation failed: {e}")
+            print(f"❌ Image data generation error: {e}")
+            return None
+
+    async def generate_educational_image(self, lesson_title: str, topic: str, style: str = "educational") -> Optional[Dict[str, Any]]:
+        """Generate educational image for a lesson"""
+        try:
+            # Create varied educational prompts with different styles and approaches
+            import random
+
+            # Add variety with different visual styles and descriptors
+            visual_styles = [
+                "modern minimalist", "vibrant colorful", "clean professional", "sleek contemporary",
+                "bright engaging", "polished elegant", "dynamic visual", "crisp detailed"
+            ]
+
+            art_styles = [
+                "digital illustration", "infographic design", "vector art", "educational diagram",
+                "technical illustration", "conceptual artwork", "instructional graphic", "learning visual"
+            ]
+
+            descriptors = [
+                "high-quality", "detailed", "clear and informative", "visually appealing",
+                "educational focused", "learning oriented", "instructionally designed", "pedagogically sound"
+            ]
+
+            # Randomly select style elements for variety
+            visual_style = random.choice(visual_styles)
+            art_style = random.choice(art_styles)
+            descriptor = random.choice(descriptors)
+
+            if style == "educational":
+                prompt = f"{descriptor.title()} {art_style} about {topic}. {visual_style} style with engaging visual elements."
+            elif style == "diagram":
+                prompt = f"Technical {art_style} showing {topic} concepts. {visual_style} design with clear visual hierarchy and {descriptor} presentation."
+            elif style == "concept":
+                prompt = f"Conceptual {art_style} of {topic}. {visual_style} visual representation with {descriptor} design elements."
+            else:
+                prompt = f"Professional {art_style} about {topic}. {visual_style}, {descriptor} educational style."
+
+            print(f"🎓 Generating educational image for: {lesson_title}")
+
+            # Use default parameters from config (already includes API credentials)
+            result = await self.generate_image_url(prompt)
+
+            if result:
+                result.update({
+                    "lesson_title": lesson_title,
+                    "topic": topic,
+                    "style": style,
+                    "educational": True
+                })
+                print(f"✅ Educational image generated for: {lesson_title}")
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Educational image generation failed: {e}")
+            print(f"❌ Educational image generation error: {e}")
+            return None
+
+    @staticmethod
+    def create_image_placeholder(lesson_title: str, description: str) -> str:
+        """Create an image placeholder marker for lessons"""
+        return f"{{{{IMAGE_PLACEHOLDER:{lesson_title}:{description}}}}}"
+
+
+def extract_image_placeholders(content: str) -> List[Dict[str, str]]:
+    """Extract image placeholder markers from content"""
+    import re
+
+    pattern = r'\{\{IMAGE_PLACEHOLDER:([^:]+):([^}]+)\}\}'
+    matches = re.findall(pattern, content)
+
+    return [
+        {
+            "lesson_title": match[0],
+            "description": match[1],
+            "placeholder": f"{{{{IMAGE_PLACEHOLDER:{match[0]}:{match[1]}}}}}"
+        }
+        for match in matches
+    ]
+
+
+def replace_image_placeholders(content: str, images: List[Dict[str, Any]]) -> str:
+    """Replace image placeholders with actual image HTML"""
+    print(f"🔄 Replacing image placeholders in content ({len(images)} images available)")
+
+    if not images:
+        print("⚠️ No images provided for placeholder replacement")
+        return content
+
+    import re
+
+    # Track which images have been used to avoid duplication
+    used_images = set()
+
+    # Find all placeholders in content
+    placeholder_pattern = r'\{\{IMAGE_PLACEHOLDER:([^:]+):([^}]+)\}\}'
+    placeholders = re.findall(placeholder_pattern, content)
+    print(f"🔍 Found {len(placeholders)} total placeholders in content")
+
+    for placeholder_lesson, placeholder_desc in placeholders:
+        print(f"📝 Looking for image for placeholder: {placeholder_lesson} - {placeholder_desc[:50]}...")
+
+        # Find the best matching image that hasn't been used
+        best_match = None
+        for i, image in enumerate(images):
+            if i in used_images:
+                continue  # Skip already used images
+
+            if not image or "data_url" not in image:
+                continue
+
+            image_lesson = image.get("lesson_title", "")
+            image_desc = image.get("placeholder_description", "")
+
+            # Check if this image matches the placeholder
+            if (image_lesson == placeholder_lesson and
+                (image_desc == placeholder_desc or
+                placeholder_desc in image_desc or
+                image_desc in placeholder_desc)):
+                best_match = (i, image)
+                break
+
+        if best_match:
+            image_index, image = best_match
+            used_images.add(image_index)
+
+            # Replace this specific placeholder
+            specific_placeholder = f"{{{{IMAGE_PLACEHOLDER:{placeholder_lesson}:{placeholder_desc}}}}}"
+            description = image.get("prompt", image.get("placeholder_description", "Educational image"))
+
+            img_html = f'<img src="{image["data_url"]}" alt="{description}" style="max-width: 100%; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.3); border: 2px solid #4a4a7a; margin: 1rem 0;">'
+
+            content = content.replace(specific_placeholder, img_html)
+            print(f"✅ Replaced placeholder with image {image_index+1}: {placeholder_desc[:50]}...")
+        else:
+            print(f"⚠️ No matching image found for: {placeholder_lesson} - {placeholder_desc[:50]}...")
+
+    # Check if any placeholders remain
+    remaining_placeholders = re.findall(r'\{\{IMAGE_PLACEHOLDER:[^}]+\}\}', content)
+    if remaining_placeholders:
+        print(f"⚠️ {len(remaining_placeholders)} placeholders still remain unreplaced")
+        for placeholder in remaining_placeholders[:3]:  # Show first 3
+            print(f"   - {placeholder}")
+    else:
+        print("✅ All image placeholders have been replaced")
+
+    print(f"📊 Used {len(used_images)} out of {len(images)} available images")
+
+    return content
+
+
+def create_image_placeholder(lesson_title: str, description: str) -> str:
+    """Convenience function for creating image placeholders"""
+    return ImageGenerator.create_image_placeholder(lesson_title, description)
+
+
+# Global instance for convenience
+_image_generator = ImageGenerator()
+
+
+async def generate_educational_image(lesson_title: str, topic: str, style: str = "educational") -> Optional[Dict[str, Any]]:
+    """Convenience function for generating educational images"""
+    return await _image_generator.generate_educational_image(lesson_title, topic, style)

coursecrafter/tools/web_research.py

@@ -0,0 +1,257 @@
+"""
+🔍 Web Research Tools
+Advanced web research using DuckDuckGo search and Crawl4AI content extraction
+"""
+
+import os
+from typing import List, Dict, Any, Optional
+from duckduckgo_search import DDGS
+from crawl4ai import (
+    AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig,
+    LLMContentFilter, DefaultMarkdownGenerator
+)
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class WebResearcher:
+    """Advanced web research using DuckDuckGo and Crawl4AI"""
+
+    def __init__(self, max_results: int = 10, max_crawl_pages: int = 7, llm_provider: str = None):
+        self.max_results = max_results
+        self.max_crawl_pages = max_crawl_pages
+        self.llm_provider = llm_provider or "openai"  # Default fallback
+        self.browser_config = BrowserConfig(
+            headless=True,
+            viewport_width=1280,
+            viewport_height=720
+        )
+
+    async def search_topic(self, topic: str, region: str = "us-en") -> List[Dict[str, Any]]:
+        """Search for a topic using DuckDuckGo"""
+        try:
+            print(f"🔍 Searching DuckDuckGo for: {topic}")
+
+            with DDGS() as ddgs:
+                results = []
+                search_results = ddgs.text(
+                    keywords=topic,
+                    region=region,
+                    safesearch="moderate",
+                    max_results=self.max_results
+                )
+
+                for result in search_results:
+                    results.append({
+                        "title": result.get("title", ""),
+                        "url": result.get("href", ""),
+                        "snippet": result.get("body", ""),
+                        "source": "duckduckgo"
+                    })
+
+                print(f"✅ Found {len(results)} search results")
+                return results
+
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            print(f"❌ Search failed: {e}")
+            return []
+
+    async def extract_content(self, urls: List[str], topic: str) -> List[Dict[str, Any]]:
+        """Extract content from URLs using Crawl4AI with LLM filtering"""
+        try:
+            print(f"📄 Extracting content from {len(urls)} URLs...")
+
+            # Try to configure LLM content filter for educational content
+            try:
+                # Use the provider passed to the class, or fall back to environment/default
+                crawl4ai_provider_simple = self.llm_provider
+
+                # Map simple provider names to full provider/model format
+                provider_mapping = {
+                    "openai": "openai/gpt-4o-mini",
+                    "google": "gemini/gemini-2.0-flash-exp",
+                    "gemini": "gemini/gemini-2.0-flash-exp",
+                    "anthropic": "gemini/gemini-2.0-flash-exp"  # Fallback since Crawl4AI doesn't support Anthropic directly
+                }
+
+                crawl4ai_provider = provider_mapping.get(crawl4ai_provider_simple, "openai/gpt-4o-mini")
+
+                if crawl4ai_provider.startswith("gemini"):
+                    # Check if Google API key is available
+                    if not os.getenv("GOOGLE_API_KEY"):
+                        print("⚠️ GOOGLE_API_KEY not found, falling back to OpenAI")
+                        llm_config = LLMConfig(
+                            provider="openai/gpt-4o-mini",
+                            api_token="env:OPENAI_API_KEY"
+                        )
+                        print("🧠 Using OpenAI for content filtering: gpt-4o-mini (fallback)")
+                    else:
+                        llm_config = LLMConfig(
+                            provider=crawl4ai_provider,
+                            api_token="env:GOOGLE_API_KEY"
+                        )
+                        print(f"🧠 Using Gemini for content filtering: {crawl4ai_provider}")
+                else:
+                    # Default to OpenAI
+                    llm_config = LLMConfig(
+                        provider="openai/gpt-4o-mini",
+                        api_token="env:OPENAI_API_KEY"
+                    )
+                    print("🧠 Using OpenAI for content filtering: gpt-4o-mini")
+
+                content_filter = LLMContentFilter(
+                    llm_config=llm_config,
+                    instruction=f"""
+                    Extract educational content related to "{topic}".
+                    Focus on:
+                    - Key concepts and explanations
+                    - Practical examples and tutorials
+                    - Technical details and specifications
+                    - Best practices and guidelines
+                    - Code examples and implementations
+
+                    Exclude:
+                    - Navigation menus and sidebars
+                    - Advertisements and promotional content
+                    - Footer content and legal text
+                    - Unrelated content
+
+                    Format as clean markdown with proper headers and code blocks.
+                    """,
+                    chunk_token_threshold=1000,
+                    verbose=False
+                )
+
+                markdown_generator = DefaultMarkdownGenerator(
+                    content_filter=content_filter,
+                    options={"ignore_links": False}
+                )
+            except Exception as e:
+                print(f"⚠️ Could not configure LLM content filter: {e}")
+                # Fallback to basic markdown generator
+                markdown_generator = DefaultMarkdownGenerator(
+                    options={"ignore_links": False}
+                )
+
+            run_config = CrawlerRunConfig(
+                markdown_generator=markdown_generator,
+                cache_mode=CacheMode.BYPASS,
+                wait_for_images=False,
+                process_iframes=False,
+                remove_overlay_elements=True
+            )
+
+            extracted_content = []
+
+            async with AsyncWebCrawler(config=self.browser_config) as crawler:
+                for i, url in enumerate(urls[:self.max_crawl_pages]):
+                    try:
+                        print(f"📖 Crawling {i+1}/{min(len(urls), self.max_crawl_pages)}: {url}")
+
+                        result = await crawler.arun(url=url, config=run_config)
+
+                        if result.success and result.markdown:
+                            extracted_content.append({
+                                "url": url,
+                                "title": result.metadata.get("title", ""),
+                                "content": result.markdown,
+                                "word_count": len(result.markdown.split()),
+                                "extraction_success": True
+                            })
+                            print(f"✅ Extracted {len(result.markdown.split())} words from {url}")
+                        else:
+                            print(f"⚠️ Failed to extract content from {url}: {result.error_message}")
+                            extracted_content.append({
+                                "url": url,
+                                "title": "",
+                                "content": "",
+                                "word_count": 0,
+                                "extraction_success": False,
+                                "error": result.error_message
+                            })
+
+                    except Exception as e:
+                        logger.error(f"Error crawling {url}: {e}")
+                        print(f"❌ Error crawling {url}: {e}")
+                        extracted_content.append({
+                            "url": url,
+                            "title": "",
+                            "content": "",
+                            "word_count": 0,
+                            "extraction_success": False,
+                            "error": str(e)
+                        })
+
+            successful_extractions = [c for c in extracted_content if c["extraction_success"]]
+            print(f"✅ Successfully extracted content from {len(successful_extractions)}/{len(urls)} URLs")
+
+            return extracted_content
+
+        except Exception as e:
+            logger.error(f"Content extraction failed: {e}")
+            print(f"❌ Content extraction failed: {e}")
+            return []
+
+    async def research_topic(self, topic: str) -> Dict[str, Any]:
+        """Complete research workflow: search + extract + summarize"""
+        try:
+            print(f"🚀 Starting comprehensive research for: {topic}")
+
+            # Step 1: Search for relevant URLs
+            search_results = await self.search_topic(topic)
+
+            if not search_results:
+                return {
+                    "topic": topic,
+                    "search_results": [],
+                    "extracted_content": [],
+                    "summary": f"No search results found for {topic}",
+                    "success": False
+                }
+
+            # Step 2: Extract content from top URLs
+            urls = [result["url"] for result in search_results]
+            extracted_content = await self.extract_content(urls, topic)
+
+            # Step 3: Compile research summary
+            successful_content = [c for c in extracted_content if c["extraction_success"]]
+            total_words = sum(c["word_count"] for c in successful_content)
+
+            summary = f"""
+            Research completed for "{topic}":
+            - Found {len(search_results)} search results
+            - Successfully extracted content from {len(successful_content)} sources
+            - Total content: {total_words} words
+            - Sources include educational articles, documentation, and tutorials
+            """
+
+            print(f"🎉 Research completed: {len(successful_content)} sources, {total_words} words")
+
+            return {
+                "topic": topic,
+                "search_results": search_results,
+                "extracted_content": extracted_content,
+                "summary": summary.strip(),
+                "total_words": total_words,
+                "successful_sources": len(successful_content),
+                "success": True
+            }
+
+        except Exception as e:
+            logger.error(f"Research failed: {e}")
+            print(f"❌ Research failed: {e}")
+            return {
+                "topic": topic,
+                "search_results": [],
+                "extracted_content": [],
+                "summary": f"Research failed for {topic}: {str(e)}",
+                "success": False
+            }
+
+
+async def research_topic(topic: str, llm_provider: str = "openai") -> Dict[str, Any]:
+    """Convenience function for topic research with LLM provider"""
+    web_researcher = WebResearcher(llm_provider=llm_provider)
+    return await web_researcher.research_topic(topic)

coursecrafter/types.py

@@ -0,0 +1,326 @@
+"""
+📊 Type Definitions for Course Creator AI
+
+Comprehensive data structures and type hints for the course generation system.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Any, Union, Literal
+from datetime import datetime
+from enum import Enum
+
+
+class DifficultyLevel(str, Enum):
+    """Course difficulty levels"""
+    BEGINNER = "beginner"
+    INTERMEDIATE = "intermediate"
+    ADVANCED = "advanced"
+
+
+class LearningStyle(str, Enum):
+    """Learning style preferences"""
+    VISUAL = "visual"
+    AUDITORY = "auditory"
+    KINESTHETIC = "kinesthetic"
+    READING = "reading"
+
+
+class ExportFormat(str, Enum):
+    """Export format options"""
+    PDF = "pdf"
+    JSON = "json"
+    MARKDOWN = "markdown"
+    HTML = "html"
+    ANKI = "anki"
+
+
+@dataclass
+class Source:
+    """Information about a content source"""
+    url: str
+    title: str
+    author: Optional[str] = None
+    date: Optional[datetime] = None
+    credibility_score: float = 0.0
+    content_type: str = "web"
+
+
+@dataclass
+class LearningObjective:
+    """A specific learning objective"""
+    description: str
+    level: DifficultyLevel
+    estimated_time: int  # minutes
+    skills: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Exercise:
+    """A practice exercise"""
+    title: str
+    description: str
+    instructions: str
+    solution: Optional[str] = None
+    difficulty: DifficultyLevel = DifficultyLevel.BEGINNER
+    estimated_time: int = 10  # minutes
+
+
+@dataclass
+class CodeExample:
+    """A code example with explanation"""
+    title: str
+    code: str
+    language: str = "python"
+    explanation: str = ""
+    tags: List[str] = field(default_factory=list)
+    difficulty: str = "intermediate"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Flashcard:
+    """A flashcard for spaced repetition learning"""
+    front: str
+    back: str
+    category: str
+    difficulty: int = 1  # 1-5 scale
+    tags: List[str] = field(default_factory=list)
+    image_url: Optional[str] = None
+
+
+@dataclass
+class QuizQuestion:
+    """A single quiz question"""
+    id: str
+    question: str
+    question_type: str  # multiple_choice, true_false, fill_blank, short_answer
+    options: List[str] = field(default_factory=list)
+    correct_answer: str = ""
+    explanation: str = ""
+    points: int = 1
+    difficulty: str = "medium"  # easy, medium, hard
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Quiz:
+    """A quiz with multiple questions"""
+    title: str
+    questions: List[QuizQuestion] = field(default_factory=list)
+    passing_score: int = 70
+    time_limit: Optional[int] = None  # minutes
+    difficulty: DifficultyLevel = DifficultyLevel.BEGINNER
+
+
+@dataclass
+class Image:
+    """Generated or sourced image"""
+    url: str
+    caption: str
+    alt_text: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+    format: str = "png"
+
+
+@dataclass
+class ImageAsset:
+    """Represents an image asset for a course"""
+    id: str
+    title: str
+    description: str
+    image_url: str
+    local_path: Optional[str] = None
+    image_type: str = "illustration"  # cover, illustration, concept, diagram, infographic
+    lesson_id: Optional[int] = None
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ContentSource:
+    """Represents a content source for research"""
+    title: str
+    url: str
+    content: str
+    source_type: str  # web, research, documentation, model, dataset, concept
+    relevance_score: float = 0.5
+    credibility_score: float = 0.5
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ResearchResult:
+    """Results from research conducted for a topic"""
+    topic: str
+    sources: List[ContentSource] = field(default_factory=list)
+    key_concepts: List[str] = field(default_factory=list)
+    learning_objectives: List[str] = field(default_factory=list)
+    difficulty_level: str = "intermediate"
+    target_audience: str = "general"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CourseStructure:
+    """High-level course structure and planning"""
+    title: str
+    description: str
+    difficulty_level: str = "intermediate"
+    estimated_duration: float = 2.0  # hours
+    prerequisites: List[str] = field(default_factory=list)
+    learning_objectives: List[str] = field(default_factory=list)
+    lessons: List['Lesson'] = field(default_factory=list)  # Forward reference
+    tags: List[str] = field(default_factory=list)
+    target_audience: str = "general"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Lesson:
+    """A single lesson in the course"""
+    title: str
+    content: str
+    objectives: List[LearningObjective]
+    duration: int  # minutes
+    exercises: List[Exercise] = field(default_factory=list)
+    images: List[Image] = field(default_factory=list)
+    flashcards: List[Flashcard] = field(default_factory=list)
+    quiz: Optional[Quiz] = None
+    prerequisites: List[str] = field(default_factory=list)
+    key_concepts: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CourseMetadata:
+    """Metadata about the course"""
+    created_at: datetime
+    topic: str
+    difficulty: DifficultyLevel
+    estimated_duration: int  # total minutes
+    sources: List[Source]
+    word_count: int
+    lesson_count: int
+    flashcard_count: int
+    image_count: int
+    target_audience: str = "general"
+    prerequisites: List[str] = field(default_factory=list)
+    learning_outcomes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Course:
+    """Complete course structure"""
+    title: str
+    description: str
+    lessons: List[Lesson]
+    metadata: CourseMetadata
+    flashcards: List[Flashcard] = field(default_factory=list)
+    images: List[Image] = field(default_factory=list)
+    summary: str = ""
+    glossary: Dict[str, str] = field(default_factory=dict)
+    resources: List[Source] = field(default_factory=list)
+
+
+@dataclass
+class ResearchData:
+    """Research data collected for course generation"""
+    topic: str
+    sources: List[Source]
+    key_concepts: List[str]
+    content_outline: Dict[str, Any]
+    related_topics: List[str] = field(default_factory=list)
+    expert_quotes: List[str] = field(default_factory=list)
+    statistics: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CourseOutline:
+    """High-level course structure"""
+    title: str
+    description: str
+    difficulty: DifficultyLevel
+    lesson_titles: List[str]
+    learning_objectives: List[LearningObjective]
+    estimated_duration: int
+    prerequisites: List[str] = field(default_factory=list)
+
+
+@dataclass
+class GenerationOptions:
+    """Options for course generation"""
+    difficulty: DifficultyLevel = DifficultyLevel.BEGINNER
+    lesson_count: int = 5
+    include_audio: bool = False
+    include_images: bool = True
+    include_flashcards: bool = True
+    include_quizzes: bool = True
+    learning_style: LearningStyle = LearningStyle.VISUAL
+    max_lesson_duration: int = 30  # minutes
+    export_formats: List[ExportFormat] = field(default_factory=list)
+
+
+@dataclass
+class ExportResult:
+    """Result of an export operation"""
+    format: ExportFormat
+    success: bool
+    file_path: Optional[str] = None
+    download_url: Optional[str] = None
+    error_message: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ProgressUpdate:
+    """Progress update during course generation"""
+    stage: str
+    progress: float  # 0.0 to 1.0
+    message: str
+    details: Optional[Dict[str, Any]] = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+# LLM Provider Types
+LLMProvider = Literal["openai", "anthropic", "google", "openai_compatible"]
+
+
+@dataclass
+class LLMConfig:
+    """Configuration for LLM providers"""
+    provider: LLMProvider
+    model: str
+    api_key: str
+    temperature: float = 0.7
+    max_tokens: Optional[int] = None
+    timeout: int = 60
+
+# API Response Types
+@dataclass
+class APIResponse:
+    """Standard API response structure"""
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+# Validation Types
+@dataclass
+class ValidationResult:
+    """Result of content validation"""
+    is_valid: bool
+    score: float  # 0.0 to 1.0
+    issues: List[str] = field(default_factory=list)
+    suggestions: List[str] = field(default_factory=list)
+
+
+# Stream Types for real-time updates
+@dataclass
+class StreamChunk:
+    """Chunk of streaming data"""
+    type: Literal["text", "tool_call", "progress", "error"]
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)

coursecrafter/ui/__init__.py

@@ -0,0 +1,16 @@
+"""
+🖥️ User Interface Components
+
+Gradio interface and custom UI components.
+"""
+
+from .gradio_app import create_coursecrafter_interface
+from .components import CoursePreview, FlashcardViewer, ProgressTracker
+from .styling import get_custom_css, get_theme_colors, get_component_styles
+
+__all__ = [
+    "create_coursecrafter_interface",
+    "CoursePreview",
+    "FlashcardViewer",
+    "ProgressTracker"
+]

coursecrafter/ui/components.py

@@ -0,0 +1,703 @@
+"""
+🎨 UI Components for Course Creator AI
+
+Beautiful, modern Gradio components with custom styling and interactions.
+"""
+
+import gradio as gr
+import json
+from typing import Dict, List, Any, Optional, Tuple
+from dataclasses import asdict
+import logging
+
+from ..types import Course, Lesson, Flashcard, Quiz, ImageAsset
+
+logger = logging.getLogger(__name__)
+
+
+class CourseGenerationForm:
+    """Main course generation form component"""
+
+    def __init__(self):
+        self.current_course = None
+        self.generation_progress = 0
+
+    def create_input_form(self) -> gr.Group:
+        """Create the main input form for course generation"""
+
+        with gr.Group() as form:
+            gr.HTML("""
+                <div class="header-section">
+                    <h1>🚀 Course Creater AI</h1>
+                    <p class="tagline">Transform any topic into an engaging course with AI</p>
+                </div>
+            """)
+
+            with gr.Row():
+                with gr.Column(scale=2):
+                    # Main topic input
+                    topic_input = gr.Textbox(
+                        label="📚 Course Topic",
+                        placeholder="e.g., Introduction to Machine Learning, Python for Beginners, Digital Marketing Basics",
+                        lines=2,
+                        elem_id="topic-input"
+                    )
+
+                    # Course configuration
+                    with gr.Row():
+                        difficulty_level = gr.Dropdown(
+                            choices=["Beginner", "Intermediate", "Advanced"],
+                            value="Intermediate",
+                            label="🎯 Difficulty Level",
+                            elem_id="difficulty-select"
+                        )
+
+                        duration = gr.Slider(
+                            minimum=0.5,
+                            maximum=8.0,
+                            value=2.0,
+                            step=0.5,
+                            label="⏱️ Duration (hours)",
+                            elem_id="duration-slider"
+                        )
+
+                    with gr.Row():
+                        num_lessons = gr.Slider(
+                            minimum=3,
+                            maximum=12,
+                            value=6,
+                            step=1,
+                            label="📖 Number of Lessons",
+                            elem_id="lessons-slider"
+                        )
+
+                        target_audience = gr.Dropdown(
+                            choices=["Students", "Professionals", "Hobbyists", "General Public"],
+                            value="General Public",
+                            label="👥 Target Audience",
+                            elem_id="audience-select"
+                        )
+
+                with gr.Column(scale=1):
+                    # Advanced options
+                    gr.HTML("<h3>🔧 Advanced Options</h3>")
+
+                    include_images = gr.Checkbox(
+                        value=True,
+                        label="🎨 Generate Images",
+                        elem_id="images-checkbox"
+                    )
+
+                    include_quizzes = gr.Checkbox(
+                        value=True,
+                        label="🎯 Include Quizzes",
+                        elem_id="quizzes-checkbox"
+                    )
+
+                    include_flashcards = gr.Checkbox(
+                        value=True,
+                        label="🃏 Create Flashcards",
+                        elem_id="flashcards-checkbox"
+                    )
+
+                    content_style = gr.Dropdown(
+                        choices=["Conversational", "Technical", "Academic", "Casual"],
+                        value="Conversational",
+                        label="✍️ Content Style",
+                        elem_id="style-select"
+                    )
+
+            # Generation button
+            with gr.Row():
+                generate_btn = gr.Button(
+                    "🚀 Generate Course",
+                    variant="primary",
+                    size="lg",
+                    elem_id="generate-button"
+                )
+
+                clear_btn = gr.Button(
+                    "🗑️ Clear",
+                    variant="secondary",
+                    elem_id="clear-button"
+                )
+
+        return form, {
+            "topic_input": topic_input,
+            "difficulty_level": difficulty_level,
+            "duration": duration,
+            "num_lessons": num_lessons,
+            "target_audience": target_audience,
+            "include_images": include_images,
+            "include_quizzes": include_quizzes,
+            "include_flashcards": include_flashcards,
+            "content_style": content_style,
+            "generate_btn": generate_btn,
+            "clear_btn": clear_btn
+        }
+
+
+class ProgressTracker:
+    """Real-time progress tracking component"""
+
+    def __init__(self):
+        self.current_step = 0
+        self.total_steps = 6
+        self.step_names = [
+            "🔍 Researching Topic",
+            "📋 Planning Course Structure",
+            "✍️ Generating Content",
+            "🎯 Creating Assessments",
+            "🎨 Generating Images",
+            "📦 Finalizing Course"
+        ]
+
+    def create_progress_display(self) -> gr.Group:
+        """Create progress tracking display"""
+
+        with gr.Group() as progress_group:
+            gr.HTML("<h3>📊 Generation Progress</h3>")
+
+            # Progress bar
+            progress_bar = gr.Progress()
+
+            # Current step indicator
+            current_step_display = gr.HTML(
+                "<div class='step-indicator'>Ready to generate course</div>",
+                elem_id="step-indicator"
+            )
+
+            # Detailed progress log
+            progress_log = gr.Textbox(
+                label="📝 Progress Log",
+                lines=8,
+                max_lines=15,
+                interactive=False,
+                elem_id="progress-log"
+            )
+
+            # Status indicators
+            with gr.Row():
+                research_status = gr.HTML("⏳ Research", elem_id="research-status")
+                planning_status = gr.HTML("⏳ Planning", elem_id="planning-status")
+                content_status = gr.HTML("⏳ Content", elem_id="content-status")
+                assessment_status = gr.HTML("⏳ Assessment", elem_id="assessment-status")
+                images_status = gr.HTML("⏳ Images", elem_id="images-status")
+                finalize_status = gr.HTML("⏳ Finalize", elem_id="finalize-status")
+
+        return progress_group, {
+            "progress_bar": progress_bar,
+            "current_step_display": current_step_display,
+            "progress_log": progress_log,
+            "status_indicators": {
+                "research": research_status,
+                "planning": planning_status,
+                "content": content_status,
+                "assessment": assessment_status,
+                "images": images_status,
+                "finalize": finalize_status
+            }
+        }
+
+    def update_progress(self, step: int, message: str, log_entry: str = "") -> Tuple[str, str]:
+        """Update progress display"""
+
+        self.current_step = step
+        progress_percent = (step / self.total_steps) * 100
+
+        # Update step indicator
+        if step < len(self.step_names):
+            step_html = f"""
+                <div class='step-indicator active'>
+                    <div class='step-icon'>{self.step_names[step].split()[0]}</div>
+                    <div class='step-text'>{self.step_names[step]}</div>
+                    <div class='step-message'>{message}</div>
+                </div>
+            """
+        else:
+            step_html = "<div class='step-indicator complete'>✅ Course Generation Complete!</div>"
+
+        return step_html, log_entry
+
+
+class CoursePreview:
+    """Interactive course preview component"""
+
+    def __init__(self):
+        self.current_course = None
+
+    def create_preview_tabs(self) -> gr.Tabs:
+        """Create tabbed course preview interface"""
+
+        with gr.Tabs() as preview_tabs:
+            # Course Overview Tab
+            with gr.Tab("📚 Course Overview", elem_id="overview-tab"):
+                course_overview = self._create_overview_section()
+
+            # Lessons Tab
+            with gr.Tab("📖 Lessons", elem_id="lessons-tab"):
+                lessons_section = self._create_lessons_section()
+
+            # Flashcards Tab
+            with gr.Tab("🃏 Flashcards", elem_id="flashcards-tab"):
+                flashcards_section = self._create_flashcards_section()
+
+            # Quizzes Tab
+            with gr.Tab("🎯 Quizzes", elem_id="quizzes-tab"):
+                quizzes_section = self._create_quizzes_section()
+
+            # Images Tab
+            with gr.Tab("🎨 Images", elem_id="images-tab"):
+                images_section = self._create_images_section()
+
+            # Export Tab
+            with gr.Tab("📤 Export", elem_id="export-tab"):
+                export_section = self._create_export_section()
+
+        return preview_tabs, {
+            "course_overview": course_overview,
+            "lessons_section": lessons_section,
+            "flashcards_section": flashcards_section,
+            "quizzes_section": quizzes_section,
+            "images_section": images_section,
+            "export_section": export_section
+        }
+
+    def _create_overview_section(self) -> Dict[str, Any]:
+        """Create course overview section"""
+
+        with gr.Group():
+            # Course header
+            course_title = gr.HTML(
+                "<h2>Course will appear here after generation</h2>",
+                elem_id="course-title"
+            )
+
+            course_metadata = gr.HTML(
+                "<div class='course-metadata'>Generate a course to see details</div>",
+                elem_id="course-metadata"
+            )
+
+            # Course description
+            course_description = gr.Markdown(
+                "Course description will appear here...",
+                elem_id="course-description"
+            )
+
+            # Learning objectives
+            learning_objectives = gr.HTML(
+                "<div class='learning-objectives'>Learning objectives will appear here</div>",
+                elem_id="learning-objectives"
+            )
+
+            # Course structure
+            course_structure = gr.HTML(
+                "<div class='course-structure'>Course structure will appear here</div>",
+                elem_id="course-structure"
+            )
+
+        return {
+            "course_title": course_title,
+            "course_metadata": course_metadata,
+            "course_description": course_description,
+            "learning_objectives": learning_objectives,
+            "course_structure": course_structure
+        }
+
+    def _create_lessons_section(self) -> Dict[str, Any]:
+        """Create lessons preview section"""
+
+        with gr.Group():
+            # Lesson selector
+            lesson_selector = gr.Dropdown(
+                choices=[],
+                label="📖 Select Lesson",
+                elem_id="lesson-selector"
+            )
+
+            # Lesson content display
+            lesson_title = gr.HTML(
+                "<h3>Select a lesson to view content</h3>",
+                elem_id="lesson-title"
+            )
+
+            lesson_content = gr.Markdown(
+                "Lesson content will appear here...",
+                elem_id="lesson-content"
+            )
+
+            # Lesson navigation
+            with gr.Row():
+                prev_lesson_btn = gr.Button(
+                    "⬅️ Previous",
+                    elem_id="prev-lesson-btn"
+                )
+                next_lesson_btn = gr.Button(
+                    "➡️ Next",
+                    elem_id="next-lesson-btn"
+                )
+
+        return {
+            "lesson_selector": lesson_selector,
+            "lesson_title": lesson_title,
+            "lesson_content": lesson_content,
+            "prev_lesson_btn": prev_lesson_btn,
+            "next_lesson_btn": next_lesson_btn
+        }
+
+    def _create_flashcards_section(self) -> Dict[str, Any]:
+        """Create flashcards preview section"""
+
+        with gr.Group():
+            # Flashcard display
+            flashcard_display = gr.HTML(
+                "<div class='flashcard-container'>Flashcards will appear here</div>",
+                elem_id="flashcard-display"
+            )
+
+            # Flashcard controls
+            with gr.Row():
+                flip_card_btn = gr.Button(
+                    "🔄 Flip Card",
+                    elem_id="flip-card-btn"
+                )
+                prev_card_btn = gr.Button(
+                    "⬅️ Previous",
+                    elem_id="prev-card-btn"
+                )
+                next_card_btn = gr.Button(
+                    "➡️ Next",
+                    elem_id="next-card-btn"
+                )
+
+            # Flashcard progress
+            flashcard_progress = gr.HTML(
+                "<div class='flashcard-progress'>Card 1 of 0</div>",
+                elem_id="flashcard-progress"
+            )
+
+        return {
+            "flashcard_display": flashcard_display,
+            "flip_card_btn": flip_card_btn,
+            "prev_card_btn": prev_card_btn,
+            "next_card_btn": next_card_btn,
+            "flashcard_progress": flashcard_progress
+        }
+
+    def _create_quizzes_section(self) -> Dict[str, Any]:
+        """Create quizzes preview section"""
+
+        with gr.Group():
+            # Quiz selector
+            quiz_selector = gr.Dropdown(
+                choices=[],
+                label="🎯 Select Quiz",
+                elem_id="quiz-selector"
+            )
+
+            # Quiz display
+            quiz_content = gr.HTML(
+                "<div class='quiz-container'>Select a quiz to begin</div>",
+                elem_id="quiz-content"
+            )
+
+            # Quiz controls
+            with gr.Row():
+                start_quiz_btn = gr.Button(
+                    "▶️ Start Quiz",
+                    variant="primary",
+                    elem_id="start-quiz-btn"
+                )
+                reset_quiz_btn = gr.Button(
+                    "🔄 Reset",
+                    elem_id="reset-quiz-btn"
+                )
+
+        return {
+            "quiz_selector": quiz_selector,
+            "quiz_content": quiz_content,
+            "start_quiz_btn": start_quiz_btn,
+            "reset_quiz_btn": reset_quiz_btn
+        }
+
+    def _create_images_section(self) -> Dict[str, Any]:
+        """Create images gallery section"""
+
+        with gr.Group():
+            # Image gallery
+            image_gallery = gr.Gallery(
+                label="🎨 Generated Images",
+                show_label=True,
+                elem_id="image-gallery",
+                columns=3,
+                rows=2,
+                height="auto"
+            )
+
+            # Image details
+            image_details = gr.HTML(
+                "<div class='image-details'>Select an image to view details</div>",
+                elem_id="image-details"
+            )
+
+        return {
+            "image_gallery": image_gallery,
+            "image_details": image_details
+        }
+
+    def _create_export_section(self) -> Dict[str, Any]:
+        """Create export options section"""
+
+        with gr.Group():
+            gr.HTML("<h3>📤 Export Your Course</h3>")
+
+            # Export format selection
+            with gr.Row():
+                export_pdf = gr.Checkbox(
+                    value=True,
+                    label="📄 PDF Course Book"
+                )
+                export_json = gr.Checkbox(
+                    value=True,
+                    label="📋 JSON Data"
+                )
+                export_anki = gr.Checkbox(
+                    value=False,
+                    label="🃏 Anki Deck"
+                )
+
+            with gr.Row():
+                export_notion = gr.Checkbox(
+                    value=False,
+                    label="📝 Notion Pages"
+                )
+                export_github = gr.Checkbox(
+                    value=False,
+                    label="🐙 GitHub Repository"
+                )
+                export_drive = gr.Checkbox(
+                    value=False,
+                    label="☁️ Google Drive"
+                )
+
+            # Export button
+            export_btn = gr.Button(
+                "📦 Export Course",
+                variant="primary",
+                size="lg",
+                elem_id="export-btn"
+            )
+
+            # Download links
+            download_links = gr.HTML(
+                "<div class='download-links'>Export files will appear here</div>",
+                elem_id="download-links"
+            )
+
+        return {
+            "export_options": {
+                "pdf": export_pdf,
+                "json": export_json,
+                "anki": export_anki,
+                "notion": export_notion,
+                "github": export_github,
+                "drive": export_drive
+            },
+            "export_btn": export_btn,
+            "download_links": download_links
+        }
+
+
+class FlashcardViewer:
+    """Interactive flashcard viewer component"""
+
+    def __init__(self):
+        self.current_card_index = 0
+        self.show_back = False
+        self.flashcards = []
+
+    def create_flashcard_interface(self, flashcards: List[Flashcard]) -> gr.Group:
+        """Create interactive flashcard viewer"""
+
+        self.flashcards = flashcards
+
+        with gr.Group() as flashcard_group:
+            gr.HTML("<h3>🃏 Interactive Flashcards</h3>")
+
+            if not flashcards:
+                gr.HTML("<p>No flashcards available</p>")
+                return flashcard_group, {}
+
+            # Card counter
+            card_counter = gr.HTML(
+                f"<div class='card-counter'>Card 1 of {len(flashcards)}</div>",
+                elem_id="card-counter"
+            )
+
+            # Flashcard display
+            with gr.Row():
+                with gr.Column(scale=1):
+                    # Card content
+                    card_display = gr.HTML(
+                        self._format_flashcard_html(flashcards[0], show_back=False),
+                        elem_id="flashcard-display"
+                    )
+
+                    # Flip button
+                    flip_btn = gr.Button(
+                        "🔄 Flip Card",
+                        variant="secondary",
+                        elem_id="flip-button"
+                    )
+
+                    # Navigation buttons
+                    with gr.Row():
+                        prev_btn = gr.Button(
+                            "⬅️ Previous",
+                            variant="secondary",
+                            interactive=False,
+                            elem_id="prev-button"
+                        )
+
+                        next_btn = gr.Button(
+                            "➡️ Next",
+                            variant="secondary",
+                            interactive=len(flashcards) > 1,
+                            elem_id="next-button"
+                        )
+
+        return flashcard_group, {
+            "card_counter": card_counter,
+            "card_display": card_display,
+            "flip_btn": flip_btn,
+            "prev_btn": prev_btn,
+            "next_btn": next_btn
+        }
+
+    def _format_flashcard_html(self, flashcard: Flashcard, show_back: bool = False) -> str:
+        """Format flashcard as HTML"""
+
+        if show_back:
+            content = f"""
+            <div class="flashcard flashcard-back">
+                <div class="flashcard-header">Answer</div>
+                <div class="flashcard-content">{flashcard.back}</div>
+                <div class="flashcard-footer">
+                    <span class="difficulty">{flashcard.difficulty}</span>
+                    <span class="tags">{', '.join(flashcard.tags) if flashcard.tags else ''}</span>
+                </div>
+            </div>
+            """
+        else:
+            content = f"""
+            <div class="flashcard flashcard-front">
+                <div class="flashcard-header">Question</div>
+                <div class="flashcard-content">{flashcard.front}</div>
+                <div class="flashcard-footer">
+                    <span class="difficulty">{flashcard.difficulty}</span>
+                </div>
+            </div>
+            """
+
+        return content
+
+
+class UIHelpers:
+    """Helper functions for UI components"""
+
+    @staticmethod
+    def format_course_metadata(course: Course) -> str:
+        """Format course metadata for display"""
+
+        metadata_html = f"""
+        <div class="course-metadata">
+            <div class="metadata-item">
+                <span class="label">🎯 Difficulty:</span>
+                <span class="value">{course.difficulty_level}</span>
+            </div>
+            <div class="metadata-item">
+                <span class="label">⏱️ Duration:</span>
+                <span class="value">{course.estimated_duration} hours</span>
+            </div>
+            <div class="metadata-item">
+                <span class="label">📖 Lessons:</span>
+                <span class="value">{len(course.lessons)}</span>
+            </div>
+            <div class="metadata-item">
+                <span class="label">👥 Audience:</span>
+                <span class="value">{course.target_audience}</span>
+            </div>
+            <div class="metadata-item">
+                <span class="label">🏷️ Tags:</span>
+                <span class="value">{', '.join(course.tags)}</span>
+            </div>
+        </div>
+        """
+
+        return metadata_html
+
+    @staticmethod
+    def format_learning_objectives(objectives: List[str]) -> str:
+        """Format learning objectives for display"""
+
+        objectives_html = """
+        <div class="learning-objectives">
+            <h4>🎯 Learning Objectives</h4>
+            <ul>
+        """
+
+        for objective in objectives:
+            objectives_html += f"<li>{objective}</li>"
+
+        objectives_html += """
+            </ul>
+        </div>
+        """
+
+        return objectives_html
+
+    @staticmethod
+    def format_flashcard(flashcard: Flashcard, show_back: bool = False) -> str:
+        """Format flashcard for display"""
+
+        card_class = "flashcard flipped" if show_back else "flashcard"
+        content = flashcard.back if show_back else flashcard.front
+
+        flashcard_html = f"""
+        <div class="{card_class}">
+            <div class="flashcard-content">
+                <div class="flashcard-category">{flashcard.category}</div>
+                <div class="flashcard-text">{content}</div>
+                <div class="flashcard-difficulty">Difficulty: {flashcard.difficulty}/5</div>
+            </div>
+        </div>
+        """
+
+        return flashcard_html
+
+    @staticmethod
+    def create_error_display(error_message: str) -> str:
+        """Create error display HTML"""
+
+        error_html = f"""
+        <div class="error-display">
+            <div class="error-icon">❌</div>
+            <div class="error-message">{error_message}</div>
+            <div class="error-suggestion">Please try again or contact support if the issue persists.</div>
+        </div>
+        """
+
+        return error_html
+
+    @staticmethod
+    def create_success_display(success_message: str) -> str:
+        """Create success display HTML"""
+
+        success_html = f"""
+        <div class="success-display">
+            <div class="success-icon">✅</div>
+            <div class="success-message">{success_message}</div>
+        </div>
+        """
+
+        return success_html

coursecrafter/ui/gradio_app.py

@@ -0,0 +1,1483 @@
+"""
+🎨 Gradio Application for Course Creator AI
+
+Main Gradio interface for course generation.
+"""
+
+import gradio as gr
+from typing import Dict, Any, Optional, Tuple
+import asyncio
+import json
+import markdown
+import re
+
+from ..agents.simple_course_agent import SimpleCourseAgent
+from ..types import DifficultyLevel, GenerationOptions, LearningStyle
+from .components import CoursePreview
+from .styling import get_custom_css
+
+
+def format_lessons(lessons: list) -> str:
+    """Format lessons from JSON data into HTML with dark theme and markdown support"""
+    if not lessons:
+        return "<div class='info'>📚 No lessons generated yet.</div>"
+
+    # Add CSS for lesson styling
+    css = """
+    <style>
+    /* Force dark theme for all lesson elements */
+    .lessons-container * {
+        background: transparent !important;
+        color: inherit !important;
+    }
+
+    .lessons-container {
+        padding: 1rem !important;
+        background: #1a1a2e !important;
+        border-radius: 12px !important;
+        margin: 1rem 0 !important;
+        max-height: none !important;
+        overflow: visible !important;
+    }
+
+    .lesson-card {
+        background: #2d2d54 !important;
+        border: 1px solid #4a4a7a !important;
+        border-radius: 12px !important;
+        padding: 2rem !important;
+        margin: 1.5rem 0 !important;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3) !important;
+        color: #e0e7ff !important;
+    }
+
+    .lesson-card h3 {
+        color: #667eea !important;
+        margin-bottom: 1rem !important;
+        font-size: 1.5rem !important;
+        border-bottom: 2px solid #667eea !important;
+        padding-bottom: 0.5rem !important;
+        background: transparent !important;
+    }
+
+    .lesson-card h4 {
+        color: #8b9dc3 !important;
+        margin: 1.5rem 0 0.75rem 0 !important;
+        font-size: 1.2rem !important;
+        background: transparent !important;
+    }
+
+    .lesson-card p {
+        color: #b8c5d6 !important;
+        line-height: 1.6 !important;
+        margin: 0.75rem 0 !important;
+        font-size: 1rem !important;
+        background: transparent !important;
+    }
+
+    .lesson-card ul {
+        color: #e0e7ff !important;
+        margin: 0.75rem 0 !important;
+        padding-left: 1.5rem !important;
+        background: transparent !important;
+    }
+
+    .lesson-card li {
+        color: #e0e7ff !important;
+        margin: 0.5rem 0 !important;
+        line-height: 1.5 !important;
+        background: transparent !important;
+    }
+
+    .lesson-content {
+        background: #3a3a6b !important;
+        border-radius: 8px !important;
+        padding: 1.5rem !important;
+        margin: 1rem 0 !important;
+        border-left: 4px solid #667eea !important;
+    }
+
+    .lesson-content h1, .lesson-content h2, .lesson-content h3,
+    .lesson-content h4, .lesson-content h5, .lesson-content h6 {
+        color: #667eea !important;
+        margin: 1rem 0 0.5rem 0 !important;
+        background: transparent !important;
+    }
+
+    .lesson-content p {
+        color: #e0e7ff !important;
+        margin: 0.75rem 0 !important;
+        line-height: 1.6 !important;
+        background: transparent !important;
+    }
+
+    .lesson-content ul, .lesson-content ol {
+        color: #e0e7ff !important;
+        margin: 0.75rem 0 !important;
+        padding-left: 1.5rem !important;
+        background: transparent !important;
+    }
+
+    .lesson-content li {
+        color: #e0e7ff !important;
+        margin: 0.5rem 0 !important;
+        background: transparent !important;
+    }
+
+    .lesson-content strong {
+        color: #8b9dc3 !important;
+    }
+
+    .lesson-content em {
+        color: #b8c5d6 !important;
+    }
+
+    .lesson-content code {
+        background: #4a4a7a !important;
+        color: #e0e7ff !important;
+        padding: 0.2rem 0.4rem;
+        border-radius: 4px;
+        font-family: monospace;
+    }
+
+    .lesson-content pre {
+        background: #4a4a7a !important;
+        color: #e0e7ff !important;
+        padding: 1rem;
+        border-radius: 8px;
+        overflow-x: auto;
+        margin: 1rem 0;
+    }
+
+    .lesson-card ul {
+        color: #e0e7ff !important;
+        margin: 0.75rem 0;
+        padding-left: 1.5rem;
+    }
+
+    .lesson-card li {
+        color: #e0e7ff !important;
+        margin: 0.5rem 0;
+        line-height: 1.5;
+    }
+
+    .lesson-image {
+        margin: 1.5rem 0;
+        text-align: center;
+    }
+
+    .image-placeholder {
+        background: #4a4a7a;
+        border: 2px dashed #667eea;
+        border-radius: 8px;
+        padding: 2rem;
+        text-align: center;
+        color: #b8c5d6;
+    }
+
+    .image-icon {
+        font-size: 3rem;
+        margin-bottom: 1rem;
+    }
+
+    .image-description {
+        font-size: 1.1rem;
+        margin-bottom: 0.5rem;
+        color: #e0e7ff;
+    }
+
+    .image-note {
+        font-size: 0.9rem;
+        font-style: italic;
+        opacity: 0.7;
+    }
+
+    .duration-info {
+        background: #4a4a7a !important;
+        color: #e0e7ff !important;
+        padding: 0.5rem 1rem !important;
+        border-radius: 20px !important;
+        display: inline-block !important;
+        margin-bottom: 1rem !important;
+        font-size: 0.9rem !important;
+    }
+
+    /* Ultimate override for any stubborn white backgrounds */
+    .lessons-container .lesson-card,
+    .lessons-container .lesson-card *,
+    .lessons-container .lesson-content,
+    .lessons-container .lesson-content * {
+        background-color: transparent !important;
+    }
+
+    .lessons-container .lesson-card {
+        background: #2d2d54 !important;
+    }
+
+    .lessons-container .lesson-content {
+        background: #3a3a6b !important;
+    }
+    </style>
+    """
+
+    html = css + "<div class='lessons-container'>"
+    for i, lesson in enumerate(lessons, 1):
+        title = lesson.get("title", f"Lesson {i}")
+        content = lesson.get("content", "")
+        duration = lesson.get("duration", "")
+        objectives = lesson.get("objectives", [])
+        key_takeaways = lesson.get("key_takeaways", [])
+        image_description = lesson.get("image_description", "")
+
+        # Convert markdown content to HTML
+        if content:
+            try:
+                # Create markdown instance with extensions
+                import markdown
+                md = markdown.Markdown(extensions=['extra', 'codehilite'])
+                content_html = md.convert(content)
+            except ImportError:
+                # Fallback if markdown is not available
+                content_html = content.replace('\n\n', '</p><p>').replace('\n', '<br>')
+                if content_html and not content_html.startswith('<p>'):
+                    content_html = f'<p>{content_html}</p>'
+        else:
+            content_html = "<p>No content available.</p>"
+
+        # Generate image placeholder or actual image
+        image_html = ""
+        if image_description:
+            # Check if we have actual image data
+            images = lesson.get("images", [])
+            if images and len(images) > 0:
+                # Display actual generated images
+                image_html = "<div class='lesson-images'>"
+                for img in images:
+                    if isinstance(img, dict) and img.get("url"):
+                        img_url = img.get("url", "")
+                        img_caption = img.get("description", image_description)
+                        image_html += f"""
+                        <div class='lesson-image'>
+                            <img src='{img_url}' alt='{img_caption}' loading='lazy' style='max-width: 100%; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.3); border: 2px solid #4a4a7a;'>
+                            <p class='image-caption'>{img_caption}</p>
+                        </div>
+                        """
+                image_html += "</div>"
+            else:
+                # Fallback to placeholder
+                image_html = f"""
+                <div class='lesson-image'>
+                    <div class='image-placeholder'>
+                        <div class='image-icon'>🖼️</div>
+                        <div class='image-description'>{image_description}</div>
+                        <div class='image-note'>(Image generation in progress...)</div>
+                    </div>
+                </div>
+                """
+
+        html += f"""
+        <div class='lesson-card'>
+            <h3>📖 {title}</h3>
+            {f"<div class='duration-info'>⏱️ Duration: {duration} minutes</div>" if duration else ""}
+
+            {f"<h4>🎯 Learning Objectives:</h4><ul>{''.join([f'<li>{obj}</li>' for obj in objectives])}</ul>" if objectives else ""}
+
+            {image_html}
+
+            <div class='lesson-content'>
+                {content_html}
+            </div>
+
+            {f"<h4>💡 Key Takeaways:</h4><ul>{''.join([f'<li>{takeaway}</li>' for takeaway in key_takeaways])}</ul>" if key_takeaways else ""}
+        </div>
+        """
+    html += "</div>"
+    return html
+
+
+def format_flashcards(flashcards: list) -> str:
+    """Format flashcards from JSON data into interactive HTML with CSS-only flip"""
+    if not flashcards:
+        return "<div class='info'>🃏 No flashcards generated yet.</div>"
+
+    # Add the CSS for flashcard flip functionality
+    css = """
+    <style>
+    .flashcards-container {
+        padding: 1rem;
+        background: #1a1a2e;
+        border-radius: 12px;
+        margin: 1rem 0;
+        max-height: none !important;
+        overflow: visible !important;
+    }
+
+    .flashcard-wrapper {
+        perspective: 1000px;
+        margin: 1rem 0;
+        height: 200px;
+    }
+
+    .flip-checkbox {
+        display: none;
+    }
+
+    .flashcard {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        cursor: pointer;
+        transform-style: preserve-3d;
+        transition: transform 0.6s;
+        display: block;
+    }
+
+    .flip-checkbox:checked + .flashcard {
+        transform: rotateY(180deg);
+    }
+
+    .flashcard-inner {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        transform-style: preserve-3d;
+    }
+
+    .flashcard-front, .flashcard-back {
+        position: absolute;
+        width: 100%;
+        height: 100%;
+        backface-visibility: hidden;
+        border-radius: 12px;
+        padding: 1.5rem;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        text-align: center;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3);
+    }
+
+    .flashcard-front {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+    }
+
+    .flashcard-back {
+        background: linear-gradient(135deg, #764ba2 0%, #667eea 100%);
+        color: white;
+        transform: rotateY(180deg);
+    }
+
+    .flashcard-category {
+        position: absolute;
+        top: 10px;
+        right: 15px;
+        background: rgba(255,255,255,0.2);
+        padding: 0.25rem 0.5rem;
+        border-radius: 12px;
+        font-size: 0.8rem;
+        font-weight: bold;
+    }
+
+    .flashcard-content {
+        font-size: 1.2rem;
+        font-weight: 500;
+        line-height: 1.4;
+        margin: 1rem 0;
+        color: white;
+    }
+
+    .flashcard-hint {
+        position: absolute;
+        bottom: 10px;
+        left: 50%;
+        transform: translateX(-50%);
+        font-size: 0.8rem;
+        opacity: 0.8;
+        font-style: italic;
+    }
+
+    .flashcard:hover {
+        box-shadow: 0 6px 12px rgba(0,0,0,0.4);
+    }
+    </style>
+    """
+
+    html = css + "<div class='flashcards-container'>"
+    html += "<p style='color: #e0e7ff; text-align: center; margin-bottom: 1rem;'><strong>🃏 Click on any flashcard to flip it and see the answer!</strong></p>"
+
+    for i, card in enumerate(flashcards):
+        question = card.get("question", "")
+        answer = card.get("answer", "")
+        category = card.get("category", "General")
+
+        # Use CSS-only flip with checkbox hack
+        html += f"""
+        <div class='flashcard-wrapper'>
+            <input type='checkbox' id='flip-{i}' class='flip-checkbox'>
+            <label for='flip-{i}' class='flashcard'>
+                <div class='flashcard-inner'>
+                    <div class='flashcard-front'>
+                        <div class='flashcard-category'>{category}</div>
+                        <div class='flashcard-content'>{question}</div>
+                        <div class='flashcard-hint'>Click to flip</div>
+                    </div>
+                    <div class='flashcard-back'>
+                        <div class='flashcard-category'>{category}</div>
+                        <div class='flashcard-content'>{answer}</div>
+                        <div class='flashcard-hint'>Click to flip back</div>
+                    </div>
+                </div>
+            </label>
+        </div>
+        """
+
+    html += "</div>"
+    return html
+
+
+def format_quiz(quiz: dict) -> str:
+    """Format quiz from JSON data into interactive HTML with working JavaScript."""
+    if not quiz or not quiz.get("questions"):
+        return "<div class='info'>📝 No quiz generated yet.</div>"
+
+    title = quiz.get("title", "Course Quiz")
+    instructions = quiz.get("instructions", "Choose the best answer for each question.")
+    questions = quiz.get("questions", [])
+    
+    if not questions:
+        return "<div class='info'>📝 No quiz questions available.</div>"
+
+    # Generate unique quiz ID
+    quiz_id = f"quiz_{abs(hash(str(questions)))%10000}"
+
+    # CSS and JavaScript for quiz functionality
+    quiz_html = f"""
+    <style>
+      .quiz-container {{ 
+        background: #1a1a2e; 
+        border-radius: 12px; 
+        padding: 2rem; 
+        color: #e0e7ff; 
+        max-height: none !important; 
+        overflow: visible !important; 
+      }}
+      .quiz-container h3 {{ 
+        color: #667eea; 
+        text-align: center; 
+        margin-bottom: 1rem;
+      }}
+      .quiz-question {{ 
+        background: #2d2d54; 
+        border-radius: 8px; 
+        padding: 1.5rem; 
+        margin: 1.5rem 0; 
+        border-left: 4px solid #667eea;
+      }}
+      .quiz-question h4 {{ 
+        color: #e0e7ff; 
+        margin-bottom: 1rem; 
+        font-size: 1.1rem;
+      }}
+      .quiz-options {{ 
+        margin: 1rem 0; 
+      }}
+      .quiz-option-label {{ 
+        display: flex; 
+        align-items: center; 
+        padding: 0.75rem 1rem;
+        background: #3a3a6b; 
+        border: 2px solid #4a4a7a; 
+        border-radius: 8px;
+        margin: 0.5rem 0;
+        cursor: pointer; 
+        color: #e0e7ff; 
+        transition: all 0.2s;
+      }}
+      .quiz-option-label:hover {{ 
+        background: #4a4a7a; 
+        border-color: #667eea;
+      }}
+      .quiz-radio {{ 
+        display: none; 
+      }}
+      .quiz-radio:checked + .quiz-option-label {{ 
+        background: #667eea; 
+        color: white; 
+        border-color: #667eea;
+      }}
+      .radio-custom {{ 
+        width: 20px; 
+        height: 20px; 
+        border: 2px solid #667eea; 
+        border-radius: 50%; 
+        margin-right: 0.75rem;
+        position: relative;
+      }}
+      .quiz-radio:checked + .quiz-option-label .radio-custom::after {{
+        content: '';
+        width: 10px;
+        height: 10px;
+        border-radius: 50%;
+        background: white;
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+      }}
+      .quiz-feedback {{ 
+        margin-top: 1rem; 
+        padding: 1rem; 
+        border-radius: 6px; 
+        font-weight: 500;
+        display: none;
+      }}
+      .feedback-correct {{ 
+        background: #d4edda; 
+        color: #155724; 
+        border: 1px solid #c3e6cb;
+      }}
+      .feedback-incorrect {{ 
+        background: #f8d7da; 
+        color: #721c24; 
+        border: 1px solid #f5c6cb;
+      }}
+      .feedback-unanswered {{ 
+        background: #fff3cd; 
+        color: #856404; 
+        border: 1px solid #ffeaa7;
+      }}
+      .quiz-results {{ 
+        margin-top: 2rem; 
+        padding: 1.5rem; 
+        background: linear-gradient(135deg, #667eea, #764ba2); 
+        color: white; 
+        border-radius: 8px; 
+        text-align: center;
+        font-size: 1.1rem;
+        display: none;
+      }}
+      .quiz-score {{ 
+        font-size: 1.5rem; 
+        font-weight: bold; 
+        margin-bottom: 0.5rem;
+      }}
+    </style>
+
+    <div class="quiz-container" id="{quiz_id}">
+      <h3>📝 {title}</h3>
+      <p style="text-align:center; color:#b8c5d6; margin-bottom: 2rem;"><em>{instructions}</em></p>
+      <form id="quiz-form-{quiz_id}">
+    """
+
+    # Display each question
+    for idx, q in enumerate(questions):
+        question_text = q.get("question", "")
+        options = q.get("options", [])
+        correct_answer = q.get("correct_answer", "A")
+        explanation = q.get("explanation", "")
+
+        quiz_html += f"""
+        <div class="quiz-question" data-correct="{correct_answer}" data-explanation="{explanation}">
+          <h4>Q{idx+1}: {question_text}</h4>
+          <div class="quiz-options">
+        """
+        
+        # Display options
+        for j, option in enumerate(options):
+            option_letter = option[0] if option and len(option) > 0 else chr(65 + j)
+            option_text = option[3:] if option.startswith(f"{option_letter}. ") else option
+            
+            quiz_html += f"""
+            <div>
+              <input type="radio" id="q{idx}_o{j}_{quiz_id}" name="q{idx}" value="{option_letter}" class="quiz-radio">
+              <label for="q{idx}_o{j}_{quiz_id}" class="quiz-option-label">
+                <span class="radio-custom"></span>
+                <strong>{option_letter}.</strong>&nbsp;&nbsp;{option_text}
+              </label>
+            </div>
+            """
+        
+        quiz_html += f"""
+          </div>
+          <div class="quiz-feedback" id="feedback-{idx}-{quiz_id}"></div>
+        </div>
+        """
+    
+    # Close form and add results container
+    quiz_html += f"""
+      </form>
+    </div>
+
+
+    """
+    
+    return quiz_html
+
+
+def create_coursecrafter_interface() -> gr.Blocks:
+    """Create the main Course Creator Gradio interface"""
+
+    with gr.Blocks(
+        title="Course Creator AI - Intelligent Course Generator",
+        css=get_custom_css(),
+        theme=gr.themes.Soft()
+    ) as interface:
+
+        # Header
+        gr.HTML("""
+        <div class="header-container">
+            <h1>🎓 Course Creator AI</h1>
+            <p>Generate comprehensive mini-courses with AI-powered content, flashcards, and quizzes</p>
+        </div>
+        """)
+
+        # LLM Provider Configuration
+        with gr.Row():
+            with gr.Column():
+                gr.HTML("<h3>🤖 LLM Provider Configuration</h3>")
+                with gr.Row():
+                    llm_provider = gr.Dropdown(
+                        label="LLM Provider",
+                        choices=["openai", "anthropic", "google", "openai_compatible"],
+                        value="google",
+                        info="Choose your preferred LLM provider"
+                    )
+                    api_key_input = gr.Textbox(
+                        label="API Key",
+                        placeholder="Enter your API key here...",
+                        type="password",
+                        info="Your API key for the selected provider (optional for OpenAI-compatible)"
+                    )
+                
+                # OpenAI-Compatible endpoint configuration (initially hidden)
+                with gr.Row(visible=False) as openai_compatible_row:
+                    endpoint_url_input = gr.Textbox(
+                        label="Endpoint URL",
+                        placeholder="https://your-endpoint.com/v1",
+                        info="Base URL for OpenAI-compatible API"
+                    )
+                    model_name_input = gr.Textbox(
+                        label="Model Name",
+                        placeholder="your-model-name",
+                        info="Model name to use with the endpoint"
+                    )
+
+        # Main interface
+        with gr.Row():
+            with gr.Column(scale=1):
+                # Course generation form
+                topic_input = gr.Textbox(
+                    label="Course Topic",
+                    placeholder="e.g., Introduction to Python Programming",
+                    lines=1
+                )
+
+                difficulty_input = gr.Dropdown(
+                    label="Difficulty Level",
+                    choices=["beginner", "intermediate", "advanced"],
+                    value="beginner"
+                )
+
+                lesson_count = gr.Slider(
+                    label="Number of Lessons",
+                    minimum=1,
+                    maximum=10,
+                    value=5,
+                    step=1
+                )
+
+                generate_btn = gr.Button(
+                    "🚀 Generate Course",
+                    variant="primary",
+                    size="lg"
+                )
+
+                # Chat interface for course refinement
+                gr.HTML("<hr><h3>💬 Course Assistant</h3>")
+
+                # Chat window with proper styling
+                with gr.Column():
+                    chat_display = gr.HTML(
+                        value="""
+                        <div class='chat-window'>
+                            <div class='chat-messages' id='chat-messages'>
+                                <div class='chat-message assistant-message'>
+                                    <div class='message-avatar'>🤖</div>
+                                    <div class='message-content'>
+                                        <div class='message-text'>Hi! I'm your Course Assistant. Generate a course first, then ask me questions about the lessons, concepts, or content!</div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                        """,
+                        elem_id="chat-display"
+                    )
+
+                    with gr.Row():
+                        chat_input = gr.Textbox(
+                            placeholder="Ask me to modify the course...",
+                            lines=1,
+                            scale=4,
+                            container=False
+                        )
+                        chat_btn = gr.Button("Send", variant="secondary", scale=1)
+
+            with gr.Column(scale=2):
+                # Course preview tabs with enhanced components
+                course_preview = CoursePreview()
+
+                with gr.Tabs():
+                    with gr.Tab("📖 Lessons"):
+                        lessons_output = gr.HTML(
+                            value="""
+                            <div class='lessons-container' style='padding: 2rem; text-align: center; background: #1a1a2e; border-radius: 12px; color: #e0e7ff;'>
+                                <h3 style='color: #667eea; margin-bottom: 1rem;'>🎓 Ready to Generate Your Course!</h3>
+                                <p style='color: #b8c5d6; font-size: 1.1rem; margin-bottom: 1.5rem;'>Enter a topic and click "Generate Course" to create comprehensive lessons with AI-powered content.</p>
+                                <div style='background: #2d2d54; padding: 1.5rem; border-radius: 8px; border-left: 4px solid #667eea;'>
+                                    <p style='color: #e0e7ff; margin: 0;'>💡 <strong>Tip:</strong> Try topics like "Introduction to Python Programming", "Digital Marketing Basics", or "Climate Change Science"</p>
+                                </div>
+                            </div>
+                            """
+                        )
+
+                    with gr.Tab("🃏 Flashcards"):
+                        flashcards_output = gr.HTML(
+                            value="""
+                            <div class='flashcards-container' style='padding: 2rem; text-align: center; background: #1a1a2e; border-radius: 12px; color: #e0e7ff;'>
+                                <h3 style='color: #667eea; margin-bottom: 1rem;'>🃏 Interactive Flashcards</h3>
+                                <p style='color: #b8c5d6;'>Flashcards will appear here after course generation. They'll help reinforce key concepts with spaced repetition learning!</p>
+                            </div>
+                            """
+                        )
+
+                    with gr.Tab("📝 Quizzes"):
+                        # Quiz functionality with HTML content and state management
+                        quiz_state = gr.State({})  # Store quiz data
+                        quizzes_output = gr.HTML(
+                            value="""
+                            <div class='quiz-container' style='padding: 2rem; text-align: center; background: #1a1a2e; border-radius: 12px; color: #e0e7ff;'>
+                                <h3 style='color: #667eea; margin-bottom: 1rem;'>📝 Knowledge Assessment</h3>
+                                <p style='color: #b8c5d6;'>Interactive quizzes will appear here to test your understanding of the course material!</p>
+                            </div>
+                            """
+                        )
+                        quiz_results = gr.HTML(visible=False)
+                        quiz_submit_btn = gr.Button("Submit Quiz", variant="primary", visible=False)
+
+                    with gr.Tab("🎨 Images"):
+                        images_section = course_preview._create_images_section()
+                        image_gallery = images_section["image_gallery"]
+                        image_details = images_section["image_details"]
+
+        # Store generated course content for chat context
+        course_context = {"content": "", "topic": "", "agent": None}
+
+        # Provider change handler to show/hide OpenAI-compatible fields
+        def on_provider_change(provider):
+            if provider == "openai_compatible":
+                return gr.update(visible=True)
+            else:
+                return gr.update(visible=False)
+
+        # Event handlers
+        async def generate_course_wrapper(topic: str, difficulty: str, lessons: int, provider: str, api_key: str, endpoint_url: str, model_name: str, progress=gr.Progress()):
+            """Wrapper for course generation with progress tracking"""
+            if not topic.strip():
+                return (
+                    "<div class='error'>❌ Please enter a topic for your course.</div>",
+                    "", "", 
+                    gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                )
+
+            if not api_key.strip() and provider != "openai_compatible":
+                return (
+                    "<div class='error'>❌ Please enter your API key for the selected LLM provider.</div>",
+                    "", "", 
+                    gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                )
+            
+            if provider == "openai_compatible" and not endpoint_url.strip():
+                return (
+                    "<div class='error'>❌ Please enter the endpoint URL for OpenAI-compatible provider.</div>",
+                    "", "", 
+                    gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                )
+            
+            if provider == "openai_compatible" and not model_name.strip():
+                return (
+                    "<div class='error'>❌ Please enter the model name for OpenAI-compatible provider.</div>",
+                    "", "", 
+                    gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                )
+
+            try:
+                # Initialize progress
+                progress(0, desc="🚀 Initializing Course Generator...")
+                
+                # Set the API key and configuration for the selected provider
+                import os
+                if provider == "openai":
+                    os.environ["OPENAI_API_KEY"] = api_key
+                elif provider == "anthropic":
+                    os.environ["ANTHROPIC_API_KEY"] = api_key
+                elif provider == "google":
+                    os.environ["GOOGLE_API_KEY"] = api_key
+                elif provider == "openai_compatible":
+                    if api_key.strip():
+                        os.environ["OPENAI_COMPATIBLE_API_KEY"] = api_key
+                    os.environ["OPENAI_COMPATIBLE_BASE_URL"] = endpoint_url
+                    os.environ["OPENAI_COMPATIBLE_MODEL"] = model_name
+                
+                # Initialize the simplified agent
+                agent = SimpleCourseAgent()
+                # Override the default provider with user selection
+                agent.default_provider = provider
+                course_context["agent"] = agent
+                course_context["topic"] = topic
+
+                progress(0.1, desc="⚙️ Setting up generation options...")
+
+                # Create generation options
+                options = GenerationOptions(
+                    difficulty=DifficultyLevel(difficulty),
+                    lesson_count=lessons,
+                    include_images=True,
+                    include_flashcards=True,
+                    include_quizzes=True
+                )
+
+                progress(0.15, desc="🔍 Checking available providers...")
+
+                # Get available providers
+                available_providers = agent.get_available_providers()
+                if not available_providers:
+                    return (
+                        "<div class='error'>❌ No LLM providers available. Please check your API keys.</div>",
+                        "", "", 
+                        gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                    )
+
+                progress(0.2, desc="🎓 Starting course generation...")
+
+                # Use the default provider from config (no need to override)
+                # The agent will automatically use the configured default provider
+
+                # Start course generation
+                lessons_html = ""
+                flashcards_html = ""
+                quizzes_html = ""
+
+                # Stream the generation process
+                course_data = None
+                current_progress = 0.2
+                
+                # Add a simple counter for fallback progress
+                chunk_count = 0
+                max_expected_chunks = 10  # Rough estimate
+
+                async for chunk in agent.generate_course(topic, options):
+                    chunk_count += 1
+                    print(f"📊 Progress Debug: Received chunk type='{chunk.type}', content='{chunk.content}'")
+                    
+                    # Update progress based on chunk content
+                    if chunk.type == "progress":
+                        # Check if the progress message matches our known steps (handle emojis)
+                        step_found = False
+                        progress_message = chunk.content.lower()
+                        print(f"🔍 Checking progress message: '{progress_message}'")
+                        
+                        if "research completed" in progress_message:
+                            current_progress = 0.3
+                            step_found = True
+                            print(f"✅ Matched: Research completed -> {current_progress}")
+                            progress(current_progress, desc="📚 Research completed, planning course structure...")
+                        elif "course structure planned" in progress_message:
+                            current_progress = 0.4
+                            step_found = True
+                            print(f"✅ Matched: Course structure planned -> {current_progress}")
+                            progress(current_progress, desc="📝 Course structure planned, generating content...")
+                        elif "lessons created" in progress_message:
+                            current_progress = 0.6
+                            step_found = True
+                            print(f"✅ Matched: Lessons created -> {current_progress}")
+                            progress(current_progress, desc="✍️ Lessons created, generating flashcards...")
+                        elif "flashcards created" in progress_message:
+                            current_progress = 0.75
+                            step_found = True
+                            print(f"✅ Matched: Flashcards created -> {current_progress}")
+                            progress(current_progress, desc="🃏 Flashcards created, creating quiz...")
+                        elif "quiz created" in progress_message:
+                            current_progress = 0.8
+                            step_found = True
+                            print(f"✅ Matched: Quiz created -> {current_progress}")
+                            progress(current_progress, desc="❓ Quiz created, generating images...")
+                        elif "images generated" in progress_message:
+                            current_progress = 0.9
+                            step_found = True
+                            print(f"✅ Matched: Images generated -> {current_progress}")
+                            progress(current_progress, desc="🎨 Images generated, finalizing course...")
+                        elif "finalizing course" in progress_message:
+                            current_progress = 0.95
+                            step_found = True
+                            print(f"✅ Matched: Finalizing course -> {current_progress}")
+                            progress(current_progress, desc="📦 Assembling final course data...")
+                        
+                        if not step_found:
+                            # Fallback: increment progress based on chunk count
+                            fallback_progress = min(0.2 + (chunk_count / max_expected_chunks) * 0.6, 0.85)
+                            current_progress = max(current_progress, fallback_progress)
+                            print(f"⚠️ No match found, using fallback: {fallback_progress}")
+                            progress(current_progress, desc=f"�� {chunk.content}")
+                    
+                    elif chunk.type == "course_complete":
+                        current_progress = 0.95
+                        progress(current_progress, desc="📦 Finalizing course data...")
+                        # Parse the complete course data
+                        try:
+                            course_data = json.loads(chunk.content)
+                        except:
+                            course_data = None
+
+                progress(0.97, desc="🎨 Processing course content...")
+
+                # If we got course data, format it nicely
+                if course_data:
+                    course_context["content"] = course_data
+
+                    # Format lessons
+                    lessons_html = format_lessons(course_data.get("lessons", []))
+
+                    # Format flashcards
+                    flashcards_html = format_flashcards(course_data.get("flashcards", []))
+
+                    # Format quiz
+                    quiz_data = course_data.get("quiz", {})
+                    quizzes_html = format_quiz(quiz_data)
+
+                    # Show quiz button if quiz exists
+                    quiz_btn_visible = bool(quiz_data and quiz_data.get("questions"))
+
+                    progress(0.98, desc="🖼️ Processing images for gallery...")
+
+                    # Prepare image gallery data - fix the format for Gradio Gallery
+                    images = []
+                    image_details_list = []
+                    
+                    # Process images from lessons
+                    for lesson in course_data.get("lessons", []):
+                        lesson_images = lesson.get("images", [])
+                        for i, img in enumerate(lesson_images):
+                            try:
+                                if isinstance(img, dict):
+                                    # Handle different image data formats
+                                    image_url = img.get("url") or img.get("data_url")
+                                    if image_url:
+                                        alt_text = img.get("caption", img.get("description", "Educational image"))
+                                        
+                                        # Handle base64 data URLs by converting to temp files
+                                        if image_url.startswith('data:image/'):
+                                            import base64
+                                            import tempfile
+                                            import os
+                                            
+                                            # Extract base64 data
+                                            header, data = image_url.split(',', 1)
+                                            image_data = base64.b64decode(data)
+                                            
+                                            # Determine file extension from header
+                                            if 'jpeg' in header or 'jpg' in header:
+                                                ext = '.jpg'
+                                            elif 'png' in header:
+                                                ext = '.png'
+                                            elif 'gif' in header:
+                                                ext = '.gif'
+                                            elif 'webp' in header:
+                                                ext = '.webp'
+                                            else:
+                                                ext = '.jpg'  # Default
+                                            
+                                            # Create temp file
+                                            temp_fd, temp_path = tempfile.mkstemp(suffix=ext, prefix=f'course_img_{i}_')
+                                            try:
+                                                with os.fdopen(temp_fd, 'wb') as f:
+                                                    f.write(image_data)
+                                                images.append(temp_path)
+                                                image_details_list.append({
+                                                    "url": temp_path,
+                                                    "caption": alt_text,
+                                                    "lesson": lesson.get("title", "Unknown lesson")
+                                                })
+                                            except Exception as e:
+                                                print(f"⚠️ Failed to save temp image {i}: {e}")
+                                                os.close(temp_fd)  # Close if write failed
+                                                continue
+                                                
+                                        elif image_url.startswith('http'):
+                                            # Regular URL - Gradio can handle these directly
+                                            images.append(image_url)
+                                            image_details_list.append({
+                                                "url": image_url,
+                                                "caption": alt_text,
+                                                "lesson": lesson.get("title", "Unknown lesson")
+                                            })
+                                        else:
+                                            # Assume it's a file path
+                                            if len(image_url) <= 260:  # Windows path limit
+                                                images.append(image_url)
+                                                image_details_list.append({
+                                                    "url": image_url,
+                                                    "caption": alt_text,
+                                                    "lesson": lesson.get("title", "Unknown lesson")
+                                                })
+                                            else:
+                                                print(f"⚠️ Skipping image {i}: path too long ({len(image_url)} chars)")
+                                elif isinstance(img, str):
+                                    # Handle case where image is just a URL string
+                                    if img.startswith('data:image/'):
+                                        # Handle base64 data URLs
+                                        import base64
+                                        import tempfile
+                                        import os
+                                        
+                                        try:
+                                            header, data = img.split(',', 1)
+                                            image_data = base64.b64decode(data)
+                                            
+                                            # Determine file extension from header
+                                            if 'jpeg' in header or 'jpg' in header:
+                                                ext = '.jpg'
+                                            elif 'png' in header:
+                                                ext = '.png'
+                                            elif 'gif' in header:
+                                                ext = '.gif'
+                                            elif 'webp' in header:
+                                                ext = '.webp'
+                                            else:
+                                                ext = '.jpg'  # Default
+                                            
+                                            # Create temp file
+                                            temp_fd, temp_path = tempfile.mkstemp(suffix=ext, prefix=f'course_img_{i}_')
+                                            try:
+                                                with os.fdopen(temp_fd, 'wb') as f:
+                                                    f.write(image_data)
+                                                images.append(temp_path)
+                                                image_details_list.append({
+                                                    "url": temp_path,
+                                                    "caption": "Educational image",
+                                                    "lesson": lesson.get("title", "Unknown lesson")
+                                                })
+                                            except Exception as e:
+                                                print(f"⚠️ Failed to save temp image {i}: {e}")
+                                                os.close(temp_fd)  # Close if write failed
+                                                continue
+                                        except Exception as e:
+                                            print(f"⚠️ Error processing base64 image {i}: {e}")
+                                            continue
+                                    else:
+                                        # Regular URL or file path
+                                        images.append(img)
+                                        image_details_list.append({
+                                            "url": img,
+                                            "caption": "Educational image",
+                                            "lesson": lesson.get("title", "Unknown lesson")
+                                        })
+                            except Exception as e:
+                                print(f"⚠️ Error processing image {i}: {e}")
+                                continue
+                    
+                    # Also check for standalone images in course data
+                    standalone_images = course_data.get("images", [])
+                    for i, img in enumerate(standalone_images):
+                        try:
+                            if isinstance(img, dict):
+                                image_url = img.get("url") or img.get("data_url")
+                                if image_url:
+                                    alt_text = img.get("caption", img.get("description", "Course image"))
+                                    
+                                    # Handle base64 data URLs
+                                    if image_url.startswith('data:image/'):
+                                        import base64
+                                        import tempfile
+                                        import os
+                                        
+                                        try:
+                                            header, data = image_url.split(',', 1)
+                                            image_data = base64.b64decode(data)
+                                            
+                                            # Determine file extension from header
+                                            if 'jpeg' in header or 'jpg' in header:
+                                                ext = '.jpg'
+                                            elif 'png' in header:
+                                                ext = '.png'
+                                            elif 'gif' in header:
+                                                ext = '.gif'
+                                            elif 'webp' in header:
+                                                ext = '.webp'
+                                            else:
+                                                ext = '.jpg'  # Default
+                                            
+                                            # Create temp file
+                                            temp_fd, temp_path = tempfile.mkstemp(suffix=ext, prefix=f'standalone_img_{i}_')
+                                            try:
+                                                with os.fdopen(temp_fd, 'wb') as f:
+                                                    f.write(image_data)
+                                                images.append(temp_path)
+                                                image_details_list.append({
+                                                    "url": temp_path,
+                                                    "caption": alt_text,
+                                                    "lesson": "Course Overview"
+                                                })
+                                            except Exception as e:
+                                                print(f"⚠️ Failed to save temp standalone image {i}: {e}")
+                                                os.close(temp_fd)  # Close if write failed
+                                                continue
+                                        except Exception as e:
+                                            print(f"⚠️ Error processing base64 standalone image {i}: {e}")
+                                            continue
+                                    else:
+                                        images.append(image_url)
+                                        image_details_list.append({
+                                            "url": image_url,
+                                            "caption": alt_text,
+                                            "lesson": "Course Overview"
+                                        })
+                            elif isinstance(img, str):
+                                if img.startswith('data:image/'):
+                                    # Handle base64 data URLs
+                                    import base64
+                                    import tempfile
+                                    import os
+                                    
+                                    try:
+                                        header, data = img.split(',', 1)
+                                        image_data = base64.b64decode(data)
+                                        
+                                        # Determine file extension from header
+                                        if 'jpeg' in header or 'jpg' in header:
+                                            ext = '.jpg'
+                                        elif 'png' in header:
+                                            ext = '.png'
+                                        elif 'gif' in header:
+                                            ext = '.gif'
+                                        elif 'webp' in header:
+                                            ext = '.webp'
+                                        else:
+                                            ext = '.jpg'  # Default
+                                        
+                                        # Create temp file
+                                        temp_fd, temp_path = tempfile.mkstemp(suffix=ext, prefix=f'standalone_img_{i}_')
+                                        try:
+                                            with os.fdopen(temp_fd, 'wb') as f:
+                                                f.write(image_data)
+                                            images.append(temp_path)
+                                            image_details_list.append({
+                                                "url": temp_path,
+                                                "caption": "Course image",
+                                                "lesson": "Course Overview"
+                                            })
+                                        except Exception as e:
+                                            print(f"⚠️ Failed to save temp standalone image {i}: {e}")
+                                            os.close(temp_fd)  # Close if write failed
+                                            continue
+                                    except Exception as e:
+                                        print(f"⚠️ Error processing base64 standalone image {i}: {e}")
+                                        continue
+                                else:
+                                    images.append(img)
+                                    image_details_list.append({
+                                        "url": img,
+                                        "caption": "Course image",
+                                        "lesson": "Course Overview"
+                                    })
+                        except Exception as e:
+                            print(f"⚠️ Error processing standalone image {i}: {e}")
+                            continue
+                    
+                    print(f"📸 Prepared {len(images)} images for gallery display")
+                    
+                    # Create image details HTML for display
+                    if image_details_list:
+                        image_details_html = "<div class='image-details-container'>"
+                        image_details_html += "<h4>🖼️ Image Gallery</h4>"
+                        image_details_html += f"<p>Total images: {len(image_details_list)}</p>"
+                        image_details_html += "<ul>"
+                        for i, img_detail in enumerate(image_details_list, 1):
+                            image_details_html += f"<li><strong>Image {i}:</strong> {img_detail['caption']} (from {img_detail['lesson']})</li>"
+                        image_details_html += "</ul></div>"
+                    else:
+                        image_details_html = "<div class='image-details'>No images available</div>"
+
+                    progress(1.0, desc="✅ Course generation complete!")
+
+                    return (
+                        lessons_html, flashcards_html, quizzes_html,
+                        gr.update(visible=quiz_btn_visible), images, image_details_html
+                    )
+                else:
+                    quiz_btn_visible = False
+                    progress(1.0, desc="⚠️ Course generation completed with issues")
+
+                    return (
+                        "", "", "",
+                        gr.update(visible=quiz_btn_visible), [], "<div class='image-details'>No images available</div>"
+                    )
+
+            except Exception as e:
+                import traceback
+                error_details = traceback.format_exc()
+                print(f"Error in course generation: {error_details}")
+                return (
+                    "", "", "",
+                    gr.update(visible=False), [], "<div class='image-details'>Error loading images</div>"
+                )
+
+        def handle_quiz_submit():
+            """Handle quiz submission using client-side processing"""
+            # This function will be replaced by client-side JavaScript
+            return gr.update()
+
+        async def handle_chat(message: str, current_chat: str):
+            """Handle chat messages for answering questions about the course content"""
+            if not message.strip():
+                return current_chat, ""
+
+            if not course_context["content"] or not course_context["agent"]:
+                assistant_response = "Please generate a course first before asking questions about it."
+            else:
+                try:
+                    # Get the agent and course content
+                    agent = course_context["agent"]
+                    course_data = course_context["content"]
+                    topic = course_context["topic"]
+                    
+                    # Create context from the course content
+                    course_context_text = f"Course Topic: {topic}\n\n"
+                    
+                    # Add lessons content
+                    lessons = course_data.get("lessons", [])
+                    for i, lesson in enumerate(lessons, 1):
+                        course_context_text += f"Lesson {i}: {lesson.get('title', '')}\n"
+                        course_context_text += f"Content: {lesson.get('content', '')[:1000]}...\n"
+                        if lesson.get('key_takeaways'):
+                            course_context_text += f"Key Takeaways: {', '.join(lesson.get('key_takeaways', []))}\n"
+                        course_context_text += "\n"
+                    
+                    # Add flashcards context
+                    flashcards = course_data.get("flashcards", [])
+                    if flashcards:
+                        course_context_text += "Flashcards:\n"
+                        for card in flashcards[:5]:  # Limit to first 5
+                            course_context_text += f"Q: {card.get('question', '')} A: {card.get('answer', '')}\n"
+                        course_context_text += "\n"
+                    
+                    # Create a focused prompt for answering questions
+                    prompt = f"""You are a helpful course assistant. Answer the user's question about the course content below.
+
+Course Content:
+{course_context_text}
+
+User Question: {message}
+
+Instructions:
+- Answer based ONLY on the course content provided above
+- Be helpful, clear, and educational
+- If the question is about something not covered in the course, say so politely
+- Keep responses concise but informative
+- Use a friendly, teaching tone
+
+Answer:"""
+
+                    # Use the default provider (same as course generation)
+                    provider = agent.default_provider
+                    available_providers = agent.get_available_providers()
+                    if provider not in available_providers:
+                        # Fallback to first available if default isn't available
+                        provider = available_providers[0] if available_providers else None
+                        
+                    if provider:
+                        # Use the agent's LLM to get a response
+                        from ..agents.simple_course_agent import Message
+                        messages = [
+                            Message(role="system", content="You are a helpful course assistant that answers questions about course content."),
+                            Message(role="user", content=prompt)
+                        ]
+                        
+                        print(f"🤖 Chat using LLM provider: {provider}")
+                        assistant_response = await agent._get_llm_response(provider, messages)
+                        
+                        # Clean up the response
+                        assistant_response = assistant_response.strip()
+                        if assistant_response.startswith("Answer:"):
+                            assistant_response = assistant_response[7:].strip()
+                            
+                    else:
+                        assistant_response = "Sorry, no LLM providers are available to answer your question."
+                        
+                except Exception as e:
+                    print(f"Error in chat: {e}")
+                    assistant_response = "Sorry, I encountered an error while trying to answer your question. Please try again."
+
+            # Extract existing messages from current chat HTML
+            existing_messages = ""
+            if current_chat and "chat-message" in current_chat:
+                # Keep existing messages
+                start = current_chat.find('<div class="chat-messages"')
+                if start != -1:
+                    end = current_chat.find('</div>', start)
+                    if end != -1:
+                        existing_content = current_chat[start:end]
+                        # Extract just the message divs
+                        import re
+                        messages_match = re.findall(r'<div class="chat-message.*?</div>\s*</div>', existing_content, re.DOTALL)
+                        existing_messages = ''.join(messages_match)
+
+            # Create new chat HTML with existing messages plus new ones
+            new_chat = f"""
+            <div class='chat-window'>
+                <div class='chat-messages' id='chat-messages'>
+                    {existing_messages}
+                    <div class='chat-message user-message'>
+                        <div class='message-avatar'>👤</div>
+                        <div class='message-content'>
+                            <div class='message-text'>{message}</div>
+                        </div>
+                    </div>
+                    <div class='chat-message assistant-message'>
+                        <div class='message-avatar'>🤖</div>
+                        <div class='message-content'>
+                            <div class='message-text'>{assistant_response}</div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            """
+
+            return new_chat, ""
+
+
+
+        # Connect provider change event
+        llm_provider.change(
+            fn=on_provider_change,
+            inputs=[llm_provider],
+            outputs=[openai_compatible_row]
+        )
+
+        generate_btn.click(
+            fn=generate_course_wrapper,
+            inputs=[topic_input, difficulty_input, lesson_count, llm_provider, api_key_input, endpoint_url_input, model_name_input],
+            outputs=[
+                lessons_output, flashcards_output, quizzes_output, quiz_submit_btn, image_gallery, image_details
+            ]
+        )
+
+        chat_btn.click(
+            fn=handle_chat,
+            inputs=[chat_input, chat_display],
+            outputs=[chat_display, chat_input]
+        )
+
+        # Use a much simpler approach with direct JavaScript execution
+        quiz_submit_btn.click(
+            fn=None,  # No Python function needed
+            js="""
+            function() {
+                // Find all quiz questions and process them
+                const questions = document.querySelectorAll('.quiz-question');
+                if (questions.length === 0) {
+                    alert('No quiz questions found!');
+                    return;
+                }
+                
+                let score = 0;
+                let total = questions.length;
+                let hasAnswers = false;
+                
+                questions.forEach((question, idx) => {
+                    const radios = question.querySelectorAll('input[type="radio"]');
+                    const correctAnswer = question.dataset.correct;
+                    const explanation = question.dataset.explanation || '';
+                    
+                    let selectedRadio = null;
+                    radios.forEach(radio => {
+                        if (radio.checked) {
+                            selectedRadio = radio;
+                            hasAnswers = true;
+                        }
+                    });
+                    
+                    // Create or find feedback element
+                    let feedback = question.querySelector('.quiz-feedback');
+                    if (!feedback) {
+                        feedback = document.createElement('div');
+                        feedback.className = 'quiz-feedback';
+                        question.appendChild(feedback);
+                    }
+                    
+                    if (selectedRadio) {
+                        const userAnswer = selectedRadio.value;
+                        if (userAnswer === correctAnswer) {
+                            score++;
+                            feedback.innerHTML = `<div style="background: #d4edda; color: #155724; padding: 1rem; border-radius: 6px; margin-top: 1rem;">✅ <strong>Correct!</strong> ${explanation}</div>`;
+                        } else {
+                            feedback.innerHTML = `<div style="background: #f8d7da; color: #721c24; padding: 1rem; border-radius: 6px; margin-top: 1rem;">❌ <strong>Incorrect.</strong> The correct answer is <strong>${correctAnswer}</strong>. ${explanation}</div>`;
+                        }
+                    } else {
+                        feedback.innerHTML = `<div style="background: #fff3cd; color: #856404; padding: 1rem; border-radius: 6px; margin-top: 1rem;">⚠️ <strong>No answer selected.</strong> The correct answer is <strong>${correctAnswer}</strong>. ${explanation}</div>`;
+                    }
+                    
+                    feedback.style.display = 'block';
+                });
+                
+                if (hasAnswers) {
+                    const percentage = Math.round((score / total) * 100);
+                    
+                    // Create or find results container
+                    let resultsContainer = document.querySelector('.quiz-results');
+                    if (!resultsContainer) {
+                        resultsContainer = document.createElement('div');
+                        resultsContainer.className = 'quiz-results';
+                        resultsContainer.style.cssText = 'margin-top: 2rem; padding: 1.5rem; background: linear-gradient(135deg, #667eea, #764ba2); color: white; border-radius: 8px; text-align: center; font-size: 1.1rem;';
+                        document.querySelector('.quiz-container').appendChild(resultsContainer);
+                    }
+                    
+                    let message = '';
+                    if (percentage >= 80) {
+                        message = '🎉 Excellent work!';
+                    } else if (percentage >= 60) {
+                        message = '👍 Good job!';
+                    } else {
+                        message = '📚 Keep studying!';
+                    }
+                    
+                    resultsContainer.innerHTML = `
+                        <div style="font-size: 1.5rem; font-weight: bold; margin-bottom: 0.5rem;">📊 Final Score: ${score}/${total} (${percentage}%)</div>
+                        <p>${message}</p>
+                    `;
+                    
+                    resultsContainer.style.display = 'block';
+                    resultsContainer.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                } else {
+                    alert('Please answer at least one question before submitting!');
+                }
+            }
+            """
+        )
+
+    return interface
+
+
+def launch_app(share: bool = False, debug: bool = False) -> None:
+    """Launch the Course Creator application"""
+    interface = create_coursecrafter_interface()
+    interface.launch(
+        share=share,
+        debug=debug,
+        server_name="0.0.0.0",
+        server_port=7862
+    )
+
+
+if __name__ == "__main__":
+    launch_app(debug=True)

coursecrafter/ui/progress_tracker.py

@@ -0,0 +1,509 @@
+"""
+📊 Real-time Progress Tracker for CourseCrafter AI
+
+Advanced progress tracking with visual feedback and status updates.
+"""
+
+import gradio as gr
+import asyncio
+import time
+from typing import Dict, List, Any, Optional, Callable, Generator
+from dataclasses import dataclass
+from enum import Enum
+import logging
+import threading
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressStatus(Enum):
+    """Progress status enumeration"""
+    PENDING = "pending"
+    ACTIVE = "active"
+    COMPLETE = "complete"
+    ERROR = "error"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class ProgressStep:
+    """Individual progress step"""
+    id: str
+    name: str
+    description: str
+    emoji: str
+    status: ProgressStatus = ProgressStatus.PENDING
+    progress: float = 0.0
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    error_message: Optional[str] = None
+    substeps: List['ProgressStep'] = None
+    
+    def __post_init__(self):
+        if self.substeps is None:
+            self.substeps = []
+
+
+class RealTimeProgressTracker:
+    """Real-time progress tracking with visual updates"""
+    
+    def __init__(self):
+        self.steps: List[ProgressStep] = []
+        self.current_step_index = 0
+        self.overall_progress = 0.0
+        self.is_running = False
+        self.start_time: Optional[datetime] = None
+        self.end_time: Optional[datetime] = None
+        self.log_entries: List[str] = []
+        self.update_callbacks: List[Callable] = []
+        
+        # Initialize default steps
+        self._initialize_default_steps()
+    
+    def _initialize_default_steps(self):
+        """Initialize the default course generation steps"""
+        
+        self.steps = [
+            ProgressStep(
+                id="research",
+                name="Research & Analysis",
+                description="Gathering information and analyzing the topic",
+                emoji="🔍",
+                substeps=[
+                    ProgressStep("research_web", "Web Search", "Searching for relevant information", "🌐"),
+                    ProgressStep("research_academic", "Academic Sources", "Finding scholarly content", "📚"),
+                    ProgressStep("research_analysis", "Content Analysis", "Analyzing gathered information", "🧠"),
+                ]
+            ),
+            ProgressStep(
+                id="planning",
+                name="Course Planning",
+                description="Creating the course structure and outline",
+                emoji="📋",
+                substeps=[
+                    ProgressStep("plan_structure", "Course Structure", "Designing lesson flow", "🏗️"),
+                    ProgressStep("plan_objectives", "Learning Objectives", "Defining learning goals", "🎯"),
+                    ProgressStep("plan_assessment", "Assessment Strategy", "Planning quizzes and activities", "📝"),
+                ]
+            ),
+            ProgressStep(
+                id="content",
+                name="Content Generation",
+                description="Creating engaging lesson content",
+                emoji="✍️",
+                substeps=[
+                    ProgressStep("content_lessons", "Lesson Content", "Writing lesson materials", "📖"),
+                    ProgressStep("content_examples", "Examples & Exercises", "Creating practical examples", "💡"),
+                    ProgressStep("content_review", "Content Review", "Reviewing and refining content", "🔍"),
+                ]
+            ),
+            ProgressStep(
+                id="assessments",
+                name="Assessment Creation",
+                description="Generating quizzes and flashcards",
+                emoji="🎯",
+                substeps=[
+                    ProgressStep("assess_flashcards", "Flashcards", "Creating study flashcards", "🃏"),
+                    ProgressStep("assess_quizzes", "Quizzes", "Generating quiz questions", "❓"),
+                    ProgressStep("assess_validation", "Validation", "Validating assessment quality", "✅"),
+                ]
+            ),
+            ProgressStep(
+                id="images",
+                name="Visual Content",
+                description="Generating images and diagrams",
+                emoji="🎨",
+                substeps=[
+                    ProgressStep("images_cover", "Course Cover", "Creating course cover image", "🖼️"),
+                    ProgressStep("images_lessons", "Lesson Images", "Generating lesson illustrations", "🎭"),
+                    ProgressStep("images_diagrams", "Diagrams", "Creating concept diagrams", "📊"),
+                ]
+            ),
+            ProgressStep(
+                id="finalize",
+                name="Finalization",
+                description="Packaging and finalizing the course",
+                emoji="📦",
+                substeps=[
+                    ProgressStep("final_package", "Course Package", "Assembling course materials", "📁"),
+                    ProgressStep("final_metadata", "Metadata", "Adding course metadata", "🏷️"),
+                    ProgressStep("final_validation", "Final Validation", "Final quality check", "🔍"),
+                ]
+            )
+        ]
+    
+    def start_generation(self) -> None:
+        """Start the course generation process"""
+        
+        self.is_running = True
+        self.start_time = datetime.now()
+        self.current_step_index = 0
+        self.overall_progress = 0.0
+        self.log_entries = []
+        
+        self.add_log_entry("🚀 Starting course generation...")
+        self.add_log_entry(f"⏰ Started at {self.start_time.strftime('%H:%M:%S')}")
+    
+    def update_step_progress(self, step_id: str, progress: float, message: str = "") -> None:
+        """Update progress for a specific step"""
+        
+        step = self._find_step_by_id(step_id)
+        if not step:
+            logger.warning(f"Step {step_id} not found")
+            return
+        
+        step.progress = min(100.0, max(0.0, progress))
+        
+        if step.status == ProgressStatus.PENDING and progress > 0:
+            step.status = ProgressStatus.ACTIVE
+            step.start_time = datetime.now()
+            self.add_log_entry(f"{step.emoji} Started: {step.name}")
+        
+        if progress >= 100.0:
+            step.status = ProgressStatus.COMPLETE
+            step.end_time = datetime.now()
+            duration = (step.end_time - step.start_time).total_seconds() if step.start_time else 0
+            self.add_log_entry(f"✅ Completed: {step.name} ({duration:.1f}s)")
+        
+        if message:
+            self.add_log_entry(f"   {message}")
+        
+        self._update_overall_progress()
+        self._notify_callbacks()
+    
+    def update_substep_progress(self, step_id: str, substep_id: str, progress: float, message: str = "") -> None:
+        """Update progress for a substep"""
+        
+        step = self._find_step_by_id(step_id)
+        if not step:
+            return
+        
+        substep = self._find_substep_by_id(step, substep_id)
+        if not substep:
+            return
+        
+        substep.progress = min(100.0, max(0.0, progress))
+        
+        if substep.status == ProgressStatus.PENDING and progress > 0:
+            substep.status = ProgressStatus.ACTIVE
+            substep.start_time = datetime.now()
+            self.add_log_entry(f"  {substep.emoji} {substep.name}...")
+        
+        if progress >= 100.0:
+            substep.status = ProgressStatus.COMPLETE
+            substep.end_time = datetime.now()
+        
+        if message:
+            self.add_log_entry(f"    {message}")
+        
+        # Update parent step progress based on substeps
+        self._update_step_from_substeps(step)
+        self._notify_callbacks()
+    
+    def mark_step_error(self, step_id: str, error_message: str) -> None:
+        """Mark a step as having an error"""
+        
+        step = self._find_step_by_id(step_id)
+        if not step:
+            return
+        
+        step.status = ProgressStatus.ERROR
+        step.error_message = error_message
+        step.end_time = datetime.now()
+        
+        self.add_log_entry(f"❌ Error in {step.name}: {error_message}")
+        self._notify_callbacks()
+    
+    def skip_step(self, step_id: str, reason: str = "") -> None:
+        """Skip a step"""
+        
+        step = self._find_step_by_id(step_id)
+        if not step:
+            return
+        
+        step.status = ProgressStatus.SKIPPED
+        step.progress = 100.0
+        step.end_time = datetime.now()
+        
+        skip_msg = f"⏭️ Skipped: {step.name}"
+        if reason:
+            skip_msg += f" ({reason})"
+        
+        self.add_log_entry(skip_msg)
+        self._update_overall_progress()
+        self._notify_callbacks()
+    
+    def complete_generation(self, success: bool = True) -> None:
+        """Complete the course generation process"""
+        
+        self.is_running = False
+        self.end_time = datetime.now()
+        
+        if success:
+            self.overall_progress = 100.0
+            total_time = (self.end_time - self.start_time).total_seconds() if self.start_time else 0
+            self.add_log_entry(f"🎉 Course generation completed successfully!")
+            self.add_log_entry(f"⏱️ Total time: {total_time:.1f} seconds")
+        else:
+            self.add_log_entry("❌ Course generation failed")
+        
+        self._notify_callbacks()
+    
+    def add_log_entry(self, message: str) -> None:
+        """Add an entry to the progress log"""
+        
+        timestamp = datetime.now().strftime("%H:%M:%S")
+        log_entry = f"[{timestamp}] {message}"
+        self.log_entries.append(log_entry)
+        
+        # Keep only last 100 entries
+        if len(self.log_entries) > 100:
+            self.log_entries = self.log_entries[-100:]
+    
+    def get_progress_display(self) -> Dict[str, Any]:
+        """Get current progress display data"""
+        
+        return {
+            "overall_progress": self.overall_progress,
+            "current_step": self.get_current_step_display(),
+            "step_indicators": self.get_step_indicators(),
+            "progress_log": "\n".join(self.log_entries[-20:]),  # Last 20 entries
+            "is_running": self.is_running,
+            "elapsed_time": self.get_elapsed_time()
+        }
+    
+    def get_current_step_display(self) -> str:
+        """Get current step display HTML"""
+        
+        if not self.is_running:
+            if self.overall_progress >= 100:
+                return """
+                <div class='step-indicator complete animate-bounce'>
+                    <div class='step-icon'>🎉</div>
+                    <div class='step-text'>Course Generation Complete!</div>
+                    <div class='step-message'>Your course is ready to explore</div>
+                </div>
+                """
+            else:
+                return """
+                <div class='step-indicator pending'>
+                    <div class='step-icon'>🚀</div>
+                    <div class='step-text'>Ready to Generate Course</div>
+                    <div class='step-message'>Click the generate button to begin</div>
+                </div>
+                """
+        
+        current_step = self._get_current_active_step()
+        if not current_step:
+            return "<div class='step-indicator'>Processing...</div>"
+        
+        status_class = current_step.status.value
+        
+        return f"""
+        <div class='step-indicator {status_class} animate-pulse'>
+            <div class='step-icon'>{current_step.emoji}</div>
+            <div class='step-text'>{current_step.name}</div>
+            <div class='step-message'>{current_step.description}</div>
+            <div class='step-progress'>
+                <div class='progress-bar'>
+                    <div class='progress-fill' style='width: {current_step.progress}%'></div>
+                </div>
+                <div class='progress-text'>{current_step.progress:.0f}%</div>
+            </div>
+        </div>
+        """
+    
+    def get_step_indicators(self) -> str:
+        """Get step indicators HTML"""
+        
+        indicators_html = "<div class='status-grid'>"
+        
+        for step in self.steps:
+            status_class = step.status.value
+            
+            indicators_html += f"""
+            <div class='status-item {status_class}' title='{step.description}'>
+                <div class='status-icon'>{step.emoji}</div>
+                <div class='status-name'>{step.name}</div>
+                <div class='status-progress'>{step.progress:.0f}%</div>
+            </div>
+            """
+        
+        indicators_html += "</div>"
+        return indicators_html
+    
+    def get_elapsed_time(self) -> str:
+        """Get elapsed time string"""
+        
+        if not self.start_time:
+            return "00:00"
+        
+        end_time = self.end_time or datetime.now()
+        elapsed = (end_time - self.start_time).total_seconds()
+        
+        minutes = int(elapsed // 60)
+        seconds = int(elapsed % 60)
+        
+        return f"{minutes:02d}:{seconds:02d}"
+    
+    def add_update_callback(self, callback: Callable) -> None:
+        """Add a callback for progress updates"""
+        self.update_callbacks.append(callback)
+    
+    def _find_step_by_id(self, step_id: str) -> Optional[ProgressStep]:
+        """Find a step by ID"""
+        for step in self.steps:
+            if step.id == step_id:
+                return step
+        return None
+    
+    def _find_substep_by_id(self, step: ProgressStep, substep_id: str) -> Optional[ProgressStep]:
+        """Find a substep by ID"""
+        for substep in step.substeps:
+            if substep.id == substep_id:
+                return substep
+        return None
+    
+    def _update_step_from_substeps(self, step: ProgressStep) -> None:
+        """Update step progress based on substeps"""
+        
+        if not step.substeps:
+            return
+        
+        total_progress = sum(substep.progress for substep in step.substeps)
+        step.progress = total_progress / len(step.substeps)
+        
+        # Update step status based on substeps
+        if all(substep.status == ProgressStatus.COMPLETE for substep in step.substeps):
+            step.status = ProgressStatus.COMPLETE
+            if not step.end_time:
+                step.end_time = datetime.now()
+        elif any(substep.status == ProgressStatus.ACTIVE for substep in step.substeps):
+            if step.status == ProgressStatus.PENDING:
+                step.status = ProgressStatus.ACTIVE
+                step.start_time = datetime.now()
+        elif any(substep.status == ProgressStatus.ERROR for substep in step.substeps):
+            step.status = ProgressStatus.ERROR
+    
+    def _update_overall_progress(self) -> None:
+        """Update overall progress based on all steps"""
+        
+        total_progress = sum(step.progress for step in self.steps)
+        self.overall_progress = total_progress / len(self.steps) if self.steps else 0.0
+    
+    def _get_current_active_step(self) -> Optional[ProgressStep]:
+        """Get the currently active step"""
+        
+        for step in self.steps:
+            if step.status == ProgressStatus.ACTIVE:
+                return step
+        
+        # If no active step, return the first pending step
+        for step in self.steps:
+            if step.status == ProgressStatus.PENDING:
+                return step
+        
+        return None
+    
+    def _notify_callbacks(self) -> None:
+        """Notify all registered callbacks"""
+        
+        for callback in self.update_callbacks:
+            try:
+                callback()
+            except Exception as e:
+                logger.error(f"Error in progress callback: {e}")
+
+
+class ProgressSimulator:
+    """Simulates realistic progress for demonstration"""
+    
+    def __init__(self, tracker: RealTimeProgressTracker):
+        self.tracker = tracker
+        self.is_running = False
+    
+    async def simulate_course_generation(self) -> None:
+        """Simulate a realistic course generation process"""
+        
+        self.is_running = True
+        self.tracker.start_generation()
+        
+        try:
+            # Research phase
+            await self._simulate_step("research", [
+                ("research_web", "Searching web for relevant content...", 3.0),
+                ("research_academic", "Finding academic sources...", 2.0),
+                ("research_analysis", "Analyzing gathered information...", 2.5),
+            ])
+            
+            # Planning phase
+            await self._simulate_step("planning", [
+                ("plan_structure", "Designing course structure...", 2.0),
+                ("plan_objectives", "Defining learning objectives...", 1.5),
+                ("plan_assessment", "Planning assessments...", 1.0),
+            ])
+            
+            # Content generation phase
+            await self._simulate_step("content", [
+                ("content_lessons", "Generating lesson content...", 4.0),
+                ("content_examples", "Creating examples and exercises...", 3.0),
+                ("content_review", "Reviewing content quality...", 1.5),
+            ])
+            
+            # Assessment creation phase
+            await self._simulate_step("assessments", [
+                ("assess_flashcards", "Creating flashcards...", 2.0),
+                ("assess_quizzes", "Generating quiz questions...", 2.5),
+                ("assess_validation", "Validating assessments...", 1.0),
+            ])
+            
+            # Image generation phase
+            await self._simulate_step("images", [
+                ("images_cover", "Creating course cover image...", 3.0),
+                ("images_lessons", "Generating lesson illustrations...", 4.0),
+                ("images_diagrams", "Creating concept diagrams...", 2.0),
+            ])
+            
+            # Finalization phase
+            await self._simulate_step("finalize", [
+                ("final_package", "Packaging course materials...", 1.5),
+                ("final_metadata", "Adding metadata...", 0.5),
+                ("final_validation", "Final quality check...", 1.0),
+            ])
+            
+            self.tracker.complete_generation(success=True)
+            
+        except Exception as e:
+            self.tracker.add_log_entry(f"❌ Simulation error: {str(e)}")
+            self.tracker.complete_generation(success=False)
+        
+        finally:
+            self.is_running = False
+    
+    async def _simulate_step(self, step_id: str, substeps: List[tuple]) -> None:
+        """Simulate a step with substeps"""
+        
+        for substep_id, message, duration in substeps:
+            if not self.is_running:
+                break
+            
+            self.tracker.add_log_entry(f"Starting {message}")
+            
+            # Simulate gradual progress
+            steps = 20
+            for i in range(steps + 1):
+                if not self.is_running:
+                    break
+                
+                progress = (i / steps) * 100
+                self.tracker.update_substep_progress(step_id, substep_id, progress)
+                
+                await asyncio.sleep(duration / steps)
+            
+            # Add some realistic variation
+            await asyncio.sleep(0.2)
+    
+    def stop_simulation(self) -> None:
+        """Stop the simulation"""
+        self.is_running = False

coursecrafter/ui/styling.py

@@ -0,0 +1,451 @@
+"""
+🎨 Styling and CSS for CourseCrafter UI
+
+Custom styling for Gradio components.
+"""
+
+def get_custom_css() -> str:
+    """Get custom CSS for the CourseCrafter interface"""
+
+    return """
+    /* CourseCrafter AI Custom Styling - Dark Theme */
+
+    /* Global dark theme overrides */
+    .gradio-container {
+        background: #1a1a2e !important;
+        color: #e0e7ff !important;
+    }
+
+    .header-container {
+        text-align: center;
+        padding: 2rem;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        border-radius: 10px;
+        margin-bottom: 2rem;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3);
+    }
+
+    .header-container h1 {
+        font-size: 2.5rem;
+        margin-bottom: 0.5rem;
+        font-weight: bold;
+        text-shadow: 0 2px 4px rgba(0,0,0,0.3);
+    }
+
+    .header-container p {
+        font-size: 1.1rem;
+        opacity: 0.9;
+    }
+
+    .progress-container {
+        padding: 1rem;
+        background: #2d2d54;
+        border-radius: 8px;
+        border-left: 4px solid #667eea;
+        margin: 1rem 0;
+        color: #e0e7ff;
+    }
+
+    .success {
+        color: #28a745 !important;
+        font-weight: bold;
+        padding: 0.5rem;
+        background: #1e4d2b;
+        border-radius: 4px;
+        border: 1px solid #28a745;
+    }
+
+    .error {
+        color: #dc3545 !important;
+        font-weight: bold;
+        padding: 0.5rem;
+        background: #4d1e1e;
+        border-radius: 4px;
+        border: 1px solid #dc3545;
+    }
+
+    .warning {
+        color: #ffc107 !important;
+        font-weight: bold;
+        padding: 0.5rem;
+        background: #4d3d1e;
+        border-radius: 4px;
+        border: 1px solid #ffc107;
+    }
+
+    .progress {
+        color: #17a2b8 !important;
+        font-weight: bold;
+        padding: 0.5rem;
+        background: #1e3d4d;
+        border-radius: 4px;
+        border: 1px solid #17a2b8;
+    }
+
+    .flashcard {
+        background: #fff;
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+        padding: 1rem;
+        margin: 0.5rem 0;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+
+    .quiz {
+        background: #e3f2fd;
+        border: 1px solid #bbdefb;
+        border-radius: 8px;
+        padding: 1rem;
+        margin: 0.5rem 0;
+    }
+
+    /* Dark theme form inputs */
+    .gradio-textbox, .gradio-dropdown, .gradio-slider {
+        background: #2d2d54 !important;
+        border: 2px solid #4a4a7a !important;
+        border-radius: 8px !important;
+        color: #e0e7ff !important;
+        transition: border-color 0.3s ease !important;
+    }
+
+    .gradio-textbox:focus, .gradio-dropdown:focus {
+        border-color: #667eea !important;
+        box-shadow: 0 0 0 0.2rem rgba(102, 126, 234, 0.25) !important;
+        background: #3a3a6b !important;
+    }
+
+    .gradio-textbox::placeholder {
+        color: #8b9dc3 !important;
+    }
+
+    /* Button styling */
+    .gradio-button {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        border: none !important;
+        border-radius: 8px !important;
+        color: white !important;
+        font-weight: bold !important;
+        transition: all 0.3s ease !important;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3) !important;
+    }
+
+    .gradio-button:hover {
+        transform: translateY(-2px) !important;
+        box-shadow: 0 6px 12px rgba(0,0,0,0.4) !important;
+    }
+
+    /* Ensure all buttons use the same blue theme */
+    button {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        border: none !important;
+        border-radius: 8px !important;
+        color: white !important;
+        font-weight: bold !important;
+        transition: all 0.3s ease !important;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3) !important;
+    }
+
+    button:hover {
+        transform: translateY(-2px) !important;
+        box-shadow: 0 6px 12px rgba(0,0,0,0.4) !important;
+    }
+
+    /* Tab styling */
+    .gradio-tabs {
+        border-radius: 8px !important;
+        overflow: hidden !important;
+        background: #2d2d54 !important;
+    }
+
+    .gradio-tab {
+        background: #3a3a6b !important;
+        border: 1px solid #4a4a7a !important;
+        padding: 0.75rem 1.5rem !important;
+        font-weight: 500 !important;
+        color: #b8c5d6 !important;
+        transition: all 0.3s ease !important;
+    }
+
+    .gradio-tab.selected {
+        background: #667eea !important;
+        color: white !important;
+        border-color: #667eea !important;
+    }
+
+    .gradio-tab:hover:not(.selected) {
+        background: #4a4a7a !important;
+        color: #e0e7ff !important;
+    }
+
+    /* Labels and text */
+    label {
+        color: #e0e7ff !important;
+        font-weight: 500 !important;
+    }
+
+    /* Slider styling */
+    .gradio-slider input[type="range"] {
+        background: #4a4a7a !important;
+    }
+
+    .gradio-slider input[type="range"]::-webkit-slider-thumb {
+        background: #667eea !important;
+    }
+
+    .gradio-slider input[type="range"]::-moz-range-thumb {
+        background: #667eea !important;
+    }
+
+    /* Course content styling */
+    .lessons-container {
+        max-height: 600px;
+        overflow-y: auto;
+        padding: 1rem;
+    }
+
+    .lesson-card {
+        background: white;
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+        padding: 1.5rem;
+        margin: 1rem 0;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+
+    .lesson-card h3 {
+        color: #667eea;
+        margin-bottom: 1rem;
+    }
+
+    .flashcards-container {
+        max-height: none !important;
+        overflow: visible !important;
+        padding: 1rem;
+    }
+
+    .quiz-container {
+        max-height: none !important;
+        overflow: visible !important;
+        padding: 1rem;
+    }
+
+    /* Chat interface styling - Dark Theme */
+    .chat-window {
+        background: #2d2d54 !important;
+        border-radius: 12px !important;
+        padding: 1rem !important;
+        margin: 1rem 0 !important;
+        border: 1px solid #4a4a7a !important;
+    }
+
+    .chat-messages {
+        max-height: 400px !important;
+        overflow-y: auto !important;
+        padding: 0.5rem !important;
+    }
+
+    .chat-message {
+        margin: 1rem 0 !important;
+        display: flex !important;
+        align-items: flex-start !important;
+        gap: 0.75rem !important;
+    }
+
+    .chat-message.user-message {
+        flex-direction: row-reverse !important;
+    }
+
+    .chat-message.assistant-message {
+        flex-direction: row !important;
+    }
+
+    .message-avatar {
+        width: 40px !important;
+        height: 40px !important;
+        border-radius: 50% !important;
+        background: #667eea !important;
+        display: flex !important;
+        align-items: center !important;
+        justify-content: center !important;
+        font-size: 1.2rem !important;
+        flex-shrink: 0 !important;
+    }
+
+    .user-message .message-avatar {
+        background: #764ba2 !important;
+    }
+
+    .message-content {
+        flex: 1 !important;
+        max-width: 70% !important;
+    }
+
+    .message-text {
+        background: #3a3a6b !important;
+        color: #e0e7ff !important;
+        padding: 0.75rem 1rem !important;
+        border-radius: 12px !important;
+        line-height: 1.5 !important;
+        word-wrap: break-word !important;
+    }
+
+    .user-message .message-text {
+        background: #667eea !important;
+        color: white !important;
+    }
+
+    .assistant-message .message-text {
+        background: #4a4a7a !important;
+        color: #e0e7ff !important;
+    }
+
+    .info {
+        background: #2d3748 !important;
+        border: 1px solid #4a5568 !important;
+        border-radius: 8px !important;
+        padding: 1rem !important;
+        color: #a0aec0 !important;
+        text-align: center !important;
+        font-style: italic !important;
+    }
+
+    /* Note: Flashcard styling is now handled inline in the format_flashcards function */
+
+    /* Note: Quiz styling is now handled inline in the format_quiz function */
+
+    /* Note: Lesson styling is now handled inline in the format_lessons function */
+
+    /* Enhanced Course Header Styling */
+    .course-header {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+        color: white !important;
+        padding: 2rem !important;
+        border-radius: 12px !important;
+        margin: 1rem 0 !important;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3) !important;
+        text-align: center !important;
+    }
+
+    .course-header h1 {
+        font-size: 2.2rem !important;
+        margin-bottom: 1rem !important;
+        font-weight: bold !important;
+        text-shadow: 0 2px 4px rgba(0,0,0,0.3) !important;
+        color: white !important;
+    }
+
+    .course-stats {
+        display: flex !important;
+        justify-content: center !important;
+        gap: 1.5rem !important;
+        flex-wrap: wrap !important;
+        margin-top: 1rem !important;
+    }
+
+    .course-stats .stat {
+        background: rgba(255,255,255,0.2) !important;
+        padding: 0.5rem 1rem !important;
+        border-radius: 20px !important;
+        font-size: 0.9rem !important;
+        font-weight: 500 !important;
+        color: white !important;
+        backdrop-filter: blur(10px) !important;
+    }
+
+    /* Progress Tracker Styling */
+    .step-indicator {
+        background: #2d2d54 !important;
+        border: 2px solid #4a4a7a !important;
+        border-radius: 12px !important;
+        padding: 1.5rem !important;
+        margin: 1rem 0 !important;
+        color: #e0e7ff !important;
+        text-align: center !important;
+    }
+
+    .step-indicator.active {
+        border-color: #667eea !important;
+        background: #3a3a6b !important;
+    }
+
+    .step-indicator.complete {
+        border-color: #28a745 !important;
+        background: #1e4d2b !important;
+        color: #28a745 !important;
+    }
+
+    .step-icon {
+        font-size: 2rem !important;
+        margin-bottom: 0.5rem !important;
+    }
+
+    .step-text {
+        font-size: 1.2rem !important;
+        font-weight: bold !important;
+        margin-bottom: 0.5rem !important;
+    }
+
+    .step-message {
+        font-size: 0.9rem !important;
+        opacity: 0.8 !important;
+    }
+
+    /* Note: All component-specific styling is now handled inline for better dark theme support */
+
+    /* Responsive design */
+    @media (max-width: 768px) {
+        .header-container h1 {
+            font-size: 2rem;
+        }
+
+        .header-container p {
+            font-size: 1rem;
+        }
+
+        .lesson-card {
+            padding: 1rem;
+        }
+    }
+    """
+
+
+def get_theme_colors() -> dict:
+    """Get theme color palette"""
+
+    return {
+        "primary": "#d068a5",
+        "secondary": "#764ba2",
+        "success": "#37cb5a",
+        "error": "#dc3545",
+        "warning": "#eec54c",
+        "info": "#09a6be",
+        "light": "#f5f7e6",
+        "dark": "#343a40"
+    }
+
+
+def get_component_styles() -> dict:
+    """Get component-specific styles"""
+
+    return {
+        "button_primary": {
+            "background": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+            "color": "white",
+            "border": "none",
+            "border_radius": "8px",
+            "font_weight": "bold"
+        },
+        "card": {
+            "background": "white",
+            "border": "1px solid #dee2e6",
+            "border_radius": "8px",
+            "padding": "1rem",
+            "box_shadow": "0 2px 4px rgba(0,0,0,0.1)"
+        },
+        "progress_bar": {
+            "background": "#d1f0e7",
+            "border_radius": "4px",
+            "height": "8px"
+        }
+    }

coursecrafter/utils/__init__.py

@@ -0,0 +1,37 @@
+"""
+🛠️ Utilities Package for Course Creator AI
+"""
+
+from .config import Config
+
+from .helpers import (
+    generate_id, clean_text, truncate_text, extract_keywords,
+    format_duration, estimate_reading_time, safe_json_loads,
+    safe_json_dumps, merge_dicts, flatten_list, chunk_list,
+    deduplicate_list, validate_email, sanitize_filename,
+    calculate_similarity, format_file_size, Timer, RateLimiter
+    
+)
+
+__all__ = [
+    "Config",
+    # Helper functions
+    "generate_id",
+    "clean_text",
+    "truncate_text",
+    "extract_keywords",
+    "format_duration",
+    "estimate_reading_time",
+    "safe_json_loads",
+    "safe_json_dumps",
+    "merge_dicts",
+    "flatten_list",
+    "chunk_list",
+    "deduplicate_list",
+    "validate_email",
+    "sanitize_filename",
+    "calculate_similarity",
+    "format_file_size",
+    "Timer",
+    "RateLimiter"
+]

coursecrafter/utils/config.py

@@ -0,0 +1,261 @@
+"""
+⚙️ Configuration Management for CourseCrafter AI
+
+Centralized configuration system with environment variable support and validation.
+"""
+
+import os
+import json
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass, field
+from pathlib import Path
+from dotenv import load_dotenv
+
+from ..types import LLMProvider
+
+
+@dataclass
+class LLMProviderConfig:
+    """Configuration for a specific LLM provider"""
+    api_key: str
+    model: str
+    temperature: float = 0.7
+    max_tokens: Optional[int] = None
+    timeout: int = 60
+    base_url: Optional[str] = None
+
+class Config:
+    """
+    Centralized configuration management for Course Creator AI
+
+    Handles environment variables, API keys, and URL configurations.
+    """
+
+    def __init__(self):
+        # Load environment variables
+        load_dotenv()
+
+        # Initialize configuration
+        self._config = self._load_default_config()
+        self._validate_config()
+
+    def _load_default_config(self) -> Dict[str, Any]:
+        """Load default configuration with environment variable overrides"""
+        # Get default model from env or fallback
+        default_model = os.getenv("DEFAULT_MODEL", "gpt-4.1-nano")
+        
+        # Get default LLM provider from env or fallback to first available
+        default_llm_provider = os.getenv("DEFAULT_LLM_PROVIDER", "openai")
+
+        return {
+            # LLM Provider Configurations
+            "llm_providers": {
+                "openai": {
+                    "api_key": os.getenv("OPENAI_API_KEY", ""),
+                    "model": os.getenv("OPENAI_MODEL", default_model),
+                    "temperature": float(os.getenv("OPENAI_TEMPERATURE", "0.7")),
+                    "max_tokens": int(os.getenv("OPENAI_MAX_TOKENS", "20000")) if os.getenv("OPENAI_MAX_TOKENS") else None,
+                    "timeout": int(os.getenv("OPENAI_TIMEOUT", "60"))
+                },
+                "anthropic": {
+                    "api_key": os.getenv("ANTHROPIC_API_KEY", ""),
+                    "model": os.getenv("ANTHROPIC_MODEL", "claude-3-5-sonnet-20241022"),
+                    "temperature": float(os.getenv("ANTHROPIC_TEMPERATURE", "0.7")),
+                    "max_tokens": int(os.getenv("ANTHROPIC_MAX_TOKENS", "20000")) if os.getenv("ANTHROPIC_MAX_TOKENS") else None,
+                    "timeout": int(os.getenv("ANTHROPIC_TIMEOUT", "60"))
+                },
+                "google": {
+                    "api_key": os.getenv("GOOGLE_API_KEY", ""),
+                    "model": os.getenv("GOOGLE_MODEL", "gemini-2.0-flash"),
+                    "temperature": float(os.getenv("GOOGLE_TEMPERATURE", "0.7")),
+                    "max_tokens": int(os.getenv("GOOGLE_MAX_TOKENS", "20000")) if os.getenv("GOOGLE_MAX_TOKENS") else None,
+                    "timeout": int(os.getenv("GOOGLE_TIMEOUT", "60"))
+                },
+                "openai_compatible": {
+                    "api_key": os.getenv("OPENAI_COMPATIBLE_API_KEY", "dummy"),
+                    "base_url": os.getenv("OPENAI_COMPATIBLE_BASE_URL", ""),
+                    "model": os.getenv("OPENAI_COMPATIBLE_MODEL", ""),
+                    "temperature": float(os.getenv("OPENAI_COMPATIBLE_TEMPERATURE", "0.7")),
+                    "max_tokens": int(os.getenv("OPENAI_COMPATIBLE_MAX_TOKENS", "20000")) if os.getenv("OPENAI_COMPATIBLE_MAX_TOKENS") else None,
+                    "timeout": int(os.getenv("OPENAI_COMPATIBLE_TIMEOUT", "60"))
+                }
+            },
+
+            # Course Generation Settings
+            "course_generation": {
+                "default_difficulty": "beginner",
+                "default_lesson_count": 5,
+                "max_lesson_duration": 30,
+                "include_images": True,
+                "include_flashcards": True,
+                "include_quizzes": True,
+                "research_depth": "comprehensive"
+            },
+
+            # Image Generation Settings
+            "image_generation": {
+                "pollinations_api_token": os.getenv("POLLINATIONS_API_TOKEN", ""),
+                "pollinations_api_reference": os.getenv("POLLINATIONS_API_REFERENCE", ""),
+                "default_width": 1280,
+                "default_height": 720,
+                "default_model": "gptimage",
+                "enhance_prompts": True,
+                "no_logo": True
+            },
+
+            # Export Settings
+            "export": {
+                "default_formats": ["pdf", "markdown"],
+                "output_directory": os.getenv("COURSECRAFTER_OUTPUT_DIR", "./output"),
+                "max_file_size": 50 * 1024 * 1024,  # 50MB
+                "compression": True
+            },
+
+            # UI Settings
+            "ui": {
+                "theme": "soft",
+                "show_progress": True,
+                "auto_scroll": True,
+                "max_concurrent_generations": 3
+            },
+
+            # System Settings
+            "system": {
+                "default_llm_provider": default_llm_provider,
+                "max_turns": 25,
+                "timeout": 300,  # 5 minutes
+                "retry_attempts": 3,
+                "log_level": os.getenv("LOG_LEVEL", "INFO"),
+                "debug_mode": os.getenv("DEBUG", "false").lower() == "true"
+            }
+        }
+
+    def _validate_config(self):
+        """Validate configuration and warn about missing required settings"""
+        warnings = []
+
+        # Check LLM provider API keys
+        for provider, config in self._config["llm_providers"].items():
+            if provider == "openai_compatible":
+                # For openai_compatible, check for base_url instead of api_key
+                if not config.get("base_url"):
+                    warnings.append(f"Missing base_url for {provider}")
+            else:
+                # For other providers, check for api_key
+                if not config["api_key"]:
+                    warnings.append(f"Missing API key for {provider}")
+
+        # Check if at least one LLM provider is configured
+        has_provider = False
+        for provider, config in self._config["llm_providers"].items():
+            if provider == "openai_compatible":
+                if config.get("base_url"):
+                    has_provider = True
+                    break
+            else:
+                if config["api_key"]:
+                    has_provider = True
+                    break
+
+        if not has_provider:
+            # Only warn instead of raising error - allows app to start for UI configuration
+            print("⚠️ Warning: No LLM providers configured. Please configure at least one provider in the UI.")
+
+    def get_llm_config(self, provider: LLMProvider) -> LLMProviderConfig:
+        """Get configuration for a specific LLM provider"""
+        if provider not in self._config["llm_providers"]:
+            raise ValueError(f"Unknown LLM provider: {provider}")
+
+        config = self._config["llm_providers"][provider]
+        return LLMProviderConfig(**config)
+
+    def get_available_llm_providers(self) -> List[LLMProvider]:
+        """Get list of available LLM providers with API keys"""
+        available = []
+        for provider, config in self._config["llm_providers"].items():
+            if provider == "openai_compatible":
+                # For openai_compatible, require base_url instead of api_key
+                if config.get("base_url"):
+                    available.append(provider)
+            else:
+                # For other providers, require api_key
+                if config["api_key"]:
+                    available.append(provider)
+        return available
+
+    def get_default_llm_provider(self) -> LLMProvider:
+        """Get the default LLM provider, falling back to first available if not configured"""
+        default_provider = self._config["system"]["default_llm_provider"]
+        available_providers = self.get_available_llm_providers()
+        
+        # If the default provider is available, use it
+        if default_provider in available_providers:
+            return default_provider
+        
+        # Otherwise, use the first available provider
+        if available_providers:
+            print(f"⚠️ Default provider '{default_provider}' not configured, using '{available_providers[0]}'")
+            return available_providers[0]
+        
+        # If no providers are available, raise an error
+        raise ValueError("No LLM providers are configured. Please set up at least one provider.")
+
+    def get_image_generation_config(self) -> Dict[str, Any]:
+        """Get image generation configuration"""
+        return self._config["image_generation"]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value using dot notation"""
+        keys = key.split(".")
+        value = self._config
+
+        try:
+            for k in keys:
+                value = value[k]
+            return value
+        except (KeyError, TypeError):
+            return default
+
+    def set(self, key: str, value: Any):
+        """Set a configuration value using dot notation"""
+        keys = key.split(".")
+        config = self._config
+
+        for k in keys[:-1]:
+            if k not in config:
+                config[k] = {}
+            config = config[k]
+
+        config[keys[-1]] = value
+
+    def update_llm_provider(self, provider: LLMProvider, **kwargs):
+        """Update LLM provider configuration"""
+        if provider not in self._config["llm_providers"]:
+            raise ValueError(f"Unknown LLM provider: {provider}")
+
+        self._config["llm_providers"][provider].update(kwargs)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary"""
+        return self._config.copy()
+
+    def save_to_file(self, filepath: str):
+        """Save configuration to JSON file"""
+        with open(filepath, 'w') as f:
+            json.dump(self._config, f, indent=2)
+
+    @classmethod
+    def load_from_file(cls, filepath: str) -> 'Config':
+        """Load configuration from JSON file"""
+        instance = cls()
+
+        if os.path.exists(filepath):
+            with open(filepath, 'r') as f:
+                file_config = json.load(f)
+                instance._config.update(file_config)
+
+        instance._validate_config()
+        return instance
+
+# Global configuration instance
+config = Config()

coursecrafter/utils/helpers.py

@@ -0,0 +1,475 @@
+"""
+🛠️ Helper Utilities for CourseCrafter AI
+
+Common utility functions and helpers used throughout the application.
+"""
+
+import re
+import json
+import hashlib
+import asyncio
+from typing import Any, Dict, List, Optional, Union, Callable
+from datetime import datetime, timedelta
+import logging
+
+
+def generate_id(prefix: str = "", length: int = 8) -> str:
+    """Generate a unique ID with optional prefix"""
+    timestamp = str(int(datetime.now().timestamp() * 1000))
+    hash_obj = hashlib.md5(timestamp.encode())
+    unique_id = hash_obj.hexdigest()[:length]
+    
+    if prefix:
+        return f"{prefix}-{unique_id}"
+    return unique_id
+
+
+def clean_text(text: str) -> str:
+    """Clean and normalize text content"""
+    if not text:
+        return ""
+    
+    # Remove extra whitespace
+    text = re.sub(r'\s+', ' ', text.strip())
+    
+    # Remove control characters
+    text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
+    
+    # Normalize quotes
+    text = text.replace('"', '"').replace('"', '"')
+    text = text.replace(''', "'").replace(''', "'")
+    
+    return text
+
+
+def truncate_text(text: str, max_length: int = 100, suffix: str = "...") -> str:
+    """Truncate text to specified length with suffix"""
+    if not text or len(text) <= max_length:
+        return text
+    
+    # Try to break at word boundary
+    truncated = text[:max_length - len(suffix)]
+    last_space = truncated.rfind(' ')
+    
+    if last_space > max_length * 0.7:  # If we can break at a reasonable word boundary
+        truncated = truncated[:last_space]
+    
+    return truncated + suffix
+
+
+def extract_keywords(text: str, max_keywords: int = 10) -> List[str]:
+    """Extract keywords from text using simple frequency analysis"""
+    if not text:
+        return []
+    
+    # Clean text and convert to lowercase
+    clean = re.sub(r'[^\w\s]', ' ', text.lower())
+    words = clean.split()
+    
+    # Filter out common stop words
+    stop_words = {
+        'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+        'of', 'with', 'by', 'is', 'are', 'was', 'were', 'be', 'been', 'have',
+        'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should',
+        'this', 'that', 'these', 'those', 'i', 'you', 'he', 'she', 'it', 'we',
+        'they', 'me', 'him', 'her', 'us', 'them', 'my', 'your', 'his', 'its',
+        'our', 'their', 'can', 'may', 'might', 'must', 'shall', 'from', 'up',
+        'out', 'down', 'off', 'over', 'under', 'again', 'further', 'then',
+        'once', 'here', 'there', 'when', 'where', 'why', 'how', 'all', 'any',
+        'both', 'each', 'few', 'more', 'most', 'other', 'some', 'such', 'no',
+        'nor', 'not', 'only', 'own', 'same', 'so', 'than', 'too', 'very'
+    }
+    
+    # Filter words and count frequency
+    filtered_words = [word for word in words if len(word) > 2 and word not in stop_words]
+    word_freq = {}
+    
+    for word in filtered_words:
+        word_freq[word] = word_freq.get(word, 0) + 1
+    
+    # Sort by frequency and return top keywords
+    sorted_words = sorted(word_freq.items(), key=lambda x: x[1], reverse=True)
+    return [word for word, freq in sorted_words[:max_keywords]]
+
+
+def format_duration(seconds: int) -> str:
+    """Format duration in seconds to human-readable string"""
+    if seconds < 60:
+        return f"{seconds} seconds"
+    elif seconds < 3600:
+        minutes = seconds // 60
+        remaining_seconds = seconds % 60
+        if remaining_seconds == 0:
+            return f"{minutes} minutes"
+        return f"{minutes} minutes {remaining_seconds} seconds"
+    else:
+        hours = seconds // 3600
+        remaining_minutes = (seconds % 3600) // 60
+        if remaining_minutes == 0:
+            return f"{hours} hours"
+        return f"{hours} hours {remaining_minutes} minutes"
+
+
+def estimate_reading_time(text: str, words_per_minute: int = 200) -> int:
+    """Estimate reading time in minutes for given text"""
+    if not text:
+        return 0
+    
+    word_count = len(text.split())
+    minutes = max(1, round(word_count / words_per_minute))
+    return minutes
+
+
+def safe_json_loads(json_str: str, default: Any = None) -> Any:
+    """Safely parse JSON string with fallback"""
+    try:
+        return json.loads(json_str)
+    except (json.JSONDecodeError, TypeError):
+        return default
+
+
+def extract_json_from_response(response_text: str) -> str:
+    """
+    Extract JSON from LLM response that might be wrapped in markdown code blocks.
+    
+    Handles cases like:
+    - Plain JSON: {"key": "value"}
+    - Markdown wrapped: ```json\n{"key": "value"}\n```
+    - Mixed content: Some text\n```json\n{"key": "value"}\n```\nMore text
+    """
+    if not response_text:
+        return ""
+    
+    # First, try to find JSON in markdown code blocks
+    import re
+    
+    # Pattern to match ```json ... ``` or ``` ... ``` blocks
+    json_block_patterns = [
+        r'```json\s*\n(.*?)\n```',  # ```json ... ```
+        r'```\s*\n(.*?)\n```',     # ``` ... ```
+        r'`(.*?)`',                # Single backticks (less common)
+    ]
+    
+    for pattern in json_block_patterns:
+        matches = re.findall(pattern, response_text, re.DOTALL | re.IGNORECASE)
+        for match in matches:
+            # Try to parse each match as JSON
+            try:
+                json.loads(match.strip())
+                return match.strip()  # Return the first valid JSON found
+            except json.JSONDecodeError:
+                continue
+    
+    # If no markdown blocks found, try to extract JSON from the response
+    # Look for content between first { and last }
+    first_brace = response_text.find('{')
+    last_brace = response_text.rfind('}')
+    
+    if first_brace != -1 and last_brace != -1 and last_brace > first_brace:
+        potential_json = response_text[first_brace:last_brace + 1]
+        try:
+            json.loads(potential_json)
+            return potential_json
+        except json.JSONDecodeError:
+            pass
+    
+    # Look for content between first [ and last ] (for arrays)
+    first_bracket = response_text.find('[')
+    last_bracket = response_text.rfind(']')
+    
+    if first_bracket != -1 and last_bracket != -1 and last_bracket > first_bracket:
+        potential_json = response_text[first_bracket:last_bracket + 1]
+        try:
+            json.loads(potential_json)
+            return potential_json
+        except json.JSONDecodeError:
+            pass
+    
+    # If all else fails, return the original response
+    return response_text.strip()
+
+
+def smart_json_loads(response_text: str, default: Any = None) -> Any:
+    """
+    Smart JSON parser that handles markdown-wrapped JSON and other common LLM response formats.
+    
+    This function:
+    1. Extracts JSON from markdown code blocks
+    2. Handles mixed content responses
+    3. Provides fallback for malformed JSON
+    4. Logs parsing attempts for debugging
+    """
+    if not response_text:
+        return default
+    
+    # Extract potential JSON from the response
+    json_text = extract_json_from_response(response_text)
+    
+    # Try to parse the extracted JSON
+    try:
+        result = json.loads(json_text)
+        return result
+    except json.JSONDecodeError as e:
+        # Log the parsing failure for debugging
+        print(f"🔍 JSON parsing failed: {e}")
+        print(f"📝 Original response length: {len(response_text)} chars")
+        print(f"📝 Extracted JSON length: {len(json_text)} chars")
+        print(f"📝 First 200 chars of original: {response_text[:200]}...")
+        print(f"📝 First 200 chars of extracted: {json_text[:200]}...")
+        return default
+    except Exception as e:
+        print(f"❌ Unexpected error in JSON parsing: {e}")
+        return default
+
+
+def safe_json_dumps(obj: Any, default: Any = None) -> str:
+    """Safely serialize object to JSON string"""
+    try:
+        return json.dumps(obj, default=str, ensure_ascii=False, indent=2)
+    except (TypeError, ValueError):
+        return json.dumps(default or {})
+
+
+def merge_dicts(*dicts: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge multiple dictionaries, with later ones taking precedence"""
+    result = {}
+    for d in dicts:
+        if isinstance(d, dict):
+            result.update(d)
+    return result
+
+
+def flatten_list(nested_list: List[Any]) -> List[Any]:
+    """Flatten a nested list structure"""
+    result = []
+    for item in nested_list:
+        if isinstance(item, list):
+            result.extend(flatten_list(item))
+        else:
+            result.append(item)
+    return result
+
+
+def chunk_list(lst: List[Any], chunk_size: int) -> List[List[Any]]:
+    """Split a list into chunks of specified size"""
+    return [lst[i:i + chunk_size] for i in range(0, len(lst), chunk_size)]
+
+
+def deduplicate_list(lst: List[Any], key_func: Optional[Callable] = None) -> List[Any]:
+    """Remove duplicates from list while preserving order"""
+    if key_func is None:
+        seen = set()
+        result = []
+        for item in lst:
+            if item not in seen:
+                seen.add(item)
+                result.append(item)
+        return result
+    else:
+        seen = set()
+        result = []
+        for item in lst:
+            key = key_func(item)
+            if key not in seen:
+                seen.add(key)
+                result.append(item)
+        return result
+
+
+def retry_async(max_attempts: int = 3, delay: float = 1.0, backoff: float = 2.0):
+    """Decorator for retrying async functions with exponential backoff"""
+    def decorator(func: Callable) -> Callable:
+        async def wrapper(*args, **kwargs):
+            last_exception = None
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        logging.warning(f"Attempt {attempt + 1} failed: {str(e)}. Retrying in {current_delay}s...")
+                        await asyncio.sleep(current_delay)
+                        current_delay *= backoff
+                    else:
+                        logging.error(f"All {max_attempts} attempts failed. Last error: {str(e)}")
+            
+            raise last_exception
+        
+        return wrapper
+    return decorator
+
+
+def validate_email(email: str) -> bool:
+    """Validate email address format"""
+    if not email or not isinstance(email, str):
+        return False
+    
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return bool(re.match(pattern, email))
+
+
+def sanitize_filename(filename: str, max_length: int = 100) -> str:
+    """Sanitize filename for cross-platform compatibility"""
+    if not filename:
+        return "untitled"
+    
+    # Remove or replace invalid characters
+    filename = re.sub(r'[<>:"/\\|?*]', '_', filename)
+    
+    # Remove leading/trailing dots and spaces
+    filename = filename.strip('. ')
+    
+    # Limit length
+    if len(filename) > max_length:
+        name, ext = filename.rsplit('.', 1) if '.' in filename else (filename, '')
+        max_name_length = max_length - len(ext) - 1 if ext else max_length
+        filename = name[:max_name_length] + ('.' + ext if ext else '')
+    
+    # Ensure it's not empty
+    if not filename:
+        filename = "untitled"
+    
+    return filename
+
+
+def calculate_similarity(text1: str, text2: str) -> float:
+    """Calculate simple text similarity using Jaccard similarity"""
+    if not text1 or not text2:
+        return 0.0
+    
+    # Convert to sets of words
+    words1 = set(text1.lower().split())
+    words2 = set(text2.lower().split())
+    
+    # Calculate Jaccard similarity
+    intersection = len(words1.intersection(words2))
+    union = len(words1.union(words2))
+    
+    return intersection / union if union > 0 else 0.0
+
+
+def format_file_size(size_bytes: int) -> str:
+    """Format file size in bytes to human-readable string"""
+    if size_bytes == 0:
+        return "0 B"
+    
+    size_names = ["B", "KB", "MB", "GB", "TB"]
+    i = 0
+    size = float(size_bytes)
+    
+    while size >= 1024.0 and i < len(size_names) - 1:
+        size /= 1024.0
+        i += 1
+    
+    return f"{size:.1f} {size_names[i]}"
+
+
+def create_progress_callback(total_steps: int, callback_func: Optional[Callable] = None):
+    """Create a progress tracking callback function"""
+    current_step = 0
+    
+    def update_progress(step_name: str = "", increment: int = 1):
+        nonlocal current_step
+        current_step += increment
+        progress = min(current_step / total_steps, 1.0)
+        
+        if callback_func:
+            callback_func(progress, step_name, current_step, total_steps)
+        
+        return progress
+    
+    return update_progress
+
+
+def debounce(wait_time: float):
+    """Decorator to debounce function calls"""
+    def decorator(func: Callable) -> Callable:
+        last_called = [0.0]
+        
+        async def wrapper(*args, **kwargs):
+            now = asyncio.get_event_loop().time()
+            if now - last_called[0] >= wait_time:
+                last_called[0] = now
+                return await func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+class Timer:
+    """Simple timer context manager"""
+    
+    def __init__(self, name: str = "Operation"):
+        self.name = name
+        self.start_time = None
+        self.end_time = None
+    
+    def __enter__(self):
+        self.start_time = datetime.now()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.end_time = datetime.now()
+        duration = self.end_time - self.start_time
+        print(f"{self.name} completed in {duration.total_seconds():.2f} seconds")
+    
+    @property
+    def duration(self) -> Optional[timedelta]:
+        if self.start_time and self.end_time:
+            return self.end_time - self.start_time
+        return None
+
+
+class RateLimiter:
+    """Simple rate limiter for API calls"""
+    
+    def __init__(self, max_calls: int, time_window: float):
+        self.max_calls = max_calls
+        self.time_window = time_window
+        self.calls = []
+    
+    async def acquire(self):
+        """Wait if necessary to respect rate limits"""
+        now = datetime.now()
+        
+        # Remove old calls outside the time window
+        self.calls = [call_time for call_time in self.calls 
+                     if (now - call_time).total_seconds() < self.time_window]
+        
+        # If we're at the limit, wait
+        if len(self.calls) >= self.max_calls:
+            oldest_call = min(self.calls)
+            wait_time = self.time_window - (now - oldest_call).total_seconds()
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+        
+        # Record this call
+        self.calls.append(now)
+
+
+def get_nested_value(data: Dict[str, Any], key_path: str, default: Any = None) -> Any:
+    """Get nested dictionary value using dot notation"""
+    keys = key_path.split('.')
+    current = data
+    
+    try:
+        for key in keys:
+            current = current[key]
+        return current
+    except (KeyError, TypeError):
+        return default
+
+
+def set_nested_value(data: Dict[str, Any], key_path: str, value: Any) -> None:
+    """Set nested dictionary value using dot notation"""
+    keys = key_path.split('.')
+    current = data
+    
+    for key in keys[:-1]:
+        if key not in current or not isinstance(current[key], dict):
+            current[key] = {}
+        current = current[key]
+    
+    current[keys[-1]] = value 

requirements.txt

@@ -0,0 +1,57 @@
+# 🎓 CourseCrafter AI Dependencies
+# Core framework and UI
+gradio>=4.0.0
+streamlit>=1.28.0
+
+# LLM Providers
+openai>=1.0.0
+anthropic>=0.20.0
+google-generativeai>=0.3.0
+
+# MCP Integration
+mcp>=1.0.0
+
+# Content Processing
+markdown>=3.5.0
+beautifulsoup4>=4.12.0
+requests>=2.31.0
+aiohttp>=3.8.0
+duckduckgo-search>=6.0.0
+crawl4ai>=0.3.0
+
+# PDF Generation
+reportlab>=4.0.0
+weasyprint>=60.0
+
+# Image Processing
+pillow>=10.0.0
+matplotlib>=3.7.0
+
+# Data Handling
+pandas>=2.0.0
+numpy>=1.24.0
+pydantic>=2.0.0
+
+# Async Support
+asyncio>=3.4.3
+asyncio-throttle>=1.0.2
+
+# Environment & Config
+python-dotenv>=1.0.0
+pyyaml>=6.0
+
+# Utilities
+uuid>=1.30
+python-dateutil>=2.8.0
+tqdm>=4.65.0
+
+# Development & Testing
+pytest>=7.4.0
+pytest-asyncio>=0.21.0
+black>=23.0.0
+flake8>=6.0.0
+
+# Cloud Integration (optional)
+google-auth>=2.22.0
+google-auth-oauthlib>=1.0.0
+google-auth-httplib2>=0.1.0