add readme

README.md

@@ -27,10 +27,11 @@ A **RAG-powered chatbot** that provides HR knowledge and policy guidance for non
   - [Qdrant](#qdrant)
   - [Firecrawl](#firecrawl)
   - [LangSmith](#langsmith)
+- [Deployment Model](#deployment-model)
 - [Running the Application](#running-the-application)
 - [Admin Interface](#admin-interface)
 - [How It Works](#how-it-works)
-- [Embedding the Chatbot](#embedding-the-chatbot)
+- [Embedding the Chatbot Widget](#embedding-the-chatbot-widget)
 - [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
 
@@ -310,23 +311,73 @@ FIRECRAWL_API_KEY="fc-your-firecrawl-api-key"
 
 ---
 
+## Deployment Model
+
+This project uses a **split deployment** architecture: the user-facing chatbot runs in the cloud, while the admin dashboard runs on your local machine.
+
+```
+┌─────────────────────────────────┐      ┌─────────────────────────────┐
+│   Hugging Face Spaces (Cloud)   │      │     Your Local Machine      │
+│                                 │      │                             │
+│   app.py  (port 7860)          │      │   admin.py  (port 7861)    │
+│   - User chat interface         │      │   - Upload documents        │
+│   - RAG Q&A                     │      │   - Scrape web pages        │
+│   - Public access               │      │   - Delete documents        │
+│                                 │      │   - View knowledge base     │
+└────────────┬────────────────────┘      └──────────┬──────────────────┘
+             │                                      │
+             └──────────┬───────────────────────────┘
+                        │  Both connect to the same
+                        ▼  cloud services
+              ┌─────────────────┐   ┌──────────────┐
+              │  Qdrant Cloud   │   │  OpenAI API  │
+              └─────────────────┘   └──────────────┘
+```
+
+| Component  | Where it runs           | Purpose                   | Access                       |
+| ---------- | ----------------------- | ------------------------- | ---------------------------- |
+| `app.py`   | **Hugging Face Spaces** | User-facing chatbot       | Public (anyone with the URL) |
+| `admin.py` | **Your local machine**  | Knowledge base management | Private (admin only)         |
+
+**Why this split?**
+
+- The **chatbot** (`app.py`) is deployed to Hugging Face Spaces so end users can access it 24/7 via a public URL without needing any local setup.
+- The **admin dashboard** (`admin.py`) runs locally because it performs sensitive operations (uploading documents, deleting data, scraping URLs). Keeping it local ensures only authorized administrators can modify the knowledge base.
+- Both components share the same `.env` configuration and connect to the same Qdrant and OpenAI instances, so changes made via the admin dashboard are immediately reflected in the chatbot.
+
+---
+
 ## Running the Application
 
-### User Chat Interface
+### User Chat Interface (Cloud)
+
+The chatbot is deployed on Hugging Face Spaces and accessible at:
+
+```
+https://pikamomo-hr-intervals-chatbot.hf.space
+```
+
+To deploy your own instance, see [Deploying to Hugging Face Spaces](#deploying-to-hugging-face-spaces) below.
+
+For local development and testing, you can also run it locally:
 
 ```bash
 python app.py
 ```
 
-Opens the chatbot at **http://localhost:7860**. Users can ask HR-related questions and receive AI-generated answers with source citations.
+This opens the chatbot at **http://localhost:7860**.
+
+### Admin Dashboard (Local)
 
-### Admin Dashboard
+The admin panel runs on your local machine. Start it with:
 
 ```bash
 python admin.py
 ```
 
-Opens the admin panel at **http://localhost:7861** (see [Admin Interface](#admin-interface) below).
+This opens the admin dashboard at **http://localhost:7861**. See [Admin Interface](#admin-interface) for details on each tab.
+
+> **Important:** The admin dashboard is intentionally **not deployed** to the cloud. Always run it locally to maintain control over who can modify the knowledge base.
 
 ---
 
@@ -403,15 +454,123 @@ A regex-based check warns users when their query appears to contain names (e.g.,
 
 ---
 
-## Embedding the Chatbot
+## Embedding the Chatbot Widget
+
+The file `chatbot-widget.html` provides a ready-to-use **floating chat widget** that you can embed on any website. It renders a circular button in the bottom-right corner that opens the chatbot in a popup window — no page navigation required.
+
+### Quick Start
+
+The simplest way to add the chatbot to an existing web page is to copy three pieces from `chatbot-widget.html` into your site:
+
+1. **CSS** (add to your `<head>` or stylesheet)
+2. **HTML** (add before `</body>`)
+3. **JavaScript** (add before `</body>`)
+
+### Step 1 — Add the CSS
+
+Copy the widget styles into your page's `<head>` (or into your existing CSS file). These styles are marked between `CHATBOT WIDGET STYLES - COPY FROM HERE` and `END OF CHATBOT WIDGET STYLES` in the source file.
+
+### Step 2 — Add the HTML
+
+Add the following HTML just before your closing `</body>` tag. Update the `src` URL to point to your own Hugging Face Space:
 
-An embeddable HTML widget is provided in `chatbot-widget.html`. It renders a floating chat button that opens the chatbot in an iframe:
+```html
+<!-- Chat Toggle Button -->
+<button class="chat-widget-button" id="chatWidgetButton" onclick="toggleChat()">
+  <span class="chat-widget-badge">1</span>
+  <svg viewBox="0 0 24 24" id="chatIcon">
+    <path
+      d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"
+    />
+  </svg>
+  <svg viewBox="0 0 24 24" id="closeIcon" style="display: none;">
+    <path
+      d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"
+    />
+  </svg>
+</button>
+
+<!-- Chat Window -->
+<div class="chat-widget-window" id="chatWidgetWindow">
+  <div class="chat-widget-header">
+    <div class="chat-widget-header-info">
+      <div class="chat-widget-avatar">🤖</div>
+      <div class="chat-widget-title">
+        <h3>HR Assistant</h3>
+        <span><span class="status-dot"></span> Online</span>
+      </div>
+    </div>
+    <button class="chat-widget-close" onclick="toggleChat()">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+        <path
+          d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"
+        />
+      </svg>
+    </button>
+  </div>
+  <div class="chat-widget-body">
+    <!-- 👇 Change this URL to your Hugging Face Space URL -->
+    <iframe
+      src="https://pikamomo-hr-intervals-chatbot.hf.space"
+      title="HR Chatbot"
+      loading="lazy"
+    >
+    </iframe>
+  </div>
+</div>
+```
+
+### Step 3 — Add the JavaScript
+
+Add this script after the HTML above:
 
 ```html
-<iframe src="https://your-space.hf.space" ...></iframe>
+<script>
+  let isOpen = false;
+  const button = document.getElementById("chatWidgetButton");
+  const window_el = document.getElementById("chatWidgetWindow");
+  const chatIcon = document.getElementById("chatIcon");
+  const closeIcon = document.getElementById("closeIcon");
+  const badge = document.querySelector(".chat-widget-badge");
+
+  function toggleChat() {
+    isOpen = !isOpen;
+    if (isOpen) {
+      window_el.classList.add("open");
+      button.classList.add("active");
+      chatIcon.style.display = "none";
+      closeIcon.style.display = "block";
+      badge.style.display = "none";
+    } else {
+      window_el.classList.remove("open");
+      button.classList.remove("active");
+      chatIcon.style.display = "block";
+      closeIcon.style.display = "none";
+    }
+  }
+
+  // Close on Escape key
+  document.addEventListener("keydown", function (e) {
+    if (e.key === "Escape" && isOpen) {
+      toggleChat();
+    }
+  });
+</script>
 ```
 
-To use it, update the `src` URL to point to your deployed Hugging Face Space, then include the widget HTML in your website.
+### Customization
+
+| What to change  | Where                                  | Details                                                                |
+| --------------- | -------------------------------------- | ---------------------------------------------------------------------- |
+| Chatbot URL     | `<iframe src="...">`                   | Replace with your Hugging Face Space URL                               |
+| Widget colors   | CSS `background: linear-gradient(...)` | Change the gradient on `.chat-widget-button` and `.chat-widget-header` |
+| Widget size     | CSS `.chat-widget-window`              | Adjust `width` (400px) and `height` (600px)                            |
+| Button position | CSS `.chat-widget-button`              | Change `bottom` and `right` values                                     |
+| Header title    | HTML `<h3>HR Assistant</h3>`           | Replace with your preferred name                                       |
+
+### Full Working Example
+
+Open `chatbot-widget.html` directly in a browser to see the widget in action on a demo page. The file is self-contained and requires no build step — just open it and click the chat button in the bottom-right corner.
 
 ---
 
@@ -447,12 +606,52 @@ This tests connectivity to:
 
 ---
 
-## Deployment
+## Deploying to Hugging Face Spaces
 
-This project is designed to run on **Hugging Face Spaces** with the Gradio SDK:
+The user-facing chatbot (`app.py`) is designed to run on **Hugging Face Spaces**. The admin dashboard (`admin.py`) stays on your local machine.
 
-1. Create a new Space on [huggingface.co](https://huggingface.co/spaces)
+### Setting Up the Space
+
+1. Create a new Space at [huggingface.co/spaces](https://huggingface.co/spaces)
 2. Select **Gradio** as the SDK
-3. Push your code to the Space repository
-4. Add all required environment variables as **Secrets** in the Space settings
-5. The Space will automatically install dependencies and start `app.py`
+3. Push your code to the Space repository (or link it to your Git repo)
+4. Add all required environment variables as **Secrets** in the Space settings:
+
+| Secret              | Value                                                 |
+| ------------------- | ----------------------------------------------------- |
+| `OPENAI_API_KEY`    | Your OpenAI API key                                   |
+| `QDRANT_URL`        | Your Qdrant cluster URL                               |
+| `QDRANT_API_KEY`    | Your Qdrant API key                                   |
+| `QDRANT_COLLECTION` | `hr-intervals` (or your collection name)              |
+| `LANGSMITH_TRACING` | `false` (or `true` if you want tracing in production) |
+| `LANGSMITH_API_KEY` | Your LangSmith API key (if tracing is enabled)        |
+| `LANGSMITH_PROJECT` | `hr-intervals-chatbot`                                |
+
+5. The Space will automatically install dependencies from `requirements.txt` and start `app.py`
+6. Once deployed, your chatbot will be available at: `https://<your-username>-<space-name>.hf.space`
+
+### Managing the Knowledge Base
+
+After the Space is live, manage the knowledge base from your local machine:
+
+```bash
+# 1. Make sure your local .env has the SAME Qdrant credentials as the Space
+# 2. Start the admin dashboard
+python admin.py
+```
+
+Any documents you upload, scrape, or delete through the local admin dashboard will immediately be available to the cloud-hosted chatbot — because both connect to the same Qdrant instance.
+
+### Embedding on Your Website
+
+Once your Space is running, you can embed the chatbot on any website using the widget (see [Embedding the Chatbot Widget](#embedding-the-chatbot-widget)). Simply set the iframe `src` to your Space URL:
+
+```html
+<iframe src="https://pikamomo-hr-intervals-chatbot.hf.space" ...></iframe>
+```
+
+---
+
+## License
+
+This project is developed for non-profit HR use. See your organization's licensing terms for details.