DEPLOY.md

Deploying FinChat to Hugging Face Spaces

A free, step-by-step guide to putting FinChat online with a public link.

---

0. Before you start

1. Rotate your Groq API key. Go to https://console.groq.com → API Keys → create a new key. You'll paste the new key into the Space as a secret (never commit it).
2. Create a free Hugging Face account: https://huggingface.co/join.
3. Make sure git is installed (it is on this machine).

---

1. Create the Space

1. Go to https://huggingface.co/new-space.
2. Owner: you. Space name: finchat.
3. SDK: choose Streamlit.
4. Hardware: CPU basic (free). Visibility: Public.
5. Click Create Space. You now have an empty Space repo.

---

2. Add your API key as a secret

In your Space: Settings → Variables and secrets → New secret

• Name: GROQ_API_KEY
• Value: your Groq key

The app reads this automatically (os.getenv("GROQ_API_KEY")), so no .env is needed on the Space.

---

3. Push the code

From the project root:

git init
git add .
git commit -m "FinChat: RAG chatbot over SEC 10-K filings"

# Connect to your Space (replace <username>)
git remote add space https://huggingface.co/spaces/<username>/finchat
git push space main

.gitignore already excludes .env, venv/, data/, and vectorstore/, so your key and large files stay out of the repo.

The Space will build (install requirements.txt) and start. On first load, the app builds the vector store itself (downloads the dataset + embeds the chunks). On free CPU this takes roughly 5–8 minutes the first time — the UI shows "Preparing the knowledge base…". After that it's fast.

---

4. (Optional) Instant cold starts — commit the prebuilt index

Free Spaces sleep after inactivity and rebuild the index on wake (~5–8 min), which is slow for someone clicking your link cold. To make cold starts instant, commit the prebuilt vector store using git-lfs (it's ~66 MB).

# One-time: install git-lfs from https://git-lfs.com then:
git lfs install

# Copy the prebuilt store into the repo
mkdir vectorstore
cp -r ~/.finchat/vectorstore/* vectorstore/     # Windows: xcopy /E /I %USERPROFILE%\.finchat\vectorstore vectorstore

# Track the large binary files with LFS
git lfs track "vectorstore/**"
git add .gitattributes

# Stop ignoring the committed store, then commit it
#   -> remove the "vectorstore/" line from .gitignore first
git add vectorstore .gitignore
git commit -m "Add prebuilt vector store for instant startup"
git push space main

Then, in the Space Settings → Variables and secrets, add a variable (not a secret):

• Name: FINCHAT_VECTORSTORE
• Value: vectorstore

Now ensure_index() finds the committed store and skips the rebuild entirely.

---

5. Verify

1. Open your Space URL.
2. Wait for the first load (see the spinner if it's building).
3. Ask: "What are AMD's main business risks?" — you should get a grounded answer with a Sources panel and a routing badge.
4. Add the live link to the top of README.md and to your portfolio.

---

Troubleshooting

Symptom	Fix
GROQ_API_KEY is not set	Add the secret (Step 2) and Restart the Space.
Build error on datasets	Confirm requirements.txt pins datasets<3.0.
Stuck on "Preparing the knowledge base"	First build is slow on free CPU; wait, or use Step 4.
Sidebar hidden	Click the › at the top-left to expand it.