v3 initial

.gitignore

@@ -0,0 +1,6 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+modules\firebase_credentials.json
+test*

Dockerfile

@@ -0,0 +1,21 @@
+# استخدم صورة أساسية خفيفة من Python
+FROM python:3.10
+
+# اضبط مجلد العمل داخل الحاوية
+WORKDIR /app
+
+# انسخ ملفات المشروع
+COPY . /app
+
+# انسخ ملف requirements لو عندك
+COPY requirements.txt .
+
+# نزّل المتطلبات
+RUN pip install --no-cache-dir -r requirements.txt
+
+
+# عرّف البورت اللي البرنامج هيشتغل عليه
+EXPOSE 7860
+
+# لو بتستخدم FastAPI (مع uvicorn):
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,10 @@
+---
+title: ContiAI-v3
+emoji: 🐨
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: apache-2.0
+app_port: 7860
+---

agents/analysis_phase/Introduction.py

@@ -0,0 +1,111 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm_g
+from schemas import IntroductionOutput
+
+intro_agent = Agent(
+    role="Human-Crafted Arabic Introduction Writer",
+    goal=(
+        "Create a deeply human, stylistically rich, emotionally resonant Arabic introduction "
+        "for a training program based on the provided topic ({topic}), outlines, units, and outcomes. "
+        "The introduction must feel alive, credible, realistic, and engaging—not artificial or generic."
+    ),
+    backstory=(
+        "You are a master Arabic writer and educational content designer. "
+        "You craft introductions that carry a human breath—mixing scene, reflection, emotion, "
+        "and intellectual depth without artificial phrases. "
+        "Your style avoids AI clichés and empty rhetoric, relying instead on concrete imagery, "
+        "varied rhythm, personal tone, and subtle storytelling. "
+        "You write for {audience} with professionalism, depth, and authenticity."
+    ),
+    system_template=(
+        "أنت كاتب عربي محترف تمتد خبرته إلى تصميم مقدمات تدريبية آسرة تعتمد على الصورة "
+        "الحسية، والتجربة الواقعية، والنبرة الشخصية الصادقة. كتابتك تشبه النصوص البشرية القوية "
+        "وليست مصطنعة أو آلية.\n\n"
+        "==============================\n"
+        "## قواعد الكتابة الإنسانية (ANTI-AI RULES)\n"
+        "==============================\n"
+        "يجب على المقدمة أن:\n"
+        "- تكون بين 250 و 320 كلمة.\n"
+        "- تتجنب تمامًا: هل تساءلت يومًا، ليس مجرد… بل…، في عالمنا المتسارع، رحلة متكاملة، إحداث فرق حقيقي.\n"
+        "- تتجنب الأسلوب الإنشائي الدعائي واللغة البراقة الفارغة.\n"
+        "- تحتوي على جُمل قصيرة وأخرى طويلة (تنويع الإيقاع).\n"
+        "- تتضمن لقطة أو مشهدًا واقعيًا مرتبطًا بالموضوع (مشهد صف، موقف واقعي، صورة حسيّة واضحة).\n"
+        "- تحمل لمسة شخصية: دهشة، ملاحظة، موقف شعوري، رأي بسيط.\n"
+        "- تستخدم انتقالات طبيعية نابعة من الفكرة نفسها، لا من الروابط الميكانيكية مثل: بعد ذلك، لن يكتمل، سننتقل.\n"
+        "- تستخدم لغة عربية قوية وواضحة، بلا مبالغة، بلا زخرفة، بلا تكرار.\n"
+        "- تعرض مشكلة حقيقية أو تحديًا واقعيًا يتعلق بالموضوع.\n"
+        "- تبتعد عن العموميات والعبارات المستهلكة.\n\n"
+        "==============================\n"
+        "## أساليب افتتاح مسموح بها\n"
+        "==============================\n"
+        "يمكنك البدء بـ:\n"
+        "- مشهد قصير واقعي.\n"
+        "- سطر من تجربة إنسانية.\n"
+        "- تساؤل تأملي صادق (غير إنشائي).\n"
+        "- حقيقة أو رقم لها علاقة مباشرة بالموضوع.\n"
+        "- حكمة أو قول مناسب لكن غير مستهلك.\n\n"
+        "==============================\n"
+        "## البنية المرنة للمقدمة\n"
+        "==============================\n"
+        "1. افتتاح مشهدي أو واقعي أو تأملي.\n"
+        "2. ربط المشهد بطبيعة موضوع التدريب.\n"
+        "3. عرض المشكلة أو التحدي الحقيقي الذي يعالجه البرنامج.\n"
+        "4. توضيح قيمة الموضوع والفائدة بأسلوب ملموس لا إنشائي.\n"
+        "5. وعد تعليمي مشتق من المخرجات لكن بلغة إنسانية طبيعية.\n\n"
+        "==============================\n"
+        "## تعليمات إضافية لضمان الأسلوب البشري\n"
+        "==============================\n"
+        "- استخدم صورًا حسية: صوت، ضوء، حركة، مشهد، شعور.\n"
+        "- لا تجعل الجمل كلها بنفس الإيقاع أو الطول.\n"
+        "- لا تبدأ بأسئلة رنانة بلا معنى.\n"
+        "- تجنب الترتيب النمطي للجمل الذي ينتجه الذكاء الاصطناعي.\n"
+        "- قدم فائدة أو ملاحظة شخصية حقيقية.\n"
+        "- اربط الكلمات بالموقف وليس بالقوالب.\n\n"
+    ),
+    llm=llm_g,
+    memory=False,
+    allow_delegation=False,
+    verbose=True,
+    max_iter=50,
+    cache=False,
+)
+
+intro_task = Task(
+    description=(
+        "Write a human-like Arabic introduction (300–400 words) that reflects true human rhythm, "
+        "## INPUT\n"
+        "You have access to the program’s full context:\n"
+        "- Topic: {topic}\n"
+        "- Outline (units and subtopics): {outlines}\n"
+        "- Unit details: {units}\n"
+        "- Learning outcomes: {outcomes}\n\n"
+        "## OBJECTIVE\n"
+        "Write an Arabic introduction that connects the learner emotionally and intellectually to the training content. "
+        "The introduction must:\n"
+        "- Reflect the program’s educational goals and outcomes.\n"
+        "- Be motivational, concise, and linguistically natural for {audience}.\n"
+        "## MUST INCLUDE:\n"
+        "• نبرة شخصية.\n"
+        "• لغة خالية من الإنشاء المكرر والعبارات المستهلكة.\n"
+        "• تنويع طول الجمل.\n"
+        "• انتقالات طبيعية.\n\n"
+        "## MUST AVOID:\n"
+        "• الأسئلة الافتتاحية المعلبة.\n"
+        "• الإنشاء الفارغ.\n"
+        "• الإفراط في الجمل الطويلة.\n"
+        "• العبارات التسويقية.\n"
+        "• الكلمات اللامعة الخاوية.\n\n"
+        "### OUTPUT\n"
+        "Return the IntroductionOutput structure in valid JSON format.\n\n"
+    ),
+    expected_output="""JSON object with this structure:
+    {
+    "introduction": "engaging introduction to the training program content, max 300 words."
+    }
+    """,
+    output_json=IntroductionOutput,
+    agent=intro_agent,
+    human_input=False,
+)

agents/analysis_phase/__init__.py

@@ -0,0 +1,10 @@
+from .analysis_report import report_agent, report_task
+from .analysis import analysis_agent, analysis_task
+from .objectives import (
+    objectives_generator,
+    objectives_task,
+    get_bloom_verb,
+)
+from .outcomes import outcomes_generator, outcomes_task
+from .outliner import outline_agent, outline_task
+from .Introduction import intro_agent, intro_task

agents/analysis_phase/analysis.py

@@ -0,0 +1,99 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+from schemas import AnalysisOutput
+
+analysis_agent = Agent(
+    role="Training Analysis Agent",
+    goal="\n".join(
+        [
+            "Generate the analysis phase for the training program in Arabic based on the topic, outline, and training outcomes.",
+            "Follow the DNA methodology defined in the Outline Agent.",
+            "and follow the DNA parameters ({domain}, {content_type}, {audience}, {material_type}).",
+            "The analysis must include the following elements (taken from the official analysis framework):",
+            "",
+            "1. Goal:",
+            "- Overall goal expected after the training program.",
+            "- Must start with: 'أن يتمكّن المتدرب من ...'.",
+            "- Should be a complete sentence covering all training topics.",
+            "- Must be comprehensive, not limited to one aspect.",
+            "",
+            "2. Target Audience:",
+            "- The group receiving the training.",
+            "- Include average age (e.g., شباب في العشرينات، موظفون في الثلاثينات).",
+            "",
+            "3. Previous Experiences:",
+            "- Short sentences written as noun-phrases (مصادر).",
+            "- Express prior practical or knowledge-based experiences.",
+            "- Examples: ممارسة أنشطة جماعية، مواجهة ضغوط العمل، استخدام أدوات تنظيم، الالتزام بجداول، إدارة مهام يومية.",
+            "",
+            "4. Learner Characteristics:",
+            "- Common traits considering age and developmental aspects:",
+            "  * Linguistic development: improving oral expression and listening.",
+            "  * Cognitive development: analyzing and linking concepts, applying analytical skills.",
+            "  * Social development: tendency to interact and collaborate.",
+            "  * Emotional development: reacting to emotional situations.",
+            "  * Personality growth: building independent identity and attitudes.",
+            "  * Learning styles: preference for practical, auditory, or visual learning.",
+            "",
+            "5. Training Needs:",
+            "- Represent what the learner needs in skills, knowledge, and behaviors.",
+            "- Must be extracted from the training topics.",
+            "- 6 sentences required, each a noun-phrase.",
+            "- Each starts with a مصدر (e.g., فهم، إدراك، توظيف، استيعاب).",
+            "- Must not be copied titles but rephrased needs.",
+            "",
+            "6. Constraints:",
+            "- Barriers that may negatively affect training.",
+            "- Two types:",
+            "  * Trainer constraints (4 sentences):Examples: (e.g.,ضيق الوقت، محدودية الوسائل التعليمية، تباين مستويات المتدربين، قلة الدعم الإداري.).",
+            "  * Trainee constraints (4 sentences): Examples:(e.g.,ضعف الالتزام، ضعف الحافز، انشغالات شخصية، قلة الخبرة التقنية.).",
+            "- All sentences must start with a مصدر (محدودية، ضعف، صعوبة، تباين).",
+            "- Written as complete noun-phrases only.",
+            "",
+            "7. Duration:",
+            "- Exact training duration (hours/days).",
+            "- Training day = 4 hours.",
+            "- Examples: دورة يوم واحد = 4 ساعات، دورتان = 8 ساعات.",
+            "",
+            "8. Sources of Analysis:",
+            "- Pre-training instructional design processes.",
+            "- Examples: البحث عن مصادر علمية، تحليل احتياجات المتدربين، دراسة محاور الدورة، تحديد الفجوات بين الواقع والمأمول، تجميع البيانات.",
+            "- Must be written as noun-phrases starting and ending with a مصدر (e.g., جمع البيانات وتحليلها).",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "This agent acts as an instructional designer responsible for producing the full analysis phase.",
+            "It ensures outputs are consistent with the Arabic training framework (مرحلة التحليل).",
+            "It builds on the Outline and Training Outcomes, while following DNA methodology and ollow the DNA parameters (domain, content_type, audience, material_type).",
+        ]
+    ),
+    llm=llm,
+    verbose=True,
+)
+
+# ====== Task ======
+analysis_task = Task(
+    description="\n".join(
+        [
+            "Generate the complete analysis phase in Arabic for the training program.",
+            "Use the outline (main_headings + sub_headings + sub_sub_headings) and training outcomes as input.",
+            "Follow the analysis framework:",
+            "- Goal",
+            "- Target Audience",
+            "- Previous Experiences",
+            "- Learner Characteristics",
+            "- Training Needs",
+            "- Constraints",
+            "- Duration",
+            "- Sources of Analysis",
+            "Ensure all outputs are written in Arabic, concise, and aligned with DNA methodology.",
+            "Output must strictly match the Pydantic schema (AnalysisOutput) and be in JSON format.",
+        ]
+    ),
+    expected_output="A JSON object in Arabic with all required analysis fields.",
+    output_json=AnalysisOutput,
+    agent=analysis_agent,
+)

agents/analysis_phase/analysis_report.py

@@ -0,0 +1,61 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+
+# ====== Agent ======
+report_agent = Agent(
+    role="Training Report Builder",
+    goal="\n".join(
+        [
+            "Take the outputs from title_agent, outline_agent, training_agent, and analysis_agent.",
+            "Generate a well-structured HTML report in Arabic.",
+            "",
+            "Rules:",
+            "- At the very top of the page, display the title from title_agent output as a main heading (<h1>).",
+            "- The training_agent introduction should appear under a section titled: 'المقدمة'.",
+            "- The outline_agent output should appear under a section titled: 'محتويات الحقيبة'.",
+            "- The training_agent learning outcomes should appear under a section titled: 'مخرجات البرنامج التدريبي'.",
+            "- The analysis_agent output should appear under a section titled: 'مرحلة التحليل'.",
+            "",
+            "For the 'مرحلة التحليل' section:",
+            "- Present it inside an HTML table.",
+            "- The table should have two columns: 'العنصر' and 'الوصف'.",
+            "- Each row corresponds to one analysis element (الهدف، الفئة المستهدفة، الخبرات السابقة، خصائص المتدربين، الاحتياجات التدريبية، القيود، المدة الزمنية، مصادر التحليل).",
+            "",
+            "The final HTML page should be clean and well-structured with Arabic titles and proper formatting.",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "This agent acts as a report generator.",
+            "It combines all outputs (title, outline, training outcomes, analysis) into one structured HTML training portfolio.",
+        ]
+    ),
+    llm=llm,
+    verbose=True,
+)
+
+# ====== Task ======
+report_task = Task(
+    description="\n".join(
+        [
+            "Build an HTML page combining all outputs:",
+            "- At the top of the page, show the title (from title_agent output) as <h1>.",
+            "- Section 1: 'المقدمة' → from training_agent output (introduction).",
+            "- Section 2: 'محتويات الحقيبة' → from outline_agent output.",
+            "- Section 3: 'مخرجات البرنامج التدريبي' → from training_agent output (learning outcomes as a bulleted list).",
+            "- Section 4: 'مرحلة التحليل' → from analysis_agent output.",
+            "   - The analysis section must be presented inside an HTML table same as this template {html_template}.",
+            "use css style to enhance the design more and the table responsive.",
+            "Care about colors, headers, and fonts.",
+            "don't change the style of analysis table",
+            "   - The table should have two columns: 'العنصر' and 'الوصف'.",
+            "   - Each row corresponds to one analysis element (goal, target audience, previous experiences, learner characteristics, training needs, constraints, duration, sources of analysis).",
+            "",
+            "Ensure the HTML page is clean, well-structured, and properly formatted in Arabic.",
+        ]
+    ),
+    expected_output="A single HTML string with a title, three sections, and a table for the analysis section. and don't put the code in html``` ```",
+    agent=report_agent,
+)

agents/analysis_phase/objectives.py

