Add login page

Dockerfile

@@ -18,4 +18,5 @@ EXPOSE 7860
 
 # استخدم Gunicorn بدلاً من uvicorn مباشرة لدعم عدة مستخدمين (Workers)
 # رقم 4 يعني أنه سيشغل 4 عمليات (Processes) لخدمة الطلبات في نفس الوقت
-CMD ["gunicorn", "app:app", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:7860", "--timeout", "120"]
+# CMD ["gunicorn", "app:app", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:7860", "--timeout", "120"]
+CMD ["gunicorn", "app:app","--workers", "2","--worker-class", "uvicorn.workers.UvicornWorker","--bind", "0.0.0.0:7860","--timeout", "180"]

agents/analysis_phase/analysis.py

@@ -76,8 +76,9 @@ def analysis_agent():
     verbose=True,
 )
 
+
 # ====== Task ======
-def analysis_task(agent):
+def analysis_task(analysis_agent):
     return Task(
     description="\n".join(
         [

agents/analysis_phase/objectives.py

@@ -74,203 +74,203 @@ def objectives_generator():
 
 def objectives_task(objectives_agent):
     return 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:
+        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": [
         {
@@ -284,7 +284,7 @@ def objectives_task(objectives_agent):
         }
       ]
     }""",
-    output_json=LearningObjectivesOutput,
-    agent=objectives_generator,
-    human_input=False,
-)
+        output_json=LearningObjectivesOutput,
+        agent=objectives_agent,
+        human_input=False,
+    )

agents/analysis_phase/outcomes.py

@@ -303,6 +303,6 @@ def outcomes_task(outcomes_agent):
     ],
     }""",
     output_json=LearningOutcomesOutput,
-    agent=outcomes_generator,
+    agent=outcomes_agent,
     human_input=False,
 )

agents/books/book_structure.py

