Educational Tutor Bot - Project Documentation

📖 Project Overview

Educational Tutor Bot is a comprehensive AI-powered educational platform that integrates OpenAI API with Flask to create an intelligent tutoring system. This project offers AI-powered tutoring with conversation memory, multi-language support (10+ languages), voice input and speech recognition, file upload and document analysis, structured learning paths for different subjects, practice question generation, comprehensive progress tracking and analytics, and personalized learning recommendations. Perfect for students, educators, and learners looking to enhance their educational experience with AI-powered tutoring and advanced learning tools.

⚡ Quick Facts

🎯 Type: Educational Platform with AI Capabilities

🤖 AI Features: OpenAI API, Conversation Memory, AI Tutoring, Multi-Language, Voice Input

⚡ Setup Time: ~5 minutes

📦 Backend: Python with Flask

🎨 Frontend: HTML5, CSS3, JavaScript

🧠 AI Model: OpenAI GPT-3.5 Turbo

📱 Platform: Web Browser

🔧 Technologies: Python, Flask, OpenAI API

25+

Files

5000+

Lines of Code

20+

Advanced Features

200K

Context Tokens

Developer: Molla Samser | Website: rskworld.in | Email: help@rskworld.in

Difficulty Level: Intermediate - Perfect for developers learning Python, Flask, OpenAI API integration, educational platform development, and AI-powered tutoring systems.

✨ Features

Core Features

🤖 AI-Powered Tutoring

Seamless integration with OpenAI GPT models for intelligent educational responses with conversation memory and context awareness.

🧠 Conversation Memory

Maintains conversation context for better learning experiences using efficient memory storage per student session.

🌍 Multi-Language Support

Support for 10+ languages including English, Spanish, French, German, Hindi, Bengali, Chinese, Japanese, Korean, and Arabic.

🎤 Voice Input

Speech recognition for voice input and hands-free interaction with the educational tutor bot.

Advanced Features

📎 File Analysis

Upload documents, images, and files for the AI tutor to analyze and provide educational insights.

📚 Learning Paths

Structured learning paths for different subjects and difficulty levels to guide your educational journey.

📝 Practice Questions

Generate custom practice questions and quizzes for various subjects and topics.

📊 Progress Tracking

Comprehensive progress tracking system with analytics, statistics, and learning achievements.

💾 Export Progress

Export learning progress and chat history as JSON or CSV files for record-keeping and analysis.

🎨 Code Syntax Highlighting

Beautiful code rendering with syntax highlighting for multiple programming languages.

📝 Markdown Rendering

Rich text formatting support with full markdown rendering including tables, lists, and links.

⚡ Real-time Responses

Fast AI responses with real-time processing for improved learning experience.

📊 Learning Analytics

Monitor learning progress, token usage, API statistics, and detailed analytics.

🎯 Quick Actions

Pre-built quick action buttons for common educational tasks to quickly start learning.

🔍 Concept Search

Search through learning history to quickly find specific concepts or topics.

⚙️ Personalized Learning

Adaptive learning recommendations based on your progress and learning style.

🛠️ Technologies

Python

Core programming language for educational platform

Language

Flask

Python web framework for backend API

Framework

OpenAI API

AI model integration for educational tutoring

AI API

SQLite

Database for storing learning progress and chat history

Database

python-dotenv

Environment variable management for configuration

Config

Speech Recognition

Voice input processing for hands-free interaction

Voice

Modular Architecture

Clean, modular code structure for easy extension

Architecture

📦 Installation Guide - Step by Step

⏱️ Installation Time: ~5 minutes

Follow these simple steps to set up the Educational Tutor Bot on your system.

📋 Prerequisites

🐍 Python 3.8+

Python 3.8 or higher required for the educational platform

Download: Python

🌐 Web Browser

Modern web browser (Chrome, Firefox, Safari, Edge) for accessing the educational platform

Recommended: Latest version of Chrome or Firefox

🌐 OpenAI API Key

Get your API key from OpenAI Platform (required for AI features)

Get Key: OpenAI Platform

🌐 Internet Connection

Required for Flask server and OpenAI API calls

🚀 Step-by-Step Installation

📌 Step 1: Download or Clone the Project

Option A: Download ZIP

Download the project ZIP file from the repository
Extract it to your desired location (e.g., C:\Projects\educational-tutor-bot or ~/Projects/educational-tutor-bot)
Navigate to the extracted folder

Option B: Clone with Git

git clone https://github.com/rskworld/educational-tutor-bot.git
cd educational-tutor-bot

