adding timesfm project and exceptions on gitignore

timesfm-forecast/README.md

@@ -0,0 +1,130 @@
+
+# TimesFM Forecast (Streamlit, OOP)
+
+A maintainable, OOP-based Streamlit app to forecast multiple time series (by `key`) using **TimesFM**.
+
+- Upload CSV with columns: `date`, `value`, `key`
+- Select a **horizon range** (e.g., 1–12)
+- App uses **all data as training** (no holdout)
+- **Progress bar** while forecasting
+- **Download** CSV with forecasts (`key, date, step, forecast`)
+- Clean separation between UI and core logic
+
+---
+
+## 🚀 Quickstart (using `uv`)
+
+> Requires Python **3.10+**.  
+> `uv` docs: https://docs.astral.sh/uv/
+
+```bash
+# 1) Clone
+# (If you already downloaded this folder locally, cd into it and skip clone.)
+# git clone https://github.com/<your-org>/timesfm-forecast.git
+cd timesfm-forecast
+
+# 2) Create a virtualenv (managed by uv)
+uv venv
+source .venv/bin/activate  # Windows: .venv\Scriptsctivate
+
+# 3) Install dependencies (editable mode)
+uv pip install -e .
+
+# 4) Run the app
+uv run timesfm-app
+# or directly:
+# uv run streamlit run src/timesfm_app/ui/app.py
+```
+
+Open the URL shown in your terminal (typically http://localhost:8501).
+
+---
+
+## 📦 CSV Format
+
+Upload a CSV with **columns**:
+
+- `date` – a date per observation (the app prefers `dd/mm/yyyy`, but will try general parsing)
+- `value` – numeric target
+- `key` – series identifier (one forecast per `key`)
+
+Example: [examples/sample.csv](examples/sample.csv)
+
+---
+
+## ⚙️ Configuration (in the UI)
+
+- **TimesFM model**: defaults to `google/timesfm-2.0-500m-pytorch`
+- **Device**: `cuda` if available, otherwise `cpu`
+- **Frequency code (TimesFM)**: defaults to **2 = monthly** (matches your original draft)
+- **Fallback pandas frequency**: used to create future dates if per-key inference fails (`D,W,M,Q,Y`)
+- **Batch size**: controls throughput vs memory
+- **Horizon range**: inclusive range (e.g., 1..12). Output includes each step with its aligned date.
+
+> The app uses `pandas.infer_freq` to detect per-key frequency; if inference fails, it falls back to your selection.
+
+---
+
+## 🧠 Design / OOP
+
+- `TimesFMService` – encapsulates model loading + batch inference.
+- `ForecastPipeline` – orchestrates validation, batching, inference, and future index construction. Returns a **long** DataFrame:
+  - `key, date, step, forecast`
+- `DataValidator` / `FrequencyHelper` – stateless utility classes.
+- `ui/app.py` – Streamlit-only, thin UI.
+
+This structure makes it straightforward to add more backends (e.g., Prophet, Chronos) by introducing a new service class.
+
+---
+
+## 🧪 Tests
+
+Install dev extras and run:
+
+```bash
+uv pip install -e ".[dev]"
+uv run pytest
+```
+
+We provide a minimal test (`tests/test_pipeline.py`) that injects a **fake service** to validate pipeline behavior without loading a real model.
+
+---
+
+## 🖥️ GPU vs CPU (PyTorch)
+
+By default, this project depends on `torch` without a pinned wheel. If you need a **CUDA** build, install the wheel for your CUDA version. Examples:
+
+```bash
+# CUDA 12.1 (example)
+uv pip install torch --index-url https://download.pytorch.org/whl/cu121
+
+# CPU-only (explicit)
+uv pip install torch --index-url https://download.pytorch.org/whl/cpu
+```
+
+Then run the app and select **Device = cuda** in the sidebar. Make sure your NVIDIA drivers & CUDA runtime match the wheel.
+
+---
+
+## 📝 Output
+
+You can download a CSV with columns:
+
+- `key` – series id
+- `date` – predicted timestamp (aligned to step)
+- `step` – horizon (1..H)
+- `forecast` – mean prediction
+
+---
+
+## 🧯 Troubleshooting
+
+- **Model download slow / blocked**: the first run downloads the model weights from Hugging Face. Ensure internet connectivity and retry. You can also pre-download the model to your HF cache.
+- **Out-of-memory on GPU**: reduce `Batch size`, or switch **Device** to `cpu`.
+- **Dates misaligned**: pick the correct fallback pandas frequency (e.g., `M` for monthly) if your data has irregular gaps that prevent inference.
+
+---
+
+## 📄 License
+
+MIT