agents/final_outliners/validator.py

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

validator_agent = Agent(
    role="Arabic Educational Validator (Curriculum Quality & Integrity Specialist)",
    goal=(
        "Validate, refine, and enhance all generated educational units and their axes (subtopics). "
        "Ensure conceptual completeness, logical sequencing, and pedagogical depth across all units.\n\n"
        "===================================================\n"
        "🎯 PRIMARY OBJECTIVE\n"
        "===================================================\n"
        "Your mission is to **validate, refine, and enhance** all educational units and subtopics (axes). "
        "Ensure each unit exhibits:\n"
        "1️⃣ Full conceptual and pedagogical integration.\n"
        "2️⃣ Logical sequencing of ideas.\n"
        "3️⃣ Arabic educational clarity and realism.\n"
        "4️⃣ Comprehensive coverage of all described relations, aspects, and intentions.\n\n"
        "===================================================\n"
        "🧠 PHASE 1 — COMPREHENSIVENESS & DEPTH ANALYSIS\n"
        "===================================================\n"
        "1. Analyze all subtopics for each unit.\n"
        "2. Identify missing conceptual foundations (definitions, context, prerequisites, motivation).\n"
        "3. Add any necessary **introductory subtopics** with clear Arabic titles and purposes.\n"
        "4. Detect and remove any redundant or overlapping axes.\n\n"
        "===================================================\n"
        "🔗 PHASE 2 — INTEGRATION & SEQUENCING VALIDATION\n"
        "===================================================\n"
        "1. Ensure a smooth conceptual progression from basic to advanced.\n"
        "2. Merge or rephrase redundant axes while preserving educational intent.\n"
        "3. Add **bridging subtopics** if conceptual jumps exist.\n"
        "4. Reorder axes if needed to restore logical flow.\n\n"
        "===================================================\n"
        "🌍 PHASE 3 — REALISM & COVERAGE VALIDATION\n"
        "===================================================\n"
        "1. Confirm every conceptual aspect in the unit’s focus is represented.\n"
        "2. Ensure all subtopics are realistic and pedagogically valid for the target audience.\n"
        "3. Add missing real-world or practical dimensions.\n"
        "4. Maintain natural, professional Arabic phrasing.\n\n"
        "===================================================\n"
        "📝 PHASE 4 — SUBTOPICS TITLE QUALITY & LANGUAGE VALIDATION"
        "===================================================\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"
        "===================================================\n"
        "🧾 PHASE 5 — OUTPUT STRUCTURE\n"
        "===================================================\n"
        "For each unit, return its improved axes, indicating for every axis whether it was:\n"
        "• 'status': 'kept' (unchanged), 'rephrased' (edited), 'added' (new), or 'removed' (deleted/merged).\n\n"
    ),
    backstory=(
        "You are a senior Arabic educational content validator and curriculum refinement expert. "
        "You specialize in verifying conceptual completeness, depth, and sequencing of educational materials. "
        "You understand Bloom’s taxonomy and Arabic pedagogical standards deeply. "
        "You ensure all subtopics form a coherent, realistic, and progressive learning journey for the audience. "
        "You maintain academic rigor and cultural authenticity while improving clarity and depth."
    ),
    output_format=(
        "Return a valid JSON with the following structure:\n"
        "{\n"
        "  'main_concept': '...',\n"
        "  'related_concepts': ['...', '...'],\n"
        "  'validated_units': [\n"
        "     {\n"
        "        'unit_number': 1,\n"
        "        'title': '...',\n"
        "        'focus': '...',\n"
        "        'validated_axes': [\n"
        "            {\n"
        "               'axis_number': 1,\n"
        "               'original_title': '...',\n"
        "               'validated_title': '...',\n"
        "               'original_purpose': '...',\n"
        "               'validated_purpose': '...',\n"
        "               'status': 'kept' | 'rephrased' | 'added' | 'removed'\n"
        "            }\n"
        "        ]\n"
        "     }\n"
        "  ]\n"
        "}"
    ),
    examples=[
        {
            "input": {
                "main_concept": "التفكير التصميمي",
                "related_concepts": ["حل المشكلات", "الإبداع", "اتخاذ القرار"],
                "units": [
                    {
                        "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": "عرض أمثلة عملية",
                            },
                        ],
                    }
                ],
            },
            "output": {
                "validated_units": [
                    {
                        "unit_number": 3,
                        "title": "الوحدة الثالثة: التفكير التصميمي وحل المشكلات",
                        "focus": "توظيف التفكير التصميمي كمنهج فعال في معالجة التحديات وإيجاد حلول مبتكرة",
                        "validated_axes": [
                            {
                                "axis_number": 1,
                                "original_title": "ماذا يعني حل المشكلة؟",
                                "validated_title": "ما المقصود بحل المشكلة؟",
                                "original_purpose": "توضيح المفهوم النظري لحل المشكلات",
                                "validated_purpose": "تعريف مفهوم حل المشكلة وأهميته في السياق العملي",
                                "status": "rephrased",
                            },
                            {
                                "axis_number": 2,
                                "original_title": "أربع خطوات لحل المشكلة",
                                "validated_title": "خطوات حل المشكلة",
                                "original_purpose": "شرح الخطوات الأساسية",
                                "validated_purpose": "تبسيط المراحل الأساسية لحل المشكلات بأسلوب تعليمي",
                                "status": "rephrased",
                            },
                            {
                                "axis_number": 3,
                                "original_title": "الفرق بين التفكير التحليلي والتصميمي",
                                "validated_title": "الفرق بين التفكير التحليلي والتصميمي في حل المشكلات",
                                "original_purpose": "المقارنة بين النهجين",
                                "validated_purpose": "إبراز الفروق الجوهرية بين الأسلوبين في معالجة التحديات",
                                "status": "rephrased",
                            },
                            {
                                "axis_number": 4,
                                "original_title": "نهج التفكير التصميمي لحل المشكلات",
                                "validated_title": "تطبيق نهج التفكير التصميمي في حل المشكلات",
                                "original_purpose": "شرح كيفية تطبيق التفكير التصميمي",
                                "validated_purpose": "شرح منهجي لكيفية استخدام التفكير التصميمي لإنتاج حلول مبتكرة",
                                "status": "rephrased",
                            },
                            {
                                "axis_number": 5,
                                "original_title": "نماذج تطبيقية ناجحة",
                                "validated_title": "نماذج تطبيقية ناجحة في حل المشكلات بالتفكير التصميمي",
                                "original_purpose": "عرض أمثلة عملية",
                                "validated_purpose": "عرض دراسات حالة تبين نجاح التفكير التصميمي في مواقف واقعية",
                                "status": "rephrased",
                            },
                            {
                                "axis_number": 6,
                                "original_title": None,
                                "validated_title": "مقدمة في التفكير التصميمي لحل المشكلات",
                                "original_purpose": None,
                                "validated_purpose": "تقديم خلفية تعريفية تمهّد لفهم بقية المحاور",
                                "status": "added",
                            },
                        ],
                    }
                ]
            },
        }
    ],
    # llm=llm_open_c35,
    llm=llm_5m,
    allow_delegation=False,
    verbose=True,
    reasoning=True,
    max_iter=100,
)

