# TimesFM-3 Studio

A local web studio for Google's TimesFM-3 forecasting model. It does four things,
all without training a model and without your data leaving your machine:

- **Forecast** several related series together, including drivers you know in advance (promotions, holidays, weather forecasts).
- **Backtest** by hiding recent history, forecasting it, and scoring the result against a simple baseline.
- **What-if**: change the future drivers and compare the result with the baseline forecast.
- **Anomalies**: flag historical points far outside what the model expected.

It ships with six real public datasets (NOAA CO₂, Capital Bikeshare, ETTh1, NYC taxi,
sunspots, Wikipedia pageviews) and five synthetic demos. An MCP server exposes the same
tools to AI agents. See [webapp/README.md](webapp/README.md) for how the studio works
and [MCP-SERVER.md](MCP-SERVER.md) for the agent tools.

> **License:** the code is Apache-2.0. The TimesFM-3 **model weights are not included**.
> You download them from Hugging Face, and they are licensed for **non-commercial,
> non-production** use only.

## Requirements

| | macOS | Windows |
|---|---|---|
| Hardware | Apple Silicon (M1 or newer). Intel Macs are not supported by current PyTorch. | Any 64-bit PC. An NVIDIA GPU is optional. |
| Memory | 8 GB RAM minimum, 16 GB recommended | 8 GB RAM minimum, 16 GB recommended |
| Disk | About 5 GB (model 1.3 GB plus PyTorch) | About 5 GB, or more with CUDA PyTorch |
| Acceleration | Apple GPU (MPS), used automatically | NVIDIA CUDA if you install CUDA PyTorch (step 4); otherwise CPU |

You don't need to install Python yourself. [uv](https://docs.astral.sh/uv/) installs Python 3.12 into the project folder.

## Install on macOS

Open **Terminal** and run:

```bash
# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Close and reopen Terminal so the `uv` command is found.

# 2. Get the code
git clone https://github.com/TheAIHorizon/timesfm3-studio.git
cd timesfm3-studio

# 3. Create the environment and install the studio
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[torch,web]"
```

