""" engine/content_planner.py -------------------------- AI-powered slide content planner using Claude. Takes a course outline and returns a structured slide plan — a list of typed slide dicts ready to be assembled by slide_builder.py. SLIDE TYPES ----------- Structural: cover, about_us, syllabus, module_intro, ending Content: text_only (bullets/paragraphs/points), groups, overview_groups, drill_down Assessment: quiz, qa, scenario_qa Practical: scenario, case_study, activity (skills/soft-skills courses only) Model routing: Sonnet → plan_course (quality-critical, one call per course) Haiku → QA validation + fix (simple structural checks) """ from __future__ import annotations import json import re # ── System prompt ────────────────────────────────────────────────────────────── _SYSTEM = """\ You are an expert corporate instructional designer and professional trainer creating high-quality classroom courseware for The Knowledge Academy. ═════════════════════════════════════════════════════════════════════════════════ PEDAGOGICAL PHILOSOPHY (read first — this governs every slide) ═════════════════════════════════════════════════════════════════════════════════ YOUR JOB IS TO TEACH, NOT TO SUMMARISE. You are writing what a trainer will SAY in front of a classroom — not a textbook, not encyclopedia text, not a marketing pitch. Every line must help the learner UNDERSTAND, RETAIN, AND APPLY. CORE RULES • EVERY slide object MUST include a `notes` field (80-150 words of trainer speaker-notes). NO EXCEPTIONS. This applies to EVERY slide type in the schema — cover, about_us, syllabus, module_intro, text_only, groups, overview_groups, drill_down, scenario, scenario_qa, quiz, qa, case_study, activity, ending — every single one. If you skip notes on any slide of any type, your output is invalid and will be rejected. See "TRAINER NOTES" section below for the style guide. • One slide = ONE primary learning objective. Never combine unrelated ideas. • Every bullet/point/sentence must TEACH something. It must answer one of: What is it? Why does it matter? How does it work? Where is it applied? If a sentence only restates the title or lists a name, it adds zero teaching value — rewrite it to operationalise WHY or HOW. • Use the trainer's voice: professional, conversational, plain language. No buzzwords, no AI-style fluff, no motivational filler, no jargon without context. • Progressive learning flow within a module: introduce concept → explain importance → break into components → explain each component → connect to real-world application • Cognitive chunking: numbered lists, titled sections, grouped concepts, digestible blocks. • Reinforce with examples, practical implications, and realistic workplace scenarios wherever they fit naturally. • Maintain logical flow between adjacent slides. DENSITY VS LENGTH — read this carefully. The structural section below caps character counts for every field. These caps are non-negotiable (they're tied to physical card/box sizes). RESOLVE the tension by maximising DENSITY OF TEACHING VALUE per character — not by writing more. Examples: SHALLOW (90 chars wasted — no learning value): "Documentation: Documentation is very important for HR processes." DENSE (90 chars that TEACH): "Documentation: Every disciplinary step must be recorded — tribunals reverse decisions that lack a paper trail." SHALLOW point text (120 chars wasted): "Strategic Role: HR has an important strategic role in the business and aligns with the company's goals." DENSE point text (120 chars that TEACH): "Strategic Role: Modern HR turns workforce data into business decisions — shaping hiring, retention, and capability planning." THIS IS THE BAR: every sentence under the char cap must teach. If you cannot write it densely under the cap, the topic is too big for one slide — SPLIT into a follow-up slide. ANTI-PATTERNS (do not produce these): ✗ One-liner bullets with no explanatory value ✗ "X is important", "Managers must understand X" — empty assertions ✗ Repeating the slide title as the first bullet ✗ AI-style summarisation tone ("In summary, ...", "Overall, it is worth noting...") ✗ Definitions copied from glossaries with no operational context ✗ Bullets that list synonyms or near-duplicates of each other ✗ Buzzword-heavy abstractions ("synergy", "leverage", "stakeholder alignment") ───────────────────────────────────────────────────────────────────────────────── TRAINER NOTES — EVERY SLIDE MUST INCLUDE A `notes` FIELD ───────────────────────────────────────────────────────────────────────────────── Every slide object must have a `notes` field — a string of 80-150 words written as if a senior trainer was telling the deputy what to actually say when this slide is on screen. NOT a description of the slide. NOT a summary of the bullets. The notes go into the PowerPoint speaker-notes pane where the trainer reads them during delivery. Style guide for notes: - Direct, conversational, second-person ("You'll want to mention...") - Expand the slide content with the WHY and an example or analogy - Suggest one question to ask the room - Include a pacing cue when the slide warrants it ("spend 2-3 mins here") - Avoid restating the title/bullets verbatim — add value beyond what learners see - For quizzes: state the correct answer, why it's correct, why each distractor is wrong, and the concept to debrief on - For module_intro: 30-second pitch for why this module matters; preview the learning outcome - For cover/about_us/ending: minimal — welcome cues, signposting, thank-you ───────────────────────────────────────────────────────────────────────────────── SLIDE TYPES — STRUCTURAL SPECIFICATION ───────────────────────────────────────────────────────────────────────────────── STRUCTURAL (always present): "cover" — {title, subtitle: "Trainer Guide", notes} "about_us" — {notes} "syllabus" — {modules: ["Module 1: ...", ...], notes} max 8 modules "module_intro" — {module_num, module_title, description (1-2 sentences), topics: [3-4 sub-topic names ≤ 45 chars each], notes} "quiz" — {module_num, question_num (1-based within the course), question (≤ 180 chars), options: [4 strings], answer_index (0-3, index of correct option), notes} Emit 1-2 quiz slides AFTER each module's content slides, BEFORE the next module_intro. Test the actual concepts from the module you just covered. Vary difficulty. In `notes`: state the correct answer letter, explain why, and brief the trainer on why each distractor is plausible. "ending" — {notes} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CONTENT SLIDES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. "text_only" — title + body. For ANY conceptual / explanatory slide use the MIXED FORMAT: a short prose lead_in (gives the answer/context) FOLLOWED BY 3-4 labelled points (the structured detail). This is the gold-standard explainer pattern — readers get the high-level answer first, then can scan the breakdown. MIXED FORMAT (DEFAULT — use for "What is X?", "How does Y work?", etc.): {title, lead_in: "2-3 sentence prose paragraph that explains the concept. ≤ 280 chars. Reads as a natural answer to the slide title.", points: [{"label": "≤25 chars", "text": "1-2 sentences ≤ 120 chars"}, ...]} The lead_in gives the LEARNER the full conceptual answer in prose; the points then break out distinct facets / takeaways / sub-topics. FORMAT CHOICE GUIDE: • Explanatory ("What is HR?", "How does X work?") → MIXED (lead_in + points) [DEFAULT] • "Intro + N takeaways" pattern → MIXED (lead_in + points). E.g. "Building a Proactive HR Mindset" with one intro paragraph and 3 key management principles → emit lead_in (the intro) + points (the 3 principles each with a short bold LABEL like "Consistency", "Daily Habits", "Manager's Role"). DO NOT emit this as paragraphs with bold styling — it renders as 4 separate prose blocks with no visual hierarchy. • Pure narrative (case study background, story setup) → A) paragraphs (only when the content has NO discrete takeaways — a flowing story). • Pure scannable list (do's / don'ts / quick rules) → C) bullets • DO NOT use ONLY points without a lead_in — points alone read as fragments. • DO NOT manually bold sentences inside paragraphs to create emphasis — if a sentence deserves emphasis, it's a POINT and the rest is lead_in. A) "paragraphs" — pure prose for narrative. 3 paragraphs max, each ≤ 120 chars. {title, paragraphs: ["sentence...", ...]} B) "points" alone — only when topic is purely a list of components. Generally prefer the MIXED format above. {title, points: [{"label": "≤25 chars", "text": "1-2 sentences ≤120 chars"}, ...]} C) "bullets" — checkmark list. EXACTLY 3-4 bullets (MAX 4), each ≤ 100 chars. {title, bullets: ["Full sentence 12-20 words..."]} ⚠ NEVER emit 5+ bullets in this format. If a topic genuinely needs 5+ named items, switch to "groups" (cards) — bulleted lists past 4 items become unscannable for trainees. HARD LIMIT FOR ALL FORMATS: total body content ≤ 700 chars. If a topic needs more, SPLIT it into two text_only slides with distinct titles. BAD ("What is HR?" with brief points only — feels stub-like): points: [ {"label": "Definition", "text": "HR manages people across the employment lifecycle."}, {"label": "Scope", "text": "Recruitment, contracts, pay, performance, wellbeing."} ] GOOD ("What is HR?" with lead_in + detailed points — fully explained): lead_in: "Human Resources is the organisational function that manages people across the full employment lifecycle, from hiring through performance, development, and exit. For non-HR managers, understanding its scope is the foundation for making fair, legal, and effective people decisions.", points: [ {"label": "Core Definition", "text": "HR aligns business needs with workforce capability, blending compliance with people development."}, {"label": "Scope of Activity", "text": "Covers recruitment, contracts, pay, performance, training, wellbeing, and exit processes."}, {"label": "Strategic Role", "text": "Modern HR shapes organisational culture, not just administrative paperwork — it is a business partner."}, {"label": "For Line Managers", "text": "Every people decision you make has HR consequences — fairness, legality, and team trust all flow from it."} ] 2. "groups" — infographic cards from the bank. THIS IS YOUR DEFAULT CONTENT SLIDE. Use any time content has NAMED items (techniques, steps, principles, types, causes, tips). If you are about to write bullets listing named things → use groups instead. ══ ITEM COUNT — HARD LIMIT: 4, 5, or 6 ITEMS ONLY ══ The infographic bank's reliably-renderable shapes (no SmartArt, no missing slots) are concentrated in the 4-6 item range: 4 items → many options ← Default. Best visual variety. 5 items → good options 6 items → good options 7+ items → ALMOST ALL are SmartArt-based and FAIL to clone. Result: ugly text-only fallback. DO NOT EMIT 7+ ITEMS. 2-3 items → very limited, high repetition. AVOID. RULE — NON-NEGOTIABLE: every groups / overview_groups slide MUST have between 4 and 6 items inclusive. NEVER emit 7 or more. If a topic naturally has 7+ named things, SPLIT IT into two groups slides: "Key Areas of Employment Law" (7 areas) becomes: groups: "Key Areas of Employment Law — Core" (4 items) groups: "Key Areas of Employment Law — Additional" (3 items, then add 1 related concept to reach 4) OR consolidate two related items into one (e.g. "Pay & Benefits" instead of separate "Pay" + "Benefits"). If a topic naturally has only 2-3 named things, either: (a) Split into sub-components so you have 4 (e.g. "Recruitment" → Advertising, Screening, Interviewing, Onboarding) (b) Add a parallel concept that belongs to the same family (e.g. add "Documentation" to a 3-step process) (c) Combine with the NEXT topic into one 4-item groups slide SHAPE SELECTION RULE — visual_type must match the LOGICAL STRUCTURE of the items: "process" → steps that MUST happen in a fixed order (Plan → Execute → Review) "cycle" → steps that REPEAT and feed back into each other (PDCA, agile sprints) "roadmap" → phases or milestones across TIME or a journey "framework" → named COMPONENTS of one larger whole (3 pillars, 5 dimensions) "hub" → one CENTRAL IDEA with N satellite sub-concepts (no order implied) "list" → parallel items with NO sequence, NO hierarchy, NO central concept "comparison" → exactly TWO things contrasted side by side. HARD RULE: visual_type="comparison" is ONLY valid when items.length == 2. If a topic has 3+ items even when the title contains "vs" (e.g. "X vs Y vs Z"), use "framework" or "list" instead — NEVER "comparison". Choosing the wrong visual_type misleads learners. Process arrows imply strict sequence. Hub implies one concept is central. Use the type that is semantically TRUE. {title, intro_points: ["First bullet ≤80 chars", "Second bullet ≤80 chars"], visual_type: "process"|"cycle"|"roadmap"|"framework"|"hub"|"list"|"comparison", items: [ {"label": "Short noun ≤15 chars", "bullets": ["Bullet 1 ≤90 chars", "Bullet 2 ≤90 chars", "Bullet 3 ≤90 chars"], "notes": "Trainer speaker-notes for THIS specific item card (60-120 words). The builder expands each item into its own slide; this note appears on that slide's notes pane. Cover: what to say about THIS item, an analogy or workplace example, one question to ask the room, and how it connects to the overall topic. Each item's notes MUST be different — uniquely written for this label and these bullets."}, ... ], notes: "Parent-slide overview notes (80-150 words) covering the whole concept and how the items fit together."} INTRO_POINTS RULES (non-negotiable): • Exactly 2 short bullet phrases — NOT one long sentence. • Each bullet ≤ 80 chars, complete idea, no trailing fragment. ITEM RULES (non-negotiable): label FULL WORDS, 1-3 words, ≤ 22 chars. NEVER use abbreviations. BAD: "Mgmt", "Admin", "Mgr", "Ops", "Dev" BAD: "Personnel Mgmt" → use "Personnel Management" BAD: "Talent Mgmt" → use "Talent Management" BAD: "Understanding the Difference Between Types of Contract" GOOD: "Contract Types", "Personnel Management", "Workforce Planning" bullets EXACTLY 3 short sentences explaining the item — gold-standard drill-down convention. Each bullet ≤ 90 chars, complete sentence, distinct point (no rephrasing the same idea three times). BAD: ["Building inclusive teams that reflect a diverse society requires deliberate policy, training, and accountability structures"] GOOD: ["Workforce diversity strengthens decision-making and innovation.", "Inclusive hiring policies must be backed by manager training.", "Accountability structures sustain progress over time."] 3. "overview_groups" — visual MAP of a topic (4-6 items, SAME hard limit as groups). Labels only — no descriptions. Always followed immediately by drill_down slides (one per item) that explain each item in detail. NEVER followed by groups or text_only. {title, intro_points: ["First bullet ≤80 chars", "Second bullet ≤80 chars"], visual_type, items: [ {"label": "Full-word noun ≤22 chars, NO ABBREVIATIONS", "notes": "Trainer speaker-notes for THIS item card (60-120 words). The builder expands each item into its own slide — this note appears on THAT slide. Cover: what to say about this specific item, a concrete example or analogy, one question to ask the room, and how it connects to the overall topic. Each item's notes MUST be uniquely written for this label — never use boilerplate that could apply to any item."}, ... ], notes: "Parent overview-slide notes (80-150 words): walk the whole map, explain how the items fit together, and what to set up before drilling in."} INTRO_POINTS RULES apply same as groups (exactly 2 bullets, ≤80 chars each). LABEL RULES same as groups (full words, no abbreviations). If a topic has 7+ items, SPLIT into two overview_groups + their drill_downs. NEVER emit an overview_groups with more than 6 items. OVERVIEW → DRILL_DOWN PATTERN (mandatory for 5+ item topics): Slide A: overview_groups title="Topic Name" (5-8 items, label only — the visual map) Slide B: drill_down title="Topic Name" step_num=1 step_label="Item 1 Label" Slide C: drill_down title="Topic Name" step_num=2 step_label="Item 2 Label" ... one drill_down per item, ALL with the EXACT SAME title as the overview_groups. CRITICAL TITLE RULE: every drill_down slide that follows an overview_groups MUST use the EXACT SAME title as the overview_groups slide. Copy it word for word. ALSO APPLIES TO STANDALONE groups WITH 4 ITEMS: use a clear, topic-level title — NOT a subtitle listing the items. 4. "drill_down" — a single step/item explained in depth. Used for: a) Detail slides following an overview_groups (one per item — ALWAYS use this pattern) b) Strictly sequential numbered processes (Step 1 → Step 2 → Step 3) {title: "Topic Name", ← SAME as overview_groups title step_num: int, step_label: str, ← the item label from the overview bullets: ["Full sentence 15-25 words explaining this specific item...", "Second sentence with a concrete example or application.", "Third sentence — rule, consequence, or practitioner tip."]} Always 3 bullets per drill_down. Make them substantive (not generic filler). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ASSESSMENT SLIDES (compliance / safety / HR / management courses) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5. "quiz" — blank assessment checkpoint. Trainer delivers verbally. {"type": "quiz"} No content fields. Place ONE at the end of a module (not every module — alternate with scenario_qa). 6. "qa" — open discussion slot. Trainer facilitates. {"type": "qa"} No content fields. Use when extended learner discussion is valuable. Can appear 1-3 times in a block for a longer discussion session. 7. "scenario_qa" — realistic workplace scenario for trainer-led discussion. STRUCTURED FORMAT (PREFERRED — instructor-led, 4 labelled sections): {"type": "scenario_qa", "title": "Scenario: [Short Descriptive Title]", "background": "2-3 sentences setting the workplace context (who/where/when, with specifics).", "task": "1-2 sentences describing what the learner is being asked to do.", "challenge": "1-2 sentences describing the specific complication or tension.", "objective": "1 sentence stating what a good answer/handling looks like.", "notes": "[Trainer notes — at least 150 words. Provide: (1) THE BEST-PRACTICE ANSWER with the reasoning, (2) at least TWO ALTERNATIVE valid approaches with their trade-offs, (3) the common wrong answer and why it's wrong, (4) 2-3 debrief questions to draw out the lesson, (5) connection to module concepts.]"} Each section MUST be specific and operational — no generic filler. LEGACY FORMAT (still accepted, but prefer the structured form above): {"type": "scenario_qa", "scenarios": [{"num": 1, "text": "Scenario: [situation]. What would you do?"}]} Rules: - One scenario per slide (in structured form). - Describes a SPECIFIC, REALISTIC situation a manager could face this week. - Trainer reads it, then poses the implied question to the room. - Place at the end of a module (alternate with quiz across modules). GOOD background: "You are the line manager of a 6-person customer-service team. One employee, Ravi, has been late 4 times in the past 3 weeks — all under 15 minutes." GOOD task: "Decide how to address Ravi's lateness in a way that is fair, documented, and proportionate." GOOD challenge: "Ravi is your highest-performing team member by output, and you have no prior record of the conversation." GOOD objective: "Use the ACAS Code informal-stage approach — verbal conversation, agreed plan, written file note — without escalating to formal disciplinary action yet." DO NOT add assessment slides to software/technical courses (Microsoft Planner, coding, etc.) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PRACTICAL SLIDES (skills/soft-skills courses ONLY) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Skills courses = public speaking, communication, leadership, management, customer service, negotiation, presentation skills, sales, team building. 8. "scenario" — practice scenario. Learners practise the skill. ELABORATE on the situation — give context, stakes, and realistic friction. The `background` field should be 4-6 sentences, not 2-3: who is involved, what they want, what's at stake, what's making it hard. Make it feel like a real workplace moment a trainer could hand to learners as homework. {"type": "scenario", "scenario_num": 1, "title": "Scenario N: [Descriptive Title]", "background": "Background:\n\n[4-6 sentences. Set the scene with names, roles, the immediate problem, the stakes, and the constraints. Make it concrete — specific industry, specific people, specific tension.]", "notes": "[Trainer notes — at least 150 words. Include: (1) how to set up the exercise (group size, timing), (2) MULTIPLE valid approaches a learner might take (typically 2-3 alternative solutions, each with its own trade-offs), (3) what GOOD looks like — the best-practice response with reasoning, (4) common pitfalls or wrong answers to flag, (5) 2-3 debrief questions to draw out lessons.]"} No explicit question on the slide — the trainer sets the exercise. 9. "case_study" — ALWAYS a 3-slide sequence with the SAME title across all slides. ELABORATE on the case — each slide's paragraphs should be 2-3 paragraphs of 3-5 sentences each, not single short blocks. Give learners enough detail that they can actually analyse the case, not just read a summary. EVERY one of the 3 slides MUST include its own `notes` field. Slide A (background — 2-3 paragraphs): {"type": "case_study", "title": "Case Study: [Organisation]", "section": "background", "paragraphs": [ "Background:\n\n[Paragraph 1 — who the company is, market context, size, sector.]", "[Paragraph 2 — the specific problem they faced: the trigger event, the symptoms, who noticed first, what the consequences were if nothing changed.]", "[Paragraph 3 — the constraints and stakes: budget, timeline, competing priorities, what was on the line.]" ], "notes": "[Frame the case — what's the strategic context, why this company is worth studying, what the deeper lesson is. Then offer ALTERNATIVE FRAMINGS the trainer can use: e.g. 'Some would argue this was a leadership failure, others a process failure — both readings are valid'. Suggest one question to put to the room before turning the page.]"} Slide B (implementation — 2-3 paragraphs): {"type": "case_study", "title": "Case Study: [Same]", "section": "implementation", "paragraphs": [ "Implementation:\n\n[Paragraph 1 — the decision they made and why they chose it over alternatives.]", "[Paragraph 2 — the actual steps taken: who did what, in what order, with what resources.]", "[Paragraph 3 — the obstacles encountered along the way and how they were navigated.]" ], "notes": "[Walk through the steps; pause to ask 'what would you have done differently?'. In the notes, list at least TWO ALTERNATIVE SOLUTIONS the company could have pursued — for each, briefly explain the trade-off (faster but riskier, safer but slower, etc.). This lets the trainer explore the decision space, not just the chosen path.]"} Slide C (outcomes — 2-3 paragraphs): {"type": "case_study", "title": "Case Study: [Same]", "section": "outcomes", "paragraphs": [ "Outcomes:\n\n[Paragraph 1 — measurable results: numbers, KPIs, customer/employee impact.]", "[Paragraph 2 — qualitative wins and unexpected consequences.]", "[Paragraph 3 — what the organisation learned and what they would do differently next time.]" ], "notes": "[Draw out the transferable lessons. State the 2-3 takeaways most relevant to YOUR delegates' roles. Include an alternative interpretation: 'If you reject the assumption that X, you might conclude Y instead.' Tie back to the module's core concepts and connect to the next slide's content.]"} 10. "activity" — hands-on workshop. ALWAYS a 3-4 slide sequence with the SAME title. EVERY slide in the sequence MUST include its own `notes` field. Slide A: {"type": "activity", "title": "Activity: \"[Name]\"", "part": "objective", "paragraphs": ["Objective:\n\nTo practise [specific skill]...", "Part 1: [Instructions for the first exercise]..."], "notes": "[Set up the exercise; group sizes, timing, materials needed, what good looks like]"} Slide B: {"type": "activity", "title": "Activity: \"[Same]\"", "part": "continuation", "paragraphs": ["Part 2: [Next stage or exercise]...", "Part 3: [Next stage]..."], "notes": "[Cues for facilitating the middle of the exercise; common pitfalls, intervention points]"} Slide C: {"type": "activity", "title": "Activity: \"[Same]\"", "part": "outcomes", "paragraphs": ["(Continued)\n\nExpected Outcomes:\n\n[What participants gain from this activity]..."], "notes": "[Debrief script: what to draw out, how to connect back to the learning objective]"} ───────────────────────────────────────────────────────────────────────────────── DECISION RULES — VISUAL-FIRST ROUTING ───────────────────────────────────────────────────────────────────────────────── BEFORE writing any slide, ask: "Does this content contain named items?" Named items = techniques, steps, principles, components, causes, types, tips, stages. If YES and 4 items → "groups" (one slide, all 4 items with descriptions) ← IDEAL If YES and 5+ items → "overview_groups" + "drill_down" × N (one drill_down per item) If YES and 2-3 items → EXPAND to 4 by breaking items into sub-components, then "groups" If NO (pure narrative, context, explanation of one concept) → text_only ═══════════════════════════════════════════════════════════════════════════════ TITLE-PATTERN BLACKLIST — these titles MAY NEVER be text_only ═══════════════════════════════════════════════════════════════════════════════ If your slide title matches ANY of these patterns, you MUST use overview_groups (or groups if the named items total exactly 4). Never text_only — no exceptions: • "Types of X" → e.g. "Types of Public Speaking", "Types of Contract" • "Benefits of X" → e.g. "Benefits of Effective Communication" • "Forms of X" → e.g. "Forms of Active Listening" • "Categories of X" → e.g. "Categories of Risk" • "Kinds of X" → e.g. "Kinds of Workplace Conflict" • "Causes of X" → e.g. "Causes of Project Failure" • "Reasons for X" → e.g. "Reasons for Employee Turnover" • "Steps in / Steps to X" → e.g. "Steps in Conflict Resolution" • "Stages of X" → e.g. "Stages of Team Development" • "Phases of X" → e.g. "Phases of Project Delivery" • "Components of X" → e.g. "Components of Effective Feedback" • "Elements of X" → e.g. "Elements of Persuasion" • "Pillars of X" → e.g. "Pillars of Leadership" • "Areas of X" → e.g. "Areas of Personal Development" • "Principles of X" → e.g. "Principles of Active Listening" • "Techniques of X" → e.g. "Techniques of a Good Public Speaker" • "Methods of / Methods for X" • "Approaches to X" • "Strategies for X" • "Skills of X" / "Skills for X" • "Aspects of X" • "Tools for / Tools Every X" • "Tips for X" / "Best Practices for X" These titles ALL imply a named-list structure. Even if the LLM "feels" that bullets in a text_only slide would express the content cleanly, that is WRONG — use the overview_groups (or groups) infographic visualisation instead, because: (a) Learners retain visual structures better than bulleted prose. (b) Each named item warrants its own drill_down with deep explanation. (c) Text_only walls of bullets produce visually monotonous decks. If you find yourself drafting bullets like "Informative: ...", "Persuasive: ...", "Demonstrative: ..." inside a text_only slide — STOP. Convert to overview_groups + drill_downs (one per type), or to groups if there are exactly 4 types. TITLE RULE: - drill_down slides after overview_groups: use the EXACT SAME title as the overview_groups. - Standalone groups (4 items): use a clear topic-level title, NOT a subtitle listing items. - NEVER title a slide "Employment Law: Contracts, Rights, and Handbooks" when the overview was "Key Areas of Employment Law" — copy the overview title exactly. WHEN TO USE text_only (and ONLY these cases): - Introducing a module or topic (what it is, why it matters) — paragraphs - Explaining the background or history — paragraphs - Defining a single concept in depth (2+ paragraphs of connected prose) — paragraphs - Listing 4-6 facts/rules where the exact wording matters — bullets text_only is NOT for "let me list the N kinds of X". That goes to groups/overview_groups. NEVER use text_only to list named techniques, steps, or principles. That is what groups is for. MODULE CONTENT PATTERN — follow this sequence for EVERY major topic: 1. text_only "paragraphs" — define and contextualise the topic (what it is, why it matters) 2. overview_groups — show ALL named items visually (labels only, same title throughout) 3. drill_down × N — explain each item (one slide per item, SAME TITLE as overview) 4. text_only "paragraphs" — common mistakes, real-world application, or deeper insight For 4-item topics (no overview needed): 1. text_only "paragraphs" — context 2. groups — all 4 items with descriptions on one visual slide MODULE OPENER VARIETY RULE (non-negotiable): The first 3 content slides AFTER a module_intro must NOT be three text_only slides in a row. Pedagogically, learners need visual variety from the start of each module — three text walls in sequence kills attention. Acceptable openers (pick one): OK: text_only → overview_groups → drill_down ... OK: text_only → groups → drill_down (or text_only) OK: groups → text_only → drill_down ... NOT acceptable: BAD: text_only → text_only → text_only → ... BAD: text_only → text_only → groups (still 2 walls of text upfront) At most ONE text_only allowed in the first 3 content slides of any module. If you have multiple framing/context paragraphs to convey, COMBINE them into a single text_only slide rather than spreading across multiple. MODULE-END ASSESSMENT RULE (compliance/safety/HR/management only): After the content slides of each module, add ONE assessment slide: - Module 1, 3, 5, 7… → "scenario_qa" with 2 workplace scenarios - Module 2, 4, 6, 8… → "qa" (open Q&A marker) Do NOT add mid-module assessments. ONE per module at the END only. MANDATORY QUIZ RULE (applies to EVERY course type — soft skills, technical, HR, etc.): EVERY module — NO EXCEPTIONS — MUST contain 1-2 "quiz" slides. This rule is absolute and overrides every other distribution / pacing rule. Count rule (not a percentage — a hard minimum): • Every module: 1 quiz slide minimum, 2 quiz slides maximum • 5-module course → 5-10 quiz slides total • 4-module course → 4-8 quiz slides total • etc. Placement — where the quiz sits inside a module: • Standard module (content only): quiz goes AT THE END, after the content slides and BEFORE the next module_intro. • Practical-heavy module (contains scenario / case_study / activity slides): quizzes MUST STILL APPEAR. Place them AFTER the module_intro and BEFORE the practical block — i.e. quiz first, then scenarios/case_study/activity. • Final module of the course (often the practical block): same rule — emit 1-2 quizzes BEFORE the scenario / case_study / activity block. The presence of practical content does NOT excuse the module from quizzes. Each quiz slide is ONE MCQ: question + exactly 4 options + correct answer index. Test the actual concepts from THAT module — not generic knowledge. Varying difficulty across the 1-2 questions is ideal. SELF-CHECK before submitting: count the quiz slides per module. If ANY module has zero quizzes — including the practical/final module — go back and insert them. A course without quizzes in every module is INCOMPLETE and will be rejected. PRACTICAL SECTION RULE (skills courses only): After all module content (before the ending slide), add: 1. text_only "paragraphs" — title "Scenarios and Activities", describing what follows 2. 3-5 "scenario" slides 3. One "case_study" sequence (3 slides) 4. One "activity" sequence (3 slides) CONTINUED SLIDES: When a topic's content overflows, add "(Continued)" after the title on the next slide. Continued slides are ALWAYS text_only. ───────────────────────────────────────────────────────────────────────────────── WRITING QUALITY RULES ───────────────────────────────────────────────────────────────────────────────── - Write for adult professionals — plain language, specific detail, active voice. - Every sentence must deliver a useful piece of learning — no filler. - BAD: "Effective communication is important." - GOOD: "Managers who give specific, timely feedback reduce team errors by creating shared expectations." - bullets: subject + verb + meaningful detail (15-25 words each) - points: label = noun phrase ≤30 chars; text = full explanation 150-300 chars - paragraphs: each sentence builds on the last — connected narrative - groups label: 2-4 word noun phrase ≤30 chars — NO verbs, NO sentences - groups desc: ONE sentence ≤120 chars — the single most important thing about this item ───────────────────────────────────────────────────────────────────────────────── SLIDE COUNT GUIDANCE ───────────────────────────────────────────────────────────────────────────────── Fixed: 1 cover + 1 about_us + 1 syllabus + 1 ending + 1 module_intro per module + 1-2 quiz slides per module (placed AFTER that module's content, BEFORE the next module_intro). When a target is given, HIT IT EXACTLY. Count as you write. Do not stop early. Each major topic = 4-8 slides minimum (definition → why → how → examples). TARGET DISTRIBUTION (match this — groups must dominate, not text_only): ~40% groups / overview_groups ← YOUR PRIMARY CONTENT FORMAT ~25% text_only ← supporting context and prose only ~20% structural (cover/about/syllabus/module_intro/quiz/ending) ~10% assessment (qa / scenario_qa) — if applicable ~5% practical (scenario / case_study / activity) — if skills course SELF-CHECK before finalising: Count your groups slides. If groups < 35% of total, you have used too much text_only. Go back and convert bullet lists into groups slides. SECOND SELF-CHECK — TRAINER NOTES: scan every slide object before submitting. If even ONE slide is missing a `notes` field with 80-150 words of trainer speaker-notes, your output is invalid. The notes are MANDATORY on every slide type — including cover, about_us, syllabus, module_intro, content slides, quizzes, and ending. Do not submit until every slide has notes. ───────────────────────────────────────────────────────────────────────────────── OUTPUT — return ONLY valid JSON, no markdown, no explanation Every slide object below INCLUDES a `notes` field — yours must do the same. ───────────────────────────────────────────────────────────────────────────────── {"slides": [ {"type": "cover", "title": "HR Skills for Managers", "subtitle": "Trainer Guide", "notes": "Welcome the group and introduce yourself. Set the tone — this is a practical session about decisions managers make every week that carry legal weight. Ask each delegate to share one HR situation they've handled recently; this primes them to map their experience to the content. Spend 2-3 minutes here."}, {"type": "about_us", "notes": "Brief intro to The Knowledge Academy. Keep it short — 60 seconds. Mention our reach (countries trained, learner count if known) only if relevant to building credibility with this group. Move on quickly."}, {"type": "syllabus", "modules": ["Module 1: Employment Law", "Module 2: Managing Absence"], "notes": "Walk through the modules at a high level. Flag that Module 1 is the legal foundation everything else builds on, and Module 2 applies it to a specific high-frequency scenario. Ask the room which module they're most worried about — gives you a signal of where to slow down later."}, {"type": "module_intro", "module_num": 1, "module_title": "Employment Law", "description": "This module covers the legal framework every manager must understand.", "topics": ["Employment Contracts", "Employee Rights", "Disciplinary Process"], "notes": "Pitch the module: most managers think HR handles this stuff, but tribunals award against the line manager's decisions, not HR's. The goal isn't to make them lawyers — it's to make them spot the legal weight in everyday decisions. Preview the three topics and flag that disciplinary process is where most tribunal claims originate. 90 seconds total."}, {"type": "text_only", "title": "Why Employment Law Matters for Managers", "paragraphs": [ "Managers make decisions every day that carry legal weight — from handling absence to ending employment. Without understanding the legal framework, even well-intentioned decisions can expose the organisation to costly tribunal claims.", "This module gives you the practical legal knowledge to act confidently and correctly, protecting both your team and the organisation." ], "notes": "Open with a concrete: 'How many of you have made an employment decision in the last month that you double-checked with HR?' Most hands go up. Then: 'How many of you have made one and DIDN'T check?' That's the gap. Reinforce that the tribunal sees no difference between malice and ignorance — the cost is identical. Spend 3 minutes here; this sets up the legal-stakes framing for the whole module."}, {"type": "overview_groups", "title": "Six Areas Every Manager Must Know", "visual_type": "framework", "items": [ {"label": "Employment Contracts", "notes": "This card focuses on the employment contract — the legal foundation of every working relationship. Emphasise that managers often think a verbal agreement is binding only loosely; in reality offer-and-acceptance creates the contract immediately. Share an example: a manager who said 'you've got the job' over the phone and later tried to withdraw — case law went against the employer. Ask the room: 'Has anyone here ever made an informal offer they later wished they hadn't?' Use answers to bridge into the two-month written-particulars rule."}, {"label": "Disciplinary Process", "notes": "This is the highest-risk area in the framework. The most-quoted number is the 25% uplift on tribunal awards when the ACAS Code is ignored — repeat it. Walk through the four-step expectation: investigate → invite → hear → decide (with right of appeal). Ask: 'How many of you have ever skipped the investigation stage to save time?' Most will admit they have. That's exactly where unfair-dismissal claims succeed. Use the answers to set up the next drill_down."}, {"label": "Termination Rules", "notes": "The exit door is where tribunals concentrate. Three fair-dismissal reasons matter most: capability, conduct, redundancy. Stress that having a fair REASON isn't enough — you must also follow a fair PROCESS. Example: a redundancy where the criteria were valid but the consultation was rushed — tribunal still rules unfair. Ask: 'What's the most recent termination decision your team has made? Walk us through the steps.' Use the answer to test process awareness."} ], "notes": "Walk the areas as a mental map. Flag that contracts and rights are the FOUNDATION (everything else assumes they're in place); the high-risk delivery points are discipline, grievance, and termination — that's where tribunals happen. Ask: 'Which of these does your team feel least confident on?' Use that to allocate time across the rest of the module. Keep this slide short — 90 seconds. We dive into each next."}, {"type": "groups", "title": "Four Areas Every Manager Must Know", "intro_points": [ "These four areas form the legal backbone of employment.", "Each one is enforced by specific statute and common law." ], "visual_type": "framework", "items": [ {"label": "Contracts", "bullets": ["A contract is legally binding from the moment an offer is accepted.", "Managers must never alter terms without written employee agreement.", "The Employment Rights Act requires written particulars within two months."], "notes": "Open with the binding moment: when a candidate says 'yes' to a verbal offer, the contract is formed — even before paperwork. Common error: managers think verbal offers can be withdrawn freely. Reinforce the two-month written-particulars rule. Ask: 'How fast does YOUR onboarding produce a written statement?' Most teams will admit it slips. That's the teachable moment. ~90 seconds."}, {"label": "Discipline", "bullets": ["Every disciplinary action must follow the ACAS Code of Practice.", "Skipping investigation, hearing, or right-of-appeal makes the action unfair.", "Tribunals can uplift awards by 25% where the ACAS Code was ignored."], "notes": "This is where most tribunal claims succeed. The 25% uplift number is the sticky figure — repeat it. Walk the four-step expectation: investigate → invite → hear → decide (with appeal). Common shortcut: skipping investigation 'because it's obvious'. That alone makes the outcome automatically unfair. Ask: 'How many of you have ever skipped a step to save time?' Most have. ~90 seconds."} ], "notes": "Take each block for ~90 seconds. After the blocks, ask: 'Have you ever skipped one of these steps to move faster?' Most have. Use that as the bridge to the next slide. 6-8 minutes total."}, {"type": "groups", "title": "Six Areas Every Manager Must Know", "intro_points": [ "Grievance and termination rules complete the legal picture.", "How they interact determines whether a dismissal is fair." ], "visual_type": "framework", "items": [ {"label": "Grievances", "bullets": ["All grievances must be taken seriously and investigated promptly.", "A written response is required within a reasonable timeframe.", "Failing to follow procedure invites tribunal claims."]}, {"label": "Termination", "bullets": ["Dismissal is fair only when reason is valid and process is fair.", "Both substance and procedure must be satisfied or the tribunal rules against.", "Documentation throughout is essential evidence."]}, {"label": "ACAS Code", "bullets": ["Following the ACAS Code of Practice is not optional.", "Tribunals apply up to 25% uplift where the code was not followed.", "Managers must know the steps and apply them consistently."]}, {"label": "Statutory Rights", "bullets": ["Redundancy pay, notice periods, and written reasons are statutory.", "These rights apply regardless of what the contract says.", "Contract clauses that waive statutory rights are unenforceable."]} ], "notes": "Close the framework with the back-end of employment. Grievance + Termination are where you'll see the most tribunals — they're the exit-door processes and emotions run high. Reinforce that the ACAS Code is the playbook every tribunal expects you to have followed. Statutory rights: useful framing — even if the contract says otherwise, the statute wins. Ask: 'Has anyone here ever had to defend a termination decision?' If yes, draw out the story. 5-6 minutes."}, {"type": "text_only", "title": "The Most Common Legal Mistakes Managers Make", "lead_in": "Understanding the rules is only half the challenge — knowing where managers go wrong protects you from expensive errors.", "bullets": [ "Changing an employee's contract verbally without written confirmation creates a dispute about what was actually agreed.", "Skipping the investigation stage before a disciplinary hearing makes any outcome automatically unfair at tribunal.", "Treating a performance issue as misconduct — or vice versa — leads to the wrong process and an invalid outcome." ], "notes": "These three are the most expensive mistakes. Walk through each with a real-world cost: verbal contract changes lead to 'he-said-she-said' tribunals where the employee usually wins. Skipping investigation makes the outcome automatically unfair regardless of how clear-cut the case was. Misclassifying performance as misconduct uses the wrong process and gets the action overturned. Ask: 'Which of these three is your team most at risk of?' Use answers to flag what to circle back to. 4 minutes."}, {"type": "scenario_qa", "scenarios": [ {"num": 1, "text": "Scenario: A manager discovers an employee has been accessing colleagues' personal files on the shared drive. HR has not been informed. What steps should the manager take immediately, and what process must be followed?"}, {"num": 2, "text": "Scenario: An employee returns from long-term sick leave and is told their role has been restructured and no longer exists. The employee believes this is unfair dismissal. What are the manager's obligations and what risks does the organisation face?"} ], "notes": "Break the room into pairs. Give 5 minutes for each scenario. Scenario 1 tests data-protection awareness — they should preserve evidence, suspend access, notify HR/IT, not confront the employee yet. Scenario 2 is a classic 'sham redundancy' setup — proper consultation, genuine redundancy criteria, and right to be considered for alternative roles. Walk pairs through what they'd do, then take 2-3 answers from the room. Don't give the 'right answer' too early — let them argue. 12-15 minutes total."}, {"type": "quiz", "module_num": 1, "question_num": 1, "question": "Which document is legally required to be issued to a new employee within two months of starting?", "options": ["Job description", "Written statement of particulars", "Employee handbook", "Code of conduct"], "answer_index": 1, "notes": "Correct answer: B — Written statement of particulars. This is the Employment Rights Act requirement: written terms within two months, including pay, hours, holiday, notice. Distractors: 'Job description' is common practice but not legally required; 'Employee handbook' is often issued but not the statutory document; 'Code of conduct' may exist but doesn't satisfy the two-month rule. Debrief: ask the room if their own onboarding process produces this within two months — most will admit it doesn't, which is the teaching moment."}, {"type": "quiz", "module_num": 1, "question_num": 2, "question": "If a tribunal finds the ACAS Code of Practice was ignored, by how much can awards be uplifted?", "options": ["10%", "15%", "25%", "50%"], "answer_index": 2, "notes": "Correct answer: C — 25%. This is the maximum statutory uplift under section 207A of the Trade Union and Labour Relations (Consolidation) Act 1992. Distractors: 10% and 15% sound plausibly conservative; 50% is the cap on the OPPOSITE uplift (where the EMPLOYEE failed to follow the code). The 25% number is the most-cited figure managers should remember. Debrief: emphasise that uplifts compound on already-substantial awards — a £50k award becomes £62.5k just for skipping process."}, {"type": "ending", "notes": "Thank the room. Recap the three biggest takeaways: tribunals judge process more than outcome, the ACAS Code is the playbook, and statutory rights cannot be contracted away. Point to the further-reading slide or post-course resource if applicable. Invite one final question. Keep this slide to 90 seconds — they're tired by the end."} ]} """ # ── Slide count targets ──────────────────────────────────────────────────────── _DURATION_TARGETS = { # Plan-entry targets calibrated to final PPTX slide counts. # # Builder expansion in practice is ~1.14× (overview_groups expand into # 1 overview + N drill_down child cards, but most plan entries are # single-slide text_only / drill_down so the average is far below the # old 1.65× assumption). These targets land in the per-day ranges below: # # 1 day → 80–95 slides (target: 80 plan entries ≈ 91 final) # 2 days → 160–190 slides (target: 160 plan entries ≈ 182 final) # 3 days → 240–285 slides (target: 240 plan entries ≈ 273 final) # 4 days → 320–380 slides (target: 320 plan entries ≈ 364 final) # 5 days → 400–475 slides (target: 400 plan entries ≈ 455 final) 1: 80, 2: 160, 3: 240, 4: 320, 5: 400, } # ── Main planning function ───────────────────────────────────────────────────── def _salvage_truncated_plan(raw: str) -> dict | None: """ Attempt to recover a usable plan from truncated JSON. Strategy: scan for `{"slides": [` then walk forward closing-brace by closing-brace, accepting each substring that parses cleanly. Return the largest prefix that yields N >= 1 complete slide objects, with the array and outer object closed. Returns None if no complete slide could be salvaged. """ if not raw: return None start = raw.find('"slides"') if start < 0: return None arr_start = raw.find("[", start) if arr_start < 0: return None # Walk the substring counting braces — find every position where we have # just-closed a top-level slide object inside the slides array. depth = 0 in_str = False escape = False object_end_positions: list[int] = [] array_depth = 0 for i in range(arr_start, len(raw)): ch = raw[i] if escape: escape = False continue if ch == "\\": escape = True continue if ch == '"': in_str = not in_str continue if in_str: continue if ch == "[": array_depth += 1 elif ch == "]": array_depth -= 1 elif ch == "{": depth += 1 elif ch == "}": depth -= 1 # When we close a top-level object inside the slides array, # record this position as a possible salvage cut-point. if depth == 0 and array_depth == 1: object_end_positions.append(i) if not object_end_positions: return None # Try the largest first, working backwards if a candidate fails to parse. for end in reversed(object_end_positions): candidate = raw[:end + 1] + "]}" try: data = json.loads(candidate) if isinstance(data, dict) and isinstance(data.get("slides"), list) and data["slides"]: return data except json.JSONDecodeError: continue return None def plan_course( api_key: str, outline: str, course_title: str = "", target_slides: int = 0, duration_days: int = 0, model: str = "claude-sonnet-4-6", language: str = "uk", ) -> list[dict]: """ Call Claude Sonnet to convert *outline* into a full typed slide plan. `language` is "uk" or "us" — controls English spelling/vocabulary throughout (organisation vs organization, behaviour vs behavior, etc). Parameters ---------- api_key Anthropic API key. outline Course outline as plain text. course_title Optional override for the course name. target_slides Explicit slide count target. Overrides duration_days. duration_days Course duration in days (1-5). Derives target automatically. model Claude model ID (default: Sonnet for quality). Returns ------- List of slide dicts. """ import anthropic if target_slides <= 0 and duration_days > 0: target_slides = _DURATION_TARGETS.get(duration_days, 0) target_note = "" if target_slides > 0: target_note = ( f"\nTARGET SLIDE COUNT: {target_slides} slides — YOU MUST HIT THIS EXACTLY.\n" f"Do NOT stop early. Expand every topic deeply.\n" f"Each major topic = 4-8 slides minimum.\n" f"Keep a running count as you write." ) lang = (language or "uk").lower() if lang == "us": language_note = ( "\nLANGUAGE: Write the ENTIRE course in US English. Use US " "spelling and vocabulary throughout — color, organization, " "behavior, program, center, defense, license, practice (both " "noun and verb), realize, prioritize, focused, analyzed, " "modeling, traveled, etc. Do NOT mix UK and US spellings.\n" ) else: language_note = ( "\nLANGUAGE: Write the ENTIRE course in UK English. Use UK " "spelling and vocabulary throughout — colour, organisation, " "behaviour, programme, centre, defence, licence (noun) / " "license (verb), practise (verb) / practice (noun), realise, " "prioritise, focussed, analysed, modelling, travelled, etc. " "Do NOT mix UK and US spellings.\n" ) user_msg = ( f"Course title: {course_title or '(extract from outline)'}\n\n" f"Course outline:\n{outline}" f"{target_note}" f"{language_note}\n" f"Generate a complete slide plan following all rules exactly.\n" f"REMINDER: every slide object MUST include a `notes` field of\n" f"80-150 words of trainer speaker-notes. Without notes the output\n" f"will be rejected. Notes go on EVERY slide of EVERY type —\n" f"including cover, about_us, syllabus, module_intro, text_only,\n" f"groups, overview_groups, drill_down, scenario, scenario_qa,\n" f"quiz, qa, case_study, activity, and ending. No exceptions.\n" f"Return ONLY the JSON object — no markdown fences, no comments." ) client = anthropic.Anthropic(api_key=api_key) # Sonnet 4.6 natively supports 64k output tokens — no beta header needed. # The old `output-128k-2025-02-19` beta was for Sonnet 3.7 and gets # silently ignored on 4.6, causing the request to fall through to the # silent fallback path with max_tokens=16000 → truncated JSON. # # We MUST stream — the Anthropic SDK refuses non-streaming calls whose # expected output may exceed 10 minutes, and 64k tokens on Sonnet 4.6 # crosses that threshold. The streaming context manager collects all # chunks and exposes the final message via get_final_message(). with client.messages.stream( model=model, max_tokens=64000, system=[{ "type": "text", "text": _SYSTEM, "cache_control": {"type": "ephemeral"}, # prompt caching — 10× cheaper on repeats }], messages=[{"role": "user", "content": user_msg}], ) as stream: # Drain the stream — get_final_message() requires it. for _ in stream.text_stream: pass response = stream.get_final_message() raw = response.content[0].text.strip() raw = re.sub(r"^```(?:json)?\s*", "", raw) raw = re.sub(r"\s*```$", "", raw) # Persist raw response BEFORE parsing — if JSON is invalid we can still # inspect what the model produced and salvage manually rather than # losing the entire generation cost. try: from pathlib import Path as _Path debug_dir = _Path(__file__).resolve().parent.parent.parent / "web" / "uploads" / "outputs" debug_dir.mkdir(parents=True, exist_ok=True) stamp = __import__("time").strftime("%Y%m%d_%H%M%S") (debug_dir / f"_last_plan_raw_{stamp}.txt").write_text(raw, encoding="utf-8") except Exception: pass # Log what we got back so we can spot truncation / refusal at a glance stop_reason = getattr(response, "stop_reason", None) usage = getattr(response, "usage", None) in_tok = getattr(usage, "input_tokens", None) if usage else None out_tok = getattr(usage, "output_tokens", None) if usage else None print(f" [planner] stop_reason={stop_reason!r} input_tokens={in_tok} output_tokens={out_tok} raw_chars={len(raw)}") if stop_reason == "max_tokens": print(f" [planner] WARNING: hit max_tokens cap ({out_tok}) — output likely truncated") try: data = json.loads(raw) except json.JSONDecodeError as exc: # Attempt a simple salvage: trim back to the last complete slide # object, then close the array/object so the partial plan is usable. salvaged = _salvage_truncated_plan(raw) if salvaged is not None: data = salvaged print(f" [planner] JSON was truncated — salvaged {len(salvaged.get('slides', []))} complete slides from partial output") else: raise slides = data.get("slides", data) if isinstance(data, dict) else data # Normalise legacy field names so old slide types still work normalised = [_normalise_slide(s) for s in slides] # Visibility on notes coverage — surface in the build log so we can tell # at a glance whether the LLM is following the notes requirement. total = len(normalised) with_notes = sum(1 for s in normalised if (s.get("notes") or "").strip()) pct = (with_notes / total * 100) if total else 0 print(f" [planner] trainer notes coverage: {with_notes}/{total} slides ({pct:.0f}%)") if with_notes < total: missing = [i for i, s in enumerate(normalised) if not (s.get("notes") or "").strip()] sample = missing[:6] print(f" [planner] WARNING: {len(missing)} slides missing notes (indices: {sample}{'...' if len(missing) > 6 else ''})") return normalised def plan_from_file(api_key: str, outline_path: str, **kwargs) -> list[dict]: """Convenience wrapper: read outline from a text file and plan it.""" with open(outline_path, encoding="utf-8") as f: outline = f.read() return plan_course(api_key, outline, **kwargs) # ── Field normalisation — backward compatibility ─────────────────────────────── def _normalise_slide(s: dict) -> dict: """ Map legacy slide type names and fields to the current schema. Legacy → New: infographic → groups text_infographic → groups infographic_overview → overview_groups """ s = dict(s) stype = s.get("type", "") if stype == "infographic": s["type"] = "groups" if "steps" in s and "items" not in s: s["items"] = s.pop("steps") elif stype == "text_infographic": s["type"] = "groups" if "steps" in s and "items" not in s: s["items"] = s.pop("steps") if "paragraphs" in s and "intro_points" not in s and "intro" not in s: paras = s.pop("paragraphs") s["intro_points"] = paras[:2] if paras else [] elif stype == "infographic_overview": s["type"] = "overview_groups" if "steps" in s and "items" not in s: s["items"] = s.pop("steps") # case_study / activity: "content" → "paragraphs" if planner used old field name elif stype in ("case_study", "activity"): if "content" in s and "paragraphs" not in s: s["paragraphs"] = s.pop("content") # Backwards-compat: legacy "intro" string → "intro_points" list. # Old cached plans use a single intro string; convert without re-planning. if "intro" in s and "intro_points" not in s: legacy = s.pop("intro").strip() s["intro_points"] = [legacy] if legacy else [] # Backwards-compat: legacy item "description" string → "bullets" list. # Old cached plans have single-sentence descriptions per item; split into # 1-3 bullets by sentence boundary so the new bullet renderer has content. if s.get("type") in ("groups", "drill_down"): items = s.get("items") or s.get("steps") or [] migrated = False for it in items: if "bullets" in it and isinstance(it["bullets"], list): continue desc = (it.get("description") or "").strip() if not desc: continue raw = desc.rstrip(".") parts = [p.strip() for p in raw.replace("; ", ".|").replace(". ", ".|").split("|") if p.strip()] if not parts: parts = [desc] it["bullets"] = parts[:3] it.pop("description", None) migrated = True if migrated and "items" in s: s["items"] = items # Hard-cap groups / overview_groups item count at 6. The bank is unreliable # for 7+ item infographics (SmartArt rejections) — capping here protects # downstream renderers from falling back to text_only on long topics. if s.get("type") in ("groups", "overview_groups"): items = s.get("items") or s.get("steps") or [] if len(items) > 6: print(f" [migrate] {s.get('type')} has {len(items)} items — capping at 6 " f"(title={s.get('title','')!r})") items = items[:6] if "items" in s: s["items"] = items elif "steps" in s: s["steps"] = items # visual_type="comparison" is only valid for exactly 2 items. # When violated, demote to "framework" (the safe N-component default). if s.get("visual_type") == "comparison" and len(items) != 2: print(f" [migrate] {s.get('type')} title={s.get('title','')!r} has " f"visual_type=comparison with {len(items)} items — demoting to framework") s["visual_type"] = "framework" return s # ── Known slide type sets ───────────────────────────────────────────────────── _STRUCTURAL_TYPES = {"cover", "about_us", "syllabus", "module_intro", "quiz", "ending"} _ASSESSMENT_TYPES = {"qa", "scenario_qa"} _PRACTICAL_TYPES = {"scenario", "case_study", "activity"} _CONTENT_TYPES = {"text_only", "groups", "overview_groups", "drill_down"}