Align inference API with official GitHub implementation

Add the official TimeRCDDetector package and documentation; re-export the official univariate checkpoint for Transformers; align long-sequence normalization semantics.

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+zero-shot.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,145 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+datasets
+checkpoints
+Uni_Time_RCD
+TSAD_dataset_gen-clean_version/
+*.zip
+*.pkl
+*.csv
+*.cpython-310.pyc
+*.pyc
+scripts/

LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025-2026 Tsinghua SAIL Lab and contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,174 +1,186 @@
 ---
 library_name: transformers
+license: apache-2.0
 tags:
   - time-series
   - anomaly-detection
   - custom_code
 ---
 
+> **Official model repository.** This Hugging Face repository hosts the checkpoints used by the official [Time-RCD GitHub project](https://github.com/thu-sail-lab/Time-RCD), as well as a Transformers-compatible model implementation. The recommended inference API is `TimeRCDDetector` below.
+
+<div align="center">
+
 # Time-RCD
 
-**Official Hugging Face model repository** for [Time-RCD](https://github.com/thu-sail-lab/Time-RCD): _Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy_.
+_Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy_
+
+[![arXiv](https://img.shields.io/badge/arXiv-2509.21190-b31b1b.svg)](https://arxiv.org/abs/2509.21190)
+[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Demo-yellow)](https://huggingface.co/spaces/thu-sail-lab/Time_RCD)
+[![时空探索之旅](https://img.shields.io/badge/时空探索之旅-black?logo=wechat&logoColor=white)](https://mp.weixin.qq.com/s/79M3jsEhMKBzbNYpROOBCw)
 
-This repository hosts the official pretrained weights, Transformers-compatible model code, and processor for zero-shot time series anomaly detection. The full training, evaluation, and TSB-AD benchmark pipeline is maintained in the companion [official GitHub repository](https://github.com/thu-sail-lab/Time-RCD).
+</div>
 
-| Resource | Link |
-| --- | --- |
-| Paper | [arXiv:2509.21190](https://arxiv.org/abs/2509.21190) |
-| Code | [github.com/thu-sail-lab/Time-RCD](https://github.com/thu-sail-lab/Time-RCD) |
-| Demo | [Hugging Face Space](https://huggingface.co/spaces/thu-sail-lab/Time_RCD) |
+<p align="center">
+    📰&nbsp;<a href="#-news">News</a>
+    | 🔍&nbsp;<a href="#-about">About</a>
+    | 🎯&nbsp;<a href="#-use-on-your-own-data">Use on Your Own Data</a>
+    | 📁&nbsp;<a href="#-project-structure">Project Structure</a>
+    | 🔗&nbsp;<a href="#-citation">Citation</a>
+</p>
 
-On the TSB-AD benchmark, Time-RCD achieves a **univariate VUS-PR of 0.52** and a **multivariate VUS-PR of 0.32**.
+## 📰 News
 
-## News
+- **2026.05:** Time-RCD has been accepted by **ICML 2026**. We also release the [pre-trained dataset generation code and hyperparameters](https://github.com/thu-sail-lab/TSAD_dataset_gen_public).
 
-- **2026.05:** Time-RCD has been accepted by **ICML 2026**. We also release the pre-trained dataset generation code and hyperparameters.
 - **2026.04:** With a new dataset and new checkpoints, Time-RCD achieves better results. The univariate setting improves VUS-PR by an **absolute 6.7 points**, and the multivariate setting improves VUS-PR by an **absolute 4.5 points**.
 
-## Model Details
+## 🔍 About
 
-- **Architecture:** Time-RCD with an 8-layer Transformer encoder
-- **Context window:** 5,000 time steps
-- **Patch size:** 16
-- **Default input features:** 1 (univariate)
-- **Output:** An anomaly score per time step; higher scores indicate a higher likelihood of anomaly
+**Time-RCD** is a zero-shot foundation model for time series anomaly detection. Given a univariate or multivariate series, it outputs a per-timestep anomaly score without any task-specific training on your data.
 
-The model normalizes each input window internally. For sequences longer than 5,000 points, use `model.zero_shot()`, which splits the input into windows and returns scores for each window.
+🐘 On the [TSB-AD benchmark](https://thedatumorg.github.io/TSB-AD/), Time-RCD achieves a **Univariate VUS-PR of 0.52** and a **Multivariate VUS-PR of 0.32**.
 
-### Repository Contents
+**[🌟 Live Demo on Hugging Face Spaces](https://huggingface.co/spaces/thu-sail-lab/Time_RCD)** — try Time-RCD interactively in your browser.
 
-```
-.
-├── config.json
-├── model.safetensors
-├── preprocessor_config.json
-├── configuration_time_rcd.py
-├── modeling_time_rcd.py
-├── processing_time_rcd.py
-├── requirements.txt
-└── best_model/
-    ├── pretrain_checkpoint_best_uni.pth
-    └── pretrain_checkpoint_best_multi.pth
-```
+<div align="center">
+<img src="https://raw.githubusercontent.com/thu-sail-lab/Time-RCD/main/zero-shot.png" style="width:95%;" />
+</div>
 
-- `model.safetensors`: Default univariate checkpoint in Safetensors format for Transformers inference.
-- `best_model/`: Original PyTorch checkpoints for univariate and multivariate settings.
+This repository contains:
 
-## Installation
+1. **`time_rcd/`** — a lightweight Python API for inference on your own data
+
+For a step-by-step guide, see **[Tutorial.md](https://github.com/thu-sail-lab/Time-RCD/blob/main/Tutorial.md)**.
+
+---
+
+## 🎯 Use on Your Own Data
+
+### Installation
 
 ```bash
 conda create -n Time-RCD python=3.10
 conda activate Time-RCD
-pip install -r requirements.txt
+
+git clone https://github.com/thu-sail-lab/Time-RCD.git
+cd Time-RCD
+pip install .
 ```
 
-Or install dependencies directly:
+When working from a local clone of this Hugging Face repository, install the same official inference package with:
 
 ```bash
-pip install "torch>=2.0.0" "transformers>=4.30.0" "numpy>=1.20.0" "scikit-learn>=1.0.0"
+pip install .
 ```
 
-## Quick Start
+### Python API (recommended)
 
-This repository ships custom model and processor code. Set `trust_remote_code=True` when loading.
+Checkpoints are downloaded from Hugging Face automatically on first use and cached locally.
+For servers in China, set `HF_ENDPOINT=https://hf-mirror.com` before running
+the examples or loading a checkpoint.
 
-### Long sequences (recommended)
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
 
 ```python
 import numpy as np
-import torch
-from transformers import AutoModel
-
-model_id = "thu-sail-lab/Time-RCD"
-device = "cuda" if torch.cuda.is_available() else "cpu"
+from time_rcd import TimeRCDDetector
 
-model = AutoModel.from_pretrained(model_id, trust_remote_code=True).to(device)
-model.eval()
+data = np.load("my_series.npy")  # shape (T,) or (T, C)
 
-# Shape: (num_timesteps,) or (num_timesteps, num_features)
-time_series = np.random.randn(10_000).astype(np.float32)
-
-with torch.no_grad():
-    scores_by_window, logits_by_window = model.zero_shot(time_series)
-
-anomaly_scores = np.concatenate(scores_by_window)
+detector = TimeRCDDetector.from_pretrained(variant="uni")   # or "multi"
+scores = detector.predict(data)                             # shape (T,)
 ```
 
-### Single window (≤ 5,000 steps)
+**Multivariate series** — use `variant="multi"` when `C > 1`:
 
 ```python
-import torch
-from transformers import AutoModel
-
-model = AutoModel.from_pretrained(
-    "thu-sail-lab/Time-RCD",
-    trust_remote_code=True,
-).eval()
+detector = TimeRCDDetector.from_pretrained(variant="multi")
+scores = detector.predict(multivariate_data)  # shape (T, C) -> scores (T,)
+```
 
-time_series = torch.randn(1, 5000, 1)  # (batch, seq_len, features)
-with torch.no_grad():
-    outputs = model(time_series=time_series)
+**Local checkpoint** — if you already downloaded weights:
 
-anomaly_scores = outputs.anomaly_scores  # (batch, seq_len)
+```python
+detector = TimeRCDDetector.from_local(
+    "best_model/pretrain_checkpoint_best_uni.pth",
+    variant="uni",
+)
 ```
 
-## Download Locally
-
-Download the full official repository:
+### Quick example
 
 ```bash
-hf download thu-sail-lab/Time-RCD --local-dir ./Time-RCD
+python examples/quickstart.py
 ```
 
-Download only the original PyTorch checkpoints:
+See **[Tutorial.md](https://github.com/thu-sail-lab/Time-RCD/blob/main/Tutorial.md)** for CSV loading, hyperparameters, and more examples.
 
-```bash
-hf download thu-sail-lab/Time-RCD \
-  --include "best_model/pretrain_checkpoint_best_uni.pth" \
-  --local-dir ./Time-RCD
+### Transformers API
 
-hf download thu-sail-lab/Time-RCD \
-  --include "best_model/pretrain_checkpoint_best_multi.pth" \
-  --local-dir ./Time-RCD
-```
+This repository also supports Transformers-based inference. The official
+`TimeRCDDetector` API above is recommended, especially for multivariate data.
+For univariate data, the following loads the same official `uni` checkpoint:
 
-For servers in mainland China, use the Hugging Face mirror:
+```python
+import numpy as np
+from transformers import AutoModel
 
-```bash
-HF_ENDPOINT=https://hf-mirror.com hf download thu-sail-lab/Time-RCD --local-dir ./Time-RCD
+model = AutoModel.from_pretrained(
+    "thu-sail-lab/Time-RCD",
+    trust_remote_code=True,
+).eval()
+
+data = np.load("my_series.npy")  # shape: (T,)
+score_chunks, _ = model.zero_shot(data)
+scores = np.concatenate([chunk.reshape(-1) for chunk in score_chunks])[: len(data)]
 ```
 
-## Training and Benchmark Evaluation
+`zero_shot()` applies the same global normalization and windowing semantics as
+the official `TimeRCDDetector` inference API. The published Transformers
+configuration is univariate; use `TimeRCDDetector.from_pretrained(variant="multi")`
+for multivariate inference.
 
-For dataset preparation, pre-training, and TSB-AD benchmark evaluation, please use the [official GitHub repository](https://github.com/thu-sail-lab/Time-RCD):
+---
+
+## 📁 Project Structure
 
-```bash
-git clone https://github.com/thu-sail-lab/Time-RCD.git
-cd Time-RCD
+```
+.
+├── time_rcd/              # User-facing inference API
+│   ├── detector.py        # TimeRCDDetector
+│   └── _core/             # Time-RCD inference model implementation
+├── examples/
+│   └── quickstart.py      # Minimal inference example
+├── Tutorial.md            # Guide for your own data
+├── pyproject.toml         # Package metadata and dependencies
+├── zero-shot.png          # Model overview
+└── README.md
 ```
 
-- **Univariate evaluation:** `python main.py`
-- **Multivariate evaluation:** `python main.py --mode multi`
-- **Pre-training:** `python training.py --mode single --gpus 0 --num-workers 0`
+### TSB-AD benchmark code
 
-## Limitations
+The original benchmark integration, evaluation scripts, and baseline
+implementations are maintained in the
+[`tsb-ad-integration`](https://github.com/thu-sail-lab/Time-RCD/tree/tsb-ad-integration)
+branch. For the lightweight zero-shot inference API, use the `main` branch.
 
-- The default published config uses `num_features=1`. Multivariate inference may require the multivariate checkpoint and the full pipeline in the GitHub repository.
-- The model outputs anomaly likelihoods, not calibrated binary labels. Choose a task-specific threshold and validate it on representative data.
-- This Hugging Face repository is optimized for inference via Transformers. Training scripts, benchmark datasets, and evaluation utilities live in the GitHub repository.
+---
 
-## Citation
+## 🔗 Citation
 
 If you find this work useful, please cite our paper:
 
 ```bibtex
 @misc{lan2025foundationmodelszeroshottime,
-  title={Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy},
-  author={Tian Lan and Hao Duong Le and Jinbo Li and Wenjun He and Meng Wang and Chenghao Liu and Chen Zhang},
-  year={2025},
-  eprint={2509.21190},
-  archivePrefix={arXiv},
-  primaryClass={cs.LG},
-  url={https://arxiv.org/abs/2509.21190}
+      title={Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy}, 
+      author={Tian Lan and Hao Duong Le and Jinbo Li and Wenjun He and Meng Wang and Chenghao Liu and Chen Zhang},
+      year={2025},
+      eprint={2509.21190},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2509.21190}, 
 }
 ```

Tutorial.md

@@ -0,0 +1,146 @@
+# Time-RCD Tutorial
+
+Time-RCD is a zero-shot foundation model for time series anomaly detection. Given a univariate or multivariate series, it outputs an anomaly score in `[0, 1]` for each time step. Higher scores indicate a higher likelihood of an anomaly.
+
+## 1. Installation
+
+Python 3.10 is recommended:
+
+```bash
+conda create -n Time-RCD python=3.10
+conda activate Time-RCD
+
+git clone https://github.com/thu-sail-lab/Time-RCD.git
+cd Time-RCD
+pip install .
+```
+
+If you are in mainland China, set the Hugging Face mirror before the first automatic checkpoint download:
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+This variable only affects Hugging Face downloads. Cached checkpoints and weights loaded from local paths are unaffected.
+
+## 2. Univariate data
+
+Univariate input can be a NumPy array of shape `(T,)` or `(T, 1)`, where `T` is the number of time steps.
+
+```python
+import numpy as np
+
+from time_rcd import TimeRCDDetector
+
+data = np.load("series.npy")  # shape: (T,) or (T, 1)
+
+detector = TimeRCDDetector.from_pretrained(variant="uni")
+scores = detector.predict(data)
+
+print(scores.shape)  # (T,)
+```
+
+## 3. Multivariate data
+
+Multivariate input must have shape `(T, C)` with `C > 1`. Each column is one feature or sensor channel.
+
+```python
+import numpy as np
+
+from time_rcd import TimeRCDDetector
+
+data = np.load("multivariate_series.npy")  # shape: (T, C), C > 1
+
+detector = TimeRCDDetector.from_pretrained(variant="multi")
+scores = detector.predict(data)
+
+print(scores.shape)  # (T,)
+```
+
+The model is initialized on the first call to `predict()`, using the channel count `C`. If the same detector is later used on data with a different number of channels, the model is rebuilt automatically.
+
+## 4. Loading from CSV
+
+Rows should be in chronological order. Timestamp columns are not model features and should be removed before inference.
+
+```python
+import pandas as pd
+
+from time_rcd import TimeRCDDetector
+
+frame = pd.read_csv("sensor_data.csv")
+feature_columns = ["temperature", "pressure", "flow"]
+data = frame[feature_columns].to_numpy()
+
+detector = TimeRCDDetector.from_pretrained(variant="multi")
+scores = detector.predict(data)
+
+frame["anomaly_score"] = scores
+frame.to_csv("scored_sensor_data.csv", index=False)
+```
+
+For a univariate CSV, select one numeric column and use `variant="uni"`:
+
+```python
+data = frame["value"].to_numpy()
+detector = TimeRCDDetector.from_pretrained(variant="uni")
+scores = detector.predict(data)
+```
+
+## 5. Local checkpoints and offline inference
+
+If checkpoints are already on disk, you can avoid network access:
+
+```python
+from time_rcd import TimeRCDDetector
+
+detector = TimeRCDDetector.from_local(
+    "best_model/pretrain_checkpoint_best_uni.pth",
+    variant="uni",
+)
+scores = detector.predict(data)
+```
+
+To use the local cache without contacting the Hub:
+
+```python
+detector = TimeRCDDetector.from_pretrained(
+    variant="uni",
+    local_files_only=True,
+)
+```
+
+If nothing is cached, `local_files_only=True` will fail. Download the checkpoint once while online, or use `from_local()` instead.
+
+## 6. Common parameters
+
+```python
+detector = TimeRCDDetector.from_pretrained(
+    variant="uni",
+    win_size=5000,
+    batch_size=64,
+    device="cuda",  # or "cpu"
+)
+```
+
+- `win_size`: Sliding window length. Default is `5000`. Shorter sequences use the full sequence length.
+- `batch_size`: Inference batch size. Defaults to `64` (uni) or `1` (multi). Reduce it if you run out of GPU memory.
+- `device`: When omitted, CUDA is used if available; otherwise CPU.
+- `return_logits=True`: Return raw anomaly logits in addition to probability scores.
+
+The same detector can be reused on sequences of different lengths. A short sequence does not change the window setting for later predictions.
+
+## 7. Interpreting anomaly scores
+
+`scores` has one value per input time step, in `[0, 1]`. Higher values mean the model considers that time step more anomalous. Time-RCD does not ship a universal fixed threshold, because a good threshold depends on your data distribution, false-alarm cost, and expected anomaly rate.
+
+A simple starting point is a high quantile of scores from known normal data:
+
+```python
+import numpy as np
+
+threshold = np.quantile(normal_scores, 0.995)
+is_anomaly = scores >= threshold
+```
+
+Calibrate the threshold on labeled validation data or known normal history. Do not deploy the example quantile directly to production without evaluation.

config.json

@@ -5,11 +5,10 @@
   ],
   "auto_map": {
     "AutoConfig": "configuration_time_rcd.TimeRCDConfig",
-    "AutoModel": "modeling_time_rcd.Time_RCD",
-    "AutoProcessor": "processing_time_rcd.TimeRCDProcessor"
+    "AutoModel": "modeling_time_rcd.Time_RCD"
   },
   "batch_size": 64,
-  "d_ff_dropout": 0.05,
+  "d_ff_dropout": 0.1,
   "d_model": 512,
   "d_proj": 256,
   "dropout": 0.1,
@@ -20,7 +19,7 @@
   "num_heads": 8,
   "num_layers": 8,
   "patch_size": 16,
-  "transformers_version": "4.56.2",
+  "transformers_version": "5.4.0",
   "use_rope": true,
   "win_size": 5000
 }

examples/quickstart.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Minimal Time-RCD inference example on synthetic data."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from time_rcd import TimeRCDDetector
+
+
+def main() -> None:
+    rng = np.random.default_rng(42)
+    length = 2048
+    data = rng.normal(size=length)
+
+    # Inject a simple anomaly spike.
+    data[1000:1010] += 8.0
+
+    detector = TimeRCDDetector.from_pretrained(variant="uni")
+    scores = detector.predict(data)
+
+    print(f"Input shape: {data.shape}")
+    print(f"Score shape: {scores.shape}")
+    print(f"Top-5 anomaly indices: {np.argsort(scores)[-5:][::-1]}")
+
+
+if __name__ == "__main__":
+    main()

model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:73a44d4a4fd9d1e47a878d1d454df30a6f597c154b39a8ced16b3c1095dcd2ac
+oid sha256:0ee52a69b6f242d8178ce85910348d8e95126681ef93dc283356a8929ecb046c
 size 148240612

modeling_time_rcd.py

@@ -133,6 +133,7 @@ class Time_RCD(PreTrainedModel):
         time_series: torch.Tensor,
         attention_mask: Optional[torch.Tensor] = None,
         return_dict: Optional[bool] = None,
+        normalize_input: bool = True,
     ) -> Union[Tuple, TimeRCDOutput]:
         """
         Forward pass through Time_RCD model
@@ -144,13 +145,18 @@ class Time_RCD(PreTrainedModel):
                 Mask to avoid performing attention on padding token indices.
             return_dict (`bool`, *optional*):
                 Whether to return a ModelOutput instead of a plain tuple.
+            normalize_input (`bool`, *optional*, defaults to `True`):
+                Whether to normalize each input window. Set this to `False`
+                only when the input has already been normalized globally.
         """
-        return_dict = return_dict if return_dict is not None else self.config.use_return_dict
+        return_dict = return_dict if return_dict is not None else self.config.return_dict
 
         batch_size, seq_len, num_features = time_series.shape
 
-        # Normalize time series (exactly like your original)
-        time_series = (time_series - time_series.mean(dim=1, keepdim=True)) / (time_series.std(dim=1, keepdim=True) + 1e-8)
+        if normalize_input:
+            time_series = (
+                time_series - time_series.mean(dim=1, keepdim=True)
+            ) / (time_series.std(dim=1, keepdim=True) + 1e-8)
 
         # Get embeddings from encoder
         embeddings = self.ts_encoder(time_series, attention_mask)  # (B, seq_len, num_features, d_proj)
@@ -176,92 +182,100 @@ class Time_RCD(PreTrainedModel):
 
     def zero_shot(self, data: np.ndarray, batch_size: int = 64, win_size: int = 5000) -> tuple:
         """
-        Zero-shot inference method matching AnomalyCLIP structure.
-        
-        The model handles normalization internally, so no external processor needed!
-        This method only handles windowing for long sequences.
-        
+        Zero-shot inference for long time series.
+
+        Windowing and padding follow the official GitHub inference backend in
+        ``time_rcd/_inference.py``. Scores are returned in batch chunks; flatten
+        them with ``np.concatenate([chunk.reshape(-1) for chunk in scores])``.
+
         Args:
             data: Input time series data of shape (n_samples, n_features) or (n_samples,)
             batch_size: Batch size for processing
-            win_size: Window size for processing (only used if data > win_size)
-            
+            win_size: Sliding window length
+
         Returns:
-            tuple: (scores, logits) where:
-                - scores: list of anomaly score arrays per batch
-                - logits: list of anomaly logit arrays per batch
+            tuple: (scores, logits) where each item is a list of numpy arrays,
+            one per inference batch.
         """
-        import tqdm
-        from torch.utils.data import DataLoader, TensorDataset
-        
+        from torch.utils.data import DataLoader, Dataset
+
+        class _WindowDataset(Dataset):
+            """Split a time series into non-overlapping padded windows."""
+
+            def __init__(self, series: np.ndarray, window_size: int) -> None:
+                self.original_length = len(series)
+                mean = np.mean(series, axis=0)
+                std = np.where(np.std(series, axis=0) == 0, 1e-8, np.std(series, axis=0))
+                series = (series - mean) / std
+                padding = (-len(series)) % window_size
+                if padding:
+                    series = np.vstack(
+                        [series, np.repeat(series[-1:, :], padding, axis=0)]
+                    )
+                self.data = series
+                self.window_size = window_size
+
+            def __len__(self) -> int:
+                return len(self.data) // self.window_size
+
+            def __getitem__(self, index: int):
+                start = index * self.window_size
+                end = start + self.window_size
+                valid_length = min(self.window_size, self.original_length - start)
+                mask = torch.zeros(self.window_size, dtype=torch.bool)
+                mask[:valid_length] = True
+                return (
+                    torch.tensor(self.data[start:end], dtype=torch.float32),
+                    mask,
+                )
+
+        def _collate_windows(batch):
+            time_series, attention_mask = zip(*batch)
+            return {
+                "time_series": torch.stack(time_series),
+                "attention_mask": torch.stack(attention_mask),
+            }
+
         self.eval()
         device = next(self.parameters()).device
-        
-        # Ensure numpy and 2D shape
-        data = np.asarray(data)
+
+        data = np.asarray(data, dtype=np.float64)
         if data.ndim == 1:
             data = data.reshape(-1, 1)
-        
-        # Adjust window size if data is too short
-        if len(data) <= win_size:
-            win_size = len(data)
-        
-        # Create windows if data is longer than win_size
-        windows = []
-        masks = []
-        
-        if len(data) > win_size:
-            # Create non-overlapping windows
-            for i in range(0, len(data), win_size):
-                window = data[i:i + win_size]
-                if len(window) < win_size:
-                    # Pad last window if needed
-                    padded = np.zeros((win_size, data.shape[1]))
-                    padded[:len(window)] = window
-                    window = padded
-                    mask = np.zeros(win_size, dtype=bool)
-                    mask[:len(window)] = True
-                else:
-                    mask = np.ones(win_size, dtype=bool)
-                windows.append(window)
-                masks.append(mask)
-        else:
-            # Single window
-            windows.append(data)
-            masks.append(np.ones(len(data), dtype=bool))
-        
-        # Convert to tensors
-        time_series_windows = torch.tensor(np.array(windows), dtype=torch.float32)
-        attention_masks = torch.tensor(np.array(masks), dtype=torch.bool)
-        
-        # Create dataloader
-        dataset = TensorDataset(time_series_windows, attention_masks)
-        dataloader = DataLoader(dataset, batch_size=batch_size, shuffle=False)
-        
-        loop = tqdm.tqdm(enumerate(dataloader), total=len(dataloader), leave=True)
+        elif data.ndim != 2:
+            raise ValueError(f"data must be 1D or 2D, got shape {data.shape}")
+
+        window_size = min(len(data), win_size)
+        dataset = _WindowDataset(data, window_size)
+        dataloader = DataLoader(
+            dataset,
+            batch_size=batch_size,
+            collate_fn=_collate_windows,
+            num_workers=0,
+            shuffle=False,
+        )
+
         scores = []
         logits = []
-        
+
         with torch.no_grad():
-            for i, (batch_ts, batch_mask) in loop:
-                batch_ts = batch_ts.to(device)
-                batch_mask = batch_mask.to(device)
-                
-                # Forward pass (model normalizes internally!)
+            for batch in dataloader:
+                batch_ts = batch["time_series"].to(device)
+                batch_mask = batch["attention_mask"].to(device)
                 outputs = self(
                     time_series=batch_ts,
                     attention_mask=batch_mask,
-                    return_dict=True
+                    return_dict=True,
+                    normalize_input=False,
                 )
-                
-                # Extract scores and logits
-                anomaly_probs = outputs.anomaly_scores.cpu().numpy()  # (B, seq_len)
-                anomaly_logits = outputs.anomaly_logits  # (B, seq_len, 2)
-                logit_diff = anomaly_logits[..., 1] - anomaly_logits[..., 0]  # (B, seq_len)
-                
+
+                anomaly_probs = outputs.anomaly_scores.cpu().numpy()
+                anomaly_logits = outputs.anomaly_logits
+                logit_diff = anomaly_logits[..., 1] - anomaly_logits[..., 0]
+
                 scores.append(anomaly_probs)
                 logits.append(logit_diff.cpu().numpy())
-        
+
         return scores, logits
 
     @classmethod

pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "time-rcd"
+version = "0.1.0"
+description = "Zero-shot time series anomaly detection with Time-RCD"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "THU SAIL Lab" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "einops>=0.7.0",
+    "huggingface_hub>=0.20.0",
+    "jaxtyping>=0.2.25",
+    "numpy>=1.24.0",
+    "torch>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/thu-sail-lab/Time-RCD"
+Repository = "https://github.com/thu-sail-lab/Time-RCD"
+
+[tool.setuptools]
+packages = ["time_rcd", "time_rcd._core"]

requirements.txt

@@ -1,4 +1,7 @@
+einops>=0.7.0
+huggingface_hub>=0.20.0
+jaxtyping>=0.2.25
+numpy>=1.24.0
+scikit-learn>=1.0.0
 torch>=2.0.0
 transformers>=4.30.0
-numpy>=1.20.0
-scikit-learn>=1.0.0

time_rcd.egg-info/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: time-rcd
+Version: 0.1.0
+Summary: Zero-shot time series anomaly detection with Time-RCD
+Author: THU SAIL Lab
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           Copyright 2025-2026 Tsinghua SAIL Lab and contributors
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/thu-sail-lab/Time-RCD
+Project-URL: Repository, https://github.com/thu-sail-lab/Time-RCD
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: einops>=0.7.0
+Requires-Dist: huggingface_hub>=0.20.0
+Requires-Dist: jaxtyping>=0.2.25
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: torch>=2.0.0
+Dynamic: license-file
+
+---
+library_name: transformers
+license: apache-2.0
+tags:
+  - time-series
+  - anomaly-detection
+  - custom_code
+---
+
+> **Official model repository.** This Hugging Face repository hosts the checkpoints used by the official [Time-RCD GitHub project](https://github.com/thu-sail-lab/Time-RCD), as well as a Transformers-compatible model implementation. The recommended inference API is `TimeRCDDetector` below.
+
+<div align="center">
+
+# Time-RCD
+
+_Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy_
+
+[![arXiv](https://img.shields.io/badge/arXiv-2509.21190-b31b1b.svg)](https://arxiv.org/abs/2509.21190)
+[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Demo-yellow)](https://huggingface.co/spaces/thu-sail-lab/Time_RCD)
+[![时空探索之旅](https://img.shields.io/badge/时空探索之旅-black?logo=wechat&logoColor=white)](https://mp.weixin.qq.com/s/79M3jsEhMKBzbNYpROOBCw)
+
+</div>
+
+<p align="center">
+    📰&nbsp;<a href="#-news">News</a>
+    | 🔍&nbsp;<a href="#-about">About</a>
+    | 🎯&nbsp;<a href="#-use-on-your-own-data">Use on Your Own Data</a>
+    | 📁&nbsp;<a href="#-project-structure">Project Structure</a>
+    | 🔗&nbsp;<a href="#-citation">Citation</a>
+</p>
+
+## 📰 News
+
+- **2026.05:** Time-RCD has been accepted by **ICML 2026**. We also release the [pre-trained dataset generation code and hyperparameters](https://github.com/thu-sail-lab/TSAD_dataset_gen_public).
+
+- **2026.04:** With a new dataset and new checkpoints, Time-RCD achieves better results. The univariate setting improves VUS-PR by an **absolute 6.7 points**, and the multivariate setting improves VUS-PR by an **absolute 4.5 points**.
+
+## 🔍 About
+
+**Time-RCD** is a zero-shot foundation model for time series anomaly detection. Given a univariate or multivariate series, it outputs a per-timestep anomaly score without any task-specific training on your data.
+
+🐘 On the [TSB-AD benchmark](https://thedatumorg.github.io/TSB-AD/), Time-RCD achieves a **Univariate VUS-PR of 0.52** and a **Multivariate VUS-PR of 0.32**.
+
+**[🌟 Live Demo on Hugging Face Spaces](https://huggingface.co/spaces/thu-sail-lab/Time_RCD)** — try Time-RCD interactively in your browser.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/thu-sail-lab/Time-RCD/main/zero-shot.png" style="width:95%;" />
+</div>
+
+This repository contains:
+
+1. **`time_rcd/`** — a lightweight Python API for inference on your own data
+
+For a step-by-step guide, see **[Tutorial.md](https://github.com/thu-sail-lab/Time-RCD/blob/main/Tutorial.md)**.
+
+---
+
+## 🎯 Use on Your Own Data
+
+### Installation
+
+```bash
+conda create -n Time-RCD python=3.10
+conda activate Time-RCD
+
+git clone https://github.com/thu-sail-lab/Time-RCD.git
+cd Time-RCD
+pip install .
+```
+
+When working from a local clone of this Hugging Face repository, install the same official inference package with:
+
+```bash
+pip install .
+```
+
+### Python API (recommended)
+
+Checkpoints are downloaded from Hugging Face automatically on first use and cached locally.
+For servers in China, set `HF_ENDPOINT=https://hf-mirror.com` before running
+the examples or loading a checkpoint.
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+```python
+import numpy as np
+from time_rcd import TimeRCDDetector
+
+data = np.load("my_series.npy")  # shape (T,) or (T, C)
+
+detector = TimeRCDDetector.from_pretrained(variant="uni")   # or "multi"
+scores = detector.predict(data)                             # shape (T,)
+```
+
+**Multivariate series** — use `variant="multi"` when `C > 1`:
+
+```python
+detector = TimeRCDDetector.from_pretrained(variant="multi")
+scores = detector.predict(multivariate_data)  # shape (T, C) -> scores (T,)
+```
+
+**Local checkpoint** — if you already downloaded weights:
+
+```python
+detector = TimeRCDDetector.from_local(
+    "best_model/pretrain_checkpoint_best_uni.pth",
+    variant="uni",
+)
+```
+
+### Quick example
+
+```bash
+python examples/quickstart.py
+```
+
+See **[Tutorial.md](https://github.com/thu-sail-lab/Time-RCD/blob/main/Tutorial.md)** for CSV loading, hyperparameters, and more examples.
+
+---
+
+## 📁 Project Structure
+
+```
+.
+├── time_rcd/              # User-facing inference API
+│   ├── detector.py        # TimeRCDDetector
+│   └── _core/             # Time-RCD inference model implementation
+├── examples/
+│   └── quickstart.py      # Minimal inference example
+├── Tutorial.md            # Guide for your own data
+├── pyproject.toml         # Package metadata and dependencies
+├── zero-shot.png          # Model overview
+└── README.md
+```
+
+### TSB-AD benchmark code
+
+The original benchmark integration, evaluation scripts, and baseline
+implementations are maintained in the
+[`tsb-ad-integration`](https://github.com/thu-sail-lab/Time-RCD/tree/tsb-ad-integration)
+branch. For the lightweight zero-shot inference API, use the `main` branch.
+
+---
+
+## 🔗 Citation
+
+If you find this work useful, please cite our paper:
+
+```bibtex
+@misc{lan2025foundationmodelszeroshottime,
+      title={Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy}, 
+      author={Tian Lan and Hao Duong Le and Jinbo Li and Wenjun He and Meng Wang and Chenghao Liu and Chen Zhang},
+      year={2025},
+      eprint={2509.21190},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2509.21190}, 
+}
+```

time_rcd.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+time_rcd/__init__.py
+time_rcd/_inference.py
+time_rcd/detector.py
+time_rcd.egg-info/PKG-INFO
+time_rcd.egg-info/SOURCES.txt
+time_rcd.egg-info/dependency_links.txt
+time_rcd.egg-info/requires.txt
+time_rcd.egg-info/top_level.txt
+time_rcd/_core/TimeRCD_pretrain_multi.py
+time_rcd/_core/__init__.py
+time_rcd/_core/dataset.py
+time_rcd/_core/full_reconstruction.py
+time_rcd/_core/time_rcd_config.py
+time_rcd/_core/ts_encoder_bi_bias.py

time_rcd.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

time_rcd.egg-info/requires.txt

@@ -0,0 +1,5 @@
+einops>=0.7.0
+huggingface_hub>=0.20.0
+jaxtyping>=0.2.25
+numpy>=1.24.0
+torch>=2.0.0

time_rcd.egg-info/top_level.txt

@@ -0,0 +1 @@
+time_rcd

time_rcd/__init__.py

@@ -0,0 +1,3 @@
+from time_rcd.detector import TimeRCDDetector
+
+__all__ = ["TimeRCDDetector"]

time_rcd/_core/TimeRCD_pretrain_multi.py

@@ -0,0 +1,236 @@
+import datetime
+import itertools
+import os
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, DistributedSampler
+import torch.nn.functional as F
+import torch.distributed as dist
+import torch.multiprocessing as mp
+from torch.nn.parallel import DistributedDataParallel as DDP
+import random
+import numpy as np
+from typing import Tuple, List, Dict, Any, Union, Optional
+from dataclasses import dataclass
+
+from .dataset import ChatTSTimeRCDPretrainDataset
+from .ts_encoder_bi_bias import TimeSeriesEncoder
+from .time_rcd_config import TimeRCDConfig, default_config
+
+import warnings
+
+warnings.filterwarnings("ignore")
+
+@dataclass
+class PretrainBatch:
+    """Batch structure for pretraining tasks."""
+    time_series: torch.Tensor
+    labels: torch.Tensor
+    masked_time_series: torch.Tensor
+    mask_indices: torch.Tensor
+
+
+class TimeSeriesPretrainModel(nn.Module):
+    """Model for time series pretraining with masked reconstruction and anomaly detection."""
+
+    def __init__(self, config: TimeRCDConfig):
+        super().__init__()
+        self.config = config
+
+        # Extract TimeSeriesEncoder parameters from config
+        ts_config = config.ts_config
+        self.ts_encoder = TimeSeriesEncoder(
+            d_model=ts_config.d_model,
+            d_proj=ts_config.d_proj,
+            patch_size=ts_config.patch_size,
+            num_layers=ts_config.num_layers,
+            num_heads=ts_config.num_heads,
+            d_ff_dropout=ts_config.d_ff_dropout,
+            use_rope=ts_config.use_rope,
+            num_features=ts_config.num_features,
+            activation=ts_config.activation
+        )
+
+        # Masked reconstruction head
+        self.reconstruction_head = nn.Sequential(
+            nn.Linear(config.ts_config.d_proj, config.ts_config.d_proj * 4),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(config.ts_config.d_proj * 4, config.ts_config.d_proj * 4),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(config.ts_config.d_proj * 4, 1)  # (B, seq_len, num_features, 1)
+        )
+
+        # Anomaly detection head
+        self.anomaly_head = nn.Sequential(
+            nn.Linear(config.ts_config.d_proj, config.ts_config.d_proj // 2),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(config.ts_config.d_proj // 2, 2)  # (B, seq_len, num_features, 2) for binary classification
+        )
+
+    def forward(self, time_series: torch.Tensor, mask: Optional[torch.Tensor] = None):
+        """Forward pass through the encoder."""
+        local_embeddings = self.ts_encoder(time_series, mask)
+        return local_embeddings
+
+    def masked_reconstruction_loss(self,
+                                   local_embeddings: torch.Tensor,  # (B, seq_len, num_features, d_proj)
+                                   original_time_series: torch.Tensor,  # (B, seq_len, num_features),
+                                   mask: torch.Tensor  # (B, seq_len)
+                                   ) -> torch.Tensor:
+        """Compute masked reconstruction loss."""
+        batch_size, seq_len, num_features = original_time_series.shape
+        patch_size = self.config.ts_config.patch_size
+
+        mask = mask.bool()
+
+        # local_embeddings: [B, seq_len, num_features, d_proj]
+        reconstructed = self.reconstruction_head(local_embeddings)  # (B, seq_len, num_features, 1)
+        reconstructed = reconstructed.view(batch_size, seq_len, num_features)
+
+        mask_expanded = mask.unsqueeze(-1).expand(-1, -1, num_features)  # (B, seq_len, num_features)
+        reconstruction_loss = F.mse_loss(
+            reconstructed[mask_expanded],
+            original_time_series[mask_expanded]
+        )
+        return reconstruction_loss
+
+    def anomaly_detection_loss(self,
+                               local_embeddings: torch.Tensor,  # (B, seq_len, num_features, d_proj)
+                               labels: torch.Tensor) -> torch.Tensor:  # (B, seq_len)
+        """Compute anomaly detection loss for each timestep."""
+        # Project local embeddings to anomaly scores
+        logits = self.anomaly_head(local_embeddings)  # (B, seq_len, num_features, 2)
+        logits = torch.mean(logits, dim=-2)  # Average over num_features to get (B, seq_len, 2)
+
+        # Reshape for loss computation
+        batch_size, seq_len, _ = logits.shape
+        logits = logits.view(-1, 2)  # (B*seq_len, 2)
+        labels = labels.view(-1)  # (B*seq_len)
+        labels = (labels > 0.5).long()
+        # Create mask for valid labels (not padding)
+        valid_mask = (labels != -1)
+
+        # Compute loss only on valid timesteps
+        if valid_mask.sum() > 0:
+            anomaly_loss = F.cross_entropy(
+                logits[valid_mask],
+                labels[valid_mask]
+            )
+        else:
+            anomaly_loss = torch.tensor(0.0, device=logits.device)
+
+        return anomaly_loss
+
+
+def create_random_mask(time_series: torch.Tensor,  # (B, max_seq_len, num_features)
+                       attention_mask: torch.Tensor,  # (B, max_seq_len)
+                       mask_ratio: float = 0.15) -> Tuple[torch.Tensor, torch.Tensor]:
+    """Create random mask for time series patches, only masking valid sequence parts."""
+    batch_size, seq_len, num_features = time_series.shape
+    patch_size = default_config.ts_config.patch_size
+
+    mask = torch.zeros(batch_size, seq_len)  # (B, max_seq_len)
+
+    for i in range(batch_size):
+        # Get valid sequence length for this sample
+        valid_length = attention_mask[i].sum().item()
+
+        # Calculate number of patches in valid sequence
+        num_valid_patches = (valid_length - 1) // patch_size + 1
+        num_masked = int(num_valid_patches * mask_ratio)
+
+        if num_masked > 0:
+            # Only select patches from valid sequence
+            masked_patches = torch.randperm(num_valid_patches)[:num_masked]
+            for j in masked_patches:
+                start_idx = j * patch_size
+                end_idx = min((j + 1) * patch_size, valid_length)  # Don't exceed valid length
+                mask[i, start_idx:end_idx] = 1
+
+    # Create masked time series - only mask valid parts
+    masked_time_series = time_series.clone()
+    mask_indices = mask.bool() & attention_mask  # Only mask where both mask and attention_mask are True
+    mask_expanded = mask_indices.unsqueeze(-1).expand(-1, -1, num_features)  # (B, max_seq_len, num_features)
+    masked_time_series[mask_expanded] = torch.randn_like(masked_time_series[mask_expanded]) * 0.1
+
+    # Update mask to only include valid parts
+    mask = mask * attention_mask.float()
+
+    return masked_time_series, mask  # (B, max_seq_len, num_features), (B, max_seq_len)
+
+
+def collate_fn(batch):
+    """Collate function for pretraining dataset."""
+    time_series_list, normal_time_series_list, labels_list, attribute_list = zip(*batch)
+
+    # Convert to tensors and pad sequences
+    if time_series_list[0].ndim == 1:
+        time_series_tensors = [ts.unsqueeze(-1) for ts in time_series_list]  # Add feature dimension
+        normal_time_series_tensors = [nts.unsqueeze(-1) for nts in normal_time_series_list]
+    else:
+        time_series_tensors = [ts for ts in time_series_list]
+        normal_time_series_tensors = [nts for nts in normal_time_series_list]
+
+    # standardize time series
+    concatenated = torch.cat(time_series_tensors, dim=0)  # (total_length, num_features)
+    mean = concatenated.mean(dim=0, keepdim=True)  # (1, num_features)
+    std = concatenated.std(dim=0, keepdim=True)  # (1, num_features)
+    std = std + 1e-4
+    time_series_tensors_std = [(ts - mean) / std for ts in time_series_tensors]
+    normal_time_series_tensors_std = [(nts - mean) / std for nts in normal_time_series_tensors]
+    time_series_tensors = time_series_tensors_std
+    normal_time_series_tensors = normal_time_series_tensors_std
+
+    # labels_tensor = torch.stack(labels_list)
+    labels = [label for label in labels_list]
+    # Pad time series to same length
+    padded_time_series = torch.nn.utils.rnn.pad_sequence(
+        time_series_tensors, batch_first=True, padding_value=0.0
+    )  # (B, max_seq_len, num_features)
+    padded_normal_time_series = torch.nn.utils.rnn.pad_sequence(
+        normal_time_series_tensors, batch_first=True, padding_value=0.0
+    )  # (B, max_seq_len, num_features)
+    padded_labels = torch.nn.utils.rnn.pad_sequence(
+        labels, batch_first=True, padding_value=-1
+    )  # (B, max_seq_len)
+
+    sequence_lengths = [ts.size(0) for ts in time_series_tensors]
+    B, max_seq_len, num_features = padded_time_series.shape
+    attention_mask = torch.zeros(B, max_seq_len, dtype=torch.bool)  # (B, max_seq_len)
+    for i, length in enumerate(sequence_lengths):
+        attention_mask[i, :length] = True
+
+        # Create random masks for reconstruction task - only mask valid sequence parts
+    masked_time_series, mask = create_random_mask(padded_time_series, attention_mask)
+
+    return {
+        'time_series': padded_time_series,
+        'normal_time_series': padded_normal_time_series,
+        'masked_time_series': masked_time_series,
+        'mask': mask,  # for reconstruction task
+        'labels': padded_labels,
+        'attention_mask': attention_mask,  # for padding
+        'attribute': attribute_list
+    }
+
+def test_collate_fn(batch):
+    """Collate function for pretraining dataset."""
+    # Unpack the batch correctly - batch is a list of (time_series, mask) tuples
+    time_series_list, mask_list = zip(*batch)
+
+    # Stack into batch format instead of concatenating
+    # This maintains the batch dimension: (B, seq_len, num_features)
+    batched_time_series = torch.stack(time_series_list, dim=0)
+    print(f"batched_time_series shape: {batched_time_series.shape}")
+    # Stack masks into batch format: (B, seq_len)
+    batched_mask = torch.stack(mask_list, dim=0)
+    print(f"batched_mask shape: {batched_mask.shape}")
+
+    return {
+        'time_series': batched_time_series,
+        'attention_mask': batched_mask,  # for padding
+    }

time_rcd/_core/dataset.py

@@ -0,0 +1,151 @@
+import json
+import numpy as np
+import torch
+from torch.utils.data import Dataset
+import random
+import os
+import pickle
+from typing import Dict, List, Union, Optional, Tuple
+from pathlib import Path
+
+
+class ChatTSTimeRCDPretrainDataset(Dataset):
+    def __init__(self,
+                 dataset_dir: str,
+                 filename: str,
+                 split: str = 'train',
+                 train_ratio: float = 0.95,
+                 seed: int = 42):
+        file_path = os.path.join(dataset_dir, filename)
+        with open(file_path, 'rb') as f:
+            dataset = pickle.load(f)
+        random.seed(seed)
+        indices = list(range(len(dataset)))
+        random.shuffle(indices)
+        num_train = int(len(dataset) * train_ratio)
+        if split == 'train':
+            selected_indices = indices[:num_train]
+        elif split == 'test':
+            selected_indices = indices[num_train:]
+        else:
+            raise ValueError("split must be 'train' or 'test'")
+        self.data = [dataset[i] for i in selected_indices]
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        sample = self.data[idx]
+        time_series = torch.tensor(sample['time_series'], dtype=torch.float32)
+        normal_time_series = torch.tensor(sample['normal_time_series'], dtype=torch.float32)
+        labels = torch.tensor(sample['labels'], dtype=torch.long)
+        attribute = sample['attribute']
+        return time_series, normal_time_series, labels, attribute
+
+
+class ChatTSTimeRCDQADataset(Dataset):
+    """Dataset class for time series anomaly detection with QA pairs.
+
+    This dataset loads time series data and corresponding question-answer pairs
+    for anomaly detection tasks. It supports train/val split and efficient loading
+    of series data from the time_rcd_datasets format.
+
+    Attributes:
+        split (str): Dataset split, either 'train' or 'val'
+        series_dir (Path): Directory containing series JSON files
+        metadata (Dict): Dataset metadata loaded from metadata.json
+        series_files (List[str]): List of series file paths
+        window_size_range (Tuple[int, int]): Range of window sizes used in the dataset
+    """
+
+    def __init__(
+            self,
+            dataset_dir: str,
+            split: str = 'train',
+            train_ratio: float = 0.95,
+            seed: int = 42,
+            cache_size: int = 1000
+    ) -> None:
+        """Initialize the dataset.
+
+        Args:
+            dataset_dir: Path to the dataset directory containing metadata.json and series/
+            split: Dataset split, either 'train' or 'val'
+            train_ratio: Ratio of training samples (default: 0.8)
+            seed: Random seed for reproducibility (default: 42)
+            cache_size: Number of series files to keep in memory (default: 1000)
+        """
+        self.split = split
+        self.series_dir = Path(dataset_dir) / 'series'
+
+        # Get all series files and shuffle them
+        self.series_files = sorted(self.series_dir.glob('series_*.json'))
+        random.seed(seed)
+        random.shuffle(self.series_files)
+
+        # Split into train/val
+        split_idx = int(len(self.series_files) * train_ratio)
+        self.series_files = self.series_files[:split_idx] if split == 'train' else self.series_files[split_idx:]
+
+        # Initialize LRU cache for series data
+        self._cache = {}
+        self._cache_size = cache_size
+        self._cache_order = []
+
+    def _load_series(self, file_path: Path) -> Dict:
+        """Load a series file with caching.
+
+        Args:
+            file_path: Path to the series JSON file
+
+        Returns:
+            Dictionary containing the series data
+        """
+        if file_path in self._cache:
+            # Update cache order
+            self._cache_order.remove(file_path)
+            self._cache_order.append(file_path)
+            return self._cache[file_path]
+
+        # Load new file
+        with open(file_path, 'r') as f:
+            data = json.load(f)
+
+        # Update cache
+        if len(self._cache) >= self._cache_size:
+            # Remove oldest item
+            oldest = self._cache_order.pop(0)
+            del self._cache[oldest]
+
+        self._cache[file_path] = data
+        self._cache_order.append(file_path)
+        return data
+
+    def __len__(self) -> int:
+        """Return the number of samples in the dataset."""
+        return len(self.series_files)
+
+    def __getitem__(self, idx: int) -> Dict[str, Union[torch.Tensor, List[Dict]]]:
+        """Get a sample from the dataset.
+
+        Args:
+            idx: Index of the sample to retrieve
+
+        Returns:
+            Dictionary containing:
+                - time_series: Time series data as torch.Tensor
+                - windows: List of window data containing QA pairs
+                - sample_id: Unique identifier for the sample
+        """
+        file_path = self.series_files[idx]
+        data = self._load_series(file_path)
+
+        # Convert time series to tensor
+        time_series = np.array(data['original_data']['time_series'])
+        time_series_tensor = torch.FloatTensor(time_series)
+
+        return {
+            'time_series': time_series_tensor,
+            'analysis_data': data['windows']
+        }
+

time_rcd/_core/full_reconstruction.py

@@ -0,0 +1,214 @@
+import datetime
+import itertools
+import os
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, DistributedSampler
+import torch.nn.functional as F
+import torch.distributed as dist
+import torch.multiprocessing as mp
+from torch.nn.parallel import DistributedDataParallel as DDP
+import random
+import numpy as np
+from typing import Tuple, List, Dict, Any, Union, Optional
+from dataclasses import dataclass
+
+from .dataset import ChatTSTimeRCDPretrainDataset
+from .ts_encoder_bi_bias import TimeSeriesEncoder
+from .time_rcd_config import TimeRCDConfig, default_config
+
+import warnings
+warnings.filterwarnings("ignore")
+
+@dataclass
+class PretrainBatch:
+    """Batch structure for pretraining tasks."""
+    time_series: torch.Tensor
+    labels: torch.Tensor
+    masked_time_series: torch.Tensor
+    mask_indices: torch.Tensor
+    
+
+class TimeSeriesPretrainModel(nn.Module):
+    """Model for time series pretraining with masked reconstruction and anomaly detection."""
+    
+    def __init__(self, config: TimeRCDConfig):
+        super().__init__()
+        self.config = config
+        
+        # Extract TimeSeriesEncoder parameters from config
+        ts_config = config.ts_config
+        self.ts_encoder = TimeSeriesEncoder(
+            d_model=ts_config.d_model,
+            d_proj=ts_config.d_proj,
+            patch_size=ts_config.patch_size,
+            num_layers=ts_config.num_layers,
+            num_heads=ts_config.num_heads,
+            d_ff_dropout=ts_config.d_ff_dropout,
+            use_rope=ts_config.use_rope,
+            num_features=ts_config.num_features,
+            activation=ts_config.activation
+        )
+        
+        # Masked reconstruction head
+        self.reconstruction_head = nn.Sequential(
+            nn.Linear(config.ts_config.d_proj, config.ts_config.d_proj * 4),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(config.ts_config.d_proj * 4, config.ts_config.d_proj * 4),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(config.ts_config.d_proj * 4, 1)  # (B, seq_len, num_features, 1)
+        )
+        self.reconstruction_head.apply(self._init_weights)
+
+    def _init_weights(self, module):
+        if isinstance(module, nn.Linear):
+            nn.init.xavier_normal_(module.weight)
+            if module.bias is not None:
+                nn.init.zeros_(module.bias)
+
+    def forward(self, time_series: torch.Tensor, mask: Optional[torch.Tensor] = None):
+        """Forward pass through the encoder."""
+        local_embeddings = self.ts_encoder(time_series, mask)
+        return local_embeddings
+
+    def masked_reconstruction_loss(self, 
+                                   local_embeddings: torch.Tensor,  # (B, seq_len, num_features, d_proj)
+                                   original_time_series: torch.Tensor,  # (B, seq_len, num_features),
+                                   mask: torch.Tensor  # (B, seq_len)
+                                   ) -> torch.Tensor:
+        """Compute masked reconstruction loss."""
+        batch_size, seq_len, num_features = original_time_series.shape
+        patch_size = self.config.ts_config.patch_size
+        
+        mask = mask.bool()
+        
+        # local_embeddings: [B, seq_len, num_features, d_proj]
+        reconstructed = self.reconstruction_head(local_embeddings)  # (B, seq_len, num_features, 1)
+        reconstructed = reconstructed.view(batch_size, seq_len, num_features)  
+        
+        mask_expanded = mask.unsqueeze(-1).expand(-1, -1, num_features)  # (B, seq_len, num_features)
+        reconstruction_loss = F.mse_loss(
+            reconstructed[mask_expanded],
+            original_time_series[mask_expanded]
+        )
+        return reconstruction_loss
+    
+def create_random_mask(time_series: torch.Tensor,  #(B, max_seq_len, num_features)
+                       attention_mask: torch.Tensor,  # (B, max_seq_len)
+                       mask_ratio: float = 0.15) -> Tuple[torch.Tensor, torch.Tensor]:
+    """Create random mask for time series patches, only masking valid sequence parts."""
+    batch_size, seq_len, num_features = time_series.shape
+    patch_size = default_config.ts_config.patch_size
+    
+    mask = torch.zeros(batch_size, seq_len)  # (B, max_seq_len)
+    
+    for i in range(batch_size):
+        # Get valid sequence length for this sample
+        valid_length = attention_mask[i].sum().item()
+        
+        # Calculate number of patches in valid sequence
+        num_valid_patches = (valid_length - 1) // patch_size + 1
+        num_masked = int(num_valid_patches * mask_ratio)
+        
+        if num_masked > 0:
+            # Only select patches from valid sequence
+            masked_patches = torch.randperm(num_valid_patches)[:num_masked]
+            for j in masked_patches:
+                start_idx = j * patch_size
+                end_idx = min((j + 1) * patch_size, valid_length)  # Don't exceed valid length
+                mask[i, start_idx:end_idx] = 1
+    
+    # Create masked time series - only mask valid parts
+    masked_time_series = time_series.clone()
+    mask_indices = mask.bool() & attention_mask  # Only mask where both mask and attention_mask are True
+    mask_expanded = mask_indices.unsqueeze(-1).expand(-1, -1, num_features)  # (B, max_seq_len, num_features)
+    masked_time_series[mask_expanded] = torch.randn_like(masked_time_series[mask_expanded]) * 0.1
+    
+    # Update mask to only include valid parts
+    mask = mask * attention_mask.float()
+    
+    return masked_time_series, mask  # (B, max_seq_len, num_features), (B, max_seq_len)
+
+
+def collate_fn(batch):
+    """Collate function for pretraining dataset."""
+    time_series_list, normal_time_series_list, labels_list, attribute_list = zip(*batch)
+    
+    # Convert to tensors and pad sequences
+    if time_series_list[0].ndim == 1:
+        time_series_tensors = [ts.unsqueeze(-1) for ts in time_series_list]  # Add feature dimension
+        normal_time_series_tensors = [nts.unsqueeze(-1) for nts in normal_time_series_list]
+    else:    
+        time_series_tensors = [ts for ts in time_series_list]
+        normal_time_series_tensors = [nts for nts in normal_time_series_list]
+
+    # standardize time series
+    # concatenated = torch.cat(time_series_tensors, dim=0)  # (total_length, num_features)
+    # mean = concatenated.mean(dim=0, keepdim=True)  # (1, num_features)
+    # std = concatenated.std(dim=0, keepdim=True)  # (1, num_features)
+    # std = std + 1e-4
+    # time_series_tensors_std = [(ts - mean) / std for ts in time_series_tensors]
+    # normal_time_series_tensors_std = [(nts - mean) / std for nts in normal_time_series_tensors]
+    # time_series_tensors = time_series_tensors_std
+    # normal_time_series_tensors = normal_time_series_tensors_std
+
+    means = []
+    stds = []
+    for i in range(len(time_series_tensors)):
+        ts = time_series_tensors[i]
+        mean = ts.mean(dim=0, keepdim=True)
+        std = ts.std(dim=0, keepdim=True) + 1e-4
+        means.append(mean)
+        stds.append(std)
+        time_series_tensors[i] = (ts - mean) / std
+    for i in range(len(normal_time_series_tensors)):
+        nts = normal_time_series_tensors[i]
+        mean = means[i]
+        std = stds[i]
+        normal_time_series_tensors[i] = (nts - mean) / std
+
+    # labels_tensor = torch.stack(labels_list)
+    labels = [label for label in labels_list]
+    # Pad time series to same length
+    padded_time_series = torch.nn.utils.rnn.pad_sequence(
+        time_series_tensors, batch_first=True, padding_value=0.0
+    )  # (B, max_seq_len, num_features) 
+    padded_normal_time_series = torch.nn.utils.rnn.pad_sequence(
+        normal_time_series_tensors, batch_first=True, padding_value=0.0
+    )  # (B, max_seq_len, num_features)
+    padded_labels = torch.nn.utils.rnn.pad_sequence(
+        labels, batch_first=True, padding_value=-1
+    )  # (B, max_seq_len)
+
+    sequence_lengths = [ts.size(0) for ts in time_series_tensors]
+    B, max_seq_len, num_features = padded_time_series.shape
+    attention_mask = torch.zeros(B, max_seq_len, dtype=torch.bool)  # (B, max_seq_len)
+    for i, length in enumerate(sequence_lengths):
+        attention_mask[i, :length] = True  
+    
+    # Create random masks for reconstruction task - only mask valid sequence parts
+    masked_time_series, mask = create_random_mask(padded_time_series, attention_mask)
+    
+    return {
+        'time_series': padded_time_series,
+        'normal_time_series': padded_normal_time_series,
+        'masked_time_series': masked_time_series,
+        'mask': mask,  # for reconstruction task
+        'labels': padded_labels,
+        'attention_mask': attention_mask,  # for padding
+        'attribute': attribute_list
+    }
+
+
+def set_seed(seed: int) -> None:
+    """Set random seed for reproducibility."""
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+        torch.backends.cudnn.deterministic = True
+        torch.backends.cudnn.benchmark = False

time_rcd/_core/time_rcd_config.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class TimeSeriesConfig:
+    """Configuration for time series encoder.
+
+    Attributes:
+        d_model: Dimension of model hidden states.
+        d_proj: Dimension of projection layer.
+        patch_size: Size of time series patches.
+        num_layers: Number of transformer layers.
+        num_heads: Number of attention heads.
+        d_ff_dropout: Dropout rate for feed-forward networks.
+        use_rope: Whether to use Rotary Position Embedding.
+        activation: Activation function name.
+        num_features: Number of input features.
+    """
+    d_model: int = 512
+    d_proj: int = 256
+    patch_size: int = 4
+    num_query_tokens: int = 1
+    num_layers: int = 8
+    num_heads: int = 8
+    d_ff_dropout: float = 0.1
+    use_rope: bool = True
+    activation: str = "gelu"
+    num_features: int = 1
+
+
+@dataclass
+class TimeRCDConfig:
+    """Configuration class for Time_RCD model.
+
+    This class contains all hyperparameters and settings for the Time_RCD model.
+    It is implemented as a dataclass for easy instantiation and modification.
+
+    Attributes:
+        ts_config: Configuration for time series encoder.
+        batch_size: Training batch size.
+        learning_rate: Learning rate for optimization.
+        num_epochs: Number of training epochs.
+        max_seq_len: Maximum sequence length.
+        dropout: Dropout rate.
+        accumulation_steps: Gradient accumulation steps.
+        weight_decay: Weight decay for optimization.
+        enable_ts_train: Whether to train the time series encoder.
+        seed: Random seed for reproducibility.
+    """
+
+    # Model configurations
+    ts_config: TimeSeriesConfig = field(default_factory=TimeSeriesConfig)
+
+    # Training parameters
+    batch_size: int = 3
+    learning_rate: float = 1e-4
+    num_epochs: int = 1000
+    max_seq_len: int = 512
+    dropout: float = 0.1
+    accumulation_steps: int = 1
+    weight_decay: float = 1e-5
+    enable_ts_train: bool = False
+    seed: int = 72
+
+    def to_dict(self) -> Dict[str, any]:
+        return {
+            "ts_config": self.ts_config.__dict__,
+        }
+
+default_config = TimeRCDConfig()

time_rcd/_core/ts_encoder_bi_bias.py

@@ -0,0 +1,376 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import math
+from jaxtyping import Float, Int
+from einops import rearrange
+
+
+class RMSNorm(nn.Module):
+    """Root Mean Square Normalization layer."""
+
+    def __init__(self, size: int, dim: int = -1, eps: float = 1e-5) -> None:
+        super().__init__()
+        self.scale = nn.Parameter(torch.ones(size))
+        self.eps = eps
+        self.dim = dim
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        norm_x = x.to(torch.float32).pow(2).mean(dim=self.dim, keepdim=True)
+        x_normed = x * torch.rsqrt(norm_x + self.eps)
+        return (self.scale * x_normed).type_as(x)
+
+
+class RotaryEmbedding(nn.Module):
+    """Rotary Positional Embedding for injecting positional information."""
+
+    def __init__(self, dim):
+        super().__init__()
+        inv_freq = 1.0 / (10000 ** (torch.arange(0, dim, 2).float() / dim))
+        self.register_buffer("inv_freq", inv_freq)
+
+    def forward(self, seq_len):
+        t = torch.arange(seq_len, device=self.inv_freq.device).type_as(self.inv_freq)
+        freqs = torch.einsum("i,j->ij", t, self.inv_freq)
+        return freqs  # Shape: (seq_len, dim // 2)
+
+
+class BinaryAttentionBias(nn.Module):
+    """Binary Variate Attention for time series data."""
+
+    def __init__(self,
+                 num_heads: Int):
+        super().__init__()
+        self.num_heads = num_heads
+        self.emd = nn.Embedding(2, num_heads)
+
+    def forward(self,
+                query_id: Int[torch.Tensor, "batch_size q_len"],
+                kv_id: Int[torch.Tensor, "batch_size kv_len"],
+                ) -> Float[torch.Tensor, "batch_size num_heads q_len kv_len"]:
+        ind = torch.eq(query_id.unsqueeze(-1), kv_id.unsqueeze(-2))
+        ind = ind.unsqueeze(1)  # (batch_size, 1, q_len, kv_len)
+        weight = rearrange(self.emd.weight, "two num_heads -> two num_heads 1 1")  # (2, num_heads, 1, 1)
+        bias = ~ind * weight[:1] + ind * weight[1:]  # (batch_size, num_heads, q_len, kv_len)
+        return bias
+
+
+class MultiheadAttentionWithRoPE(nn.Module):
+    """Multi-head Attention with Rotary Positional Encoding (RoPE), non-causal by default."""
+    "========== NOtice that this applies BinaryAttentionBias ==========="
+
+    def __init__(self, embed_dim, num_heads, num_features):
+        super().__init__()
+        self.embed_dim = embed_dim
+        self.num_heads = num_heads
+        self.head_dim = embed_dim // num_heads
+        self.num_features = num_features
+        assert self.head_dim * num_heads == embed_dim, "embed_dim must be divisible by num_heads"
+
+        # Linear projections for Q, K, V, and output
+        self.q_proj = nn.Linear(embed_dim, embed_dim, bias=False)
+        self.k_proj = nn.Linear(embed_dim, embed_dim, bias=False)
+        self.v_proj = nn.Linear(embed_dim, embed_dim, bias=False)
+        self.out_proj = nn.Linear(embed_dim, embed_dim, bias=False)
+
+        # Binary attention bias for time series
+        if num_features > 1:
+            self.binary_attention_bias = BinaryAttentionBias(num_heads)
+
+    def apply_rope(self, x, freqs):
+        """Apply Rotary Positional Encoding to the input tensor."""
+        B, seq_len, embed_dim = x.shape
+        assert embed_dim == self.embed_dim, "Embedding dimension mismatch"
+        assert freqs.shape == (seq_len, embed_dim // 2), "freqs shape mismatch"
+
+        # Reshape for rotation: split embed_dim into pairs
+        x_ = x.view(B, seq_len, embed_dim // 2, 2)
+        cos = freqs.cos().unsqueeze(0)  # (1, seq_len, embed_dim // 2, 1)
+        sin = freqs.sin().unsqueeze(0)  # (1, seq_len, embed_dim // 2, 1)
+
+        # Apply rotation to each pair
+        x_rot = torch.stack(
+            [
+                x_[..., 0] * cos - x_[..., 1] * sin,
+                x_[..., 0] * sin + x_[..., 1] * cos,
+            ],
+            dim=-1
+        )
+        return x_rot.view(B, seq_len, embed_dim)
+
+    def forward(self, query, key, value, freqs, query_id=None, kv_id=None, attn_mask=None):
+        """
+        Forward pass for multi-head attention with RoPE.
+
+        Args:
+            query (Tensor): Shape (B, T, C)
+            key (Tensor): Shape (B, T, C)
+            value (Tensor): Shape (B, T, C)
+            freqs (Tensor): RoPE frequencies, shape (T, embed_dim // 2)
+            query_id (Tensor, optional): Shape (B, q_len), feature IDs for query
+            kv_id (Tensor, optional): Shape (B, kv_len), feature IDs for key/value
+            attn_mask (Tensor, optional): Shape (B, T), True for valid positions, False for padding.
+
+        Returns:
+            Tensor: Attention output, shape (B, T, C)
+        """
+        B, T, C = query.shape
+        assert key.shape == (B, T, C) and value.shape == (B, T, C), "query, key, value shapes must match"
+
+        # Project inputs to Q, K, V
+        Q = self.q_proj(query)
+        K = self.k_proj(key)
+        V = self.v_proj(value)
+
+        # Apply RoPE to Q and K
+        Q_rot = self.apply_rope(Q, freqs)
+        K_rot = self.apply_rope(K, freqs)
+
+        # Reshape for multi-head attention
+        Q_rot = Q_rot.view(B, T, self.num_heads, self.head_dim).transpose(1, 2)  # (B, nh, T, hs)
+        K_rot = K_rot.view(B, T, self.num_heads, self.head_dim).transpose(1, 2)  # (B, nh, T, hs)
+        V = V.view(B, T, self.num_heads, self.head_dim).transpose(1, 2)  # (B, nh, T, hs)
+
+        # Prepare attention mask for padding
+        if attn_mask is not None:
+            attn_mask = attn_mask.unsqueeze(1).unsqueeze(2)  # (B, 1, 1, T)
+        else:
+            attn_mask = None
+
+        if query_id is not None and kv_id is not None:
+            # Add binary attention bias
+            attn_bias = self.binary_attention_bias(query_id, kv_id)  # (B, num_heads, q_len, kv_len)
+            scores = torch.matmul(Q_rot, K_rot.transpose(-2, -1)) / math.sqrt(
+                self.head_dim)  # (B, num_heads, q_len, kv_len)
+            scores += attn_bias
+            if attn_mask is not None:
+                scores = scores.masked_fill(~attn_mask, float('-inf'))
+            attn_weights = F.softmax(scores, dim=-1)  # (B, num_heads, q_len, kv_len)
+            y = torch.matmul(attn_weights, V)  # (B, num_heads, q_len, hs)
+
+        else:
+            # Compute scaled dot-product attention (non-causal) without binary bias
+            # for param in self.binary_attention_bias.parameters():
+            #     param.requires_grad = False
+            y = F.scaled_dot_product_attention(
+                Q_rot, K_rot, V,
+                attn_mask=attn_mask,
+                is_causal=False  # Non-causal attention for encoder
+            )  # (B, nh, T, hs)
+
+        # Reshape and project output
+        y = y.transpose(1, 2).contiguous().view(B, T, C)
+        y = self.out_proj(y)
+        return y
+
+
+class LlamaMLP(nn.Module):
+    def __init__(self, d_model, dim_feedforward=2048):
+        super().__init__()
+        self.hidden_size = d_model
+        self.intermediate_size = dim_feedforward
+        self.gate_proj = nn.Linear(self.hidden_size, self.intermediate_size, bias=True)
+        self.up_proj = nn.Linear(self.hidden_size, self.intermediate_size, bias=True)
+        self.down_proj = nn.Linear(self.intermediate_size, self.hidden_size, bias=True)
+        self.act_fn = F.gelu
+
+    def forward(self, x):
+        down_proj = self.down_proj(self.act_fn(self.gate_proj(x)) * self.up_proj(x))
+        return down_proj
+
+
+class TransformerEncoderLayerWithRoPE(nn.Module):
+    """Transformer Encoder Layer with RoPE and RMSNorm."""
+
+    def __init__(self, d_model, nhead, dim_feedforward=2048, dropout=0.1, activation="relu", num_features=1):
+        super().__init__()
+        self.self_attn = MultiheadAttentionWithRoPE(d_model, nhead, num_features)
+        self.dropout = nn.Dropout(dropout)
+        self.input_norm = RMSNorm(d_model)
+        self.output_norm = RMSNorm(d_model)
+        self.mlp = LlamaMLP(d_model, dim_feedforward)
+        self.dropout1 = nn.Dropout(dropout)
+        self.dropout2 = nn.Dropout(dropout)
+        self.activation = F.relu if activation == "relu" else F.gelu
+
+    def forward(self, src, freqs, src_id=None, attn_mask=None):
+        residual = src
+        src = self.input_norm(src)
+        src = self.self_attn(src, src, src, freqs, src_id, src_id, attn_mask=attn_mask)
+        src = src + residual
+        residual = src
+        src = self.output_norm(src)
+        src = self.mlp(src)
+        src = residual + self.dropout2(src)
+        return src
+
+
+class CustomTransformerEncoder(nn.Module):
+    """Stack of Transformer Encoder Layers."""
+
+    def __init__(self, d_model, nhead, dim_feedforward, dropout, activation, num_layers, num_features):
+        super().__init__()
+        self.layers = nn.ModuleList([
+            TransformerEncoderLayerWithRoPE(
+                d_model=d_model,
+                nhead=nhead,
+                dim_feedforward=dim_feedforward,
+                dropout=dropout,
+                activation=activation,
+                num_features=num_features
+            ) for _ in range(num_layers)
+        ])
+
+    def forward(self, src, freqs, src_id=None, attn_mask=None):
+        output = src
+        for layer in self.layers:
+            output = layer(output, freqs, src_id, attn_mask=attn_mask)
+        return output
+
+
+class TimeSeriesEncoder(nn.Module):
+    """
+    Time Series Encoder with PatchTST-like patching, RoPE.
+
+    Args:
+        d_model (int): Model dimension
+        d_proj (int): Projection dimension
+        patch_size (int): Size of each patch
+        num_layers (int): Number of encoder layers
+        num_heads (int): Number of attention heads
+        d_ff_dropout (float): Dropout rate
+        max_total_tokens (int): Maximum sequence length
+        use_rope (bool): Use RoPE if True
+        num_features (int): Number of features in the time series
+        activation (str): "relu" or "gelu"
+
+    Inputs:
+        time_series (Tensor): Shape (batch_size, seq_len, num_features)
+        mask (Tensor): Shape (batch_size, seq_len)
+
+    Outputs:
+        local_embeddings (Tensor): Shape (batch_size, seq_len, num_features, d_proj)
+    """
+
+    def __init__(self, d_model=2048, d_proj=512, patch_size=32, num_layers=6, num_heads=8,
+                 d_ff_dropout=0.1, max_total_tokens=8192, use_rope=True, num_features=1,
+                 activation="relu"):
+        super().__init__()
+        self.patch_size = patch_size
+        self.d_model = d_model
+        self.d_proj = d_proj
+        self.num_layers = num_layers
+        self.num_heads = num_heads
+        self.d_ff_dropout = d_ff_dropout
+        self.max_total_tokens = max_total_tokens
+        self.use_rope = use_rope
+        self.num_features = num_features
+        self.activation = activation
+
+        # Patch embedding layer
+        self.embedding_layer = nn.Linear(patch_size, d_model)
+
+        if use_rope:
+            # Initialize RoPE and custom encoder
+            self.rope_embedder = RotaryEmbedding(d_model)
+            self.transformer_encoder = CustomTransformerEncoder(
+                d_model=d_model,
+                nhead=num_heads,
+                dim_feedforward=d_model * 4,
+                dropout=d_ff_dropout,
+                activation=activation,
+                num_layers=num_layers,
+                num_features=num_features
+            )
+        else:
+            # Standard encoder without RoPE
+            encoder_layer = nn.TransformerEncoderLayer(
+                d_model=d_model,
+                nhead=num_heads,
+                dim_feedforward=d_model * 4,
+                dropout=d_ff_dropout,
+                batch_first=True,
+                activation=activation
+            )
+            self.transformer_encoder = nn.TransformerEncoder(encoder_layer, num_layers)
+
+        # Output projection layers
+        self.projection_layer = nn.Linear(d_model, patch_size * d_proj)
+        self._init_parameters()
+
+    def _init_parameters(self):
+        for name, param in self.named_parameters():
+            if 'weight' in name and 'linear' in name:
+                if self.activation == "relu":
+                    nn.init.kaiming_uniform_(param, nonlinearity='relu')
+                elif self.activation == "gelu":
+                    nn.init.kaiming_uniform_(param, nonlinearity='gelu')
+            elif 'bias' in name:
+                nn.init.constant_(param, 0.0)
+
+    def forward(self, time_series, mask):
+        """Forward pass to generate local embeddings."""
+        if time_series.dim() == 2:
+            time_series = time_series.unsqueeze(-1)
+        device = time_series.device
+        B, seq_len, num_features = time_series.size()
+        assert num_features == self.num_features, f"Number of features mismatch with data: {num_features} vs param: {self.num_features}"
+        assert mask.size() == (B, seq_len), "Mask shape mismatch"
+
+        # Pad sequence to be divisible by patch_size
+        padded_length = math.ceil(seq_len / self.patch_size) * self.patch_size
+        if padded_length > seq_len:
+            pad_amount = padded_length - seq_len
+            time_series = F.pad(time_series, (0, 0, 0, pad_amount), value=0)
+            mask = F.pad(mask, (0, pad_amount), value=0)
+
+        # Convert to patches
+        num_patches = padded_length // self.patch_size
+        total_length = num_patches * num_features
+        patches = time_series.view(B, num_patches, self.patch_size, num_features)
+        patches = patches.permute(0, 3, 1, 2).contiguous()  # (B, num_features, num_patches, patch_size)
+        patches = patches.view(B, num_features * num_patches, self.patch_size)  # (B, L, patch_size)
+        # Create feature IDs for patches
+        feature_id = torch.arange(num_features, device=device).repeat_interleave(
+            num_patches)  # (num_features * num_patches = L,)
+        feature_id = feature_id.unsqueeze(0).expand(B, -1)  # (B, L)
+
+        # Embed patches
+        embedded_patches = self.embedding_layer(patches)  # (B, L, d_model)
+
+        # Create patch-level mask
+        mask = mask.view(B, num_patches, self.patch_size)
+        patch_mask = mask.sum(dim=-1) > 0  # (B, num_patches)
+        full_mask = patch_mask.unsqueeze(1).expand(-1, num_features, -1)  # (B, num_features, num_patches)
+        full_mask = full_mask.reshape(B, num_features * num_patches)  # (B, L)
+
+        # Generate RoPE frequencies if applicable
+        if self.use_rope:
+            freqs = self.rope_embedder(total_length).to(device)
+        else:
+            freqs = None
+
+        # Encode sequence
+        if num_features > 1:
+            output = self.transformer_encoder(
+                embedded_patches,
+                freqs=freqs,
+                src_id=feature_id,
+                attn_mask=full_mask
+            )
+        else:
+            output = self.transformer_encoder(
+                embedded_patches,
+                freqs=freqs,
+                attn_mask=full_mask
+            )
+
+        # Extract and project local embeddings
+        patch_embeddings = output  # (B, L, d_model)
+        patch_proj = self.projection_layer(patch_embeddings)  # (B, L, patch_size * d_proj)
+        local_embeddings = patch_proj.view(B, num_features, num_patches, self.patch_size, self.d_proj)
+        local_embeddings = local_embeddings.permute(0, 2, 3, 1, 4)  # (B, num_patches, patch_size, num_features, d_proj)
+        local_embeddings = local_embeddings.view(B, -1, num_features, self.d_proj)[:, :seq_len, :,
+                           :]  # (B, seq_len, num_features, d_proj)
+
+        return local_embeddings

time_rcd/_inference.py

@@ -0,0 +1,117 @@
+"""Minimal inference backend packaged with the public Time-RCD API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch.utils.data import DataLoader, Dataset
+
+from ._core.TimeRCD_pretrain_multi import TimeSeriesPretrainModel
+from ._core.time_rcd_config import TimeRCDConfig
+
+
+class _WindowDataset(Dataset):
+    """Split a normalized time series into non-overlapping padded windows."""
+
+    def __init__(self, data: np.ndarray, window_size: int) -> None:
+        mean = np.mean(data, axis=0)
+        std = np.where(np.std(data, axis=0) == 0, 1e-8, np.std(data, axis=0))
+        normalized = (data - mean) / std
+
+        padding = (-len(normalized)) % window_size
+        if padding:
+            normalized = np.vstack(
+                [normalized, np.repeat(normalized[-1:, :], padding, axis=0)]
+            )
+        self.data = normalized
+        self.window_size = window_size
+        self.original_length = len(data)
+
+    def __len__(self) -> int:
+        return len(self.data) // self.window_size
+
+    def __getitem__(self, index: int) -> Tuple[torch.Tensor, torch.Tensor]:
+        start = index * self.window_size
+        end = start + self.window_size
+        valid_length = min(self.window_size, self.original_length - start)
+        mask = torch.zeros(self.window_size, dtype=torch.bool)
+        mask[:valid_length] = True
+        return (
+            torch.tensor(self.data[start:end], dtype=torch.float32),
+            mask,
+        )
+
+
+def _collate_windows(
+    batch: list[Tuple[torch.Tensor, torch.Tensor]],
+) -> dict[str, torch.Tensor]:
+    time_series, attention_mask = zip(*batch)
+    return {
+        "time_series": torch.stack(time_series),
+        "attention_mask": torch.stack(attention_mask),
+    }
+
+
+class TimeRCDPretrainTester:
+    """Inference-only wrapper for a pretrained Time-RCD checkpoint."""
+
+    def __init__(self, checkpoint_path: str, config: TimeRCDConfig) -> None:
+        self.config = config
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self.win_size = config.win_size
+        self.batch_size = config.batch_size
+        self.model = TimeSeriesPretrainModel(config).to(self.device)
+        self.load_checkpoint(checkpoint_path)
+        self.model.eval()
+
+    def load_checkpoint(self, checkpoint_path: str) -> None:
+        path = Path(checkpoint_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"Checkpoint not found: {path}")
+
+        try:
+            checkpoint = torch.load(
+                path, map_location=self.device, weights_only=True
+            )
+        except TypeError:
+            checkpoint = torch.load(path, map_location=self.device)
+        state_dict = checkpoint.get("model_state_dict", checkpoint)
+        state_dict = {
+            key.removeprefix("module."): value for key, value in state_dict.items()
+        }
+        self.model.load_state_dict(state_dict)
+
+    def zero_shot(
+        self, data: np.ndarray
+    ) -> tuple[list[np.ndarray], list[np.ndarray]]:
+        window_size = min(len(data), self.win_size)
+        dataset = _WindowDataset(data, window_size)
+        loader = DataLoader(
+            dataset,
+            batch_size=self.batch_size,
+            collate_fn=_collate_windows,
+            num_workers=0,
+            shuffle=False,
+        )
+
+        scores: list[np.ndarray] = []
+        logits: list[np.ndarray] = []
+        with torch.no_grad():
+            for batch in loader:
+                time_series = batch["time_series"].to(self.device)
+                attention_mask = batch["attention_mask"].to(self.device)
+                local_embeddings = self.model(
+                    time_series=time_series, mask=attention_mask
+                )
+                anomaly_logits = self.model.anomaly_head(local_embeddings)
+                anomaly_logits = torch.mean(anomaly_logits, dim=-2)
+                anomaly_probs = F.softmax(anomaly_logits, dim=-1)[..., 1]
+                scores.append(anomaly_probs.cpu().numpy())
+                logits.append(
+                    (anomaly_logits[..., 1] - anomaly_logits[..., 0]).cpu().numpy()
+                )
+        return scores, logits

time_rcd/detector.py

@@ -0,0 +1,172 @@
+"""User-facing zero-shot inference API for Time-RCD."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Literal, Optional, Tuple, Union
+
+import numpy as np
+
+HF_REPO_ID = "thu-sail-lab/Time-RCD"
+CHECKPOINT_FILES = {
+    "uni": "best_model/pretrain_checkpoint_best_uni.pth",
+    "multi": "best_model/pretrain_checkpoint_best_multi.pth",
+}
+DEFAULT_WIN_SIZE = 5000
+DEFAULT_BATCH_SIZE = {"uni": 64, "multi": 1}
+
+
+class TimeRCDDetector:
+    """Zero-shot time series anomaly detector powered by Time-RCD.
+
+    Parameters
+    ----------
+    checkpoint_path:
+        Path to a local ``.pth`` checkpoint.
+    variant:
+        ``"uni"`` for univariate series, ``"multi"`` for multivariate series.
+    win_size:
+        Sliding window length. Sequences shorter than this value use the full
+        sequence length instead.
+    batch_size:
+        Inference batch size. Defaults to 64 (uni) or 1 (multi).
+    device:
+        PyTorch device string, e.g. ``"cuda"`` or ``"cpu"``. Auto-detected when
+        omitted.
+
+    Notes
+    -----
+    The model is initialized on the first call to :meth:`predict`, when the
+    number of input features is known.
+    """
+
+    def __init__(
+        self,
+        checkpoint_path: str,
+        variant: Literal["uni", "multi"] = "uni",
+        win_size: int = DEFAULT_WIN_SIZE,
+        batch_size: Optional[int] = None,
+        device: Optional[str] = None,
+    ) -> None:
+        if variant not in CHECKPOINT_FILES:
+            raise ValueError(f"variant must be one of {list(CHECKPOINT_FILES)}, got {variant!r}")
+
+        self.variant = variant
+        self.win_size = win_size
+        self.batch_size = batch_size if batch_size is not None else DEFAULT_BATCH_SIZE[variant]
+        self.checkpoint_path = str(checkpoint_path)
+        self.device = device
+        self._tester = None
+        self._num_features: Optional[int] = None
+
+    def _ensure_tester(self, num_features: int) -> None:
+        """Initialize a model compatible with ``num_features`` when needed."""
+        if self._tester is not None and self._num_features == num_features:
+            return
+
+        from ._core.time_rcd_config import default_config
+        from ._inference import TimeRCDPretrainTester
+
+        # ``default_config`` is a module-level template. Each detector must own
+        # its configuration so its runtime options cannot affect other instances.
+        config = deepcopy(default_config)
+        config.ts_config.patch_size = 16
+        config.win_size = self.win_size
+        config.batch_size = self.batch_size
+        config.ts_config.num_features = num_features
+
+        self._tester = TimeRCDPretrainTester(self.checkpoint_path, config)
+        self._num_features = num_features
+        if self.device is not None:
+            import torch
+
+            self._tester.device = torch.device(self.device)
+            self._tester.model.to(self._tester.device)
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        repo_id: str = HF_REPO_ID,
+        variant: Literal["uni", "multi"] = "uni",
+        cache_dir: Optional[str] = None,
+        local_files_only: bool = False,
+        **kwargs,
+    ) -> "TimeRCDDetector":
+        """Load a checkpoint from Hugging Face Hub (cached locally after first use)."""
+        from huggingface_hub import hf_hub_download
+
+        checkpoint_path = hf_hub_download(
+            repo_id=repo_id,
+            filename=CHECKPOINT_FILES[variant],
+            cache_dir=cache_dir,
+            local_files_only=local_files_only,
+        )
+        return cls(checkpoint_path=checkpoint_path, variant=variant, **kwargs)
+
+    @classmethod
+    def from_local(
+        cls,
+        checkpoint_path: Union[str, Path],
+        variant: Literal["uni", "multi"] = "uni",
+        **kwargs,
+    ) -> "TimeRCDDetector":
+        """Load a checkpoint from a local path."""
+        path = Path(checkpoint_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"Checkpoint not found: {path}")
+        return cls(checkpoint_path=str(path), variant=variant, **kwargs)
+
+    def predict(
+        self,
+        data: Union[np.ndarray, list],
+        return_logits: bool = False,
+    ) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+        """Run zero-shot anomaly scoring on a single time series.
+
+        Parameters
+        ----------
+        data:
+            Array of shape ``(T,)`` or ``(T, C)`` where ``T`` is time steps and
+            ``C`` is the number of channels.
+        return_logits:
+            When ``True``, also return raw anomaly logits.
+
+        Returns
+        -------
+        scores:
+            Anomaly scores in ``[0, 1]``, one value per time step.
+        logits:
+            Returned only when ``return_logits=True``.
+        """
+        data = np.asarray(data, dtype=np.float64)
+        if data.ndim == 1:
+            data = data.reshape(-1, 1)
+        elif data.ndim != 2:
+            raise ValueError(f"data must be 1D or 2D, got shape {data.shape}")
+
+        if self.variant == "uni" and data.shape[1] != 1:
+            raise ValueError(
+                "variant='uni' expects a univariate series with shape (T,) or (T, 1). "
+                f"Got {data.shape[1]} channels; use variant='multi' instead."
+            )
+        if self.variant == "multi" and data.shape[1] < 2:
+            raise ValueError(
+                "variant='multi' expects at least two channels with shape (T, C), where C > 1. "
+                "Use variant='uni' for a univariate series."
+            )
+
+        original_length = data.shape[0]
+        self._ensure_tester(data.shape[1])
+        assert self._tester is not None
+
+        score_chunks, logit_chunks = self._tester.zero_shot(data)
+        scores = np.concatenate([np.asarray(chunk).reshape(-1) for chunk in score_chunks], axis=0)
+        logits = np.concatenate([np.asarray(chunk).reshape(-1) for chunk in logit_chunks], axis=0)
+
+        scores = scores[:original_length]
+        logits = logits[:original_length]
+
+        if return_logits:
+            return scores, logits
+        return scores