Predict 30-day daily transaction volume with festival-aware patterns, simulating ₹18,000 annual savings per merchant across 500 test kirana stores.
| Hero & Stats | Historical Charts |
|---|---|
 |
 |
| Forecast | Alerts & Surge Detection |
|---|---|
 |
 |
| Savings Simulator | Full Dashboard |
|---|---|
 |
 |
A full walkthrough video is available at assets/demo_video.mp4.
Try it instantly — the app has a built-in Demo Mode that generates NPCI-calibrated synthetic data. No CSV needed to explore all features.
PulseCast accepts UPI merchant transaction CSVs. You can use any of these sources:
A ready-to-use sample is bundled in the repo:
assets/sample_upi_transactions.csv (9,717 transactions · 8 months · kirana store)
Format preview:
Transaction Date,Amount,Status,Merchant,Payment Mode,UTR
2025-06-01 09:37:00,59.93,SUCCESS,Kirana Store Demo,UPI,UTR134126396
2025-06-01 20:14:00,90.70,SUCCESS,Kirana Store Demo,UPI,UTR732719211
2025-06-01 17:17:00,137.37,SUCCESS,Kirana Store Demo,UPI,UTR331191390Download your real transaction history from any UPI app:
| App | How to Export |
|---|---|
| PhonePe | Profile → Transaction History → Download Statement (CSV) |
| Google Pay | Activity → All Transactions → Export |
| Paytm | Passbook → Statement → Download |
| Any UPI app | Look for "Download Statement" or "Export Transactions" |
Search for UPI/digital payment datasets on Kaggle:
- UPI Transactions Dataset — search "UPI transactions India"
- Digital Payments India — search "digital payments merchant"
- NPCI UPI Statistics — aggregate monthly volumes (for calibration reference)
The built-in synthetic generator creates realistic data:
# Via API
curl http://127.0.0.1:8000/api/demo?merchant_type=kirana&history_days=365
# Or just use Demo Mode in the Streamlit dashboardThe auto-detect parser handles most formats. Minimum required columns:
| Column | Required | Aliases Accepted |
|---|---|---|
| Date | ✅ | date, timestamp, txn_date, transaction_date, created_at, payment_date |
| Amount | ✅ | amount, value, txn_amount, total, paid, price, debit, credit |
| Status | Optional | status, txn_status, state, result (filters to SUCCESS only) |
Supported delimiters: , \t ; | — auto-detected.
Date formats: YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY, YYYY-MM-DD HH:MM:SS, and more.
| Paper / Source | Key Idea Used | Where Applied |
|---|---|---|
| TimesFM (arXiv:2310.10688, ICML 2024) | Zero-shot forecasting via patched-decoder transformer, 200M params | Core forecasting engine (CP3) |
| Holiday Intervention Analysis (JDMDC 2024) | Binary holiday indicators as exogenous variables; pre/post-holiday modeling | Festival covariate features |
| Fourier Features (Prophet / N-BEATS) | Cyclical encoding of day-of-week and month-of-year | Seasonal covariates |
| NPCI UPI Statistics | Real UPI volume/value trends, P2P vs P2M breakdowns | Synthetic data calibration |
# Clone & setup
git clone https://github.com/sohamukute/PulseCast.git
cd PulseCast
cp .env.example .env
# Edit .env → add CALENDARIFIC_API_KEY (free: https://calendarific.com/signup)
# Create virtual environment
python3 -m venv .venv && source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Start the backend
uvicorn backend.main:app --reload &
# Run Streamlit dashboard
PYTHONPATH=$PWD streamlit run frontend/app_v2.pyOpen http://localhost:8501 in your browser. The demo mode runs automatically — no setup needed.
PulseCast/
├── backend/
│ ├── main.py # FastAPI entry + CORS
│ ├── config.py # Pydantic Settings (reads .env)
│ ├── middleware.py # Request logging & timing
│ ├── routers/ # API endpoints (13 routes)
│ │ ├── upload.py # CSV upload with auto-detect
│ │ ├── forecast.py # TimesFM forecast (CP3)
│ │ ├── insights.py # BI & alerts (CP4)
│ │ ├── demo.py # Synthetic data demo
│ │ └── festivals.py # Festival API proxy
│ ├── services/
│ │ ├── csv_parser.py # Auto-detect CSV format
│ │ ├── forecaster.py # TimesFM wrapper (CP3)
│ │ ├── festival_api.py # Calendarific + Nager.Date
│ │ ├── features.py # Fourier + holiday covariates
│ │ ├── salary_detection.py # Dynamic salary-day detection
│ │ └── intelligence.py # BI metrics (CP4)
│ └── data/
│ └── synthetic.py # NPCI-calibrated generator
├── frontend/
│ ├── app_v2.py # Streamlit dashboard (Soft-Pop theme)
│ ├── theme.py # Soft-Pop CSS theme system
│ ├── api_client.py # REST client for backend
│ ├── charts.py # Plotly visualizations (8 chart types)
│ ├── widgets.py # Reusable UI components (14 widgets)
│ ├── app.py # Legacy dashboard
│ └── components/ # Legacy components
├── tests/ # 186 unit + 70 E2E tests (256 total)
├── assets/ # Screenshots, demo video, sample CSV
├── .env.example # API key template
├── requirements.txt
├── Dockerfile
└── README.md
- Zero hardcoded data: Festivals come from live APIs, salary-day spikes are auto-detected
- Dynamic everything: Impact metrics computed from each merchant's actual data
- NPCI-calibrated synthetics: Statistical distributions match real UPI P2M patterns
- Robust fallback chain: Calendarific → Nager.Date → cached last-known
- Soft-Pop theme: Custom CSS theme with indigo/teal/amber palette for clean visual hierarchy
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Server health & engine status |
GET |
/api/demo |
Generate synthetic merchant data |
POST |
/api/upload |
Upload & parse UPI CSV |
POST |
/api/forecast |
Run TimesFM forecast |
POST |
/api/insights |
Business intelligence metrics |
POST |
/api/alerts |
Predictive alerts engine |
POST |
/api/pipeline |
Full orchestrated pipeline |
POST |
/api/compare |
Multi-merchant comparison |
GET |
/api/festivals |
Festival calendar (live API) |
POST |
/api/export |
Export report (JSON/CSV) |
POST |
/api/clear-cache |
Clear LRU cache |
Interactive API docs: http://localhost:8000/docs
| Layer | Technology | Why |
|---|---|---|
| Forecasting | TimesFM 2.0 (PyTorch) | Zero-shot, no training, ICML 2024 |
| Backend | FastAPI 2.0 | Async, auto-docs, CORS |
| Frontend | Streamlit 1.54 | Rapid prototyping, free hosting |
| Theme | Soft-Pop (tweakcn) | Custom CSS — indigo/teal/amber palette |
| Charts | Plotly | Interactive, publication-quality |
| Festival Data | Calendarific + Nager.Date | Dynamic, no hardcoding |
| Testing | Pytest | 256 tests (186 unit + 70 E2E) |
| Storage | In-memory + LRU cache | Zero-config |
# Run all 256 tests
PYTHONPATH=$PWD pytest tests/ -v
# Unit tests only (186)
PYTHONPATH=$PWD pytest tests/ -v -k "not e2e"
# E2E tests only (70) — requires backend running
PYTHONPATH=$PWD pytest tests/ -v -k "e2e"Built UPI merchant cash flow forecasting app using TimesFM (ICML 2024), predicting 30-day transaction volume with festival-aware patterns via dynamic holiday intervention analysis, simulating ₹18,000 annual savings per merchant across 500 test kirana stores