Skip to content

StudentTraineeCenter/edu-agent

BranchesTags

Repository files navigation

EduAgent

AI-powered educational platform for creating interactive learning experiences

Python TypeScript FastAPI React License

Features • Quick Start • Documentation • Contributing

EduAgent is a cutting-edge, AI-powered educational platform designed to transform how you learn. By combining advanced RAG (Retrieval-Augmented Generation) with proactive AI agents, EduAgent turns static documents into a dynamic, personalized tutor. Upload your course materials and experience a new way of studying with automatically generated quizzes, flashcards, mind maps, and a Personalized Study Plan that adapts to your unique learning pace.

Table of Contents

✨ Features

  • 📂 Project-Based Learning - Organize courses into focused projects containing all your documents, chats, and AI-generated study aids.
  • 🧠 Personalized Study Plans - AI identifies your weak spots based on performance and generates a custom tailored curriculum to help you master the material.
  • 🤖 Proactive AI Tutor - Chat with an intelligent agent that not only answers questions but proactively generates quizzes, flashcards, and notes during your conversation.
  • 📄 Smart Document Processing - Drag-and-drop PDF, DOCX, TXT, and RTF files. We handle the OCR, text extraction, and vector embedding automatically.
  • 🔍 Semantic Search & RAG - Stop Ctrl+F. Ask questions and get answers grounded in your specific course materials with source citations.
  • 📝 Automated Quizzes - Generate multiple-choice quizzes from any document. The system grades you, explains answers, and tracks your progress.
  • 🎴 Flashcards (Spaced Repetition) - Turn dense text into flashcards instantly. Perfect for memorizing definitions and key concepts.
  • 🗺️ Interactive Mind Maps - Visualize connections between topics with AI-generated mind maps that help you understand the bigger picture.
  • 🔐 Enterprise-Grade Security - Built with Supabase Auth, Row Level Security, and Azure usage limits to keep your data safe and costs controlled.

🏗️ Tech Stack

Backend

Frontend

📋 Prerequisites

Before you begin, ensure you have the following installed:

🚀 Quick Start

Get EduAgent running locally using Docker for the backend and Vite for the frontend:

# Clone the repository
git clone https://github.com/StudentTraineeCenter/edu-agent.git
cd edu-agent

# Start backend stack (API, worker, Postgres, Azurite)
docker-compose up --build api worker db azurite

# In a separate terminal, run DB migrations (one-time)
# Make sure DATABASE_URL is set correctly for your local Postgres
export DATABASE_URL="postgresql+psycopg2://postgres:postgres@localhost:5432/postgres"
alembic upgrade head

# In a new terminal, start the web frontend
cd src/edu-web
pnpm install
pnpm dev

Visit http://localhost:3000 for the web app and http://localhost:8000 for the API.

📦 Installation

Backend Setup (API + Worker)

The Python services use a uv workspace with pyproject.toml + uv.lock.

cd edu-agent

# Install uv if you don't have it yet (see https://docs.astral.sh/uv/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all workspace dependencies (api, worker, shared)
uv sync

# Run database migrations (DATABASE_URL must be set)
export DATABASE_URL="postgresql+psycopg2://postgres:postgres@localhost:5432/postgres"
alembic upgrade head

# Start API locally (without Docker)
cd src/edu-api
uv run python main.py

# Optional: in another terminal, start the worker locally
cd src/edu-worker
uv run python main.py

Frontend Setup

cd src/edu-web

# Install dependencies
pnpm install

# Generate TypeScript types from OpenAPI schema (optional)
pnpm gen:types

⚙️ Configuration

Backend Environment Variables

You can configure the backend either via Azure Key Vault (recommended for production) or via local environment variables / .env files (recommended for local dev).

# Azure Key Vault (production)
AZURE_KEY_VAULT_URI=

# Usage Limits (optional, defaults shown)
MAX_DOCUMENT_UPLOADS_PER_DAY=5
MAX_QUIZ_GENERATIONS_PER_DAY=10
MAX_FLASHCARD_GENERATIONS_PER_DAY=10
MAX_CHAT_MESSAGES_PER_DAY=50

For local development, you can skip Key Vault and set individual environment variables directly:

# Azure Key Vault (local)
AZURE_KEY_VAULT_URI=

# Usage Limits (optional, defaults shown)
MAX_DOCUMENT_UPLOADS_PER_DAY=5
MAX_QUIZ_GENERATIONS_PER_DAY=10
MAX_FLASHCARD_GENERATIONS_PER_DAY=10
MAX_CHAT_MESSAGES_PER_DAY=50

Note: The backend uses python-dotenv, so .env files at the project root work fine for local dev. See Local Development Guide for the full list and details.

Frontend Environment Variables

Create a .env file in the src/edu-web/ directory:

VITE_SERVER_URL=http://localhost:8000
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=

For detailed configuration instructions, see the Local Development Guide.

📁 Project Structure

edu-agent/
├── src/
│   ├── edu-api/        # FastAPI backend (public API)
│   ├── edu-worker/     # Background worker (queue/AI processing)
│   ├── edu-web/        # React frontend (Vite + TanStack)
│   └── edu-shared/     # Shared DB models, agents, services, schemas
├── deploy/
│   └── azure/          # Azure Terraform + ACR build tooling
├── docs/               # Documentation (features, local dev, privacy, etc.)
├── alembic.ini         # Alembic config pointing at src/edu-shared/db/alembic
├── docker-compose.yaml # Local stack (api, worker, db, azurite)
├── pyproject.toml      # uv workspace definition
├── uv.lock             # Locked dependency graph
└── ruff.toml           # Backend linting/formatting configuration

🔧 Development

Backend Development

# From repo root

# Create a new database migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Run API with uv (auto-respects workspace venv)
cd src/edu-api
uv run python main.py

Frontend Development

cd src/edu-web

# Start development server
pnpm dev

# Build for production
pnpm build

# Run linter
pnpm lint

# Format code
pnpm format

# Run type checking
pnpm type-check

# Generate TypeScript types from OpenAPI schema
pnpm gen:types

Code Quality

Both backend and frontend use linting and formatting tools:

  • Backend: Ruff (configured in ruff.toml, run via ruff format . and ruff check .)
  • Frontend: ESLint + Prettier (configured in src/edu-web/)

📚 API Documentation

Once the backend server is running, API documentation is available at:

  • Scalar UI (OpenAPI docs): http://localhost:8000/
  • Health Check: http://localhost:8000/health
  • OpenAPI Schema: http://localhost:8000/openapi.json

📖 Documentation

Comprehensive documentation is available in the docs/ directory:

  • Features - Detailed overview of platform features and capabilities
  • Local Development - Complete setup and development guide (Docker + uv workspace)
  • Azure Deployment - Production deployment instructions for Azure (using deploy/azure)
  • Privacy Policy - Privacy and data handling information

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow the existing code style and conventions
  • Write clear commit messages
  • Add tests for new features when possible
  • Update documentation as needed
  • Ensure all linting checks pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

🙏 Acknowledgments

Made with ❤️ for students and educators

⬆ Back to Top

About

app-eduagent-dev-swc-web-fzgza1.azurewebsites.net/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Languages