Open TutorAI 👋

OpenTutorAI-CE (Community Edition) is an open-source project designed to provide an educational and collaborative AI-powered platform. This public edition is the foundation for a proprietary Enterprise Edition (EE) and is built to encourage community contributions.

[!TIP]

Looking for a Support? – Speak with our support Team Today!

Get enhanced capabilities, including custom theming and branding, Service Level Agreement (SLA) support, Long-Term Support (LTS) versions, and more!

For more information, be sure to check out our Open TutorAI Documentation.

⭐ Key Features of Open TutorAI

Open TutorAI-CE is packed with powerful features designed for educational and collaborative AI experiences. Here's what makes it stand out:

• 🚀 Effortless Setup with Docker Set up your environment in minutes using Docker with support for :ollama and :cuda tagged images, ensuring a streamlined and hassle-free deployment.

• 🤖 Ollama & OpenAI API Compatibility Easily integrate OpenAI-compatible APIs for flexible conversations. Customize the API endpoint to connect with services like LMStudio, GroqCloud, Mistral, OpenRouter, and more—alongside local Ollama models.

• 🛡️ Granular Permissions & User Groups Admins can define detailed roles and permissions, allowing for secure, customized user experiences while promoting accountability and collaboration.

• 🧑‍💻 Responsive & Mobile-Optimized Design Enjoy a smooth user experience across desktops, laptops, and mobile devices with a fully responsive interface.

• 📱 Progressive Web App (PWA) Support Install Open TutorAI on your mobile device for an app-like experience, including offline mode on localhost and full access to core functionality.

• 🎤📹 Voice, Video & Avatar Discussion Mode Interact hands-free using integrated voice and video calls, or dive into an engaging experience with our avatar-powered discussion mode—a lifelike conversational interface that brings your AI to life.

• 🧑‍🏫 Personalized Learning Experience Open TutorAI is purpose-built for education:

  • 🎓 Customize learning support to meet individual learner needs.
  • 🧠 Generate a personalized LLM, optionally paired with a user-selected avatar, tailored to each learner's style, personality, or curriculum.

• 🛠️ Model Builder: Easily create Ollama models. Create and add custom characters/agents, customize chat elements, and import models effortlessly.

• 📚 Local RAG Integration for Educational Content Empower learners and educators with Retrieval-Augmented Generation (RAG) tailored for education. Seamlessly integrate textbooks, lecture notes, assignments, and research papers into the chat experience. Students can load documents directly into the conversation or access classroom resources from their document library using the # command—enabling context-aware tutoring, assignment help, and in-depth discussion of study material.

• 🔍 Educational Web Search for RAG Enhance learning with real-time web search integration. Students and educators can perform targeted research using providers like Google PSE, SearXNG, Brave, DuckDuckGo, and more—right from the chat. The search results are automatically injected into the conversation, enabling fact-checking, discovery of up-to-date information, and exploration of external academic resources without leaving the tutoring environment.

• 🌐 Web Browsing Capability: Seamlessly integrate websites into your chat experience using the # command followed by a URL. This feature allows you to incorporate web content directly into your conversations, enhancing the richness and depth of your interactions.

• 🎨 Image Generation Integration: Seamlessly incorporate image generation capabilities using options such as AUTOMATIC1111 API or ComfyUI (local), and OpenAI's DALL-E (external), enriching your chat experience with dynamic visual content.

• ⚙️ Many Models Conversations: Effortlessly engage with various models simultaneously, harnessing their unique strengths for optimal responses. Enhance your experience by leveraging a diverse set of models in parallel.

• 🔐 Role-Based Access Control (RBAC): Ensure secure access with restricted permissions; only authorized individuals can access your Ollama, and exclusive model creation/pulling rights are reserved for administrators.

• 🌐🌍 Multilingual Support: Experience Open TutorAI in your preferred language with our internationalization (i18n) support. Join us in expanding our supported languages! We're actively seeking contributors!

• 🌟 Continuous Updates: We are committed to improving Open TutorAI with regular updates, fixes, and new features.

