AI Tutor Demo

AI-powered tutor for laboratory quality control procedures (MVP Demo).

Features

• Adaptive Guidance: AI adjusts teaching level (detailed/summary/minimal) based on user experience
• RAG Integration: Retrieves relevant procedure sections from indexed documents with native pgvector search
• Real-time Chat: WebSocket-powered AI guidance during procedure execution
• Progress Tracking: Tracks user completions and applies time decay
• Modular Frontend: Clean, maintainable ES6 JavaScript architecture

Tech Stack

• Backend: FastAPI + SQLAlchemy + PostgreSQL + pgvector
• AI Model: Qwen 2.5-14B-Instruct (4-bit quantization) via LocalAI
• RAG: sentence-transformers embeddings with native pgvector similarity search
• Frontend: Modular ES6 JavaScript + HTML5 + CSS3
• Hardware: Optimized for RTX 4070 12GB

Quick Start

Prerequisites

• Ubuntu 24.04 or similar
• PostgreSQL 14+ with pgvector extension
• CUDA 12+ (for GPU support)
• Conda
• 16 CPU cores, 128GB RAM, RTX 4070 12GB (recommended)

Setup

# 1. Clone repository
git clone <repo-url>
cd tutor_demo

# 2. Create conda environment
conda env create -f environment.yml
conda activate ai-tutor

# 3. Setup PostgreSQL
sudo systemctl start postgresql
sudo -u postgres psql -c "CREATE DATABASE ai_tutor;"
sudo -u postgres psql -d ai_tutor -c "CREATE EXTENSION vector;"
sudo -u postgres psql -c "CREATE DATABASE ai_tutor_test;"
sudo -u postgres psql -d ai_tutor_test -c "CREATE EXTENSION vector;"

# 4. Initialize database and seed data
python -m app.db.init_db
python scripts/seed_db.py

# 5. Setup LocalAI (see docs/LOCALAI_SETUP.md)
cd localai
./LocalAI-linux-amd64 --config-file config.yaml

# 6. Start backend (in new terminal)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 7. Open frontend
open frontend/index.html

Demo Credentials

• Username: demo_user
• Password: demo123 (see documentation for setup)

Project Structure

app/
├── api/          # FastAPI endpoints
├── core/         # Config, security, dependencies
├── db/           # Database session
├── models/       # SQLAlchemy models
├── schemas/      # Pydantic schemas
└── services/     # Business logic
frontend/         # Web application
│   └── modules/  # Modular JavaScript
localai/          # LocalAI config
tests/            # API tests (PostgreSQL-based)
docs/             # Documentation

API Documentation

Interactive API docs: http://localhost:8000/docs

Testing

# Run tests
pytest

# With coverage
pytest --cov=app tests/

Architecture Highlights

• Async I/O: All external HTTP calls use httpx.AsyncClient (non-blocking)
• Vector Search: pgvector native similarity search (O(log N) not O(N) in Python)
• Auth Security: JWT-based authentication with WebSocket token validation
• Testing: PostgreSQL test database (pgvector-compatible)
• Frontend: Modular ES6 architecture for maintainability

License

MIT License

Copyright (c) 2026 Aram Amalietti

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in Software without restriction, including without limitation rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of Software, and to permit persons to whom Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of Software.