WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 18 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Time-Series-Library (TSLib) is a comprehensive benchmarking framework and model zoo for evaluating deep learning architectures on time series tasks—forecasting (long/short-term), imputation, anomaly detection, and classification. It provides 20+ production-grade implementations (Autoformer, Informer, DLinear, Transformer variants, Mamba-based models, and LLM-based zero-shot forecasters like Chronos/Moirai) with standardized data loaders and experiment pipelines across datasets like ETT, M4, and UEA. Monolithic single-package structure: data_provider/ abstracts datasets (M4, UEA, ETT via data_loader.py/data_factory.py), models/ contains 50+ architecture files (each a standalone class like models/Autoformer.py), layers/ provides reusable components (Autoformer_EncDec.py, SelfAttention_Family.py, MambaBlock.py), and exp/ wraps task-specific training loops (exp_long_term_forecasting.py, exp_anomaly_detection.py). Shell scripts in scripts/ define hyperparameter sweeps per dataset.

Time series ML researchers and practitioners who need a unified codebase to benchmark competing architectures, validate novel models against established baselines, or reproduce published results. Data scientists building production forecasting systems who want reference implementations. PhD students studying temporal dependencies in deep learning.

Mature but transitioning to maintenance mode. The library has been active for 3+ years with 20k+ LoC across 50+ model implementations and comprehensive exp/ task runners, but maintainers announced in April 2026 they will not actively add features due to limited bandwidth—recent updates (Dec 2025) focused on Docker/requirements modernization rather than new models. Production-grade baseline implementations, but benchmarks may be outdated for evaluating cutting-edge research.

Moderate risk: 40+ direct dependencies (transformers, gluonts, jax, lightning, hydra) create a large attack surface and potential version conflicts; no visible test suite in file listing; Python 2.1.2 / PyTorch constraints suggest narrow compatibility windows. Maintenance concentration risk—core maintainers signal reduced capacity. News items indicate confusion in community about benchmark saturation (2025.10 Accuracy Law paper), suggesting the library may not reflect current research directions.

Focus shifted to emerging Large Time Series Models (LTSMs): zero-shot forecasting support added (Nov 2025, exp_zero_shot_forecasting.py) with TimesFM/Chronos integration. Parallel OpenLTM library launched for pretrain-finetuning paradigm (Oct 2024). Recent work validates 'Accuracy Law' principle (Oct 2025 paper) to identify dataset saturation. Docker deployment and requirements.txt modernization merged (Dec 2025 PR from ailuntz). No active development of new traditional architectures.

git clone https://github.com/thuml/Time-Series-Library.git && cd Time-Series-Library && pip install -e . && pip install -r requirements.txt (or use Docker: docker-compose up)