✅ Step 2: Install Python Dependencies

Install required Python packages using pip.

# Install dependencies
pip install -r requirements.txt

🔑 Step 3: Set Up API Keys

Configure your OpenAI API key in the environment file.

Copy .env.example to .env
Edit .env and add your API key:
- OPENAI_API_KEY=sk-your-openai-key-here
- FLASK_ENV=development (optional)
- PORT=5000 (optional, default is 5000)
Get your OpenAI API key from OpenAI Platform
Make sure your API key has sufficient credits for testing

🚀 Step 4: Start the Flask Server

Start the Flask backend server by running app.py.

# Start Flask server
python app.py

# The server will start on http://localhost:5000

🌐 Step 5: Open Frontend

Open the HTML file in your browser or use a local web server.

Method 1: Direct File Opening

Open index.html in your browser

Method 2: Using Local Web Server (Recommended)

# In a new terminal, start HTTP server
python -m http.server 8000

# Then open: http://localhost:8000

✅ Installation Complete!

Congratulations! You've successfully set up the Educational Tutor Bot. The platform is ready to use with all features including:

OpenAI API integration for AI-powered tutoring
Conversation memory for context-aware learning
Multi-language support (10+ languages)
Voice input and speech recognition
File upload and document analysis
Structured learning paths
Practice question generation
Progress tracking and analytics
Personalized learning recommendations

Next Steps:

Ensure the Flask server is running (Step 4)
Open the frontend in your browser (Step 5)
Start asking educational questions to test the AI tutor
Explore all the features, learning paths, and customization options!

🔧 Troubleshooting Installation

❌ API Key Issues

Solution: Ensure your .env file contains a valid OPENAI_API_KEY starting with sk-. Check API key has sufficient credits.

❌ Flask Server Not Starting

Solution: Check Python version (3.8+), verify dependencies installed with pip install -r requirements.txt, ensure port 5000 is available.

❌ Connection Errors

Solution: Verify Flask server is running on port 5000, check script.js has correct API_BASE_URL, ensure CORS is enabled in Flask.

❌ Import Errors

Solution: Reinstall dependencies, check virtual environment is activated, verify all packages in requirements.txt are installed.

📚 Usage Guide - Step by Step

🎯 Getting Started with Educational Tutor Bot

Step-by-Step Usage Instructions

📝 Step 1: Start Backend Server

Ensure Flask server is running: python app.py
Check server status at http://localhost:5000
You should see the Educational Tutor Bot interface

🌐 Step 2: Open Frontend

Open http://localhost:5000 in your web browser
You should see the Educational Tutor Bot interface with:
- Chat messages area with markdown support
- Text input field
- Quick action buttons for common tasks
- Features panel with learning capabilities
- Statistics cards showing progress
- Send button

💬 Step 3: Start Chatting

Text Input: Type your message and press Enter or click Send
Voice Input: Click microphone button and speak (optional)
File Upload: Click paperclip icon to attach images or documents
Try These:
- "Explain quantum computing in simple terms"
- "Write a Python function to calculate Fibonacci numbers"
- "Solve: x² + 5x + 6 = 0"
- "Summarize the key features of AI"
- "Compare Python and JavaScript"
View Responses: The AI tutor will respond with formatted text, code blocks, and markdown

⚙️ Step 4: Explore Features

Try out the platform features:

Quick Actions: Use pre-built buttons for common educational tasks
Learning Paths: Follow structured learning paths for different subjects
Practice Questions: Generate custom practice quizzes
Progress Tracking: Monitor your learning progress and statistics
Multi-Language: Switch between 10+ supported languages
Voice Input: Use voice commands for hands-free interaction

💻 Using the Educational Platform

You can interact with the Educational Tutor Bot through the web interface:

# Example Interactions
User: "Can you help me understand algebra?"
Bot: [Detailed explanation with examples]

User: "Explain photosynthesis in simple terms"
Bot: [Step-by-step explanation]

User: "Create a practice quiz on Python"
Bot: [Generated quiz with questions and answers]

User: "Solve: x² + 5x + 6 = 0"
Bot: [Step-by-step solution]
                

# Quick Action Buttons
- Math Help: Get help with mathematics
- Explain Concept: Understand complex topics
- Practice Quiz: Generate practice questions
- Math Problem: Solve equations
- Summarize: Get summaries of topics
- Compare: Compare different concepts
                

📊 Features Usage

🤖 OpenAI API