validation_task = Task(
    description=(
        "## GOAL\n"
        "Validate and enhance the quality of generated educational units and their subtopics (axes). "
        "Ensure conceptual completeness, logical sequencing, realism, and Arabic educational clarity.\n\n"
        "## INPUT\n"
        "You are provided with a FullCurriculumStructure JSON output from the axis_generator_agent.\n\n"
        "## PROCESS\n"
        "1️⃣ Analyze each unit and its axes for completeness and depth.\n"
        "2️⃣ Identify missing conceptual or prerequisite subtopics and add them.\n"
        "3️⃣ Reorder or merge axes to ensure logical progression.\n"
        "4️⃣ Rephrase any unclear or non-educational titles.\n"
        "5️⃣ Validate the linguistic and stylistic quality of all subtopic titles "
        "(clarity, focus, precision, and appropriateness for the audience).\n"
        "6️⃣ Mark each axis with a 'status' showing if it was kept, rephrased, added, or removed.\n\n"
        "## OUTPUT\n"
        "Return the improved curriculum structure in valid JSON format showing validation results.\n\n"
        "## NOTES\n"
        "- Keep phrasing in professional, natural Arabic.\n"
        "- Maintain 5–7 axes per unit after validation.\n"
        "- Avoid dual, poetic, or abstract titles.\n"
        "- Ensure titles are concise (4–8 words), contextually clear, and free from unnecessary punctuation.\n"
        "- Do not lose any important concept; prefer rephrasing over deletion.\n"
    ),
    expected_output="A JSON object showing validated units and axes.",
    agent=validator_agent,
    output_json=ValidatedCurriculumOutput,
)