@@ -0,0 +1,287 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import bloom_taxonomy_2, objectives_dimensions, llm_g
+from schemas import LearningObjectivesOutput
+
+
+def get_bloom_verb(level: str) -> str:
+    """Returns verbs from the given Bloom's taxonomy level."""
+
+    if level not in bloom_taxonomy_2:
+        raise ValueError(f"Invalid Bloom level: {level}")
+    verbs_key = [k for k in bloom_taxonomy_2[level].keys() if "_verbs_examples" in k][0]
+    return bloom_taxonomy_2[level][verbs_key]
+
+
+def get_verbs_by_domain_and_level(domain, level_name):
+    """
+    استخراج الأفعال المناسبة من قاموس الأبعاد التعليمية
+
+    Args:
+        domain: "Knowledge", "Ability", or "Skills"
+        level_name: اسم المستوى مثل "Remember", "Response", "Practice"
+
+    Returns:
+        قائمة بالأفعال المتاحة
+    """
+    if domain not in objectives_dimensions:
+        return []
+
+    for level in objectives_dimensions[domain]["levels"]:
+        if level_name.lower() in level["level_name"].lower():
+            return level["verbs_examples"]
+
+    return []
+
+
+objectives_generator = Agent(
+    role="Expert Learning Objectives Designer (Instructional Design Specialist)",
+    goal=(
+        "Design a comprehensive list of clear, measurable, and achievable learning objectives in Arabic "
+        "for each subtopic in the training curriculum. Your objectives must be based on {topic} and the "
+        "content provided in {outlines}. "
+        "You must carefully read and analyze every subtopic title, its purpose, and the unit description "
+        "before writing any objective. "
+        "Each objective must align with Bloom’s Taxonomy and the three learning domains "
+        "(cognitive, affective, psychomotor), accurately reflect the intended learning outcome, "
+        "and meet all 12 professional instructional design standards. "
+        "**Critical:** You must maximize verb diversity across all objectives — avoid repeating the same "
+        "verb whenever possible."
+    ),
+    # system_template="",
+    backstory=(
+        "You are an expert instructional designer with deep experience in creating professional training programs. "
+        "You analyze each unit and subtopic to determine the type of knowledge, skill, or attitude learners "
+        "should achieve. "
+        "Then, you write one short, measurable, learner-centered objective for each subtopic following Bloom’s "
+        "Taxonomy sequence (Remember → Understand → Apply → Analyze → Evaluate → Create). "
+        "**You are exceptionally skilled at selecting diverse and non-repetitive verbs from Bloom’s Taxonomy "
+        "and the three learning domains.** "
+        "You maintain a mental tracker of all verbs used and actively avoid repetition across the entire curriculum. "
+        "You ensure maximum verb diversity, linguistic precision, and that every objective is "
+        "clear, measurable, realistic, achievable, and free from ambiguity or linguistic complexity. "
+        "Your objectives must reflect the parameters of {domain}, {content_type}, {audience}, and {material_type}, "
+        "while covering the cognitive, psychomotor, and affective domains."
+    ),
+    llm=llm_g,
+    verbose=True,
+    max_iter=100,
+)
+
+
+objectives_task = Task(
+    description=(
+        "You have a complete and well-structured training curriculum provided in outlines: {outlines} and units details: {units}. "
+        "Your task is to create one detailed, measurable learning objective in Arabic for each subtopic, "
+        "aligned with Bloom’s Taxonomy and the three learning domains, and consistent with the purpose of each subtopic.\n\n"
+        "### Step-by-Step Process\n"
+        "1. Read the curriculum overview to understand the full learning journey.\n"
+        "2. **Before you begin, review the complete list of Bloom’s action verbs and the three domains for each level to plan maximum diversity.**\n"
+        "3. **Create a mental or written record of verbs as you use them to avoid repetition.**\n"
+        "4. For each unit:\n"
+        "   a. Analyze the unit description to understand the learning scope and intended outcomes.\n"
+        "   b. For each subtopic within that unit:\n"
+        "      - Carefully read the subtopic title and its purpose.\n"
+        "      - Identify the main learning outcome (Knowledge, Skill, or Attitude/Behavior).\n"
+        "      - **First, determine the appropriate domain: Cognitive (Knowledge), Affective (Attitude), or Psychomotor (Skills).**\n"
+        "      - Choose the most suitable Bloom’s level or the appropriate level of that domain.\n"
+        "      - **From the available verbs at that level, select one that has not been used before (or only minimally used).**\n"
+        "      - Choose three relevant Bloom’s verbs that suit the abilities of {audience}.\n"
+        "      - Write one measurable learning objective in Arabic that accurately reflects the subtopic’s purpose.\n"
+        "      - **Track the chosen verb to prevent reusing it in later objectives.**\n\n"
+        "### Requirements for the Three Learning Domains\n"
+        "**Objectives must cover the three domains in a balanced way:**\n\n"
+        f"**1. Cognitive Domain (Knowledge):**\n"
+        f"{objectives_dimensions['Knowledge']['description']}\n"
+        "**Levels:**\n"
+        + "\n".join(
+            [
+                f"   - {level['level_name']}: {level['description']}\n     Verbs: {', '.join(level['verbs_examples'])}"
+                for level in objectives_dimensions["Knowledge"]["levels"]
+            ]
+        )
+        + "\n\n"
+        f"**2. Affective Domain (Attitude/Ability):**\n"
+        f"{objectives_dimensions['Ability']['description']}\n"
+        "**Levels:**\n"
+        + "\n".join(
+            [
+                f"   - {level['level_name']}: {level['description']}\n     Verbs: {', '.join(level['verbs_examples'])}"
+                for level in objectives_dimensions["Ability"]["levels"]
+            ]
+        )
+        + "\n\n"
+        f"**3. Psychomotor Domain (Skills):**\n"
+        f"{objectives_dimensions['Skills']['description']}\n"
+        "**Levels:**\n"
+        + "\n".join(
+            [
+                f"   - {level['level_name']}: {level['description']}\n     Verbs: {', '.join(level['verbs_examples'])}"
+                for level in objectives_dimensions["Skills"]["levels"]
+            ]
+        )
+        + "\n\n"
+        "### Critical Requirement: Verb Diversity \n"
+        "**This is a top-priority rule that must be followed precisely:**\n\n"
+        "**Verb Non-Repetition Rules:**\n"
+        "1. **Maximize verb diversity** — each objective should ideally use a different verb than all previous ones.\n"
+        "2. **Before selecting a verb, check:** Have I used this verb before? If yes, choose another.\n"
+        "3. **Repeat a verb only when:**\n"
+        "   - All suitable alternative verbs in that Bloom level or domain are exhausted.\n"
+        "   - The subtopic’s content explicitly requires that verb for accuracy.\n"
+        "   - You can justify why no other verb fits.\n"
+        "4. **Prioritize diversity over perfect synonyms** — it’s better to use a slightly different but valid verb than to repeat.\n"
+        "5. **Use the full range of verbs from Bloom and the three domains** — avoid overusing common ones like 'define' or 'explain'.\n"
+        "6. **Track verb usage:** after writing each objective, note the verb and consciously avoid it in the next.\n"
+        "7. **If repetition is necessary:**\n"
+        "   - Space it out by at least 3–5 objectives.\n"
+        "   - Add a justification note in your internal reasoning.\n"
+        "   - Try using it in a different context or content area.\n\n"
+        "### The 12 Mandatory Design Standards — Each Objective Must Meet All\n"
+        "**Based on the detailed objectives reference document:**\n\n"
+        "1. **Linked to the general goal:**\n"
+        "   - Every objective must connect to the course’s overall goal.\n"
+        "   - Example: If the general goal is 'Understand the concept of e-learning', "
+        "the specific objective could be 'The trainee accurately defines e-learning.'\n\n"
+        "2. **Measurable:**\n"
+        "   - Objectives must be assessable using measurable performance indicators or outcomes.\n"
+        "   - Correct: 'The trainee compares synchronous and asynchronous learning accurately.'\n"
+        "   - Incorrect: 'The trainee understands e-learning.' (Not measurable)\n\n"
+        "3. **Achievable:**\n"
+        "   - Realistic, suitable for learner ability and course duration.\n"
+        "   - Correct: 'The trainee applies the steps to create a learning management account.'\n"
+        "   - Incorrect: 'The trainee develops a full e-learning system in one hour.' (Unrealistic)\n\n"
+        "4. **Covers all three domains (Cognitive, Psychomotor, Affective):**\n"
+        "   - Cognitive: 'The trainee defines e-learning accurately.'\n"
+        "   - Psychomotor: 'The trainee practices using LMS assessment tools.'\n"
+        "   - Affective: 'The trainee demonstrates interest in participating in e-learning activities.'\n\n"
+        "5. **Aligned with Bloom’s hierarchy:**\n"
+        "   - Objectives must progress logically from lower to higher levels (Remember → Create).\n\n"
+        "6. **Clarity and precision:** Objective must be completely clear and specific.\n\n"
+        "7. **Free from ambiguity:** No vague or overly complex phrasing.\n\n"
+        "8. **Vocabulary clarity:** All terms must be understandable to {audience}.\n\n"
+        "9. **Single, focused goal:** Each objective expresses only one learning outcome.\n"
+        "   - Correct: 'The trainee identifies the components of a virtual classroom.'\n"
+        "   - Incorrect: 'The trainee identifies and applies virtual classroom components.'\n\n"
+        "10. **Realistic and feasible:** Achievable within program time and resources.\n\n"
+        "11. **Consistent with program outcomes:** Must align with the general and specific learning outcomes.\n\n"
+        "12. **Content-linked:** Directly related to the unit or module content.\n\n"
+        "### Objective Writing Rules\n"
+        "- One objective per subtopic — no more, no less.\n"
+        "- Each must directly and precisely reflect the subtopic’s purpose.\n"
+        "- Follow Bloom’s sequence within each unit (from lower to higher order thinking).\n"
+        "- If a level doesn’t logically fit, skip it but maintain general progression.\n"
+        "- You may combine two levels (e.g., Understand + Apply) if justified by subtopic purpose.\n"
+        "- Start each objective with '[verb in present]' and keep length between 6–10 words.\n"
+        "- Use verbs suitable for {audience} — e.g., children cannot 'evaluate' or 'analyze' like professionals.\n"
+        "- **Core rule: Avoid verb repetition — use the widest possible range from all three domains.**\n"
+        "- Ensure objectives are **measurable** and **achievable**.\n"
+        "- Maintain linguistic clarity — no vague or double meanings.\n"
+        "- Each objective must express only one precise learning outcome.\n\n"
+        "### Strategies for Verb Diversity\n"
+        "**Use these strategies to ensure maximum variety:**\n\n"
+        "- **Alternate synonyms:**\n"
+        "  - Instead of always 'define', use: name, list, mention, identify, classify, select.\n"
+        "- **Use less common verbs:**\n"
+        "  - Distinguish, infer, demonstrate, interpret, justify, summarize, illustrate.\n"
+        "- **Match verbs to content type:**\n"
+        "  - Use verbs that capture the learning result precisely.\n"
+        "- **Consult the full domain verb lists** (above) with 5–7 verbs per level.\n"
+        "- **Distribute objectives across the three domains** — avoid focusing only on the cognitive domain.\n\n"
+        "### Examples of Correct and Incorrect Objectives\n\n"
+        "**Correct Examples (Good verb diversity and domain balance):**\n"
+        "1. (Cognitive - Remember): The trainee lists five types of e-learning platforms.\n"
+        "2. (Cognitive - Understand): The trainee distinguishes between various digital assessment tools.\n"
+        "3. (Cognitive - Apply): The trainee applies active learning strategies in the classroom.\n"
+        "4. (Cognitive - Understand): The trainee infers the main benefits of blended learning.\n"
+        "5. (Psychomotor - Practice): The trainee practices designing an interactive learning activity.\n"
+        "6. (Affective - Respond): The trainee actively participates in collaborative learning discussions.\n"
+        "7. (Cognitive - Analyze): The trainee compares different instructional design models.\n"
+        "8. (Psychomotor - Adapt): The trainee adjusts learning activities to meet learner needs.\n\n"
+        "**Incorrect Examples (Verb repetition — avoid this):**\n"
+        "1. The trainee defines the types of e-learning platforms.\n"
+        "2. The trainee defines digital assessment tools.\n"
+        "3. The trainee defines active learning strategies.\n"
+        "4. The trainee defines blended learning benefits.\n"
+        "5. The trainee defines steps of activity design.\n\n"
+        "**Unclear or Unmeasurable Objectives:**\n"
+        "- 'The trainee understands e-learning.' (Vague, not measurable)\n"
+        "- 'The trainee learns how to use tools.' (Unclear — which tools?)\n"
+        "- 'The trainee becomes an expert in instructional design.' (Unrealistic, not measurable)\n\n"
+        "**Improved Versions:**\n"
+        "- 'The trainee accurately defines e-learning.'\n"
+        "- 'The trainee effectively uses LMS tools.'\n"
+        "- 'The trainee applies instructional design principles to create a learning unit.'\n\n"
+        "### Critical Quality Checklist — Verify Before Finalizing Each Objective:\n"
+        "1. ✓ Is it clear and accurately expresses the intended outcome?\n"
+        "2. ✓ Does it align with a Bloom’s level or learning domain?\n"
+        "3. ✓ Is it free from ambiguity?\n"
+        "4. ✓ Is all vocabulary appropriate for {audience}?\n"
+        "5. ✓ Does it express only one learning outcome?\n"
+        "6. ✓ Is it measurable through observable performance?\n"
+        "7. ✓ Is it realistic and achievable?\n"
+        "8. ✓ Does it align with the overall outcomes?\n"
+        "9. ✓ Is it directly linked to the subtopic content?\n"
+        "10. ✓ Is it sequenced logically (simple → complex)?\n"
+        "11. ✓ Is it suitable for the learners’ level?\n"
+        "12. ✓ Do all objectives collectively cover knowledge, skills, and attitudes?\n"
+        "**13. Verb Check: Have you reused this verb? If yes, can you replace it?**\n"
+        "**14. Domain Check: Are the objectives balanced across all three domains?**\n\n"
+        "### Self-Reflection Requirement\n"
+        "After generating all objectives for a unit, pause and evaluate:\n"
+        "- Do objectives progress logically through Bloom’s levels?\n"
+        "- **How many unique verbs did you use? Any repetition?**\n"
+        "- **Can any repeated verbs be replaced with alternatives?**\n"
+        "- Are verbs diverse and contextually appropriate?\n"
+        "- **Do objectives cover all three domains evenly?**\n"
+        "- Can an external evaluator assess each objective clearly?\n"
+        "- Are all objectives realistic for {audience} and course duration?\n\n"
+        "### Final Verification: Verb Diversity & Domain Balance\n"
+        "**Before submitting your final output:**\n"
+        "1. Count how many times each verb appears.\n"
+        "2. If any verb appears more than 2–3 times, review and replace it where possible.\n"
+        "3. Aim for at least 70–80% unique verbs across the entire curriculum.\n"
+        "4. Keep a mental record of verb use for ongoing awareness.\n"
+        "5. **Check balanced distribution:**\n"
+        "   - Cognitive (Knowledge): 50–60% of objectives\n"
+        "   - Affective (Attitude): 20–30% of objectives\n"
+        "   - Psychomotor (Skills): 20–30% of objectives\n"
+        "6. If imbalance occurs, revisit and adjust classifications.\n\n"
+        "### Domain-Specific Guidelines\n\n"
+        "**When writing Cognitive (Knowledge) objectives:**\n"
+        "- Use for topics focused on information, understanding, applying, analyzing, evaluating, or creating.\n"
+        "- Examples: 'The trainee defines...', 'The trainee compares...', 'The trainee designs...'.\n\n"
+        "**When writing Affective (Attitude) objectives:**\n"
+        "- Use for topics involving values, emotions, interests, or behaviors.\n"
+        "- Examples: 'The trainee demonstrates interest in...', 'The trainee participates actively...', 'The trainee commits to...'.\n\n"
+        "**When writing Psychomotor (Skills) objectives:**\n"
+        "- Use for topics requiring physical, technical, or procedural performance.\n"
+        "- Examples: 'The trainee practices...', 'The trainee performs...', 'The trainee innovates...'.\n\n"
+        "### Final Important Notes\n"
+        "- **Top Priority:** Verb diversity and balanced domain distribution.\n"
+        "- **Quality over quantity:** One well-crafted, diverse objective is better than several repetitive ones.\n"
+        "- **Flexibility with precision:** Be flexible in verb choice but never compromise on accuracy.\n"
+        "- **Continuous review:** Revisit objectives regularly for diversity and balance.\n"
+        "- **Context matters:** Always choose the verb that best reflects what the learner should achieve in that specific subtopic.\n"
+        "### OUTPUT\n"
+        "Return the LearningObjectivesOutput structure in valid JSON format.\n\n"
+    ),
+    expected_output="""JSON object with this structure:
+    {
+      "objectives": [
+        {
+          "unit": "Unit title",
+          "unit_description": "Brief summary of the unit scope",
+          "subtopic": "subtopic title",
+          "module_description": "Brief summary of what this subtopic covers",
+          "level": "Bloom's level assigned based on subtopic analysis",
+          "verbs": ["verb1", "verb2", "verb3"],
+          "objective": "One measurable Arabic objective"
+        }
+      ]
+    }""",
+    output_json=LearningObjectivesOutput,
+    agent=objectives_generator,
+    human_input=False,
+)

agents/analysis_phase/outcomes.py

