Upload README.md with huggingface_hub

README.md

@@ -1,69 +1,159 @@
----
-license: mit
-library_name: pytorch
-tags:
-- time-series
-- forecasting
-- lstm
-- multi-task
-- multi-domain
-pipeline_tag: time-series-forecasting
----
+# Future Prediction Models (6 topics + Unified)
 
-# Future Prediction Models (Multi-Domain LSTM)
+An end-to-end multi-domain AI forecasting system. Real datasets, two model modes, ChatGPT-style predictions.
 
-Trained PyTorch LSTM checkpoints forecasting 7 daily time-series domains (AI/NVIDIA, Programming/npm, Finance/BTC, Sports/ATP Elo, Weather, Economy/S&P500, Energy/WTI).
+## Models: separate vs unified
 
-Trained with a leak-free protocol: chronological TRAIN/VALIDATION/TEST splits, validation-only early stopping and tuning, untouched test set, and walk-forward backtesting as the headline metric.
+- **Separate** (`model_<topic>.pt`) — 6 dedicated 2-layer LSTMs, one per topic
+- **Unified** (`unified_model.pt`) — ONE combined model for all 6 domains: shared LSTM backbone + per-domain embedding + per-domain heads, trained jointly from merged separate models
 
-## Checkpoints
+```powershell
+python train_unified.py                          # train the single combined model
+python predict.py --topic finance --mode unified # query it for any topic
+python ask.py "compare all topics"               # chat uses unified automatically when available
+```
+
+## Topics & datasets (all real, fetched automatically)
+
+| Topic | Asset | Source | Points |
+|---|---|---|---|
+| **AI** | NVIDIA daily close | Yahoo Finance | 6,938 |
+| **Programming** | Daily `react` npm downloads | npm registry API | 547 |
+| **Finance** | Bitcoin BTC-USD close | Yahoo Finance (Hugging Face fallback) | 4,252 |
+| **Sports** | ATP world #1 Elo rating | Hugging Face tennis (93,028 matches, Elo computed from results) | 10,944 |
+| **Weather** | Daily mean temperature (any city) | Open-Meteo archive | 4,248 |
+| **Economy** | S&P 500 daily close | Yahoo Finance | 6,699 |
 
-All models predict 7 steps from a 60-step window. Inputs are 7 causal features per timestep: base-relative value, 1-step return, MA7 ratio, MA30 ratio, 7-step volatility, day-of-week sin/cos.
+- Weather city is configurable: set env vars `WEATHER_NAME` / `WEATHER_LAT` / `WEATHER_LON`, or add cities to `weather_cities.py` (Chennai, Mumbai, Delhi, London, Tokyo, ... included).
+- Every topic falls back gracefully: Hugging Face search -> API -> synthetic data if fully offline.
 
-| File | Architecture |
-|---|---|
-| `unified_model.pt` | Multi-task: shared LSTM (128 hidden, 2 layers) + domain embedding (16) + 7 heads; domains: ai, programming, finance, sports, weather, economy, energy |
-| `model_ai.pt` | LSTM 64 hidden, 2 layers |
-| `model_programming.pt` | LSTM 64 hidden, 2 layers |
-| `model_finance.pt` | LSTM 64 hidden, 2 layers |
-| `model_sports.pt` | LSTM 64 hidden, 2 layers |
-| `model_weather.pt` | LSTM 64 hidden, 2 layers |
-| `model_economy.pt` | LSTM 64 hidden, 2 layers |
-| `model_energy.pt` | LSTM 64 hidden, 2 layers |
+## Configs
 
-## Honest performance (walk-forward backtest vs naive persistence)
+All configuration files are in the `configs/` folder:
+- `configs/config_ai.json`
+- `configs/config_finance.json`
+- `configs/config_economy.json`
+- `configs/config_programming.json`
+- `configs/config_sports.json`
+- `configs/config_weather.json`
+- `configs/unified_config.json` (original unified training config)
+- `configs/unified_config_merged.json` (merged from 6 separate models)
 
-Positive = model beats "tomorrow equals today" baseline.
+## Validated accuracy (held-out test set, no data leakage)
 
-| Topic | vs naive (separate) | vs naive (unified) | Verdict |
+**Separate per-topic models:**
+
+| Topic | MAE | H1 MAPE | vs naive baseline |
 |---|---|---|---|
