====== AI Enrichment Tools ======

===== Overview =====

LEAST includes a full AI enrichment suite backed by the Anthropic Claude API. It helps educators and administrators enrich lesson metadata, classify content, surface discovery connections, and govern AI-generated material before it goes live.

===== Live AI Features =====

^ Code ^ Feature ^ Status ^ Where to find it ^
| AI-01 | Lesson Markup — AI Insights modal | **Live** | Lesson page → AI Insights button |
| AI-02 | IWTB Role Enrichment — 700+ career roles | **Live** | Admin → IWTB → Role list |
| AI-03 | Role-Lesson Semantic Graph — 734 scored links | **Live** | Admin → IWTB → Role-Lesson links |
| AI-04 | Editorial Governance Workspace | **Live** | ''/educator/ai-review-queue.php'' |
| AI-06 | EKOS Classification — UDC + IFQ alignment | **Live** | System → EKOS → Awaiting review |

===== AI-01: Lesson Markup (AI Insights) =====

Every published lesson has an **AI Insights** button that opens a modal with AI-generated learning support:

  * **Overview** — plain-language summary of the lesson
  * **Key Points** — bullet list of core concepts
  * **Why This Matters** — real-world relevance
  * **Suggested Next Steps** — what to explore after this lesson
  * **AI Instructions** — guidance for AI systems using this lesson with learners
  * **Sources** — references to materials used in generation

Content is reviewed via the AI-04 governance workspace before going live. Stored in ''strLesson_AI_Markup'' and rendered as CommonMark on the lesson page.

===== AI-02: IWTB Role Enrichment =====

The **I Want To Be** (IWTB) engine covers 700+ career roles, each AI-enriched with:

  * Role background and description
  * Suggested next steps for learners
  * Key figures in the field
  * Recommended books
  * Related TV shows and films
  * Salary and career outlook data

Roles are browsable from the learner dashboard and discoverable via the Discover page.

===== AI-03: Role-Lesson Semantic Graph =====

Claude scores how well each lesson matches each career role (0–100). 734 approved links are live, powering:

  * "Lessons for this role" on IWTB role pages
  * Personalised lesson recommendations
  * Curriculum gap analysis per role

===== AI-04: Editorial Governance Workspace =====

Navigate to ''/educator/ai-review-queue.php'' to:

  * Review AI-generated lesson markup awaiting approval
  * Accept, edit, or reject individual fields with field-level rollback
  * Track OG / AI / Tags completion status per lesson
  * Monitor which lessons are missing markup

===== AI-06: EKOS Classification =====

The **European Key Occupations Standard** (EKOS) engine links lessons to:

  * **UDC** (Universal Decimal Classification) subject categories
  * **IFQ** (Irish Framework of Qualifications) levels 1–22

Review and approve EKOS suggestions at ''/system/workflow_content.php''.

===== Content Pipeline =====

The AI content pipeline generates complete lesson bundles from a topic list and injects them via the Lesson Injection API. The pipeline is fully **PHP-native** — no Python or external packages required on the server.

**To queue a pipeline run:**

  - Add topics to ''projects/topic_list.json''
  - The cron worker (''job_type = pipeline_ingest'') picks up the job
  - Claude generates a complete lesson bundle per topic
  - Lessons land in the review queue at ''/educator/lesson-review-queue.php''

**topic_list.json format:**
<code json>
[
  {
    "topic": "How to send an email",
    "context": "Digital skills for beginners",
    "learning_objective": "Compose and send a basic email",
    "target_level": "beginner",
    "materials": ["https://youtube.com/watch?v=example"],
    "notes": "Prefer practical framing."
  }
]
</code>

===== Lesson Review Queue =====

After pipeline ingestion, AI-generated lessons land in the **Lesson Review Queue** at ''/educator/lesson-review-queue.php'':

  * Lesson title and summary
  * OG / AI / Tags completion indicators
  * Source (ai_pipeline, manual, etc.)
  * Batch ID for traceability

===== Technical Reference =====

  * Model: ''claude-haiku-4-5-20251001'' (configurable via ''ANTHROPIC_MODEL'' in env.php)
  * Prompt caching enabled — ephemeral cache blocks reduce cost on repeated runs
  * PHP client: ''cron/lib/claude_client.php'' — reusable for other cron jobs
  * API key: ''ANTHROPIC_API_KEY'' in ''lib/const/env.php''