@@ -0,0 +1,305 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm_g
+from schemas import LearningOutcomesOutput
+
+outcomes_generator = Agent(
+    role="Expert DNA-Based Learning Outcomes Designer",
+    goal="\n".join(
+        [
+            "Design a comprehensive list of high-quality Arabic learning outcomes for a training program based on the learning objectives provided.",
+            "Each outcome must be measurable, aligned with Bloom's taxonomy, and crafted using the DNA methodology.",
+            "",
+            "### CRITICAL RULES FOR OUTCOMES:",
+            "",
+            "**1. LINGUISTIC STRUCTURE:**",
+            "   - Outcomes MUST be phrased as infinitive nouns (مصادر) such as: فهم، إدراك، تطبيق، تحليل، تقييم، تصميم.",
+            "   - Use the verbal noun form (المصدر) not the verb itself.",
+            "   - Structure: [مصدر] + [المحتوى/الموضوع] + [السياق إن وُجد]",
+            "   - Example: 'فهم مبادئ التعليم الإلكتروني' NOT 'أن يفهم المتدرب...'",
+            "",
+            "**2. BLOOM'S TAXONOMY ALIGNMENT:**",
+            "   - Outcomes MUST be strictly ordered according to Bloom's taxonomy hierarchy:",
+            "     • Remember (التذكر) → Understand (الفهم) → Apply (التطبيق) → Analyze (التحليل) → Evaluate (التقييم) → Create (الإبداع)",
+            "   - Start from lower cognitive levels and progress to higher levels.",
+            "   - Each outcome must accurately reflect its assigned Bloom's level.",
+            "   - Use appropriate verbal nouns (مصادر) that match the cognitive level.",
+            "",
+            "**3. VERB/NOUN DIVERSITY:**",
+            "   - CRITICAL: Maximize diversity in verbal nouns (مصادر) across all outcomes.",
+            "   - Avoid repeating the same مصدر unless absolutely necessary.",
+            "   - Use synonyms and varied expressions within the same Bloom's level.",
+            "   - Track usage to ensure maximum variety throughout the outcomes list.",
+            "",
+            "**4. CLARITY AND CONCISENESS:**",
+            "   - Each outcome must be concise: 10-15 words maximum.",
+            "   - Use clear, unambiguous language appropriate for {audience}.",
+            "   - Avoid complex grammatical structures or nested phrases.",
+            "   - Ensure smooth, natural Arabic flow.",
+            "",
+            "**5. MEASURABILITY:**",
+            "   - Every outcome must be observable and measurable.",
+            "   - The outcome should clearly indicate what success looks like.",
+            "   - Avoid vague or abstract outcomes that cannot be assessed.",
+            "",
+            "**6. DNA METHODOLOGY INTEGRATION:**",
+            "Apply DNA principles to ensure comprehensive coverage:",
+            "   - **Declarative (Conceptual)**: Theories, principles, abstract concepts, definitions",
+            "     Examples: فهم المفاهيم، إدراك المبادئ، معرفة النظريات",
+            "   - **Procedural**: Step-by-step methods, processes, how-to knowledge",
+            "     Examples: تطبيق الخطوات، تنفيذ الإجراءات، ممارسة الأساليب",
+            "   - **Structural**: Frameworks, models, system-level understanding, relationships",
+            "     Examples: تحليل النماذج، فحص الأطر، استكشاف العلاقات",
+            "   - **Personal/Metacognitive**: Self-reflection, personal development, awareness",
+            "     Examples: تقييم الذات، تطوير المهارات الشخصية، إدراك القدرات",
+            "   - **Realistic/Contextual**: Real-world application, case studies, practical scenarios",
+            "     Examples: تطبيق في سياقات واقعية، حل مشكلات حقيقية، توظيف في الميدان",
+            "",
+            "Ensure outcomes collectively cover multiple DNA dimensions for holistic learning.",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "You are an elite instructional designer specializing in outcomes-based education and the DNA knowledge framework.",
+            "You have deep expertise in:",
+            "   - Arabic linguistic structures, particularly verbal nouns (المصادر)",
+            "   - Bloom's Taxonomy and its precise application to learning outcomes",
+            "   - DNA methodology for comprehensive knowledge representation",
+            "   - Measurable outcome design that can be clearly assessed",
+            "",
+            "You analyze learning objectives carefully to extract the core learning achievements,",
+            "then synthesize them into well-crafted outcomes that are:",
+            "   • Linguistically precise and natural in Arabic",
+            "   • Aligned with the appropriate Bloom's cognitive level",
+            "   �� Diverse in vocabulary to avoid monotony",
+            "   • Measurable and realistic for the {audience}",
+            "   • Comprehensive in covering declarative, procedural, structural, personal, and realistic dimensions",
+            "",
+            "You consider the ({topic}, {domain}, {content_type}, {audience}, {material_type}) context",
+            "to ensure outcomes are appropriate, achievable, and relevant.",
+            "",
+            "You maintain a mental tracker of all verbal nouns (مصادر) used to maximize diversity across outcomes.",
+        ]
+    ),
+    llm=llm_g,
+    verbose=True,
+    max_iter=100,
+)
+
+outcomes_task = Task(
+    description="\n".join(
+        [
+            "You are given a set of learning objectives in: {objectives}.",
+            "",
+            "Your task is to analyze these objectives and generate high-quality Arabic learning outcomes",
+            "that are measurable, aligned with Bloom's taxonomy, and designed using DNA methodology.",
+            "",
+            "### STEP-BY-STEP PROCESS:",
+            "",
+            "**STEP 1: ANALYZE THE OBJECTIVES**",
+            "   - Read all objectives carefully to understand the complete learning journey.",
+            "   - Identify the main knowledge domains, skills, and behaviors covered.",
+            "   - Group objectives by Bloom's taxonomy levels.",
+            "   - Note the DNA dimensions present (declarative, procedural, structural, personal, realistic).",
+            "",
+            "**STEP 2: DETERMINE OUTCOME STRUCTURE**",
+            "   - Decide how many outcomes are needed (typically one per Bloom's level that has objectives).",
+            "   - If multiple objectives exist at one Bloom's level, synthesize them into ONE comprehensive outcome.",
+            "   - Ensure outcomes progress logically from Remember → Create.",
+            "",
+            "**STEP 3: SELECT APPROPRIATE VERBAL NOUNS (مصادر)**",
+            "   - For each Bloom's level, review the available verbal nouns (provided below).",
+            "   - Select a مصدر that:",
+            "     • Accurately represents the cognitive level",
+            "     • Has NOT been used in previous outcomes (maximize diversity)",
+            "     • Is appropriate for the {audience}",
+            "     • Matches the DNA dimension of the content",
+            "   - Maintain a mental list of used مصادر to avoid repetition.",
+            "",
+            "**STEP 4: CRAFT EACH OUTCOME**",
+            "   - Structure: [مصدر] + [core content/concept] + [context if needed]",
+            "   - Keep it concise: 6-10 words maximum.",
+            "   - Ensure it's measurable and observable.",
+            "   - Use natural, flowing Arabic.",
+            "   - Verify it synthesizes all related objectives at that level.",
+            "",
+            "**STEP 5: QUALITY VERIFICATION**",
+            "   - Check each outcome against the 12 quality criteria (see below).",
+            "   - Ensure verb diversity across all outcomes.",
+            "   - Verify Bloom's sequence is maintained.",
+            "   - Confirm DNA dimensions are covered.",
+            "",
+            "### COMPREHENSIVE VERBAL NOUNS (مصادر) BY BLOOM'S LEVEL:",
+            "",
+            "Use these extensive lists to maximize diversity:",
+            "",
+            "**Remember (التذكر) - Declarative Focus:**",
+            "تعريف، تحديد، تسمية، ذكر، كتابة، عرض، سرد، تعداد، حفظ، استرجاع، تكرار، معرفة، إدراج، إشارة، اختيار",
+            "",
+            "**Understand (الفهم) - Conceptual Focus:**",
+            "فهم، إدراك، توضيح، شرح، تفسير، تلخيص، وصف، مناقشة، استنتاج، تمثيل، ترجمة، تعبير، صياغة، إعادة صياغة، استيعاب",
+            "",
+            "**Apply (التطبيق) - Procedural Focus:**",
+            "تطبيق، استخدام، توظيف، ممارسة، تنفيذ، إجراء، حل، تشغيل، إنجاز، ربط، تجريب، اختبار، عرض، إعداد، إظهار",
+            "",
+            "**Analyze (التحليل) - Structural Focus:**",
+            "تحليل، فحص، تمييز، مقارنة، تصنيف، فصل، تفريق، استقصاء، استكشاف، اكتشاف، ربط، تنظيم، تجزئة، دراسة، بحث",
+            "",
+            "**Evaluate (التقييم) - Metacognitive/Critical Focus:**",
+            "تقييم، حكم، نقد، تبرير، دعم، توصية، اختيار، مراجعة، دفاع، تقدير، فحص نقدي، موازنة، مفاضلة، ترجيح، إصدار حكم",
+            "",
+            "**Create (الإبداع) - Generative/Innovative Focus:**",
+            "تصميم، إنشاء، ابتكار، تطوير، بناء، تأليف، تخطيط، تركيب، صياغة، اقتراح، إعداد، إنت��ج، تكوين، توليد، ابتداع",
+            "",
+            "### DNA METHODOLOGY INTEGRATION GUIDE:",
+            "",
+            "Ensure your outcomes collectively address multiple DNA dimensions:",
+            "",
+            "**Declarative/Conceptual Outcomes (مصادر مناسبة):**",
+            "   - Focus on: concepts, definitions, theories, principles",
+            "   - Verbs: تعريف، فهم، إدراك، معرفة، استيعاب",
+            "   - Example: فهم المبادئ الأساسية للتعلم الإلكتروني",
+            "",
+            "**Procedural Outcomes (مصادر مناسبة):**",
+            "   - Focus on: methods, steps, processes, how-to",
+            "   - Verbs: تطبيق، تنفيذ، ممارسة، استخدام، إجراء",
+            "   - Example: تطبيق خطوات تصميم محتوى تعليمي رقمي",
+            "",
+            "**Structural Outcomes (مصادر مناسبة):**",
+            "   - Focus on: frameworks, models, relationships, systems",
+            "   - Verbs: تحليل، فحص، استكشاف، ربط، تنظيم",
+            "   - Example: تحليل العلاقة بين استراتيجيات التعليم وأنواع المحتوى",
+            "",
+            "**Personal/Metacognitive Outcomes (مصادر مناسبة):**",
+            "   - Focus on: self-awareness, reflection, personal development",
+            "   - Verbs: تقييم الذات، تطوير، إدراك، تحسين، تنمية",
+            "   - Example: تقييم المهارات الشخصية في إدارة الوقت",
+            "",
+            "**Realistic/Contextual Outcomes (مصادر مناسبة):**",
+            "   - Focus on: real-world application, case studies, practical use",
+            "   - Verbs: توظيف في سياق واقعي، حل مشكلات، تطبيق ميداني",
+            "   - Example: حل مشكلات تعليمية واقعية باستخدام التقنيات الحديثة",
+            "",
+            "### QUALITY CRITERIA CHECKLIST (12+2 Criteria):",
+            "",
+            "Before finalizing each outcome, verify:",
+            "",
+            "✓ 1. **Correct linguistic form**: Uses مصدر (infinitive noun), not verb",
+            "✓ 2. **Bloom's alignment**: Accurately reflects the assigned cognitive level",
+            "✓ 3. **Clear and unambiguous**: No vague or confusing language",
+            "✓ 4. **Appropriate vocabulary**: Suitable for {audience} level",
+            "✓ 5. **Single focus**: Expresses ONE outcome, not multiple combined",
+            "✓ 6. **Measurable**: Can be observed or assessed",
+            "✓ 7. **Realistic**: Achievable within program scope and time",
+            "✓ 8. **Aligned with objectives**: Synthesizes related learning objectives",
+            "✓ 9. **Content-relevant**: Directly relates to {topic} and {domain}",
+            "✓ 10. **Logical sequence**: Follows Bloom's order (low to high)",
+            "✓ 11. **Audience-appropriate**: Matches {audience} capabilities",
+            "✓ 12. **Comprehensive**: Covers knowledge, skills, attitudes collectively",
+            "✓ 13. **DIVERSE VOCABULARY**: Avoids repetition of مصادر",
+            "✓ 14. **DNA-aligned**: Reflects appropriate DNA dimension(s)",
+            "",
+            "### EXAMPLES OF HIGH-QUALITY OUTCOMES:",
+            "",
+            "**✅ EXCELLENT EXAMPLES:**",
+            "",
+            "**Remember Level:**",
+            "تعريف المصطلحات الأساسية في التعلم الإلكتروني بدقة.",
+            "(Declarative, clear, measurable, concise, uses تعريف)",
+            "",
+            "**Understand Level:**",
+            "إدراك العلاقة بين أنماط التعلم واستراتيجيات التدريس.",
+            "(Structural understanding, uses إدراك, different from تعريف)",
+            "",
+            "**Apply Level:**",
+            "توظيف أدوات التقييم الرقمية في بيئة تعليمية فعلية.",
+            "(Procedural + Realistic, uses توظيف, context-specific)",
+            "",
+            "**Analyze Level:**",
+            "تمييز نقاط القوة والضعف في نماذج التصميم التعليمي.",
+            "(Structural analysis, uses تمييز, critical thinking)",
+            "",
+            "**Evaluate Level:**",
+            "مقارنة فعالية استراتيجيات التعليم المختلفة وفق معايير محددة.",
+            "(Evaluative, uses مقارنة, criteria-based)",
+            "",
+            "**Create Level:**",
+            "ابتكار حلول إبداعية لتحديات التعليم عن بُعد.",
+            "(Generative, uses ابتكار, innovative focus)",
+            "",
+            "**❌ POOR EXAMPLES (Avoid These):**",
+            "",
+            "❌ 'أن يفهم ا��متدرب مفهوم التعليم الإلكتروني'",
+            "(Wrong: uses verb form, not مصدر; includes 'أن يفهم المتدرب')",
+            "",
+            "❌ 'فهم التعليم الإلكتروني'",
+            "(Too vague, not measurable, lacks specificity)",
+            "",
+            "❌ 'فهم وتطبيق مبادئ التعليم الإلكتروني'",
+            "(Double outcome, combines two Bloom's levels)",
+            "",
+            "❌ 'تعريف أنواع التعليم الإلكتروني وتصنيف منصات التعلم'",
+            "(Multiple outcomes in one, too long)",
+            "",
+            "❌ Using 'تعريف' for all Remember-level outcomes",
+            "(Lacks diversity, repetitive)",
+            "",
+            "### CRITICAL VERB DIVERSITY REQUIREMENT:",
+            "",
+            "**🚨 PRIMARY INSTRUCTION: Maximize مصدر diversity across all outcomes**",
+            "",
+            "**Diversity Rules:**",
+            "1. Before selecting a مصدر, check: Have I used this before?",
+            "2. If yes, select an alternative unless no suitable synonym exists.",
+            "3. Use the full range of available مصادر at each Bloom's level.",
+            "4. Aim for 80-100% unique مصادر across all outcomes.",
+            "5. Track usage mentally as you craft each outcome.",
+            "",
+            "**Diversity Strategies:**",
+            "- Rotate through synonyms systematically",
+            "- Match مصدر to specific DNA dimension when possible",
+            "- Use more specific مصادر rather than generic ones",
+            "- Consider the nuance each مصدر brings to meaning",
+            "",
+            "### SELF-REFLECTION AFTER GENERATION:",
+            "",
+            "After creating all outcomes, review and ask:",
+            "- Do outcomes progress clearly from Remember to Create?",
+            "- Is there good diversity in مصادر (minimal repetition)?",
+            "- Do outcomes collectively cover DNA dimensions?",
+            "- Are all outcomes measurable and realistic for {audience}?",
+            "- Does each outcome synthesize its related objectives effectively?",
+            "- Is the Arabic natural, clear, and linguistically correct?",
+            "- Would an evaluator be able to assess achievement of each outcome?",
+            "",
+            "### FINAL QUALITY ASSURANCE:",
+            "",
+            "Before submitting, verify:",
+            "✓ All outcomes use مصدر form (not verbs)",
+            "✓ Bloom's sequence is maintained throughout",
+            "✓ Each outcome is 10-15 words maximum",
+            "✓ Vocabulary is appropriate for {audience}",
+            "✓ DNA methodology is applied",
+            "✓ Outcomes are measurable and realistic",
+            "✓ Minimal repetition of مصادر (high diversity)",
+            "✓ Each outcome synthesizes multiple related objectives where applicable",
+            "",
+            "### OUTPUT\n"
+            "Return the LearningObjectivesOutput structure in valid JSON format.\n\n",
+        ]
+    ),
+    expected_output="""JSON object with this structure:
+    {
+    "objectives": [
+    {
+        "unit": "Unit title",
+        "unit_description": "Brief summary of the unit scope",
+        "unit_outcome": "One measurable Arabic objective derived from the unit description and its subtopics and their purposes",
+    }
+    ],
+    }""",
+    output_json=LearningOutcomesOutput,
+    agent=outcomes_generator,
+    human_input=False,
+)

agents/analysis_phase/outliner.py

@@ -0,0 +1,97 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+#from schemas import CurriculumOutline
+
+# ========= 4. Outline Agent =========
+outline_agent = Agent(
+    role="Scientific Outline Generator",
+    goal="\n".join(
+        [
+            "Generate a complete and scientifically accurate training curriculum for the topic: {topic}.",
+            "The curriculum must be structured, logically sequenced, and pedagogically useful.",
+            "Avoid vague, redundant, or repetitive points—each topic must be unique and non-overlapping.",
+            "Ensure strong logical flow: units must progress according to Bloom’s taxonomy principles—starting from simple recall/understanding, moving to deeper analysis, application, evaluation, and finally creation/innovation.",
+            "Important: Do NOT explicitly use Bloom verbs (e.g., analyze, evaluate, create). Instead, embed the cognitive levels implicitly in the phrasing of topics.",
+            "When generating topics, always use terms and concepts that are common, searchable, and can be easily found in Arabic or international online sources (articles, courses, books).",
+            "Avoid overly creative or abstract titles that are difficult to map to real content.",
+            "Follow this strict format:",
+            "- Output must be in JSON.",
+            "- Curriculum must include exactly 4 units.",
+            "- Each unit must have exactly 5 sub-topics.",
+            "- Units must be output with keys: unit_title, topics.",
+            "Each unit must reflect and cover one of the core concepts of the topic, so that together they encompass all aspects of the subject.",
+            "The 4 units must be interconnected, sequentially linked, and collectively ensure full coverage of all concepts of the topic, leaving no gaps.",
+            "Ensure all text is written in **Arabic language**.",
+            "Units should be connected and form a comprehensive training program that gradually increases in cognitive depth according to Bloom’s taxonomy.",
+            "Always adapt to metadata: domain ({domain}), content_type ({content_type}), audience ({audience}), material_type ({material_type}).",
+            "Apply DNA methodology explicitly in topic design:",
+            "- material_type:",
+            "-- Conceptual: theories, principles, abstract knowledge.",
+            "-- Procedural: step-by-step instructions or methods.",
+            "-- Structural: frameworks, models, or system views.",
+            "-- Personal: learner reflection, skills, or self-development aspects.",
+            "-- Realistic: real-world examples, applications, or case studies.",
+            "- content_type:",
+            "-- Educational → for structured learning (e.g., lessons, modules)",
+            "-- Awareness → for informative/raising awareness purposes (e.g., campaigns, workshops)",
+            "-- Training → for skill development with step-by-step practice (e.g., hands-on, exercises)",
+            "Important: The curriculum title must be identical to the input topic, and unit titles must reflect or embed the meaning of this title.",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "This agent acts as both a scientific researcher and curriculum designer.",
+            "It generates structured outlines in the form of 4 units × 5 topics, aligned with DNA methodology.",
+            "It ensures progression follows Bloom’s taxonomy: Unit 1 covers basic recall/understanding, Unit 2 focuses on application of methods/tools, Unit 3 emphasizes analysis and evaluation in real contexts, and Unit 4 explores integration, innovation, or advanced synthesis.",
+            "The topics must always be realistic, practical, and searchable in Arabic or global sources to ensure that real content can be gathered later.",
+            "The final output must always be in Arabic.",
+            "The curriculum should progress from simple to complex, reflecting Bloom’s cognitive hierarchy, but without explicitly naming Bloom’s verbs in the text.",
+        ]
+    ),
+    llm=llm,
+    verbose=True,
+    reasoning=True,
+    max_reasoning_attempts=3,
+    max_iter=100,
+)
+
+
+# ========= 5. Task =========
+outline_task = Task(
+    description="\n".join(
+        [
+            "Generate a structured outline for the topic: {topic}.",
+            "The output must strictly follow this format:",
+            "- JSON object with keys: 'title' and 'units'.",
+            "- 'title': must be exactly the same as the input topic (in Arabic).",
+            "- 'units': exactly 4 items.",
+            "- Each unit must have:",
+            "   - unit_title (string, Arabic, must reflect or embed the curriculum title meaning)",
+            "   - topics (list of exactly 5 short topics, in Arabic).",
+            "Ensure the units flow logically, progressively, and cover the subject fully.",
+            "The units must align with Bloom’s taxonomy progression: Unit 1 = basic knowledge & understanding, Unit 2 = tools & applications, Unit 3 = analysis & evaluation, Unit 4 = synthesis & advanced innovation.",
+            "Do NOT explicitly use Bloom’s action verbs; express the cognitive levels implicitly in the phrasing of topics.",
+            "Each topic must embed one aspect of DNA methodology (Conceptual, Procedural, Structural, Personal, Realistic) and (content_type: Training, Awareness, Educational).",
+            "All topics must be formulated using widely recognized and searchable concepts (to allow collecting real content from online sources).",
+            "Avoid repetition—no two topics should overlap in meaning.",
+            "Do not add extra fields outside the schema.",
+            "The entire output must be in Arabic.",
+        ]
+    ),
+    expected_output=(
+        "A valid JSON object with this structure:\n"
+        "{\n"
+        '  "title": "string (Arabic curriculum title)",\n'
+        '  "units": [\n'
+        "    {\n"
+        '      "unit_title": "string (Arabic, must reflect the title)",\n'
+        '      "topics": ["topic1", "topic2", "topic3", "topic4", "topic5"]\n'
+        "    }, ... (4 units total)\n"
+        "  ]\n"
+        "}"
+    ),
+    #output_json=CurriculumOutline,
+    agent=outline_agent,
+)

agents/design_phase/__init__.py

@@ -0,0 +1,3 @@
+from .keywoard_researcher import keyword_researcher_agent, keyword_researcher_task
+from .source_finder import search_engine_agent, search_engine_task
+from .extractor import scraping_agent, scraping_task

agents/design_phase/extractor.py

