Quickstart

Get ts-agents running in under a minute.

Prerequisites

  • Python 3.11, 3.12, or 3.13
  • 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] or a source checkout with uv sync for the full three-workflow experience.

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. 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

# 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.

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]}'

# Forecasting extra: save the structured forecast payload as JSON
uv run ts-agents tool run forecast_theta_with_data \
  --run Re200Rm200 --var bx001_real \
  --param horizon=12 \
  --json \
  --save outputs/theta.json

# Plot-producing tool: save the payload and read artifact paths from JSON
uv run ts-agents tool run stl_decompose_with_data \
  --run Re200Rm200 --var bx001_real \
  --json \
  --save outputs/stl.json

For current low-level plot-producing tools, inspect result.artifacts[*].path in the saved JSON rather than expecting extracted PNGs. --extract-images only applies to saved legacy outputs that still contain [IMAGE_DATA:...] tokens. If you want forecast plots, CSVs, and Markdown reports, prefer workflow run forecast-series --output-dir ... or omit --output-dir and let the workflow create a run-scoped directory under outputs/forecast/.

LLM-backed mode

Export an API key to unlock agent-generated narrative reports:

export OPENAI_API_KEY="sk-..."
uv run ts-agents agent run \
  "Use the forecasting skill to compare ARIMA and Theta for a short univariate series"

Or run the built-in agent directly:

uv run ts-agents agent run "Forecast bx001_real for Re200Rm200 with horizon 12"

Compatibility note: ts-agents run ... and ts-agents demo ... remain available for one release cycle, but they now emit deprecation warnings. Prefer ts-agents tool run ... and ts-agents workflow run ....

Next steps