ProVAI

An intelligent, RAG-powered AI tutor for education.

 

✨ Overview

ProVAI (Professor Virtual with AI) is an intelligent learning tutor designed to enhance educational experiences. It uses a Retrieval-Augmented Generation (RAG) engine to provide personalized support by interacting with teacher-provided course materials.

ProVAI helps:

• Students to master their course material through:

  • On-demand, context-aware answers grounded in their documents.
  • Automated, non-graded quizzes for effective self-assessment.

• Teachers to provide scalable, personalized support with:

  • An AI tutor that handles common student questions 24/7.
  • Privacy-preserving analytics that identify classroom-wide learning gaps.

• Educational Institutions to deploy a secure, self-hostable, and resource-efficient AI learning tool.

 

🚀 Getting Started

Note

Before you start, make sure you have Docker installed and running.

1. Clone the repository:

   git clone https://github.com/joelabreurojas/ProVAI.git
   cd ProVAI

2. Download assets:

   chmod +x ./scripts/download_assets.sh
   ./scripts/download_assets.sh

   This will download the LLM and a sample document.

3. Configure your environment:

   cp .env.template .env

   Open the .env file. The comments explain what should be set.

4. Build and run:

   docker compose watch
   

   Embedding model will be downloaded in the first run.

5. Run database migrations:

   docker compose exec api python -m alembic upgrade head

Important

The API will be available at http://localhost:8000.

Check out the OpenAPI documentation at http://localhost:8000/docs.

 

🧑‍💼 User Role Management (CLI)

The application assigns a student role to all new users by default. To promote a user to a teacher, you must use the command-line interface.

1. Ensure the user is already registered.

2. Run the script from your terminal:

   # Make sure your virtual environment is active or you are inside the Docker container
   docker compose exec app bash
   
   # Promote a user to teacher
   python -m scripts.manage_roles --email "your-email@example.com" --role "teacher"
   
   # Or demote them back to student
   python -m scripts.manage_roles --email "your-email@example.com" --role "student"

 

🛠 Tech Stack

ProVAI is built on a foundation of modern, high-performance technologies, guided by professional software engineering principles to ensure it is maintainable, testable, and scalable.

Category	Technology	Rationale
ProVAI on  feat/m3-130-132-cli-and-model-refactor [?] is 󰏗 v0.1.0 via  v22.19.0 via  v3.13.5 (provai0
❯ python -m scripts.manage_roles --email teacher@provai.com --role teacher (base)
INFO:main:Connecting to database specified in ENV_STATE='dev'...
ERROR:main:An unexpected error occurred: When initializing mapper Mapper[Invitation(invitations)], expression 'InvitationMember' failed to locate a name ('InvitationMember'). If this is a class name, consider adding this relationship() to the <class 'src.core.domain.models.invitation.Invitation'> class after both dependent classes have been defined.	Backend	FastAPI & Python 3.13
Architecture	Hexagonal (Ports & Adapters)	A clean, decoupled architecture with a central core business domain and independent api and ui adapters.
Frontend	Jinja2, Tailwind CSS, HTMX, Alpine.js	A modern, high-performance stack for server-rendered interactivity.
AI Engine	LangChain & llama-cpp	Robust orchestration with direct, efficient local model inference.
Database	SQLite & ChromaDB	Lightweight, file-based storage for the MVP, managed by SQLAlchemy and Alembic.
DevOps	Docker, tox, pytest, Ruff, Mypy	A fully containerized, quality-gated development environment with a comprehensive, multi-layered test suite.

 

🗺 Roadmap

This is a high-level overview of our development milestones, focusing on the path to our Minimum Viable Product (MVP).

Milestone 1: The Walking Skeleton (Completed)

• Establish professional project structure, tooling, and CI/CD foundation.

Milestone 2: The Core Engine (Completed)

• Implement secure, headless User Authentication.
• Integrate local LLM and Embedding models.
• Build the Document Ingestion and core RAG services.
• Implement the Chat and Message service for conversation persistence.

Milestone 3: The Minimum Viable Interface (In Progress)

• Build the UI for user interaction, login, and document upload.
• Implement "Teacher" and "Student" role-based access control.
• Deploy the complete MVP to a public platform.

Post-MVP Vision (ProVAI on  feat/m3-130-132-cli-and-model-refactor [?] is 󰏗 v0.1.0 via  v22.19.0 via  v3.13.5 (provai0 ❯ python -m scripts.manage_roles --email teacher@provai.com --role teacher (base) INFO:__main__:Connecting to database specified in ENV_STATE='dev'... ERROR:__main__:An unexpected error occurred: When initializing mapper Mapper[Invitation(invitations)], expression 'InvitationMember' failed to locate a name ('InvitationMember'). If this is a class name, consider adding this relationship() to the class after both dependent classes have been defined.Milestone g):

• Implement the Learning Support module (Quiz Generation, Roadmaps).
• Build the Teacher Analytics Dashboard for classroom insights.
• Explore advanced RAG techniques (Parent Document Retrieval, CRAG).
• Refactor the core engine into a LangGraph state machine for agentic behavior.
• ...and much more!

 

📌 Disclaimer

Warning

This is an academic project under active development.

• Always verify critical information against the source documents.
• This tool is a study aid, not a substitute for professional instruction.
• This project is provided as is, without any warranty. Use at your own risk.

 

👐 Contribute

• Found a bug? Feel free to open a new issue!
• Have a question or an idea? Join our community.

Please, read our Contribution Guidelines to take part in the project.