@@ -0,0 +1,75 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+from modules import llm
+from tools import web_scraping_tool
+
+
+scraping_agent = Agent(
+    role="Web Scraping & Content Extraction Agent",
+    goal="\n".join(
+        [
+            "To extract structured and valuable content details from multiple trusted web pages.",
+            "The agent should gather, analyze, and filter relevant information about {topic} from reliable Arabic and English sources.",
+            "It must focus on scholarly materials, books, research papers, and high-quality educational content that can inspire ideas for building the course and trusted websites.",
+            "Focus on extracting the COMPLETE content, capture every paragraph, section, example, and detail.",
+            "The agent should also identify and rank the usefulness of each source depending on its credibility and relevance to the course objectives.",
+            "The goal is not only to scrape raw text but also to provide clear notes and recommendations about the extracted content to help instructional designers, course creators, and content writers.",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "This agent acts like a scientific researcher and content curator for e-learning projects.",
+            "It specializes in exploring a wide range of Arabic and English references: books, articles, and academic research papers.",
+            "By analyzing the scraped content, it supports course designers in identifying diverse and meaningful ideas aligned with the main course theme and learning objectives.",
+            "It ensures that every extracted resource is reliable, and practical for developing educational materials, such as cultural intelligence courses.",
+        ]
+    ),
+    llm=llm,
+    tools=[web_scraping_tool],
+    verbose=True,
+)
+
+scraping_task = Task(
+    description="\n".join(
+        [
+            "The task is to extract and organize content details from the most relevant and trusted web pages.",
+            "You should gather insights in both Arabic and English.",
+            "Here are the search results you have to extract content from:",
+            "{urls}",
+            "From each page, extract the title, main content, and any associated media (images, videos, audios, pdfs).",
+            "For every resource, provide an agent recommendation rank (0–5) along with notes explaining its relevance, credibility, and why it is or is not recommended.",
+            "For every resource select the heading and the subheading the content is belongs to from these outlines {outlines}",
+        ]
+    ),
+    expected_output=(
+        "Return ONLY a valid Python dictionary.\n"
+        "- Do not include explanations, markdown, or code fences.\n"
+        "- The dictionary must be UTF-8 safe and directly usable in Python with ast.literal_eval.\n"
+        "- Keys must be wrapped in double quotes.\n\n"
+        "Format example:\n"
+        "{\n"
+        '  "parts": [\n'
+        "    {\n"
+        '      "page_url": "https://example.com/page1",\n'
+        '      "title": "Understanding Time Management for Kids",\n'
+        '      "content": "Detailed explanation of how children can learn time management.",\n'
+        '      "img_url": ["https://example.com/image1.jpg"],\n'
+        '      "video_url": ["https://example.com/video1.mp4"],\n'
+        '      "audio_url": ["https://example.com/audio1.mp3"],\n'
+        '      "pdf_url": ["https://example.com/file1.pdf"],\n'
+        '      "agent_recommendation_rank": 4.7,\n'
+        '      "agent_recommendation_notes": "This content provides clear strategies and visuals that are highly useful.",\n'
+        '      "header": "Time Management",\n'
+        '      "sub_header": "For Children"\n'
+        "    }\n"
+        "  ]\n"
+        "}\n\n"
+        "Make the output compatible with Python's ast library because I use:\n"
+        "    r1 = result.dict()['raw']\n"
+        "    f_result = ast.literal_eval(r1)\n"
+        "Make sure there are no unterminated string literals and no invalid syntax.\n"
+        "The output MUST match exactly the schema and format example above.\n"
+        "Do not include Thoughts, explanations, or anything else besides the dictionary."
+    ),
+    agent=scraping_agent,
+)

agents/design_phase/keywoard_researcher.py

@@ -0,0 +1,50 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+from modules import llm
+from schemas import SuggestedSearchQueries
+
+no_keywords = 25
+
+keyword_researcher_agent = Agent(
+    role="search queries recommendation agent",
+    goal="\n".join(
+        [
+            "To generate a set of structured and comprehensive search queries based on the topic {topic} "
+            "and the outline headings (main and sub-headings) provided from the outline task.",
+            "Queries should be varied, precise,relevant , and research-oriented.",
+            "For each heading and sub-heading, create multiple queries to help collect rich, relevant content from the web.",
+            "Queries must ensure coverage of the most important aspects of the topic, avoiding irrelevant or empty dimensions.",
+            "Avoid vague or overly generic queries.",
+            "Ensure queries reflect the scope of the outline, avoiding irrelevant or generic phrasing.",
+            "Strictly avoid generating queries related to religions, politics, or any biased/off-topic perspectives.",
+        ]
+    ),
+    backstory=(
+        "This agent acts as a scientific researcher and content strategist and instructional designer. "
+        "It takes the topic and its structured outline (headings + sub-headings) and expands them into precise, "
+        "targeted search queries. These queries are crafted to maximize coverage of the outline sections "
+        "and ensure the user can gather high-quality resources for each part."
+    ),
+    llm=llm,
+    verbose=True,
+)
+
+keyword_researcher_task = Task(
+    name="search queries recommendation task",
+    description="\n".join(
+        [
+            "Using the outline headings and sub-headings {outlines} for the topic {topic},",
+            "generate up to {no_keywords_Researcher_For_Each_Heading} short and precise search queries for each heading.",
+            "Each query must be short, complete, and precise, directly reflecting the heading or sub-heading it belongs to.",
+            "The aim is to cover the full breadth of the outline so that no important section is left without queries.",
+            "Queries should be research-oriented, avoiding vague or overly generic terms.",
+            "Important: All queries for the same heading must be unique and non-repetitive.",
+            "Do NOT generate queries that only differ by synonyms like 'concept' vs. 'definition'.",
+            "Instead, vary the focus (e.g., concept, benefits, methods, challenges, applications).",
+            "Strictly exclude any queries related to religion, politics, or biased/off-topic perspectives.",
+        ]
+    ),
+    expected_output="A JSON object containing a list of suggested search queries.",
+    output_json=SuggestedSearchQueries,
+    agent=keyword_researcher_agent,
+)

agents/design_phase/source_finder.py

@@ -0,0 +1,69 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+from modules import llm
+from tools import search_engine_tool
+
+
+search_engine_agent = Agent(
+    role="search engine agent",
+    goal="\n".join(
+        [
+            "Search for diverse, high-quality, and reliable information related to {topic} using the suggested search queries.",
+            "Prioritize **scholarly and educational resources**: academic journals, books, research articles, and trusted institutional websites.",
+            "Include Arabic sources when contextually valuable, but prioritize English academic sources for broader coverage.",
+            "Ensure all results are concise, relevant, and aligned with the outline headings to directly support course design and educational content.",
+            "For each query, return at most 5 results with structured metadata (title, url, content summary, score, search_query).",
+        ]
+    ),
+    backstory=(
+        "This agent acts like a scientific researcher and educational content curator."
+        "It executes the generated queries and gathers high-value, trustworthy information."
+        "The agent is trained to filter out irrelevant, commercial, or low-quality content, ensuring that "
+        "only academic and pedagogically useful resources are kept."
+        "for building interactive e-learning content are retrieved."
+        "It balances global knowledge with local cultural enrichment by including both English and Arabic sources."
+    ),
+    llm=llm,
+    verbose=True,
+    tools=[search_engine_tool],
+)
+
+search_engine_task = Task(
+    description="\n".join(
+        [
+            "The task is to search the web for relevant and reliable resources about {topic} using the suggested search queries.",
+            "You must collect results from multiple queries to ensure diversity of perspectives and sources.",
+            "Here are the queries you can use to search:",
+            "{queries}",
+            "For each query, retrieve at least 1 link and a maximum of {no_links} links only.",
+            "Prioritize scholarly, academic, and educational resources (journals, books, institutional websites).",
+            "Filter out irrelevant, suspicious, or low-quality results (e.g., personal blogs, spam, commercial ads).",
+            "Apply score filtering: ignore results with a confidence score lower than {score_th}.",
+            "The final results will serve as the knowledge base for building trusted, high-quality content, ",
+            "with a focus on supporting the course’s educational objectives and cultural enrichment goals.",
+            "with a focus on supporting the course’s educational objectives and cultural enrichment goals.",
+        ]
+    ),
+    expected_output=(
+        "Return ONLY a valid Python dictionary.\n"
+        "- Do not include explanations, markdown, or code fences.\n"
+        "- The dictionary must be UTF-8 safe and directly usable in Python with ast.literal_eval.\n"
+        "- Keys must be wrapped in double quotes.\n\n"
+        "Format example:\n"
+        "{\n"
+        '  "results": [\n'
+        "    {\n"
+        '      "url": "...",\n'
+        '      "title": "...",\n'
+        '      "content": "...",\n'
+        '      "score": 0.85,\n'
+        '      "search_query": "..."\n'
+        "    }\n"
+        "  ]\n"
+        "}"
+        "Make the out compatible with ast python library because i use r1 = result.dict()['raw'] f_result = ast.literal_eval(r1)"
+        "Make sure there is no unterminated string literal and no invalid syntax, errors will happen when parsing"
+        "Make sure that the output is only as the format example i give you before, dont include Thoughts or anything else"
+    ),
+    agent=search_engine_agent,
+)

agents/final_outliners/__init__.py

@@ -0,0 +1,4 @@
+from .subtopics_generator import subtopics_generator_agent, subtopics_generation_task
+from .validator import validator_agent, validation_task
+# from .units_langchain import units_langchain_agent
+from .units_langchain_1v import units_langchain1_agent

agents/final_outliners/subtopics_generator.py

@@ -0,0 +1,129 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm_5m, llm_g
+from schemas import FullCurriculumStructure
+
+
+subtopics_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 (containing the main concept, General_objectives_of_the_plan, and list of units and their details). "
+        "For each unit — based on its title and details — generate list of coherent and progressive Arabic subtopics (axes). "
+        "These subtopics should represent a logical and educational flow from foundational understanding "
+        "to advanced application and creativity. "
+        "Each unit's subtopic should represent a specific stage of learning progression — starting from basic knowledge acquisition "
+        "and moving toward critical thinking and creative application. "
+        ## 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 subtopics 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."
+        "Ensure that the subtopics 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 subtopics are contextually relevant to the unit's focus and contribute to the learner's comprehensive understanding."
+    ),
+    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 that reflect a logical learning progression — "
+        "starting from basic understanding and moving toward higher-order thinking and creative application. "
+        "Each subtopic 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 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"
+        "  '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"
+        "}"
+    ),
+    # llm=llm_open_c35,
+    llm=llm_g,
+    allow_delegation=False,
+    verbose=True,
+    reasoning=True,
+    max_iter=100,
+)
+
+# ============================================================
+# 🧩 3. Axis Generation Task
+# ============================================================
+
+subtopics_generation_task = Task(
+    description=(
+        "## GOAL\n"
+        "Expand each educational unit from the given file into number of structured Arabic subtopics: {units}. "
+        # "Each axis should develop the learner’s understanding progressively — starting with remembering, "
+        # "then understanding, applying, analyzing, and finally creating.\n"
+        "Each subtopic 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, General_objectives_of_the_plan, and list of units and their details). "
+        # "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 title and details.\n"
+        "   - Generate list of progressive subtopics that unfold logically.\n"
+        "   - Each subtopic must include:\n"
+        "     • 'subtopic_number': numerical order of the subtopic in the unit.\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 subtopic\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 subtopic:\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"
+        "     can be in form of short sentence or a question\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 subtopics."
+    ),
+    expected_output="A FullCurriculumStructure JSON object containing all units and their respective list of subtopics each.",
+    agent=subtopics_generator_agent,
+    output_json=FullCurriculumStructure,
+)

agents/final_outliners/units_langchain.py

@@ -0,0 +1,67 @@
+# from langchain.agents import create_tool_calling_agent, AgentExecutor
+# from langchain.prompts import ChatPromptTemplate
+# from modules import model, llm_g
+# import json
+# import re
+# import pandas as pd
+
+
+# def units_langchain_agent(topic: str, units_number: int):
+#     # الخطوة 1: نطلب من llm_g إنشاء Markdown plan
+#     result = llm_g.call(
+#         f"Create a structured {units_number}-unit study plan for the topic [{topic}]"
+#     )
+
+#     # الخطوة 2: الـ System Prompt الخاص بالاستخراج
+#     system_prompt = """
+#     You will receive Markdown text representing a study plan.
+#     Extract structured data and return it strictly in this JSON format:
+
+#     {{
+#         "topic": "<topic name>",
+#         "General_objectives_of_the_plan": ["string", "string", ...],
+#         "total_units": <total_units_number>,
+#         "units": [
+#             {{
+#                 "unit_number": 1,
+#                 "unit_title": "string",
+#                 "description": "string",
+#                 "unit_objectives": ["string", "string", ...],
+#                 "unit_main_topics": ["string", "string", ...]
+#             }},
+#             ...
+#         ]
+#     }}
+
+#     Output **only valid JSON**, no explanations, markdown, or extra text.
+#     """
+
+#     # الخطوة 3: إنشاء prompt فيه متغير agent_scratchpad المطلوب
+#     prompt = ChatPromptTemplate.from_messages(
+#         [
+#             ("system", system_prompt),
+#             ("user", "{input}"),
+#             ("assistant", "{agent_scratchpad}"),  # << الإضافة المطلوبة
+#         ]
+#     )
+
+#     # الخطوة 4: إنشاء الـ Agent
+#     tools = []  # مفيش Tools هنا
+#     agent = create_tool_calling_agent(model, tools, prompt=prompt)
+
+#     # الخطوة 5: تنفيذ الـ Agent
+#     agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+#     response = agent_executor.invoke({"input": result, "agent_scratchpad": ""})
+
+#     # الخطوة 6: استخراج النتيجة
+#     raw_output = response.get("output", "").strip()
+
+#     # الخطوة 7: تنظيف وتحويل JSON
+#     try:
+#         structured_data = json.loads(raw_output)
+#     except json.JSONDecodeError:
+#         cleaned = re.sub(r"```json|```", "", raw_output).strip()
+#         structured_data = json.loads(cleaned)
+
+#     return structured_data
+

agents/final_outliners/units_langchain_1v.py

@@ -0,0 +1,58 @@
+from modules import model, llm_g
+import json
+import re
+from langchain.agents import create_agent
+
+
+def units_langchain1_agent(topic: str, units_number: int):
+    # الخطوة 1: نطلب من llm_g إنشاء Markdown plan
+    result = llm_g.call(
+        f"Create a structured {units_number}-unit study plan for the topic [{topic}] focuses on logical sequencing and educational activities without delving into scientific or technical details, The plan should be similar to a training plan that can be presented in a workshop or short course."
+    )
+
+    # الخطوة 2: الـ System Prompt الخاص بالاستخراج
+    system_prompt = """
+    extract structured data from Markdown text you will be given.
+
+    The JSON should have this exact structure:
+    {
+        "topic": "<topic name>",
+        "General_objectives_of_the_plan": ["string", "string", ...]
+        "total_units": <total_units_number>,
+        "units": [
+            {
+                "unit_number": 1,
+                "unit_title": "string",
+                "description": "string",
+                "unit_objectives": ["string", "string", ...],
+                "unit_main_topics": ["string", "string", ...]
+            },
+            ...
+        ]
+    }
+
+    NOTE:
+    if any descriptions are missing from the given file you can generate them after understanding the context.
+
+    Output **only valid JSON**, no explanations, markdown, or extra text.
+    """
+
+    agent = create_agent(
+        model=model,
+        system_prompt=system_prompt,
+    )
+
+    response = agent.invoke({"messages": [{"role": "user", "content": result}]})
+
+    #######################
+    # الخطوة 6: استخراج النتيجة
+    raw_output = response['messages'][1].content.strip()
+
+    # الخطوة 7: تنظيف وتحويل JSON
+    try:
+        structured_data = json.loads(raw_output)
+    except json.JSONDecodeError:
+        cleaned = re.sub(r"```json|```", "", raw_output).strip()
+        structured_data = json.loads(cleaned)
+
+    return structured_data

agents/final_outliners/validator.py

@@ -0,0 +1,139 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm_5m, llm_g
+from schemas import ValidatedCurriculumOutput, validated_parser
+from functools import cache
+
+validator_agent = Agent(
+    role="Arabic Educational Validator (Curriculum Quality & Integrity Specialist)",
+    goal=(
+        "Ensure that all educational units and subtopics are conceptually complete, logically sequenced, linguistically refined, "
+        "and pedagogically sound for Arabic learners. Validate and enhance each unit's structure to maintain educational coherence "
+        "and clarity while preserving Arabic authenticity. Ensure all titles are in Arabic only. and try to include the notes given in the structure."
+    ),
+    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"
+        "  'General_objectives_of_the_plan': '...',\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"
+        "}"
+    ),
+    # llm=llm_open_c35,
+    llm=llm_g,
+    allow_delegation=False,
+    verbose=True,
+    reasoning=True,
+    max_iter=100,
+    cache=False,
+)
+
+validation_task = Task(
+    description=(
+        "Validate, refine, and enhance all generated educational units and their subtopics (only those needing improvement). "
+        "Ensure conceptual completeness, logical sequencing, and pedagogical depth across all units.\n\n"
+        "===================================================\n"
+        "## INPUT\n"
+        "You will be given a FullCurriculumStructure JSON from axis_generator_agent and details: {units}. "
+        "NOTES may also be provided {note}. These notes contain additional instructions or required new content. "
+        "so think how to achieve this within the educational plan, should you add new subtopic or new unit with new subtopic or modify anything(sure without deleting), "
+        "The agent must interpret the notes and add the required new subtopics or axes to the appropriate unit. "
+        "Example: If the note says 'تناول الاستخدامات الحديثة لتحليل البيانات في محور واحد', "
+        "you must add a new subtopic titled 'الاستخدامات الحديثة لتحليل البيانات' or any academically suitable Arabic title, "
+        "place it in the correct unit, and mark its status as 'added'.\n\n"
+        "===================================================\n"
+        "PRIMARY OBJECTIVE\n"
+        "===================================================\n"
+        "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"
+        "5- Ensure the unit name best expresses its content in professional Arabic.\n"
+        "6- Avoid punctuation marks (– , ; : . ! ? , /) except for simple questions.\n"
+        "7- If removing punctuation affects grammar, enhance the title for natural Arabic style.\n\n"
+        "===================================================\n"
+        "PHASE 1 — COMPREHENSIVENESS & DEPTH ANALYSIS\n"
+        "===================================================\n"
+        "1. Analyze all subtopics for each unit and unit details.\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 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 and all details is represented.\n"
+        "2. Ensure 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"
+        "===================================================\n"
+        "4. Validate that each Subtopic:\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"
+        "   - Title length: concise (4–8 words preferred).\n"
+        "   - Clear and contextually linked to its unit.\n"
+        "   - Tone appropriate for {audience}.\n"
+        "   - Avoids punctuation marks except for simple questions.\n"
+        "   - Represents one coherent idea, not compound.\n"
+        "   - Avoids activity-based terms like 'ورشة عمل' or 'نشاط'.\n"
+        "   - Sounds realistic, teachable, and suitable for Arabic educational content.\n\n"
+        "===================================================\n"
+        "PHASE 4.1 — ARABIC LANGUAGE INTEGRITY ENFORCEMENT\n"
+        "===================================================\n"
+        "1. Ensure that all titles (unit and subtopic) are written entirely in Arabic script.\n"
+        "2. If a title contains any Latin (English) letters, numerals, or symbols, rephrase it fully into correct Modern Standard Arabic.\n"
+        "3. Maintain original meaning and clarity when translating or rephrasing into Arabic.\n"
+        "4. Titles must not contain any transliterations (e.g., 'Entrepreneurship', 'AI', 'Design Thinking'). Replace them with Arabic equivalents.\n"
+        "5. Reject any title that cannot be made purely Arabic, and provide a suitable Arabic substitute aligned with educational context.\n\n"
+        "===================================================\n"
+        "PHASE 5 — OUTPUT STRUCTURE\n"
+        "===================================================\n"
+        "Return validated curriculum in JSON format with units, subtopics, and validation status.\n\n"
+        "===================================================\n"
+        "## NOTES\n"
+        "- Keep phrasing in professional Modern Standard Arabic.\n"
+        "- Avoid dual, poetic, or abstract titles.\n"
+        "- Ensure all outputs are grammatically correct and stylistically natural Arabic.\n"
+        "- Titles must not include any English or foreign words."
+        "- don't let the added notes destroy any of the curriculum structur only add what is needed."
+    ),
+    # guardrail="",
+    expected_output="A JSON object showing validated units and subtopics with Arabic-only titles.",
+    output_json=ValidatedCurriculumOutput,
+    output_parser=validated_parser,
+    agent=validator_agent,
+)