Start learning and the AI tutor will respond with educational explanations and helpful guidance

📎 File Upload

Upload images or documents for the AI tutor to analyze and provide educational insights

🎤 Voice I/O

Use microphone for voice input and text-to-speech for responses

💬 Multiple Sessions

Create separate chat sessions for different topics or projects

🎨 Code Highlighting

Code blocks automatically rendered with syntax highlighting

📝 Markdown

Rich text formatting with full markdown support

⚡ Streaming

Enable streaming for real-time token-by-token responses

📊 Usage Tracking

Monitor token usage, API costs, and conversation statistics

🚀 Advanced Features & Capabilities

The Educational Tutor Bot includes advanced AI capabilities, learning tools, and educational features. Here's what you can do:

🧠 Advanced Reasoning

The AI tutor excels at complex educational tasks, coding challenges, mathematics, and multi-step problem solving. Ask complex questions and get detailed, well-reasoned educational responses.

📎 Multi-Modal Support

Upload images, PDFs, or documents for the AI tutor to analyze. The tutor can understand visual content and extract educational information from various file formats.

💬 Long Context

Handle extended conversations with up to 200K tokens of context. Perfect for detailed discussions, document analysis, and maintaining context across long interactions.

🎨 Code & Markdown

Code blocks are automatically highlighted with syntax highlighting. Markdown formatting including tables, lists, links, and more is fully supported and rendered beautifully.

💻 Code Examples

Basic OpenAI API Integration

// Python Flask backend - app.py
from openai import OpenAI
from flask import Flask, request, jsonify

app = Flask(__name__)
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

@app.route('/chat', methods=['POST'])
def chat():
    data = request.json
    response = client.chat.completions.create(
        model=data.get('model', 'gpt-3.5-turbo'),
        messages=[{"role": "user", "content": data['message']}],
        max_tokens=data.get('max_tokens', 1024)
    )
    return jsonify({
        'response': response.choices[0].message.content,
        'tokens_used': response.usage.total_tokens
    })

if __name__ == '__main__':
    app.run(debug=True, port=5000)
                

JavaScript Frontend Integration

// Frontend JavaScript - script.js
async function sendMessage(message) {
    const response = await fetch('http://localhost:5000/chat', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
            message: message,
            subject: 'General',
            difficulty: 'Intermediate',
            language: 'en'
        })
    });
    
    const data = await response.json();
    return data.response;
}

// Usage
sendMessage('Hello! Can you help me learn algebra?').then(response => {
    console.log('AI Tutor:', response);
});
                

Complete Educational Tutor Bot Example

// Educational Tutor Bot Class
class EducationalTutorBot {
    constructor(apiUrl) {
        this.apiUrl = apiUrl || 'http://localhost:5000/chat';
        this.conversationHistory = [];
    }
    
    async sendMessage(message, subject = 'General', difficulty = 'Intermediate') {
        const response = await fetch(this.apiUrl, {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({
                message: message,
                subject: subject,
                difficulty: difficulty,
                language: 'en'
            })
        });
        
        const data = await response.json();
        
        // Update conversation history
        this.conversationHistory.push(
            {role: 'user', content: message},
            {role: 'assistant', content: data.response}
        );
        
        return data.response;
    }
    
    clearHistory() {
        this.conversationHistory = [];
    }
}

// Usage
const tutorBot = new EducationalTutorBot();
tutorBot.sendMessage('Can you explain photosynthesis?').then(response => {
    console.log('AI Tutor:', response);
});
                

Configuration Example

// Frontend config - script.js
const TutorBotConfig = {
    api: {
        baseUrl: 'http://localhost:5000',
        endpoints: {
            chat: '/chat',
            progress: '/progress',
            history: '/history'
        }
    },
    model: {
        default: 'gpt-3.5-turbo',
        maxTokens: 1024,
        temperature: 0.7
    },
    ui: {
        animationDuration: 300,
        messageDelay: 500
    }
};

// Access configuration
console.log(TutorBotConfig.model.default);
                

# Backend config - config.py
import os
from openai import OpenAI

class Config:
    OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
    DEFAULT_MODEL = 'gpt-3.5-turbo'
    DEFAULT_MAX_TOKENS = 1024
    DEFAULT_TEMPERATURE = 0.7
    
    client = OpenAI(api_key=OPENAI_API_KEY) if OPENAI_API_KEY else None
                

🔗 OpenAI API Integration

OpenAI API Integration