Want to learn more about Open TutorAI's features? Check out our Open TutorAI documentation for a comprehensive overview!

🔗 Also Check Out Open TutorAI Community!

Don't forget to explore our sibling project, Open TutorAI Community, where you can discover, download, and explore customized Modelfiles. Open TutorAI Community offers a wide range of exciting possibilities for enhancing your chat interactions with Open TutorAI! 🚀

🗂️ Project Structure

open-tutor-ai-CE/
├── main.py                    ← Python entry point (uvicorn)
│
├── ── Application Domains ───────────────────────────────────────────────
├── accounts/                  ← Auth, users, roles, permissions
├── learning/                  ← Learners, teachers, classrooms, courses
│   ├── sessions/              ← Chat sessions, tags, sharing, search
│   └── supports/              ← Personalized tutoring supports
├── ai/                        ← LLM, providers, RAG, media, memory, tools
│   ├── llm/                   ← LLM schemas, service, transports
│   ├── model_catalog/         ← Model overlays/catalog
│   ├── providers/             ← OpenAI-compatible + Ollama providers
│   ├── retrieval/             ← RAG pipeline and knowledge bases
│   └── media/                 ← Audio (TTS/STT) + image generation
├── content/                   ← Files, uploads, learning resources
│   ├── files/                 ← User-owned files and extracted content
│   └── resources/             ← Learning resources not tied to RAG
├── governance/                ← HITL governance and LLM response evaluation
│   └── self_regulation/       ← Self-regulation feedback domain
├── system/                    ← App-level configs and bootstrap services
│   ├── configs/               ← Runtime app configuration store
│   └── app/                   ← App info/bootstrap services
│
├── ── Gateway & Infrastructure ──────────────────────────────────────────
├── gateway/                   ← Transport layer
│   ├── http/                  ← FastAPI app, dependencies, routers/
│   └── realtime/              ← Socket.IO ASGI (/realtime/socket.io)
├── data/                      ← ORM models, DB engine, base repository
├── config/                    ← App settings & constants
├── common/                    ← Shared utilities (exceptions, logging)
├── tests/                     ← Pytest suite
│
├── ── Frontend ──────────────────────────────────────────────────────────
├── ui/                        ← SvelteKit application
│   ├── src/lib/apis/          ← API clients (one folder per domain)
│   ├── src/lib/components/    ← Reusable Svelte components
│   ├── src/lib/i18n/          ← Translations (AR / FR / EN)
│   ├── src/routes/            ← File-based routing
│   ├── static/                ← Assets (avatars, images, audio)
│   └── cypress/               ← E2E tests
│
├── ── DevOps ────────────────────────────────────────────────────────────
├── devops/
│   ├── docker/                ← Dockerfiles + Docker Compose overlays
│   └── scripts/               ← Dev & ops shell scripts
│
├── ── Project ───────────────────────────────────────────────────────────
├── docs/                      ← Documentation
├── kubernetes/                ← Helm charts
├── .github/workflows/         ← CI/CD
└── var/                       ← Runtime only, gitignored (DB, uploads, vector_db)

Full structure with annotations: MIGRATION.md

OpenWebUI and Hermes are used as design references only. OpenTutorAI keeps its own domain names and has no runtime dependency on either project.

How to Install 🚀

Below is a list of essential steps and resources to help you get started, manage, and develop with Open TutorAI.

🛠️ Setup Guide — Local Development (without Docker)

Use this path when you want hot-reload for active development or contribution.

Requirements: Python 3.11–3.12 · Node.js 18.13–22.x

1. Fork and Clone the Repository

   • Go to GitHub Repository
   • Click on Fork, then clone your forked repo:

     git clone https://github.com/YOUR_USERNAME/open-tutor-ai-CE.git
     cd open-tutor-ai-CE

2. Python Application Setup

   • Create and activate a Python environment (conda or venv):

     # conda
     conda create -n tutorai-env python=3.11
     conda activate tutorai-env
     
     # or plain venv
     python3 -m venv .venv && source .venv/bin/activate

   • Install the required packages:

     pip install -r requirements.txt

   • Copy and configure environment variables:

     cp .env.example .env
     # The defaults in .env.example work for local dev (DEBUG=true).
     # No changes needed unless you use an external API or want production mode.

   • Start the Python API with hot-reload (available at http://localhost:8080):

     uvicorn main:app --reload --port 8080

     Or use the provided convenience script:

     chmod +x devops/scripts/dev.sh && ./devops/scripts/dev.sh

   • Interactive API docs: http://localhost:8080/docs

3. Frontend Setup (in a second terminal)

   • Navigate to the ui/ folder:

     cd ui
     npm install
     npm run dev        # dev server with hot-reload at http://localhost:5173

4. Ollama (optional — for local models)

   • Install from ollama.com, then:

     ollama pull llama3.2

   • Verify OLLAMA_BASE_URL=http://localhost:11434 is set in your .env.

5. First login

   • Open http://localhost:5173 and create an account.
   • The first account registered becomes the administrator.

6. Run tests (no external services required)

   pytest -q

🐳 Docker & Docker Compose Setup (Recommended)

For a hassle-free setup without installing Python or Node.js, use Docker. A single container serves both the Python API and the built frontend.

Prerequisites

1. Docker + Docker Compose from docker.com
2. Git for cloning
3. At least 8 GB RAM recommended for AI models

Step 1: Clone the Repository

git clone https://github.com/Open-TutorAi/open-tutor-ai-CE.git
cd open-tutor-ai-CE

Step 2: Set Up Environment Variables

cp .env.example .env

For production, replace the placeholder SECRET_KEY in your .env with a randomly generated value:

# macOS / Linux — replaces the existing SECRET_KEY line in-place
sed -i.bak "s/^SECRET_KEY=.*/SECRET_KEY=$(openssl rand -hex 32)/" .env && rm .env.bak

For local development, the defaults in .env.example work as-is (DEBUG=true bypasses the key check).

Step 3: Start the Stack

With Ollama bundled (recommended for local models):

docker compose --env-file .env -f devops/docker/docker-compose.yaml up --build

This starts:

• open-tutorai — Python API + frontend at http://localhost:8080
• ollama — local model server at http://localhost:11434

Without Ollama (use an external OpenAI-compatible API):

docker compose --env-file .env -f devops/docker/docker-compose.yaml up --build open-tutorai

Set OPENAI_API_BASE_URL and OPENAI_API_KEY in .env.

Then in another terminal, you can also start Ollama separately:

chmod +x devops/scripts/run-ollama-docker.sh
./devops/scripts/run-ollama-docker.sh

Step 4: Download AI Models (if using Ollama)

docker exec -it ollama ollama pull llama3.2

Verify the model is installed:

docker exec -it ollama ollama list

If the Python API was already running before the model was pulled, restart it:

docker compose --env-file .env -f devops/docker/docker-compose.yaml restart open-tutorai

Step 5: Access the Application

Open http://localhost:8080 in your browser. The first account created becomes the administrator.

Stopping the Services

docker compose --env-file .env -f devops/docker/docker-compose.yaml down

# Full reset (removes all data volumes)
docker compose --env-file .env -f devops/docker/docker-compose.yaml down -v

GPU Support

# NVIDIA GPU
docker compose --env-file .env -f devops/docker/docker-compose.yaml -f devops/docker/docker-compose.gpu.yaml up --build

# AMD GPU
docker compose --env-file .env -f devops/docker/docker-compose.yaml -f devops/docker/docker-compose.amdgpu.yaml up --build

⚙️ Environment Variables Reference

Troubleshooting

Encountering connection issues? See TROUBLESHOOTING.md for common fixes, or visit our Open TutorAI Documentation. For further assistance, join the Open TutorAI Discord.

🌟 What's Next?

Discover upcoming features on our roadmap in the Open TutorAI Documentation.

📜 License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details. 📄

💬 Support

If you have any questions, suggestions, or need assistance, please open an issue or join our Open TutorAI Discord community to connect with us! 🤝

Star History

Founded by Mohamed El Hajji and built by the community - Let's make Open TutorAI even more amazing together! 💪