Upload llms_handler.py

Improved llm handler with individual llms for duration evaluation, structure, activity selection and lesson plan generation

llms_handler.py

@@ -0,0 +1,428 @@
+import os
+import json
+from openai import OpenAI
+from typing import Dict, List, Any, Optional
+from dotenv import load_dotenv
+
+
+class LLMHandler:
+    def __init__(self):
+        """Initialize the LLM handler with OpenAI client."""
+        load_dotenv()
+        self.client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))
+        self.model = "gpt-4o-mini"
+
+    def input_extraction_validation(self, user_prompt: str) -> Dict[str, Any]:
+        """
+        Extract and validate key information from user prompt.
+        Returns a dictionary with extracted information and duration adequacy assessment.
+        """
+        system_prompt = """
+        You are an expert in language education, specializing in extracting key information from lesson requests.
+        Your task is to identify and validate crucial parameters for language lesson planning.
+        """
+
+        user_message = f"""
+        Extract key information from the following request for a lesson plan:
+
+        User Request: {user_prompt}
+
+        Extract the following information:
+        - topic: The main subject of the lesson
+        - age_group: Target age group (e.g., Elementary (6-11), High School (14-18), Adult)
+        - proficiency_level: Language proficiency according to CEFR (e.g., A1, A2, B1, B2, C1, C2)
+        - lesson_duration: Length of the lesson in minutes
+        - tech_requirements: Any technology needed for the lesson
+        - output_language: Language in which materials should be produced
+        - number_of_students: Number of students in the class
+        - skills_to_focus: Skills to emphasize (e.g., reading, writing, listening, speaking)
+
+      
+
+        Then, evaluate whether the provided duration is sufficient for a structured lesson plan (PPP, ESA, TTT, TBL, or UbD) based on:
+        - The complexity of the topic
+        - The proficiency level of the learners
+
+        If duration is insufficient: set "duration_adequacy" to "Not sufficient for structured lesson plan"
+        If duration is sufficient: set "duration_adequacy" to "Sufficient for structured lesson plan"
+        Return ONLY a JSON object with these fields. No explanations or other text.
+
+        """
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message}
+                ],
+                response_format={"type": "json_object"}
+            )
+
+            # Try to parse the response as JSON
+            extracted_info = json.loads(response.choices[0].message.content)
+
+            # Validate essential fields and set defaults if missing
+            if not extracted_info.get("topic"):
+                extracted_info["topic"] = "No context provided"
+
+            if not extracted_info.get("lesson_duration"):
+                extracted_info["lesson_duration"] = "30 minutes"
+
+            if not extracted_info.get("proficiency_level"):
+                extracted_info["proficiency_level"] = "Intermediate [B1, B2]"
+
+            if not extracted_info.get("age_group"):
+                extracted_info["age_group"] = "Elementary (6-11)"
+
+            if not extracted_info.get("tech_requirements"):
+                extracted_info["tech_requirements"] = ["White Board", "Internet Access"]
+
+            if not extracted_info.get("output_language"):
+                extracted_info["output_language"] = "English"
+
+            if not extracted_info.get("number_of_students"):
+                extracted_info["number_of_students"] = "No context provided"
+
+            if not extracted_info.get("skills_to_focus"):
+                extracted_info["skills_to_focus"] = "No context provided"
+
+            if not extracted_info.get("duration_adequacy"):
+                # Fallback if model doesn't assess duration
+                extracted_info["duration_adequacy"] = "Sufficient for structured lesson plan"
+
+            return extracted_info
+
+        except Exception as e:
+            print(f"Error in input_extraction_validation: {str(e)}")
+            # Return default values
+            return {
+                "topic": "General language practice",
+                "age_group": "Elementary (6-11)",
+                "proficiency_level": "Intermediate [B1, B2]",
+                "lesson_duration": "30 minutes",
+                "tech_requirements": ["White Board", "Internet Access"],
+                "output_language": "English",
+                "number_of_students": "No context provided",
+                "skills_to_focus": "No context provided",
+                "duration_adequacy": "Sufficient for structured lesson plan"
+            }
+
+    def lesson_plan_structure(self, input_data: Dict[str, Any]) -> Dict[str, str]:
+        """
+        Determine the appropriate lesson plan structure based on the extracted information.
+        Returns a dictionary with the selected structure and description.
+        """
+        system_prompt = """
+        You are an expert educator specializing in language lesson planning frameworks.
+        Your task is to select the most appropriate lesson structure based on given parameters.
+        """
+
+        user_message = f"""
+        Based on the following information about a language lesson, determine the most appropriate lesson plan structure:
+
+        Topic: {input_data.get('topic', 'No context provided')}
+        Age Group: {input_data.get('age_group', 'No context provided')}
+        Proficiency Level: {input_data.get('proficiency_level', 'No context provided')}
+        Lesson Duration: {input_data.get('lesson_duration', 'No context provided')}
+        Duration Adequacy: {input_data.get('duration_adequacy', 'No context provided')}
+        Skills to Focus: {input_data.get('skills_to_focus', 'No context provided')}
+
+        If Duration Adequacy is "Not sufficient for structured lesson plan":
+          - Set output_structure to "Generic" 
+          - Set description to "The given duration is not sufficient to create a fully structured lesson plan. Instead, a simplified activity plan has been provided."
+
+        Otherwise, select the most appropriate structure from:
+          - PPP (Presentation, Practice, Production) - For young learners, basic comprehension, structured activities
+          - ESA (Engage, Study, Activate) - For young learners needing flexibility (consider Boomerang ESA or Patchwork ESA variants)
+          - TBL (Task-Based Learning) - For high school, advanced learners, or adults focusing on real-world applications
+          - TTT (Test, Teach, Test) - For learners with prior knowledge to assess gaps, instruct, and reassess
+          - UbD (Understanding by Design) - For long-term, curriculum-based instruction
+          
+          Return your response as a JSON object with these two fields:
+          - output_structure: The selected structure (PPP, ESA, TBL, TTT, UbD, or Generic)
+          - description: A brief explanation of why this framework structure was chosen
+        """
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message}
+                ],
+                response_format={"type": "json_object"}
+            )
+
+            structure_info = json.loads(response.choices[0].message.content)
+
+            # Validate required fields
+            if not structure_info.get("output_structure"):
+                structure_info["output_structure"] = "Generic"
+
+            if not structure_info.get("description"):
+                structure_info[
+                    "description"] = "A simplified lesson plan structure was selected based on the available information."
+
+            return structure_info
+
+        except Exception as e:
+            print(f"Error in lesson_plan_structure: {str(e)}")
+            # Fallback if the response is not valid JSON
+            return {
+                "output_structure": "Generic",
+                "description": "A simplified lesson plan structure was selected as a fallback."
+            }
+
+    def activity_template_selection(self, input_data: Dict[str, Any], structure_info: Dict[str, str]) -> Dict[
+        str, List[str]]:
+        """
+        Select appropriate activity/worksheet templates based on lesson structure, topic, and duration.
+        Returns a dictionary with a list of selected activity templates.
+        """
+        system_prompt = """
+        You are an expert language instructor specializing in selecting appropriate activities for lessons.
+        Your task is to choose the most suitable activity templates based on lesson parameters.
+        """
+
+        user_message = f"""
+                            Select the top 5 most suitable worksheet and activity templates for a language lesson with the following characteristics:
+                    
+                    Lesson Structure: {structure_info.get('output_structure', 'Generic')}
+                    Topic: {input_data.get('topic', 'No context provided')}
+                    Duration: {input_data.get('lesson_duration', '30 minutes')}
+                    Age Group: {input_data.get('age_group', 'Elementary (6-11)')}
+                    Proficiency Level: {input_data.get('proficiency_level', 'Intermediate [B1, B2]')}
+                    Skills to Focus: {input_data.get('skills_to_focus', 'No context provided')}
+                    
+                    Choose ONLY from these activity templates:
+                    1. Fill in the blank
+                    2. Picture/Visual
+                    3. Sentence Formation
+                    4. Finding
+                    5. Matching
+                    6. Short Response
+                    7. Long Response
+                    8. Correction
+                    9. Audio as material [suitable for activities to focus on listening tasks] 
+                    Selection Guidelines:
+                    
+                    Prioritize activities that match the Skills to Focus, proficiency level, lesson structure, topic. 
+                    For beginner learners (A1, A2), emphasize simple activities like Matching, Picture/Visual, and Fill in the Blank.
+                    For intermediate/advanced learners (B1, B2), incorporate Finding, Short Response, and Long Response.
+                    Ensure a balance of engagement and difficulty.
+                    Return your selection as a JSON object with this field:
+                     - activity_templates: An array containing 5 selected activity templates from the list above
+        """
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message}
+                ],
+                response_format={"type": "json_object"}
+            )
+
+            templates_info = json.loads(response.choices[0].message.content)
+
+            # Validate the response contains activity_templates
+            if not templates_info.get("activity_templates"):
+                templates_info["activity_templates"] = [
+                    "Fill in the blank",
+                    "Picture/Visual",
+                    "Matching",
+                    "Short Response",
+                    "Correction"
+                ]
+
+            # Ensure we have exactly 5 templates
+            if len(templates_info["activity_templates"]) < 5:
+                # Add default templates to reach 5
+                default_templates = [
+                    "Fill in the blank",
+                    "Picture/Visual",
+                    "Matching",
+                    "Short Response",
+                    "Correction"
+                ]
+
+                for template in default_templates:
+                    if template not in templates_info["activity_templates"] and len(
+                            templates_info["activity_templates"]) < 5:
+                        templates_info["activity_templates"].append(template)
+
+            if len(templates_info["activity_templates"]) > 5:
+                templates_info["activity_templates"] = templates_info["activity_templates"][:5]
+
+            return templates_info
+
+        except Exception as e:
+            print(f"Error in activity_template_selection: {str(e)}")
+            # Fallback if the response is not valid JSON
+            return {
+                "activity_templates": [
+                    "Fill in the blank",
+                    "Picture/Visual",
+                    "Matching",
+                    "Short Response",
+                    "Correction"
+                ]
+            }
+
+    def lesson_plan_generation(
+            self,
+            input_data: Dict[str, Any],
+            structure_info: Dict[str, str],
+            activity_info: Dict[str, List[str]]
+    ) -> Dict[str, Any]:
+        """
+        Generate a complete lesson plan based on all previous inputs.
+        Returns a structured JSON lesson plan.
+        """
+        lesson_structure = structure_info.get("output_structure", "Generic")
+        structure_description = structure_info.get("description", "")
+        activity_templates = activity_info.get("activity_templates", [])
+
+        system_prompt = """
+        You are an expert language instructor with extensive experience in creating detailed lesson plans.
+        Your task is to generate a comprehensive, well-structured lesson plan based on provided parameters.
+        These are the details about the activity templates we are considering: 
+        Fill in the Blanks: This activity assesses students’ ability to apply knowledge learned during the lesson.
+        Example: Complete the sentences using the correct verb forms.
+        Picture/Visual: This activity tests students' ability to interpret basic pictorial information, such as icons of fruits, animals, and everyday objects.
+        Example: Identify and write the names of the fruits and vegetables shown in the images.
+        Sentence Formation: This activity helps students practice sentence construction using minimal context.
+        Example: Given the words "your brother, height," form a question: "How tall is your brother?"
+        Finding: This activity strengthens vocabulary and comprehension by requiring students to identify words based on definitions or clues.
+        Example: What is the term for a woman on her wedding day? Answer: Bride
+        Matching: This activity reinforces the relationship between different concepts by having students pair related elements.
+        Example: Match the illnesses in one column with their appropriate treatments in another.
+        Short Response: This activity helps students practice forming concise answers to questions.
+        Example: "Which do you prefer—tea or coffee?" Answer: I prefer coffee over tea.
+        Long Response: This activity encourages students to construct detailed responses or dialogues.
+        Example: Write a conversation between you and a friend who has just passed an exam.
+        Correction: This activity develops students’ ability to identify and correct grammatical or structural errors in sentences.
+        Example: Identify and correct the mistakes in the given sentences.
+        Audio: This activity aids students to develop their listening skills.
+        Example: Listen to the audio of customer speaking to a tech support agent and answer to the below questions.
+
+        """
+
+        if lesson_structure == "Generic":
+            user_message = f"""
+            Generate a Basic Activity Plan for a language lesson with the following details:
+
+            Topic: {input_data.get('topic', 'No context provided')}
+            Age Group: {input_data.get('age_group', 'Elementary (6-11)')}
+            Proficiency Level: {input_data.get('proficiency_level', 'Intermediate [B1, B2]')}
+            Lesson Duration: {input_data.get('lesson_duration', '30 minutes')}
+            Tech Requirements: {input_data.get('tech_requirements', ['White Board', 'Internet Access'])}
+            Output Language: {input_data.get('output_language', 'English')}
+            Number of Students: {input_data.get('number_of_students', 'No context provided')}
+            Skills to Focus: {input_data.get('skills_to_focus', 'No context provided')}
+
+            The plan should focus on selecting 2 or 3 meaningful activity due to time constraints. Include a note stating:
+            "The given duration is not sufficient to create a fully structured lesson plan. Instead, a simplified activity plan has been provided."
+
+            Include only activities that match these templates: {', '.join(activity_templates)}.
+
+            You must include the following sections in your JSON response:
+            - lesson_plan_title
+            - structure (which should be "Generic")
+            - structure_explanation (explanation that this is a simplified plan due to time constraints)
+            - objectives
+            - learning_outcomes
+            - materials_and_resources (*Avoid external platforms like Kahoot, Quizlet*)  
+            - activity_plan (with timing, e.g., "Activity [X min]") and detail description explaining the activity and its objective.
+            - assessment_strategy
+            
+            Provide your complete response in JSON format.
+            """
+        else:
+            user_message = f"""
+            Generate a structured lesson plan using the {lesson_structure} framework for a language lesson with the following details:
+
+            Topic: {input_data.get('topic', 'No context provided')}
+            Age Group: {input_data.get('age_group', 'Elementary (6-11)')}
+            Proficiency Level: {input_data.get('proficiency_level', 'Intermediate [B1, B2]')}
+            Lesson Duration: {input_data.get('lesson_duration', '30 minutes')}
+            Tech Requirements: {input_data.get('tech_requirements', ['White Board', 'Internet Access'])}
+            Output Language: {input_data.get('output_language', 'English')}
+            Number of Students: {input_data.get('number_of_students', 'No context provided')}
+            Skills to Focus: {input_data.get('skills_to_focus', 'No context provided')}
+
+            Framework Structure: {lesson_structure}
+            Framework Explanation: {structure_description}
+
+            Include only activities that match these templates: {', '.join(activity_templates)}
+
+            You must include the following sections in your JSON response:
+            - lesson_plan_title
+            - structure (which should be "{lesson_structure}")
+            - structure_explanation (brief explanation of why this framework was chosen)
+            - objectives
+            - learning_outcomes
+            - essential_questions (if using UbD)
+            - materials_and_resources (avoid external platforms like Kahoot, Quizlet)
+            - lesson_plan_structure - with all appropriate sections for {lesson_structure} framework, each containing:
+              * key_parts (with time allocations, e.g., "Engage [20 minutes]")
+              * objective (purpose of this section)
+              * activityies (with timing, e.g., "Activity [X min]") and detail description explaining the activity and its objective.
+            - assessment_strategies
+            - additional_details
+            
+            Provide your complete response in JSON format.
+            For time allocations, use brackets format (e.g., "Reflection [5 min]").
+            Ensure all activities have detailed descriptions.
+            """
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message}
+                ],
+                response_format={"type": "json_object"}
+            )
+
+            lesson_plan = json.loads(response.choices[0].message.content)
+
+            # Basic validation of the lesson plan
+            required_fields = ["lesson_plan_title", "structure", "objectives", "learning_outcomes"]
+
+            for field in required_fields:
+                if field not in lesson_plan:
+                    if field == "lesson_plan_title":
+                        lesson_plan[field] = f"Language Lesson: {input_data.get('topic', 'General Practice')}"
+                    elif field == "structure":
+                        lesson_plan[field] = lesson_structure
+                    elif field == "objectives":
+                        lesson_plan[field] = ["Improve language skills"]
+                    elif field == "learning_outcomes":
+                        lesson_plan[field] = ["Students will be able to communicate more effectively"]
+
+            return lesson_plan
+
+        except Exception as e:
+            print(f"Error in lesson_plan_generation: {str(e)}")
+            # Create a minimal fallback lesson plan
+            return {
+                "lesson_plan_title": f"Language Lesson: {input_data.get('topic', 'General Practice')}",
+                "structure": lesson_structure,
+                "structure_explanation": structure_description or "Basic language practice structure",
+                "objectives": ["Improve language skills"],
+                "learning_outcomes": ["Students will be able to communicate more effectively"],
+                "materials_and_resources": ["Whiteboard", "Handouts"],
+                "lesson_plan_structure": {
+                    "main_activity": {
+                        "key_parts": "Main Activity [30 minutes]",
+                        "objective": "Practice language skills",
+                        "activities": "Complete worksheet activities"
+                    }
+                },
+                "assessment_strategies": ["Informal assessment through observation"],
+                "note": "This is a fallback lesson plan due to processing limitations."
+            }