Skip to main content

Quickstart

Get ts-agents running in under a minute.

Prerequisites

  • Python 3.11-3.14 for the base CLI; use 3.11-3.13 for the qualified optional dependency stack
  • uv package manager

Install

Install from PyPI:

python -m pip install ts-agents

Or from a source checkout:

git clone https://github.com/fnauman/ts-agents.git
cd ts-agents
uv sync

Base install gives you workflow discovery, workflow show, inspect-series, and a dependency-light seasonal_naive forecast baseline. Use ts-agents[recommended] for the main workflow stack (ARIMA/ETS/Theta and activity-recognition). From a source checkout, plain uv sync matches the base CLI-first install; use uv sync --extra recommended for the same recommended workflow stack.

Bootstrap for autonomous agents

If you are wiring ts-agents into an agent runtime, make these three calls first — they tell the agent exactly what is available in the current environment:

# 1. Top-level capabilities: workflows, tools, sandboxes, install_profile
ts-agents capabilities --json

# 2. Per-workflow execution metadata: CLI templates, options, status contract
ts-agents workflow show forecast-series --json
ts-agents workflow show forecast-panel --json
ts-agents workflow show inspect-series --json
ts-agents workflow show activity-recognition --json

# 3. Sandbox readiness for isolated execution
ts-agents sandbox list
ts-agents sandbox doctor local --json

Agents should plan commands from cli_templates in the workflow show response, watch the top-level quality_status / degraded / requires_review fields on every run, inspect workflow-level result.status / result.data.quality_flags for partial-success details, and read run_manifest.json inside the workflow output directory to enumerate artifacts.

First run (base install, no LLM required)

These commands work immediately with python -m pip install ts-agents — no API key needed.

# Inspect what each workflow requires in the current environment
ts-agents workflow list
ts-agents workflow show forecast-series --json

# Inspect a short inline series and write summary artifacts
ts-agents workflow run inspect-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10]}' \
  --output-dir outputs/inspect

# Run the light seasonal baseline without the forecasting extra
ts-agents workflow run forecast-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}' \
  --horizon 5 \
  --methods seasonal_naive \
  --output-dir outputs/forecast

Check outputs/inspect/ and outputs/forecast/ for JSON, plots, CSVs, and Markdown reports. The 10-point inspect series is too short for the periodicity test, so that run reports quality_status: degraded with the periodicity_not_assessed quality flag. If you omit --output-dir, each workflow run creates a unique run directory under outputs/<workflow>/ and writes run_manifest.json plus the generated artifacts there.

Full workflow stack from a source checkout

Use this path when you want ARIMA/ETS/Theta forecasting comparisons plus activity-recognition.

uv sync --extra recommended

# Compare multiple forecasting baselines
uv run ts-agents workflow run forecast-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}' \
  --horizon 5 \
  --methods seasonal_naive,arima,theta \
  --output-dir outputs/forecast-full

# Generate a labeled stream and run the activity-recognition workflow
uv run python data/make_synthetic_labeled_stream.py \
  --scenario gait --seconds 40 --seed 1337 \
  --out data/demo_labeled_stream.csv
uv run ts-agents workflow run activity-recognition \
  --input data/demo_labeled_stream.csv \
  --label-col label \
  --value-cols x,y,z \
  --output-dir outputs/activity

Check outputs/forecast-full/ and outputs/activity/ for JSON, plots, CSVs, and Markdown reports. The same workflows can also auto-create run-scoped output directories when --output-dir is omitted.

Panel and foundation-model forecasting

forecast-panel compares models across many related series. The seasonal baseline works on the base install; LightGBM/histogram GBM (ml), NHITS (neural) and Darts zero-shot foundation models (foundation) are optional.

ts-agents data export-panel m4-monthly-mini --split train --out panel.csv --json
ts-agents workflow run forecast-panel --input panel.csv --freq MS \
  --horizon 18 --season-length 12 --methods seasonal_naive --skip-plots

# From a source checkout with the foundation extra
uv sync --extra foundation
uv run ts-agents workflow run forecast-panel --input panel.csv --freq MS \
  --horizon 18 --season-length 12 --methods seasonal_naive,chronos2_small --skip-plots

Only the requested checkpoint downloads (into HF_HOME). See Panel and foundation-model forecasting for details.

Try a single tool

# Base install: lightweight statistics on inline JSON
ts-agents tool run describe_series \
  --input-json '{"series":[1,2,3,4,5]}'

# Source checkout: load one column of a file into the tool's `series`
# (data/synthetic_signals.csv is a 50 Hz table with known answers)
uv run ts-agents tool run detect_periodicity \
  --input data/synthetic_signals.csv --time-col t --value-col periodic \
  --json \
  --save outputs/periodicity.json

# Forecasting extra: save the structured forecast payload as JSON
uv run ts-agents tool run forecast_theta \
  --input data/synthetic_signals.csv --value-col periodic \
  --param horizon=25 \
  --json \
  --save outputs/theta.json

# Find tools by task words (anomaly, regime, spectrum, ...)
ts-agents tool search anomaly

--input accepts CSV, TSV, parquet, JSON, or JSONL and fills the series parameter; --value-col picks the column. With --time-col, rows are ordered by time, gaps or irregular sampling are reported in input.warnings, and a regular numeric time column sets sample_rate for tools that accept one (here 50 Hz, so the detected period is reported in seconds). Every tool run reports quality_status ok, or review when the result or the input has warnings.

Tools return structured data, not plots. If you want plots, CSVs, and Markdown reports, prefer workflows such as workflow run forecast-series --input data.csv --value-col y --horizon 12 --output-dir ..., or omit --output-dir and let the workflow create a run-scoped directory under outputs/forecast/.

External agents

Drive the CLI and skills from an external agent runtime. Built-in agents and LLM report generation were removed in 0.4.0; workflow reports are scripted. Activity recognition, classification, anomaly/pattern detection, forecasting, decomposition, and spectral analysis remain available.

The deprecated ts-agents run ... and ts-agents demo ... aliases, the tool run --run/--var flags, and the *_with_data tools are removed in 0.4.1. Use ts-agents tool run <tool> --input <file> --value-col <col> and ts-agents workflow run ... instead.

Next steps