README.md

---
title: VersionRAG
emoji: 📚
colorFrom: blue
colorTo: green
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false
---

# VersionRAG: Version-Aware RAG System

A proof-of-concept implementation of Version-Aware Retrieval-Augmented Generation (RAG) system for handling versioned documents.

## Features
- ✅ Version-aware document retrieval
- ✅ Change tracking between versions
- ✅ Multi-user support with data isolation
- ✅ Interactive Streamlit interface

## Usage
1. Enter your OpenAI API key in the sidebar
2. Click "🚀 Initialize Systems"
3. Upload versioned documents
4. Query using Content Retrieval, Version Inquiry, or Change Retrieval

## Requirements
- OpenAI API key

Built with Streamlit, LangChain, and ChromaDB.
```

Save this as `README.md` in your project folder.

---

## 🌐 Part 2: Create Hugging Face Account (3 minutes)

### Step 1: Go to Hugging Face
Open your browser and go to: **https://huggingface.co**

### Step 2: Sign Up
- Click **"Sign Up"** in the top right
- Use your email
- Choose a username (e.g., `shahbaz_ai` or whatever you like)
- Verify your email

### Step 3: Verify You're Logged In
You should see your profile picture in the top right corner.

---

## 🎨 Part 3: Create Your Space (2 minutes)

### Step 1: Go to Spaces
Click on **"Spaces"** in the top menu bar.

### Step 2: Create New Space
- Click the big **"Create new Space"** button
- You'll see a form

### Step 3: Fill Out the Form
```
Space name: VersionRAG
(or whatever name you want - use letters, numbers, hyphens only)

License: MIT

Select SDK: Streamlit ← IMPORTANT!

Space hardware: CPU basic - 2 vCPU, 16GB RAM (FREE tier)

Visibility: Public (or Private if you prefer)
```

### Step 4: Create!
Click **"Create Space"** button at the bottom.

You'll see a page that says "This Space is empty. Push your first commit to get started."

---

## 💻 Part 4: Upload Your Files (10 minutes)

You have two options: **Easy way (Web)** or **Git way**. Let's do the **Easy way** first!

### 🌐 Easy Way: Upload via Web Interface

#### Step 1: Click "Files" Tab
At the top of your Space page, click the **"Files"** tab.

#### Step 2: Upload Files One by One

Click **"Add file"** → **"Upload files"**

Upload these files in this order:
1. `README.md` (the one you just created)
2. `requirements.txt`
3. `app.py`
4. `version_rag.py`
5. `evaluation.py`
6. `graph_manager.py`
7. `utils.py`
8. `.gitignore`

After each upload, scroll down and click **"Commit changes to main"**.

**IMPORTANT:** Do NOT upload:
- ❌ `.env` file (has your API key)
- ❌ `venv/` folder
- ❌ `chroma_db_*` folders
- ❌ Any `__pycache__` folders

---

## 🔐 Part 5: Add Your OpenAI API Key (CRITICAL!) (2 minutes)

### Step 1: Go to Settings
In your Space, click **"Settings"** tab at the top.

### Step 2: Add Secret
- Scroll down to **"Variables and secrets"** section
- Click **"New secret"**

### Step 3: Fill In Your API Key
```
Name: OPENAI_API_KEY
Value: sk-proj... (paste your actual OpenAI API key here)
```

### Step 4: Save
Click **"Save"** button.

**⚠️ SUPER IMPORTANT:** Without this, your app won't work!

---

## ⏳ Part 6: Wait for Build (5-10 minutes)

### Step 1: Go to "App" Tab
Click the **"App"** tab at the top.

### Step 2: Watch It Build
You'll see logs scrolling. This is normal! It's installing all the packages.

You'll see messages like:
```
Collecting streamlit==1.28.0
Downloading streamlit-1.28.0...
Installing...
```

### Step 3: Wait for Success
When it's done, you'll see:
```
✅ Space is running!

You can now view your Streamlit app in your browser.
```

If you see errors, don't panic! We'll fix them. Take a screenshot and show me.

---

## 🎉 Part 7: Test Your Deployed App! (5 minutes)

### Step 1: Your App Should Now Be Live!
You should see your VersionRAG interface in the "App" tab.

### Step 2: Test It
1. **Initialize Systems**:
   - The OpenAI API key should already be set (from secrets)
   - Click **"🚀 Initialize Systems"** in the sidebar
   - Wait for "✅ Systems initialized successfully!"

2. **Upload a Document** (optional for testing):
   - Go to **"📤 Document Upload"** tab
   - Create a simple test file on your computer:
   
   **test_v1.txt:**
```
   Test Document v1.0
   This is a test document for version 1.0.
   Feature A is available.
```
   
   - Upload it with Version: `v1.0`, Domain: `Software`
   - Click "Process"

3. **Try a Query**:
   - Go to **"💬 Query Interface"** tab
   - Enter: `What features are available?`
   - Click **"🔍 Search"**
   - You should get a response!

### Step 3: Share Your Space!
Your Space URL is:
```
https://huggingface.co/spaces/YOUR_USERNAME/VersionRAG
```

Copy this and share it with anyone! 🎉

---

## 🐛 Common Problems & Fixes

### Problem 1: "Space is building..." for more than 15 minutes

**Fix:**
- Refresh the page
- Check "Logs" tab for errors
- Common issue: `requirements.txt` has wrong versions

### Problem 2: "Import Error" or "Module not found"

**Fix:**
- Go to "Files" tab
- Click on `requirements.txt`
- Click "Edit" (pencil icon)
- Make sure it has all packages:
```
streamlit==1.28.0
chromadb==0.4.22
langchain==0.1.16
langchain-community==0.0.38
langchain-openai==0.1.6
openai==1.23.0
PyPDF2==3.0.1
python-dotenv==1.0.1
pandas==2.2.1
plotly==5.20.0
networkx==3.2.1
pydantic==2.7.0
tiktoken==0.6.0
numpy==1.26.4
scikit-learn==1.4.2