The application integrates with OpenAI's GPT API for advanced educational AI. The backend uses Python Flask to handle API calls, while the frontend uses JavaScript for user interactions and response rendering.

Available APIs & Technologies

API/Technology	Type	Description
OpenAI GPT API	AI API	Advanced educational AI and tutoring
Flask REST API	Backend	Python Flask server for API endpoints
LocalStorage	Browser API	Store settings and conversation history
Web Speech API	Browser API	Voice input/output (optional feature)

Backend API Endpoints

# Flask Backend - app.py
@app.route('/chat', methods=['POST'])
def chat():
    data = request.json
    response = client.chat.completions.create(
        model=data.get('model', 'gpt-3.5-turbo'),
        messages=[{"role": "user", "content": data['message']}],
        max_tokens=data.get('max_tokens', 1024),
        temperature=data.get('temperature', 0.7)
    )
    return jsonify({
        'response': response.choices[0].message.content,
        'tokens_used': response.usage.total_tokens,
        'model': response.model
    })

@app.route('/progress', methods=['GET'])
def progress():
    return jsonify({
        'status': 'healthy',
        'openai_configured': bool(os.getenv('OPENAI_API_KEY'))
    })

@app.route('/history', methods=['GET'])
def history():
    return jsonify({
        'history': []
    })
                

// Frontend JavaScript - API Integration
async function sendMessage(message) {
    try {
        const response = await fetch('http://localhost:5000/chat', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({
                message: message,
                subject: 'General',
                difficulty: 'Intermediate',
                language: 'en'
            })
        });
        
        if (!response.ok) {
            throw new Error('API request failed');
        }
        
        const data = await response.json();
        return data.response;
    } catch (error) {
        console.error('Error:', error);
        return 'Error: ' + error.message;
    }
}
                

Browser Compatibility

// Check OpenAI API Connection
async function checkHealth() {
    try {
        const response = await fetch('http://localhost:5000');
        const data = await response.json();
        console.log('Server Status:', data.status);
        console.log('API Configured:', data.openai_configured);
        return data.openai_configured;
    } catch (error) {
        console.error('Health check failed:', error);
        return false;
    }
}

// Recommended setup:
// - Backend: Python 3.8+ with Flask
// - Frontend: Modern browsers (Chrome, Edge, Safari, Firefox)
// - Voice Features: Chrome/Edge for Web Speech API support
                

⚙️ Configuration

Configuration in this application is handled through environment variables and settings files:

Environment Variables

Create a .env file in the project root (copy from env.example):

# .env file
OPENAI_API_KEY=sk-your-openai-api-key-here
FLASK_ENV=development
PORT=5000
                

Note: Get your API key from OpenAI Platform. Never commit your .env file to version control.

Python Configuration (config.py)

The config.py file contains configuration settings:

# config.py
import os
from openai import OpenAI

class Config:
    OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
    DEFAULT_MODEL = 'gpt-3.5-turbo'
    DEFAULT_MAX_TOKENS = 1024
    DEFAULT_TEMPERATURE = 0.7
    
    # Initialize OpenAI client
    client = OpenAI(api_key=OPENAI_API_KEY) if OPENAI_API_KEY else None
                

Frontend Configuration

Edit script.js to configure API endpoint:

// script.js
const API_BASE_URL = 'http://localhost:5000';
const DEFAULT_MODEL = 'gpt-3.5-turbo';
const DEFAULT_MAX_TOKENS = 1024;
const DEFAULT_TEMPERATURE = 0.7;
                

Browser LocalStorage Settings

User settings are automatically saved to browser's local storage:

// Settings are saved automatically
localStorage.setItem('tutorBotSettings', JSON.stringify({
    model: 'gpt-3.5-turbo',
    maxTokens: 1024,
    temperature: 0.7,
    subject: 'General',
    difficulty: 'Intermediate',
    language: 'en'
}));

// Load settings
const settings = JSON.parse(localStorage.getItem('tutorBotSettings'));
                

Runtime Configuration

Configure settings through the web interface:

Subject: Select subject (Mathematics, Science, History, etc.)
Difficulty: Choose difficulty level (Beginner, Intermediate, Advanced)
Language: Select language for responses (10+ languages supported)
Voice Input: Enable/disable voice input functionality
File Upload: Upload documents for analysis

All settings are saved automatically and persist across browser sessions.

📁 Project Structure

The Educational Tutor Bot follows a clean, organized structure for easy navigation and maintenance.

