EduMorph AI - Adaptive Learning Platform

EduMorph AI transforms static PDF educational materials into interactive, multi-modal learning experiences using Google Gemini Flash 2.5 and AWS services.

Features

• Document Ingestion: Upload PDFs and extract text using AWS Textract
• RAG Pipeline: Semantic search with local embeddings using sentence-transformers
• Podcast Generation: Convert content into conversational audio using Amazon Polly
• AI Tutor: Interactive Q&A powered by Gemini Flash 2.5
• Quiz Engine: Spaced repetition-based assessments
• Mind Map Visualization: Interactive concept mapping with React Flow

Architecture

• Backend: Python FastAPI with async processing
• Frontend: React + Vite + Tailwind CSS
• AI: Google Gemini Flash 2.5 via API key
• Vector DB: ChromaDB (dev) / OpenSearch (prod)
• Storage: AWS S3 (free tier)
• Text Extraction: AWS Textract
• Text-to-Speech: Amazon Polly

Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+
• AWS Account (free tier)
• Google AI Studio API key

1. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env file with your API keys:
# - GEMINI_API_KEY (from Google AI Studio)
# - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
# - AWS_S3_BUCKET name

# Test the setup
python test_setup.py

# Start the backend server
python main.py

The backend will be available at http://localhost:8000

2. Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

The frontend will be available at http://localhost:5173

3. Quick Start Scripts (Windows)

For convenience, you can use the provided batch files:

# Start backend
start_backend.bat

# Start frontend (in another terminal)
start_frontend.bat

API Documentation

Once the backend is running, visit:

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Project Structure

├── backend/                    # Python FastAPI backend
│   ├── app/
│   │   ├── core/              # Configuration and settings
│   │   │   └── config.py      # Application settings
│   │   └── services/          # Business logic services
│   │       ├── embedding_service.py    # Local embeddings with sentence-transformers
│   │       └── gemini_service.py       # Google Gemini API integration
│   ├── venv/                  # Python virtual environment
│   ├── main.py                # FastAPI application entry point
│   ├── requirements.txt       # Python dependencies
│   ├── test_setup.py          # Setup verification script
│   └── .env.example           # Environment variables template
├── frontend/                  # React frontend
│   ├── src/
│   │   ├── App.tsx            # Main React component
│   │   ├── main.tsx           # React entry point
│   │   └── index.css          # Tailwind CSS imports
│   ├── package.json           # Node.js dependencies
│   ├── vite.config.ts         # Vite configuration
│   ├── tailwind.config.js     # Tailwind CSS configuration
│   └── tsconfig.json          # TypeScript configuration
├── start_backend.bat          # Windows backend startup script
├── start_frontend.bat         # Windows frontend startup script
├── .env.example               # Global environment template
└── README.md                  # This file

Environment Variables

Create a .env file in the backend directory with the following variables:

# Google Gemini API Configuration
GEMINI_API_KEY=your_gemini_api_key_here

# AWS Configuration
AWS_ACCESS_KEY_ID=your_aws_access_key_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
AWS_REGION=us-east-1
AWS_S3_BUCKET=edumorph-documents

# Application Configuration
ENVIRONMENT=development
DEBUG=true

# Vector Database Configuration
VECTOR_DB_TYPE=chromadb
CHROMADB_PATH=./data/chromadb

Getting API Keys

Google Gemini API Key

1. Visit Google AI Studio
2. Create a new API key
3. Copy the key to your .env file

AWS Credentials

1. Sign up for AWS (free tier available)
2. Create an IAM user with permissions for S3, Textract, and Polly
3. Generate access keys
4. Copy to your .env file

Development

Backend Development

• FastAPI automatic docs: http://localhost:8000/docs
• Health check: http://localhost:8000/health
• Run tests: pytest
• Verify setup: python test_setup.py

Frontend Development

• Hot reload enabled with Vite
• Tailwind CSS for styling
• Lucide React for icons
• Run tests: npm test

Testing

Backend Tests

cd backend
venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux
pytest

Frontend Tests

cd frontend
npm test

Setup Verification

cd backend
python test_setup.py

Troubleshooting

Common Issues

1. Import errors with sentence-transformers: Make sure numpy<2.0 is installed
2. ChromaDB compatibility: Ensure numpy version is <2.0
3. API key errors: Verify your Gemini API key is correctly set in .env
4. AWS permissions: Ensure your AWS user has S3, Textract, and Polly permissions

Dependencies

If you encounter dependency issues:

# Backend
cd backend
pip install --upgrade pip
pip install -r requirements.txt

# Frontend
cd frontend
npm install

Next Steps

After setup is complete, you can:

1. Implement Document Upload: Add PDF upload functionality
2. Set up RAG Pipeline: Configure vector database and embeddings
3. Add Content Generation: Implement podcast, quiz, and mind map generation
4. Create AI Tutor: Build conversational Q&A interface
5. Add Authentication: Implement user management
6. Deploy to Cloud: Set up production deployment

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Verify your environment setup with python test_setup.py
3. Check API documentation at http://localhost:8000/docs