paeg-teaching-materials

Chinese | English

What Is This

paeg-teaching-materials is a teaching materials creation plugin — 6 types of material generators + a unified execution entry + an MCP server.

Originating from the PAEG education agent material system (v0.87-§3.91 iterations), it has been refactored into a zero-host-dependency standalone plugin.

Related MCP server: Learn Shell

Key Features

• Mesh-connected architecture (top-tier tool standard ⭐): 10 functional nodes (research / outline / PPT / handout / lecture script / mind map / video / Manim / study methods / study plan) — each can be used independently and is also a prerequisite for other features

• Extensible generator registry: MaterialRegistry.register("自定义类型", generator) to extend

• Zero host dependencies: 6 Protocol abstractions (LLMCallable/RefinerProtocol/HandoutGenerator/ScriptGenerator/MindmapGenerator/ResourceProvider) + Null weak mode

• Unified execution entry: execute(name, args) serving as the counterpart to constraint_engine (JSON contract, never throws)

• MCP server direct installation: pip install + MCP config declaration to integrate (15 tools)

• Language specification integration: material output automatically passes L0 grammar error correction (reuses paeg-lang-style)

• Quality checks + review: deterministic structural checks + LLM 5-dimension scoring

Mesh-Connected Architecture (Features Are Both Independent and Prerequisites ⭐)

Inside, tools form an interwoven mesh of wiring and connectivity — every feature is a first-class citizen node:

research（查资料·广播前置）
   ├──→ outline（大纲）──→ ppt（PPT 制作）
   ├──→ script（讲稿）──→ video（教学视频）
   ├──→ handout / manim / method / study_plan / mindmap(可选)

Three-mode dependency edges:

Dual exposure: every feature is both a standalone MCP tool (execute_tool) and can be automatically orchestrated (execute_pipeline expands prerequisite stages according to the dependency graph), or chained with |:

from paeg_teaching_materials import MaterialRegistry
from paeg_teaching_materials.tools import ResearchTool, OutlineTool, PptTool

# 1. 独立调用
result = MaterialRegistry.execute_plan("ppt", ctx, {"topic": "导数"})
#   自动执行: research → outline → ppt（查资料是前置环节）

# 2. 链式组合（LangChain Runnable 模式）
pipeline = ResearchTool() | OutlineTool() | PptTool()  # 组合结果仍是 Tool

# 3. 依赖图自省（MCP: list_dependencies）
graph = MaterialRegistry.get_resolver().dependency_graph()

Intermediate artifacts (MaterialContext typed Blackboard): resources (research · append accumulation) / outline / lecture_script / ppt_outline / completed_stages (stage markers · union) — artifacts from prerequisite stages are automatically consumed downstream.

Installation

pip install -e /path/to/paeg-teaching-materials
# 可选依赖：
pip install -e "paeg-teaching-materials[pptx]"    # PPT 渲染
pip install -e "paeg-teaching-materials[manim]"   # Manim 渲染
pip install -e "paeg-teaching-materials[mcp]"     # MCP server

Requires Python 3.9+.

Quick Start

from paeg_teaching_materials import MaterialRegistry, execute

# 1. 注入你的 LLM（任何项目接入点）
def my_llm(system, user, max_tokens=2000, temperature=0.7):
    return call_your_llm(system, user, max_tokens=max_tokens)
MaterialRegistry.inject(llm=my_llm)

# 2. 生成物料（统一执行入口）
result = execute("generate_handout", {"topic": "一元二次方程", "subject": "数学"})
# → {"material_type": "handout", "topic": "...", "ok": true, "output": "## 教学目标..."}

# 3. 质量检查 + 评审
from paeg_teaching_materials import check_material_structure, judge_material
issues = check_material_structure(result["output"], "handout")
score = judge_material(result["output"], "一元二次方程")