@@ -41,13 +41,13 @@ def book_structure_agent():
 # ---------------------------------
 def generate_book_outline_task(structure_agent):
     return Task(
-    name="Generate book outline (NO content writing)",
-    description=(
-        """أنت تبني هيكل كتاب فقط (Outline) من بيانات الإدخال،
+        name="Generate book outline (NO content writing)",
+        description=(
+            """أنت تبني هيكل كتاب فقط (Outline) من بيانات الإدخال،
 بما يتناسب مع نوع الكتاب (تعليمي، معرفي، تطوير ذات، أعمال، أو غير خيالي)،
 مع مراعاة الجمهور المستهدف وطبيعة التجربة القرائية.
 """
-        """تنبيه صارم:
+            """تنبيه صارم:
 - لا تقم بإنشاء فصول (Chapters) جديدة.
 - لا تقم بإنشاء أقسام (Sections) جديدة.
 - لا تغيّر أسماء Chapters أو Sections الواردة في raw_units حرفيًا.
@@ -55,106 +55,106 @@ def generate_book_outline_task(structure_agent):
 - دورك يقتصر حصريًا على:
   • تنظيم وبناء Subsections داخل كل Section موجود.
 """
-        "==============================\n"
-        "قواعد إلزامية (معايير إعداد الكتب)\n"
-        "==============================\n"
-        "1) ممنوع كتابة محتوى الكتاب/شرح مطول/أمثلة تفصيلية. أنت تنتج هيكل فقط.\n"
-        "2) الوضوح والبساطة في العناوين واللغة.\n"
-        "3) تجنب التكديس: لا تضع أكثر من 6 محاور في القسم، ولا أكثر من 6 أقسام في الفصل.\n"
-        "4) لا تضع أقل من 2 محاور في القسم نهائيًا.\n"
-        "5) منع التكرار: لا تكرر نفس الفكرة بين محاور متجاورة، ولا تكرر نفس الصياغة الافتتاحية.\n"
-        """6) التدرج:
+            "==============================\n"
+            "قواعد إلزامية (معايير إعداد الكتب)\n"
+            "==============================\n"
+            "1) ممنوع كتابة محتوى الكتاب/شرح مطول/أمثلة تفصيلية. أنت تنتج هيكل فقط.\n"
+            "2) الوضوح والبساطة في العناوين واللغة.\n"
+            "3) تجنب التكديس: لا تضع أكثر من 6 محاور في القسم، ولا أكثر من 6 أقسام في الفصل.\n"
+            "4) لا تضع أقل من 2 محاور في القسم نهائيًا.\n"
+            "5) منع التكرار: لا تكرر نفس الفكرة بين محاور متجاورة، ولا تكرر نفس الصياغة الافتتاحية.\n"
+            """6) التدرج:
     - الكتب التعليمية: من الأساسيات إلى التطبيق/التحليل
     - الكتب غير التعليمية: من التمهيد إلى التعمق ثم الخلاصة/التحول
     - يجب أن يعكس الترتيب رحلة القارئ الطبيعية
 """
-        "7) ترابط منطقي بين الأقسام والمحاور (بدون قفزات مفاهيمية).\n\n"
-        "==============================\n"
-        "قواعد إلزامية لصياغة عناوين Subsections (مهم جدًا)\n"
-        "==============================\n"
-        "A) عناوين المحاور الفرعية لازم تكون:\n"
-        "   - قصيرة وواضحة (يفضل 2–6 كلمات).\n"
-        "   - غير تقليدية/غير جامدة، وتشد القارئ.\n"
-        "   - لغة بسيطة مناسبة للجمهور (ابتعد عن الأسلوب الأكاديمي الثقيل).\n"
-        "   - فكرة واحدة لكل عنوان.\n"
-        "B) ممنوع تكرار بدايات العناوين أو الحشو اللفظي.\n"
-        "   - لا تبدأ عدة محاور بنفس الصيغة مثل: (في ظل...)، (يبرز...)، (من المعروف...)، (يتناول هذا القسم...).\n"
-        "C) تجنب العناوين المركّبة التي تجمع محورين مختلفين في عنوان واحد.\n"
-        "   - مثال ممنوع: (تعريف الصمود النفسي وأهميته)\n"
-        "   - الصحيح: محور لتعريف المفهوم + محور مستقل للأهمية/الفوائد.\n"
-        "D) تجنب كلمات فضفاضة أو غير دقيقة في العناوين مثل:\n"
-        "   - (الرئيسية/الأساسية) إذا كانت لا تضيف معنى.\n"
-        "E) لا تستخدم عناوين تشبه عناوين الأبحاث (توثيق/اقتباسات/أسماء باحثين/سنوات) داخل العناوين.\n"
-        "F) يجوز استخدام أساليب عنوان جذابة حسب نوع القسم:\n"
-        "   - سؤال تحفيزي، عبارة قصيرة، أو صياغة عملية (لكن بدون كتابة محتوى).\n\n"
-        "==============================\n"
-        "إدارة عدد الصفحات\n"
-        "==============================\n"
-        """إذا تم تمرير target_total_pages:
+            "7) ترابط منطقي بين الأقسام والمحاور (بدون قفزات مفاهيمية).\n\n"
+            "==============================\n"
+            "قواعد إلزامية لصياغة عناوين Subsections (مهم جدًا)\n"
+            "==============================\n"
+            "A) عناوين المحاور الفرعية لازم تكون:\n"
+            "   - قصيرة وواضحة (يفضل 2–6 كلمات).\n"
+            "   - غير تقليدية/غير جامدة، وتشد القارئ.\n"
+            "   - لغة بسيطة مناسبة للجمهور (ابتعد عن الأسلوب الأكاديمي الثقيل).\n"
+            "   - فكرة واحدة لكل عنوان.\n"
+            "B) ممنوع تكرار بدايات العناوين أو الحشو اللفظي.\n"
+            "   - لا تبدأ عدة محاور بنفس الصيغة مثل: (في ظل...)، (يبرز...)، (من المعروف...)، (يتناول هذا القسم...).\n"
+            "C) تجنب العناوين المركّبة التي تجمع محورين مختلفين في عنوان واحد.\n"
+            "   - مثال ممنوع: (تعريف الصمود النفسي وأهميته)\n"
+            "   - الصحيح: محور لتعريف المفهوم + محور مستقل للأهمية/الفوائد.\n"
+            "D) تجنب كلمات فضفاضة أو غير دقيقة في العناوين مثل:\n"
+            "   - (الرئيسية/الأساسية) إذا كانت لا تضيف معنى.\n"
+            "E) لا تستخدم عناوين تشبه عناوين الأبحاث (توثيق/اقتباسات/أسماء باحثين/سنوات) داخل العناوين.\n"
+            "F) يجوز استخدام أساليب عنوان جذابة حسب نوع القسم:\n"
+            "   - سؤال تحفيزي، عبارة قصيرة، أو صياغة عملية (لكن بدون كتابة محتوى).\n\n"
+            "==============================\n"
+            "إدارة عدد الصفحات\n"
+            "==============================\n"
+            """إذا تم تمرير target_total_pages:
 - يجب توزيع عدد الصفحات على جميع Subsections بشكل متوازن ومنطقي
 - مجموع est_pages لكل Subsections = target_total_pages
 إذا لم يتم تمرير target_total_pages أو كانت القيمة 0:
 - قدّر عدد الصفحات المناسب للكتاب بناءً على عدد الفصول وعمق الموضوع ومستوى الجمهور
 - ثم وزّع الصفحات داخليًا على المحاور
 """
-        "==============================\n"
-        "الحفاظ على الأسماء\n"
-        "==============================\n"
-        """- استخدم عناوين Chapters وSections كما هي حرفيًا من raw_units.
+            "==============================\n"
+            "الحفاظ على الأسماء\n"
+            "==============================\n"
+            """- استخدم عناوين Chapters وSections كما هي حرفيًا من raw_units.
 - يُمنع إعادة الصياغة أو التحسين اللغوي لعناوين Chapters/Sections.
 - التعديل/التحسين مسموح فقط داخل Subsections التي تنشئها.
 """
-        "==============================\n"
-        "المدخلات\n"
-        "==============================\n"
-        "- book_title: {book_title}\n"
-        "- target_audience: {target_audience}\n"
-        "- book_description: {book_description}\n"
-        "- learning_outcomes: {learning_outcomes}\n"
-        "- raw_units: {raw_units}\n"
-        "- target_total_pages (optional): {target_total_pages}\n"
-        "- example_reference (optional): {example_reference}\n\n"
-        """ملاحظة مهمة:
+            "==============================\n"
+            "المدخلات\n"
+            "==============================\n"
+            "- book_title: {book_title}\n"
+            "- target_audience: {target_audience}\n"
+            "- book_description: {book_description}\n"
+            "- learning_outcomes: {learning_outcomes}\n"
+            "- raw_units: {raw_units}\n"
+            "- target_total_pages (optional): {target_total_pages}\n"
+            "- example_reference (optional): {example_reference}\n\n"
+            """ملاحظة مهمة:
 raw_units تمثل الهيكل النهائي للفصول والأقسام.
 يُمنع تعديل أو إعادة تسمية أي Unit أو Topic.
 Subsections فقط هي التي يتم إنشاؤها وتنظيمها.
 """
-        "==============================\n"
-        "مطلوب الإخراج (JSON صارم)\n"
-        "==============================\n"
-        "أخرج JSON فقط مطابق لـ BookOutlineOutput وبنفس أسماء الحقول:\n"
-        "{\n"
-        '  "book_title": "...",\n'
-        '  "target_audience": "...",\n'
-        '  "book_description": "...",\n'
-        '  "chapters": [\n'
-        "    {\n"
-        '      "chapter_title": "...",\n'
-        '      "outcome": "...",\n'
-        '      "sections": [\n'
-        "        {\n"
-        '          "title": "...",\n'
-        '          "overview": "...",\n'
-        '          "subsections": [\n'
-        "            {\n"
-        '              "title": "...",\n'
-        '              "purpose": "...",\n'
-        '              "suggested_queries": ["..."],\n'
-        '              "difficulty": "basic|intermediate|advanced",\n'
-        '              "est_pages": 1\n'
-        "            }\n"
-        "          ]\n"
-        "        }\n"
-        "      ]\n"
-        "    }\n"
-        "  ],\n"
-        '  "outline_notes": "..."\n'
-        '  "total_pages": 50\n'
-        "}\n"
-        "==============================\n"
-        "تحقق إلزامي قبل الإخراج\n"
-        "==============================\n"
-        """قبل إخراج الـ JSON النهائي، راجع ما يلي بدقة:
+            "==============================\n"
+            "مطلوب الإخراج (JSON صارم)\n"
+            "==============================\n"
+            "أخرج JSON فقط مطابق لـ BookOutlineOutput وبنفس أسماء الحقول:\n"
+            "{\n"
+            '  "book_title": "...",\n'
+            '  "target_audience": "...",\n'
+            '  "book_description": "...",\n'
+            '  "chapters": [\n'
+            "    {\n"
+            '      "chapter_title": "...",\n'
+            '      "outcome": "...",\n'
+            '      "sections": [\n'
+            "        {\n"
+            '          "title": "...",\n'
+            '          "overview": "...",\n'
+            '          "subsections": [\n'
+            "            {\n"
+            '              "title": "...",\n'
+            '              "purpose": "...",\n'
+            '              "suggested_queries": ["..."],\n'
+            '              "difficulty": "basic|intermediate|advanced",\n'
+            '              "est_pages": 1\n'
+            "            }\n"
+            "          ]\n"
+            "        }\n"
+            "      ]\n"
+            "    }\n"
+            "  ],\n"
+            '  "outline_notes": "..."\n'
+            '  "total_pages": 50\n'
+            "}\n"
+            "==============================\n"
+            "تحقق إلزامي قبل الإخراج\n"
+            "==============================\n"
+            """قبل إخراج الـ JSON النهائي، راجع ما يلي بدقة:
 - كل Chapter يحتوي 2–6 Sections
 - كل Section يحتوي على 2–6 Subsections (لا أقل من 2 نهائيًا)
 - إذا وجدت Section تحتوي فكرة واحدة فقط:
@@ -166,9 +166,9 @@ Subsections فقط هي التي يتم إنشاؤها وتنظيمها.
 - لا تخرج JSON حتى تتأكد أن جميع القيود محققة
 - أي مخالفة ستُعد إخراجًا غير صالح
 """
-    ),
-    expected_output="Strict JSON matching BookOutlineOutput schema (NO extra keys).",
-    output_json=BookOutlineOutput,
-    agent=book_structure_agent,
-    async_execution=False,
-)
+        ),
+        expected_output="Strict JSON matching BookOutlineOutput schema (NO extra keys).",
+        output_json=BookOutlineOutput,
+        agent=structure_agent,
+        async_execution=False,
+    )

agents/books/intro_plan.py

@@ -23,29 +23,29 @@ def intro_style_planner():
     memory=False,
 )
 
-def intro_style_planner_task(intro_style_planner_agent, book_plan):
+def intro_style_planner_task(intro_style_planner_agent):
     return Task(
-    description=(
-        "You are given a FULL BOOK PLAN containing ALL chapters.\n\n"
-        "Your job is NOT to analyze text.\n"
-        "Your job is to DESIGN the most suitable introduction style for EACH chapter.\n\n"
-        "### Goals:\n"
-        "1) Each chapter must receive a StyleOutput profile.\n"
-        "2) Styles MUST fit the chapter topic and emotional intent.\n"
-        "3) Styles MUST NOT repeat across chapters.\n"
-        "4) Consecutive chapters MUST NOT share the same intro_function.\n"
-        "5) The book must feel rhythmically varied (narrative → reflective → conceptual → atmospheric → etc).\n\n"
-        "### Diversity Rules (HARD CONSTRAINTS):\n"
-        "- Do NOT repeat the same intro_function more than once.\n"
-        "- Do NOT reuse identical tone or sentence_structure in adjacent chapters.\n"
-        "- Vary opening strategies: story, scene, question, metaphor, reflection, contrast.\n\n"
-        "### Output:\n"
-        "Return ONE JSON object for the whole book using IntroStylePlan schema.\n\n"
-        "Input book chapters:\n"
-        "{book_plan}"
-    ),
-    agent=intro_style_planner,
-    expected_output="A valid JSON following IntroPlan schema with inferred intro-writing rules",
-    output_json=IntroPlan,
-    # output_file=os.path.join(output_dir, "style_output_2.json"),
-)
+        description=(
+            "You are given a FULL BOOK PLAN containing ALL chapters.\n\n"
+            "Your job is NOT to analyze text.\n"
+            "Your job is to DESIGN the most suitable introduction style for EACH chapter.\n\n"
+            "### Goals:\n"
+            "1) Each chapter must receive a StyleOutput profile.\n"
+            "2) Styles MUST fit the chapter topic and emotional intent.\n"
+            "3) Styles MUST NOT repeat across chapters.\n"
+            "4) Consecutive chapters MUST NOT share the same intro_function.\n"
+            "5) The book must feel rhythmically varied (narrative → reflective → conceptual → atmospheric → etc).\n\n"
+            "### Diversity Rules (HARD CONSTRAINTS):\n"
+            "- Do NOT repeat the same intro_function more than once.\n"
+            "- Do NOT reuse identical tone or sentence_structure in adjacent chapters.\n"
+            "- Vary opening strategies: story, scene, question, metaphor, reflection, contrast.\n\n"
+            "### Output:\n"
+            "Return ONE JSON object for the whole book using IntroStylePlan schema.\n\n"
+            "Input book chapters:\n"
+            "{book_plan}"
+        ),
+        agent=intro_style_planner_agent,
+        expected_output="A valid JSON following IntroPlan schema with inferred intro-writing rules",
+        output_json=IntroPlan,
+        # output_file=os.path.join(output_dir, "style_output_2.json"),
+    )

agents/books/units_intro.py

@@ -306,193 +306,152 @@ def intro_generator():
 
 def intro_generation_task(intro_generator_agent):
     return Task(
-    description=(
-        "You are given structured chapters metadata:\n({chapter_metadata})\n andfocus on intros style for each chapter:\n({intro_style})\n\n"
-
-        "CRITICAL WRITING RULE — Opening Diversity:\n"
-
-        "Even if the tone is academic or formal,"
-        "MANDATORY HOOK:\n"
-        "The first sentence MUST be engaging (question, story, scenario, or problem).\n"
-        "Never start with a definition.\n\n"
-
-        "AI-STYLE BAN:\n"
-        "Never use cliché academic phrases or repeated textbook templates.\n"
-        "If the sentence feels predictable, rewrite it.\n\n"
-        "BANNED VERBS (in all conjugations):\n"
-        "❌ يبرز / تبرز / يُبرز / نبرز / برز / بارز\n"
-        "❌ يتجلى / تتجلى / تجلّى / متجلّي\n"
-        "❌ يُعدّ / تُعدّ / عُدّ\n"
-        "❌ يُسلّط الضوء / نسلّط\n"
-        "❌ يغوص / نغوص\n"
-        "❌ يمتدّ النقاش / يمتدّ\n\n"
-
-        "BANNED META-DESCRIPTIONS:\n"
-        "❌ هذا الفصل + any verb (يبرز، يقدّم، يستعرض، يتناول، يناقش)\n"
-        "❌ نرى فيه / نُلاحظ هنا / نُتَعَرَّضُ هنا\n"
-        "❌ يدعونا هذا + anything\n"
-        "❌ من هنا، يصبح...\n\n"
-
-        "BANNED TRANSITIONS:\n"
-        "❌ من خلال (find alternatives: بفضل، عبر، بواسطة، or restructure)\n"
-        "❌ في ظل\n"
-        "❌ عبر استكشاف\n\n"
-
-        "**WHY THESE ARE BANNED:**\n"
-        "These phrases describe what THE CHAPTER DOES.\n"
-        "The introduction should describe THE CONCEPT, not the chapter's actions.\n\n"
-
-
-        "NO DIRECT ADDRESS:\n"
-        "Do not explicitly mention the audience (طلاب، متعلمون، قرّاء).\n"
-        "Use implicit contextual framing instead.\n\n"
-
-        "ARABIC QUALITY:\n"
-        "Zero spelling, grammar, or phrasing mistakes are allowed.\n"
-        "DO NOT use full tashkeel (vocalization marks) except:\n"
-        "- To disambiguate rare cases\n"
-        "- On the last word of a sentence if needed\n\n"
-
-        "Academic writing does NOT mean identical openings.\n"
-        "Each chapter MUST begin with a naturally varied opening strategy.\n"
-        "Before writing, internally choose ONE opening style that best fits the chapter according to what style says:\n"
-        "- contextual background\n"
-        "- problem framing\n"
-        "- conceptual importance\n"
-        "- analytical contrast\n"
-        "- research observation\n"
-        "- structural preview\n\n"
-        "=============================\n"
-        "AUDIENCE RULE (REINFORCED)\n"
-        "=============================\n\n"
-
-        "NEVER use these terms:\n"
-        "❌ المتدرّب / المتدربون\n"
-        "❌ القارئ / القرّاء\n"
-        "❌ الطالب / الطلاب\n"
-        "❌ المتعلّم / المتعلمون\n"
-        "❌ الموظف / الموظفون\n\n"
-
-        "**This is a BOOK, not a training course.**\n\n"
-
-        "Rotate openings naturally across chapters.\n"
-        "Never reuse the same opening structure repeatedly.\n"
-        "Avoid formulaic or AI-sounding sentences.\n"
-        "The introduction must feel written by a human author, not generated from a template.\n"
-
-        "Write ONE introduction that:\n"
-        "1) Follows the style of the chapter intro\n"
-        "2) Reflects the learning outcome\n"
-        "3) Frames all sections conceptually without detailing them\n"
-        "4) Respects scope limits and avoids overlap\n"
-        "5) Matches the declared intro_function\n\n"
-
-        "CRITICAL — NO SECTION SUMMARY:\n"
-        "Do NOT sequentially describe chapter sections.\n"
-        "Do NOT narrate the structure of the chapter.\n"
-        "The introduction must frame ideas, not summarize contents.\n\n"
-
-        "=============================\n"
-        "NO UNSOURCED RESEARCH CLAIMS\n"
-        "=============================\n"
-
-        "NEVER say:\n"
-        "• تشير الدراسات\n"
-        "• أثبتت الأبحاث\n"
-        "• تؤكد الدراسات\n"
-        "• يرى الباحثون\n\n"
-
-        "Unless a specific study, author, or year is explicitly provided in metadata.\n"
-        "Otherwise, discuss ideas conceptually only.\n\n"
-
-
-        "=============================\n"
-        "REQUIRED APPROACH\n"
-        "=============================\n\n"
-
-        "1. **START**: Hook that engages with the CONCEPT\n"
-        "   Example: 'ما الذي يجعل البعض قادرين على...؟'\n\n"
-
-        "2. **DEVELOP**: Discuss the concept's nature, significance, challenges\n"
-        "   - Focus on WHAT THE CONCEPT IS\n"
-        "   - Focus on WHY IT MATTERS\n"
-        "   - Focus on HOW IT MANIFESTS\n"
-        "   - DO NOT focus on what the chapter covers\n\n"
-
-        "3. **CLOSE**: Connect to reader's context or forward implication\n"
-        "   • Set intellectual expectations\n"
-        "   • Create forward momentum\n"
-        "   • NO phrases like 'هنا نستكشف' or 'هذا الفصل يتناول'\n\n"
-
-        "=============================\n"
-        "STYLE: AVOID RIGID ACADEMIC TONE\n"
-        "=============================\n\n"
-
-        "The introduction should be:\n"
-        "• Intellectually engaging (not dry)\n"
-        "• Fluid and connected (not choppy)\n"
-        "• Conceptually rich (not procedurally descriptive)\n"
-        "• Human-sounding (not research-report style)\n\n"
-
-        "❌ RIGID ACADEMIC STYLE:\n"
-        "'يُعرّف الصمود بأنه قدرة الفرد على التعافي. تشير الدراسات إلى دوره في الأداء.'\n\n"
-
-        "✅ FLUID ENGAGING STYLE:\n"
-        "'الصمود ليس مجرد قدرة على التحمّل، بل هو فنّ إعادة البناء الداخلي بعد كل اهتزاز.'\n\n"
-
-        "=============================\n"
-        "TRANSITIONS BETWEEN IDEAS\n"
-        "=============================\n\n"
-
-        "ALWAYS connect paragraphs smoothly.\n\n"
-
-        "Use varied transition tools:\n"
-        "• وفي هذا السياق...\n"
-        "• ومن هذا المنطلق...\n"
-        "• وهنا تكمن...\n"
-        "• لكن...\n"
-        "• غير أن...\n"
-        "• بينما...\n"
-        "• ومع ذلك...\n\n"
-
-        "❌ BAD (choppy jumps):\n"
-        "'الصمود مهم. له أركان. الشخصية الصامدة لها سمات.'\n\n"
-
-        "✅ GOOD (smooth flow):\n"
-        "'الصمود النفسي يتجاوز القوة الظاهرة. وفي أعماقه، تكمن بنية معقّدة من الأركان النفسية التي تشكّل معًا درعاً داخلياً. وهذا التماسك الداخلي هو ما يميّز...'\n\n"
-
-
-        "STYLE REFINEMENT:\n"
-        "Prefer conceptual language over procedural language.\n"
-        "Avoid verbs like: يبدأ، ينتقل، يستعرض، يختتم.\n\n"
-
-        "FORBIDDEN ROLES:\n"
-        "Never use: متدرّب، مشارك، متعلم في دورة، برنامج تدريبي\n"
-        "This is a BOOK, not training material.\n\n"
-
-        'FIELD OVERRIDES:\n'
-        '- reader_interaction:\n'
-        '  → Prefer conceptual engagement over direct address\n'
-
-        '- opening_style includes "سؤال":\n'
-        '  → Question MAY be implicit, not explicit\n'
-
-        '- explicit_structure_markers:\n'
-        '  → Use conceptual flow, not verbal markers\n'
-
-        '- voice_type = إرشادي:\n'
-        '  → Guide through idea progression, not instructions\n\n'
-
-        "Length rules:\n"
-        "- conceptual_explanation → 250–350 words\n"
-        "- academic orientation → 450–750 words\n"
-        "- analytical → 350–550 words\n\n"
-
-        "Output:\n"
-        "- JSON with a single key: intro"
-    ),
-    agent=intro_generator,
-    expected_output="ChapterIntro JSON",
-    output_json=ChapterIntro,
-    # output_file=os.path.join(output_dir, "intro_output.json")
-)
+        description=(
+            "You are given structured chapters metadata:\n({chapter_metadata})\n andfocus on intros style for each chapter:\n({intro_style})\n\n"
+            "CRITICAL WRITING RULE — Opening Diversity:\n"
+            "Even if the tone is academic or formal,"
+            "MANDATORY HOOK:\n"
+            "The first sentence MUST be engaging (question, story, scenario, or problem).\n"
+            "Never start with a definition.\n\n"
+            "AI-STYLE BAN:\n"
+            "Never use cliché academic phrases or repeated textbook templates.\n"
+            "If the sentence feels predictable, rewrite it.\n\n"
+            "BANNED VERBS (in all conjugations):\n"
+            "❌ يبرز / تبرز / يُبرز / نبرز / برز / بارز\n"
+            "❌ يتجلى / تتجلى / تجلّى / متجلّي\n"
+            "❌ يُعدّ / تُعدّ / عُدّ\n"
+            "❌ يُسلّط الضوء / نسلّط\n"
+            "❌ يغوص / نغوص\n"
+            "❌ يمتدّ النقاش / يمتدّ\n\n"
+            "BANNED META-DESCRIPTIONS:\n"
+            "❌ هذا الفصل + any verb (يبرز، يقدّم، يستعرض، يتناول، يناقش)\n"
+            "❌ نرى فيه / نُلاحظ هنا / نُتَعَرَّضُ هنا\n"
+            "❌ يدعونا هذا + anything\n"
+            "❌ من هنا، يصبح...\n\n"
+            "BANNED TRANSITIONS:\n"
+            "❌ من خلال (find alternatives: بفضل، عبر، بواسطة، or restructure)\n"
+            "❌ في ظل\n"
+            "❌ عبر استكشاف\n\n"
+            "**WHY THESE ARE BANNED:**\n"
+            "These phrases describe what THE CHAPTER DOES.\n"
+            "The introduction should describe THE CONCEPT, not the chapter's actions.\n\n"
+            "NO DIRECT ADDRESS:\n"
+            "Do not explicitly mention the audience (طلاب، متعلمون، قرّاء).\n"
+            "Use implicit contextual framing instead.\n\n"
+            "ARABIC QUALITY:\n"
+            "Zero spelling, grammar, or phrasing mistakes are allowed.\n"
+            "DO NOT use full tashkeel (vocalization marks) except:\n"
+            "- To disambiguate rare cases\n"
+            "- On the last word of a sentence if needed\n\n"
+            "Academic writing does NOT mean identical openings.\n"
+            "Each chapter MUST begin with a naturally varied opening strategy.\n"
+            "Before writing, internally choose ONE opening style that best fits the chapter according to what style says:\n"
+            "- contextual background\n"
+            "- problem framing\n"
+            "- conceptual importance\n"
+            "- analytical contrast\n"
+            "- research observation\n"
+            "- structural preview\n\n"
+            "=============================\n"
+            "AUDIENCE RULE (REINFORCED)\n"
+            "=============================\n\n"
+            "NEVER use these terms:\n"
+            "❌ المتدرّب / المتدربون\n"
+            "❌ القارئ / القرّاء\n"
+            "❌ الطالب / الطلاب\n"
+            "❌ المتعلّم / المتعلمون\n"
+            "❌ الموظف / الموظفون\n\n"
+            "**This is a BOOK, not a training course.**\n\n"
+            "Rotate openings naturally across chapters.\n"
+            "Never reuse the same opening structure repeatedly.\n"
+            "Avoid formulaic or AI-sounding sentences.\n"
+            "The introduction must feel written by a human author, not generated from a template.\n"
+            "Write ONE introduction that:\n"
+            "1) Follows the style of the chapter intro\n"
+            "2) Reflects the learning outcome\n"
+            "3) Frames all sections conceptually without detailing them\n"
+            "4) Respects scope limits and avoids overlap\n"
+            "5) Matches the declared intro_function\n\n"
+            "CRITICAL — NO SECTION SUMMARY:\n"
+            "Do NOT sequentially describe chapter sections.\n"
+            "Do NOT narrate the structure of the chapter.\n"
+            "The introduction must frame ideas, not summarize contents.\n\n"
+            "=============================\n"
+            "NO UNSOURCED RESEARCH CLAIMS\n"
+            "=============================\n"
+            "NEVER say:\n"
+            "• تشير الدراسات\n"
+            "• أثبتت الأبحاث\n"
+            "• تؤكد الدراسات\n"
+            "• يرى الباحثون\n\n"
+            "Unless a specific study, author, or year is explicitly provided in metadata.\n"
+            "Otherwise, discuss ideas conceptually only.\n\n"
+            "=============================\n"
+            "REQUIRED APPROACH\n"
+            "=============================\n\n"
+            "1. **START**: Hook that engages with the CONCEPT\n"
+            "   Example: 'ما الذي يجعل البعض قادرين على...؟'\n\n"
+            "2. **DEVELOP**: Discuss the concept's nature, significance, challenges\n"
+            "   - Focus on WHAT THE CONCEPT IS\n"
+            "   - Focus on WHY IT MATTERS\n"
+            "   - Focus on HOW IT MANIFESTS\n"
+            "   - DO NOT focus on what the chapter covers\n\n"
+            "3. **CLOSE**: Connect to reader's context or forward implication\n"
+            "   • Set intellectual expectations\n"
+            "   • Create forward momentum\n"
+            "   • NO phrases like 'هنا نستكشف' or 'هذا الفصل يتناول'\n\n"
+            "=============================\n"
+            "STYLE: AVOID RIGID ACADEMIC TONE\n"
+            "=============================\n\n"
+            "The introduction should be:\n"
+            "• Intellectually engaging (not dry)\n"
+            "• Fluid and connected (not choppy)\n"
+            "• Conceptually rich (not procedurally descriptive)\n"
+            "• Human-sounding (not research-report style)\n\n"
+            "❌ RIGID ACADEMIC STYLE:\n"
+            "'يُعرّف الصمود بأنه قدرة الفرد على التعافي. تشير الدراسات إلى دوره في الأداء.'\n\n"
+            "✅ FLUID ENGAGING STYLE:\n"
+            "'الصمود ليس مجرد قدرة على التحمّل، بل هو فنّ إعادة البناء الداخلي بعد كل اهتزاز.'\n\n"
+            "=============================\n"
+            "TRANSITIONS BETWEEN IDEAS\n"
+            "=============================\n\n"
+            "ALWAYS connect paragraphs smoothly.\n\n"
+            "Use varied transition tools:\n"
+            "• وفي هذا السياق...\n"
+            "• ومن هذا المنطلق...\n"
+            "• وهنا تكمن...\n"
+            "• لكن...\n"
+            "• غير ��ن...\n"
+            "• بينما...\n"
+            "• ومع ذلك...\n\n"
+            "❌ BAD (choppy jumps):\n"
+            "'الصمود مهم. له أركان. الشخصية الصامدة لها سمات.'\n\n"
+            "✅ GOOD (smooth flow):\n"
+            "'الصمود النفسي يتجاوز القوة الظاهرة. وفي أعماقه، تكمن بنية معقّدة من الأركان النفسية التي تشكّل معًا درعاً داخلياً. وهذا التماسك الداخلي هو ما يميّز...'\n\n"
+            "STYLE REFINEMENT:\n"
+            "Prefer conceptual language over procedural language.\n"
+            "Avoid verbs like: يبدأ، ينتقل، يستعرض، يختتم.\n\n"
+            "FORBIDDEN ROLES:\n"
+            "Never use: متدرّب، مشارك، متعلم في دورة، برنامج تدريبي\n"
+            "This is a BOOK, not training material.\n\n"
+            "FIELD OVERRIDES:\n"
+            "- reader_interaction:\n"
+            "  → Prefer conceptual engagement over direct address\n"
+            '- opening_style includes "سؤال":\n'
+            "  → Question MAY be implicit, not explicit\n"
+            "- explicit_structure_markers:\n"
+            "  → Use conceptual flow, not verbal markers\n"
+            "- voice_type = إرشادي:\n"
+            "  → Guide through idea progression, not instructions\n\n"
+            "Length rules:\n"
+            "- conceptual_explanation → 250–350 words\n"
+            "- academic orientation → 450–750 words\n"
+            "- analytical → 350–550 words\n\n"
+            "Output:\n"
+            "- JSON with a single key: intro"
+        ),
+        agent=intro_generator_agent,
+        expected_output="ChapterIntro JSON",
+        output_json=ChapterIntro,
+        # output_file=os.path.join(output_dir, "intro_output.json")
+    )