Metadata-Version: 2.4
Name: tsicl
Version: 0.2.0
Summary: TS-ICL: A Flexible Time-Index Foundation Model for Time Series via In-Context Learning
Project-URL: Repository, https://github.com/EDF-Lab/ts-icl
Project-URL: Documentation, https://edf-lab.github.io/ts-icl/
Author: Etienne Le Naour, Tahar Nabil, Adrien Petralia
License: TS-ICL NON-COMMERCIAL LICENSE v1.0
        EDF SA
        Version: 1.0  |  Last Revised: June 9, 2026
        
        EDF SA ("we" or "our" or "Company") makes available the weights, parameters and inference code for the TS-ICL Model (as defined below) freely available for your non-commercial and non-production use as set forth in this TS-ICL Non-Commercial License ("License"). The "TS-ICL Model" means the TS-ICL AI models and models denoted as TS-ICL and their elements, which include algorithms, software, checkpoints, parameters, source code (inference code, evaluation code, and if applicable, fine-tuning code) and any other materials associated with the TS-ICL AI models made available by Company under this License, including, if any, the technical documentation, manuals and instructions for the use and operation thereof (collectively, "TS-ICL Model").
        
        By downloading, accessing, using, Distributing (as defined below), or creating a Derivative (as defined below) of the TS-ICL Model, you agree to the terms of this License. If you do not agree to this License, then you do not have any rights to access, use, Distribute or create a Derivative of the TS-ICL Model and you must immediately cease using the TS-ICL Model. If you are agreeing to be bound by the terms of this License on behalf of your employer or other entity, you represent and warrant to us that you have full legal authority to bind your employer or such entity to this License. If you do not have the requisite authority, you may not accept the License or access the TS-ICL Model on behalf of your employer or other entity.
        
        
        1. Definitions
        
        a. "Derivative" means any (i) modified version of the TS-ICL Model (including but not limited to any customized, fine-tuned, retrained, or otherwise adapted version thereof), (ii) work based on the TS-ICL Model, or (iii) any other derivative work thereof. For the avoidance of doubt, Outputs are not considered Derivatives under this License.
        
        b. "Distribution," "Distribute," or "Distributing" means providing or making available, by any means, a copy of the TS-ICL Model and/or the Derivatives as the case may be.
        
        c. "Non-Commercial Purpose" means use for testing, evaluation, or research not tied to commercial gain, production deployment, or revenue generation. This includes internal benchmarking, academic research, and experimentation on private or public datasets as well as Data Science Competitions as defined below, provided the results are not used in commercial decision-making, client deliverables, or paid products/services. For clarity, use (a) for any revenue-generating activity, (b) in direct or indirect interactions with end users or production systems, or (c) to train, fine-tune, or distill other models for commercial use, in each case is not a Non-Commercial Purpose. A Data Science Competition in the meaning of this Agreement is a publicly accessible contest hosted on established platforms (such as Kaggle, DrivenData, or ChallengeData) or by academic/non-profit institutions where participants compete to develop predictive models for specified datasets.
        
        d. "Outputs" means predictions, scores, probabilities, recommendations, explanations, or other results generated by operation of the TS-ICL Model or any Derivative from datasets or other inputs supplied by a user. For the avoidance of doubt, Outputs do not include any components of the TS-ICL Model, such as any fine-tuned versions of the TS-ICL Model, the weights, or parameters.
        
        e. "you" or "your" means the individual or entity entering into this License with Company.
        
        
        2. License Grant
        
        a. License. Subject to your compliance with this License, Company grants you a non-exclusive, worldwide, non-transferable, non-sublicensable, revocable, royalty-free and limited license to access, use, create Derivatives of, and Distribute the TS-ICL Model and Derivatives solely for your Non-Commercial Purposes. The foregoing license is personal to you, and you may not assign or sublicense this License or any other rights or obligations under this License without Company's prior written consent; any such assignment or sublicense will be void and will automatically and immediately terminate this License. Any restrictions set forth herein regarding the TS-ICL Model also apply to any Derivative you create or that are created on your behalf.
        
        b. Non-Commercial Use Only. You may only access, use, Distribute, or create Derivatives of the TS-ICL Model or Derivatives for Non-Commercial Purposes. If you wish to use the TS-ICL Model or a Derivative for any purpose not expressly authorized under this License, including any commercial or production activity, you must obtain a commercial license from Company, which Company may grant in its sole discretion and which additional use may be subject to a fee, royalty or other revenue share. Please contact tsicl-contact@edf.fr to request a commercial license.
        
        c. Reserved Rights. The rights expressly set forth in this License constitute the complete grant of rights to you in the TS-ICL Model; no other licenses are granted, whether by waiver, estoppel, implication, equity or otherwise. Company and its licensors reserve all rights not expressly granted by this License.
        
        d. Outputs. Company claims no ownership rights in and to the Outputs. You are solely responsible for the Outputs you generate and their subsequent uses in accordance with this License. Outputs may be used only for Non-Commercial Purposes. Any use of Outputs in production systems, business processes, commercial research services, client deliverables, or revenue-generating activities requires a separate commercial license. You may not use Outputs to train, fine-tune, or distill a model that is competitive with the TS-ICL Model.
        
        e. Compliance and Safeguards. You must ensure that any use of the TS-ICL Model, Derivatives, and Outputs complies with applicable data protection, privacy, export control, and AI regulations (including, where applicable, GDPR and the EU Artificial Intelligence Act), and that you implement reasonable technical and organizational measures appropriate to the data and risks involved.
        
        
        3. Distribution
        
        Subject to this License, you may Distribute copies of the TS-ICL Model and/or Derivatives made by you, under the following conditions:
        
        a. You must make available a copy of this License to third-party recipients of the TS-ICL Model and/or Derivatives you Distribute, and specify that any rights to use the TS-ICL Model and/or Derivatives shall be directly granted by Company to said third-party recipients pursuant to this License.
        
        b. You must prominently display the following notice alongside the Distribution of the TS-ICL Model or Derivative (such as via a "NOTICE" text file distributed as part of such TS-ICL Model or Derivative) (the "Attribution Notice"):
        
            The TS-ICL Model is licensed by EDF SA under the TS-ICL Non-Commercial License.
            Copyright © EDF SA 2026.
            THE MODEL IS PROVIDED FREE OF CHARGE: EDF SA SHALL NOT BE LIABLE FOR DAMAGES ARISING FROM ORDINARY NEGLIGENCE. LIABILITY FOR GROSS NEGLIGENCE AND INTENTIONAL MISCONDUCT REMAINS UNAFFECTED.
        
        c. In the case of Distribution of Derivatives made by you: (i) you must also include in the Attribution Notice a statement that you have modified the applicable TS-ICL Model; (ii) any terms and conditions you impose on any third-party recipients relating to Derivatives made by or for you shall neither limit such third-party recipients' use of the TS-ICL Model or any Derivatives made by or for Company in accordance with this License nor conflict with any of its terms and conditions and must include disclaimer of warranties and limitation of liability provisions that are at least as protective of Company as those set forth herein; and (iii) you must not misrepresent or imply, through any means, that the Derivatives made by or for you and/or any modified version of the TS-ICL Model you Distribute under your name and responsibility is an official product of Company or has been endorsed, approved or validated by Company, unless you are authorized by Company to do so in writing.
        
        d. No Hosted Service. You may not Distribute, host, or make available the TS-ICL Model or any Derivative as part of a hosted, managed, API, or SaaS service (whether paid or free) without a separate commercial license from Company.
        
        
        4. Restrictions
        
        You will not, and will not permit, assist or cause any third party to:
        
        a. use, modify, copy, reproduce, create Derivatives of, or Distribute the TS-ICL Model (or any Derivative thereof, or any data produced by the TS-ICL Model), in whole or in part, (i) for any commercial or production purposes, (ii) military purposes, (iii) purposes of surveillance, including any research or development relating to surveillance, (iv) biometric processing, (v) in any manner that infringes, misappropriates, or otherwise violates (or is likely to infringe, misappropriate, or otherwise violate) any third party's legal rights (including privacy, data protection, or publicity rights), (vi) in any unlawful, fraudulent, defamatory, or abusive activity, or (vii) in any manner that violates applicable law (including the General Data Protection Regulation (Regulation (EU) 2016/679) and the EU Artificial Intelligence Act (Regulation (EU) 2024/1689), as well as all amendments and successor laws to any of the foregoing);
        
        b. alter or remove copyright and other proprietary notices which appear on or in any portion of the TS-ICL Model;
        
        c. utilize any equipment, device, software, or other means to circumvent or remove any security or protection used by Company in connection with the TS-ICL Model, or to circumvent or remove any usage restrictions, or to enable functionality disabled by the TS-ICL Model;
        
        d. offer or impose any terms on the TS-ICL Model that alter, restrict, or are inconsistent with the terms of this License;
        
        e. violate any applicable export control and trade sanctions laws ("Export Laws") in connection with your use or Distribution of any TS-ICL Model;
        
        f. directly or indirectly Distribute, export, or otherwise transfer the TS-ICL Model (i) to any individual, entity, or country prohibited by Export Laws; (ii) to anyone on government restricted parties lists; (iii) for any purpose prohibited by Export Laws, including nuclear, chemical or biological weapons, or missile technology applications; (iv) use or download the TS-ICL Model if you or they are (a) located in a comprehensively sanctioned jurisdiction, (b) currently listed on any restricted parties list, or (c) for any purpose prohibited by Export Laws; or (v) disguise your location through IP proxying or other methods.
        
        
        5. Limitation of Liability
        
        Because Company makes the TS-ICL Model available free of charge, Company's liability is limited to cases of willful misconduct or gross negligence. Liability for bodily injury, death, or harm to health remains unaffected by this limitation. Any further liability, in particular for ordinary negligence, is expressly excluded to the fullest extent permitted by applicable law.
        
        
        6. Indemnification
        
        You will indemnify, defend and hold harmless Company and its subsidiaries and affiliates (collectively, the "Company Parties") from and against any losses, liabilities, damages, fines, penalties, and expenses (including reasonable attorneys' fees) incurred by any Company Party in connection with any claim, demand, allegation, lawsuit, proceeding, or investigation (collectively, "Claims") arising out of or related to (a) your access to or use of the TS-ICL Model (including in connection with any Output, results or data generated from such access or use), including any High-Risk Use; (b) your violation of this License; or (c) your violation, misappropriation or infringement of any rights of another (including intellectual property or other proprietary rights and privacy rights). You will promptly notify the Company Parties of any such Claims, and cooperate with Company Parties in defending such Claims. You will also grant the Company Parties sole control of the defense or settlement, at Company's sole option, of any Claims. You are entitled to engage counsel of your choice at your own expense to conduct the defense. You may not make any admissions or enter into settlements without the prior written consent of the Company Parties. This indemnity is in addition to, and not in lieu of, any other indemnities or remedies set forth in a written agreement between you and Company or the other Company Parties.
        
        
        7. Termination; Survival
        
        a. This License will automatically terminate upon any breach by you of the terms of this License.
        
        b. Company may terminate this License, in whole or in part, at any time upon notice (including electronic notice) to you.
        
        c. If you initiate any legal action or proceedings against Company or any other entity (including a cross-claim or counterclaim in a lawsuit), alleging that the TS-ICL Model or any Derivative, or any part thereof, infringes upon intellectual property or other rights owned or licensable by you, then any licenses granted to you under this License will immediately terminate as of the date such legal action or claim is filed or initiated.
        
        d. Upon termination of this License, you must cease all use, access or Distribution of the TS-ICL Model and any Derivatives and delete all copies in your possession or control, except as required by law or legitimate institutional archiving policies. The following sections survive termination of this License: 2(c), 2(d), 3–10.
        
        
        8. Third-Party Materials
        
        The TS-ICL Model may contain third-party software or other components (including free and open source software) (all of the foregoing, "Third-Party Materials"), which are subject to the license terms of the respective third-party licensors. Your dealings or correspondence with third parties and your use of or interaction with any Third-Party Materials are solely between you and the third party. Company does not control or endorse, and makes no representations or warranties regarding, any Third-Party Materials, and your access to and use of such Third-Party Materials are at your own risk.
        
        
        9. Trademarks
        
        You have not been granted any trademark license as part of this License and may not use any name, logo or trademark associated with Company without the prior written permission of Company, except to the extent necessary to make the reference required in the Attribution Notice as specified above or as is reasonably necessary in describing the TS-ICL Model and its creators.
        
        
        10. Governing Law; General
        
        This License shall be governed by and construed in accordance with the laws of France, without regard to its conflict of law provisions. Any dispute arising out of or in connection with this License shall be subject to the exclusive jurisdiction of the competent courts of Paris, France. If any provision or part of a provision of this License is unlawful, void or unenforceable, that provision or part of the provision is deemed severable from this License, and will not affect the validity and enforceability of any remaining provisions. The failure of Company to exercise or enforce any right or provision of this License will not operate as a waiver of such right or provision. This License does not confer any third-party beneficiary rights upon any other person or entity. This License, together with the documentation, constitutes the entire understanding between you and Company regarding the subject matter of this License, and supersedes all other written or oral agreements and understandings between you and Company regarding such subject matter.
        
        
        Commercial inquiries: tsicl-contact@edf.fr
        © 2026 EDF SA. All rights reserved.
License-File: LICENSE
Keywords: TS-ICL,foundation model,in-context learning,time series
Requires-Python: >=3.12
Requires-Dist: datasets<4.0
Requires-Dist: dotenv>=0.9.9
Requires-Dist: einops>=0.8.0
Requires-Dist: einx>=0.3.0
Requires-Dist: fev>=0.7.0
Requires-Dist: gluonts>=0.16.2
Requires-Dist: hydra-core>=1.3.2
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: numpy>=2.1.3
Requires-Dist: pandas>=2.2.3
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: torch<2.10,>=2.5.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.15.17; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: ipython>=9.14.1; extra == 'docs'
Requires-Dist: myst-nb>=1.4.0; extra == 'docs'
Requires-Dist: myst-parser>=5.1.0; extra == 'docs'
Requires-Dist: nbconvert>=7.17.1; extra == 'docs'
Requires-Dist: nbsphinx-link>=1.4.1; extra == 'docs'
Requires-Dist: nbsphinx>=0.9.8; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.18.0; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3.8.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
Requires-Dist: sphinx-design>=0.7.0; extra == 'docs'
Requires-Dist: sphinx-inline-tabs>=2025.12.21.14; extra == 'docs'
Requires-Dist: sphinx>=9.1.0; extra == 'docs'
Requires-Dist: sphinxcontrib-lightbox2>=0.6.0; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid>=2.0.2; extra == 'docs'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/logo-tsicl.jpeg" alt="TS-ICL architecture" width="30%" />
</div>

# TS-ICL: a Time-Indexed Foundation Model for Time Series Forecasting & Imputation via In-Context Learning


[![arXiv](https://img.shields.io/badge/arXiv-2606.05878-b31b1b.svg)](https://arxiv.org/abs/2606.05878)
[![PyPI](https://img.shields.io/pypi/v/tsicl.svg)](https://pypi.org/project/tsicl)
[![test](https://github.com/EDF-Lab/ts-icl/actions/workflows/tests.yml/badge.svg)](https://github.com/EDF-Lab/ts-icl/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-%3E%3D3.12-blue.svg)](https://www.python.org/)

**Paper:** [TS-ICL: A Flexible Time-Indexed Foundation Model for Time Series via In-Context Learning](https://arxiv.org/abs/2606.05878)

**TS-ICL** is a continuous probabilistic Time Series Foundation Model (TSFM) that unifies **forecasting** and **imputation** in a single zero-shot architecture, requiring no task-specific training or fine-tuning.

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/TS-ICL-v1.png" alt="TS-ICL architecture" width="80%" />
</div>

---

## Installation

```bash
pip install tsicl
```

Model checkpoint can be found on [TS-ICL's Huggingface repo](https://huggingface.co/taharnbl/TS-ICL).

**Requirements:** Python ≥ 3.12, PyTorch ≥ 2.5.1

---

## Quick Start

```python
from tsicl import TSICL

model = TSICL(model_path="checkpoints/tsicl-v1.ckpt")

# Forecasting — predict the next 96 timesteps
point, quantiles = model.forecast(
    inputs            = my_series,        # e.g. 1-D numpy array or tensor
    prediction_length = 96,
    quantile_levels   = [0.1, 0.5, 0.9],
    denormalize       = True
)

# Imputation — reconstruct NaN values
point, quantiles = model.impute(
    inputs          = my_series_with_nans,
    quantile_levels = [0.1, 0.5, 0.9],
    denormalize     = True
)
```

Both methods return a `(point_prediction, quantile_predictions)` tuple. **NaN values are handled natively** — no preprocessing required.

---

## Notebooks

Step-by-step tutorials on synthetic Gaussian Processes:

| Notebook | Description |
|---|---|
| [get_started_imputation.ipynb](notebooks/get_started_imputation.ipynb) | Pointwise & block missingness, covariate-aware imputation, output format, batch processing |
| [get_started_forecasting.ipynb](notebooks/get_started_forecasting.ipynb) | Univariate forecasting, partially observed look-back, covariate-aware forecasting, batch processing |

---

## Model

TS-ICL processes each time series through four successive modules:

1. **Time Series Encoder** — a Perceiver-like architecture that compresses observed (timestamp, value) pairs into M = 32 learnable latent tokens via cross-attention. Accepts inputs of **arbitrary length** without preprocessing.
2. **Channel Mixer** — aggregates information across channels via cross-attention. Selectively integrates covariate representations into the target's representation when covariates are provided.
3. **Temporal Context Query Module** — maps any query timestamp to a context-aware embedding using Fourier (NeRF-style) positional encoding. Enables prediction at arbitrary timestamps, including on **irregular grids**.
4. **In-Context Regressor** — a causal Transformer that reads observed (representation, value) pairs as in-context training examples and outputs **99 quantiles** at the queried timestamps.

A single checkpoint (`tsicl-v1.ckpt`) contains two specialised components — one trained with masking for imputation, one with causal masking for forecasting — sharing the same architecture backbone.

---

## Performance

### Forecasting — `fev-bench`

TS-ICL is highly competitive with the best forecasting foundation models, while being **fast** at inference. TS-ICL  **efficently leverages covariate** (when relevant) and is also **robust to sparse look-back windows**.

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/fevbench.png" alt="fev-bench results" width="80%" />
</div>

*Example — pointwise forecast with a known covariate (GFC17 dataset):*

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/forecast-GFC17-covar.png" alt="Forecast with covariate example" width="80%" />
</div>

### Forecasting — `TIME benchmark`

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/Time-Benchmark.png" alt="TIME benchmark results" width="60%" />
</div>

### Imputation — `fm-impute-bench`

TS-ICL achieves **state-of-the-art imputation** across 132 univariate and 24 covariate-aware tasks, outperforming the best tabular foundation model baseline while being **~50× faster** at inference.

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/fm-impute-bench.png" alt="fm-impute-bench results" width="80%" />
</div>

*Example — block imputation with uncertainty quantification (COVID-19 energy dataset):*

<div align="center">
  <img src="https://raw.githubusercontent.com/EDF-Lab/ts-icl/main/docs/contents/impute-covid19-energy.png" alt="Block imputation with uncertainty quantification example" width="80%" />
</div>

---

## Citation

If you use TS-ICL for research purposes, please consider citing the associated paper:

```bibtex
@article{lenaour2026tsicl,
  title={TS-ICL: A Flexible Time-Indexed Foundation Model for Time Series via In-Context Learning},
  author={Le Naour, Etienne and Nabil, Tahar and Petralia, Adrien},
  journal={arXiv preprint arXiv:2606.05878},
  year={2026}
}
```

---

## Contributors

- [Etienne Le Naour](https://github.com/EtienneLnr)
- [Tahar Nabil](https://github.com/TaharNbl)
- [Adrien Petralia](https://github.com/adrienpetralia)
- [Marc Héry](https://github.com/MarHery)

---

## License

TS-ICL weights and code are released under a non-commercial license, see [LICENSE](LICENSE).

## Contact

To learn more or request a commercial license, please contact us at:
tsicl-contact_at_edf.fr (replace `_at_` with @).