ENV_SETUP.md

# Environment Variables Setup

This document describes the environment variables needed to run the RAG system.

## Required Variables

### HF_TOKEN (Required)

Your Hugging Face API token for accessing the Inference API.

**How to get it:**
1. Go to [https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Click "New token"
3. Give it a name (e.g., "RAG System")
4. Select `read` permissions
5. Click "Generate"
6. Copy the token (starts with `hf_`)

**Set it:**

```bash
# Linux/Mac
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Windows (PowerShell)
$env:HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Windows (CMD)
set HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**For Hugging Face Spaces:**
- Go to Space Settings → Repository secrets
- Add secret: Name=`HF_TOKEN`, Value=your token

## Optional Variables

### HF_MODEL

The Hugging Face model to use for text generation.

**Default:** `meta-llama/Llama-3.2-3B-Instruct`

**Other options:**
- `mistralai/Mistral-7B-Instruct-v0.2`
- `meta-llama/Meta-Llama-3-8B-Instruct`

```bash
export HF_MODEL=meta-llama/Llama-3.2-3B-Instruct
```

### EMBEDDING_MODEL

The sentence transformer model for embeddings (runs locally).

**Default:** `all-MiniLM-L6-v2`

```bash
export EMBEDDING_MODEL=all-MiniLM-L6-v2
```

### CHROMA_PERSIST_DIR

Directory for ChromaDB vector database storage.

**Default:** `./chroma_db`

```bash
export CHROMA_PERSIST_DIR=./chroma_db
```

### DOCUMENTS_DIR

Directory containing source documents.

**Default:** `./documents`

```bash
export DOCUMENTS_DIR=./documents
```

### PROCESSED_DOCS_DIR

Directory for processed markdown documents.

**Default:** `./processed_docs`

```bash
export PROCESSED_DOCS_DIR=./processed_docs
```

### DEFAULT_N_RESULTS

Number of context chunks to retrieve for each query.

**Default:** `5`

```bash
export DEFAULT_N_RESULTS=5
```

### SIMILARITY_THRESHOLD

Minimum similarity score for retrieved chunks.

**Default:** `0.5`

```bash
export SIMILARITY_THRESHOLD=0.5
```

### CHUNK_SIZE

Size of text chunks for processing.

**Default:** `1000`

```bash
export CHUNK_SIZE=1000
```

### CHUNK_OVERLAP

Overlap between consecutive chunks.

**Default:** `200`

```bash
export CHUNK_OVERLAP=200
```

### GRADIO_SHARE

Whether to create a public Gradio share link.

**Default:** `False` (set to `True` for 72-hour public link)

```bash
export GRADIO_SHARE=True
```

### GRADIO_SERVER_PORT

Port for the Gradio server.

**Default:** `7860`

```bash
export GRADIO_SERVER_PORT=7860
```

## Complete Example

Create a `.env` file in the project root:

```bash
# Required
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional (uncomment to override defaults)
# HF_MODEL=meta-llama/Llama-3.2-3B-Instruct
# EMBEDDING_MODEL=all-MiniLM-L6-v2
# CHROMA_PERSIST_DIR=./chroma_db
# DOCUMENTS_DIR=./documents
# PROCESSED_DOCS_DIR=./processed_docs
# DEFAULT_N_RESULTS=5
# SIMILARITY_THRESHOLD=0.5
# CHUNK_SIZE=1000
# CHUNK_OVERLAP=200
# GRADIO_SHARE=False
# GRADIO_SERVER_PORT=7860
```

Then load it before running:

```bash
# Using python-dotenv (recommended)
pip install python-dotenv
# Add to your script: from dotenv import load_dotenv; load_dotenv()

# Or manually source it
source .env  # Linux/Mac
```

## Verification

To verify your environment is set up correctly:

```bash
python -c "import os; print('HF_TOKEN:', 'SET' if os.getenv('HF_TOKEN') else 'NOT SET')"
```

Should output: `HF_TOKEN: SET`