Daily commands: Task-specific: python -m exp.exp_long_term_forecasting --model Autoformer --data ETTh1 (inferred from exp/*.py structure). Or shell scripts: bash scripts/long_term_forecast/ETT_script/Autoformer.sh. Zero-shot: python -m exp.exp_zero_shot_forecasting --model Chronos (from 2025.11 feature). Docker: docker-compose up spins containerized training.

• run.py — Main entry point for all experiments; every contributor must understand how to execute training, evaluation, and inference workflows
• data_provider/data_factory.py — Central data loading orchestrator that routes to task-specific loaders; critical for adding new datasets or modifying data pipelines
• exp/exp_basic.py — Base experiment class defining the training loop, validation, and testing logic; all task-specific experiments inherit from this
• models/__init__.py — Model registry and factory; required to register any new model before it can be used in experiments
• layers/__init__.py — Layer abstractions (attention, correlation, decomposition) that form the building blocks of models; understanding these is essential for model development
• requirements.txt — Dependencies including PyTorch, transformers, and specialized libraries (chronos, timesfm); must be maintained for reproducibility

Add a new time series model

1. Create a new model file in models/ (e.g., models/MyModel.py) inheriting from nn.Module with forward() and encoder/decoder structure (models/MyModel.py)
2. Register the model in models/init.py by importing it and adding to the model dictionary (models/__init__.py)
3. Create a bash script in scripts/ (e.g., scripts/long_term_forecasting/ETTh1/MyModel.sh) with dataset, model, and hyperparameter configs (scripts/long_term_forecasting/ETTh1/MyModel.sh)
4. Execute the script: bash scripts/long_term_forecasting/ETTh1/MyModel.sh or use run.py with --model MyModel flag (run.py)

Add a new dataset for forecasting

1. Place your CSV file in data/your_dataset/ with columns: date, value1, value2, ... (multivariate supported) (data_provider/data_loader.py)
2. Update data_factory.py to recognize your dataset name and route to the standard DataLoader or create a custom loader if special preprocessing is needed (data_provider/data_factory.py)
3. Add a script in scripts/long_term_forecasting/YourDataset/ that references the new dataset with the same hyperparameters as existing datasets (scripts/long_term_forecasting/ETTh1/Autoformer.sh)
4. Run: bash scripts/long_term_forecasting/YourDataset/ModelName.sh to validate the pipeline (run.py)

Implement a new attention or correlation layer

1. Create a new layer file in layers/ (e.g., layers/MyAttention.py) implementing the forward() method as an nn.Module (layers/MyAttention.py)
2. Register the layer in layers/init.py so it can be imported by models (layers/__init__.py)
3. Integrate the layer into one or more models (e.g., in models/Autoformer.py) by replacing or augmenting existing attention modules (models/Autoformer.py)
4. Test using exp_long_term_forecasting.py or another task runner to verify training and inference work correctly (exp/exp_long_term_forecasting.py)

Add a new task (e.g., forecasting variant or new downstream task)

1. Create exp/exp_your_task.py inheriting from exp_basic.py, implementing custom _train_epoch(), _validate(), and _test() methods (exp/exp_your_task.py)
2. Ensure init() in exp/exp_your_task.py calls parent init() and initializes task-specific loss/metrics (exp/exp_basic.py)
3. Update data_factory.py to instantiate the correct DataLoader variant for your task (add a conditional branch) (data_provider/data_factory.py)
4. Add a conditional in run.py to route your task flag to the new experiment class (run.py)

• PyTorch — Standard for deep learning research; enables GPU acceleration, autograd, and easy model composition
• einops (reshape & einsum utilities) — Simplifies tensor manipulations in attention and decomposition layers; improves code readability and prevents shape errors
• Hugging Face transformers & datasets — Integrates pre-trained models (Chronos, TimesFM) for zero-shot forecasting; provides unified API for model loading
• scikit-learn, scipy, numpy — Classical baselines, normalization, statistical preprocessing, and feature engineering utilities
• Lightning (pytorch-lightning) + Hydra — For uni2ts and advanced multi-task training; handles distributed training, logging, and config management

• Monolithic model registry in models/init.py rather than dynamic plugin discovery

  • Why: Simplifies deployment and avoids runtime import errors; all models must be explicitly imported
  • Consequence: Adding a new model requires editing models/init.py; no hot-reloading but ensures clarity

• Task-specific

  • Why: undefined
  • Consequence: undefined

1. Dataset downloads: some datasets (M4, UEA) auto-download but may require authentication or slow network; check data/ directory permissions. 2) GPU/CPU mismatch: models default to CUDA if available—set CUDA_VISIBLE_DEVICES='' for CPU-only runs or face OOM. 3) Normalization leak: StandardNorm.py uses train statistics to normalize test data; misuse causes information leakage—always call .fit() on train only. 4) Missing scripts: shell scripts in scripts/long_term_forecast/ reference hyperparameters; running raw Python requires manual arg passing. 5) Requirements.txt version pins are strict (numpy==2.1.2, scipy==1.16.3)—pip upgrade may break. 6) Mamba layers require custom triton compilation on first run—expect slow import. 7) HuggingFace token: Chronos/Moirai models may require huggingface_hub login if gated.

• Autocorrelation-based Attention — layers/AutoCorrelation.py replaces O(n²) softmax with O(n log n) autocorrelation computation—essential for scaling to long sequences without VRAM explosion.
• Reversible Normalization (z-score) — StandardNorm.py inverts predictions back to original scale for loss computation; critical for fair benchmarking since raw MSE is scale-dependent.
• Encoder-Decoder with Look-ahead Mask — layers/Transformer_EncDec.py enforces causal masking during training to prevent information leakage from future tokens—core technique for autoregressive forecasting.
• Fourier Basis Decomposition — layers/FourierCorrelation.py and layers/DWT_Decomposition.py separate trend/seasonality in frequency domain; reduces noise and improves interpretability vs end-to-end black-box.
• State Space Models (Mamba) — layers/MambaBlock.py provides O(n) linear complexity alternative to quadratic Transformer attention; newer paradigm explored in models/Mamba.py and models/MambaSimple.py.
• Multi-head Self-Attention with Sparse Factorization — layers/SelfAttention_Family.py implements variants (LogSparse, Linformer, Reformer) to reduce memory footprint on ultra-long sequences; critical for ETT-hourly (17.5K timesteps).
• Zero-shot Transfer via Pretrained LLMs — exp_zero_shot_forecasting.py leverages large frozen models (Chronos, TimesFM, Moirai) without fine-tuning—paradigm shift from supervised training in TSLib baseline models.

• thuml/OpenLTM — Sibling repo by same lab providing pretrain-finetuning paradigm for Large Time Series Models, complementary to TSLib's supervised benchmarking approach.
• amazon-science/chronos-forecasting — Source implementation of Chronos pretrained model referenced in models/Chronos.py; directly integrated as zero-shot baseline.
• aaronwwf/DLinear — Original DLinear model (simple linear baseline that outperforms Transformers on certain datasets); implemented in TSLib as models/DLinear.py.
• thuml/iTransformer — Related architecture from same lab applying Transformers to multivariate series; represents evolution of Autoformer design principles.
• gluonts/gluonts — Probabilistic forecasting library (gluonts==0.16.2 in deps); used by TSLib for baseline comparisons and data format compatibility.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for data_provider module components

The data_provider directory (data_factory.py, data_loader.py, m4.py, uea.py) lacks visible unit tests. Given that data loading is critical for reproducible benchmarking in a time series library, adding comprehensive tests would ensure data integrity across different datasets (M4, UEA) and prevent regressions when updating data handling logic.

• [ ] Create tests/test_data_provider/ directory structure
• [ ] Add unit tests for data_factory.py covering dataset instantiation and edge cases
• [ ] Add tests for data_loader.py validating batch creation, normalization, and sequence splitting
• [ ] Add tests for m4.py and uea.py validating dataset-specific loading and format correctness
• [ ] Integrate tests into GitHub Actions CI workflow (if not already present)

Create experiment reproducibility validation suite

The exp/ directory contains 7 experiment runners (exp_basic.py, exp_long_term_forecasting.py, exp_classification.py, etc.) but there's no automated validation that these experiments run successfully with different model/dataset combinations. This is critical for a benchmarking library where maintainers have limited bandwidth. A lightweight test suite would catch breakages early.

• [ ] Create tests/test_experiments/ directory with smoke tests for each exp_*.py module
• [ ] Add minimal integration tests that run exp_long_term_forecasting.py and exp_classification.py with a toy dataset
• [ ] Validate that all 30+ models in models/ can be instantiated within at least one experiment type
• [ ] Create a GitHub Actions workflow that runs these smoke tests on each PR to catch model/layer incompatibilities

Add model-to-task compatibility matrix and validation

With 30+ models and 5 tasks (forecasting, imputation, anomaly detection, classification, zero-shot), there's no documented/validated mapping of which models support which tasks. Several models may only work for specific tasks, creating silent failures. Formalizing this would reduce contributor confusion and maintenance burden.

• [ ] Create docs/MODEL_TASK_COMPATIBILITY.md documenting which models support which of the 5 tasks
• [ ] Add a utils/model_registry.py that defines a compatibility matrix as a data structure
• [ ] Add validation logic in exp/exp_basic.py to raise clear errors when an unsupported model-task combination is attempted
• [ ] Update README.md with a table referencing the compatibility matrix for quick lookup

• Add unit tests for layers/StandardNorm.py—test that .fit() on train doesn't leak into test normalization, and verify reverse transform correctness. Currently no test file exists for normalization correctness.
• Document hyperparameter mapping in exp/*.py: create a HYPERPARAMETERS.md listing which arguments map to model.py init, optimizer settings, and learning rate schedule—currently scattered across shell scripts with no central reference.
• Extend data_provider/data_loader.py with a CsvDataset class to load arbitrary CSV time series (timestamp + value columns)—currently supports only built-in ETT/M4/UEA, blocking users with custom datasets.

• High · Outdated and Vulnerable Dependencies — requirements.txt. Multiple dependencies have known vulnerabilities or are significantly outdated. Notably: numpy==2.1.2 (should be >=2.0.0 with security patches), transformers==4.57.3 (very recent but may have unpatched vulnerabilities), and jax==0.8.1 (outdated, current versions are 0.4.x+). The use of pinned versions without security monitoring increases risk. Fix: Implement automated dependency scanning using tools like Snyk, Dependabot, or GitHub Security Advisories. Update to latest stable versions and establish a regular patching schedule. Consider using version ranges (e.g., >=4.50.0,<5.0.0) instead of exact pinning for critical security patches.
• High · Unrestricted Wheel Installation from GitHub — Dockerfile (line with mamba-ssm installation). The Dockerfile installs a pre-built wheel directly from GitHub without verifying cryptographic signatures or checksums. The mamba-ssm wheel at 'https://github.com/state-spaces/mamba/releases/download/v2.2.6.post3/mamba_ssm-2.2.6.post3+cu12torch2.5cxx11abiFALSE-cp311-cp311-linux_x86_64.whl' is downloaded without integrity verification, exposing to man-in-the-middle attacks and supply chain compromise. Fix: Verify wheel integrity using SHA256 checksums. Store checksums in the repository and validate before installation: 'pip install --no-cache-dir wheel_url --hash=sha256:HASH_VALUE'. Alternatively, build the wheel from source or use official package repositories.
• High · Unsafe Installation with --no-deps Flag — Dockerfile (uni2ts installation). The uni2ts package is installed with the --no-deps flag, which bypasses dependency resolution. This can lead to missing or incompatible dependencies at runtime, potentially causing security issues if dependency versions have known vulnerabilities. Fix: Remove the --no-deps flag and let pip resolve dependencies properly. If there are conflicts, address them explicitly by pinning conflicting dependencies or using dependency resolution tools. Document any compatibility issues and version requirements.
• Medium · Missing Docker Base Image Security — Dockerfile (FROM clause). The base image 'pytorch/pytorch:2.5.1-cuda12.1-cudnn9-devel' is a development image that may contain unnecessary tools and larger attack surface. No health checks or minimal image verification present. Fix: Use official minimal or slim base images where possible. Implement image vulnerability scanning (Trivy, Grype). Consider using distroless or alpine-based alternatives. Add HEALTHCHECK directives and regularly rebuild images with security patches.
• Medium · Environment Variable Exposure in docker-compose.yml — docker-compose.yml (commented proxy environment variables). The docker-compose.yml file contains commented-out proxy credentials that could be accidentally uncommented. While commented, this indicates developers might pass sensitive configuration through environment variables without proper secret management. Fix: Use Docker secrets or external secret management (Vault, AWS Secrets Manager) instead of environment variables for sensitive data. Never commit uncommented credentials. Use .env files with .gitignore and consider using docker-compose.override.yml for local configurations.
• Medium · Large Cache Mount Without Restrictions — Dockerfile (cache mount directives). The Dockerfile uses 'RUN --mount=type=cache,target=/root/.cache/pip' without setting cache permissions or cleanup. Pip cache could accumulate across builds and potentially allow cache poisoning attacks. Fix: Explicitly clean the pip cache: 'pip cache purge' after installations. Set proper permissions on cache directories. Use '--no-cache-dir' flag with pip when cache is not needed. Monitor cache contents in CI/CD pipelines.
• Medium · No Network Security in Docker Configuration — docker-compose.yml (NVIDIA configuration and network settings). The docker-compose.yml exposes all NVIDIA devices and does not define network isolation. The service could communicate with any network without restriction. Fix: Define explicit network policies using Docker networks. Use 'networks' section to create isolated networks. Remove unnecessary NVIDIA_VISIBLE_DEVICES or restrict to specific GPUs. Implement network segmentation for production deployments

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/thuml/Time-Series-Library shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live thuml/Time-Series-Library repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thuml/Time-Series-Library.

What it runs against: a local clone of thuml/Time-Series-Library — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in thuml/Time-Series-Library | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of thuml/Time-Series-Library. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/thuml/Time-Series-Library.git
#   cd Time-Series-Library
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of thuml/Time-Series-Library and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thuml/Time-Series-Library(\\.git)?\\b" \\
  && ok "origin remote is thuml/Time-Series-Library" \\
  || miss "origin remote is not thuml/Time-Series-Library (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "run.py" \\
  && ok "run.py" \\
  || miss "missing critical file: run.py"
test -f "data_provider/data_factory.py" \\
  && ok "data_provider/data_factory.py" \\
  || miss "missing critical file: data_provider/data_factory.py"
test -f "exp/exp_basic.py" \\
  && ok "exp/exp_basic.py" \\
  || miss "missing critical file: exp/exp_basic.py"
test -f "models/__init__.py" \\
  && ok "models/__init__.py" \\
  || miss "missing critical file: models/__init__.py"
test -f "layers/__init__.py" \\
  && ok "layers/__init__.py" \\
  || miss "missing critical file: layers/__init__.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 50 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~20d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/thuml/Time-Series-Library"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.