Skip to content

Add toto2 ensemble#349

Open
elmartinj wants to merge 4 commits into
TimeCopilot:mainfrom
elmartinj:add-toto2-fnf
Open

Add toto2 ensemble#349
elmartinj wants to merge 4 commits into
TimeCopilot:mainfrom
elmartinj:add-toto2-fnf

Conversation

@elmartinj

Copy link
Copy Markdown
Contributor

Adds a general TimeCopilot implementation of the Toto 2.0 Family-and-Friends forecasting ensemble.

It runs compatible foundation-model forecasters, computes per-series tsfeatures, applies the published frequency and horizon-specific XGBoost gating model, and returns forecasts using the standard TimeCopilot output conventions.

Changes

  • Added Toto2FnF under timecopilot.models.ensembles
  • Added support for published FnF model aliases and quantiles
  • Added automatic short, medium, and long horizon-bucket selection
  • Added frequency normalization across pandas alias versions
  • Added support for using a subset of the published model pool with renormalized weights
  • Added XGBoost as a dependency
  • Exported Toto2FnF from the ensembles package

Added unit tests for:

  • frequency normalization
  • horizon-term inference
  • model alias validation
  • quantile validation
  • weighted forecast generation

Notes
The published FnF ensemble uses a fixed ten-model order. Existing compatible TimeCopilot forecasters can be supplied using their published aliases.

The current TimeCopilot Toto wrapper targets Toto 1.0. A separate Toto 2.0 wrapper will be needed to reproduce the complete published ten-model pool.

@AzulGarza AzulGarza left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thank @elmartinj! it's looking great. i left a couple of comments. also, the branch needs to be cleaned up a little bit. there are some old files in it (docs/examples/cryptocurrentcy-quickstart.ipynb) and some conflicts with main.


def __init__(
self,
models: Sequence[Forecaster],

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since we are dealing with a metalearner with a fixed set of models, it would be best to limit the set of models to the PUBLISHED_MODEL_ORDER and not allow a custom list.

models: Sequence[Forecaster],
*,
alias: str = "Toto-2.0-FnF",
artifacts_repo: str = "Datadog/Toto-2.0-Family-and-Friends",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we use repo_id to maintain consistency across the repo?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we would like to have at least one test where the metalearner passes (not a monkey-patched test).

artifacts_dir: str | Path | None = None,
domain: str | None = None,
term: Literal["auto", "short", "medium", "long"] = "auto",
threads: int = 4,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this argument just used for tsfeatures? if that's the case, can we add it as tsfeatures_threads?

Comment on lines +98 to +105

The class accepts ordinary TimeCopilot forecasters, computes live forecasts
and tsfeatures from a ``unique_id, ds, y`` dataframe, and applies the
published per-(frequency, horizon-term) XGBoost gating head.

Model aliases must use the published names because XGBoost class indices are
tied to that order. A subset of the pool is allowed; weights are then
renormalized over the available models.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's document the arguments and their default values in the docstrings.

@elmartinj

Copy link
Copy Markdown
Contributor Author

Hello!

Addressed the review comments:

  • rebased the branch onto upstream/main and removed unrelated commits
  • renamed artifacts_repo to repo_id
  • renamed threads to tsfeatures_threads
  • expanded the Toto2FnF docstring
  • changed Toto2FnF to require the published model order instead of subset/custom pools
  • updated tests accordingly

Validation:

  • uv run pytest -n 2 tests/models/ensembles/test_toto_2_fnf.py -q
  • uv run pre-commit run --all-files

@elmartinj

Copy link
Copy Markdown
Contributor Author

Updated the PR with the requested changes plus one implementation correction.

Changes made:

  • Rebased the branch onto current upstream/main and force-updated the PR branch.

  • Removed the custom/subset model-pool API.

  • Added FamilyAndFriends as the production-facing hardcoded ensemble.

  • Kept Toto2FnF as a backward-compatible alias.

  • The ensemble now builds the published TimeCopilot model pool internally:

    • Chronos 2
    • TimesFM 2.5
    • FlowState
    • TiRex
    • PatchTST-FM
    • Toto 2.0 4M / 22M / 313M / 1B / 2.5B
  • Changed base model execution to run sequentially and clean up between models, reducing peak memory pressure versus holding the full pool through one TimeCopilotForecaster, this was necessary due to memory overflow during trials. A further version that runs these in a non sequential way would make sense in the future (but made for more powerful hardware).

  • Added/updated tests for:

    • hardcoded published model order
    • sequential hardcoded pool execution
    • frequency normalization
    • quantile validation
    • weighted forecast output

Validation run locally:

  • uv run pytest -n 2 tests/models/ensembles/test_toto_2_fnf.py -q
  • uv run pre-commit run --all-files

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants