agents/final_outliners/axis_generator.py

from crewai import Agent, Task, Crew, Process, LLM
import os
import json
from modules import llm_5m
from schemas import FullCurriculumStructure


axis_generator_agent = Agent(
    role="Arabic Educational Subtopic Generator (Subtopic Developer)",
    goal=(
        "Analyze the provided metadata ({topic}, {domain}, {audience}, {content_type}, {material_type}) "
        "along with the CurriculumStructure (main concept, related concepts, and units). "
        # "Receive the output of the unit generator (which includes units titles and focuses). "
        "For each unit — based on its title and focus — generate 5 coherent and progressive Arabic subtopics (axes). "
        "These subtopics should represent a logical and educational flow from foundational understanding "
        "to advanced application and creativity. "
        # "Each axis should represent a specific stage of learning progression — starting from basic knowledge acquisition "
        # "and moving toward critical thinking and creative application. "
        "Each axis should correspond to a cognitive stage: remembering, understanding, applying, analyzing, evaluating, and creating. "
        ## ADD
        "Example:"
        "- Unit: التفكير التصميمي وحل المشكلات"
        "- Given Subtopics:"
        "  • ماذا يعنى حل المشكلة؟"
        "  • 4 خطوات لحل المشكلة"
        "  • الفرق بين التفكير التحليلي والتصميمي في حل المشكلات"
        "  • نهج التفكير التصميمي لحل المشكلات"
        "  • نماذج تطبيقية ناجحة في حل المشكلات بالتفكير التصميمي"
        "- Observation: The first two are introductory — essential for understanding the later applied parts."
        ## ADD
        "Finally, ensure that all generated titles and subtopics (axes) comply with the approved Arabic educational titling standards:\n"
        "- Titles must be clear, direct, and precise, avoiding ambiguous or poetic phrasing.\n"
        "- Avoid dual or compound titles; use a single, focused phrasing.\n"
        "- Each title must reflect its actual educational content accurately.\n"
        "- Limited creativity is acceptable, but without exaggeration or metaphorical obscurity.\n"
        "- Always adapt the title to the target audience’s cultural and cognitive level.\n"
        "These standards ensure the linguistic clarity and educational value of all generated subtopics."
        "📝 SUBTOPICS TITLE (axes) QUALITY & LANGUAGE VALIDATION\n"
        "===================================================\n"
        "Each subtopic title plays a vital role as the front-facing part of the content. Titles must be crafted carefully following "
        "the comprehensive Arabic educational standards below:\n\n"
        "📘 **General Rules:**\n"
        "✅ Each title must be clear, concise (4–8 words preferred), and engaging.\n"
        "✅ Written in tone appropriate for {audience}.\n"
        "✅ It must clearly indicate that it belongs to the main unit or topic; so even if read alone, it’s recognizable as part of the same subject — e.g., 'تصميم المبادرات الأسرية'.\n"
        "✅ Avoid unnecessary punctuation (– , ; : . ! ? , /) except for simple questions.\n"
        "✅ Represent one coherent idea only — avoid dual or compound titles.\n"
        "✅ Avoid activity-based phrasing (like 'ورشة عمل', 'نشاط').\n"
        "✅ Sound realistic, teachable, and suitable for Arabic educational material.\n\n"
        "Ensure that the axes are written as Arabic educational subheadings that align with the unit’s focus, "
        "support conceptual growth, and maintain thematic coherence across the curriculum."
        "Ensure all axes are contextually relevant to the unit's focus and contribute to the learner's comprehensive understanding."
        "Additionally, before finalizing each axis, verify that it can be supported by available educational content such as articles, research papers, open educational resources, or online books. "
        "Ensure that each axis represents a concept or topic that has sufficient publicly available Arabic or English educational materials that could be used for further learning content generation."
    ),
    backstory=(
        "You are a senior Arabic curriculum designer and learning progression specialist. "
        "You possess deep expertise in Arabic pedagogy and cognitive development frameworks such as Bloom’s Taxonomy. "
        "You skillfully expand each educational unit into coherent Arabic subtopics (axes) that reflect a logical learning progression — "
        "starting from basic understanding and moving toward higher-order thinking and creative application. "
        "Each axis builds upon the previous one to form a cohesive and culturally relevant learning journey. "
        "Your designs prioritize conceptual clarity, educational depth, and alignment with Arabic academic standards."
        "You also ensure that each generated subtopic (axis) is research-backed and can be supported by credible educational materials available online, enabling later integration with content retrieval systems."
        ## ADD
        "You strictly follow the approved Arabic educational title formulation standards, ensuring clarity, precision, and appropriateness for the learner’s level."
    ),
    output_format=(
        "Return valid JSON strictly following this structure:\n"
        "{\n"
        "  'main_concept': '...',\n"
        "  'related_concepts': ['...', '...'],\n"
        "  'units': [\n"
        "     {\n"
        "        'unit_number': 1,\n"
        "        'title': 'الوحدة الأولى: ...',\n"
        "        'focus': '...',\n"
        "        'axes': [\n"
        "            {'axis_number': 1, 'title': '...', 'purpose': '...'},\n"
        "            {'axis_number': 2, 'title': '...', 'purpose': '...'},\n"
        "            {'axis_number': 3, 'title': '...', 'purpose': '...'},\n"
        "            {'axis_number': 4, 'title': '...', 'purpose': '...'},\n"
        "            {'axis_number': 5, 'title': '...', 'purpose': '...'}\n"
        "        ]\n"
        "     }, ...\n"
        "  ]\n"
        "}"
    ),
    examples=[
        {
            "input": {
                "main_concept": "التفكير التصميمي",
                "related_concepts": [
                    "حل المشكلات",
                    "اتخاذ القرار",
                    "الإبداع",
                    "تحسين العمليات",
                ],
                "units": [
                    {
                        "unit_number": 1,
                        "title": "الوحدة الأولى: مدخل إلى التفكير التصميمي",
                        "focus": "فهم المفهوم الجوهري وأبعاده الفكرية والنظرية",
                    },
                    {
                        "unit_number": 2,
                        "title": "الوحدة الثانية: الأدوات والمجالات العملية لتطبيق التفكير التصميمي",
                        "focus": "تطبيق أدوات التفكير التصميمي في بيئات واقعية ومجالات مختلفة",
                    },
                    {
                        "unit_number": 3,
                        "title": "الوحدة الثالثة: التفكير التصميمي وحل المشكلات",
                        "focus": "توظيف التفكير التصميمي كمنهج فعال في معالجة التحديات وإيجاد حلول مبتكرة",
                    },
                    {
                        "unit_number": 4,
                        "title": "الوحدة الرابعة: التفكير التصميمي مدخل لتطوير مهارات اتخاذ القرار",
                        "focus": "استخدام التفكير التصميمي كأداة لتحسين جودة القرارات وتطوير مهارات المفكر التصميمي",
                    },
                ],
            },
            "output": {
                "units": [
                    {
                        "unit_number": 1,
                        "title": "الوحدة الأولى: مدخل إلى التفكير التصميمي",
                        "focus": "فهم المفهوم الجوهري وأبعاده الفكرية والنظرية",
                        "axes": [
                            {
                                "axis_number": 1,
                                "title": "ما هو التفكير التصميمي؟",
                                "purpose": "تعريف المفهوم وشرح جوهره الفلسفي والعملي",
                            },
                            {
                                "axis_number": 2,
                                "title": "أهمية التفكير التصميمي",
                                "purpose": "إبراز الدور الحيوي للتفكير التصميمي في الإبداع والابتكار",
                            },
                            {
                                "axis_number": 3,
                                "title": "المبادئ الأساسية للتفكير التصميمي",
                                "purpose": "توضيح الأسس التي يقوم عليها النهج التصميمي",
                            },
                            {
                                "axis_number": 4,
                                "title": "المراحل الخمس للتفكير التصميمي",
                                "purpose": "شرح خطوات العملية التصميمية من التعاطف إلى الاختبار",
                            },
                            {
                                "axis_number": 5,
                                "title": "نماذج تطبيقية ناجحة للتفكير التصميمي",
                                "purpose": "عرض أمثلة عملية من مؤسسات استخدمت التفكير التصميمي بفعالية",
                            },
                        ],
                    },
                    {
                        "unit_number": 2,
                        "title": "الوحدة الثانية: الأدوات والمجالات العملية لتطبيق التفكير التصميمي",
                        "focus": "تطبيق أدوات التفكير التصميمي في بيئات واقعية ومجالات مختلفة",
                        "axes": [
                            {
                                "axis_number": 1,
                                "title": "استخدامات التفكير التصميمي",
                                "purpose": "توضيح المجالات التي يمكن تطبيق التفكير التصميمي فيها",
                            },
                            {
                                "axis_number": 2,
                                "title": "ستة مجالات عملية يظهر فيها أثر التفكير التصميمي",
                                "purpose": "عرض تطبيقات التفكير التصميمي في مجالات متنوعة",
                            },
                            {
                                "axis_number": 3,
                                "title": "أدوات التفكير التصميمي",
                                "purpose": "تعريف المتعلم بأهم الأدوات والوسائل المستخدمة في العملية التصميمية",
                            },
                            {
                                "axis_number": 4,
                                "title": "عوامل يجب مراعاتها عند تنفيذ عملية التفكير التصميمي",
                                "purpose": "توضيح الاعتبارات التي تضمن نجاح التطبيق",
                            },
                            {
                                "axis_number": 5,
                                "title": "التحديات الشائعة في التفكير التصميمي",
                                "purpose": "تحليل العقبات التي تواجه الفرق عند تطبيق هذا النهج",
                            },
                        ],
                    },
                    {
                        "unit_number": 3,
                        "title": "الوحدة الثالثة: التفكير التصميمي وحل المشكلات",
                        "focus": "توظيف التفكير التصميمي كمنهج فعال في معالجة التحديات وإيجاد حلول مبتكرة",
                        "axes": [
                            {
                                "axis_number": 1,
                                "title": "ماذا يعني حل المشكلة؟",
                                "purpose": "توضيح المفهوم النظري والعملي لحل المشكلات",
                            },
                            {
                                "axis_number": 2,
                                "title": "أربع خطوات لحل المشكلة",
                                "purpose": "شرح المراحل الأساسية في عملية حل المشكلات",
                            },
                            {
                                "axis_number": 3,
                                "title": "الفرق بين التفكير التحليلي والتصميمي في حل المشكلات",
                                "purpose": "المقارنة بين نهجين مختلفين في معالجة القضايا",
                            },
                            {
                                "axis_number": 4,
                                "title": "نهج التفكير التصميمي لحل المشكلات",
                                "purpose": "شرح كيفية استخدام التفكير التصميمي لإيجاد حلول مبتكرة",
                            },
                            {
                                "axis_number": 5,
                                "title": "نماذج تطبيقية ناجحة في حل المشكلات بالتفكير التصميمي",
                                "purpose": "تقديم دراسات حالة توضح نجاح النهج التصميمي في معالجة قضايا واقعية",
                            },
                        ],
                    },
                    {
                        "unit_number": 4,
                        "title": "الوحدة الرابعة: التفكير التصميمي مدخل لتطوير مهارات اتخاذ القرار",
                        "focus": "استخدام التفكير التصميمي كأداة لتحسين جودة القرارات وتطوير مهارات المفكر التصميمي",
                        "axes": [
                            {
                                "axis_number": 1,
                                "title": "ما هو اتخاذ القرار؟",
                                "purpose": "تعريف عملية اتخاذ القرار وعناصرها الأساسية",
                            },
                            {
                                "axis_number": 2,
                                "title": "خصائص المفكر التصميمي ودوره في تحسين القرارات",
                                "purpose": "توضيح السمات الشخصية والعقلية للمفكر التصميمي",
                            },
                            {
                                "axis_number": 3,
                                "title": "العلاقة بين التفكير التصميمي واتخاذ القرار",
                                "purpose": "شرح كيفية مساهمة النهج التصميمي في اتخاذ قرارات فعالة",
                            },
                            {
                                "axis_number": 4,
                                "title": "سبع خطوات لعملية اتخاذ القرار باستخدام التفكير التصميمي",
                                "purpose": "عرض مراحل متكاملة لاتخاذ القرار بأسلوب تصميمي",
                            },
                            {
                                "axis_number": 5,
                                "title": "كيف انعكس التفكير التصميمي في قرارات ناجحة؟",
                                "purpose": "عرض أمثلة واقعية لنجاحات عملية في قرارات اتخذت عبر التفكير التصميمي",
                            },
                        ],
                    },
                ]
            },
        }
    ],
    # llm=llm_open_c35,
    llm=llm_5m,
    allow_delegation=False,
    verbose=True,
    reasoning=True,
    max_iter=100,
)

