Content
="center">
<img src="https://img.shields.io-3.10+-logo=python&logoColor=white="Python">
<img src="https://img.shields.io/badge/FastAPI-0.130+-009688?logo=fastapi&logoColor=white" alt="FastAPI">
<img src="https://img.shields.io/badge/LangGraph-1.0-purple?logo=langchain&logoColor=white" alt="LangGraph">
<img src="https://img.shields.io/badge/License-MIT-green" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alts Welcome">
</p>
<h1 align="center">Forewish Backend</h1>
<p align="center">
<strong>Multi-Agent Intelligent Exam System powered by LangGraph + FastAPI</strong>
<br />
<em>Intent Recognition · Multi-Agent Collaboration · RAG Knowledge Base · MCP Protocol · Streaming Output</em>
</p>
<p align="center">
<a href="#-quick-start">Quick Start</a> ·
<a href="#-core-features">Core Features</a> ·
<a href="#-architecture-overview">Architecture</a> ·
<a href="#-api-reference">API Reference</a> ·
<a hrefconfiguration">Configuration</a>
</p>
---
## 🎯 Core Features
<table>
<tr>
<td width="50%">
<h3>🤖 MainAgent Architecture</h3>
Intent recognition + tool invocation loop, progressive skill discovery, and on-demand execution. Complete the process from intent understanding to exam generation in one conversation.
</td>
<="50%">
<h3>🧩 Multi-Agent Collaboration</h3>
Analyzer, multi-question type generation (multiple choice/fill-in-the-blank/short answer), illustration, summarization, and other agents are orchestrated through LangGraph state diagrams, each with its own responsibilities.
</td>
</tr <tr>
<td>
<h3>📚 RAG Knowledge Base</h3>
Supports importing documents in PDF/DOCX/TXT/Web formats, with four slicing strategies, ChromaDB semantic search, and cross-knowledge base search.
</td>
<td>
<h3>🔌 MCP Protocol</h3>
Built-in MCP Server (search tool) and Client, supporting local/remote/WebSocket/HTTP connection methods.
</td>
</tr>
<tr>
<td>
<h3>⚡ Streaming Response</h3>
SSE (Server-Sent Events) pushes generation progress in real-time, and the front-end renders it immediately, enhancing user experience.
</td>
<td>
<h3>🛠️ Extensible Skill System</h3>
Automatically scans the <code>app/skills/</code> directory, with hot-swappable registration. Existing skills: exam generation, PDF processing.
</td>
</tr>
</table>
## 🏗️ Tech Stack
| Category | Technology | Description |
|:-----|:-----|:-----|
| **Web** | FastAPI + Uvicorn | Asynchronous high-performance ASGI framework |
| **LLM Orchestration** | LangGraph 1.0 + LangChain | Multi-agent state diagram orchestration |
| **LLM Service** | LangChain-OpenAI | Compatible with any OpenAI API format model |
| **Relational Database** | SQLAlchemy 2.0 (async) + MySQL | Asynchronous ORM, aiomysql driver |
| **Vector Database** | ChromaDB | Document embedding vector persistence and retrieval |
| **Cache** | Redis | Session caching and hot data management |
| **MCP** | mcp\[cli\] (FastMCP) | Model Context Protocol tool protocol |
| **Document Parsing** | pdfplumber · python-docx · BeautifulSoup4 | Multi-format document parsing |
| **Logging** | Loguru | Structured logging |
| **Tracing** | LangSmith | LLM call chain tracing and debugging |
## 🏛️ Architecture Overview
```
┌──────────────────────────────────────────────┐
│ FastAPI Application │
│ │
│ /chat /generate-exam /knowledge-bases ... │
└───────────────────┬──────────────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌───────────────────┐
│ MainAgent │ │ Exam CRUD API │ │ RAG Pipeline │
│ (Intent + Scheduling)│ │ (Exam Management)│ │ (Knowledge Base)│
└────────┬────────┘ └────────────────────┘ └────────┬────────── │ │
┌─────────────┼─────────────┐ ┌────────────┼────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌────────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐
│ Summary │ │ Analyzer │ │ Skill │ │ Parser │ │ Chunker │ │ Embedding │
│ Agent │ │ Agent │ │ System │ │ PDF/DOCX │ │ 4 Strategies│ │ Service │
└────────────┘ └──────────┘ └─────┬──────┘ │ Web/Text │ └──────────┘ └─────┬─────┘
│ └──────────┘ │
┌────────────┼────────────┐ ▼
▼ ▼ ▼ ┌───────────────┐
┌────────────┐┌──────────┐┌──────────┐ │ ChromaDB │
│ MCQ Agent ││Fill Blank││ Essay │ │ Vector Store │
└────────────┘│ Agent ││ Agent │ └───────────────┘
└──────────┘└──────────┘
│
┌────────┼────────┐
▼ ▼ ▼
┌──────────┐┌──────┐┌────────┐
│Illustrate│re-││ MCP │
│ Agent│gator ││ └──────────┘└──────┘└────────```
### Exam Generation Process
```
User Input ──▶ MainAgent (Intent Recognition) ──▶ Skill Scheduling
│
┌───────────────────────────┘
▼
SummaryAgent▶ AnalyzerAgent ──▶ Demand Extraction
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
MultipleChoice FillBlank Essay
Agent Agent Agent
│ │ │
└──────────────────┼──────────────────┘
▼
IllustrationAgent (Optional)
▼
AggregatorAgent ──▶ Save & Return Exam
```
### RAG Knowledge Base Process
```
Document Upload / Web Import
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Parser │────▶│ Chunker │────▶│ Embedding │────▶│ ChromaDB │
│ Document Parsing│ │ ing│ │ Vectorization│ │ Vector Store │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
PDF/DOCX/Web/TXT Auto/Custom/ OpenAI API Persistent Storage
FAQ/ParentChild Compatible Interface
▲ Query │
│ ▼
User Search Request ◀──── RetrievalService ◀──── Semantic Similarity Top-K ◀────────┘
```
**Supported Chunking Strategies:**
| Strategy | Description |
|:-----|:-----|
| `auto` | RecursiveCharacterTextSplitter, intelligent recursive splitting |
| `custom` | Configurable `chunk_size` and `chunk_overlap` |
| `faq` | LLM automatically extracts Q&A pairs, suitable for FAQ scenarios |
| `parent_child` | Child segments are used for retrieval, and parent segments are returned for context, balancing precision and completeness |
## 📁 Project Structure
```
forewish-backend/
├── app/
│ ├── main.py # FastAPI entry point, lifecycle management
│ ├── database.py # Database connection and initialization
│ ├── config/
│ │ └── settings.py # Pydantic Settings configuration
│ ├── agents/ # Agent layer
│ │ ├── base_agent.py # Agent base class
│ │ ├── main_agent/ # MainAgent (intent recognition + skill scheduling)
│ │ │ ├── agent.py # Core logic: tool call loop
│ │ │ └── tools/ # Built-in tool definitions
│ │ ├── sub_agent.py # Sub-task Agent
│ │ ├── summary_agent.py # Historical conversation summary
│ │ ├── analyzer_agent.py # Question requirement analysis
│ │ ├── multiple_choice_agent.py # Multiple-choice question generation
│ │ ├── fill_blank_agent.py # Fill-in-the-blank question generation
│ │ ├── essay_agent.py # Essay question generation
│ │ ├── illustration_agent.py # Question illustration
│ │ └── aggregator_agent.py # Result summary & saving
│ ├── api/ # API routes
│ │ ├── routes.py # Conversation & generation interface
│ │ ├── file_routes.py # Exam file operations
│ │ └── exam_routes.py # Exam CRUD
│ ├── models/ # Data models
│ │ ├── schemas.py # Request/response Pydantic models
│ │ ├── state.py # LangGraph State definition
│ │ ├── exam.py # Exam ORM model
│ │ └── exam_schemas.py # Exam API models
│ ├── services/ # Business services
│ │ ├── agent_service.py # MainAgent singleton & unified entry point
│ │ └── exam_service.py # Exam CRUD business logic
│ ├── skills/ # Skill modules (hot-swappable)
│ │ ├── base_skill.py # Skill base class
│ │ ├── exam_generation/ # Exam generation skill
│ │ └── pdf/ # PDF processing skill
│ ├── rag/ # RAG knowledge base module
│ │ ├── models/ # ORM & Pydantic models
│ │ │ ├── knowledge_base.py # Knowledge base table
│ │ │ ├── document.py # Document & segment table
│ │ │ └── schemas.py # Request/response models
│ │ ├── services/ # Business logic
│ │ │ ├── knowledge_base_service.py
│ │ │ ├── document_service.py # Document processing pipeline
│ │ │ ├── embedding_service.py # Vectorization service
│ │ │ ├── retrieval_service.py # Semantic retrieval
│ │ │ ├── parser/ # Document parsers
│ │ │ │ ├── pdf_parser.py # PDF (including images/tables)
│ │ │ │ ├── docx_parser.py # Word documents
│ │ │ │ ├── web_parser.py # Web scraping
│ │ │ │ └── text_parser.py # TXT / Markdown
│ │ │ └── chunker/ # Chunking strategies
│ │ │ ├── auto_chunker.py
│ │ │ ├── custom_chunker.py
│ │ │ ├── faq_chunker.py
│ │ │ └── parent_child_chunker.py
│ │ ├── api/ # REST API
│ │ │ ├── knowledge_base_routes.py
│ │ │ ├── document_routes.py
│ │ │ └── retrieval_routes.py
│ │ └── vector_store/ # Vector database
│ │ ├── base_store.py
│ │ └── chroma_store.py # ChromaDB implementation
│ ├── mcp/ # MCP protocol
│ │ ├── mcp_client.py # MCP Client (multi-connection mode)
│ │ └── search_server.py # MCP Server (search tool)
│ ├── tools/
│ │ └── web_search.py # SerpAPI Google search
│ └── utils/
│ └── file_utils.py # Exam file management
├── tests/
│ └── test_api.py
├── mcp.json # MCP Server configuration
├── requirements.txt
├── env.example
├── Makefile
├── start_service.sh # Startup script
└── ARCHITECTURE.md # Architecture design document
```
## 🚀 Quick Start
### Prerequisites
- Python 3.10+
- MySQL 8.0+
- Redis 6.0+
- OpenAI API-compatible LLM service
### 1. Clone & Install
```bash
git clone https://github.com/your-org/forewish-backend.git
cd forewish-backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
make install # or pip install -r requirements.txt
```
### 2. Configure Environment Variables
```bash
cp env.example .env
```
Edit `.env` and fill in necessary configurations:
```bash
# LLM (required)
OPENAI_API_KEY=sk-your-key
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1
# MySQL (required)
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=forewish
# RAG Embedding (optional, reuse OpenAI configuration if empty)
EMBEDDING_MODEL=text-embedding-ada-002
```
### 3. Start
```bash
make run
```
or run directly:
```bash
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### 4. Verification
| Address | Description |
|:-----|:-----|
| http://localhost:8000 | Root path |
| http://localhost:8000/docs | Swagger UI interactive documentation |
| http://localhost:8000/redoc | ReDoc documentation |
## 📡 API Reference
### Conversation & Generation
| Method | Path | Description |
|:-----|:-----|:-----|
| `GET` | `/api/v1/health` | Health check |
| `POST` | `/api/v1/chat` | Intelligent conversation (intent recognition + automatic routing) |
| `POST` | `/api/v1/chat/stream` | Streaming conversation (SSE) |
| `POST` | `/api/v1/generate-exam` | Structured exam generation |
| `POST` | `/api/v1/generate-exam/stream` | Streaming exam generation (SSE) |
| `POST` | `/api/v1/analyze-conversation` | Conversation intent analysis (only analysis, no execution) |
### Exam Management
| Method | Path | Description |
|:-----|:-----|:-----|
| `POST` | `/api/v1/exams` | Create exam record |
| `GET` | `/api/v1/exams` | Paginated query exams |
| `GET` | `/api/v1/exams/stats` | Exam statistics |
| `GET` | `/api/v1/exams/{exam_id}` | Get exam details |
| `PUT` | `/api/v1/exams/{exam_id}` | Update exam |
| `DELETE` | `/api/v1/exams/{exam_id}` | Delete exam (soft delete) |
| `POST` | `/api/v1/exams/{exam_id}/publish` | Publish exam |
| `POST` | `/api/v1/exams/{exam_id}/archive` | Archive exam |
### Knowledge Base (RAG)
| Method | Path | Description |
|:-----|:-----|:-----|
| `POST` | `/api/v1/knowledge-bases` | Create knowledge base |
| `GET` | `/api/v1/knowledge-bases` | Knowledge base list (paginated/searchable) |
| `GET` | `/api/v1/knowledge-bases/{kb_id}` | Knowledge base details |
| `PUT` | `/api/v1/knowledge-bases/{kb_id}` | Update knowledge base configuration |
| `DELETE` | `/api/v1/knowledge-bases/{kb_id}` | Delete knowledge base |
| `POST` | `/api/v1/knowledge-bases/{kb_id}/documents/upload` | Upload document (PDF/DOCX/TXT) |
| `POST` | `/api/v1/knowledge-bases/{kb_id}/documents/web` | Import from webpage |
| `GET` | `/api/v1/knowledge-bases/{kb_id}/documents` | Get document list |
| `GET` | `/api/v1/knowledge-bases/{kb_id}/documents/{doc_id}` | Get document details |
| `GET` | `/api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/chunks` | Get document chunks |
| `DELETE` | `/api/v1/knowledge-bases/{kb_id}/documents/{doc_id}` | Delete document |
| `POST` | `/api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/reprocess` | Reprocess document |
| `POST` | `/api/v1/knowledge-bases/{kb_id}/search` | Single knowledge base semantic search |
| `POST` | `/api/v1/knowledge-bases/search` | Cross-knowledge base joint search |
### File Operations
| Method | Path | Description |
|:-----|:-----|:-----|
| `GET` | `/api/v1/exams/list` | Saved exam file list |
| `GET` | `/api/v1/exams/download/{filename}` | Download exam file |
| `GET` | `/api/v1/exams/read/{filename}` | Read exam content |
| `DELETE` | `/api/v1/exams/delete/{filename}` | Delete exam file |
### Request Examples
<details>
<summary><strong>Intelligent Conversation</strong></summary>
```bash
curl -X POST http://localhost:8000/api/v1/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Help me generate 5 Python multiple-choice questions and 3 fill-in-the-blank questions",
"session_id": "optional-session-id",
"history": [],
"context": {}
}'
```
</details>
<details>
<summary><strong>Structured Exam Generation</strong></summary>
```bash
curl -X POST http://localhost:8000/api/v1/generate-exam \
-H "Content-Type: application/json" \
-d '{
"topic": "Python Basics",
"multiple_choice_count": 5,
"fill_blank_count": 3,
"essay_count": 2,
"difficulty": "medium",
"additional_requirements": "Focus on function and class usage"
}'
```
</details>
<details>
<summary><strong>Create Knowledge Base & Upload Document</strong></summary>
```bash
# Create knowledge base
curl -X POST http://localhost:8000/api/v1/knowledge-bases \
-H "Content-Type: application/json" \
-d '{
"name": "Python Textbook",
"description": "Python programming basics textbook knowledge base",
"chunk_strategy": "auto"
}'
# Upload document to knowledge base
curl -X POST http://localhost:8000/api/v1/knowledge-bases/{kb_id}/documents/upload \
-F "file=@textbook.pdf"
# Semantic search
curl -X POST http://localhost:8000/api/v1/knowledge-bases/{kb_id}/search \
-H "Content-Type: application/json" \
-d '{
"query": "Python decorator usage",
"top_k": 5
}'
```
</details>
## ⚙️ Environment Variables
<details>
<summary>Complete configuration list (click to expand)</summary>
| Group | Variable | Default Value | Description |
|:-----|:-----|:-------|:-----|
| **LLM** | `OPENAI_API_KEY` | — | LLM API Key (required) |
| | `OPENAI_API_BASE` | — | API Base (required) |
| | `OPENAI_MODEL` | `gpt-4.1` | Model Name |
| **App** | `APP_NAME` | `EasyExam` | App Name |
| | `APP_VERSION` | `0.1.0` | Version Number |
| | `DEBUG` | `true` | Debug Mode |
| | `HOST` | `0.0.0.0` | Listen Address |
| | `PORT` | `8000` | Port Number |
| **MySQL** | `MYSQL_HOST` | `localhost` | Database Host |
| | `MYSQL_PORT` | `3306` | Port |
| | `MYSQL_USER` | `root` | Username |
| | `MYSQL_PASSWORD` | — | Password (required) |
| | `MYSQL_DATABASE` | `forewish` | Database Name |
| **Redis** | `REDIS_HOST` | `localhost` | Redis Host |
| | `REDIS_PORT` | `6379` | Port |
| | `REDIS_DB` | `0` | Database Number |
| | `REDIS_PASSWORD` | — | Password |
| **Illustration** | `ENABLE_ILLUSTRATION` | `true` | Enable AI Illustration |
| | `IMAGE_API_BASE` | — | Image API Base |
| | `IMAGE_API_KEY` | — | Image API Key |
| | `IMAGE_MODEL` | — | Image Model |
| **Search** | `SERPAPI_KEY` | — | SerpAPI Key |
| **MCP** | `USE_MCP` | `true` | Use MCP Protocol |
| **RAG** | `EMBEDDING_API_BASE` | — | Embedding API Base (leave blank to reuse OpenAI) |
| | `EMBEDDING_API_KEY` | — | Embedding API Key |
| | `EMBEDDING_MODEL` | `text-embedding-ada-002` | Embedding Model |
| **ChromaDB** | `CHROMA_PERSIST_DIR` | `./chroma_data` | Vector Data Persistence Directory |
| **RAG Files** | `RAG_UPLOAD_DIR` | `./uploaded_docs` | Document Upload Directory |
| | `RAG_DEFAULT_CHUNK_SIZE` | `500` | Default Chunk Size |
| | `RAG_DEFAULT_CHUNK_OVERLAP` | `50` | Default Chunk Overlap |
| **Background Tasks** | `ENABLE_BACKGROUND_TASK` | `false` | Enable Background Asynchronous Tasks |
| | `BACKGROUND_TASK_TIMEOUT` | `300` | Timeout (seconds) |
| **Logs** | `LOG_LEVEL` | `INFO` | Log Level |
| | `LOG_FILE` | `logs/app.log` | Log File Path |
</details>
## 🔧 MainAgent Toolset
MainAgent completes complex tasks through tool calls, with the following built-in tools:
| Tool | Description |
|:-----|:-----|
| `read_skill_doc` | Read skill documents, determine if they match current needs |
| `execute_skill` | Execute specified skills (e.g., exam generation) |
| `sub_agent` | Dispatch sub-tasks to SubAgent for parallel processing |
| `google_search` | Search online to enhance content quality |
| `task_manage` | Task planning and state management |
| `background_task` | Background asynchronous task management |
## 📦 Skill System
The system automatically scans the `app/skills/` directory, registering modules containing `SKILL.md` + `scripts/` as available skills:
| Skill | Description |
|:-----|:-----|
| `exam_generation` | Multi-Agent collaboration to generate exams (multiple choice / fill-in-the-blank / short answer / illustration) |
| `pdf` | PDF extraction, creation, merging, and form processing |
> New skills can be added by creating a directory under `app/skills/`, including `SKILL.md` (skill description) and `scripts/` (execution scripts), which will be automatically discovered and registered.
## 🔗 MCP Configuration
The project includes an MCP Server and Client:
- **Server** (`app/mcp/search_server.py`): Provides `google_search`, `wikipedia_search`, and `fetch_webpage` search tools
- **Client** (`app/mcp/mcp_client.py`): Supports local / remote / WebSocket / HTTP / SSE connections
```json
// mcp.json
{
"mcpServers": {
"easyexam-tools": {
"command": "python",
"args": ["app/mcp/search_server.py"],
"type": "local"
}
}
}
```
Enable MCP mode with `USE_MCP=true` (recommended), or use `bind_tools` for direct connection.
## 🧑💻 Development
```bash
make install # Install dependencies
make run # Start development server (hot reload)
make test # Run tests
make format # Format code (Black + isort)
make lint # Code check (Flake8 + mypy)
make clean # Clean cache files
make venv # Create virtual environment
```
## 🗺️ Roadmap
- [x] MainAgent intent recognition + skill scheduling
- [x] Multi-Agent collaboration for exam generation
- [x] SSE streaming response
- [x] MCP protocol integration
- [x] RAG knowledge base (multi-source documents / multi-strategy chunking / semantic search)
- [x] Exam CRUD and file management
- [ ] Enhanced question generation based on RAG (knowledge base + Agent collaboration)
- [ ] User authentication and permission system
- [ ] Agent parallel execution optimization
- [ ] Adaptive difficulty and question deduplication
- [ ] Automatic scoring system
## 📄 License
[MIT](LICENSE)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available