LA Tech Rising | Spring 2026 | Mentor: Ritesh Verma
A reusable retail forecasting engine that ingests historical sales data, forecasts future demand, flags unusual patterns, and generates plain-English summaries using the Gemini API.
Live demo: inventory-iq-dun.vercel.app · API docs: inventoryiq-api.onrender.com/docs
| Role | Name | Primary Ownership |
|---|---|---|
| Project Lead · Architecture & Infrastructure | Mira Bhakta | System design, model selection, testing suite, CI/CD, deployment, cross-role debugging |
| Co-Project Lead · Alerting Engine · Forecasting Co-Owner | James Ybarra | models/alerter.py, utils/forecasting.py (co-owner) |
| Data Preparation & Schema Mapping · Dashboard Support | Andrew Garcia Leopold | utils/processor.py - schema mapping + derived fields |
| Data Preparation (Derived Fields) · AI Insights Support | Krisna Vega | utils/trend.py + derived fields in processor.py |
| Forecasting Engine · Alerting Co-Owner | Alberto Barboza | utils/forecasting.py, models/alerter.py (co-owner) |
| AI Insights & Reporting · Dashboard Support | Sarah Abdeen | utils/ai_summary.py + dashboard AI summary panel |
| Dashboard & Visualization · Integration Lead | Justin Hernandez | frontend/src/pages/DashboardPage.jsx — views, sidebar, filters, layout, loading states |
- Python
- FastAPI
- Uvicorn
- pandas
- NumPy
- scikit-learn
- LightGBM
- Google Gen AI SDK
- python-dotenv
- openpyxl
- React 19
- Vite
- React Router DOM
- Axios
- Recharts
api/ FastAPI route layer
services/ Forecast orchestration and response shaping
models/ Alert engine
utils/ Cleaning, schema mapping, forecasting, Gemini summary
frontend/ React + Vite dashboard
data/ Small demo dataset (regenerate with scripts/)
tests/ Backend pytest suite
git clone https://github.com/mirabhakta/inventoryIQ.git
cd inventoryIQUse Python 3.11 or 3.12. Python 3.14 may fail with older pinned dependencies on Windows.
python -m venv venvActivate the virtual environment:
Windows PowerShell
venv\Scripts\Activate.ps1macOS/Linux
source venv/bin/activateInstall backend dependencies:
pip install -r requirements.txtCreate a .env file in the project root (start from the committed template):
cp .env.example .envGEMINI_API_KEY=your_api_key_hereRun the backend:
uvicorn main:app --reloadThe backend should start at:
http://localhost:8000- API docs:
http://localhost:8000/docs
Run the backend tests:
pip install -r requirements-dev.txt
pytestOpen a second terminal and run:
cd frontend
npm ci
npm run devThe frontend should start at:
http://localhost:5173
If the API is not running on localhost:8000, copy frontend/.env.example to
frontend/.env.local and change VITE_API_BASE_URL.
You need two terminals:
- Backend
uvicorn main:app --reload- Frontend
cd frontend
npm run devUpload data/sample_sales.csv on the upload page. It contains 1,800 rows
across three stores and five products, with a planted demand decline, a
low-margin product, and a one-day sales spike so the dashboard and alert panel
have real signals to show.
Regenerate it at any time with:
python scripts/generate_sample_data.pyThe API ships as a Docker image and the UI as a Vite static build. The included
render.yaml and frontend/vercel.json deploy both services with a health check,
an explicit CORS allowlist, and SPA routing.
See DEPLOY.md for the Render + Vercel steps, environment variables, and the post-deploy checklist.
- Upload retail CSV or Excel (
.xlsx) files up to 10 MB / 200,000 rows - Fuzzy schema mapping for common column names (
OrderDate,Sales Amnt,Units_Sold…) - LightGBM demand forecasts for 30, 90, or 180 days, computed from the daily total so large uploads stay fast
- Model accuracy comparison (MAE, RMSE, MASE) on uploads up to 5,000 rows / 50 series
- Store-level alerts for sales anomalies, demand declines, and margin losses
- Plain-English Gemini summary on demand; the app stays fully usable without a key
- Server-side filters by store, category, region, and forecast horizon
POST /analyzedecodes the upload, maps columns to the shared schema, applies filters, and returns KPIs, monthly history, product/store/category rankings, an aggregated forecast, alerts, and — for smaller uploads — the model benchmark in one response.- The React dashboard renders that payload directly. Changing a filter re-runs
/analyzewith the same file, and in-flight requests are cancelled so stale responses never win. POST /summarysends the current metrics to Gemini only when the user asks for a summary.
Large files are expected: the dashboard forecast uses one daily-total series, and the expensive four-model benchmark is skipped above 5,000 rows / 50 series with a note in the UI.
| Products | Analysis |
|---|---|
![]() |
![]() |
Never commit your .env file. It is excluded from version control via .gitignore.
Start from .env.example instead. If a key is accidentally exposed, revoke it
immediately in the Gemini console and generate a new one.
The AI summary is optional. Without GEMINI_API_KEY, the dashboard shows a clear
configuration message instead of failing.
MIT — see LICENSE.



