Metadata-Version: 2.4
Name: edurag
Version: 0.1.0
Summary: 基于LLM的教育RAG组件，支持解题、文献分析、知识点答疑
Project-URL: Homepage, https://github.com/edurag/edurag
Project-URL: Documentation, https://github.com/edurag/edurag#readme
Project-URL: Repository, https://github.com/edurag/edurag
Project-URL: Issues, https://github.com/edurag/edurag/issues
Author: EduRAG Team
License: MIT
License-File: LICENSE
Keywords: AI,LLM,RAG,education,langchain,retrieval-augmented-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: docx2txt>=0.8
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: langchain-community>=0.3.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: pypdf>=4.0.0
Provides-Extra: agentic
Requires-Dist: langgraph>=0.2.0; extra == 'agentic'
Provides-Extra: all
Requires-Dist: langchain-google-genai>=2.0.0; extra == 'all'
Requires-Dist: langchain-ollama>=0.2.0; extra == 'all'
Requires-Dist: langgraph>=0.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: langchain-google-genai>=2.0.0; extra == 'gemini'
Provides-Extra: ollama
Requires-Dist: langchain-ollama>=0.2.0; extra == 'ollama'
Description-Content-Type: text/markdown

# EduRAG

基于 LLM 的教育 RAG（检索增强生成）组件，支持解题、文献分析、知识点答疑。

## 功能特性

- **两种 RAG 模式**：SimpleRAG（简单高效）和 AgenticRAG（智能推理）
- **多 LLM 支持**：OpenAI GPT 系列、Google Gemini、Ollama 本地模型
- **多格式文档**：PDF、DOCX、DOC、TXT、Markdown
- **教师人设定制**：自定义教师名称、学科、学段、教学风格
- **多轮对话**：支持上下文记忆的连续问答
- **向量存储持久化**：避免重复 embedding，快速加载知识库

## 安装

```bash
pip install edurag
```

安装可选依赖：

```bash
# 使用 AgenticRAG（基于 LangGraph）
pip install edurag[agentic]

# 使用 Google Gemini
pip install edurag[gemini]

# 使用 Ollama 本地模型
pip install edurag[ollama]

# 安装所有可选依赖
pip install edurag[all]
```

## 快速开始

### 基础用法

```python
from edurag import SimpleRAG

# 初始化
rag = SimpleRAG(api_key="your-openai-api-key")

# 加载文档
rag.load_documents("教材.pdf")

# 提问
answer = rag.ask("这篇文档的主要内容是什么？")
print(answer)
```

### 自定义教师人设

```python
from edurag import SimpleRAG, TeacherProfile

# 创建教师人设
teacher = TeacherProfile(
    name="物理王老师",
    subject="高中物理",
    grade_level="高三",
    teaching_style="注重概念理解，善于用生活实例解释抽象原理",
    introduction="20年教龄，物理竞赛教练"
)

# 初始化 RAG
rag = SimpleRAG(
    api_key="your-openai-api-key",
    teacher_profile=teacher
)

# 加载教材
rag.load_documents([
    "高中物理必修一.pdf",
    "力学专题.docx"
])

# 提问 - AI 会以王老师的身份和风格回答
answer = rag.ask("为什么自由落体的加速度是恒定的？")
```

### 使用不同的 LLM

```python
# OpenAI
rag = SimpleRAG(
    api_key="sk-xxx",
    llm_provider="openai",
    llm_model="gpt-4o"
)

# Google Gemini
rag = SimpleRAG(
    api_key="your-google-key",
    llm_provider="gemini",
    llm_model="gemini-pro"
)

# Ollama 本地模型（无需 API Key）
rag = SimpleRAG(
    llm_provider="ollama",
    llm_model="llama3"
)
```

### 持久化向量存储

```python
# 首次加载：自动保存向量存储
rag = SimpleRAG(
    api_key="sk-xxx",
    vectorstore_path="./my_knowledge_base"
)
rag.load_documents("./documents/")

# 后续使用：直接加载已有存储（跳过 embedding）
rag = SimpleRAG.from_vectorstore(
    vectorstore_path="./my_knowledge_base",
    api_key="sk-xxx"
)
```

### AgenticRAG（智能推理）

适合处理复杂问题，Agent 可以自主决定是否需要检索，支持多步推理。

```python
from edurag import AgenticRAG, TeacherProfile

teacher = TeacherProfile(
    name="物理王老师",
    subject="高中物理",
    grade_level="高三",
    teaching_style="善于类比，用生活实例解释"
)

rag = AgenticRAG(
    api_key="sk-xxx",
    teacher_profile=teacher
)

rag.load_documents(["物理教材.pdf"])

# Agent 会自动决定是否检索，支持多步推理
answer = rag.ask("比较牛顿三大定律的异同点")

# 查看推理过程
result = rag.ask_with_steps("解释动量守恒定律")
print(result["steps"])  # 查看 Agent 的推理步骤
print(result["answer"]) # 最终答案
```

**SimpleRAG vs AgenticRAG：**

| 特性 | SimpleRAG | AgenticRAG |
|------|-----------|------------|
| 检索方式 | 每次都检索 | Agent 自主决定 |
| 推理能力 | 单步 | 多步推理 |
| 速度 | 更快 | 较慢 |
| 成本 | 更低 | 较高 |
| 适用场景 | 简单问答 | 复杂分析 |

## API 参考

### SimpleRAG

主要的 RAG 类，提供文档加载和问答功能。

#### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `api_key` | str | None | LLM API 密钥 |
| `llm_provider` | str | "openai" | LLM 提供商：openai/gemini/ollama |
| `llm_model` | str | "gpt-4o" | 模型名称 |
| `teacher_profile` | TeacherProfile | None | 教师人设配置 |
| `config` | EduRAGConfig | None | 完整配置对象 |

#### 方法

- `load_documents(sources)`: 加载文档到知识库
- `ask(question)`: 提问并获取回答
- `ask_with_sources(question)`: 提问并返回回答及来源文档
- `search(query, top_k)`: 直接搜索相关文档
- `clear_history()`: 清空对话历史
- `save_vectorstore(path)`: 保存向量存储

### TeacherProfile

教师人设配置类。

```python
from edurag import TeacherProfile

teacher = TeacherProfile(
    name="李老师",           # 教师名称
    subject="数学",          # 教学课程
    grade_level="初中",      # 学段
    teaching_style="...",    # 教学风格
    introduction="...",      # 个人介绍（可选）
    language="中文"          # 回答语言
)
```

### EduRAGConfig

完整配置类，用于高级自定义。

```python
from edurag import EduRAGConfig

config = EduRAGConfig(
    llm_provider="openai",
    llm_model="gpt-4o",
    api_key="sk-xxx",
    temperature=0.7,           # 生成温度
    chunk_size=1000,           # 文档切分大小
    chunk_overlap=200,         # 切分重叠
    retrieval_top_k=4,         # 检索结果数量
    vectorstore_path=None      # 向量存储路径
)
```

## 预定义教师模板

```python
from edurag.prompt.teacher_profile import PRESET_TEACHERS

# 可用的预设教师
teacher = PRESET_TEACHERS["physics_senior"]    # 高中物理
teacher = PRESET_TEACHERS["math_college"]      # 大学数学
teacher = PRESET_TEACHERS["english_junior"]    # 初中英语
teacher = PRESET_TEACHERS["chemistry_senior"]  # 高中化学
```

## License

MIT

