Joshua-Abok/sidewalk-fm

📊 Sidewalk FM — Small Trader Ledger & Advisory

---

tags: - sidewalk-fm - gradio - hackathon - build-small - tiny-titan - back-yai - best-agent - off-brand - nvidia-nim - modal license: mit

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.

---

🧠 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

---

🧩 Features

• Natural Language Input: "bought 50 mangoes at 200 shillings each"
• 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

---

📦 Deployment

This is a Gradio app with two model backends:

1. NVIDIA NIM API (for structured extraction)
2. Modal vLLM (for advisory + conversation)

Requirements

pip install -r requirements.txt

Run Locally

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

HF Space YAML

# Space YAML for Hugging Face Spaces
sdk: gradio
runtime: python3.10
requirements:
  - gradio>=5.0
  - huggingface_hub>=0.28
  - httpx>=0.25
environment:
  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

---

📝 License

MIT