DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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"]