CI: sync project3-document-qa to Space

README.md

@@ -1,14 +1,83 @@
----
-title: Document Qa Rag
-emoji: 🐢
-colorFrom: indigo
-colorTo: pink
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
-license: mit
-short_description: RAG-based document Q&A using ChromaDB, SentenceTransformers,
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Project 3: Document Q&A (Gradio / Hugging Face Spaces)
+
+[![Open in Hugging Face Spaces](https://img.shields.io/badge/Spaces-Open%20App-blue?logo=huggingface)](https://huggingface.co/spaces/zhangju2023/document-qa-rag)
+
+A RAG (Retrieval-Augmented Generation) application using:
+- ChromaDB for vector storage
+- SentenceTransformers for embeddings (`all-MiniLM-L6-v2`)
+- Hugging Face Transformers for text generation (`distilgpt2`)
+- Gradio UI
+
+## Local Run
+
+```bash
+cd project3-document-qa
+pip install -r requirements.txt
+python app.py
+# Then open http://localhost:7860
+```
+
+Live app: https://huggingface.co/spaces/zhangju2023/document-qa-rag
+
+## Try it online (3 steps)
+
+1) Open the Space
+   - https://huggingface.co/spaces/zhangju2023/document-qa-rag
+   - First load can take 1–3 minutes while models download
+
+2) Load documents
+   - Go to the "📁 Manage Documents" tab
+   - Click "📥 Load Sample AI/ML Documents" or "📥 Load Sample HR Policy Documents" and wait for the status to confirm
+   - (Optional) Paste your own text into "Document Text" and click "➕ Add Document"
+
+3) Ask a question
+   - Switch to the "💬 Ask Questions" tab
+   - Type a question or click one of the sample buttons
+   - Adjust "Number of context documents" if you like (default: 3)
+   - Click "🔍 Ask Question" and read the answer
+   - Expand "📄 Retrieved Context" to see the sources and relevance scores
+
+Troubleshooting
+- HR use case tips:
+   - Try questions like "What is the overtime policy?", "When is payroll processed?", or "How does PTO accrue?"
+   - Load the HR sample first to populate the knowledge base with HR/policy docs.
+- If you see "No relevant documents", make sure you loaded sample or custom documents
+- First inference might be slow while the model warms up; later queries are faster
+- Click "📊 View Statistics" or "🗑️ Clear Knowledge Base" in the Manage tab to inspect/reset the index
+
+## CI/CD (Auto-deploy from GitHub)
+
+This folder is configured to auto-sync to the Hugging Face Space via GitHub Actions.
+
+- Workflow: `.github/workflows/deploy-project3-to-hf.yml`
+- Trigger: Any push to `main` that changes files under `project3-document-qa/**`
+- Requirements: GitHub repo secret `HF_TOKEN` containing a Hugging Face write token
+- Target Space: `zhangju2023/document-qa-rag`
+
+If you just pushed changes and don't see them live yet:
+1. Open the GitHub "Actions" tab and check the latest run for "Deploy Project 3 (RAG) to Hugging Face Space".
+2. Wait 1–3 minutes for the Space to rebuild after the upload completes.
+3. Hard refresh the Space page (Cmd+Shift+R) if the UI was open during the update.
+
+## Deploy to Hugging Face Spaces
+
+Option A — Create a new Space and upload:
+1. Go to https://huggingface.co/spaces
+2. New Space → Type: "Gradio" → Name: `document-qa-rag`
+3. Upload these files from this repo:
+   - `project3-document-qa/app.py`
+   - `project3-document-qa/requirements.txt`
+   - (optional) `README.md`
+4. Set the Space hardware to CPU Basic (free)
+5. The app will auto-build and launch
+
+Option B — Connect to GitHub (recommended):
+1. Create a new Space as above
+2. In Space settings → "Link Git Repositories"
+3. Connect to this GitHub repo and map `/project3-document-qa` folder
+4. Set `app.py` as the entry file
+
+Notes:
+- First build may take a while to download models.
+- You can switch to a lighter LLM in `app.py` (e.g., `sshleifer/tiny-gpt2`) if needed.
+- For production, consider larger models via Inference Endpoints or OpenAI with an API key.

UPDATE_GUIDE.md

@@ -0,0 +1,52 @@
+# Update Your Hugging Face Space (RAG)
+
+This guide helps you update your existing Space to reflect the new HR policy features (sample corpus + loader button).
+
+## What Changed
+
+- Added "Load Sample HR Policy Documents" in the Manage Documents tab
+- Included curated HR policy snippets (PTO, overtime, payroll schedule, benefits, FMLA, expenses, reviews)
+- Minor README improvements
+
+## Files to Update in Your Space
+
+Upload these 3 files from this repo to your Space:
+
+1. `project3-document-qa/app.py`
+2. `project3-document-qa/requirements.txt`
+3. (optional) `project3-document-qa/README.md`
+
+## Option A — Upload via Web UI (Easiest)
+
+1. Go to your Space: https://huggingface.co/spaces/zhangju2023/document-qa-rag
+2. Click the "Files" tab
+3. Upload the files listed above (drag & drop or click Upload)
+4. Commit the changes — the Space will rebuild automatically
+5. Wait 1–3 minutes for the rebuild
+
+## Option B — Link to GitHub (Recommended)
+
+1. In your Space, open "Settings" → "Repository" → "Link Git Repositories"
+2. Connect GitHub repo: `justin-mbca/enterprise-ai-workflows`
+3. Map the subdirectory: `/project3-document-qa`
+4. App file: `app.py` (Gradio)
+5. Save. The Space will auto-sync on every push to `main`.
+
+## After Update — Quick Test
+
+In the running app:
+
+- Go to "📁 Manage Documents"
+- Click "📥 Load Sample HR Policy Documents" → wait for success
+- Switch to "💬 Ask Questions" and try:
+  - "What is the overtime policy?"
+  - "When is payroll processed?"
+  - "How does PTO accrue?"
+
+If you see "No relevant documents", ensure you loaded the HR sample first.
+
+## Troubleshooting
+
+- First load can take 1–3 minutes while models download
+- If the Space errors, check Logs → look for package install or model download issues
+- You can switch to a lighter LLM in `app.py` (e.g., `sshleifer/tiny-gpt2`) to reduce cold start time

