Skip to content

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

45 Commits

Folders and files

Repository files navigation

Adaptive Learning Platform - AI for Bharat Hackathon

AI-Driven Adaptive Learning Platform for AI for Bharat Hackathon

📖 Project Overview

Ariveon is an intelligent adaptive learning platform that leverages AI to provide personalized education experiences. The platform analyzes student knowledge gaps, generates customized learning roadmaps, provides interactive AI tutoring, and adapts practice materials based on individual performance. Built with a modern tech stack, it combines a React-based frontend with a Node.js backend and Python-powered AI agents using AWS Bedrock (Llama 3).

Key Features

  • 🗺️ Personalized Learning Roadmaps - AI-generated learning paths tailored to individual goals and knowledge levels
  • 🤖 Adaptive AI Tutoring - Interactive tutoring sessions that adjust to student responses and learning pace
  • 📝 Intelligent Practice System - Dynamic question generation based on difficulty level and topic mastery
  • 📊 Progress Tracking - Comprehensive analytics showing mastery levels, strengths, and areas for improvement
  • 🔍 Mistake Analysis - Deep dive into errors with personalized remediation strategies
  • ⚙️ Customizable Workflows - Create and manage learning workflows using a visual builder

🏗️ Project Structure

project/
├── backend/                    # Backend services
│   ├── agents.py              # FastAPI server (Python) for AI agents
│   ├── server.ts              # Express/Next.js API server (TypeScript)
│   ├── package.json           # Node.js dependencies
│   └── requirements.txt       # Python dependencies
├── adaptive-learning-platform/ # Frontend Next.js application
│   └── package.json           # Frontend dependencies
├── n8n/                       # Workflow definitions (legacy)
└── requirements.txt           # Root Python dependencies

🎨 Component Architecture

Frontend: adaptive-learning-platform/

The Next.js 16 frontend application provides a modern, responsive interface for the adaptive learning platform. Built with React 19 and TypeScript, it offers a seamless user experience with real-time updates and interactive components.

Core Features:

🏠 Landing Page & Authentication

  • Modern landing page showcasing platform features
  • Secure registration and login system with JWT authentication
  • Protected routes ensuring authorized access to user content

📊 Dashboard

  • Personalized learning overview with progress metrics
  • Quick access to active lessons, practice sessions, and workflows
  • Interactive onboarding spotlight for new users
  • Customizable sidebar navigation

🗺️ Learning Module (/learn/[subtopic_id])

  • AI-generated personalized learning roadmaps based on goals and current knowledge
  • Visual representation of learning paths with subtopics and dependencies
  • Topic recommendations with difficulty levels and estimated time
  • Direct integration with tutor for interactive learning sessions

🎓 Tutor System (/lessons)

  • Real-time conversational AI tutoring with natural language processing
  • Adaptive responses based on student understanding and learning pace
  • Context-aware explanations with examples and clarifications
  • Support for multiple learning styles (visual, auditory, kinesthetic)

✍️ Practice System (/practice)

  • Dynamic quiz generation tailored to current mastery level
  • Multiple question types (multiple choice, short answer, problem-solving)
  • Immediate feedback on submitted answers with detailed explanations
  • Practice history tracking with performance analytics
  • Mistake analysis modal showing error patterns and remediation suggestions

📈 Progress Tracking (/progress)

  • Comprehensive progress dashboard with subject mastery levels
  • Strength and weakness identification across topics
  • Historical performance trends with visual charts
  • Update progress dialog for manual adjustments
  • Export and share progress reports

🔧 Remediation System (/remediation/[subtopic_id])

  • Targeted learning materials for identified weak areas
  • Customized exercises focusing on specific mistakes
  • Step-by-step guidance for concept reinforcement
  • Integration with practice system for continuous improvement

⚙️ Settings & Workflows (/settings, /workflows)

  • User profile and learning preference management
  • Visual workflow builder for creating custom learning sequences
  • Template library for common learning patterns
  • Workflow execution and monitoring