agents/outliner_phase/Deep_Semantic_Topics_Generator_1.py

@@ -0,0 +1,118 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+from schemas import CurriculumOutline, DeepSemanticTopicsOutput
+
+# ---------------------------
+# === Agent 1: Deep Semantic Topics Generator (Full Coverage + Metadata Adaptive) ===
+# ---------------------------
+
+research_agent = Agent(
+    role="Deep Semantic Topics Generator (Educational Research Agent)",
+    goal="\n".join(
+        [
+            "Generate as many interconnected and realistic Arabic topics as possible for the curriculum title: {topic}.",
+            "Do NOT divide topics into units — just produce a comprehensive standalone list of high-quality topics.",
+            "Your mission is to achieve *maximum conceptual and practical coverage* of the topic: cover every visible and implicit meaning embedded in the title: {topic}.",
+            "Interpret the topic deeply and explore all related sub-concepts, tools, methods, applications, personal skills, frameworks, real-world examples, and future trends.",
+            "No aspect of the topic should remain uncovered — ensure total thematic coverage from theory to practice.",
+            # === Adaptation & Metadata awareness ===
+            "Always adapt to metadata: domain ({domain}), content_type ({content_type}), audience ({audience}), material_type ({material_type}).",
+            "Adjust tone, complexity, and depth according to the audience and domain type.",
+            "Apply DNA methodology explicitly in topic design:",
+            "- material_type:",
+            "-- Conceptual: theories, principles, abstract knowledge.",
+            "-- Procedural: step-by-step instructions or methods.",
+            "-- Structural: frameworks, models, or system views.",
+            "-- Personal: learner reflection, skills, or self-development aspects.",
+            "-- Realistic: real-world examples, applications, or case studies.",
+            "- content_type:",
+            "-- Educational → for structured learning (e.g., lessons, modules).",
+            "-- Awareness → for informative or awareness-raising purposes (e.g., campaigns, workshops).",
+            "-- Training → for hands-on skill development (e.g., exercises, applied learning).",
+            # === Learning progression ===
+            "Ensure logical educational progression throughout the topics:",
+            "  1️⃣ Start with conceptual understanding (definitions, foundations, importance).",
+            "  2️⃣ Then practical tools and applications (methods, workflows, tools).",
+            "  3️⃣ Then analysis and real-world case studies (evaluation, lessons learned).",
+            "  4️⃣ End with strategies, integration, and innovation (advanced synthesis, policies, or future directions).",
+            # === Title & Content validation ===
+            "Each topic must be realistic and searchable in Arabic or bilingual educational sources.",
+            "Before finalizing each topic, mentally confirm that real Arabic educational content exists online for it.",
+            "Reject or replace any vague, repetitive, or non-educational topics.",
+            "Avoid vague or redundant points — every topic must be unique and non-overlapping.",
+            # === Arabic educational title standards ===
+            "Follow Arabic educational title standards strictly:",
+            "  - Clear, concise, and direct phrasing (no metaphors or poetic language).",
+            "  - Titles should be between 4–7 words long.",
+            "  - Represent a clear learning focus, suitable for the target audience ({audience}).",
+            "  - Example good: مهارات التفكير النقدي واتخاذ القرار",
+            "  - Example bad: رحلة العقل نحو التفكير النقدي وصناعة القرار",
+            # === Output schema ===
+            "For each topic, provide the following JSON fields exactly:",
+            "  - title: Arabic, concise and direct",
+            "  - description: 1–2 lines Arabic summarizing the topic",
+            "  - dna: one of [Conceptual, Procedural, Structural, Personal, Realistic] and [Educational, Awareness, Training]",
+            "  - suggested_unit: integer (1–4) showing depth progression (1=basic → 4=advanced)",
+            "  - search_terms: 3–6 Arabic keywords relevant to the topic",
+            "  - source: optional Arabic or bilingual educational source name/title (if known)",
+            # === Output constraints ===
+            "Output must be a valid JSON list (no commentary, no explanations).",
+            "List must be ordered by suggested_unit (1 → 4) to reflect gradual learning progression.",
+        ]
+    ),
+    backstory="\n".join(
+        [
+            "You are a senior educational researcher and curriculum architect with deep expertise in Arabic educational design and semantic topic analysis.",
+            "You deeply interpret the input topic — uncovering both its explicit and implicit meanings to ensure total thematic coverage.",
+            "You create coherent, realistic, and pedagogically structured topic sets that form a logical educational progression.",
+            "Each topic you design is grounded in actual Arabic or bilingual educational resources, ensuring that every subject can be realistically taught or studied.",
+            "You think step by step before finalizing outputs — validating realism, logical sequence, and online content availability.",
+            "Your work directly feeds the downstream Outline Agent, so clarity, precision, and educational completeness are essential in every topic you produce.",
+        ]
+    ),
+    allow_delegation=False,
+    llm=llm,
+    reasoning=True,
+    verbose=True,
+    max_reasoning_attempts=4,
+    max_iter=100,
+)
+
+# ---------------------------
+# === Task 1: Generate Deep & Comprehensive Topics ===
+# ---------------------------
+
+research_task = Task(
+    description="\n".join(
+        [
+            "Generate a comprehensive, realistic, and logically structured list of Arabic topics for {topic}.",
+            "Ensure full semantic coverage — address both the explicit and implicit meanings of the topic title to cover all relevant dimensions and perspectives.",
+            "Include topics that collectively span all DNA dimensions and metadata parameters: content_type ({content_type}) and material_type ({material_type}).",
+            "Each topic must be unique, clear, and pedagogically meaningful — avoiding repetition, overlap, or vague expressions.",
+            "All topics must be realistic and supported by potential Arabic or bilingual educational resources available online.",
+            "Ensure educational progression: begin with conceptual foundations and definitions, then move through methods and tools, practical applications, case studies, and finally strategic or innovative insights.",
+            "Maintain alignment with Arabic educational title standards: concise, direct, single-part titles with clear learning focus.",
+            "Output must be a valid JSON list following the schema below — no explanations, introductions, or extra commentary.",
+        ]
+    ),
+    expected_output=(
+        "A valid JSON list ordered by suggested_unit ascending:\n"
+        "[\n"
+        "  {\n"
+        '    "title": "string (Arabic)",\n'
+        '    "description": "string (1–2 lines in Arabic)",\n'
+        '    "dna": "Conceptual|Procedural|Structural|Personal|Realistic",\n'
+        '    "suggested_unit": 1|2|3|4,\n'
+        '    "search_terms": ["string (Arabic keyword)", ...],\n'
+        '    "source": "string (optional)"\n'
+        "  }, ...\n"
+        "]\n"
+        "The output must be valid JSON, without markdown formatting or code blocks."
+    ),
+    params={"min_topics": 10, "max_topics": 30},  # expand to ensure deeper coverage
+    output_json=DeepSemanticTopicsOutput,
+    # output_file=os.path.join(output_dir, "deep_semantic_topics.json"),
+    agent=research_agent,
+)

agents/outliner_phase/__init__.py

@@ -0,0 +1,4 @@
+from .Deep_Semantic_Topics_Generator_1 import research_agent, research_task
+from .topic_expander_2 import structure_agent, structure_task
+from .module_organizer_3 import designer_agent, design_task
+from .review_agent_4 import review_agent, review_task

agents/outliner_phase/module_organizer_3.py

@@ -0,0 +1,46 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+from schemas import CurriculumOutline
+
+
+# ---------------------------
+# === Agent 3: Module Organizer ===
+# ---------------------------
+designer_agent = Agent(
+    role="Module Organizer Agent (Group into 4 modules)",
+    goal=(
+        "استلم الـ20 محورًا من Agent2. نظّمهم إلى **4 وحدات**، كل وحدة تحتوي على **5 مواضيع** "
+        "مرتبة متسلسلة ومنطقية. أعطِ كل وحدة عنوانًا واضحًا ومعبّرًا (module_title بالعربية)، "
+        "وقصّر عناوين المواضيع بحيث تكون جاهزة للاستخدام في الـ Curriculum (كل موضوع عبارة "
+        "عن جملة قصيرة أو عبارة). أعد صياغة المواضيع إن لزم لتكون متجانسة معًا."
+    ),
+    backstory=(
+        "أنت كبير مصممي مناهج. مهمتك إخراج المخرجات بصيغة CurriculumOutline المتوافقة مع الـ schema."
+    ),
+    llm=llm,
+    allow_delegation=False,
+    verbose=True,
+)
+
+
+design_task = Task(
+    description="تنظيم المحاور العشرين إلى 4 وحدات × 5 مواضيع في كل وحدة.",
+    expected_output=(
+        "A valid JSON object with this structure:\n"
+        "{\n"
+        '  "title": "string (Arabic curriculum title)",\n'
+        '  "units": [\n'
+        "    {\n"
+        '      "unit_title": "string (Arabic, must reflect the title)",\n'
+        '      "topics": ["topic1", "topic2", "topic3", "topic4", "topic5"]\n'
+        "    }, ... (4 units total)\n"
+        "  ]\n"
+        "}\n"
+        "The output must be valid JSON, without markdown formatting or code blocks."
+    ),
+    output_json=CurriculumOutline,
+    # output_file=os.path.join(output_dir, "curriculum_outline.json"),
+    agent=designer_agent,
+)

agents/outliner_phase/review_agent_4.py

@@ -0,0 +1,35 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+from schemas import CurriculumOutline
+
+# ---------------------------
+# === Agent 4: Final Reviewer (اختياري) ===
+# ---------------------------
+review_agent = Agent(
+    role="Final Review Agent",
+    goal=(
+        "راجع الناتج النهائي (4 وحدات × 5 مواضيع). صحح اللغة، احذف التكرار، وحسّن العناوين لتكون واضحة "
+        "وتتماشى مع الأسلوب التدريبي. تأكد أن 'title' يطابق الـ topic المدخل (بالعربية)."
+    ),
+    backstory=(
+        "أنت محرر تعليمي يركز على وضوح الصياغة والاتساق. لا تغيّر المحتوى الجوهري، فقط حسن الصياغة."
+    ),
+    llm=llm,
+    allow_delegation=False,
+    verbose=True,
+)
+
+
+review_task = Task(
+    description="مراجعة نهائية لغوية وتنسيقية للـ Curriculum النهائي.",
+    expected_output=(
+        "Final polished JSON identical in structure to CurriculumOutline, "
+        "with clear Arabic titles and consistent formatting. "
+        "The output must be valid JSON, without markdown formatting or code blocks."
+    ),
+    output_json=CurriculumOutline,
+    # output_file=os.path.join(output_dir, "curriculum_outline_final.json"),
+    agent=review_agent,
+)

agents/outliner_phase/topic_expander_2.py

@@ -0,0 +1,43 @@
+from crewai import Agent, Task, Crew, Process, LLM
+import os
+import json
+from modules import llm
+from schemas import ExpandedTopicsList
+
+# ---------------------------
+# === Agent 2: Expander to 20 Topics ===
+# ---------------------------
+structure_agent = Agent(
+    role="Expander to 20 Topics Agent (Structure & Relations)",
+    goal=(
+        "استلم قائمة المحاور المبدئية من Agent1. راجعها لإزالة التكرار ودمج المتقارب منها، "
+        "ثم أكمل ووسع القائمة لتصل إلى **بالضبط 20 محورًا** مترابطًا. "
+        "لكل محور اكتب وصفًا تفصيليًا 3-5 سطور يشرح محتوى المحور، ولماذا هو مهم، "
+        "واذكر علاقات واضحة بين المحاور (مثال: 'مرتبط بـ X لأن...'، أو 'يأتي بعد Y لأنه...'). "
+        "لا تقسم الوحدات بعد — فقط اضمن اتساق وترابط المحاور الـ20."
+    ),
+    backstory=(
+        "أنت مصمم تعليمي بارع في بناء التسلسل المنطقي بين الموضوعات. مهمتك تحويل قائمة أولية "
+        "إلى خريطة معرفية من 20 محورًا."
+    ),
+    llm=llm,
+    allow_delegation=False,
+    verbose=True,
+)
+
+
+structure_task = Task(
+    description="تنظيف القائمة السابقة وتوسيعها لتصل إلى 20 محورًا مترابطًا مع وصف مفصل.",
+    expected_output=(
+        "A JSON list of exactly 20 items:\n"
+        "[\n"
+        '  { "title": "string (topic title)",\n'
+        '    "description": "string (3–5 lines)",\n'
+        '    "relation": "string (e.g., related to X because...)" }\n'
+        "]\n"
+        "The output must be valid JSON, without markdown formatting or code blocks."
+    ),
+    output_json=ExpandedTopicsList,
+    # output_file=os.path.join(output_dir, "expanded_20_topics.json"),
+    agent=structure_agent,
+)

app.py

@@ -0,0 +1,60 @@
+import os
+import shutil
+# Force HOME to /tmp so CrewAI doesn't try writing to /.local
+os.environ["HOME"] = "/tmp"
+os.environ["XDG_DATA_HOME"] = "/tmp/.local/share"
+os.environ["CREWAI_STORAGE_PATH"] = "/tmp/crewai_data"
+os.environ["CREWAI_HOME"] = "/tmp/crewai_home"
+
+# Create safe directories
+os.makedirs("/tmp/.local/share", exist_ok=True)
+os.makedirs("/tmp/crewai_data", exist_ok=True)
+os.makedirs("/tmp/crewai_home", exist_ok=True)
+from crewai import Crew, Process
+import json
+from fastapi import FastAPI
+from routers import objective_route, outliner_route, outcome_route,introduction_route
+
+
+app = FastAPI(title="AI Agent Project", version="1.0.0")
+
+app.include_router(outliner_route.router)
+app.include_router(objective_route.router)
+app.include_router(outcome_route.router)
+app.include_router(introduction_route.router)
+
+# Clear Cashe
+@app.get("/reset-cache")
+def reset_cache():
+
+    paths = [
+        "/tmp/crewai_data",
+        "/tmp/crewai_home",
+        "/tmp/.local/share",
+    ]
+
+    for path in paths:
+        if os.path.exists(path):
+            shutil.rmtree(path, ignore_errors=True)
+
+    os.makedirs("/tmp/crewai_data", exist_ok=True)
+    os.makedirs("/tmp/crewai_home", exist_ok=True)
+    os.makedirs("/tmp/.local/share", exist_ok=True)
+
+    return {"message": "✅ Cache cleared successfully."}
+
+
+# Example root endpoint
+@app.get("/")
+def read_root():
+    return {"message": "Welcome to AI Agent Project API 🚀"}
+
+
+# ------------------------
+# ✅ نقطة تشغيل السيرفر
+# ------------------------
+
+# if __name__ == "__main__":
+#     import uvicorn
+
+#     uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

modules/__init__.py

@@ -0,0 +1,28 @@
+from .env import (
+    llm,
+    llm_g,
+    llm_5m,
+    llm_4m,
+    llm_5n,
+    llm_oss,
+    llm_open_c3,
+    llm_open_c35,
+    model,
+)
+from .inputs import (
+    TRUSTED_SITES,
+    bloom_taxonomy_1,
+    bloom_taxonomy_2,
+    html_template,
+    objectives_dimensions,
+    # outlines,
+    # objectives,
+)
+
+# from .directory import (
+#     output_dir,
+#     keywords_dir,
+#     outliner_dir,
+#     scraper_dir,
+#     urls_dir
+# )

modules/directory.py

@@ -0,0 +1,12 @@
+# import os
+
+# current_dir = os.path.dirname(os.path.abspath(__file__))
+# base_dir = os.path.dirname(current_dir)
+
+# output_dir = os.path.join(base_dir, "assets", "ai_agent_output")
+# keywords_dir = os.path.join(base_dir, "assets", "keywords")
+# outliner_dir = os.path.join(base_dir, "assets", "outliner_sections")
+# scraper_dir = os.path.join(base_dir, "assets", "scraped_data")
+# urls_dir = os.path.join(base_dir, "assets", "urls")
+
+

modules/env.py

@@ -0,0 +1,73 @@
+from crewai import LLM
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+from langchain_openai import ChatOpenAI
+
+env_path = Path(__file__).resolve().parents[1] / ".env"
+# Load variables from .env file
+load_dotenv(dotenv_path=env_path)
+
+# Now you can access them
+gemini_key = os.getenv("GEMINI_API_KEY")
+tavily_key = os.getenv("TAVILY_API_KEY")
+openrouter_key = os.getenv("OPENROUTER_API_KEY")
+os.environ["ANTHROPIC_API_KEY"] = openrouter_key
+# llm = LLM(model="gemini/gemini-2.5-flash", temperature=0, api_key=gemini_key)
+llm = LLM(
+    model="openrouter/openai/gpt-oss-20b:free",
+    api_key=openrouter_key,
+    base_url="https://openrouter.ai/api/v1",
+)
+llm_oss = LLM(
+    model="openrouter/openai/gpt-oss-20b:free",
+    api_key=openrouter_key,
+    base_url="https://openrouter.ai/api/v1",
+)
+
+
+llm_g = LLM(
+    model="openrouter/google/gemini-2.5-flash",
+    temperature=0,
+    api_key=openrouter_key,
+    base_url="https://openrouter.ai/api/v1",
+)
+
+llm_5m = LLM(
+    model="gpt-5-mini-2025-08-07",
+)
+
+llm_4m = LLM(
+    model="gpt-4.1-mini-2025-04-14",
+)
+
+llm_5n = LLM(
+    model="gpt-5-nano-2025-08-07",
+)
+
+llm_open_c3 = LLM(
+    api_key=os.environ["OPENROUTER_API_KEY"],
+    base_url="https://openrouter.ai/api/v1",
+    model="openrouter/anthropic/claude-3-haiku",
+    streaming=False,
+)
+
+llm_open_c35 = LLM(
+    api_key=os.environ["OPENROUTER_API_KEY"],
+    base_url="https://openrouter.ai/api/v1",
+    model="openrouter/anthropic/claude-3.5-haiku",
+    streaming=False,
+)
+
+# Initialize Gemini model
+model = ChatOpenAI(
+    model="google/gemini-2.5-flash",
+    temperature=0,
+    api_key=openrouter_key,
+    base_url="https://openrouter.ai/api/v1",
+)
+
+
+# # check llm
+# response=llm_g.call("Hello, how are you?")
+# print(response)