Integrate as an MCP Server (Install Directly Like MCP and It's Ready to Use)

# 方式 1：console_scripts 入口（pip install 后）
paeg-teaching-materials-mcp

# 方式 2：python -m 入口（源码运行）
python -m paeg_teaching_materials.mcp_server

MCP client configuration declaration (config/mcp_servers.json):

{
  "mcpServers": {
    "paeg-teaching-materials": {
      "command": "python",
      "args": ["-m", "paeg_teaching_materials.mcp_server"],
      "cwd": "D:/wbo-workspace/paeg_project/paeg-teaching-materials"
    }
  }
}

Exposed MCP tools (15):

External Project Integration Guide

Scenario A: Use Only the Unified Execution Entry (Recommended)

from paeg_teaching_materials import execute
result = execute("generate_ppt", {"topic": "微积分", "subject": "数学"})

Scenario B: Inject Your Own LLM (Strong Implementation)

from paeg_teaching_materials import MaterialRegistry
MaterialRegistry.inject(llm=my_llm, refiner=my_refiner)
result = MaterialRegistry.generate("handout", "力学", "物理")

Scenario C: Register Custom Material Types (Extensibility)

from paeg_teaching_materials import MaterialRegistry
from paeg_teaching_materials.generators.base import Generator

class QuizGenerator(Generator):
    material_type = "quiz"
    def generate(self, topic, subject="通用", learner_id="anon", **kw):
        return {"material_type": "quiz", "topic": topic, "ok": True, "output": "..."}

MaterialRegistry.register("quiz", generator=QuizGenerator())
# 现在 execute("generate_quiz", {...}) 可用

Scenario D: MCP Server (Zero-Code Bridge)

pip install + MCP config declaration (see above) — any MCP client (Claude/OpenCode/self-built) can call it directly.

Extensibility

Maintainability

• Zero host dependencies: the core package depends only on stdlib; all host features are injected via Protocol

• Unified contract: execute returns a JSON string (MCP contract), never throws on failure

• Weak mode: runs without a host (Null generator placeholder), convenient for testing and demos

• Language specification integration: material output automatically passes L0 grammar error correction

• 41 tests: full coverage of public API / weak mode / injection / execute / quality / MCP

Architecture

宿主系统（任何 Python 项目 / 智能体）
  MaterialRegistry.inject(llm=..., refiner=..., resources=...)  <- 宿主注入
  execute("generate_handout", {...})                            <- 统一入口
        |
        | 零宿主依赖（Protocol 抽象）
        v
paeg_teaching_materials（独立插件）
  +-------------------+  +-------------------+  +----------------+
  | registry.py       |  | generators/       |  | quality/       |
  | MaterialRegistry  |  | ppt/handout/...   |  | checks/judge   |
  +---------+---------+  +---------+---------+  +----------------+
            |                      |
            v                      v
  +-----------------------------------------------------------+
  | executor.py（execute 统一入口，JSON 契约）                   |
  | mcp_server.py（FastMCP 15 工具，stdio 直接安装）            |
  +-----------------------------------------------------------+

Integration with the PAEG Main Project

PAEG integrates via services/material_bridge.py (host injection + zero-breakage fallback):

from services.material_bridge import install_material_plugin
install_material_plugin()   # server.py 启动时调用一次
# 注入 PAEG LLM（subagents._safe_chat）+ Refiner（paeg.refiner）+ 资源（library）
# 插件未安装 → 静默回退 PAEG 原物料实现（旧文件永不删除）

Tests

python -m pytest tests/ -q
# 22 项：公共 API / 弱模式 / 注入 / execute / 质量 / MCP server

Contribution Guide

Contributions welcome!

• Add a new material type: subclass the Generator base class + MaterialRegistry.register()

• Add quality checks: add functions in quality/checks.py

• Code style: follow the existing module structure + comment conventions

Acknowledgments

• PAEG Education Agent — this plugin is extracted from its material creation system (§3.87-§3.100)

• paeg-lang-style — language specification plugin (L0 integration)

• Presenton / ppt-agent-skills — LLM + rendering pipeline paradigm

• ManimTrainer — Manim rendering closed-loop paradigm

License

MIT © 2026 PAEG Team