-| Programming | +71% | +68% | Real edge (weekly seasonality) |
-| AI | +2.3% | +1.6% | Small edge |
-| Energy | +1.8% | +0.9% | Small edge |
-| Economy | +0.3% | +2.0% | Marginal |
-| Weather | -1.3% | -0.2% | No edge |
-| Finance | -4.3% | -2.3% | Trails naive |
-| Sports | -11.9% | -22.8% | Trails naive |
+| AI (NVIDIA) | $2.17 | 2.26% | ~naive |
+| Economy (S&P 500) | $37.37 | 0.71% | beats naive by 0.5% |
+| Finance (Bitcoin) | $1,437.46 | 1.61% | ~naive |
+| Programming (react) | 1.17M downloads | 7.12% | **beats naive by 77.5%** |
+| Sports (ATP #1 Elo) | 3.40 Elo | 0.06% | ~naive |
+| Weather (Chennai temp) | 0.99 K | 0.18% | beats naive by 1.9% |
 
-Directional accuracy is ~50-55% on financial series (barely better than chance). Sports direction is mostly undefined because Elo is flat on no-match days.
+**Unified single model (merged from 6 separate models):**
 
-## Loading
+| Topic | MAE | H1 MAPE |
+|---|---|---|
+| AI | $3.40 | 2.36% |
+| Economy | $72.21 | 0.75% |
+| Finance | $2,863.45 | 1.74% |
+| Programming | 1.14M downloads | 5.42% |
+| Sports | 2.75 Elo | 0.04% |
+| Weather | 0.94 K | 0.18% |
 
-```python
-import torch
+> Markets behave near a random walk, so 100% accuracy is impossible — these are honest, validated numbers. No model can guarantee the future.
+
+## Architecture (normal mode shows only the final response)
+
+```
+user question -> intent detection (response.py)
+              -> prediction_engine.py   (structured metrics, prints nothing)
+              -> response_formatter.py  (natural summary + Markdown, no internal details)
+              -> ask.py                 (chat_output, stdout)
+```
+
+- `ask.py` — chat CLI; only the final assistant response reaches the user
+- `response.py` — intent detection + orchestration (topic, location, horizon, style)
+- `prediction_engine.py` — runs the LSTM, returns distinct metrics:
+  `net_change_pct` (path change), `forecast_range_pct` (path min-max range),
+  `current_to_forecast_pct` (vs latest observed value), `direction`
+  (rising/falling/sideways, configurable threshold), `primary_forecast`
+  (end-of-horizon value)
+- `response_formatter.py` — presents metrics naturally; opens with a one-sentence
+  ChatGPT-style summary; never invents confidence, probability, or values
+- `debug_logger.py` — internal logs go to stderr only when `FORECAST_DEBUG=1` (or `--debug`)
+- `data.py` — multi-topic data pipeline (fetchers + caching to `data/<topic>.csv`)
+- `weather_cities.py` — city registry for location-specific weather models
+- `model.py` / `train.py` — 2-layer LSTM, Huber loss, AdamW, early stopping, temporal split
+- `predict.py` — per-topic model loader, rollout forecast, chart + text report
+- `multi.py` — trains + evaluates all topics; quiet in normal mode
+
+## Ask it anything (ChatGPT-style)
+
+```powershell
+.\.venv\Scripts\python.exe ask.py                                 # interactive chat
+.\.venv\Scripts\python.exe ask.py "what will bitcoin do next week?"
+.\.venv\Scripts\python.exe ask.py "compare all topics"
+.\.venv\Scripts\python.exe ask.py --detailed "predict programming for 14 days"
+.\.venv\Scripts\python.exe ask.py --debug "predict ai for 3 days" # internal logs on stderr
+```
+
+Example response:
+
+```
+In short, the model expects Bitcoin to stay roughly stable next week, hovering near $63,228.
+
+Bitcoin Forecast
+
+August 18-24, 2026
+
+The model forecasts relatively sideways movement for Bitcoin next week, with an
+estimated level around **$63,228**.
+
+Outlook: Sideways
+Predicted level (2026-08-24): ~$63,228
+Expected change: <0.01%
+Forecast range: <0.01%
+From latest observed value ($63,229, 2026-08-17): <0.01%
+
+This is a model-generated forecast, and actual market behavior may differ.
+```
 
-model = torch.load("model_ai.pt", weights_only=False)
-model.eval()
-x = torch.randn(1, 60, 7)          # last 60 steps of the 7 causal features
-pred = model(x)                    # (1, 7) predicted returns over next 7 steps
+## Weather for any city
+
+```powershell
+$env:WEATHER_NAME='Chennai, India'; $env:WEATHER_LAT='13.0827'; $env:WEATHER_LON='80.2707'
+.\.venv\Scripts\python.exe data.py --topic weather --refresh
+.\.venv\Scripts\python.exe train.py --topic weather --epochs 150
+.\.venv\Scripts\python.exe ask.py "predict weather in chennai tomorrow"
+```
+
+## Train / refresh
+
+```powershell
+.\run_all.ps1                        # everything (default topics)
+.\.venv\Scripts\python.exe multi.py  # all topics
+.\.venv\Scripts\python.exe train.py --topic sports
+.\.venv\Scripts\python.exe predict.py --topic ai --days 14
 ```
 
-## Notes
+Outputs: `model_<topic>.pt`, `configs/config_<topic>.json`, `prediction_<topic>.png`, `prediction_<topic>.txt`, `results.json`.
 
-- Forecasts are statistical estimates; no model predicts the future reliably.
-- Uncertainty bands shipped with predictions come from validation residual std (+/-1.96 sigma), not invented confidence.
-- Where the model does not beat the persistence baseline, that is reported rather than hidden.
+## Add a new domain
 
-## License
+1. Add an entry to `TOPICS` in `data.py` (label, unit, asset name)
+2. Add a fetcher returning `{source, series}` (date + value columns) to `FETCHERS`
+3. Run `python train.py --topic <name>` — everything else is automatic
 
-MIT
+## Hugging Face Repository
+
+All models and configs are available at:
+**https://huggingface.co/CodeDevX/future-prediction-multi-domain-lstm**
+
+Download with:
+```python
+from huggingface_hub import hf_hub_download
+model_path = hf_hub_download("CodeDevX/future-prediction-multi-domain-lstm", "model_ai.pt", repo_type="model")
+```