Prompt Reference

This page shows the exact prompt templates sent to the Gemini API, with annotations explaining where each variable comes from.

Lesson Prompt

Template file: apps/ai_engine/templates/ai_engine/lesson_prompt.md

The prompt is rendered as a Django template. Variables are populated from the Lesson.generation_meta JSON and related model lookups in apps/ai_engine/tasks.py::_build_lesson_prompt.

Generate a complete, ready-to-use lesson plan addressed to the TEACHER. Start with a clear title as a markdown heading (# Title).

### TEACHING PERSONA: {{ persona_name }}
{{ persona_instructions }}
{% if teacher %}

### TEACHER PROFILE
- **Bio:** {{ teacher.bio|default:"Not specified" }}
- **Teaching Style:** {{ teacher.teaching_style|default:"Not specified" }}
- **Strengths:** {{ teacher.strengths|default:"Not specified" }}
- **Weaknesses:** {{ teacher.weaknesses|default:"Not specified" }}
{% endif %}

### LEARNER
- **Name:** {{ learner.name }}
- **Age:** {{ learner_age }}
- **Learning style:** {{ learner.learning_style|default:"Not specified" }}
- **Strengths:** {{ learner.strengths|default:"Not specified" }}
- **Areas for development:** {{ learner.weaknesses|default:"Not specified" }}

### LESSON FOCUS
{% if mode == 'extension' %}
Build on the following source lesson, addressing gaps or next steps.

**Source Lesson:** {{ source_lesson.title }}

{{ source_lesson.content }}
{% if achievements %}

**Achievements from source lesson:**
{% for a in achievements %}
- {{ a.timestamp|date:"Y-m-d" }}: {{ a.description }}
{% endfor %}
{% endif %}
{% if goal %}

**Extension focus:** {{ goal }}
{% endif %}
{% elif mode == 'targeted' %}
{{ goal }}
{% elif mode == 'suggestions' %}
Suggest a logical next lesson based on recent achievements.
{% else %}
{{ frequency|default:"" }} lesson based on recent achievements.
{% endif %}

### CONTEXT
- **Related tags:** {{ tags_context|default:"None specified" }}
- **Available tools/inventory:** {{ inventory_context|default:"None" }}

### RECENT ACHIEVEMENTS (last {{ achievement_days }} days, today is {{ today|date:"Y-m-d" }})
{% if lesson_linked_groups %}

#### Achievements linked to prior lessons
{% for group in lesson_linked_groups %}

**Lesson: {{ group.lesson.title }}**  (earliest recent achievement {{ group.days_ago_label }}, {{ group.lesson_date|date:"Y-m-d" }}){% if not group.include_full_content %} — title only{% endif %}

Achievements from this lesson:
{% for a in group.achievements %}
- {{ a.timestamp|date:"Y-m-d" }}: {{ a.description }}
{% endfor %}
{% if group.include_full_content %}

Lesson content:
{{ group.lesson.content }}
{% endif %}

---
{% endfor %}
{% endif %}
{% if free_achievements_by_date %}

#### Other achievements (no associated lesson)
{% for day in free_achievements_by_date %}

**{{ day.date|date:"Y-m-d" }} ({{ day.relative_label }}):**
{% for a in day.list %}
- {{ a.description }}
{% endfor %}
{% endfor %}
{% endif %}
{% if not lesson_linked_groups and not free_achievements_by_date %}
No recent achievements.
{% endif %}

{{ format_instructions }}

Variable Reference

Variable	Source	Default
persona_name	TeacherPersona.name (looked up by generation_meta.persona_id, scoped to teacher)	"an expert homeschool teacher"
persona_instructions	TeacherPersona.prompt_instructions	"Your goal is to provide exceptional, tailored educational content."
teacher.bio	Teacher.bio	"Not specified"
teacher.teaching_style	Teacher.teaching_style	"Not specified"
teacher.strengths	Teacher.strengths	"Not specified"
teacher.weaknesses	Teacher.weaknesses	"Not specified"
learner.name	Learner.name	--
learner_age	Learner.age property (calculated from birthdate)	"unknown"
learner.learning_style	Learner.learning_style	"Not specified"
learner.strengths	Learner.strengths	"Not specified"
learner.weaknesses	Learner.weaknesses	"Not specified"
tags_context	Comma-joined Tag.name values for IDs in generation_meta.tag_ids	"None specified"
inventory_context	Comma-joined InventoryItem.name values for IDs in generation_meta.inventory_ids (teacher-scoped, active only)	"None"
achievement_days	Lookback window (days). For on-demand generation: generation_meta.achievement_days, clamped to 1–90, default 7. For scheduled generation: hard-coded to 7.	7
today	timezone.localdate() — the local date when the prompt was built, used in the header and to compute "N days ago" labels.	--
lesson_linked_groups	List of {lesson, lesson_date, days_ago_label, achievements, include_full_content} dicts built by _build_achievement_context. Achievements within the lookback window that have a non-null lesson FK, grouped by source lesson and sorted by the earliest linked achievement timestamp descending (with lesson.created_at as tiebreaker). lesson_date is the earliest linked achievement timestamp within the visible window — surfaced in the prompt as "earliest recent achievement N days ago". The true first-exposure date may lie outside the window; we trade some precision for zero extra DB cost. The first FULL_LESSON_CONTENT_LIMIT (= 2) groups have include_full_content=True so the full lesson.content is rendered; older groups render title + date only.	empty list (section is skipped)
free_achievements_by_date	List of {date, relative_label, list} dicts built by _build_achievement_context. Achievements with no source lesson, grouped by timestamp date and sorted descending. relative_label is "today", "yesterday", or "N days ago".	empty list (section is skipped)
format_instructions	OutputTemplate.format_instructions (looked up by generation_meta.template_id, scoped to teacher, type=lesson)	See default below

Default format instructions (when no output template is selected):

Generate a complete, ready-to-use lesson. Start with a clear title as a markdown heading (# Title).
Include learning objectives, activities, and discussion questions.
Output only the lesson content, no preamble.

Lesson Focus by Mode

The LESSON FOCUS section changes depending on the generation mode stored in generation_meta.mode. The full conditionals are shown in the template above. Here is a summary of each mode:

Mode	Trigger	Content
targeted	User provides a goal	The goal text is inserted directly
extension	User selects a parent lesson	Source lesson title + content, achievements linked to that lesson (via {% for a in achievements %}), optional extension focus
suggestions	User picks "Suggestions" tab	Static text: "Suggest a logical next lesson based on recent achievements."
(no mode)	Auto-scheduled generation	{{ frequency }} (daily/weekly) + "lesson based on recent achievements."

---

Report Prompt

Template file: apps/records/templates/records/report_prompt.md

The prompt is rendered as a Django template. Variables are populated in apps/records/tasks.py::_build_report_prompt.

You are generating a {{ report.get_period_type_display|lower }} progress report for a learner.

### LEARNER
- **Name:** {{ learner.name }}
- **Age:** {{ learner.age|default:"unknown" }}
- **Learning style:** {{ learner.learning_style|default:"Not specified" }}
- **Strengths:** {{ learner.strengths|default:"Not specified" }}
- **Areas for development:** {{ learner.weaknesses|default:"Not specified" }}

### PERIOD: {{ report.period_start }} to {{ report.period_end }} ({{ report.get_period_type_display }})

### ACHIEVEMENTS ({{ achievements|length }} total)
{% if achievements %}
{% for achievement in achievements %}
- {{ achievement.timestamp|date:"Y-m-d" }}: {{ achievement.description }}{% if achievement.tags.all %} [{{ achievement.tags.all|join:", " }}]{% endif %}
{% endfor %}
{% else %}
No achievements recorded for this period.
{% endif %}

{{ format_instructions }}

Variable Reference

Variable	Source	Default
report.get_period_type_display	Report.get_period_type_display() — "Daily", "Weekly", "Monthly", "Annual", or "Custom" (lowercased in the opening line)	--
learner.name	Learner.name	--
learner.age	Learner.age property	"unknown"
learner.learning_style	Learner.learning_style	"Not specified"
learner.strengths	Learner.strengths	"Not specified"
learner.weaknesses	Learner.weaknesses	"Not specified"
report.period_start	Report.period_start (date)	--
report.period_end	Report.period_end (date)	--
achievements	All Achievement records where timestamp is between period_start and period_end, ordered by timestamp, with tags prefetched. When the matching ReportAutoSchedule has tags set, achievements are filtered to only those with matching tags. Count shown via achievements|length.	--
format_instructions	Resolved in priority order: 1) Report.template.format_instructions (set explicitly or copied from the auto-schedule at enqueue time), 2) built-in default	See default below

