learning-platform/docs/generation-spec.md

Generation spec: learning content & micro-learnings

Two generators turn a topic into learner-facing material. Both go through callLLM with forced tool use and Zod-validated output. All content is cached in PocketBase so it is generated once per topic/type.

---

A. Long-form content — src/lib/learningService.js

Stored in the content collection (one record per topic, data is a merged object). Three types, generated on demand:

Type	Tool	Min requirements
article	emit_learning_article	≥3 sections, ≥2 takeaways
slides	emit_learning_slides	≥4 slides
infographic	emit_learning_infographic	≥3 stats, ≥3 steps

generateLearningContent(topic, force, selectedType):

• tier standard, maxTokens: 8192
• selectedType is one of the three, or 'all' (emit_learning_all) for admin regeneration
• cache check looks at content[selectedType]; on generation the new payload is shallow-merged into the cached object so other types survive
• there is no podcast type

Article refinement (refineLearningContent): the admin describes a change and the model edits via targeted patch tools — set_intro, set_section, add_section, remove_section, replace_takeaways — so only the affected parts change. Patches are applied and re-validated in src/lib/articlePatches.js.

---

B. Micro-learnings — src/lib/microLearningService.js

Stored in the micro_learnings collection (one record per topic per type, status='published'). Three types:

Type	Tool	Tier	Shape
concept_explainer	emit_concept_explainer	standard	{ sections: [{ title, content (HTML) }] }, ≥3 sections
scenario_quiz	emit_scenario_quiz	standard	{ scenario, options: [{ text, isCorrect, explanation }] }, 3–4 options, exactly 1 correct
flashcard_set	emit_flashcard_set	fast (Haiku)	{ cards: [{ front, back }] }, 5–10 cards

getOrGenerateMicroLearning(topicId, type):

• returns the cached published record if one exists (findExisting)
• otherwise loads the topic, calls callLLM with forced tool choice, and creates a micro_learnings record with the validated content

A former reflection_prompt type was dropped. Do not re-add it.

Completion is recorded (append-only) by useMicroLearningCompletions into micro_learning_completions with { team_member_id, micro_learning_id, topic_id, type, session_week }.

---

C. Weekly quiz — src/lib/testService.js

Generates a 5-question multiple-choice test for the user's current week.

• Topic selection (selectTestTopics): primary topic from the active curriculum week (else hash fallback) + a few review topics for breadth.
• Batch generation (callQuizBatchModel): a single fast-tier call (emit_quiz_questions, maxTokens: 4096, 25s timeout) returns all 5 questions.
• Quality gates (validateBatchQuality): no duplicate options; no banned fillers ("all/none of the above", "both A and B"); explanations ≥20 chars; reject if correctIndex is dominated by one position (>80%) and re-roll.
• Scoring (saveTestResult): pointsEarned = score * 2, written to leaderboard via db.upsertLeaderboardEntry.

Question shape: { id, question, topicLabel, options[4], correctIndex (0–3), explanation, difficulty }.

---

D. Onboarding overviews — src/lib/onboardingService.js

Powers the 5-day onboarding track (issue #30): a short, breadth-first overview of one theme for a brand-new employee — deliberately light, not a deep lesson.

• Tool: emit_onboarding_overview · tier: fast (Haiku) · maxTokens: 1500, 60s timeout · schema onboardingOverviewSchema.
• Shape: { title, what_it_is, why_it_matters, key_points[3–5], topics_covered[{topic_id,label}] }. why_it_matters is framed around day-to-day / week-to-week work at Respellion.
• Cache: onboarding_overviews, one row per theme, keyed by theme name plus a topics_fingerprint (stable hash of the theme's sorted topic ids). getOrGenerateOnboardingOverview(theme, topics, {force}) returns the cached row when the fingerprint matches; a mismatch (topic added/removed) or force regenerates.
• Simulation: emit_onboarding_overview has a stub in SIMULATION_TOOL_STUBS.

Theme ordering + day grouping are pure helpers in the same module (orderThemes, distributeThemesIntoDays, computeTopicsFingerprint, computeOnboardingProgress, buildOnboardingPlan), unit-tested in src/lib/__tests__/onboardingService.test.js. Completion is recorded per theme in onboarding_completions ({ team_member_id, theme }), not per day.

---

Shared infrastructure (src/lib/llm.js)

• Tiers: fast (Haiku 4.5), standard (Sonnet 4.6), reasoning (Opus 4.7); per-tier admin overrides via admin:model:{tier}.
• Structured output: prefer tool use with forced toolChoice; inputs validated by toolSchemaRegistry. Text responses go through parseStructuredText.
• Caching: wrap stable system text with cachedSystem(...).
• Retry/limits: src/lib/llmRetry.js — backoff + jitter on 408/425/429/5xx/529, honors Retry-After, rate limiters for bulk work.
• Telemetry: every call logged to llm_calls.
• Simulation: with admin:use_simulation, calls return stub output (no API hit).