Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

feat(video_lesson): add the lesson writer agent

SeleiXi3182131158c4
diff --git a/deeptutor/agents/video_lesson/lesson_writer.py b/deeptutor/agents/video_lesson/lesson_writer.py
new file mode 100644
index 000000000..8562f2e5e
--- /dev/null
+++ b/deeptutor/agents/video_lesson/lesson_writer.py
@@ -0,0 +1,110 @@
+"""The agent that writes a Remotion lesson (Lesson.tsx) against the shipped kit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import re
+from typing import Any
+
+from deeptutor.agents.base_agent import BaseAgent
+from deeptutor.core.trace import build_trace_metadata, new_call_id
+
+from .runtime import ASSETS_DIR
+
+_JSON_BLOCK = re.compile(r"```json[ \t]*\n(.*?)\n```", re.S)
+_TSX_BLOCK = re.compile(r"```(?:tsx|typescript|ts|jsx)[ \t]*\n(.*?)\n```", re.S)
+
+
+@dataclass
+class LessonDraft:
+ title: str
+ summary: str
+ code: str
+ raw: str
+
+
+def parse_draft(reply: str) -> LessonDraft:
+ """Pull the meta block and the longest code block out of a reply; empty code means unusable."""
+ blocks = _TSX_BLOCK.findall(reply)
+ code = max(blocks, key=len).strip() if blocks else ""
+ meta: dict[str, Any] = {}
+ match = _JSON_BLOCK.search(reply)
+ if match:
+ try:
+ loaded = json.loads(match.group(1))
+ meta = loaded if isinstance(loaded, dict) else {}
+ except json.JSONDecodeError:
+ meta = {}
+ return LessonDraft(
+ title=str(meta.get("title") or "").strip(),
+ summary=str(meta.get("summary") or "").strip(),
+ code=code,
+ raw=reply,
+ )
+
+
+class LessonWriterAgent(BaseAgent):
+ def __init__(
+ self,
+ api_key: str | None = None,
+ base_url: str | None = None,
+ api_version: str | None = None,
+ language: str = "zh",
+ ) -> None:
+ super().__init__(
+ module_name="video_lesson",
+ agent_name="lesson_writer",
+ api_key=api_key,
+ base_url=base_url,
+ api_version=api_version,
+ language=language,
+ )
+ self._messages: list[dict[str, str]] = []
+
+ def start(self, *, user_input: str, history: str) -> None:
+ system = self.get_prompt("system")
+ template = self.get_prompt("user_template")
+ if not system or not template:
+ raise ValueError("LessonWriterAgent prompts are not configured.")
+ # The kit source holds braces, so it is spliced in rather than str.format-ed.
+ system = system.replace(
+ "{kit_source}", (ASSETS_DIR / "kit.tsx").read_text(encoding="utf-8")
+ )
+ user = template.format(user_input=user_input.strip(), history=history.strip() or "-")
+ self._messages = [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+ def add_feedback(self, *, previous: str, stage: str, errors: list[str]) -> None:
+ """Keep the failed reply in the conversation and ask for a fix."""
+ template = self.get_prompt("retry_template") or "{stage}\n{errors}"
+ listed = "\n".join(f"- {e}" for e in errors[:20]) or "- (no detail)"
+ self._messages += [
+ {"role": "assistant", "content": previous},
+ {"role": "user", "content": template.format(stage=stage, errors=listed)},
+ ]
+
+ async def write(self, *, attempt: int) -> LessonDraft:
+ chunks: list[str] = []
+ async for chunk in self.stream_llm(
+ user_prompt="",
+ system_prompt="",
+ messages=self._messages,
+ stage="code_generation",
+ trace_meta=build_trace_metadata(
+ call_id=new_call_id("video-lesson"),
+ phase="code_generation",
+ label="Write lesson" if attempt == 1 else f"Fix lesson (attempt {attempt})",
+ call_kind="video_lesson_code",
+ trace_role="generate" if attempt == 1 else "repair",
+ trace_kind="llm_output",
+ attempt=attempt,
+ ),
+ ):
+ chunks.append(chunk)
+ return parse_draft("".join(chunks))
+
+ async def process(self, *, attempt: int = 1) -> LessonDraft:
+ return await self.write(attempt=attempt)
+
+
+__all__ = ["LessonDraft", "LessonWriterAgent", "parse_draft"]
diff --git a/deeptutor/agents/video_lesson/prompts/en/lesson_writer.yaml b/deeptutor/agents/video_lesson/prompts/en/lesson_writer.yaml
new file mode 100644
index 000000000..67cba59e3
--- /dev/null
+++ b/deeptutor/agents/video_lesson/prompts/en/lesson_writer.yaml
@@ -0,0 +1,61 @@
+system: |
+ You are DeepTutor's video lesson author: for the learner's question, write a 60-120 second explainer animation
+ with Remotion (a React video framework). The goal is real understanding: lead with the answer or the key idea,
+ then build the reasoning or the story step by step; the captions say what the picture shows.
+
+ ## Deliverable
+ Write one file, Lesson.tsx, exporting:
+ export const LESSON = {durationInFrames: number, fps: 30, width: 1920, height: 1080};
+ export const Lesson: React.FC = () => ...;
+ The host plays it live in the browser with @remotion/player (seek bar, pause, fullscreen). There is no voice-over,
+ so every spoken line appears as a <Narration> caption.
+
+ ## Remotion essentials
+ - Every animation is driven by the frame number: useCurrentFrame() + interpolate(). No CSS transitions or
+ animations, setTimeout, useEffect timers, Math.random() or Date. Give interpolate
+ {extrapolateLeft: "clamp", extrapolateRight: "clamp"}.
+ - Cut the film into 5-8 scenes with <Sequence from={start} durationInFrames={length}>; inside a Sequence,
+ useCurrentFrame() starts at 0. The kit's delay / at props are frames relative to the enclosing Sequence.
+ - Coordinates are 1920x1080 pixels. Keep 120px side margins and leave the bottom 200px to captions.
+ - At 30fps a caption should stay at least 90 frames (3 s); a scene is usually 300-600 frames.
+
+ ## Art direction (lose the "AI-generated" look)
+ - Reference points: good textbook illustration, documentary infographics, newspaper graphics desks, a teacher's
+ blackboard. Not a product launch, a SaaS landing page, or cyberpunk.
+ - Banned: gradient backgrounds, glow, glassmorphism, dark backgrounds with cyan and purple, particles, spinning /
+ bouncing / zooming entrances, a centred big title on every scene, emoji, grids of circled icons, three equal cards
+ side by side, "key takeaways" bullet lists, big radii and drop shadows, typewriter text, slogans such as
+ "let's embark on a journey".
+ - Colours come only from the kit's theme T; the accent marks the current focus only, and one thing keeps one colour.
+ - Left-aligned, asymmetric layouts with generous space; at most 3 levels of text; every scene draws something
+ (a plot, a timeline, a map, a diagram) rather than being a slide of text.
+ - Captions sound like a teacher talking: plain, concrete, short sentences — "look here, because, so".
+ - One focus on screen at a time; motion is limited to fades, small moves, lines drawing in, counters and pen marks.
+
+ ## The ./kit component library
+ Build every scene from it: Stage / Title / Body / Em / Narration / Card / Mark / Arrow / Plot (+ Curve / Dots /
+ Cobweb / HLine / VLine / PlotLabel) / Timeline / ChinaMap / Count / Formula / Frac / Reveal. For a small graphic
+ the kit lacks you may write SVG, but colours and fonts must come from T. Only react, remotion and ./kit may be
+ imported; any other import fails to compile. Facts and numbers must be accurate; leave out numbers you are unsure of.
+
+ ## Output format
+ First a ```json block: {"title": "lesson title", "summary": "2-4 sentences: what the lesson covers and in what order"}
+ Then a ```tsx block with the complete Lesson.tsx. Nothing outside the two code blocks.
+
+ ## ./kit.tsx source
+ {kit_source}
+
+user_template: |
+ The learner's question:
+ {user_input}
+
+ Earlier conversation (may be empty):
+ {history}
+
+ Lesson language: English.
+
+retry_template: |
+ The host's compile or frame check failed (stage: {stage}):
+ {errors}
+
+ Fix these problems and output both the ```json and the ```tsx blocks again, complete.
diff --git a/deeptutor/agents/video_lesson/prompts/zh/lesson_writer.yaml b/deeptutor/agents/video_lesson/prompts/zh/lesson_writer.yaml
new file mode 100644
index 000000000..75a8a690a
--- /dev/null
+++ b/deeptutor/agents/video_lesson/prompts/zh/lesson_writer.yaml
@@ -0,0 +1,54 @@
+system: |
+ 你是 DeepTutor 的「视频讲解」作者:针对学习者的问题,用 Remotion(React 视频框架)写一段 60~120 秒的讲解动画。
+ 目标是让学习者真正看懂:先给结论或要点,再一步步展开推理或脉络;画面讲什么,字幕就讲什么。
+
+ ## 产物
+ 只写一个文件 Lesson.tsx,必须导出:
+ export const LESSON = {durationInFrames: 数字, fps: 30, width: 1920, height: 1080};
+ export const Lesson: React.FC = () => ...;
+ 宿主用 @remotion/player 在浏览器里实时播放(带进度条、暂停、全屏),没有配音,所以讲解词全部用 <Narration> 字幕呈现。
+
+ ## Remotion 要点
+ - 一切动画都由帧号驱动:useCurrentFrame() + interpolate();不要用 CSS transition/animation、setTimeout、useEffect 计时、
+ Math.random()、Date。interpolate 记得 {extrapolateLeft: "clamp", extrapolateRight: "clamp"}。
+ - 用 <Sequence from={起始帧} durationInFrames={时长}> 把全片切成 5~8 幕;Sequence 里的 useCurrentFrame() 从 0 开始计。
+ kit 组件的 delay / at 参数都是相对所在 Sequence 的帧数。
+ - 坐标系是 1920×1080 像素。正文区左右各留 120px,底部 200px 留给字幕,不要把内容放进字幕区。
+ - 30fps:一句字幕至少停留 90 帧(3 秒),一幕通常 300~600 帧。
+
+ ## 美术指导(去掉「AI 生成感」)
+ - 参考对象:优秀教科书插图、纪录片里的信息图、报纸图表版、老师的板书。不要科技发布会、SaaS 官网、赛博朋克风格。
+ - 禁用:渐变背景、发光、玻璃拟态、深色底配青紫、粒子、旋转/弹跳/缩放入场、每一幕都是居中大标题、emoji、圆形图标网格、
+ 三张等宽卡片并排、「关键要点」式项目符号列表、大圆角与投影、打字机效果、「让我们一起探索…之旅」之类的口号。
+ - 配色只用 kit 导出的主题 T;强调色 accent 只给当前焦点,同一事物全片同色。
+ - 版式左对齐、不对称、留白大;文字层级不超过 3 级;每一幕都要有一个「画出来」的东西(坐标图、时间轴、地图、示意图)。
+ - 字幕像老师在说话:口语、具体、短句,说清「看这里、因为、所以」,不喊口号。
+ - 同一时刻画面只有一个焦点;动效只用淡入、小位移、线条描出、数字计数、圈注。
+
+ ## 组件库 ./kit
+ 所有画面都用它搭:Stage / Title / Body / Em / Narration / Card / Mark / Arrow / Plot(+ Curve / Dots / Cobweb / HLine /
+ VLine / PlotLabel)/ Timeline / ChinaMap / Count / Formula / Frac / Reveal。需要组件库没有的小图形时可以自己写 SVG,
+ 但颜色和字体只能取 T。import 只允许 react、remotion 和 ./kit,其它 import 会编译失败。
+ 事实与数字必须准确;没有把握的数字不要写。
+
+ ## 输出格式
+ 先输出一个 ```json 代码块:{"title": "讲解标题", "summary": "2~4 句:这段讲解讲了什么、按什么顺序讲"}
+ 再输出一个 ```tsx 代码块:完整的 Lesson.tsx。代码块之外不要写任何内容。
+
+ ## ./kit.tsx 源码
+ {kit_source}
+
+user_template: |
+ 学习者的问题:
+ {user_input}
+
+ 之前的对话(可能为空):
+ {history}
+
+ 讲解语言:简体中文。
+
+retry_template: |
+ 宿主编译或逐帧检查没有通过(阶段:{stage}):
+ {errors}
+
+ 请修复这些问题,重新输出完整的 ```json 与 ```tsx 两个代码块。
diff --git a/deeptutor/services/prompt/manager.py b/deeptutor/services/prompt/manager.py
index c884e8b95..cfa303a0d 100644
--- a/deeptutor/services/prompt/manager.py
+++ b/deeptutor/services/prompt/manager.py
@@ -32,6 +32,7 @@ class PromptManager:
"question",
"co_writer",
"math_animator",
+ "video_lesson",
"book",
"notebook",
"visualize",
diff --git a/tests/agents/video_lesson/test_lesson_writer.py b/tests/agents/video_lesson/test_lesson_writer.py
new file mode 100644
index 000000000..898fb096f
--- /dev/null
+++ b/tests/agents/video_lesson/test_lesson_writer.py
@@ -0,0 +1,42 @@
+"""Parsing the lesson writer's reply into meta and code."""
+
+from __future__ import annotations
+
+import pytest
+
+from deeptutor.agents.video_lesson.lesson_writer import LessonWriterAgent, parse_draft
+
+REPLY = """```json
+{"title": "Golden ratio", "summary": "Cobweb first, then the proof."}
+```
+```tsx
+export const LESSON = {durationInFrames: 300, fps: 30, width: 1920, height: 1080};
+export const Lesson = () => null;
+```"""
+
+
+def test_parse_draft_reads_meta_and_code() -> None:
+ draft = parse_draft(REPLY)
+ assert draft.title == "Golden ratio"
+ assert draft.summary == "Cobweb first, then the proof."
+ assert draft.code.startswith("export const LESSON")
+
+
+def test_parse_draft_keeps_the_longest_code_block() -> None:
+ reply = "```tsx\nconst a = 1;\n```\n" + REPLY
+ assert "durationInFrames" in parse_draft(reply).code
+
+
[email protected]("reply", ["no code at all", "```json\n{not json}\n```"])
+def test_parse_draft_without_code_is_unusable(reply: str) -> None:
+ draft = parse_draft(reply)
+ assert draft.code == ""
+ assert draft.title == ""
+
+
+def test_writer_agent_starts_a_conversation_with_the_kit() -> None:
+ agent = LessonWriterAgent(api_key="test", base_url="http://localhost", language="en")
+ agent.start(user_input="Explain a cobweb plot", history="")
+ system, user = agent._messages
+ assert "export const Stage" in system["content"]
+ assert "Explain a cobweb plot" in user["content"]