# eduagent-pro

**Repository Path**: joeyloo/eduagent-pro

## Basic Information

- **Project Name**: eduagent-pro
- **Description**: 我自己的教学bot
- **Primary Language**: Python
- **License**: MPL-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduAgent

AI-powered educational assistant combining the best of DeepTutor and Hermes Agent.

<!-- Badges -->
<!--
[![Tests](https://github.com/your-org/eduagent-pro/actions/workflows/tests.yml/badge.svg)](https://github.com/your-org/eduagent-pro/actions)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](docs/DEPLOYMENT.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-->

## Features

- 🤖 **AI Tutor** - Personalized learning with adaptive tutoring
- 📚 **Knowledge Base** - RAG-powered answers from uploaded documents
- 🔧 **Tool System** - Code execution and other educational tools
- 💬 **Multi-modal Chat** - Support for text, code, and visual learning
- 📖 **Book Engine** - Generate structured learning materials
- 🔐 **User Authentication** - Secure JWT-based auth system

## Tech Stack

### Frontend
- Next.js 16 (App Router)
- React 19
- TypeScript (Strict Mode)
- Tailwind CSS v4
- shadcn/ui components

### Backend
- FastAPI
- SQLAlchemy 2.0 (Async)
- Alembic (Migrations)
- Pydantic v2
- Celery (Background Tasks)

### Infrastructure
- PostgreSQL 16 + pgvector (Vector search)
- Redis (Cache + Message Broker)
- MinIO (S3-compatible Object Storage)

## Architecture

```mermaid
graph TB
    User[</br>User Browser</br>]
    Nginx[</br>Nginx</br>Reverse Proxy</br>]
    Web[</br>Next.js Frontend</br>:3000</br>]
    API[</br>FastAPI Backend</br>:8000</br>]
    Celery[</br>Celery Worker</br>]
    Postgres[</br>PostgreSQL</br>+ pgvector</br>:5432</br>]
    Redis[</br>Redis</br>:6379</br>]
    MinIO[</br>MinIO</br>S3 Storage</br>:9000</br>]

    User -->|HTTP/HTTPS| Nginx
    Nginx -->|/| Web
    Nginx -->|/api/| API
    Nginx -->|/ws/| API
    API -->|SQL| Postgres
    API -->|Cache/Queue| Redis
    API -->|Tasks| Celery
    Celery -->|SQL| Postgres
    API -->|Object Storage| MinIO
    Celery -->|Object Storage| MinIO
```

## Quick Start (Without Docker)

### Prerequisites

- Node.js 20+
- Python 3.11+
- Git Bash or PowerShell

### Option 1: PowerShell One-Click Startup (Windows)

```powershell
# In PowerShell, run:
.\start-dev.ps1
```

This will automatically start both frontend and backend servers.

> **Note:** If ports are occupied or you see `WinError 10013`, use **Manual Startup** (Option 2) instead.

### Option 2: Manual Startup (Recommended)

**Step 1 — Configure `.env`**

`.env` is located at the project root and pre-configured with SQLite. Key settings:

```ini
# Database (SQLite for dev, no Docker needed)
DATABASE_URL=sqlite+aiosqlite:///./eduagent.db

# LLM Provider: openai | deepseek
DEFAULT_LLM_PROVIDER=deepseek
DEFAULT_LLM_MODEL=deepseek-v4-pro
LLM_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=sk-your-deepseek-key

# CORS (JSON array format required)
CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
```

> **Important:** `.env` uses **JSON array** for `CORS_ORIGINS`. Comma-separated strings will cause a parse error.

**Step 2 — Start Backend (Terminal 1)**

```powershell
cd apps/api
.venv\Scripts\Activate.ps1
uvicorn src.main:app --reload --host 127.0.0.1 --port 8000
```

**Step 3 — Start Frontend (Terminal 2)**

```powershell
cd apps/web
npm run dev
```

**Access Points:**

| Service | URL |
|---------|-----|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| API Docs | http://localhost:8000/docs |

### Access Points

| Service | URL |
|---------|-----|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| API Docs | http://localhost:8000/docs |

### Quick Test

```powershell
# Run startup test
.\test-startup.ps1
```

## Production Deployment

For production deployment with Docker Compose:

```bash
# 1. Configure environment
cp .env.example .env
# Edit .env with production values

# 2. Deploy with one-click script
chmod +x scripts/deploy.sh
./scripts/deploy.sh
```

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions including SSL setup, monitoring, and troubleshooting.

## Docker Setup (Optional - for Full Infrastructure)

If you want to use PostgreSQL + Redis + MinIO in development:

```bash
# Start Docker Desktop first, then:
docker-compose up -d postgres redis minio

# Update .env to use PostgreSQL:
DATABASE_URL=postgresql+asyncpg://eduagent:eduagent123@localhost:5432/eduagent

# Run migrations
cd apps/api
alembic upgrade head
```

## Development with Docker Compose

Alternatively, you can run everything with Docker Compose:

```bash
# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v
```

## Project Structure

```
eduagent-pro/
├── apps/
│   ├── web/                    # Next.js 16 Frontend
│   │   ├── src/
│   │   │   ├── app/            # App Router (route groups)
│   │   │   ├── components/     # React Components
│   │   │   └── lib/            # API clients & utilities
│   │   ├── package.json
│   │   ├── Dockerfile          # Development image
│   │   └── Dockerfile.prod     # Production image
│   │
│   └── api/                    # FastAPI Backend
│       ├── src/
│       │   ├── models/         # SQLAlchemy ORM
│       │   ├── schemas/        # Pydantic Schemas
│       │   ├── services/       # Business Logic
│       │   ├── routers/        # API Routes
│       │   ├── middleware/     # FastAPI Middleware
│       │   ├── core/           # Config, Security, DB
│       │   └── tasks/          # Celery Tasks
│       ├── tests/
│       │   ├── integration/    # End-to-end integration tests
│       │   └── test_*.py       # Unit tests
│       ├── alembic/            # Database Migrations
│       ├── pyproject.toml
│       └── Dockerfile
│
├── docs/
│   ├── architecture.md         # System architecture
│   ├── API.md                  # API documentation
│   ├── DEPLOYMENT.md           # Deployment guide
│   └── DEVELOPMENT.md          # Development guide
├── scripts/
│   ├── deploy.sh               # One-click deploy
│   └── health-check.sh         # Health check script
├── nginx/
│   └── nginx.conf              # Reverse proxy config
├── docker-compose.yml          # Development orchestration
├── docker-compose.prod.yml     # Production orchestration
└── .env.example                # Environment variables template
```

## LLM Provider Configuration

The backend supports OpenAI-compatible APIs (OpenAI, DeepSeek, etc.).

### DeepSeek (Default)

```ini
DEFAULT_LLM_PROVIDER=deepseek
DEFAULT_LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=sk-your-key
```

### OpenAI

```ini
DEFAULT_LLM_PROVIDER=openai
DEFAULT_LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-your-key
```

After modifying `.env`, **restart the backend** (`get_settings()` uses `@lru_cache`).

## API Endpoints

### Health Check
- `GET /api/v1/health` - Service health status
- `GET /api/v1/health/ready` - Readiness probe

### Authentication
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/refresh` - Refresh access token
- `POST /api/v1/auth/logout` - Logout (blacklist tokens)
- `GET /api/v1/auth/me` - Current user info

### Materials
- `POST /api/v1/materials/generate` - AI generate learning material
- `POST /api/v1/materials/upload-generate` - Upload PDF/Markdown and generate
- `GET /api/v1/materials` - List materials with pagination
- `GET /api/v1/materials/{id}` - Get material by ID
- `PUT /api/v1/materials/{id}` - Update material
- `DELETE /api/v1/materials/{id}` - Delete material

### Chat
- `POST /api/v1/chat` - Send chat message
- `POST /api/v1/chat/stream` - Stream chat response (SSE)
- `WS /api/v1/ws/chat` - Real-time WebSocket chat

### Admin
- `GET /api/v1/stats/dashboard` - Dashboard metrics
- `GET /api/v1/users` - User management
- `GET /api/v1/audit` - Audit logs
- `GET /api/v1/config` - System configuration

See [docs/API.md](docs/API.md) for the complete API reference.

## Testing

### Unit Tests

```bash
cd apps/api
pytest tests/test_*.py -v
```

### Integration Tests

```bash
cd apps/api
pytest tests/integration/ -v
```

### Load Tests

```bash
cd tests/performance
./run_load_test.sh http://localhost:8000 50 60s
```

## Documentation

| Document | Description |
|----------|-------------|
| [docs/API.md](docs/API.md) | Complete API reference with endpoint details |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment guide |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Development setup and code standards |
| [docs/architecture.md](docs/architecture.md) | System architecture overview |

## Environment Variables

`.env` is located at the **project root** and auto-loaded by `config.py`.

Key variables:
- `DATABASE_URL` - SQLite/PostgreSQL connection string
- `SECRET_KEY` - JWT secret key
- `DEFAULT_LLM_PROVIDER` - `openai` or `deepseek`
- `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` - LLM API keys
- `LLM_BASE_URL` - Base URL for OpenAI-compatible APIs
- `CORS_ORIGINS` - JSON array of allowed origins
- `REDIS_URL` - Redis connection string (optional)
- `MINIO_*` - MinIO object storage configuration (optional)

## Troubleshooting

### Port 8000 occupied (`WinError 10013`)

```powershell
# Kill all Python processes
Get-Process python -ErrorAction SilentlyContinue | Stop-Process -Force

# Or use a different port
uvicorn src.main:app --reload --host 127.0.0.1 --port 8001
```

### Chat returns mock reply

1. Check `.env` has valid `DEEPSEEK_API_KEY` or `OPENAI_API_KEY`
2. Verify config is loaded: `python -c "from src.core.config import get_settings; print(get_settings().default_llm_provider)"`
3. **Restart backend** — `get_settings()` uses `@lru_cache`, changes only apply after restart

### `CORS_ORIGINS` parse error

Use JSON array format, not comma-separated string:
```ini
# Correct
CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]

# Wrong
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
```

### Tests call real LLM API (slow / expensive)

Mock tests patch `_has_llm` to `False`. If you see tests taking minutes, check that `.env` isn't pointing to a real API key during CI.

## Code Quality

### Frontend
```bash
cd apps/web
npm run lint          # ESLint
npm run lint:fix      # ESLint with auto-fix
npm run format        # Prettier format
npm run type-check    # TypeScript type checking
```

### Backend
```bash
cd apps/api
black .               # Code formatting
isort .               # Import sorting
ruff check .          # Linting
ruff check --fix .    # Linting with auto-fix
mypy src              # Type checking
pytest                # Run tests
```

## Contributing

1. Fork the repository
2. Create your feature branch from `dev` (`git checkout -b feature/amazing-feature`)
3. Commit your changes using [Conventional Commits](docs/DEVELOPMENT.md#git-workflow)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request to `dev`

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development guidelines.

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Inspired by [DeepTutor](https://github.com/HKUDS/DeepTutor) and [Hermes Agent](https://github.com/NousResearch/hermes-agent)