Skip to main content
Get started with EduMate and create your first Bloom’s taxonomy-aligned assessment from your educational materials in minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.8 or higher installed
  • Node.js 16 or higher and npm
  • PostgreSQL database running
  • Qdrant vector database running
  • Ollama with embedding model installed
  • Redis server running
  • A Google Gemini API key (for AI generation)
If you haven’t installed these dependencies yet, follow our complete Installation Guide first.

​
Get Started

1

Clone and Set Up the Project

Clone the repository and navigate to the project directory:
git clone <repository-url>
cd edu-mate
Install Python dependencies:
pip install -r requirements.txt
Install frontend dependencies:
cd frontend
npm install
cd ..
2

Configure Your Database

Create a PostgreSQL database for EduMate:
createdb edumate
createuser edumate_user -P
# Enter password: edumate_pass when prompted
Update the database connection in backend/database.py:
backend/database.py
SQLALCHEMY_DATABASE_URL = "postgresql://edumate_user:edumate_pass@localhost:5432/edumate"
The database tables will be created automatically when you start the server for the first time.
3

Set Up Your Environment

Create a .env file in the project root and add your Gemini API key:
GEMINI_API_KEY=your_gemini_api_key_here
Ensure all required services are running:
  • PostgreSQL: Port 5432
  • Qdrant: Port 6333
  • Redis: Port 6379
  • Ollama: Port 11434
You can verify Ollama is running by visiting http://localhost:11434 in your browser.
4

Start the Backend Server

Start the Redis queue worker in one terminal:
rq worker
Start the FastAPI backend server in another terminal:
python -m backend.main
The API server will be available at http://localhost:8000.
5

Start the Frontend (Optional)

For development, you can run the React frontend:
cd frontend
npm run dev
Or build it for production:
cd frontend
npm run build
cd ..
If you build the frontend, the FastAPI server will automatically serve it from http://localhost:8000.
6

Create Your Account

Register a new account using the signup endpoint:
curl -X POST http://localhost:8000/api/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "your_secure_password"
  }'
Then login to get your access token:
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=your_secure_password"
Save the access_token from the response - you’ll need it for authenticated requests.
7

Upload Your First Document

Upload a PDF document to be processed and indexed:
curl -X POST http://localhost:8000/chunking \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/your/document.pdf"
The response will include a job_id and collection_name:
{
  "status": "queued",
  "job_id": "abc123-def456",
  "collection_name": "edu_mate_7f3a2b..."
}
The document will be chunked into smaller pieces and embedded using Ollama’s qwen3-embedding:0.6b model, then stored in Qdrant for semantic search.
8

Check Processing Status

Monitor the chunking job status:
curl http://localhost:8000/chunking/status?job_id=YOUR_JOB_ID
Wait until you get a response with "status": "chunked":
{
  "status": "chunked",
  "result": {
    "stored": true,
    "chunks": 42,
    "collection_name": "edu_mate_7f3a2b..."
  }
}
9

Generate Your First Assessment

Generate multiple-choice questions based on your document:
curl -X POST "http://localhost:8000/chat" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "query=Generate MCQs for Node.js fundamentals" \
  -d "collection_name=edu_mate_7f3a2b..." \
  -d "blooms_requirements=5 remember, 3 understand, 4 apply, 3 analyze, 2 evaluate, 3 create"
This returns a job ID:
{
  "status": "queued",
  "job_id": "xyz789-uvw012"
}
Check the job status:
curl http://localhost:8000/job_status?job_id=YOUR_JOB_ID
When complete, you’ll receive structured MCQs:
{
  "status": "finished",
  "result": {
    "mcqs": [
      {
        "question_no": "1",
        "bloom_level": "remember",
        "question": "What is the primary purpose of Node.js?",
        "answer_options": [
          "Server-side JavaScript runtime",
          "Frontend framework",
          "Database management system",
          "CSS preprocessor"
        ],
        "correct_answer": "Server-side JavaScript runtime",
        "explaination": "Node.js is a runtime environment that allows JavaScript to be executed on the server side."
      }
    ]
  }
}
The Bloom’s taxonomy requirements string controls how many questions are generated at each cognitive level. Adjust these numbers based on your assessment needs.
10

Save Your Assessment

Save the generated assessment to your database:
curl -X POST http://localhost:8000/api/assessments/save \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chapter_name": "Node.js Fundamentals",
    "bloom_factors": {
      "remember": 5,
      "understand": 3,
      "apply": 4,
      "analyze": 3,
      "evaluate": 2,
      "create": 3
    },
    "content_json": {
      "mcqs": [...]
    }
  }'

​
What’s Next?

Installation Guide

Detailed setup instructions for all dependencies

API Reference

Complete API documentation for all endpoints

RAG System

Learn about EduMate’s RAG architecture

Bloom's Taxonomy

Understanding cognitive levels in assessments

​
Common Issues

Job keeps failing? Make sure:
  • Ollama has the qwen3-embedding:0.6b model pulled: ollama pull qwen3-embedding:0.6b
  • Qdrant is accessible at http://localhost:6333
  • Your PDF contains extractable text (not just images)
  • Redis worker is running in a separate terminal
Authentication errors? Verify:
  • Your access token is included in the Authorization: Bearer YOUR_TOKEN header
  • The token hasn’t expired (24-hour expiration by default)
  • You’re using the correct email/password combination

Build docs developers (and LLMs) love

Get started for freeTalk to us