DEPLOY.md

# Deploying FinAgent to Hugging Face Spaces (from zero)

Everything in **this folder** is what gets uploaded. Nothing else from the
project is needed. Total size ~71 MB.

Files included:
- `app.py` — Streamlit entry point (HF runs this automatically)
- `phase1_ingestion.py`, `phase2_retrieval.py`, `phase3_agent.py`, `phase4_tools.py` — pipeline
- `requirements.txt` — Python deps (HF installs these)
- `infosys-ar-25.pdf` — source document (BM25 reads it at startup)
- `table_store.json` — pre-extracted financial tables
- `finance_db/` — **pre-built ChromaDB vector store** (so the app does NOT re-index on boot)
- `README.md` — contains the HF Space config header
- `.gitignore`, `.env.example`

---

## Step 0 — Create a Hugging Face account (you have none)
1. Go to https://huggingface.co/join
2. Sign up (email + password, or Google/GitHub). Verify your email.

## Step 1 — Get a free Groq API key
1. Go to https://console.groq.com/keys → sign in → **Create API Key** → copy it.
   (Use a FRESH key — do not reuse one that was ever pasted into code/chat.)

## Step 2 — Create the Space
1. Go to https://huggingface.co/new-space
2. **Owner:** you · **Space name:** e.g. `finagent`
3. **License:** MIT (optional) · **SDK:** select **Streamlit**
4. **Hardware:** **CPU basic — FREE** (2 vCPU, 16 GB RAM — enough)
5. **Visibility:** Public (reviewers can open it) or Private (share access manually)
6. Click **Create Space**.

## Step 3 — Add your Groq key as a secret (NOT in code)
1. Open your Space → **Settings** → **Variables and secrets** → **New secret**
2. **Name:** `GROQ_API_KEY` · **Value:** your key → **Save**

## Step 4 — Upload the files
### Option A — Browser (simplest, no tools)
1. Space → **Files** tab → **Add file → Upload files**
2. Drag in **all files from this folder**, INCLUDING the `finance_db/` folder
   and the PDF. (The browser uploader handles the 54 MB sqlite fine.)
3. Commit. The Space auto-builds.

### Option B — Git (recommended for the large `finance_db/`)
```bash
# install git-lfs once: https://git-lfs.com  → then: git lfs install
git clone https://huggingface.co/spaces/<your-username>/finagent
cd finagent
# copy everything from this folder into the clone:
cp -r /Users/sumitsaurabh/Downloads/RAG/huggingface_deploy/. .
# track large binaries with LFS so the push succeeds
git lfs track "*.sqlite3" "*.bin" "*.pdf"
git add .gitattributes .
git commit -m "Deploy FinAgent"
git push
```
> If git asks for a password, use a **HF access token** (Settings → Access Tokens,
> role: write) as the password, not your account password.

## Step 5 — Watch it build
- Space page shows **Building** → **Running** (first build ~3–5 min: installs torch,
  then first request downloads ~1 GB of models, ~1–2 min).
- Your public URL: `https://huggingface.co/spaces/<your-username>/finagent`

## Step 6 — Test
Open the URL, click an example question, hit **Ask FinAgent**. An answer with page
citations should appear. Share the URL with your reviewer.

---

## Notes & safety
- **Key safety:** it lives only in the Space secret, never in the repo. On the Groq
  free tier (no card) the worst case is an exhausted daily quota — no money risk.
- **Protect your quota (optional):** keep the Space private, or add a password gate.
- **Sleeping:** free Spaces sleep after inactivity and wake on the next visit
  (~30–60 s cold start). Fine for a demo.