TimeCopilot: benchmark claims on a package classified pre-alpha

The classifier says pre-alpha, the news section says first place

The two halves of this project describe different maturity levels. The news section claims the top position on the GIFT-Eval benchmark above labs and vendors, reports acceptance at a NeurIPS 2025 workshop, and links a founding essay on agentic forecasting. The package metadata says something different: the classifier list carries Development Status 2, Pre-Alpha. That label is what registries and dependency resolvers read, so a team automating an upgrade policy will see a pre-alpha package while a human reading the readme sees benchmark leadership. The version history is consistent with the classifier rather than the news: v0.0.34 on 2026-09-15, v0.0.35 on 2026-09-23 and v0.0.36 on 2026-09-29, with the last push to the default branch on the same day as the newest tag. One detail in that feed is a small sign of a manual release step: the middle tag's name carries a trailing space that the other two do not.

Horizon defaults to twice the inferred seasonality

The data contract is narrow and worth reading twice. A DataFrame must carry three columns with fixed types: a unique identifier per series as a string, a date column in datetime format, and the target as a float. Three things are inferred rather than supplied. The pandas frequency is inferred from the date column if it is not given, seasonality is inferred from that frequency, and the horizon, if unset, defaults to twice the inferred seasonality. So for a monthly series with a seasonal period of twelve, the default forecast is twenty-four steps, not some global default length. This is the setting most likely to surprise someone comparing outputs: two datasets with the same frequency get the same horizon, and a series with no detectable seasonality falls back to whatever the frequency implies. The bundled example makes the chain visible, since its feature output reports a seasonal period of twelve.

The sample explanation argues from a KPSS value of 2.74

The expanded forecast output is the most instructive part of the readme, because it shows the reasoning layer doing its job in prose. Alongside a list of computed time series features, the tool writes an English paragraph describing seasonality, trend and stationarity. In the bundled example the feature list reports a Hurst value of 1.04, a Phillips-Perron unit root statistic of -6.57, a KPSS statistic of 2.74, a seasonal period of twelve, a trend value of 1.00, an entropy of 0.43, an autocorrelation of 0.95 and a seasonal strength of 0.98. The prose then treats the KPSS figure as evidence of non-stationarity on the grounds that it exceeds a threshold of 0.5, and separately reads the trend component as upward motion. Check the direction of that argument against the test you trust before repeating it in a report. The explanation is generated, fluent, and confident, and those are the three properties that make it easy to paste unexamined.

Intel Macs are excluded, and Windows is held to one minor version

Platform support is described with more precision than the classifier's OS Independent suggests. The stated requirement is Python 3.10 or newer, with classifiers naming 3.10 through 3.13. macOS on Intel processors is not supported, and the reason given is concrete: some dependencies including PyTorch fail to install on that architecture, and the guidance for anyone who needs it is to open an issue. On Windows, Python 3.10 is recommended rather than merely allowed, because of how the current packages are built. So an OS Independent classifier sits next to two explicit exclusions. The gap matters most for laptops bought in the last several years that still ship Intel, and for Windows users who would otherwise follow the newest interpreter their tooling supports.

Model choice is one string, and tool use is not optional

Model selection is a command-line string rather than a configuration file. The default run uses a small OpenAI model, and switching models means passing a provider and model name together, the form used in the quickstart being an OpenAI model identifier. A question can be attached to the same command so the agent answers a specific question about the same series rather than returning a bare forecast. The endpoint story is delegated to Pydantic, and the claim is that any endpoint Pydantic supports should work, with a documentation pointer for provider-specific setup. There is one hard requirement attached to that flexibility: models need tool use support to function properly. That single constraint rules out a number of otherwise compatible endpoints, and it is stated as a note rather than checked at startup, so it shows up as a degraded run rather than an error.

One command reaches the internet and forecasts it

The shortest path to a result takes a URL rather than a file. Running the tool through a one-off runner executes a forecast against a public dataset in a single command:

# Baseline run (uses default model: openai:gpt-4o-mini)
uvx timecopilot forecast https://otexts.com/fpppy/data/AirPassengers.csv

Adding a model flag or a question flag extends the same invocation. For development the package installs from PyPI with pip or with uv, and the setup then asks for an OpenAI key exported as an environment variable, with a separate form for Linux shells, for PowerShell on Windows, and one set through Python. That third form is the one to watch, because the snippet imports the OpenAI library and then assigns to the process environment through a module it never imported, so copying it verbatim raises a name error. The key still has to exist in the parent environment for the library call to succeed.

Documentation is built locally and served through a hosted platform

The Makefile has exactly two targets and both are about documentation. Each builds the site with the docs dependency group and then hands the result to Modal, once in serving mode for preview and once in deploy mode for publishing, both times running a deployment script that lives under the repository's own workflow directory. So the docs are ordinary MkDocs output that a hosted platform executes, and the repository has no static host configuration of its own. The docs group explains the rest: material theme, notebook rendering, docstring extraction, an include-markdown plugin, and the hosted runtime library itself, alongside the linter. Alongside that sits a benchmarks directory in the repository, matching the readme's claims about evaluation results, and the dependency notes in the manifest record why a transformers major version required widening two upper bounds together for a security fix.

Editorial conclusion

TimeCopilot suits someone who wants to try several foundation models on the same series from a shell, with the agent choosing and explaining, rather than someone who needs a pinned, production-stable dependency. Before you depend on it, read the packaging rather than the news section: the classifier says pre-alpha, the version is 0.0.x, and the documentation build depends on a hosted platform rather than a static host. Check your platform too, since Intel macOS is excluded outright and Windows is recommended on a single Python minor. And when you read a generated statistical explanation, verify it against your own test before acting on it.

Frequently asked questions

Official sources

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