coursecrafter/types.py

"""

📊 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)