TimeCopilot: An LLM Agent That Picks Your Time Series Model For You

The Model Selection Problem TimeCopilot Attacks

Forecasting a single series used to mean picking between ARIMA, ETS, a gradient boosting regressor, or a neural net, then tuning each one. Time series foundation models changed the menu without shrinking it. The README names Amazon Chronos, Salesforce Moirai, Google TimesFM and Nixtla TimeGPT, and claims a unified layer over more than thirty such models. A practitioner with one monthly sales series now has thirty plausible defaults and no principled way to choose among them in an afternoon. TimeCopilot's pitch is that an LLM reads statistical features of your data, picks a model, and writes the justification in plain language. The audience is therefore narrow and specific: analysts and engineers who can describe a series in a sentence but do not want to run a model selection sweep, and who are comfortable sending a description of that series to a hosted LLM. It is not aimed at teams that already have a tuned pipeline, because the agent does not promise to beat one.

What Actually Happens Between Your DataFrame and the Forecast

The mechanism visible in the README is a loop, not a fixed pipeline. You pass a DataFrame with three required columns: unique_id as a string identifier, ds as a datetime column, and y as the float target. According to the documentation, the pandas frequency is inferred from ds when you do not supply it, seasonality is inferred from that frequency, and the horizon defaults to twice the inferred seasonality. The LLM then interprets statistical features of the series and guides model selection, and once a model is chosen the underlying foundation model produces the numbers. The README describes the agent as explaining technical decisions in natural language and answering domain-specific questions about forecasts. So the data flow has three stages: profile the series, ask the LLM which foundation model fits, run that model. The retries parameter in the constructor tells you the authors expect the LLM step to fail sometimes and want a bounded number of attempts. That is a candid design detail, and it also tells you where the non-determinism lives.

Installing TimeCopilot and Getting a First Number Out

There are two entry points. For a one-off run with no local files, the README gives a uvx invocation: uvx timecopilot forecast https://otexts.com/fpppy/data/AirPassengers.csv. The default LLM is openai:gpt-4o-mini, and you can override it with --llm openai:gpt-4o. A --query flag accepts a natural-language question, for example asking how many air passengers are expected in total over the next 12 months. For library use, install with pip install timecopilot or uv add timecopilot, export OPENAI_API_KEY, then construct the agent. The README example sets llm="openai:gpt-4o" and retries=3, and calls tc.forecast(df=df, freq="MS"). Optional arguments named in the code comments are freq, h and seasonality. Two environment constraints are stated plainly: Python 3.10 or newer, and no support for macOS on Intel processors (x86_64), where the README warns that dependencies such as PyTorch may fail to install. On Windows the README recommends Python 3.10 specifically. Note that the quickstart command reaches out to a public CSV over HTTPS, so the first thing you run already assumes network access and a working API key.

Where the Agent Design Costs You

The LLM sits in the model selection path, which means forecast reproducibility depends on a hosted service you do not control. Two runs with the same input can select different foundation models, and the README offers no seed, no caching layer and no way to pin a chosen model and skip the reasoning step. For a regulated reporting workflow or a backtest you need to rerun identically, that is disqualifying. There is a second cost: every forecast spends tokens, and the retries parameter exists precisely because those calls can fail. A batch of a thousand series is a thousand LLM conversations before any model runs. Third, the architecture excludes Intel macOS outright, which is unusual and worth weighing if your team is mixed. Fourth, the version number matters. Release v0.0.32 landed on 2026-09-09, with v0.0.31 a week earlier and v0.0.30 about a month before that. A 0.0.x line moving at that cadence can rename constructor arguments between minor releases, so pinning an exact version in your requirements file is the difference between a working notebook and a broken one.

TimeCopilot Versus Nixtla's StatsForecast

StatsForecast, also from Nixtla, takes the opposite approach to the same job. It ships a fixed catalogue of classical and statistical models (AutoARIMA, AutoETS, Theta and others) and expects you to specify which ones to fit, then compares them by cross-validation on your own data. The selection criterion is a measured error metric on held-out windows, not a language model's reading of the series. That means StatsForecast is deterministic, runs entirely locally with no API key, and its per-series cost is CPU time rather than tokens. TimeCopilot's advantage is the opposite of StatsForecast's strength: it can reach foundation models that StatsForecast does not wrap, it explains its reasoning in prose, and it lets you ask a question in English instead of writing a cross-validation loop. If your series is short, your budget for API calls is zero, or you must justify a model choice with a number rather than a paragraph, StatsForecast is the more defensible tool. The two are not mutually exclusive, and nothing in the TimeCopilot material suggests they conflict.

Licence, Maintenance and the Cost of Upgrading

TimeCopilot is MIT licensed, which is permissive and places few obligations on how you redistribute or embed it. That covers the TimeCopilot code itself. It does not cover the foundation models it calls, and the README lists Chronos, Moirai, TimesFM and TimeGPT among them, each with its own licence and, in TimeGPT's case, a commercial service behind it. Nor does MIT cover the LLM: your OpenAI usage is billed separately under OpenAI's terms, and the README's setup path assumes you create an account and generate a key. On maintenance, the release cadence is the signal. Three releases in roughly five weeks on a 0.0.x version means the API surface is still settling. Upgrading is not free: you should re-run your own series after each bump and confirm the constructor arguments and the forecast call signature still match. The repository lists a CI workflow badge and a Discord server, and the README points to a NeurIPS 2025 BERTs workshop paper on agentic forecasting, so there is active development behind it. None of that tells you whether the next release breaks your code, which is why the version pin matters more here than in a project at 1.0.

Who Should Run It Today

Adopt TimeCopilot if you want a fast, explainable first pass on a series you have not modelled before, you already pay for an OpenAI key, and your environment is Python 3.10 or newer on Linux, Windows or Apple Silicon. The uvx command is the cheapest way to find out whether the output is useful to you, because it needs no project setup at all. Do not adopt it as the forecasting engine inside a system that must reproduce identical numbers on demand, and do not adopt it if your machines are Intel Macs, since the README states that configuration is unsupported. The first thing to verify is not accuracy. It is whether the model selection is stable: run the same forecast twice with the same llm and retries values and compare which foundation model the agent chose. If the choice flips between runs, you have learned that the LLM step, not the foundation model, is the variable you would have to control before this belongs anywhere near a production schedule.

Editorial conclusion

TimeCopilot fits teams that already hold an OpenAI API key, work on Python 3.10 or newer, and want a first forecast on a public or local CSV without writing a pipeline. It does not fit anyone needing offline operation, Intel macOS machines, or a deterministic model choice they can pin and audit. Before adopting, run the AirPassengers example with your own key, then check whether the returned model selection is stable across two runs with the same llm and retries values, because that stability is the property the whole design rests on.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. TimeCopilot/timecopilot on GitHub