# 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

⚙️ 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:

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:

# 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.

📸 UI Preview (Screenshots)

A quick visual tour of the Streamlit app — settings, upload, forecasting, preview, and visualization.

App Home + Settings Sidebar Shows the TimesFM configuration, frequency settings, batch size and horizon range.

CSV Upload Modal Preview of the uploaded dataset before running the forecast.

Forecast Preview (Long Format) First rows of the generated forecast output (key, date, step, forecast).

Single-Key Visualization Historical series + forecast plotted for a chosen key.

📄 License

MIT

README.md Unescape Escape

TimesFM Forecast (Streamlit, OOP)

🚀 Quickstart (using uv)