modules/inputs.py

@@ -0,0 +1,736 @@
+import os 
+import json
+# from .directory import output_dir
+###################--Inputs--#######################
+"""
+/*********************************************************************************************************************************************/
+title="The main topic to generate an outline for",
+description="The specific subject or concept that the outline should focus on. Example: 'Time Management', 'Machine Learning Basics', 'Healthy Nutrition'")
+/*********************************************************************************************************************************************/
+title="Knowledge domain",
+description="The broader field of knowledge or industry where the topic belongs. Example: IT, Engineering, Education, Healthcare, Business"
+/*********************************************************************************************************************************************/
+title="Type of content",
+description=(
+            "Educational → for structured learning (e.g., lessons, modules)\n"
+            "Awareness → for informative/raising awareness purposes (e.g., campaigns, workshops)\n"
+            "Training → for skill development with step-by-step practice (e.g., hands-on, exercises)"
+            )
+/*********************************************************************************************************************************************/
+title="Target audience",
+description=(
+            "The group of people intended to benefit from the material. Example:\n"
+            "- Kids (age 6–12)\n"
+            "- High School Students (teenagers)\n"
+            "- University Students (academic level)\n"
+            "- Professionals (working individuals)\n"
+            "- General Public (all ages, non-technical)"
+        )
+/*********************************************************************************************************************************************/
+title="Nature of the scientific material",
+description=(
+            "Defines the learning approach:\n"
+            "- Conceptual → focuses on theories, principles, and abstract knowledge.\n"
+            "- Procedural → step-by-step methods, instructions, or processes.\n"
+            "- Structural → frameworks, models, and organized structures.\n"
+            "- Personal → reflections, personal skills, and self-development aspects.\n"
+            "- Realistic → practical, case-based, real-world examples and applications."
+        )
+/*********************************************************************************************************************************************/
+
+"""
+
+#     inputs={
+#         "topic":"بدله الفضاء",
+#         "domain": "Aerospace Engineering",
+#         "content_type": "Educational",
+#         "audience": "University Students",
+#         "material_type": ["Procedural","Realistic","Personal"]
+#     }
+
+
+TRUSTED_SITES = [
+    "scholar.google.com",
+    "researchgate.net",
+    "doaj.org",
+    "scopus.com",
+    "academia.edu",
+    "almanhal.com",
+    "digitallibrary.un.org",
+    "virtuallrc.com",
+    "dlc.dlib.indiana.edu",
+    "pubmed.ncbi.nlm.nih.gov",
+    "arxiv.org",
+    "archiveshub.jisc.ac.uk",
+]
+
+
+###################--BLOOM 1--#######################
+bloom_taxonomy_1 = {
+    "Remember": """The process of recalling facts, terms, concepts, or basic principles from memory
+without necessarily understanding them. This level involves recognition and recall
+of previously learned material, such as definitions, lists, dates, formulas, or key terms.
+The focus is strictly on accurate retrieval, not comprehension or application.
+It is the foundation for higher-order thinking because learners must first be able
+to retrieve information before they can understand, apply, or analyze it.""",
+    "Understand": """The process of constructing meaning from instructional materials and messages.
+It involves explaining ideas or concepts, interpreting information, summarizing content,
+and demonstrating comprehension of facts, rules, or principles. Learners show that they
+grasp the essence of material by restating it in their own words, providing basic
+interpretations, or making connections. At this level, students demonstrate they
+understand the 'what' and 'why' of knowledge rather than just memorizing it.""",
+    "Apply": """The process of using learned material in new and concrete situations.
+It includes executing procedures, implementing methods, or applying principles
+to solve problems. Learners demonstrate their ability to transfer knowledge to
+practical tasks, exercises, or unfamiliar contexts. This involves using facts,
+techniques, and rules in a different way than originally learned, adapting them
+to meet the needs of new situations. Application shows the ability to move beyond
+rote memory and demonstrate understanding through action.""",
+    "Analyze": """The process of examining material in detail and breaking it into smaller components
+to understand its structure and relationships. This involves identifying motives, causes,
+assumptions, or evidence and distinguishing between facts and opinions. Learners also
+draw conclusions, detect patterns, and find evidence to support generalizations.
+Analysis requires uncovering how parts work together and how they contribute
+to the overall meaning or outcome. It is a critical step that prepares learners
+for evaluation and creation.""",
+    "Evaluate": """The process of presenting opinions and defending them by making judgments
+about information, the validity of ideas, or the quality of work based on a set
+of criteria. It includes checking, critiquing, and reviewing by applying logical reasoning
+or evidence. Learners assess the strengths and weaknesses of approaches, solutions,
+or arguments, providing justification for their conclusions. Evaluation demands both
+critical thinking and the ability to apply standards consistently, making it
+a higher-order skill that guides decision-making.""",
+    "Create": """The process of putting elements together to form a novel, functional whole.
+It involves reorganizing concepts into a new pattern or structure, such as through planning,
+design, or production. Learners generate original ideas, propose innovative solutions,
+or produce unique work by combining existing knowledge in new ways. This level requires
+synthesis, imagination, and innovation. Creation is the highest level of Bloom’s taxonomy,
+demonstrating mastery by building something entirely new from prior knowledge
+and skills.""",
+}
+
+
+###################--BLOOM 2--#######################
+
+bloom_taxonomy_2 = {
+    "Remember": {
+        "description": """The process of recalling facts, terms, concepts, or basic principles from memory
+without necessarily understanding them. This level involves recognition and recall
+of previously learned material, such as definitions, lists, dates, formulas, or key terms.
+The focus is strictly on accurate retrieval, not comprehension or application.
+It is the foundation for higher-order thinking because learners must first be able
+to retrieve information before they can understand, apply, or analyze it.""",
+        "Remember_verbs_examples": [
+            "يختار",
+            "يراقب",
+            "يعرض",
+            "ينسخ",
+            "يتهجى",
+            "يُعرّف",
+            "يقتبس",
+            "يقرأ",
+            "يتعرف على",
+            "يحدد",
+            "يكرر",
+            "يكتب",
+            "يعيد سرد",
+            "يصف",
+            "يطابق",
+            "يسمي",
+            "يرقم",
+            "يتلو",
+            "يبحث",
+        ],
+    },
+    "Understand": {
+        "description": """The process of constructing meaning from instructional materials and messages.
+It involves explaining ideas or concepts, interpreting information, summarizing content,
+and demonstrating comprehension of facts, rules, or principles. Learners show that they
+grasp the essence of material by restating it in their own words, providing basic
+interpretations, or making connections. At this level, students demonstrate they
+understand the 'what' and 'why' of knowledge rather than just memorizing it.""",
+        "Understand_verbs_examples": [
+            "يسأل",
+            "يستشهد",
+            "يعمم",
+            "يتنبأ",
+            "يصنف",
+            "يقارن",
+            "يوضح",
+            "يَعُد",
+            "يناقش",
+            "يستدل",
+            "يراجع",
+            "يفسر",
+            "يعرض",
+            "يشرح",
+            "يلخص",
+            "يعبر عن",
+            "يترجم",
+            "يربط",
+            "يصف",
+            "يحول",
+            "يكتشف",
+            "يميز",
+            "يجمع",
+            "يحدد",
+            "يعيد الصياغة",
+            "يلخص",
+        ],
+    },
+    "Apply": {
+        "description": """The process of using learned material in new and concrete situations.
+It includes executing procedures, implementing methods, or applying principles
+to solve problems. Learners demonstrate their ability to transfer knowledge to
+practical tasks, exercises, or unfamiliar contexts. This involves using facts,
+techniques, and rules in a different way than originally learned, adapting them
+to meet the needs of new situations. Application shows the ability to move beyond
+rote memory and demonstrate understanding through action.""",
+        "Apply_verbs_examples": [
+            "يمثل",
+            "يوظف",
+            "يمارس",
+            "يدير",
+            "يجرب",
+            "يبني",
+            "يحسب",
+            "يحاكي",
+            "يحل",
+            "يستخدم",
+            "ينظم",
+            "يطور",
+            "يؤدي",
+            "يخطط",
+            "ينفذ",
+            "يرسم بياني",
+            "يستكمل",
+            "يفحص",
+            "��شرح",
+            "يحرر",
+            "يحمل",
+            "يشغل",
+            "يلون",
+            "يلعب",
+            "يحضر",
+            "يشارك",
+            "يرسم",
+            "يستخدم",
+        ],
+    },
+    "Analyze": {
+        "description": """The process of examining material in detail and breaking it into smaller components
+to understand its structure and relationships. This involves identifying motives, causes,
+assumptions, or evidence and distinguishing between facts and opinions. Learners also
+draw conclusions, detect patterns, and find evidence to support generalizations.
+Analysis requires uncovering how parts work together and how they contribute
+to the overall meaning or outcome. It is a critical step that prepares learners
+for evaluation and creation.""",
+        "Analyze_verbs_examples": [
+            "يحلل",
+            "يفحص",
+            "يحدد الأولويات",
+            "يجد",
+            "يرتب",
+            "يفترض",
+            "يوظف",
+            "يسلط الضوء",
+            "يناقش",
+            "يعيد تنظيم",
+            "يبحث",
+            "يستدل",
+            "يحدد الاختلافات",
+            "يكتشف",
+            "يبسط",
+            "يشرح",
+            "يحذف",
+            "يقارن",
+            "يربط بين",
+            "يستنتج",
+            "يفرق",
+            "يميز",
+            "يفصل",
+            "يقدر",
+            "يرسم الخرائط الذهنية",
+            "يحدد الخطوط العريضة بخطط",
+        ],
+    },
+    "Evaluate": {
+        "description": """The process of presenting opinions and defending them by making judgments
+about information, the validity of ideas, or the quality of work based on a set
+of criteria. It includes checking, critiquing, and reviewing by applying logical reasoning
+or evidence. Learners assess the strengths and weaknesses of approaches, solutions,
+or arguments, providing justification for their conclusions. Evaluation demands both
+critical thinking and the ability to apply standards consistently, making it
+a higher-order skill that guides decision-making.""",
+        "Evaluate_verbs_examples": [
+            "يعطي رأي",
+            "يدحض",
+            "يقيس",
+            "يُقيم",
+            "يجادل",
+            "يقدر",
+            "يقنع",
+            "يثبت",
+            "يعطي الأسباب",
+            "يومي",
+            "يصدر حكم على",
+            "يدعم",
+            "يضع معايير",
+            "يتحقق من صحة",
+            "يقرر",
+            "يفسر",
+            "يحكم على",
+            "يبرر",
+            "يتجادل",
+            "ينتقد",
+            "يناقش",
+            "يدافع",
+            "يحرر",
+            "يفترض",
+            "يقيس",
+            "يراقب",
+            "يتنبأ",
+            "يعيد صياغة",
+        ],
+    },
+    "Create": {
+        "description": """The process of putting elements together to form a novel, functional whole.
+It involves reorganizing concepts into a new pattern or structure, such as through planning,
+design, or production. Learners generate original ideas, propose innovative solutions,
+or produce unique work by combining existing knowledge in new ways. This level requires
+synthesis, imagination, and innovation. Creation is the highest level of Bloom’s taxonomy,
+demonstrating mastery by building something entirely new from prior knowledge
+and skills.""",
+        "Create_verbs_examples": [
+            "يدون",
+            "يتعاون",
+            "يؤلف",
+            "يبني",
+            "يصمم",
+            "يبتكر",
+            "يوجه",
+            "يضع تصور",
+            "يعيد صياغة",
+            "يخترع",
+            "يخلط",
+            "يعيد مزج",
+            "يعدل",
+            "يتفاوض",
+            "يخطط",
+            "ينتج",
+            "يبرمج",
+            "ينشر",
+            "يلعب الأدوار",
+            "يحاكي",
+            "يقترح حل",
+            "يعيد هيكلة",
+            "يكتب",
+        ],
+    },
+}
+
+
+objectives_dimensions = {
+    "Knowledge": {
+        "description": "المجال المعرفي (Cognitive Domain): يركز على العمليات العقلية والفكرية، ويشمل اكتساب المعلومات، الفهم، التطبيق، التحليل، التقييم، والإبداع. يتدرج من مستويات التفكير الدنيا إلى العليا حسب تصنيف بلوم المعدل.",
+        "levels": [
+            {
+                "level_name": "Remember (التذكر)",
+                "description": "استرجاع المعلومات والمعارف من الذاكرة طويلة المدى",
+                "verbs_examples": [
+                    "يذكر",
+                    "يعرف",
+                    "يحدد",
+                    "يصنف",
+                    "يسمي",
+                    "يعدد",
+                    "يسترجع",
+                ],
+            },
+            {
+                "level_name": "Understand (الفهم)",
+                "description": "بناء المعنى من المعلومات الشفهية والمكتوبة والرسومية",
+                "verbs_examples": [
+                    "يفسر",
+                    "يستنتج",
+                    "يصف",
+                    "يناقش",
+                    "يترجم",
+                    "يميز",
+                    "يشرح",
+                    "يلخص",
+                ],
+            },
+            {
+                "level_name": "Apply (التطبيق)",
+                "description": "تنفيذ أو استخدام إجراء معين في موقف محدد",
+                "verbs_examples": [
+                    "يستخدم",
+                    "يطبق",
+                    "يجرب",
+                    "يشرح",
+                    "يبرهن",
+                    "ينفذ",
+                    "يحل",
+                ],
+            },
+            {
+                "level_name": "Analyze (التحليل)",
+                "description": "تقسيم المادة إلى أجزائها المكونة وتحديد العلاقات بينها",
+                "verbs_examples": [
+                    "يحلل",
+                    "يربط",
+                    "يقارن",
+                    "يوازن",
+                    "يفحص",
+                    "يميز",
+                    "يصنف",
+                ],
+            },
+            {
+                "level_name": "Evaluate (التقويم)",
+                "description": "إصدار أحكام بناءً على معايير ومحكات محددة",
+                "verbs_examples": [
+                    "يقيم",
+                    "ينقد",
+                    "يبرر",
+                    "يوازن",
+                    "يحكم",
+                    "يدافع عن",
+                    "يختار",
+                ],
+            },
+            {
+                "level_name": "Create (الإبداع)",
+                "description": "دمج العناصر لتكوين كل متماسك أو وظيفي جديد وإعادة تنظيم العناصر في نمط أو بنية جديدة",
+                "verbs_examples": [
+                    "يصمم",
+                    "يبتكر",
+                    "يطور",
+                    "يؤلف",
+                    "ينشئ",
+                    "يخطط",
+                    "يبني",
+                ],
+            },
+        ],
+    },
+    "Ability": {
+        "description": "المجال الوجداني/الانفعالي (Affective Domain): يتعلق بالمشاعر والاتجاهات والقيم والميول. يتدرج من مجرد الاستقبال السلبي إلى التبني الكامل للقيم وجعلها جزءاً من شخصية المتعلم.",
+        "levels": [
+            {
+                "level_name": "Reception (الاستقبال)",
+                "description": "الوعي والانتباه والاستعداد لاستقبال الظواهر والمثيرات",
+                "verbs_examples": ["ينتبه", "يختار", "يشعر", "يصغي", "يستقبل", "يلاحظ"],
+            },
+            {
+                "level_name": "Response (الاستجابة)",
+                "description": "المشاركة النشطة والتفاعل مع الظواهر والاستجابة لها",
+                "verbs_examples": [
+                    "يستجيب",
+                    "يشارك",
+                    "يعاون",
+                    "يمتثل",
+                    "يتطوع",
+                    "يساعد",
+                    "يناقش",
+                ],
+            },
+            {
+                "level_name": "Valuing (التقييم)",
+                "description": "إعطاء قيمة للأشياء والظواهر والسلوكيات والالتزام بها",
+                "verbs_examples": [
+                    "يقدر",
+                    "يحترم",
+                    "يؤيد",
+                    "يدعم",
+                    "يظهر اقتناعاً",
+                    "يعتز",
+                ],
+            },
+            {
+                "level_name": "Organization (التنظيم)",
+                "description": "تنظيم القيم المختلفة وحل التناقضات بينها وبناء نظام قيمي متسق",
+                "verbs_examples": [
+                    "ينظم",
+                    "يقارن",
+                    "يلتزم",
+                    "يوازن",
+                    "يرت��",
+                    "يدمج",
+                    "يوحد",
+                ],
+            },
+            {
+                "level_name": "Characterization (التمييز/التشخيص)",
+                "description": "امتلاك نظام قيمي يتحكم في السلوك بشكل ثابت ومتسق ويصبح جزءاً من شخصية الفرد",
+                "verbs_examples": [
+                    "يميز",
+                    "يفضل",
+                    "يتبنى",
+                    "يلتزم",
+                    "يمارس",
+                    "يحل",
+                    "يتصرف وفقاً لـ",
+                ],
+            },
+        ],
+    },
+    "Skills": {
+        "description": "المجال المهاري/النفسحركي (Psychomotor Domain): يركز على المهارات الحركية والجسدية التي تتطلب تنسيقاً بين العقل والعضلات. يتدرج من الملاحظة البسيطة إلى الإتقان والإبداع الحركي.",
+        "levels": [
+            {
+                "level_name": "Readiness (الاستعداد)",
+                "description": "الاستعداد الذهني والجسدي والانفعالي للقيام بالمهارة",
+                "verbs_examples": [
+                    "يتهيأ",
+                    "يستعد",
+                    "يظهر رغبة",
+                    "يبدي اهتماماً",
+                    "يتخذ وضعية",
+                ],
+            },
+            {
+                "level_name": "Guided Response/Imitation (الاستجابة الموجهة/التقليد)",
+                "description": "محاكاة وتقليد المهارة تحت الإشراف والتوجيه",
+                "verbs_examples": ["يقلد", "يحاكي", "يكرر", "يتبع", "يجرب", "يستجيب"],
+            },
+            {
+                "level_name": "Mechanism/Practice (الآلية/الممارسة)",
+                "description": "أداء المهارة بثقة ودقة دون الحاجة للتوجيه المستمر",
+                "verbs_examples": ["يمارس", "يطبق", "يؤدي", "ينفذ", "يكمل", "يعمل"],
+            },
+            {
+                "level_name": "Complex Overt Response (الاستجابة الظاهرة المعقدة)",
+                "description": "أداء المهارة بسلاسة وإتقان وبشكل تلقائي",
+                "verbs_examples": [
+                    "يؤدي بسلاسة",
+                    "يستخدم بانتظام",
+                    "يتقن",
+                    "ينجز بمهارة",
+                    "يعمل بكفاءة",
+                ],
+            },
+            {
+                "level_name": "Adaptation (التكيف)",
+                "description": "تعديل وتكييف المهارات لتناسب المواقف المختلفة",
+                "verbs_examples": [
+                    "يعدل",
+                    "يطور",
+                    "يبدل",
+                    "يكيف",
+                    "يعيد تنظيم",
+                    "يحسن",
+                ],
+            },
+            {
+                "level_name": "Origination/Creativity (الإبداع)",
+                "description": "ابتكار حركات وأنماط مهارية جديدة وإبداعية",
+                "verbs_examples": [
+                    "يبتكر",
+                    "يصمم",
+                    "يبدع",
+                    "يخترع",
+                    "يطور أسلوباً جديداً",
+                    "يؤلف",
+                ],
+            },
+        ],
+    },
+}
+###############################################################
+html_template = """
+        <!DOCTYPE html>
+        <html lang="ar" dir="rtl">
+
+        <head>
+          <meta charset="UTF-8">
+          <title>مرحلة التحليل</title>
+          <style>
+            body {
+              font-family: "Tahoma", sans-serif;
+              direction: rtl;
+              margin: 0;
+              padding: 0;
+            }
+
+            .header {
+              background: #c79810;
+              /* ذهبي */
+              color: white;
+              text-align: center;
+              font-weight: bold;
+              padding: 12px;
+              font-size: 20px;
+            }
+
+            .sub-header {
+              background: #000;
+              color: white;
+              text-align: center;
+              padding: 10px;
+              font-size: 16px;
+              font-weight: bold;
+            }
+
+            table {
+              width: 100%;
+              border-collapse: collapse;
+            }
+
+            td {
+              border: 1px solid #000;
+              padding: 8px 12px;
+              vertical-align: top;
+              line-height: 1.6;
+            }
+
+            .main-col {
+              background: #666;
+              color: white;
+              width: 20%;
+              font-weight: bold;
+              text-align: center;
+            }
+
+            .sub-col {
+              background: #e6e6e6;
+              width: 20%;
+              font-weight: bold;
+              text-align: right;
+            }
+
+            ul {
+              margin: 6px 0;
+              padding-right: 20px;
+            }
+          </style>
+        </head>
+
+        <body>
+
+          <div class="header">إدارة الوقت</div>
+          <div class="sub-header">مرحلة التحليل</div>
+
+          <table>
+            <!-- الهدف -->
+            <tr>
+              <td class="main-col">المتوقع تحقيقه (النهائي)</td>
+              <td colspan="2">
+                أن يتمكّن المتدرب من اكتساب مهارة إدارة وقته بفعالية، من خلال فهم المفهوم والأسس،
+                وتطبيق المهارات والتقنيات العملية، بما ينعكس على إنجاز أهدافه الشخصية والعملية بكفاءة عالية.
+              </td>
+            </tr>
+
+            <!-- الفئة المستهدفة -->
+            <tr>
+              <td class="main-col" rowspan="4">الفئة المستهدفة</td>
+              <td class="sub-col">أعمارهم</td>
+              <td>18 إلى 35 عامًا.</td>
+            </tr>
+
+            <tr>
+              <td class="sub-col">الخبرات السابقة</td>
+              <td>
+                <ul>
+                  <li>ممارسة أعمال أو مهام تتطلب التخطيط أو التنظيم.</li>
+                  <li>حضور أنشطة أو دورات سابقة في التنمية الذاتية أو المهارات الحياتية.</li>
+                  <li>إلمام جزئي بأساسيات إدارة العمل أو الأنشطة التربوية.</li>
+                </ul>
+              </td>
+            </tr>
+
+            <tr>
+              <td class="sub-col">خصائص المتدربين</td>
+              <td>
+                <ul>
+                  <li>امتلاك حصيلة لغوية جيدة مع قدرة على التعبير.</li>
+                  <li>القدرة على التفكير التحليلي والمنطقي وحل المشكلات.</li>
+                  <li>الرغبة في التفاعل مع المجموعات وتقدير العلاقات القائمة على الاحترام.</li>
+                  <li>ميل قوي للاستقلالية في اتخاذ القرارات وحمل المسؤوليات.</li>
+                  <li>ظهور ميول متزايدة بالذات والحاجة إلى التحكم في الانفعالات.</li>
+                  <li>السعي لتطوير الهوية الذاتية والاجتماعية وتعزيز الثقة بالنفس.</li>
+                  <li>تفضيل التعلم التفاعلي القائم على الأنشطة التطبيقية.</li>
+                </ul>
+              </td>
+            </tr>
+
+            <tr>
+              <td class="sub-col">احتياجات المتدربين</td>
+              <td>
+                <ul>
+                  <li>تمييز أسباب ضياع الوقت الشخصي والتنظيمي.</li>
+                  <li>تحقيق التوازن بين المهام والأهداف.</li>
+                  <li>امتلاك أدوات عملية لتحديد الأولويات.</li>
+                  <li>استخدام تقنيات جديدة أكثر كفاءة.</li>
+                  <li>ضبط التوتر الناتج عن ضغوط المهام.</li>
+                  <li>أساليب مجرَّبة ناجحة في استثمار الوقت.</li>
+                </ul>
+              </td>
+            </tr>
+
+            <!-- القيود -->
+            <tr>
+              <td class="main-col" rowspan="2">القيود</td>
+              <td class="sub-col">بالنسبة للمدرب</td>
+              <td>
+                <ul>
+                  <li>صعوبة التعامل مع تفاوت الخلفيات المعرفية.</li>
+                  <li>محدودية الوقت المخصص للأنشطة التدريبية.</li>
+                  <li>حاجة إلى تكييف الأمثلة بما يناسب الجمهور.</li>
+                  <li>صعوبة متابعة الأداء الفردي لجميع المتدربين.</li>
+                </ul>
+              </td>
+            </tr>
+            <tr>
+              <td class="sub-col">بالنسبة للمتدرب</td>
+              <td>
+                <ul>
+                  <li>محدودية الخبرة السابقة في إدارة الوقت.</li>
+                  <li>صعوبة الالتزام بجميع التمارين المقترحة.</li>
+                  <li>التأثر بالضغوط الشخصية والاجتماعية.</li>
+                  <li>مقاومة تغيي�� العادات السلبية القديمة.</li>
+                </ul>
+              </td>
+            </tr>
+
+            <!-- المدة الزمنية -->
+            <tr>
+              <td class="main-col">المدة الزمنية</td>
+              <td colspan="2">مدة الكورس محسوبة بعدد الأيام (اليوم = 4 ساعات).</td>
+            </tr>
+
+            <!-- جمع البيانات -->
+            <tr>
+              <td class="main-col">جمع البيانات وتحليلها</td>
+              <td colspan="2">
+                <ul>
+                  <li>تحديد محاور الدورة التدريبية.</li>
+                  <li>تحليل الاحتياجات التدريبية.</li>
+                  <li>تحديد الفجوات المعرفية والمهارية.</li>
+                  <li>تصميم أنشطة لمعالجة الفجوات.</li>
+                  <li>تجريب الأنشطة وتقييمها.</li>
+                  <li>تطوير الأنشطة وتحسينها.</li>
+                </ul>
+              </td>
+            </tr>
+          </table>
+
+        </body>
+
+        </html>
+        """
+
+
+##########################################################
+# # This is an input For  === Objectives Agent ===
+# with open(os.path.join(output_dir, "curriculum_outline_final.json"), "r", encoding="utf-8") as f:
+#     outlines = json.load(f)
+
+# # This is an input For  === Outcomes Agent ===
+# with open(
+#     os.path.join(output_dir, "step_analysis_2_objectives.json"),
+#     "r",
+#     encoding="utf-8",
+# ) as f:
+#     objectives = json.load(f)

