Generate educational flashcards for effective study and memorization.

This function creates a set of flashcards using EduChain's content engine,
focusing on key concepts, definitions, and important facts related to the topic.
Each flashcard contains a question/prompt on one side and a comprehensive
answer on the other side, optimized for spaced repetition learning.

Args:
    topic (str): The subject area, concept, or learning domain for which to
        create flashcards. Should be specific enough to generate focused content.
        Examples: "Spanish Vocabulary - Food", "Chemistry - Periodic Table",
        "History - World War I Events"
    num_cards (int, optional): The number of flashcards to generate.
        Defaults to 10. Must be between 1 and 50.
    difficulty (Optional[str]): The difficulty level for the flashcards.
        Options: "beginner", "intermediate", "advanced". If not provided,
        a mixed difficulty approach will be used.

Returns:
    Dict[str, Any]: A dictionary containing the generated flashcards and metadata.
        On success:
        - flashcards: List of flashcard objects with front and back content
        - topic: The input topic
        - count: Number of flashcards generated
        - difficulty: Difficulty level (if specified)
        On error:
        - error: Detailed error message

Raises:
    ValueError: If num_cards is not in the valid range (1-50)

Example:
    >>> generate_flashcards("Spanish Vocabulary - Animals", 5, "beginner")
    {
        "flashcards": [
            {
                "front": "What is the Spanish word for 'dog'?",
                "back": "perro (masculine noun)"
            },
            {
                "front": "Translate: 'The cat is sleeping'",
                "back": "El gato está durmiendo"
            },
            ...
        ],
        "topic": "Spanish Vocabulary - Animals",
        "count": 5,
        "difficulty": "beginner"
    }

Generate multiple-choice questions (MCQs) for a given educational topic.

This function leverages EduChain's QnA engine to create well-structured
multiple-choice questions with correct answers and plausible distractors.
Each question includes four options with one correct answer.

Args:
    topic (str): The educational topic or subject area for which to generate
        questions. Should be specific enough to generate focused questions.
        Examples: "Photosynthesis", "World War II", "Python Programming"
    num_questions (int, optional): The number of questions to generate.
        Defaults to 5. Must be between 1 and 20.

Returns:
    Dict[str, Any]: A dictionary containing the generated questions and metadata.
        On success, includes:
        - questions: List of question objects with options and correct answers
        - topic: The input topic
        - count: Number of questions generated
        On error, includes:
        - error: Error message describing what went wrong

Raises:
    ValueError: If num_questions is not in the valid range (1-20)

Example:
    >>> generate_mcqs("Photosynthesis", 3)
    {
        "questions": [
            {
                "question": "What is the primary purpose of photosynthesis?",
                "options": ["A) ...", "B) ...", "C) ...", "D) ..."],
                "correct_answer": "B"
            },
            ...
        ],
        "topic": "Photosynthesis",
        "count": 3
    }

Generate a comprehensive, structured lesson plan for a given educational topic.

This function creates a detailed lesson plan using EduChain's content engine,
including learning objectives, materials needed, activities, and assessment methods.
The lesson plan follows educational best practices and can be customized for
different grade levels and durations.

Args:
    topic (str): The subject, concept, or learning objective for the lesson.
        Should be specific and focused. Examples: "Introduction to Fractions",
        "The American Revolution", "Basic HTML Tags"
    duration (Optional[str]): The intended duration of the lesson.
        Examples: "45 minutes", "1 hour", "2 class periods". If not provided,
        a standard duration will be assumed.
    grade_level (Optional[str]): The target grade level or educational level.
        Examples: "Grade 5", "High School", "College Level", "Adult Education".
        If not provided, a general approach will be used.

Returns:
    Dict[str, Any]: A comprehensive lesson plan dictionary containing:
        On success:
        - title: Lesson title
        - objectives: Learning objectives and goals
        - materials: Required materials and resources
        - activities: Structured learning activities
        - assessment: Methods for evaluating student learning
        - duration: Lesson duration
        - grade_level: Target grade level
        On error:
        - error: Detailed error message

Example:
    >>> lesson_plan("Photosynthesis", "50 minutes", "Grade 7")
    {
        "title": "Understanding Photosynthesis",
        "objectives": ["Students will understand...", "Students will be able to..."],
        "materials": ["Textbook", "Microscope", "Plant samples"],
        "activities": [
            {
                "name": "Introduction",
                "duration": "10 minutes",
                "description": "..."
            },
            ...
        ],
        "assessment": "Quiz on key concepts",
        "duration": "50 minutes",
        "grade_level": "Grade 7"
    }