educational-tutor-bot/
├── educational-tutor-bot/
│   ├── templates/
│   │   └── index.html      # Main HTML interface
│   ├── static/
│   │   ├── css/
│   │   │   └── style.css   # Modern styling
│   │   └── js/
│   │       └── script.js   # Frontend logic
│   ├── utils/
│   │   ├── ai_helper.py    # OpenAI API integration
│   │   └── database.py     # Database management
│   ├── app.py              # Flask backend server
│   ├── config.py           # Configuration settings
│   ├── run.py              # Application runner
│   └── requirements.txt    # Python dependencies
├── demo/
│   ├── index.html          # Documentation page
│   ├── demo.html           # Interactive demo
│   ├── style.css           # Demo styling
│   └── script.js           # Demo scripts
├── .env                    # Environment variables
└── README.md               # Project documentation

📄 Frontend Files

Location: educational-tutor-bot/templates/ and educational-tutor-bot/static/

templates/index.html - Main UI interface with chat
static/css/style.css - Modern gradient styling
static/js/script.js - JavaScript functionality

🐍 Backend Files

Location: educational-tutor-bot/

app.py - Flask server & API endpoints
config.py - Configuration settings
run.py - Application entry point
utils/ai_helper.py - OpenAI API integration
utils/database.py - SQLite database operations

⚙️ Configuration

Setup: Configure these files for your environment

.env - Environment variables (API keys)
requirements.txt - Python dependencies
config.py - Application configuration

🔧 Troubleshooting

API Key Issues

Ensure your .env file contains a valid OPENAI_API_KEY starting with sk-
Check that the API key is correctly formatted and not expired
Verify your API key has sufficient credits in OpenAI Platform
Make sure the .env file is in the project root directory
Restart the Flask server after updating the API key

Flask Server Issues

Server not starting: Check Python version (3.8+), verify dependencies installed with pip install -r requirements.txt
Port 5000 in use: Change port in .env file or stop other applications using port 5000
Import errors: Ensure virtual environment is activated, reinstall dependencies
CORS errors: Verify Flask-CORS is installed and enabled in app.py
Connection refused: Check firewall settings, ensure server is running on correct port

Frontend Connection Issues

Failed to fetch: Ensure Flask server is running, check API_BASE_URL in script.js
CORS errors: Make sure Flask-CORS is installed and configured in backend
Server offline indicator: Check server status at http://localhost:5000
Port mismatch: Verify frontend API_BASE_URL matches backend port

Common Issues

API key not found: Create .env file from env.example and add your API key
Module not found: Install dependencies with pip install -r requirements.txt
Response errors: Check API key validity, verify credits, check OpenAI API status
File upload not working: Check file size limits, supported formats, and Flask file handling configuration
Streaming not working: Verify streaming is enabled in settings and backend supports streaming

📋 Requirements

Backend Requirements:
- Python 3.8 or higher
- Flask web framework
- OpenAI Python SDK
- Flask-CORS for CORS support

Frontend Requirements:
- Modern Web Browser (Chrome, Edge, Safari, Firefox)
- JavaScript ES6+ support
- LocalStorage API
- Web Speech API (for voice features, optional)

API Requirements:
- OpenAI API Key (get from platform.openai.com)
- Active internet connection for API calls

Python Dependencies (see requirements.txt):
- openai
- flask
- flask-cors
- python-dotenv

Optional Dependencies:
- Voice features require Web Speech API (Chrome/Edge recommended)
- File upload requires modern browser with File API support
                

Browser Compatibility: Chrome, Edge, Safari, or Firefox (Chrome/Edge recommended for voice features).

Python Version: Python 3.8 or higher required for backend server.

Internet Connection: Required for OpenAI API calls and CDN resources.

🎯 Use Cases

💻 Code Assistance

Get help with coding, debugging, and programming questions

📚 Education & Learning

Learn new concepts, get explanations, and study assistance

📊 Content Analysis

Analyze documents, summarize text, and extract key information

🧮 Problem Solving

Solve complex problems, math equations, and reasoning tasks

✍️ Content Creation

Writing assistance, creative content, and text generation

🎓 Personalized Tutoring

Get personalized learning recommendations and adaptive tutoring based on your progress

📎 Document Analysis

Upload and analyze images, PDFs, and documents

🌐 Web Integration

Integrate OpenAI API into educational web applications and services

💬 Support

For support, questions, or more projects:

Website: https://rskworld.in
Email: help@rskworld.in
Phone: +91 93305 39277

📄 License

This project is provided as-is for educational and development purposes.

MIT License - See LICENSE file for details.