requirements.txt

@@ -0,0 +1,15 @@
+crewai[tools]
+tavily-python
+scrapegraph-py
+scrapegraphai
+PyPDF2
+reportlab
+langchain_openai
+litellm
+openai
+fastapi
+crewai[anthropic]
+crewai[google-genai]
+langchain
+langchain_core
+langchain-community

routers/introduction_route.py

@@ -0,0 +1,59 @@
+import os
+from crewai import Crew, Process
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from agents.analysis_phase import (
+    intro_agent,
+    intro_task,
+)
+from modules import (
+    llm,
+    inputs,
+)
+from schemas import (
+    ValidatedCurriculumOutput,
+    LearningOutcomesOutput,
+    DNAMetadata,
+    OutlineInput,
+)
+
+
+router = APIRouter(prefix="/analysis", tags=["Introduction"])
+
+# ------------------------------------
+# === Agent 7:Training Generator ===
+# ------------------------------------
+
+
+@router.post("/introduction")
+def run_training(
+    data: OutlineInput,
+    outlines: ValidatedCurriculumOutput,
+    outcomes: LearningOutcomesOutput,
+    units:dict,
+):
+    training_crew = Crew(
+        agents=[intro_agent],
+        tasks=[intro_task],
+        process=Process.sequential,
+    )
+
+    inputs = data.dict()
+    user_inputs = DNAMetadata(
+        topic=inputs["topic"],
+        domain=inputs["domain"],
+        content_type=inputs["content_type"],
+        audience=inputs["audience"],
+        material_type=inputs["material_type"],
+    ).dict()
+
+    merged_inputs = {
+        **user_inputs,
+        "outlines": outlines.dict(),
+        "outcomes": outcomes.dict(),
+        "units": units,
+    }
+    result = training_crew.kickoff(inputs=merged_inputs)
+    print(result.json_dict)
+
+    return {"message": "Introduction Generated Well 🚀", "result": result}

routers/objective_route.py

@@ -0,0 +1,51 @@
+import os
+from crewai import Crew, Process
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from agents.analysis_phase import (
+    objectives_generator,
+    objectives_task,
+)
+from modules import (
+    llm_g,
+    inputs,
+)
+from schemas import (
+    ValidatedCurriculumOutput,
+    DNAMetadata,
+    OutlineInput,
+)
+
+
+router = APIRouter(prefix="/analysis", tags=["Objectives"])
+
+
+# ------------------------------------
+# === Agent 5:Objectives Generator ===
+# ------------------------------------
+
+
+@router.post("/objectives")
+def run_objectives(
+    data: OutlineInput, outlines: ValidatedCurriculumOutput, units: dict
+):
+    objectives_crew = Crew(
+        agents=[objectives_generator],
+        tasks=[objectives_task],
+        process=Process.sequential,
+    )
+    inputs = data.dict()
+    user_inputs = DNAMetadata(
+        topic=inputs["topic"],
+        domain=inputs["domain"],
+        content_type=inputs["content_type"],
+        audience=inputs["audience"],
+        material_type=inputs["material_type"],
+    ).dict()
+    merged_inputs = {**user_inputs, "units":units,"outlines": outlines.dict()}
+
+    result = objectives_crew.kickoff(inputs=merged_inputs)
+
+    print(result.json_dict)
+
+    return {"message": "Objectives Generated Well 🚀", "result": result}

routers/outcome_route.py

@@ -0,0 +1,50 @@
+import os
+from crewai import Crew, Process
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from agents.analysis_phase import (
+    outcomes_generator,
+    outcomes_task,
+)
+from modules import (
+    llm_g,
+    inputs,
+)
+from schemas import (
+    ObjectivesOutput,
+    LearningObjectivesOutput,
+    DNAMetadata,
+    OutlineInput,
+)
+
+
+router = APIRouter(prefix="/analysis", tags=["outcomes"])
+
+
+# ------------------------------------
+# === Agent 6:Outcomes Generator ===
+# ------------------------------------
+
+
+@router.post("/outcomes")
+def run_outcomes(data: OutlineInput, objectives: LearningObjectivesOutput):
+    outcomes_crew = Crew(
+        agents=[outcomes_generator],
+        tasks=[outcomes_task],
+        process=Process.sequential,
+    )
+
+    inputs = data.dict()
+    user_inputs = DNAMetadata(
+        topic=inputs["topic"],
+        domain=inputs["domain"],
+        content_type=inputs["content_type"],
+        audience=inputs["audience"],
+        material_type=inputs["material_type"],
+    ).dict()
+    merged_inputs = {**user_inputs, "objectives": objectives.dict()}
+
+    result = outcomes_crew.kickoff(inputs=merged_inputs)
+    print(result.json_dict)
+
+    return {"message": "Outcomes Generated Well 🚀", "result": result}

routers/outliner_route.py

@@ -0,0 +1,66 @@
+import os
+from crewai import Crew, Process
+import json
+from fastapi import APIRouter, HTTPException, Depends
+from agents.final_outliners import (
+    subtopics_generator_agent,
+    subtopics_generation_task,
+    validator_agent,
+    validation_task,
+    units_langchain1_agent,
+)
+from modules import (
+    llm_5m,
+    inputs,
+)
+from schemas import (
+    DNAMetadata,
+    OutlineInput,
+)
+
+
+router = APIRouter(prefix="/outliner", tags=["Outliner"])
+
+
+# === Agent 1: Unit Generator ===
+# === Agent 2: Axis Generator===
+# === Agent 3: Validator ===
+# === Agent 4: Final Reviewer (اختياري) ===
+# -----------------------------------------------
+@router.post("/run_outliner_agents")
+def run_outliner_agents(data: OutlineInput):
+    outline_crew = Crew(
+        agents=[subtopics_generator_agent, validator_agent],
+        tasks=[subtopics_generation_task, validation_task],
+        process=Process.sequential,
+    )
+
+    inputs = data.dict()
+    user_inputs = DNAMetadata(
+        topic=inputs["topic"],
+        domain=inputs["domain"],
+        content_type=inputs["content_type"],
+        audience=inputs["audience"],
+        material_type=inputs["material_type"],
+        note=inputs["note"],
+    ).dict()
+
+    units = units_langchain1_agent(
+        topic=inputs["topic"], units_number=inputs["units_number"]
+    )
+
+    merged_input = {
+        **user_inputs,
+        "units": units,
+    }
+
+    result = outline_crew.kickoff(inputs=merged_input)
+
+    print("units: ", units)
+    print("-" * 50)
+    print("final result: ", result.json_dict)
+    return {
+        "message": "Outliner Generators works well 🚀",
+        "result": result,
+        "units": units,
+    }

schemas/__init__.py

@@ -0,0 +1,19 @@
+from .analysis_schema import AnalysisOutput
+from .dna_schema import DNAMetadata
+from .extractor_schema import AllPartsOfContent, SinglePartOfContent, Section
+from .keywoard_schema import SuggestedSearchQueries
+from .objectives_schema import ObjectivesOutput, LearningObjectivesOutput
+from .outcomes_schema import LearningOutcomesOutput
+from .outliner_schema import (
+    Subtopic,
+    UnitWithAxes,
+    FullCurriculumStructure,
+    ValidatedAxis,
+    ValidatedUnit,
+    ValidatedCurriculumOutput,
+    validated_parser,
+)
+
+from .source_schema import AllResults, SingleResult
+from .introduction_schema import IntroductionOutput
+from .inputs_schema import OutlineInput

schemas/analysis_schema.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+# ====== Pydantic Model for Analysis Phase ======
+class AnalysisOutput(BaseModel):
+    goal: str = Field(
+        ...,
+        description="Overall training goal, must start with 'أن يتمكّن المتدرب من...'.",
+    )
+    target_audience: str = Field(
+        ...,
+        description="The target audience group and their average age/professional profile.",
+    )
+    previous_experiences: List[str] = Field(
+        ..., description="3–5 short noun-phrases reflecting prior experiences."
+    )
+    learner_characteristics: List[str] = Field(
+        ..., description="Learner characteristics based on developmental dimensions."
+    )
+    training_needs: List[str] = Field(
+        ...,
+        description="6 noun-phrases representing training needs extracted from course topics.",
+    )
+    constraints: Dict[str, List[str]] = Field(
+        ...,
+        description="Constraints divided into {'trainer': [...], 'trainee': [...]}, 4 noun-phrases each.",
+    )
+    duration: str = Field(..., description="The duration of the course (days/hours).")
+    sources_of_analysis: List[str] = Field(
+        ...,
+        description="Noun-phrases starting and ending with a مصدر, e.g., 'جمع البيانات وتحليلها'.",
+    )

schemas/dna_schema.py

@@ -0,0 +1,82 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+
+# ========= 1. Parameters for DNA methodology + topic =========
+class DNAMetadata(BaseModel):
+    topic: str = Field(
+        ...,
+        title="The main topic to generate an outline for",
+        description="The specific subject or concept that the outline should focus on. Example: 'Time Management', 'Machine Learning Basics', 'Healthy Nutrition'",
+    )
+
+    domain: str = Field(
+        ...,
+        title="Knowledge domain",
+        description="The broader field of knowledge or industry where the topic belongs. Example: IT, Engineering, Education, Healthcare, Business",
+    )
+
+    # content_type: Literal["Educational", "Awareness", "Training"] = Field(
+
+    content_type: str = Field(
+        ...,
+        title="Type of content",
+        description=(
+            "Educational → for structured learning (e.g., lessons, modules)\n"
+            "Awareness → for informative/raising awareness purposes (e.g., campaigns, workshops)\n"
+            "Training → for skill development with step-by-step practice (e.g., hands-on, exercises)"
+        ),
+    )
+
+    # audience: str = Field(
+    #     ...,
+    #     title="Target audience",
+    #     description=(
+    #         "The group of people intended to benefit from the material. Example:\n"
+    #         "- Kids (age 6–12)\n"
+    #         "- High School Students (teenagers)\n"
+    #         "- University Students (academic level)\n"
+    #         "- Professionals (working individuals)\n"
+    #         "- General Public (all ages, non-technical)"
+    #     )
+    # )
+
+    audience: str = Field(
+        ...,
+        title="Target audience",
+        description=(
+            "The group of people intended to benefit from the material. Examples:\n"
+            "- Education (Teachers, Principals, Students, Faculty, Instructional Designers)\n"
+            "- Special Education (Special Needs Teachers, Speech Therapists, Psychologists, ABA Specialists, Children with Disabilities)\n"
+            "- Family & Child (Parents, Counselors, Social Workers, Children, Adolescents, Youth, Elderly)\n"
+            "- Women Empowerment (Mothers, Teenage Girls, Women Entrepreneurs, Researchers, Artists)\n"
+            "- Self-Development (Individuals seeking personal growth, Life Coaches, Students, Graduates, Employees)\n"
+            "- Training (Soft/Technical Skills Trainers, Training Designers, Training Institutes)\n"
+            "- Human Resources (HR Managers, Recruiters, Employee Relations, L&D Officers)\n"
+            "- Management & Leadership (CEOs, Directors, Team Leaders, Consultants, Entrepreneurs)\n"
+            "- Law (Lawyers, Judges, Prosecutors, Legal Advisors, Notaries)\n"
+            "- Public Relations & Media (PR Officers, Journalists, Broadcasters, Media Professionals)\n"
+            "- Marketing & Sales (Marketing Managers, Sales Representatives, Digital Marketing Specialists, Content Creators)\n"
+            "- Technology & IT (Software Developers, Data Scientists, AI Engineers, Cybersecurity Specialists)\n"
+            "- Languages & Translation (Translators, Interpreters, Language Teachers, Proofreaders)\n"
+            "- Medicine & Nutrition (Doctors, Nurses, Pharmacists, Nutritionists, Mental Health Specialists)\n"
+            "- Occupational Health & Safety (HSE Officers, Safety Inspectors, First Aid Trainers)\n"
+            "- Sports (Athletes, Coaches, Referees, Nutritionists, Physiotherapists)\n"
+            "- Arts & Fashion (Artists, Designers, Photographers, Art Directors)"
+        ),
+    )
+
+    material_type: List[str] = Field(
+        ...,
+        title="Nature of the scientific material",
+        description=(
+            "Defines the learning approach:\n"
+            "- Conceptual → focuses on theories, principles, and abstract knowledge.\n"
+            "- Procedural → step-by-step methods, instructions, or processes.\n"
+            "- Structural → frameworks, models, and organized structures.\n"
+            "- Personal → reflections, personal skills, and self-development aspects.\n"
+            "- Realistic → practical, case-based, real-world examples and applications."
+        ),
+    )
+
+    note: Optional[str] = None

