paeg-teaching-materials

Chino | English

¿Qué es esto?

paeg-teaching-materials es un plugin de creación de materiales didácticos — 6 generadores de materiales + punto de entrada unificado + servidor MCP.

Proveniente del sistema de materiales del agente educativo PAEG (iteración v0.87-§3.91), transformado en un plugin independiente con cero dependencias del host.

Related MCP server: interactive-edtech-mcp

Características principales

• Arquitectura de interconexión en red (estándar de herramientas de primer nivel ⭐): 10 nodos funcionales (buscar información / esquema / PPT / apuntes / guion / mapa mental / vídeo / Manim / métodos de estudio / plan de estudio) — cada uno puede usarse de forma independiente y también es un paso previo para otras funciones

• Registro de generadores extensible: MaterialRegistry.register("自定义类型", generator) para ampliar

• Cero dependencias del host: 6 abstracciones Protocol (LLMCallable/RefinerProtocol/HandoutGenerator/ScriptGenerator/MindmapGenerator/ResourceProvider) + modo débil Null

• Punto de entrada unificado: execute(name, args) equivalente a constraint_engine (contrato JSON, nunca lanza excepciones)

• Instalación directa como servidor MCP: pip install + declaración de configuración MCP para la integración (15 herramientas)

• Vinculación con normas lingüísticas: los materiales producidos pasan automáticamente por la corrección de errores de redacción L0 (reutiliza paeg-lang-style)

• Control de calidad + evaluación: verificación determinista de estructura + puntuación del LLM en 5 dimensiones

Arquitectura de interconexión en red (cada función es independiente y también un paso previo ⭐)

Internamente, la herramienta es un entramado de conexiones y enlaces en red — cada función es un nodo de primera clase:

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

Tres modos de aristas de dependencia:

Doble exposición: cada función es a la vez una herramienta MCP independiente (execute_tool), puede orquestarse automáticamente (execute_pipeline expande los pasos previos según el grafo de dependencias), y también se puede combinar en cadena con |:

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()

Artefactos intermedios (Blackboard tipado MaterialContext): resources (búsqueda de información · acumulación por append) / outline / lecture_script / ppt_outline / completed_stages (marcadores de etapa · union) — los productos de los pasos previos son consumidos automáticamente por las etapas posteriores.

Instalación

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

Requiere Python 3.9+.

Inicio rápido

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"], "一元二次方程")

Integración como servidor MCP (se puede instalar directamente como un MCP y usar)

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

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

Declaración de configuración del cliente MCP (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"
    }
  }
}

Herramientas MCP expuestas (15):

Guía de integración para proyectos externos

Escenario A: Usar solo el punto de entrada unificado (recomendado)

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

Escenario B: Inyectar tu propio LLM (implementación sólida)

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

Escenario C: Registrar tipos de material personalizados (extensibilidad)

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", {...}) 可用

Escenario D: Servidor MCP (puente sin código)

pip install + declaración de configuración MCP (ver arriba) — cualquier cliente MCP (Claude/OpenCode/desarrollo propio) puede invocarlo directamente.

Extensibilidad

Mantenibilidad

• Cero dependencias del host: el paquete principal solo depende de la stdlib; todas las funciones del host se inyectan mediante Protocol

• Contrato unificado: execute devuelve una cadena JSON (contrato MCP) y no lanza excepciones en caso de fallo

• Modo débil: funciona sin host (generadores Null como marcadores), adecuado para pruebas y demostraciones

• Vinculación con normas lingüísticas: los materiales producidos pasan automáticamente por la corrección de errores de redacción L0

• 41 pruebas: cobertura completa de API pública / modo débil / inyección / execute / calidad / MCP

Arquitectura

宿主系统（任何 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 直接安装）            |
  +-----------------------------------------------------------+

Integración con el proyecto principal de PAEG

PAEG se integra a través de services/material_bridge.py (inyección del host + degradación sin rupturas):

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

Pruebas

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

Guía de contribución

¡Las contribuciones son bienvenidas!

• Nuevo tipo de material: heredar de la clase base Generator + MaterialRegistry.register()

• Nueva verificación de calidad: añadir una función en quality/checks.py

• Estilo de código: seguir la estructura de módulos existente + las normas de comentarios

Agradecimientos

• Agente educativo PAEG — este plugin se extrae de su sistema de creación de materiales (§3.87-§3.100)

• paeg-lang-style — plugin de normas lingüísticas (integración L0)

• Presenton / ppt-agent-skills — paradigma de pipeline LLM + renderizado

• ManimTrainer — paradigma de bucle cerrado de renderizado Manim

Licencia

MIT © 2026 PAEG Team