Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/vitalune/pitt-llamaproject

Helping students process and interact with their data.
https://github.com/vitalune/pitt-llamaproject

llamaindex streamlit

Last synced: 12 days ago
JSON representation

Helping students process and interact with their data.

Awesome Lists containing this project

README 

          
# 🤖 LlamaIndex RAG Chatbot Template



![final product demo](example/visuals/embeddedui-demo.png)



A Retrieval-Augmented Generation (RAG) chatbot template that answers questions based on your company's documents using LlamaIndex and OpenAI.



> **📘 For Students**: This is a template for your project. The main folder contains your workspace, and the `examples/` folder shows a complete working version for reference.



---



## 💼 Why Choose This High-Tech Option?



**This project gives you a competitive edge.** By building an AI-powered chatbot with industry-standard tools, you'll gain hands-on experience with technologies that Fortune 500 companies and cutting-edge startups use daily—from working with OpenAI's API and deploying to professional platforms like Hugging Face, to managing code with Git and GitHub. These aren't just buzzwords: they're resume-ready skills that distinguish you in any career path, whether you're pursuing roles in business, healthcare, law, marketing, or technology. You'll create a live, public portfolio piece that demonstrates technical problem-solving, modern AI fluency, and the ability to build real-world applications—capabilities that employers across industries increasingly value. While the low-tech option is perfectly valid, this path transforms your class project into a genuine professional asset.



---



## 📋 Table of Contents