Default format instructions (generated dynamically based on period type, e.g. for "weekly"):

Write a clear, encouraging weekly progress report covering:
1. What was covered and learned
2. Notable achievements or breakthroughs
3. Areas of strength demonstrated
4. Areas to continue developing
5. Suggested focus for the coming week

Write in plain markdown. Be specific — reference actual achievements where relevant.
Output only the report itself, no preamble.

Example: Rendered Lesson Prompt

To illustrate what Gemini actually receives, here is an example of a fully rendered lesson prompt:

Generate a complete, ready-to-use lesson plan addressed to the TEACHER.
Start with a clear title as a markdown heading (# Title).

### TEACHING PERSONA: Gentle Socratic
Ask guiding questions rather than giving direct answers. Use real-world
examples from everyday life. Break complex ideas into small steps.

### TEACHER PROFILE
- **Bio:** Homeschooling parent of two, background in environmental science
- **Teaching Style:** Hands-on, inquiry-based
- **Strengths:** Making abstract concepts tangible
- **Weaknesses:** Keeping younger learners focused during longer activities

### LEARNER
- **Name:** Alex
- **Age:** 8
- **Learning style:** Visual and hands-on
- **Strengths:** Curious, loves experiments, strong spatial reasoning
- **Areas for development:** Reading comprehension, staying on task

### LESSON FOCUS
Introduction to fractions using physical manipulatives

### CONTEXT
- **Related tags:** Maths, Number Sense
- **Available tools/inventory:** Fraction tiles, whiteboard, coloured counters

### RECENT ACHIEVEMENTS (last 7 days, today is 2026-05-09)

#### Achievements linked to prior lessons

**Lesson: Introduction to Multiplication**  (earliest recent achievement 2 days ago, 2026-05-07)

Achievements from this lesson:
- 2026-05-07: Completed multiplication tables 1-5 with 90% accuracy

Lesson content:
# Introduction to Multiplication

Today we'll explore multiplication as repeated addition. Use the fraction
tiles to make groups of equal size, then count the total.

Activities: ...

---

#### Other achievements (no associated lesson)

**2026-05-09 (today):**
- Identified basic shapes and their properties

**2026-05-07 (2 days ago):**
- Read a short passage and answered 3 comprehension questions

Generate a complete, ready-to-use lesson. Start with a clear title as a
markdown heading (# Title). Include learning objectives, activities, and
discussion questions. Output only the lesson content, no preamble.