schemas/extractor_schema.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+class Section(BaseModel):
+    heading: str
+    text: str
+
+class SinglePartOfContent(BaseModel):
+  page_url: str = Field(..., title="URL of the page containing the content")
+  title: str = Field(..., title="Title of the content")
+  sections: List[Section] = Field(..., title="Sections of the content")
+  img_url: List[str] = Field( title="URL of the image associated with the content")
+  video_url: List[str] = Field( title="URL of the video associated with the content")
+  audio_url: List[str] = Field( title="URL of the audio associated with the content")
+  pdf_url: List[str] = Field( title="URL of the pdf associated with the content")
+  agent_recommendation_rank: float = Field(..., title="Rank of the content as per the agent recommendation, (out of 5, Higher is Better) in the recommendation list ordering from the best to the worst")
+  agent_recommendation_notes: str = Field(..., title="A set of notes why would you recommend or not recommend this content to the company")
+  header: str = Field(..., title="the header this content belongs to")
+  sub_header: str = Field(..., title="the sub_header this content belongs to")
+
+class AllPartsOfContent(BaseModel):
+  parts: List[SinglePartOfContent]

schemas/inputs_schema.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel
+
+
+# Step 1️⃣: Create a Pydantic model for inputs
+class OutlineInput(BaseModel):
+    topic: str
+    domain: str
+    content_type: str
+    audience: str
+    material_type: list
+    units_number: int
+    note: str
+
+
+# {
+# "topic": "إدارة الوقت",
+# "domain": "Management",
+# "content_type": "Educational",
+# "audience": "kids",
+# "material_type": ["Procedural", "Realistic", "Personal"],
+# }
+
+# {
+#     "topic": "(Design thinking) تقنيات التفكير التصميمي لحل المشكلات واتخاذ القرارات",
+#     "domain": "Management",
+#     "content_type": "تدريبي",
+#     "audience": "القادة والموظفون والإداريون",
+#     "material_type": ["مفاهمية", "هيكلية", "شخصية", "واقعية", "اجرائية"],
+# }

schemas/introduction_schema.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+
+class IntroductionOutput(BaseModel):
+    introduction: str = Field(
+        ...,
+        title="Introduction",
+        description="engaging introduction to the training program content, max 300 words.",
+    )

schemas/keywoard_schema.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+
+no_keywords = 25
+
+
+class SuggestedSearchQueries(BaseModel):
+    queries: List[str] = Field(
+        ...,
+        title="List of suggested search queries",
+        min_items=1,
+        max_items=no_keywords,
+    )

schemas/objectives_schema.py

@@ -0,0 +1,65 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class Objective(BaseModel):
+    unit: str = Field(..., description="The title of the unit.")
+    unit_description: str = Field(..., description="A brief summary of the unit scope.")
+    subtopic: str = Field(..., description="The title of the subtopic (axis).")
+    module_description: str = Field(
+        ..., description="A brief summary of what this subtopic covers."
+    )
+    level: str = Field(
+        ..., description="Bloom's level assigned based on subtopic analysis."
+    )
+    verbs: List[str] = Field(
+        ..., description="A list of verbs used to define the learning objective."
+    )
+    objective: str = Field(
+        ...,
+        description="A measurable Arabic objective derived from the subtopic purpose.",
+    )
+
+
+class ObjectivesOutput(BaseModel):
+    objectives: List[Objective] = Field(
+        ...,
+        description="List of objectives including unit, subtopic, and measurable goals.",
+    )
+
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+
+class LearningObjective(BaseModel):
+    """Schema for a single learning objective"""
+
+    unit: str = Field(description="The title of the unit this objective belongs to")
+    unit_description: str = Field(
+        description="Brief summary of the unit scope and learning journey"
+    )
+    subtopic: str = Field(description="The title of the specific subtopic")
+    module_description: str = Field(
+        description="Brief summary of what this subtopic covers"
+    )
+    level: str = Field(
+        description="Bloom's Taxonomy level or learning domain level assigned based on subtopic analysis"
+    )
+    verbs: List[str] = Field(
+        description="List of three relevant Bloom's verbs suitable for the audience",
+        min_items=3,
+        max_items=3,
+    )
+    objective: str = Field(
+        description="One measurable learning objective in Arabic derived from the subtopic purpose"
+    )
+
+
+class LearningObjectivesOutput(BaseModel):
+    """Schema for the complete learning objectives output"""
+
+    objectives: List[LearningObjective] = Field(
+        description="Complete list of learning objectives for all subtopics in the curriculum"
+    )

schemas/outcomes_schema.py

@@ -0,0 +1,28 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class LearningOutcomeItem(BaseModel):
+    unit: str = Field(
+        ...,
+        description="The title of the training unit for which the outcome is designed.",
+    )
+    unit_description: str = Field(
+        ...,
+        description="A brief summary describing the scope and purpose of this unit.",
+    )
+    unit_outcome: str = Field(
+        ...,
+        description=(
+            "One concise, measurable Arabic learning outcome derived from the unit description "
+            "and its subtopics and their purposes. The outcome should be written in مصدر form (infinitive noun), "
+            "be measurable, realistic, and aligned with Bloom’s taxonomy and DNA methodology."
+        ),
+    )
+
+
+class LearningOutcomesOutput(BaseModel):
+    outcomes: List[LearningOutcomeItem] = Field(
+        ...,
+        description="A list of unit-level Arabic learning outcomes covering all units in the program.",
+    )

schemas/outliner_schema.py

@@ -0,0 +1,207 @@
+import os
+import json
+import requests
+import time
+import re
+from pydantic import BaseModel, Field, ValidationError
+from typing import List, Dict, Literal, Optional
+from .dna_schema import DNAMetadata
+
+
+################==NEW==################
+class Subtopic(BaseModel):
+    """
+    Represents a single subtopic within an educational unit.
+
+    Each subtopic embodies a progressive learning step that moves from
+    basic understanding toward higher-order thinking such as
+    application, analysis, or creative synthesis.
+    """
+
+    subtopic_number: int = Field(
+        ...,
+        title="Subtopic Number",
+        description="The sequential order of this subtopic within the unit.",
+    )
+
+    title: str = Field(
+        ...,
+        title="Subtopic Title",
+        description=(
+            "The Arabic title of the subtopic inside the unit. "
+            "Each subtopic defines a distinct conceptual or cognitive step "
+            "that contributes to the overall unit progression."
+        ),
+    )
+
+    purpose: str = Field(
+        ...,
+        title="Subtopic Purpose",
+        description=(
+            "A concise statements describing the educational intent of this subtopic — "
+            "what learners should achieve cognitively (e.g., understanding, applying, analyzing, creating)."
+        ),
+    )
+
+
+############################################################################################################
+class UnitWithAxes(BaseModel):
+    """
+    Represents a curriculum unit that contains multiple learning subtopics.
+
+    Each unit defines a coherent topic focus and consists of number of subtopics,
+    each representing a structured subtopic or cognitive level that guides
+    the learner progressively from comprehension to advanced application.
+    """
+
+    unit_number: int = Field(
+        ...,
+        title="The sequential number of this unit within the overall curriculum (e.g., 1, 2, 3).",
+    )
+
+    title: str = Field(
+        ...,
+        title="Unit Title",
+        description="The Arabic title or name of the educational unit, clearly representing its theme or purpose.",
+    )
+
+    focus: str = Field(
+        ...,
+        title="Unit Focus",
+        description=(
+            "A concise overview highlighting the main concepts, skills, and learning outcomes "
+            "covered in this unit. It describes what learners should understand or achieve after completing it."
+            "It sets the intellectual direction for the included subtopics."
+        ),
+    )
+
+    subtopics: List[Subtopic] = Field(
+        ...,
+        title="Unit Subtopics",
+        description=(
+            "A list of coherent Arabic subtopics that make up the unit. "
+            "Each subtopic represents a progressive cognitive step — from foundational understanding "
+            "to creative synthesis — ensuring a balanced learning journey."
+        ),
+    )
+
+
+############################################################################################################
+class FullCurriculumStructure(BaseModel):
+    """
+    Represents the complete process of subtopic generation for an educational curriculum.
+
+    This model integrates educational metadata (via DNAMetadata), the conceptual hierarchy
+    (main and related concepts), and the pedagogical structure (units and subtopics).
+    It serves as the core structure for AI-driven generation, evaluation, and organization
+    of educational subtopics aligned with learner needs and content goals.
+    """
+
+    Metadata: List["DNAMetadata"] = Field(
+        ...,
+        title="List of DNA Metadata Objects",
+        description=(
+            "A list of DNAMetadata items, where each item represents a distinct topic or concept "
+            "along with its domain, audience, content type, and material nature.\n"
+            "This allows the agent to process multiple curriculum components or educational segments "
+            "within a single structured input."
+        ),
+    )
+
+    main_concept: str = Field(
+        ...,
+        title="Main Concept",
+        description=(
+            "The central or core idea around which the curriculum is built. "
+            "It defines the overarching theme that connects all units and topics together."
+        ),
+    )
+
+    related_concepts: List[str] = Field(
+        ...,
+        title="Related Concepts",
+        description=(
+            "A set of secondary or supporting ideas that complement or expand upon the main concept. "
+            "These help the agent establish conceptual links and subtopics within the curriculum."
+        ),
+    )
+
+    units: List[UnitWithAxes] = Field(
+        ...,
+        title="Units with Subtopics",
+        description=(
+            "A structured list of educational units. Each unit includes its title, "
+            "conceptual focus, and number of well-defined subtopics that progressively develop the learner’s understanding."
+        ),
+    )
+
+
+############################################################################################################
+# ---- Custom Pydantic parser ----
+class PydanticOutputParser:
+    """Safely parses model output into a Pydantic schema."""
+
+    def __init__(self, pydantic_object):
+        self.model = pydantic_object
+
+    def parse(self, raw_output: str):
+        # Extract JSON substring between first { and last }
+        match = re.search(r"\{.*\}", raw_output, re.S)
+        if not match:
+            raise ValueError("❌ No JSON object found in model output.")
+        cleaned = match.group()
+        try:
+            return self.model.model_validate_json(cleaned)
+        except ValidationError as e:
+            raise ValueError(f"❌ JSON validation failed: {e}")
+
+
+class ValidatedAxis(BaseModel):
+    """Schema for a validated subtopics"""
+
+    subtopic_number: int = Field(
+        description="Sequential number of the subtopic within the unit", ge=1
+    )
+
+    title: str = Field(
+        description="The improved/validated subtopic title in Arabic (4-8 words, clear, focused)"
+    )
+
+    purpose: str = Field(
+        description="The subtopic purpose explaining its educational intent"
+    )
+    status: Literal["kept", "rephrased", "added", "removed"] = Field(
+        description="Validation status: 'kept' (unchanged), 'rephrased' (edited), 'added' (new), 'removed' (deleted/merged)"
+    )
+
+
+class ValidatedUnit(BaseModel):
+    """Schema for a validated educational unit"""
+
+    unit_number: int = Field(
+        description="Sequential number of the unit in the curriculum", ge=1
+    )
+    title: str = Field(description="The title of the unit in Arabic")
+    focus: str = Field(
+        description="Description of the unit's main educational focus and objectives"
+    )
+    axes: List[ValidatedAxis] = Field(
+        description="List of validated subtopics for this unit", min_items=1
+    )
+
+
+class ValidatedCurriculumOutput(BaseModel):
+    """Schema for the complete validated curriculum output"""
+
+    main_concept: str = Field(
+        description="The main concept or topic of the entire curriculum"
+    )
+    General_objectives_of_the_plan: List[str] = Field(
+        description="the main gaols of this educational plan"
+    )
+    validated_units: List[ValidatedUnit] = Field(
+        description="List of all validated educational units with their subtopics"
+    )
+
+
+validated_parser = PydanticOutputParser(pydantic_object=ValidatedCurriculumOutput)

schemas/source_schema.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Literal, Optional
+
+class SingleResult(BaseModel):
+    url: str
+    title: str
+    content: str
+    score: float
+    search_query: str
+
+
+class AllResults(BaseModel):
+    results: List[SingleResult]

tools/__init__.py

@@ -0,0 +1,3 @@
+# from .chapter_division import split_json
+# from .scraper import web_scraping_tool
+# from .tavily import search_engine_tool, is_recent

tools/chapter_division.py

@@ -0,0 +1,46 @@
+# import os
+# import json
+# import re
+# from modules import outliner_dir, output_dir
+
+# # ---------- Helper: sanitize file names ----------
+# def safe_filename(name: str) -> str:
+#     return re.sub(r'[\\/*?:"<>|]', "", name).strip()
+
+
+# # ---------- Main function ----------
+# def split_json(input_file: str, output_dir: str):
+#     # Load JSON
+#     with open(input_file, "r", encoding="utf-8") as f:
+#         data = json.load(f)
+
+#     main_headings = data.get("main_headings", [])
+#     sub_headings = data.get("sub_headings", [])
+#     sub_sub_headings = data.get("sub_sub_headings", None)
+
+#     # Ensure output folder exists
+#     os.makedirs(output_dir, exist_ok=True)
+
+#     for idx, main in enumerate(main_headings):
+#         headers = sub_headings[idx] if idx < len(sub_headings) else []
+
+#         # لو فيه sub_sub_headings نجيبها، لو مش فيه نخليها null
+#         if sub_sub_headings and idx < len(sub_sub_headings):
+#             subs = sub_sub_headings[idx]
+#         else:
+#             subs = None
+
+#         section = {"headers": headers, "sub_sub_headings": subs}
+
+#         file_name = safe_filename(main) + ".json"
+#         file_path = os.path.join(output_dir, file_name)
+
+#         with open(file_path, "w", encoding="utf-8") as out_f:
+#             json.dump(section, out_f, ensure_ascii=False, indent=2)
+
+#         print(f"✅ Saved {file_name}")
+
+
+# # ---------- Example usage ----------
+# if __name__ == "__main__":
+#     split_json("/content/ai_agent_output/step_1_outlines.json", "output_sections")

tools/scraper.py

@@ -0,0 +1,32 @@
+# from crewai.tools import tool
+# from scrapegraphai.graphs import SmartScraperGraph
+# from schemas.extractor_schema import SinglePartOfContent
+# from modules import llm
+
+# @tool
+# def web_scraping_tool(page_url: str):
+#     """
+#     An AI Tool to help an agent to scrape a web page using ScrapegraphAI.
+#     """
+#     try:
+#         graph = SmartScraperGraph(
+#             prompt=(
+#                 "Extract ALL detailed content from the web page without summarizing. "
+#                 "Preserve full paragraphs, lists, and section headers. "
+#                 "Include associated media (images, videos, audios, pdfs). "
+#                 "Fit everything into this schema:\n"
+#                 "```json\n" + SinglePartOfContent.schema_json() + "\n```"
+#             ),
+#             source=page_url,
+#             llm=llm,
+#         )
+
+#         details = graph.run()
+
+#         return {
+#             "page_url": page_url,
+#             "details": details,
+#         }
+
+#     except Exception as e:
+#         raise RuntimeError(f"Scraping failed for {page_url}: {str(e)}")

tools/tavily.py

@@ -0,0 +1,64 @@
+# import os
+# from tavily import TavilyClient
+# from crewai.tools import tool
+# from modules import TRUSTED_SITES
+
+# search_tool = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
+
+
+# def is_recent(result, min_year=2021):
+#     """Validate result date is >= min_year if available."""
+#     pub_date = result.get("published_date")
+#     if not pub_date:
+#         return False  # skip if no date
+#     try:
+#         year = int(pub_date.split("-")[0])
+#         return year >= min_year
+#     except Exception:
+#         return False
+
+
+# @tool
+# def search_engine_tool(query: str):
+#     """Execute a focused web search for the given query.
+
+#     - Prioritize **scholarly resources** (academic papers, books, journals, trusted educational sites).
+#     - Filters results to only those published/updated >= 2021.
+#     - Include **Arabic sources** when contextually relevant, but prioritize **English academic sources**.
+#     - Retrieve only **diverse and high-quality** results (avoid spam, low-quality blogs, or purely commercial pages).
+#     - For each result, ensure useful metadata is returned:
+#         * url
+#         * title
+#         * short content/summary
+#         * relevance score
+#     - Use a maximum of 5 results per query to keep output precise and useful.
+#     """
+#     # Step 1: Normal Tavily search
+#     # tavily_results = search_tool.search(query)
+
+#     site_query = f"{query} after:2020"
+#     tavily_results = search_tool.search(query=site_query, max_results=10)
+#     # Step 2: Force search inside trusted domains
+#     trusted_results = []
+#     for site in TRUSTED_SITES:
+#         site_query = f"site:{site} {query}"
+#         try:
+#             res = search_tool.search(site_query)
+#             if res and "results" in res:
+#                 trusted_results.extend(res["results"])
+#         except Exception as e:
+#             print(f"Skipping {site}: {e}")
+
+#     # Step 3: Merge + deduplicate
+#     all_results = tavily_results.get("results", []) + trusted_results
+#     seen = set()
+#     filtered = []
+#     for r in all_results:
+#         if r["url"] not in seen:
+#             seen.add(r["url"])
+#             filtered.append(r)
+
+#     # Step 4: Limit to 5 best results
+#     final_results = sorted(filtered, key=lambda x: x.get("score", 0), reverse=True)[:5]
+
+#     return {"results": final_results}