Technical Highlights:

  • State Management: Zustand stores for global state (auth, progress, practice)
  • Form Handling: React Hook Form with Zod validation for type-safe forms
  • UI Components: Shadcn/ui (Radix UI primitives) with Tailwind CSS for consistent design
  • API Integration: Type-safe API client with error handling and retry logic
  • Theming: Dark/light mode support with theme provider
  • Responsive Design: Mobile-first approach ensuring usability across devices

Backend: backend/server.ts

The TypeScript/Express backend serves as the main API server and orchestration layer for the platform. It handles authentication, manages the SQLite database, coordinates with the AI agents service, and provides RESTful endpoints for all frontend operations.

Core Responsibilities:

🔐 Authentication & Authorization

  • JWT-based authentication system with secure token generation
  • Password hashing with bcrypt
  • Session management and refresh token support
  • Protected route middleware for secure API access
  • User profile management and preferences storage

📡 API Layer Routes organized by feature domain:

  • Auth Routes (/api/auth/*):

    • User registration and login
    • Profile retrieval and updates
    • Password reset and email verification

  • Workflow Routes (/api/workflows/*):

    • Create, read, update, delete workflow definitions
    • Execute workflows with parameter validation
    • Template management for reusable workflows
    • Track workflow execution history

  • Tutor Routes (/api/tutor/*):

    • Initialize tutoring sessions with context
    • Send messages and receive AI tutor responses
    • Retrieve session history and metadata
    • Coordinate with agents.py for prompt generation

  • Practice Routes (/api/practice/*):

    • Generate practice questions based on topic and difficulty
    • Submit answers for evaluation
    • Retrieve practice history and analytics
    • Coordinate with agents.py for question generation and evaluation

  • Progress Routes (/api/progress/*):

    • Track user progress across topics and subtopics
    • Calculate mastery levels and skill gaps
    • Provide analytics and insights on learning trends
    • Update progress based on practice performance

  • Remediation Routes (/api/remediation/*):

    • Identify weak areas requiring additional focus
    • Generate targeted remediation content
    • Track remediation progress and effectiveness
    • Coordinate with agents.py for mistake analysis

💾 Database Management

  • SQLite3 (Better-SQLite3) - Current lightweight database for development and prototype
    • Fast, synchronous database operations
    • Zero configuration, file-based storage
    • Perfect for development and small-scale deployments
  • Amazon RDS (PostgreSQL/MySQL) - Planned for production deployment
    • Scalable managed database service
    • Automated backups and high availability
    • Multi-user concurrent access support
    • Migration path from SQLite planned for production
  • Schema management with TypeScript types for type safety
  • Migration system for database versioning
  • Seed data for development and testing

Database Models:

  • users - User accounts and authentication
  • learning_preferences - Personalized learning settings
  • progress - User progress across topics
  • practice_sessions - Practice attempt records
  • workflows - Workflow definitions and templates
  • workflow_executions - Execution history and results

🤖 AI Integration

  • Proxy layer for agents.py communication
  • Request/response transformation and validation
  • Error handling and fallback strategies
  • Caching for frequently requested AI generations

🛡️ Middleware

  • Error handling middleware with structured error responses
  • Request validation using Zod schemas
  • Logging middleware for monitoring and debugging
  • CORS configuration for frontend integration

Technical Highlights:

  • TypeScript: Full type safety with interfaces and type guards
  • Express: Robust routing and middleware system
  • SQLite: Lightweight database with Better-SQLite3 for performance
  • LangChain: AI orchestration framework for complex workflows
  • Winston: Structured logging for debugging and monitoring
  • Dotenv: Environment configuration management

AI Layer: backend/agents.py

The FastAPI Python service provides the intelligence layer of the platform, powered by AWS Bedrock's Llama 3 70B model. It replicates the functionality of five specialized AI agent nodes, each responsible for a critical aspect of the adaptive learning experience.

AI Agent Endpoints:

1️⃣ Roadmap Generator (POST /gen-found)

  • Purpose: Generate personalized learning roadmaps
  • Input: User goals, current knowledge level, learning preferences, time constraints
  • Processing:
    • Analyzes learning objectives and breaks them into subtopics
    • Creates dependency graphs for sequential learning
    • Estimates time requirements and difficulty levels
    • Considers user's learning style and pace preferences
  • Output: Structured learning roadmap with topics, subtopics, dependencies, and recommendations

2️⃣ Tutor Prompt Generator (POST /tutor-prompt-generator)

  • Purpose: Generate context-aware tutoring prompts
  • Input: Topic, student's current understanding, conversation history, learning style
  • Processing:
    • Creates adaptive system prompts for the AI tutor
    • Tailors explanation style to student's learning preferences
    • Incorporates Socratic questioning for deeper understanding
    • Adjusts complexity based on student responses
  • Output: Optimized prompts that guide the tutor's responses

3️⃣ Practice Generator (POST /practice-generator)

  • Purpose: Generate practice questions and exercises
  • Input: Topic, subtopic, difficulty level, question type, quantity
  • Processing:
    • Creates questions aligned with learning objectives
    • Varies question formats (multiple choice, short answer, problem-solving)
    • Generates correct answers and plausible distractors
    • Ensures progressive difficulty and concept coverage
  • Output: Array of practice questions with answers and metadata

4️⃣ Answer Evaluator (POST /evaluator)

  • Purpose: Evaluate student answers and provide feedback
  • Input: Question, student answer, correct answer, evaluation criteria
  • Processing:
    • Assesses correctness with nuanced scoring (not just right/wrong)
    • Identifies partial understanding and misconceptions
    • Generates detailed feedback explaining errors
    • Provides hints for improvement without giving away answers
  • Output: Score, correctness assessment, detailed feedback, learning insights

5️⃣ Mistake Analyzer (POST /mistake-analysis)

  • Purpose: Analyze patterns in student errors and suggest remediation
  • Input: Collection of incorrect answers, question contexts, student performance data
  • Processing:
    • Identifies recurring error patterns and knowledge gaps
    • Diagnoses root causes of misunderstanding (conceptual, procedural, etc.)
    • Generates targeted remediation strategies
    • Recommends specific topics for review and practice
  • Output: Mistake analysis report with remediation roadmap

Technical Implementation:

🤖 LLM Backend: AWS Bedrock

  • Service: AWS Bedrock - Fully managed foundation model service
  • Model: meta.llama3-70b-instruct-v1:0 (Meta Llama 3 70B Instruct)
  • Region: us-east-1
  • SDK: boto3 (mirrors AWS CLI bedrock-runtime converse)
  • Benefits:
    • No infrastructure management required
    • Pay-per-use pricing model
    • Serverless and auto-scaling
    • Enterprise-grade security and compliance
  • Configuration:
    • Max tokens: 2048 (configurable per endpoint)
    • Temperature: 0.7 (balanced creativity/consistency)
    • Streaming support for real-time responses

⚙️ API Features

  • FastAPI Framework: High-performance async API with automatic OpenAPI documentation
  • CORS Support: Configured for frontend and backend integration
  • Error Handling: Comprehensive exception handling with informative error messages
  • Request Validation: Pydantic models for type-safe request/response handling
  • Logging: Detailed logging for debugging and monitoring AI behavior

🔧 Prompt Engineering Each endpoint uses carefully crafted system prompts that:

  • Define the AI's role and expertise level
  • Set output format expectations (JSON, structured text)
  • Include few-shot examples for consistent responses
  • Implement safety guardrails and content filtering
  • Optimize for education-specific use cases

📊 Response Processing

  • JSON parsing and validation of LLM outputs
  • Fallback mechanisms for malformed responses
  • Response caching for common queries
  • Token usage tracking and optimization

Infrastructure Requirements:

  • Python 3.9+ with FastAPI and Boto3
  • AWS Credentials with Bedrock access permissions
  • AWS Bedrock enabled with Llama 3 model access in us-east-1
  • Environment Variables: AWS keys, model ID, region configuration

🛠️ Technology Stack

Backend

Python Stack:

  • FastAPI - Modern Python web framework
  • Uvicorn - ASGI server
  • Boto3 - AWS SDK for Bedrock LLM integration

Node.js/TypeScript Stack:

  • Node.js v18+
  • TypeScript - Type-safe JavaScript
  • Express - Web server framework
  • Next.js - React framework with API routes
  • Better-SQLite3 - Database (development)
  • LangChain - AI orchestration
  • JWT - Authentication

Frontend

  • Next.js 16 - React framework
  • React 19 - UI library
  • TypeScript - Type safety
  • Tailwind CSS 4 - Styling
  • Radix UI - Component library
  • Zustand - State management
  • React Hook Form - Form handling
  • Zod - Schema validation

Cloud Infrastructure & Deployment

AWS Services:

  • AWS Bedrock - Managed AI/ML model deployment for Llama 3 70B
    • Serverless LLM inference
    • No model hosting infrastructure required
    • Auto-scaling and high availability
  • Amazon Lightsail - Production deployment platform
    • Cost-effective VPS for hosting frontend and backend
    • Simple deployment with predictable pricing
    • Integrated load balancing and CDN
    • Easy scaling as user base grows
  • Amazon RDS (Future) - Managed relational database
    • PostgreSQL or MySQL for production
    • Automated backups and maintenance
    • High availability with Multi-AZ deployment
    • Migration from SQLite planned for scale

Current Setup:

  • Development: SQLite (file-based, zero configuration)
  • Production (Planned): Amazon Lightsail + RDS + Bedrock

📋 Prerequisites

  • Node.js >= 18.0.0
  • Python >= 3.9
  • pnpm (recommended for frontend) or npm
  • AWS Credentials (for Bedrock access)

🚀 Installation

1. Clone the Repository

git clone <repository-url>
cd project

2. Install Python Dependencies

# Install Python packages for agents.py
pip install -r requirements.txt

# Or if using a virtual environment (recommended):
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Install Backend Dependencies

cd backend
npm install

4. Install Frontend Dependencies

cd adaptive-learning-platform
pnpm install
# or: npm install

5. Configure Environment Variables

Backend Environment (.env)

Create backend/.env:

# AWS Configuration (for agents.py)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1

# Agents API Configuration
AGENTS_API_URL=http://localhost:8000

# Google Gemini API (for TypeScript backend)
GEMINI_API_KEY=your_gemini_api_key

# Session Configuration
SESSION_SECRET=your_session_secret_here

# Optional: Model Configuration
GEMINI_MODEL=gemini-2.5-flash
MAX_TOKENS=8192
TEMPERATURE=0.7

# Server Configuration
PORT=3000
NODE_ENV=development

AWS Credentials Setup

For agents.py to access AWS Bedrock:

# Option 1: Configure AWS CLI
aws configure

# Option 2: Set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

🏃 Running the Application

Start All Services

You'll need 3 terminal windows:

Terminal 1: Python FastAPI Server (agents.py)

cd backend
python agents.py

# Or with uvicorn directly:
uvicorn agents:app --host 0.0.0.0 --port 8000 --reload

✅ Server runs at: http://localhost:8000

Terminal 2: TypeScript Backend Server

cd backend
npm run dev

✅ Backend API runs at: http://localhost:3000

Terminal 3: Frontend Application

cd adaptive-learning-platform
pnpm dev

✅ Frontend runs at: http://localhost:3000 (or next available port)

🧪 Testing

Backend Tests

cd backend

# Run all tests
npm test

# Run agents.py integration tests
npm run test:n8n

# Run Sprint 3 integration tests
npm run test:sprint3

Database Operations

cd backend

# Initialize database
npm run db:init

# Reset database
npm run db:reset

📡 API Endpoints

Agents.py (Python FastAPI) - Port 8000

  • POST /gen-found - Generate learning roadmap
  • POST /tutor-prompt-generator - Generate tutor prompts
  • POST /practice-generator - Generate practice questions
  • POST /evaluator - Evaluate answers
  • POST /mistake-analysis - Analyze mistakes

Backend (TypeScript) - Port 3000

  • POST /api/auth/register - User registration
  • POST /api/auth/login - User login
  • GET /api/progress - Get user progress
  • POST /api/practice/generate - Generate practice
  • POST /api/practice/submit - Submit practice answers
  • GET /api/workflows - Get workflows
  • And more...

🔧 Development Scripts

Backend

npm run dev          # Start dev server with hot reload
npm run build        # Build TypeScript
npm run start        # Start production server
npm run lint         # Type check with TypeScript
npm run db:init      # Initialize database
npm run db:reset     # Reset database

Frontend

pnpm dev            # Start development server
pnpm build          # Build for production
pnpm start          # Start production server
pnpm lint           # Run ESLint

🚀 Deployment Architecture

The platform is designed for scalable cloud deployment using AWS infrastructure:

Development Environment

  • Database: SQLite (file-based, embedded)
  • Hosting: Local development servers
  • AI Models: AWS Bedrock API calls

Production Environment (AWS)

┌─────────────────────────────────────────┐
│         Amazon Lightsail VPS            │
│  ┌─────────────┐   ┌─────────────┐     │
│  │   Frontend  │   │   Backend   │     │
│  │  (Next.js)  │◄─►│ (Express +  │     │
│  │  Port 3000  │   │   FastAPI)  │     │
│  └─────────────┘   └──────┬──────┘     │
└────────────────────────────┼───────────┘
                             │
            ┌────────────────┼────────────────┐
            │                │                │
            ▼                ▼                ▼
    ┌──────────────┐  ┌──────────┐  ┌──────────────┐
    │ AWS Bedrock  │  │ Amazon   │  │ CloudWatch   │
    │ (Llama 3 70B)│  │    RDS   │  │  (Logging)   │
    │  AI Models   │  │(Future DB)│  │              │
    └──────────────┘  └──────────┘  └──────────────┘

Deployment Benefits

  • Cost-Effective: Lightsail provides predictable monthly pricing starting at $5-20/month
  • Scalable: Easy upgrade path from Lightsail to full AWS infrastructure (ECS, RDS, etc.)
  • Managed AI: No need to manage GPU servers - Bedrock handles all AI inference
  • Database Evolution: Start with SQLite, migrate to RDS as user base grows

🏆 AI for Bharat Hackathon

This project is developed for the AI for Bharat Hackathon, showcasing how artificial intelligence can democratize and personalize education in India and beyond. The platform addresses key challenges in education:

  • Personalization at Scale: AI-powered adaptive learning paths for every student
  • Accessibility: Web-based platform accessible from any device
  • Multilingual Support: Designed to support multiple Indian languages (future roadmap)
  • Affordable: Leveraging AWS Bedrock (managed AI) and Lightsail (cost-effective hosting) for economical deployment
  • Data-Driven Insights: Analytics to identify learning gaps and improve outcomes
  • Cloud-Native: Built on AWS infrastructure for reliability and scalability

📚 Documentation

🐛 Troubleshooting

Port Already in Use

If you get "port already in use" errors:

# Find process using port 8000
lsof -ti:8000 | xargs kill -9

# Find process using port 3000
lsof -ti:3000 | xargs kill -9

AWS Bedrock Access Issues

Ensure:

  1. AWS credentials are configured
  2. Your AWS account has Bedrock access enabled
  3. The model meta.llama3-70b-instruct-v1:0 is available in us-east-1

Database Issues

cd backend
npm run db:reset  # Reset and reinitialize database

📝 License

[Add your license information here]

👥 Contributors

[Add contributor information here]

🤝 Contributing

[Add contribution guidelines here]

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages