README_LINUX.md

Mintoak RAG Assistant - Linux Setup Guide

This guide describes how to set up and run the Mintoak RAG Knowledge Assistant locally on a Linux system (supporting both CPU and CUDA-enabled NVIDIA GPUs).

---

Prerequisites

1. OS: Ubuntu 20.04/22.04 LTS or any modern Linux distribution.
2. Python: Python 3.9, 3.10, or 3.11 installed. (Check with python3 --version).
3. C++ Compiler: ChromaDB requires compilation tools. Install build-essential:

   sudo apt-get update
   sudo apt-get install -y build-essential python3-dev git-lfs
   git lfs install
   

---

1. Environment Setup

It is highly recommended to use a virtual environment:

# Create a virtual environment named 'rag-env'
python3 -m venv rag-env

# Activate the virtual environment
source rag-env/bin/activate

# Upgrade pip
pip install --upgrade pip

---

2. Installation of Dependencies

Install the requirements from requirements.txt.

• If you have an NVIDIA GPU with CUDA installed, PyTorch will automatically utilize CUDA.
• If you are running on CPU, PyTorch will run in CPU-only mode.

# Install core dependencies (Flask, Transformers, PyTorch, ChromaDB, etc.)
pip install -r requirements.txt

---

3. Running the Assistant

On Linux, the assistant runs using the PyTorch-based Transformers framework (this is the same setup deployed on Hugging Face Spaces):

# Ensure your environment is active
source rag-env/bin/activate

# Start the Flask app
python3 app.py

• Once started, open http://localhost:7860 in your browser.
• The local vector database will automatically populate with 900+ chunks from mintoak_chunks.json on first run.

---

Troubleshooting

• CUDA Out of Memory: If your GPU has limited VRAM and you encounter memory issues, you can force CPU execution by running:

  export CUDA_VISIBLE_DEVICES=""
  python3 app.py
  

• ChromaDB SQLite Issues: ChromaDB requires a modern SQLite3 version. If your system's SQLite3 is outdated:

  pip install pysqlite3-binary
  

  Then append the following to the top of app.py:

  __import__('pysqlite3')
  import sys
  sys.modules['sqlite3'] = sys.modules.pop('pysqlite3')
  

• Rebuilding the DB: If you modify the knowledge base JSON files and need to force-reload the database, delete the local DB cache folder:

  rm -rf data/mintoak/chroma_db
  

  The app will rebuild the vector database on the next launch.