TimeCopilot is an open-source GenAI forecasting agent that bridges Large Language Models (LLMs) with advanced time series foundation models. It automates complex forecasting workflows, making professional-grade time series analysis accessible. The agent interprets natural-language queries to generate production-ready forecasts, cross-validations, and anomaly detections across diverse domains like finance, energy, and web analytics.

How It Works

This generative agent employs LLMs to systematically interpret statistical features and patterns within time series data. It intelligently guides model selection based on data characteristics, explains technical decisions in natural language, and answers domain-specific questions about forecasts. By integrating multiple foundation models (e.g., Chronos, Moirai, TimesFM, TimeGPT) via a single API, TimeCopilot offers a novel, unified approach to forecasting.

Quick Start & Requirements

• Installation: pip install timecopilot or uv add timecopilot.
• Prerequisites: Python 3.10+ (recommended for Windows). Requires an OpenAI API Key, exportable as an environment variable.
• Running: Execute forecasts via uvx timecopilot forecast <url_to_csv>, e.g., uvx timecopilot forecast https://otexts.com/fpppy/data/AirPassengers.csv.
• Limitations: Does not support macOS on Intel processors (x86_64).
• Documentation: README provides examples and usage details.

Highlighted Details

• Integrates leading time series foundation models (Amazon Chronos, Salesforce Moirai, Google TimesFM, Nixtla TimeGPT) with LLMs.
• Automates model selection, cross-validation, and provides natural-language explanations for forecasts and feature analysis.
• Supports forecasting from natural-language queries, offering business insights and specific predictions.
• Outputs detailed analysis including time series features, model performance comparisons, and forecast interpretations.

Maintenance & Community

• Active community engagement is encouraged via a Discord server for feedback and shaping the project's future.
• Contributions are welcomed, with clear calls for feature requests, bug reports, and roadmap participation.
• A pre-print paper detailing the project is available on arXiv (2509.00616).

Licensing & Compatibility

• The provided README does not specify a software license. This omission requires clarification for adoption decisions, particularly regarding commercial use or derivative works.

Limitations & Caveats

• Known compatibility issues exist for macOS running on Intel processors (x86_64).
• Reliance on OpenAI API necessitates managing API keys and associated costs.
• The absence of explicit licensing information presents a significant adoption blocker.