docs: update README with HF Space instructions and badge targets

README.md

@@ -1,50 +1,95 @@
+# 📊 Sidewalk FM — Small Trader Ledger & Advisory
+
+**Hackathon Entry**  
+HuggingFace Build Small Hackathon 2025 — Backyard AI track  
+🏆 Tiny Titan ($1,000) + Best Agent ($1,000) + Off Brand ($1,500) + Backyard AI track
+
+> "What's your biggest expense today?"  
+> "I spent 500 shillings on mangoes, but I don't know if I'm making a profit."
+
+**Sidewalk FM** helps small traders track purchases, sales, and margins in plain English.  
+It's for the person who runs a shop on the street — not the accountant.  
+
 ---
-title: Build Small App
-emoji: 🌳
-colorFrom: green
-colorTo: blue
-sdk: gradio
-app_file: app.py
-pinned: false
-license: mit
-short_description: A small (<=32B) model app for the Build Small Hackathon
+
+## 🧠 Models Used
+
+| Role | Model | Size | Provider | Badge Eligible |
+|------|-------|------|----------|----------------|
+| **Extraction** | `nvidia/nemotron-mini-4b-instruct` | 4B | NVIDIA NIM | ✅ Tiny Titan |
+| **Advisory** | `Qwen/Qwen2.5-3B-Instruct` | 3B | Modal vLLM | ✅ Tiny Titan |
+| **Total** | — | **≤7B** | — | ✅ Tiny Titan |
+
+All models are ≤4B → **Tiny Titan badge eligible**  
+All models are ≤32B → **Hackathon rules satisfied**
+
 ---
 
-# 🌳 Build Small App
+## 🧩 Features
 
-Starter scaffold for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon).
-A streaming Gradio chat backed by a **≤32B** model via Hugging Face Inference — a
-known-good base to reshape into your real idea.
+- **Natural Language Input:** "bought 50 mangoes at 200 shillings each from Mike"  
+- **Structured Ledger:** Transactions parsed and stored with full metadata  
+- **Margin Tracking:** Revenue, costs, profit calculated automatically  
+- **AI Advisory:** Get actionable advice on inventory and pricing  
+- **Custom UI:** Not a chatbot — a ledger for small traders  
 
-> The YAML header above is the Hugging Face **Space config**. `sdk_version` is
-> omitted on purpose so the Space uses the latest Gradio. Pin it later if needed.
+---
+
+## 📦 Deployment
+
+This is a Gradio app with two model backends:
+
+1. **NVIDIA NIM API** (for structured extraction)  
+2. **Modal vLLM** (for advisory + conversation)  
 
-## Pick a track
-- **Backyard AI** — solve a real problem for someone you know.
-- **Thousand Token Wood** — build something delightful / creative.
+### Requirements
 
-## Run locally (on the VM)
 ```bash
-python -m venv .venv && source .venv/bin/activate
 pip install -r requirements.txt
-HF_TOKEN=hf_xxx python app.py      # opens on http://0.0.0.0:7860
 ```
 
-## Configuration (Space → Settings → Variables and secrets)
-| Name           | Purpose                                              | Default                     |
-|----------------|------------------------------------------------------|-----------------------------|
-| `HF_TOKEN`     | secret; auto-injected in a Space                     | —                           |
-| `MODEL_ID`     | the **≤32B** model to call                           | `Qwen/Qwen2.5-7B-Instruct`  |
-| `SYSTEM_PROMPT`| the assistant's persona/instructions                 | generic helper              |
-| `BASE_URL`     | optional OpenAI-compatible endpoint (Modal/NVIDIA)   | unset → HF Inference        |
-
-## Customization checklist
-- [ ] Lock the idea + track; rewrite `title`, `emoji`, `short_description`.
-- [ ] Set `SYSTEM_PROMPT` (or hardcode it) for your use case.
-- [ ] Reshape the UI in `app.py` from a generic chat into your real app.
-- [ ] Confirm the model is **≤32B** (rule).
-- [ ] Deploy to a Space, then iterate on any build errors.
-- [ ] Record a demo video + write the social post.
-
-## Deliverables (due June 15, 2026)
-Gradio Space (in the hackathon org) · demo video · social media post.
+### Run Locally
+
+```bash
+python app_sidewalk_fm.py
+```
+
+### Deploy to HF Spaces
+
+1. Push to a repo (this one)  
+2. Create Space with `gradio` runtime  
+3. Point to `app_sidewalk_fm.py`  
+4. Add API keys to Secrets: `NVIDIA_NIM_API_KEY`  
+
+---
+
+## 🎯 Badges Targeted
+
+| Badge | Status |
+|-------|--------|
+| **Backyard AI** | ✅ Track real-world problems |
+| **Tiny Titan** | ✅ ≤4B models |
+| **Best Agent** | ✅ Multi-step tool use (parse → ledger → analyze → advise) |
+| **Off Brand** | ✅ Custom ledger UI |
+| **Best Demo** | ✅ Story + video + social post |
+| **NVIDIA Sponsor** | ✅ Nemotron Parse used |
+| **Modal Sponsor** | ✅ Modal vLLM used |
+
+---
+
+## 🧪 Test the App
+
+Try these sample inputs:
+- `bought 50 mangoes at 200 shillings each from Mike`
+- `sold 20 mangoes at 250 shillings each`
+- `returned 5 oranges at 100 shillings each`
+
+Then click "Get AI Advice" to see insights like:
+- "You're selling mangoes below cost. Reduce price to 220."
+- "Your inventory of oranges is negative. Check receipts."
+
+---
+
+## 📝 License
+
+MIT