📚 Education Services

Textbook-driven AI agent pack for teachers and parents — built on the Anthropic financial-services architecture, adapted for the education domain.

🇨🇳 中文文档 | 🇺🇸 English

Education Services is an open-source AI agent pack for K-12 education. It is not a "student answer bot" — it is a textbook-driven tutoring agent designed to help:

• Teachers prepare lessons, grade homework, and diagnose student errors
• Parents understand what their child is learning and tutor effectively
• Students (with teacher/parent supervision) get scaffolded, Socratic-style help

The system is grounded in a single principle: every output must be traceable to a specific textbook page. No hallucination, no fabrication.

┌──────────────────────────────────────────────────────────────┐
│                      User Interface                          │
│  Cowork Plugin │ Hermes Agent │ FastAPI Backend / WebSocket  │
└─────────────┬─────────────┬──────────────────┬───────────────┘
              │             │                  │
        ┌─────▼─────┐ ┌─────▼──────┐ ┌────────▼────────┐
        │  Agent    │ │  Agent     │ │   Agent         │
        │  Plugins  │ │  Cookbooks │ │   Backends      │
        │  (5)      │ │  (5)       │ │   (FastAPI)     │
        └─────┬─────┘ └─────┬──────┘ └────────┬────────┘
              │             │                  │
        ┌─────▼─────────────▼──────────────────▼────────┐
        │     Skills (56 SKILL.md knowledge bases)      │
        └─────────────────────┬─────────────────────────┘
                              │
        ┌─────────────────────▼─────────────────────────┐
        │  MCP Servers (5)                              │
        │  textbook_store / vector_index / student_...  │
        └─────────────────────┬─────────────────────────┘
                              │
        ┌─────────────────────▼─────────────────────────┐
        │  PostgreSQL + pgvector │ MinIO/S3             │
        └───────────────────────────────────────────────┘

# Clone the repo
git clone https://github.com/education-services/education-services.git
cd education-services

# Install dependencies
pip install -r requirements-dev.txt --break-system-packages

# Validate project structure
python scripts/validate.py        # 6/6 ✅
python scripts/eval_agent.py --all  # 12/12 ✅

# 1. Configure environment
cp .env.example .env
# Edit .env: set ANTHROPIC_API_KEY=sk-ant-...

# 2. Start infrastructure
docker compose up -d postgres minio

# 3. Initialize database
python scripts/init_db.py
python scripts/seed_data.py

# 4. Start backend
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# → API docs at http://localhost:8000/docs

# OpenClaw desktop
bash dist/openclaw-install.sh

# Hermes Agent server
bash dist/hermes-install.sh

education-services/
├── plugins/
│   ├── agent-plugins/         # 5 named agents (textbook-teaching, lesson-planner, ...)
│   └── vertical-plugins/      # 7 vertical plugins (education-core, subject-math, ...)
├── managed-agent-cookbooks/   # 5 deployment manifests + 7 subagents
├── backend/                   # FastAPI + PostgreSQL schema
├── scripts/                   # 15 utility scripts (validate, eval, init_db, ...)
├── evals/                     # 12 test cases + 5 fixture sets
├── dist/                      # Distribution packages (ClawHub, Hermes)
└── docs/                      # Internal documentation

1. Citation Required — Every textbook-related claim must reference a page, chapter, or question
2. Human Review — All agent outputs are drafts; teachers/parents must confirm before sharing with students
3. No Cheating — Socratic prompts, never direct answers
4. No Fabrication — Marked "教材中未找到直接依据" when source is missing
5. Privacy — Student data is anonymized; never enters external training
6. Prompt Injection Defense — User uploads are data, not instructions
7. Professional Boundary — Mental health / medical / special education → refer to professionals

We welcome contributions! Please read CONTRIBUTING.md first.

• 🐛 Report a bug
• ✨ Request a feature
• 📚 Submit a Skill
• 🔒 Security issues

Apache 2.0 — see LICENSE.

If this project helps you, please consider giving it a star! ⭐

Education Services 是一个面向 K-12 教育的开源 AI Agent 套件。它不是"学生答题机器人"，而是教材驱动的辅导 Agent，主要帮助：

• 教师备课、批改作业、诊断错因
• 家长理解孩子学什么、有效辅导
• 学生（在教师/家长监督下）获得脚手架式、苏格拉底式的引导

系统的核心原则是：所有输出必须能回溯到教材具体页码。不编造、不幻觉。

# 克隆仓库
git clone https://github.com/education-services/education-services.git
cd education-services

# 安装依赖
pip install -r requirements-dev.txt --break-system-packages

# 验证
python scripts/validate.py        # 6/6 ✅
python scripts/eval_agent.py --all  # 12/12 ✅

# 1. 配置环境
cp .env.example .env
# 编辑 .env：ANTHROPIC_API_KEY=sk-ant-...

# 2. 启动基础设施
docker compose up -d postgres minio

# 3. 初始化数据库
python scripts/init_db.py
python scripts/seed_data.py

# 4. 启动后端
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# → API 文档 http://localhost:8000/docs

# OpenClaw 桌面
bash dist/openclaw-install.sh

# Hermes 服务端
bash dist/hermes-install.sh

详细使用文档：Education-Services-使用文档.docx · Education-Services-OpenClaw-Hermes-使用文档.docx

1. 引用必需 — 所有教材相关结论必须引用页码/章节/题号
2. 人审机制 — Agent 输出是草稿，必须由教师/家长确认才发学生
3. 不替学生作弊 — 苏格拉底式提问，不直接给答案
4. 不编造 — 找不到时明确标注"教材中未找到直接依据"
5. 数据隐私 — 学生数据脱敏，不进入外部训练
6. Prompt Injection 防御 — 上传内容是数据而非指令
7. 专业边界 — 心理/医疗/特殊教育 → 建议寻求专业人士

欢迎贡献！请先阅读 CONTRIBUTING.md。

• 🐛 报告 Bug
• ✨ 功能建议
• 📚 提交 Skill
• 🔒 安全问题

Apache 2.0 — 详见 LICENSE。

• Inspired by anthropics/financial-services
• Built with Anthropic Claude (Opus 4.7, Sonnet 4.5, Haiku 4.5)
• Database: PostgreSQL 16 with pgvector
• PDF processing: PyMuPDF
• OCR: PaddleOCR

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: team@education-services.local
• Security: security@education-services.local

Made with ❤️ for teachers, parents, and students.