- [Repository Structure](#-repository-structure)

- [What This Does](#-what-this-does)

- [Prerequisites](#-prerequisites)

- [Setup Instructions](#-setup-instructions)

- [Adding Your Data](#-adding-your-data)

- [Development & Testing Options](#-development--testing-options)

- [Testing with the Example](#-testing-with-the-example)

- [Deploying to Hugging Face](#-deploying-to-hugging-face)

- [Embedding in Your Website](#-embedding-in-your-website)

- [Publishing to GitHub Pages](#-publishing-your-website-to-github-pages)

- [Troubleshooting](#-troubleshooting)

- [Project Integration](#-project-integration-engcmp-0600)

- [Recommended Workflow](#-recommended-workflow)



---



## 📁 Repository Structure



```

pitt-llama-project/

├── README.md                    # ← You are here!

├── .env.example                 # Template for your API key

├── .gitignore                   # Protects sensitive files

├── requirements.txt             # Python dependencies

├── app.py                       # YOUR chatbot (work here!)

├── data/                        # YOUR documents go here (currently empty)

│   └── README.md

│

└── examples/                    # 👀 Reference only

    ├── llama_test.ipynb         # Learning notebook for Colab

    ├── index.html         # Full website (HTML, CSS, JS) saved locally w/ embedded chatbot script

    ├── visuals/         # example images of UI 

    │   ├── embeddedui-demo.png  # example website w/ embedded chatbot

    │   └── ui-demo.jpeg         # example ui during local streamlit testing

    ├── data/                    # Example documents

    │   ├── taylor_swift_biography.html

    │   └── constitution.pdf

    └── storage/                 # Pre-built index for example

```



### 🎯 Where to Work



- **`app.py`** - Your main chatbot code (already complete, no edits needed!)

- **`data/`** - Put YOUR company documents here

- **`examples/`** - Look here if you get stuck (don't edit this!)



### 📂 What Gets Created



When you run the app, it will automatically create:

- **`storage/`** - Cached index of your documents (speeds up loading)



---



## 🎯 What This Does



This chatbot uses **Retrieval-Augmented Generation (RAG)** to answer questions about your documents:



1. **📖 Reads your documents** from the `data/` folder

2. **🔍 Creates a searchable index** using AI embeddings

3. **💬 Answers questions** by finding relevant information and generating responses

4. **🧠 Remembers conversation** context within each chat session



**Example Use Case**: A customer support chatbot that answers questions about your company's products, policies, or services.



---



## ✅ Prerequisites



Before starting, make sure you have:



1. **A Google account** for Google Colab ([Sign up here](https://accounts.google.com/signup))

2. **Google Colab Pro (FREE for students!)** ([Get it here](https://colab.research.google.com/signup/pricing))

   - ✨ Faster execution

   - ⏱️ Longer runtime limits

   - 💾 More storage

   - ⚡ Priority access to GPUs

   - 🎓 **100% FREE with your .edu email** - verification takes ~2 seconds!

3. **An OpenAI API key**

   - 🎓 **I, Amir, will provide a shared API key** for the class

   - No payment required! Use the key provided by me

   - (Alternative: Use Gemini API within your Google Colab Workspace for free! For more info, see [this link](https://github.com/googlecolab/colabtools/blob/main/notebooks/Getting_started_with_google_colab_ai.ipynb))

4. **A LlamaCloud API key (Optional but Recommended)**

   - 🆓 **Free tier available** at [cloud.llamaindex.ai](https://cloud.llamaindex.ai/)

   - Enables advanced parsing of PDFs with tables, charts, and complex layouts

   - Get 1,000 free pages per month

   - Not required but highly recommended for processing complex documents

5. **A GitHub account** ([Sign up here](https://github.com/signup))

6. **A Hugging Face account** ([Sign up here](https://huggingface.co/join)) - for deployment



---



## 🚀 Setup Instructions



### Step 1: Create Your Google Colab Account



1. Go to [Google Colab](https://colab.research.google.com/)

2. Sign in with your Google account

3. **Get Colab Pro for FREE**:

   - Go to [Colab Pro pricing page](https://colab.research.google.com/signup/pricing)

   - Click "Get Colab Pro" and verify with your .edu email

   - Instant approval! No payment required for students 🎉

   - Enjoy faster runtimes and priority access



### Step 2: Fork This Repository



1. Go to the repository on GitHub

2. Click the "Fork" button in the top right

3. This creates your own copy of the project



### Step 3: Connect Colab to Your GitHub



1. In Google Colab, click **File → Open notebook**

2. Select the **GitHub** tab

3. Enter your repository URL or search for your username

4. Open `examples/llama_test.ipynb` to start learning!



### Step 4: Set Up Your API Keys in Colab



**Option A: Using Colab Secrets (Recommended)**



1. In your Colab notebook, click the 🔑 key icon in the left sidebar

2. Click "Add new secret"

3. Add `OPENAI_API_KEY`:

   - Name: `OPENAI_API_KEY`

   - Value: `sk-proj-xxxxxxxxxxxxxxxxxxxxx` (your actual key)

   - Toggle "Notebook access" to ON

4. (Optional) Add `LLAMA_CLOUD_API_KEY`:

   - Click "Add new secret" again

   - Name: `LLAMA_CLOUD_API_KEY`

   - Value: `llx-xxxxxxxxxxxxxxxxxxxxx` (your LlamaCloud key)

   - Toggle "Notebook access" to ON



**Option B: Using Code (Less Secure)**



```python

from google.colab import userdata

import os



# This retrieves your secret keys

os.environ['OPENAI_API_KEY'] = userdata.get('OPENAI_API_KEY')

# Optional: Enable advanced document parsing

os.environ['LLAMA_CLOUD_API_KEY'] = userdata.get('LLAMA_CLOUD_API_KEY')

```



⚠️ **Important**: Never hardcode your API keys directly in the notebook!



---



## 📄 Adding Your Data



### Supported File Types



#### Complex Documents (Parsed with LlamaParse - requires LLAMA_CLOUD_API_KEY)

- PDF documents (`.pdf`) - with advanced OCR, table extraction, and chart recognition

- Word documents (`.docx`, `.doc`)

- PowerPoint presentations (`.pptx`, `.ppt`)

- Excel spreadsheets (`.xlsx`, `.xls`)



#### Simple Text Files (Parsed with SimpleDirectoryReader)

- HTML files (`.html`)

- Text files (`.txt`)

- Markdown files (`.md`)

- CSV files (`.csv`)

- JSON files (`.json`)

- XML files (`.xml`)



![LlamaParse demo](example/visuals/llamaparse-demo%20Large.jpeg)



**New Feature**: The app now uses LlamaParse for advanced document parsing! LlamaParse provides:

- High-quality OCR for scanned documents

- Intelligent table extraction (even from images and charts)

- Multi-column layout handling

- Chart and graph text extraction

- Better handling of complex PDFs with mixed content



If LLAMA_CLOUD_API_KEY is not set, the app will fall back to SimpleDirectoryReader for all files.



### How to Add Documents to Colab



**Method 1: Upload Directly (Quick Testing)**



1. In your Colab notebook, run:

   ```python

   from google.colab import files

   uploaded = files.upload()

   ```

2. Select your documents to upload

3. Files will be in the current directory



**Method 2: Mount Google Drive (Recommended)**



1. Upload your documents to a folder in Google Drive (e.g., `My Drive/chatbot-data/`)

2. In your Colab notebook:

   ```python

   from google.colab import drive

   drive.mount('/content/drive')

   ```

3. Access files from: `/content/drive/MyDrive/chatbot-data/`



**Method 3: Push to GitHub (For Deployment)**



1. Add your documents to the `data/` folder in your repository

2. Commit and push to GitHub

3. Pull the repository in Colab or deploy directly to Hugging Face



### Tips for Better Results

- ✅ Use clear, well-formatted documents

- ✅ Include only relevant company information

- ✅ Break very large documents into smaller, topic-focused files

- ❌ Don't include sensitive data (passwords, private info)

- ❌ Avoid image-only PDFs (text must be selectable)



---



## 🧪 Development & Testing Options



You have **two options** for developing and testing your chatbot. Choose the one that works best for you!



---



### 🌐 Option 1: Google Colab (Recommended for Beginners)



**Pros**: No installation needed, works in browser, free GPU access

**Cons**: Temporary URLs, session expires after inactivity



**Use this if**: You prefer browser-based development or don't want to install Python locally



---



### 💻 Option 2: Local Development (Recommended for Advanced Users)



**Pros**: Persistent environment, faster development, works offline

**Cons**: Requires Python installation and setup



**Use this if**: You're comfortable with terminal/command line and want full control



---



## 🌐 Option 1: Testing in Google Colab



### Phase 1: Learning with the Example Notebook



The example notebook (`examples/llama_test.ipynb`) teaches you RAG concepts interactively.



1. **Open the example notebook** in Colab:

   - Go to your forked repository

   - Navigate to `examples/llama_test.ipynb`

   - Click "Open in Colab" badge (or manually open via Colab)



2. **Install dependencies** (First cell - run this first!):

   ```python

   # STEP 1: Install all required packages

   print("📦 Installing dependencies...")

   

   !pip install -q streamlit==1.50.0

   !pip install -q llama-index==0.14.4

   !pip install -q llama-index-core==0.14.4

   !pip install -q llama-index-llms-openai==0.6.4

   !pip install -q llama-index-embeddings-openai==0.5.1

   !pip install -q openai==1.109.1

   !pip install -q python-dotenv==1.1.1

   !pip install -q jedi==0.19.2

   

   print("✅ All dependencies installed!")

   ```

   ⏱️ This takes 1-2 minutes. Wait for "✅ All dependencies installed!" before continuing.



3. **Set up your API key** (Second cell):

   ```python

   # STEP 2: Configure OpenAI API Key

   from google.colab import userdata

   import os

   

   # Get API key from Colab secrets (you must add this first!)

   os.environ['OPENAI_API_KEY'] = userdata.get('OPENAI_API_KEY')

   print("✅ API key loaded")

   ```



4. **Load and index documents** (Third cell):

   ```python

   # STEP 3: Load documents and create index

   from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

   from llama_index.llms.openai import OpenAI

   from llama_index.embeddings.openai import OpenAIEmbedding

   

   # Configure models

   llm = OpenAI(model="gpt-5-nano-2025-08-07", temperature=0.1)

   embed_model = OpenAIEmbedding(model="text-embedding-3-small")

   

   # Load documents from data folder

   documents = SimpleDirectoryReader("data").load_data()

   print(f"📄 Loaded {len(documents)} documents")

   

   # Create searchable index

   index = VectorStoreIndex.from_documents(

       documents,

       llm=llm,

       embed_model=embed_model

   )

   print("✅ Index created successfully!")

   ```



5. **Query the chatbot** (Fourth cell):

   ```python

   # STEP 4: Ask questions!

   query_engine = index.as_query_engine()

   

   # Try your first question

   response = query_engine.query("Your question here")

   print(response)

   ```



6. **Test with example data** first, then replace with your own documents



### Phase 2: Running Your Streamlit App in Colab



Once you understand how RAG works from the notebook, transition to testing your actual `app.py` Streamlit application.



#### Why Transition to app.py?



- 📓 **Notebook (`llama_test.ipynb`)**: Learning tool, shows RAG step-by-step

- 🚀 **Streamlit app (`app.py`)**: Production-ready chatbot with UI, what you'll deploy



#### Step-by-Step: Running app.py in Colab



1. **Create a new Colab notebook** (or add cells to your existing one):

   - File → New notebook

   - Or continue in your existing notebook



2. **Install dependencies** (same as before):

   ```python

   !pip install -q streamlit==1.50.0 llama-index==0.14.4 llama-index-core==0.14.4 llama-index-llms-openai==0.6.4 llama-index-embeddings-openai==0.5.1 openai==1.109.1 python-dotenv==1.1.1 jedi==0.19.2

   ```



3. **Clone your repository** (if not already in Colab):

   ```python

   # Clone your forked repository

   !git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.git

   %cd YOUR-REPO-NAME

   ```



4. **Set up your API key as environment variable**:

   ```python

   import os

   from google.colab import userdata

   

   # Set API key for the app to use

   os.environ['OPENAI_API_KEY'] = userdata.get('OPENAI_API_KEY')

   ```



5. **Upload your documents** (if not already in the repo):

   ```python

   # Option A: Upload directly to Colab

   from google.colab import files

   uploaded = files.upload()

   # Move uploaded files to data folder

   !mkdir -p data

   !mv *.pdf data/  # Adjust file extensions as needed

   

   # Option B: Mount Google Drive

   from google.colab import drive

   drive.mount('/content/drive')

   !cp -r /content/drive/MyDrive/chatbot-data/* data/

   ```



6. **Install localtunnel to expose Streamlit**:

   ```python

   # Install localtunnel for public URL

   !npm install -g localtunnel

   ```



7. **Run Streamlit in the background**:

   ```python

   # Run Streamlit app in background

   !streamlit run app.py &>/content/logs.txt &

   

   # Wait for Streamlit to start

   import time

   time.sleep(5)

   

   # Verify it's running

   !curl http://localhost:8501

   ```



8. **Expose with localtunnel to get a public URL**:

   ```python

   # Get a public URL using localtunnel

   !npx localtunnel --port 8501 &

   

   # Wait a moment for the URL

   import time

   time.sleep(3)

   

   # The URL will appear in the output above

   # Look for: "your url is: https://xxxxx.loca.lt"

   ```



9. **Access your chatbot**:

   - Click the URL from localtunnel output (looks like `https://xxxxx.loca.lt`)

   - Click "Click to Continue" on the localtunnel page

   - Your Streamlit chatbot interface will appear! 🎉



![chatbot ui demo](example/visuals/ui-demo.jpeg)



10. **Test your chatbot**:

    - Ask questions about your documents

    - Verify responses are accurate

    - Test different types of queries



#### Important Notes for Running app.py in Colab:



⚠️ **Limitations**:

- Localtunnel URLs are temporary (expire when Colab disconnects)

- Not suitable for permanent hosting

- Great for testing and development only



✅ **When to Use This**:

- Testing your app with real documents before deploying

- Showing your team the chatbot interface during development

- Debugging issues before Hugging Face deployment



🚀 **For Production**:

- After testing in Colab, deploy to Hugging Face Spaces (permanent hosting)

- Colab is for **development and testing**

- Hugging Face is for **production and embedding**



#### Workflow Summary:



```

Step 1: Learn RAG concepts

└─→ Use llama_test.ipynb notebook



Step 2: Test with your data

└─→ Add your documents to data/

└─→ Run notebook cells to verify indexing works



Step 3: Test the Streamlit UI

└─→ Run app.py in Colab with localtunnel

└─→ Verify chatbot interface works correctly



Step 4: Deploy to production

└─→ Push to GitHub

└─→ Deploy to Hugging Face Spaces

└─→ Embed in your website



Step 5: Publish website

└─→ Enable GitHub Pages

└─→ Share your live URL!

```



### Phase 3: When You're Ready for Production



Once you've tested everything in Colab and your chatbot works well:



1. ✅ Make sure all your documents are in the `data/` folder

2. ✅ Push your code to GitHub

3. ✅ Deploy to Hugging Face Spaces (see next section)

4. ✅ Embed the permanent Hugging Face URL in your website



---



## 💻 Option 2: Testing Locally on Your Computer



If you prefer to develop on your local machine, follow these steps.



### Prerequisites



- Python 3.9+ installed

- Terminal/Command Prompt access

- Text editor or IDE (VS Code recommended)



### Setup Steps



1. **Clone your repository**:

   ```bash

   git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.git

   cd YOUR-REPO-NAME

   ```



2. **Create a virtual environment**:

   

   **On macOS/Linux**:

   ```bash

   python3 -m venv venv

   source venv/bin/activate

   ```

   

   **On Windows**:

   ```bash

   python -m venv venv

   venv\Scripts\activate

   ```



3. **Install dependencies**:

   ```bash

   pip install -r requirements.txt

   ```



4. **Set up your API keys**:

   ```bash

   # Copy the template

   cp .env.example .env



   # Edit .env and add your keys

   # OPENAI_API_KEY=your-provided-key-here

   # LLAMA_CLOUD_API_KEY=llx-your-key-here (optional but recommended)

   ```



5. **Add your documents** to the `data/` folder:

   ```bash

   # Place your PDF, HTML, TXT files in data/

   ls data/

   ```



6. **Run the Streamlit app**:

   ```bash

   streamlit run app.py

   ```

   

   The app will open at `http://localhost:8501` 🎉



### Testing Locally



1. **First run**: The app will index your documents (takes 10-30 seconds)

2. **Subsequent runs**: Loads from cached `storage/` folder (much faster)

3. **To re-index**: Delete the `storage/` folder and restart



### Local Development Tips



✅ **Advantages**:

- Faster iteration (no need to reinstall packages each time)

- Persistent storage (index cache survives between sessions)

- Works offline (once dependencies are installed)

- Better debugging experience



⚠️ **Remember**:

- Keep your virtual environment activated when working

- Never commit `.env` file to GitHub

- Test thoroughly before deploying to Hugging Face



### Workflow for Local Development



```bash

# 1. Activate environment

source venv/bin/activate  # or venv\Scripts\activate on Windows



# 2. Make changes to your code or data/



# 3. Test locally

streamlit run app.py



# 4. When satisfied, push to GitHub

git add .

git commit -m "Update chatbot"

git push



# 5. Deploy to Hugging Face (see next section)

```



---



## 🎯 Which Option Should You Choose?



| Factor | Google Colab | Local Development |

|--------|--------------|-------------------|

| **Setup Time** | ⚡ Instant | 🕐 10-15 minutes |

| **No Installation** | ✅ Yes | ❌ Need Python |

| **Persistent Environment** | ❌ Sessions expire | ✅ Always available |

| **Speed** | 🐌 Slower | ⚡ Faster |

| **Best For** | Beginners, quick tests | Serious development |

| **Internet Required** | ✅ Always | ❌ Only for deployment |



**Recommendation**: Start with Google Colab to learn, then switch to local development if you want a better experience!



### Understanding the Workflow



```

📝 Colab Notebook → 🧪 Test RAG Logic → 🚀 Deploy to Hugging Face → 🌐 Embed in Website

```



- **Colab**: Development and testing environment

- **Hugging Face**: Production hosting for your Streamlit app

- **Website**: User-facing integration



---



## 🧪 Testing with the Example



### Option 1: Use the Example Notebook in Colab



1. Open `examples/llama_test.ipynb` in Google Colab

2. Run all cells to see the chatbot in action

3. Ask questions like:

   - "When did Taylor Swift become a superstar?"

   - "What are the amendments in the Constitution?"



### Option 2: Copy Example Data for Testing



If you want to test with the example documents:



1. Clone the example data to your Google Drive

2. Or download from GitHub and upload to Colab

3. Point your code to the example data folder



---



## 🌐 Deploying to Hugging Face



### Why Deploy?

- ✨ Makes your chatbot publicly accessible

- 🆓 Free hosting for public projects

- 🔗 Easy to share with your team and embed in websites

- 🎨 Professional Streamlit interface



### Deployment Steps



1. **Create a new Space** at [huggingface.co/new-space](https://huggingface.co/new-space)

   - Name: `your-company-chatbot`

   - License: Apache 2.0

   - SDK: **Streamlit** ⚠️ Important!

   - Hardware: CPU Basic (free)



2. **Upload your files** from your GitHub repository:

   - `app.py` ✅

   - `requirements.txt` ✅

   - `data/` folder with YOUR documents ✅

   - `storage/` folder (optional - speeds up first load) ⚠️



3. **Add your API keys as Secrets**:

   - Go to Space Settings → Repository secrets

   - Add secret: `OPENAI_API_KEY` = `your-key-here` (required)

   - Add secret: `LLAMA_CLOUD_API_KEY` = `llx-your-key-here` (optional but recommended for better document parsing)



4. **Wait for build** (2-3 minutes)

   - Check the "Logs" tab for any errors

   - Look for: "✅ Index loaded" or "✅ Index created"

   - Once running, your chatbot is live! 🎉



Your chatbot URL will be: `https://huggingface.co/spaces/YOUR-USERNAME/your-company-chatbot`



### 💡 Pro Tips for Hugging Face Deployment

- Upload the `storage/` folder to skip indexing on first load (faster startup)

- Test thoroughly in Colab or locally before deploying

- Use descriptive Space names (e.g., `acme-support-bot` not `test123`)

- The chatbot uses `gpt-5-nano-2025-08-07` for responses and `text-embedding-3-small` for indexing (configured in app.py)



---



## 🌍 Embedding in Your Website



Once deployed to Hugging Face, you can embed your chatbot in your company website HTML page.



### Option 1: Floating Chat Widget (Recommended)



**See it in action**: Check out `visuals/embeddedui-demo.html` for a working example!



Add this code before the closing `