Upload README.md with huggingface_hub

README.md

@@ -5,13 +5,9 @@ An end-to-end multi-domain AI forecasting system. Real datasets, two model modes
 ## Models: separate vs unified
 
 - **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
+- **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
 
-```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
-```
+The unified model merges weights from all 6 trained separate models into a single checkpoint, enabling cross-domain knowledge transfer and a single model that can predict any of the 6 topics.
 
 ## Topics & datasets (all real, fetched automatically)
 
@@ -24,8 +20,7 @@ python ask.py "compare all topics"               # chat uses unified automatical
 | **Weather** | Daily mean temperature (any city) | Open-Meteo archive | 4,248 |
 | **Economy** | S&P 500 daily close | Yahoo Finance | 6,699 |
 
-- 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.
+Weather city is configurable. Every topic falls back gracefully: Hugging Face search -> API -> synthetic data if fully offline.
 
 ## Configs
 
@@ -48,7 +43,7 @@ All configuration files are in the `configs/` folder:
 | 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%** |
+| 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% |
 
@@ -67,46 +62,29 @@ All configuration files are in the `configs/` folder:
 
 ## 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)
-```
+User question -> intent detection -> prediction engine -> response formatter -> chat output
 
-- `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
+- Chat CLI — only the final assistant response reaches the user
+- Intent detection + orchestration (topic, location, horizon, style)
+- Prediction engine — runs the LSTM, returns structured metrics: net change, forecast range, current-to-forecast, direction, primary forecast
+- Response formatter — presents metrics naturally; opens with a one-sentence ChatGPT-style summary; never invents confidence, probability, or values
+- Multi-topic data pipeline (fetchers + caching)
+- 2-layer LSTM, Huber loss, AdamW, early stopping, temporal split
+- Per-topic model loader, rollout forecast, chart + text report
 
 ## 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
-```
+Interactive chat with natural language queries:
+- "what will bitcoin do next week?"
+- "compare all topics"
+- "predict programming for 14 days"
+- "predict ai for 3 days"
 
 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
@@ -123,37 +101,19 @@ This is a model-generated forecast, and actual market behavior may differ.
 
 ## 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"
-```
+Configure city via environment variables or city registry, then query weather predictions.
 
 ## 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
-```
-
-Outputs: `model_<topic>.pt`, `configs/config_<topic>.json`, `prediction_<topic>.png`, `prediction_<topic>.txt`, `results.json`.
+Run training for all topics or individual domains. Outputs: model checkpoints, configs, predictions, charts, and results.
 
 ## Add a new domain
 
-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
+1. Add entry to topics configuration (label, unit, asset name)
+2. Add a fetcher returning date + value columns
+3. Run training — everything else is automatic
 
 ## 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")
-```
+**https://huggingface.co/CodeDevX/future-prediction-multi-domain-lstm**