app.py

@@ -265,6 +265,17 @@ SAMPLE_DOCUMENTS = [
     "Kubernetes is an open-source container orchestration platform that automates deploying, scaling, and managing containerized applications. It groups containers into logical units for easy management and discovery, and provides tools for load balancing, rolling updates, and service discovery.",
 ]
 
+# HR/Payroll policy sample documents for domain-specific demo
+HR_SAMPLE_DOCUMENTS = [
+    "Paid Time Off (PTO): Full-time employees accrue 1.67 days of PTO per month (20 days/year). Unused PTO carries over up to 5 days. PTO requests must be submitted at least 2 weeks in advance via the HR portal.",
+    "Overtime Policy: Non-exempt hourly employees are eligible for overtime pay at 1.5x the regular rate for hours worked over 40 in a workweek. Overtime must be pre-approved by a manager.",
+    "Payroll Schedule: Employees are paid bi-weekly on Fridays. Direct deposit is required. Payroll cut-off is Tuesday 5pm for the current pay period.",
+    "Benefits Eligibility: Employees working 30+ hours per week are eligible for medical, dental, and vision plans starting on the first day of the month following 30 days of employment.",
+    "Leave of Absence: FMLA provides up to 12 weeks of unpaid, job-protected leave for eligible employees. Employees must provide 30 days' notice when foreseeable and submit required documentation.",
+    "Expense Reimbursement: Business expenses must be submitted within 30 days with itemized receipts. Reimbursements are processed in the next payroll cycle upon approval.",
+    "Performance Reviews: Formal performance reviews occur annually in Q4 with mid-year checkpoints. Salary adjustments, if any, are effective in the first payroll of Q1."
+]
+
 
 # Helper: add sample documents with dedup by deterministic IDs
 def _add_sample_documents_dedup() -> int:
@@ -319,6 +330,35 @@ def load_sample_documents():
     return f"✅ Loaded {added} sample documents. Total documents: {stats['total_documents']}"
 
 
+def load_sample_hr_documents():
+    """Load HR/policy sample documents into the system (idempotent)"""
+    # Build deterministic IDs for HR docs
+    ids = [f"hr_doc_{i}" for i in range(len(HR_SAMPLE_DOCUMENTS))]
+    metadata = [{"source": ids[i], "domain": "hr", "topic": "HR/Payroll"} for i in range(len(HR_SAMPLE_DOCUMENTS))]
+
+    # Determine which ones already exist
+    existing_ids = set()
+    try:
+        got = qa_system.collection.get(ids=ids)
+        if got and isinstance(got.get("ids", None), list):
+            existing_ids = set(got["ids"])  # existing subset
+    except Exception:
+        existing_ids = set()
+
+    to_add_idx = [i for i, _id in enumerate(ids) if _id not in existing_ids]
+    if not to_add_idx:
+        stats = qa_system.get_collection_stats()
+        return f"ℹ️ HR policy documents already loaded. Total documents: {stats['total_documents']}"
+
+    docs = [HR_SAMPLE_DOCUMENTS[i] for i in to_add_idx]
+    metas = [metadata[i] for i in to_add_idx]
+    sel_ids = [ids[i] for i in to_add_idx]
+
+    qa_system.add_documents(docs, metas, ids=sel_ids)
+    stats = qa_system.get_collection_stats()
+    return f"✅ Loaded {len(docs)} HR policy documents. Total documents: {stats['total_documents']}"
+
+
 def add_custom_document(text: str):
     """Add a custom document"""
     if not text.strip():
@@ -450,12 +490,17 @@ with gr.Blocks(title="Document Q&A System", theme=gr.themes.Soft()) as demo:
             with gr.Column():
                 gr.Markdown("#### Load Sample Documents")
                 load_sample_btn = gr.Button("📥 Load Sample AI/ML Documents", variant="primary")
+                load_hr_btn = gr.Button("📥 Load Sample HR Policy Documents")
                 load_status = gr.Textbox(label="Status", interactive=False)
                 
                 load_sample_btn.click(
                     load_sample_documents,
                     outputs=load_status
                 )
+                load_hr_btn.click(
+                    load_sample_hr_documents,
+                    outputs=load_status
+                )
             
             with gr.Column():
                 gr.Markdown("#### Add Custom Document")