Metadata-Version: 2.4
Name: chronocratic-models
Version: 0.1.0a1
Summary: Ready-to-use time series models implemented in PyTorch and Lightning.
Author-email: The Chronocratic Developers <github@users.noreply.github.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/chronocratic/chronocratic-models
Project-URL: Documentation, https://chronocratic-models.readthedocs.io/
Project-URL: Repository, https://github.com/chronocratic/chronocratic-models
Project-URL: Issues, https://github.com/chronocratic/chronocratic-models/issues
Keywords: time-series,pytorch,lightning,machine-learning,self-supervised-learning,representation-learning,forecasting,classification,regression,anomaly-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0.0,>=2.1
Requires-Dist: scipy>=1.13.0
Requires-Dist: lightning<3.0,>=2.5
Requires-Dist: torch<3.0,>=2.4
Requires-Dist: einops>=0.8.2
Requires-Dist: numba>=0.65.1
Requires-Dist: tqdm>=4.66.0
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Dynamic: license-file

# chronocratic-models

[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/chronocratic-models.svg)](https://pypi.org/project/chronocratic-models/)
[![Python versions](https://img.shields.io/pypi/pyversions/chronocratic-models.svg)](https://pypi.org/project/chronocratic-models/)
[![Build Status](https://github.com/chronocratic/chronocratic-models/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/chronocratic/chronocratic-models/actions)
[![Documentation Status](https://readthedocs.org/projects/chronocratic-models/badge/?version=latest)](https://chronocratic-models.readthedocs.io/en/latest/?badge=latest)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![GitHub stars](https://img.shields.io/github/stars/chronocratic/chronocratic-models)](https://github.com/chronocratic/chronocratic-models/stargazers)

Self-supervised time-series representation learning models built with PyTorch and Lightning.

> **Note:** The PyPI package name uses a hyphen (`chronocratic-models`), but the import uses the `chronocratic.models` namespace.

## Installation

```bash
pip install chronocratic-models
```

## Quick Start

```python
import torch
from chronocratic.models import TS2Vec, TS2VecModelParameters

# Create model with default parameters
model = TS2Vec(TS2VecModelParameters(input_dim=1))
model.eval()

# Encode a synthetic time series (batch, channels, seq_len)
synthetic_data = torch.randn(1, 1, 100)

# Get multi-scale representations
with torch.no_grad():
    representations = model.encode(synthetic_data)
    print(representations.shape)  # (1, channels, hidden_dim)
```

## Models

### Convolutional (Dilated)

| Model | Description |
|-------|-------------|
| **TS2Vec** | Multi-scale hierarchical representation learning via dilated convolutions with hierarchical clustering. Code source: [zhihanyue/ts2vec](https://github.com/zhihanyue/ts2vec) |
| **CoST** | Decomposition-based contrastive self-supervised learning with trend-seasonal decomposition and contrastive objectives. Code source: [salesforce/CoST](https://github.com/salesforce/CoST) |
| **AutoTCL** | Automatic temporal contrastive learning with a trainable augmentation module for self-supervised time-series encoding. Code source: [AslanDing/AutoTCL](https://github.com/AslanDing/AutoTCL) |

### Convolutional (Standard)

| Model | Description |
|-------|-------------|
| **Series2Vec** | Self-supervised pretraining via contrastive learning on augmented time-series segments. |
| **TSTCC** | Temporal and contextual contrastive pretraining for time-series representation learning. |
| **FCN** | Fully convolutional encoder designed for Mixup Contrastive Learning (MCL) objectives. |

### Transformer

| Model | Description |
|-------|-------------|
| **TST** | Time Series Transformer with masked-reconstruction-based self-supervised pretraining. |

### Recurrent

| Model | Description |
|-------|-------------|
| **TimeNet** | Recurrent encoder-decoder architecture for time-series representation learning. |

### Generative

| Model | Description |
|-------|-------------|
| **TimeVAE** | Variational autoencoder for time-series data with latent representation encoding and generation. |

## Features

- **Polymorphic augmentation producer contract** — models accept any augmentation through a unified interface, eliminating enum-based branching.
- **Lightning integration** — all models are built on PyTorch Lightning for clean training loops and extensibility.
- **Self-supervised representation learning** — pre-trained encoders ready for downstream tasks without labeled data.
- **Pre-configured model parameters** — each model ships with tested default configuration dataclasses.
- **NumPy and PyTorch tensor support** — flexible input handling for both frameworks.

## Documentation

For full API reference, guides, and examples, visit [chronocratic-models.readthedocs.io](https://chronocratic-models.readthedocs.io/).

## License

This project is licensed under the BSD 3-Clause License — see the [LICENSE](LICENSE) file for details.
