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:
   ```bash
   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:

```bash
# 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.

```bash
# 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):

```bash
# 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:
  ```bash
  export CUDA_VISIBLE_DEVICES=""
  python3 app.py
  ```
* **ChromaDB SQLite Issues**: ChromaDB requires a modern SQLite3 version. If your system's SQLite3 is outdated:
  ```bash
  pip install pysqlite3-binary
  ```
  Then append the following to the top of `app.py`:
  ```python
  __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:
  ```bash
  rm -rf data/mintoak/chroma_db
  ```
  The app will rebuild the vector database on the next launch.