# ============================================================
# 🧩 3. Axis Generation Task
# ============================================================

axis_generation_task = Task(
    description=(
        "## GOAL\n"
        "Expand each educational unit from the Unit Generator output into 5 structured Arabic subtopics (axes). "
        # "Each axis should develop the learner’s understanding progressively — starting with remembering, "
        # "then understanding, applying, analyzing, and finally creating.\n"
        "Each axis should represent a cognitive development stage — moving from foundational understanding to applied mastery.\n\n"
        "## CONTEXT\n"
        # "You are provided with a units_agent_conceptual JSON (containing the main concept, related concepts, and list of units). "
        "You are provided with a CurriculumStructure JSON (containing the main concept, related concepts, and list of units). "
        "Each unit includes a title and conceptual focus.\n\n"
        "## STEPS\n"
        "1. Read the CurriculumStructure carefully to understand the hierarchy and conceptual logic.\n"
        "2. For each unit:\n"
        "   - Identify its conceptual focus.\n"
        "   - Generate 5 progressive subtopics (axes) that unfold logically.\n"
        "   - Each axis must include:\n"
        "     • 'axis_number': numerical order from 1 to 5.\n"
        "     • 'title': Arabic title that feels like a subheading in a textbook.\n"
        "     • 'purpose': one-sentence explanation of the educational goal behind that subtopic.\n\n"
        "3. For each generated axis, verify conceptually that it can be expanded using available online educational content (articles, academic papers, or open textbooks).\n"
        "   - Prefer subtopics that are well-established in educational or academic literature.\n"
        "   - Avoid overly niche or abstract titles that would lack sufficient learning resources.\n\n"
        ## ADD
        "4. Validate that each axis:\n"
        "   - Aligns with Arabic educational title standards (clarity, focus, precision, and appropriateness).\n"
        "   - Avoids dual titles, poetic phrasing, or abstract metaphors.\n\n"
        "5. 📝 **Subtopics Title Quality & Language Validation**\n"
        "   - Each subtopic title is the learner’s first point of contact with the concept, so ensure the following:\n"
        "     ✅ Title length: concise (4–8 words preferred).\n"
        "     ✅ Clear and contextually linked to its unit or topic.\n"
        "     ✅ Written in tone appropriate for {audience}.\n"
        "     ✅ Avoids punctuation marks (– , ; : . ! ? , /) except for simple questions.\n"
        "     ✅ Represents one coherent idea — avoid compound or dual phrasing.\n"
        "     ✅ Avoids activity-based terms like 'ورشة عمل' or 'نشاط'.\n"
        "     ✅ Sounds realistic, teachable, and suitable for Arabic educational content.\n\n"
        "## NOTES\n"
        # "- Make sure the subtopics flow naturally, covering introduction, comprehension, practice, and innovation.\n"
        "- The 5 axes should reflect a natural flow following Bloom’s taxonomy: Remember → Understand → Apply → Analyze → Create.\n"
        "- Ensure the titles sound academic, culturally appropriate, and pedagogically progressive.\n"
        "- Return the result as a valid FullCurriculumStructure JSON containing all units with their axes."
    ),
    expected_output="A FullCurriculumStructure JSON object containing all units and their respective 5 axes each.",
    agent=axis_generator_agent,
    output_json=FullCurriculumStructure,
)