**Start the studio:** double-click `start_studio.command` in Finder, or run
`./start_studio.command`. The first time, it offers to download the model weights
(about 1.3 GB from Google's Hugging Face page, no account needed). It shows the
non-commercial licence first and waits for you to type `y`. Once the weights are there,
your browser opens at http://127.0.0.1:7863. Press `Ctrl+C` in the Terminal window to stop it.

To download the weights without starting the studio, run `.venv/bin/python download_model.py`.

If macOS says the file can't be opened, right-click it, choose **Open**, then **Open**
again. You only need to do this once.

## Install on Windows

Open **PowerShell** and run:

```powershell
# 1. Install uv (skip if you already have it)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Close and reopen PowerShell so the `uv` command is found.

# 2. Get the code (needs Git: https://git-scm.com/download/win)
#    Or download the ZIP from GitHub (Code > Download ZIP), unzip it, and cd into the folder.
git clone https://github.com/TheAIHorizon/timesfm3-studio.git
cd timesfm3-studio

# 3. Create the environment and install the studio
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[torch,web]"

# 4. Optional, for NVIDIA GPUs only: replace the CPU build of PyTorch with a CUDA build.
#    Get the exact command from https://pytorch.org/get-started/locally/
#    (choose Windows, Pip, Python and your CUDA version). It looks like this:
#    uv pip install --python .venv\Scripts\python.exe torch --index-url https://download.pytorch.org/whl/cu128 --reinstall
```

**Start the studio:** double-click `start_studio.bat` in File Explorer, or run
`.\start_studio.bat`. The first time, it offers to download the model weights
(about 1.3 GB from Google's Hugging Face page, no account needed). It shows the
non-commercial licence first and waits for you to type `y`. Once the weights are there,
your browser opens at http://127.0.0.1:7863. Press `Ctrl+C` in the window to stop it.

To download the weights without starting the studio, run `.venv\Scripts\python.exe download_model.py`.

If Windows SmartScreen warns about the file, click **More info**, then **Run anyway**.

## After installing

- The status dot in the top-right corner turns green when the model has loaded. Loading happens in the background at startup and takes a few seconds.
- Open any dataset from the **Demo datasets** gallery. Each one opens set up for the analysis that shows it off best.
- To refresh the real datasets from their original sources, run
  `.venv/bin/python webapp/fetch_real_datasets.py --refresh` on macOS or
  `.venv\Scripts\python.exe webapp\fetch_real_datasets.py --refresh` on Windows.
- To keep the weights somewhere else, set `TIMESFM_MODEL_DIR` to that folder before starting. The launcher and `download_model.py` both use it.

**Troubleshooting**

- *"Checkpoint missing" in the status bar:* the weights didn't finish downloading. Run the launcher again, or run `download_model.py`; the download resumes where it stopped.
- *Installing on a machine without a keyboard or terminal (scripted setup):* run `download_model.py --yes` to accept the licence without the prompt.
- *Port 7863 already in use:* another copy of the studio is running. Close it, or edit the port in the launcher.
- *CUDA not used on Windows:* check with `.venv\Scripts\python.exe -c "import torch; print(torch.cuda.is_available())"`. If it prints `False`, redo step 4 with the command from pytorch.org.

---

*The original TimesFM README from Google Research follows.*

# TimesFM

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation
model developed by Google Research for time-series forecasting.

*   Paper:
    [A decoder-only foundation model for time-series forecasting](https://arxiv.org/abs/2310.10688),
    ICML 2024.
*   <span style="color:red">(NEW!)</span> TimesFM 3.0 Checkpoint:
    [`google/timesfm-3.0-pytorch`](https://huggingface.co/google/timesfm-3.0-pytorch).
*   Checkpoints (up to 2.5):
    [TimesFM Hugging Face Collection](https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6).
*   [Google Research blog](https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/)
    (New blog post for TimesFM 3.0 coming soon!).
*   TimesFM in Google 1P Products:
    *   [BigQuery ML](https://cloud.google.com/bigquery/docs/timesfm-model):
        Enterprise level SQL queries for scalability and reliability.
    *   [Google Sheets](https://workspaceupdates.googleblog.com/2026/02/forecast-data-in-connected-sheets-BigQueryML-TimesFM.html):
        For your daily spreadsheet.
    *   [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/timesfm):
        Dockerized endpoint for agentic calling.

This open version is not an officially supported Google product.

**Latest Model Version:** TimesFM 3.0

**Archived Model Versions:**

-   2.5: relevant code under `src/timesfm`.
-   1.0 and 2.0: relevant code archived in the subdirectory `v1`. You can `pip
    install timesfm==1.3.0` to install an older version of this package to load
    them.

--------------------------------------------------------------------------------

## Update — August 2026

**TimesFM 3.0 is out!**

TimesFM 3.0 introduces native **multivariate time-series forecasting**, flexible
**covariate support** (both past-only and past-and-future covariates), superior
zero-shot generalist capabilities, and top performance across all three major
time-series foundation model benchmarks.

### Key Highlights:

-   **Native Multivariate & Univariate Forecasting with Covariates**: Seamlessly
    forecast multi-channel multivariate series as well as individual univariate
    series, with native support for past-only and past-and-future dynamic
    covariates without per-task tuning.
-   **Top Benchmark Performance**:
    -   🥇 **fev-bench**: **Rank #1 overall** across 100 diverse real-world
        forecasting tasks.
    -   🥇 **TIME Benchmark**: **Rank #1 overall** across 50 domain datasets and
        98 evaluation tasks.
    -   🥇 **GIFT-Eval**: **Rank #1 among all foundation models**.

### License notice for pretrained weights

> **Important:** The TimesFM source code in this repository is licensed under
> Apache-2.0, and model weights up to version 2.5 remain Apache-2.0. However,
> for the time being, TimesFM 3.0 pretrained weights are distributed under the
> separate `timesfm-non-commercial-license-v1.0` license and are restricted to
> non-commercial, non-production use. Commercial or production use of the
> default pretrained weights is **not permitted**.

--------------------------------------------------------------------------------

## Update - July 2, 2026

Updated PyPI to `timesfm=2.0.2`. See
[Install](https://github.com/google-research/timesfm#from-pypi).

## Update - Apr. 9, 2026

Added fine-tuning example using HuggingFace Transformers + PEFT (LoRA) — see
[`timesfm-forecasting/examples/finetuning/`](timesfm-forecasting/examples/finetuning/).
Also added unit tests (`tests/`) and incorporated several community fixes.

Shoutout to [@kashif](https://github.com/kashif) and
[@darkpowerxo](https://github.com/darkpowerxo).

## Update - Mar. 19, 2026

Huge shoutout to [@borealBytes](https://github.com/borealBytes) for adding the
support for
[AGENTS](https://github.com/google-research/timesfm/blob/master/AGENTS.md)!
TimesFM
[SKILL.md](https://github.com/google-research/timesfm/tree/master/timesfm-forecasting)
is out.

## Update - Oct. 29, 2025

Added back the covariate support through XReg for TimesFM 2.5.

## Update - Sept. 15, 2025

TimesFM 2.5 is out!

Comparing to TimesFM 2.0, this new 2.5 model:

-   uses 200M parameters, down from 500M.
-   supports up to 16k context length, up from 2048.
-   supports continuous quantile forecast up to 1k horizon via an optional 30M
    quantile head.
-   gets rid of the `frequency` indicator.
-   has a couple of new forecasting flags.

Since the Sept. 2025 launch, the following improvements have been completed for
TimesFM 2.5:

1.  ✅ Flax version of the model for faster inference.
2.  ✅ Covariate support via XReg (see Oct. 2025 update).
3.  ✅ Documentation, examples, and agent skill (see `timesfm-forecasting/`).
4.  ✅ Fine-tuning example with LoRA via HuggingFace Transformers + PEFT (see
    `timesfm-forecasting/examples/finetuning/`).
5.  ✅ Unit tests for core layers, configs, and utilities (see `tests/`).

### Install

#### From `PyPI`

```shell
# Install TimesFM with PyTorch
pip install timesfm[torch]
```

#### Local Install

1.  Clone the repository:

    ```shell
    git clone https://github.com/google-research/timesfm.git
    cd timesfm
    ```

2.  Create a virtual environment and install with PyTorch:

    ```shell
    # Using uv
    uv venv
    source .venv/bin/activate

     # Install the package in editable mode with torch
    uv pip install -e .[torch]
    ```

--------------------------------------------------------------------------------

### Code Examples: TimesFM 3.0

#### 1. Univariate Forecasting (Variable Lengths)

Pass a batch of 1D NumPy arrays of different context lengths to forecast
univariate time series:

```python
import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

# Initialize TimesFM 3.0
config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"
)
forecaster = TimesFM3Evaluator(config)

# Two univariate series of different lengths (100 and 72 steps)
ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)

# Generate forecast (point predictions + 9 quantiles: 0.1 to 0.9)
outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))

print("Series 1 forecast shape:", outputs[0].forecast.shape)   # (12,)
print("Series 1 quantiles shape:", outputs[0].quantiles.shape) # (12, 9)

print("Series 2 forecast shape:", outputs[1].forecast.shape)   # (12,)
print("Series 2 quantiles shape:", outputs[1].quantiles.shape) # (12, 9)
```

#### 2. Multivariate Forecasting with Covariates

Pass a 2D array of shape `(num_variates, context_length)` along with optional
past-only and past-and-future covariates:

```python
import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

# Initialize TimesFM 3.0
config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=16,
    device="cuda"
)
forecaster = TimesFM3Evaluator(config)

context_len = 128
horizon = 24

# 3 target variates across past context: (3, 128)
target = np.random.randn(3, context_len).astype(np.float32)

# 1 past-only covariate channel across past context: (1, 128)
past_only_cov = np.random.randn(1, context_len).astype(np.float32)

# 2 past-and-future covariate channels across context + horizon: (2, 152)
past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32)

# Generate joint forecast across all 3 target variates
outputs = list(
    forecaster.predict_batch(
        contexts=[target],
        horizon=horizon,
        past_only_covariates=[past_only_cov],
        past_future_covariates=[past_future_cov],
        return_quantiles=True,
        use_symmetric_averaging=False,
    )
)

print("Multivariate forecast shape:", outputs[0].forecast.shape)   # (3, 24)
print("Multivariate quantiles shape:", outputs[0].quantiles.shape) # (3, 24, 9)
```