Chaouesrex/ispaza1

AI advisor for South African spaza shop owners — IEB TechWays AI Hackathon 2026 # iSpaza — AI Advisor for Spaza Shop Owners > **Better decisions today. Banking tomorrow.** A Streamlit demo built for the **IEB TechWays AI Hackathon 2026** under the *Cross-Border Trade & Informal Economy* category. iSpaza is an advisor for South African spaza shop owners. The owner enters their current stock and last week's sales, and the app returns three things: what to restock, what to reprice, and one new product to try. Every weekly interaction is saved into a persistent "iSpaza Ledger" — over months, this becomes alternative credit history the owner can show to partner banks. --- ## Quickstart ```powershell # 1. Create a virtual environment (recommended) python -m venv .venv .\.venv\Scripts\Activate.ps1 # 2. Install pip install -r requirements.txt # 3. Run streamlit run app.py ``` That's it — **no API key, no `.env` file, no internet required at the venue.** Open the URL Streamlit prints (default: localhost). --- ## What's in the box ``` ispaza/ ├── app.py # Streamlit UI (single entry point) ├── advisor.py # Local recommender — the demo's "brain" ├── core.py # Pure helpers (prompt builder, parser, ledger) ├── prompts.py # SYSTEM_PROMPT (reference for the production path) ├── data/ │ └── benchmarks.json # Township pricing benchmarks (10 products) ├── tests/ │ ├── conftest.py │ ├── test_core.py # Tests on the pure logic + parser + ledger │ ├── test_advisor.py # Tests on the local recommender │ └── test_prompts.py # Sanity tests on the system prompt ├── .streamlit/config.toml # Brand colours (SA green + accent yellow) ├── requirements.txt └── README.md ``` The pure-logic helpers live in `core.py` and `advisor.py` so the entire recommender can be unit-tested without launching Streamlit. `app.py` is the thin UI layer on top. --- ## How the "AI" works in the demo The demo's brain is **deterministic, runs locally**, and uses real analysis on the own …