README.md

metadata

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