tsft 0.1.1
Time Series Forecasting Tool
Requires Python: >=3.12

# TSFT — Time Series Forecasting Tool

![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)
![Darts](https://img.shields.io/badge/Darts-Time%20Series%20Forecasting-1f77b4)
![Dash](https://img.shields.io/badge/Dash-Plotly-119DFF?logo=plotly&logoColor=white)

TSFT is a CLI utility for training deep learning forecasting models, generating exploratory reports, and visualizing results for time series data.

It is built on top of Darts + PyTorch Lightning and provides a simple command-line interface powered by Typer.

## Features

* Deep learning forecasting models (Darts-based)
* Interactive Dash dashboards
* Clean CLI interface

## Dataset Requirements

- Your dataset must have a column named `timestamp`, which will be used as the time index for the model.
- For multivariate time series, dashboards are not very informative for datasets with more than 20 dimensions.


## Installation

```bash
pip install tsft
```

Or install locally:

```bash
pip install -e .
```

## Usage

```bash
tsft [COMMAND] [OPTIONS]
```

Available commands:

* `report` — Launch exploratory dashboard for a dataset
* `run` — Train a forecasting model
* `summary` — Visualize training results


## Generate Dataset Report

Launch an interactive dashboard for time series exploration:

```bash
tsft report data.csv
```

Optional:

```bash
tsft report data.csv --port 9000
```


## Train a Model

Train a forecasting model on your dataset:

```bash
tsft run data.csv
```

With options:

```bash
tsft run data.csv \
  --model=nbeats \
  --input-chunk=24 \
  --output-chunk=12 \
  --epochs=5 \
  --no-stopper \
  --output=results/
```

### Options

| Option                     | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `--model`                  | Model name (`lstm`, `gru`, `rnn`, `nbeats`, `transformer`, `tcn`) |
| `--input-chunk`            | Input window length                                               |
| `--output-chunk`           | Forecast horizon                                                  |
| `--epochs`                 | Number of training epochs                                         |
| `--stopper / --no-stopper` | Enable/disable early stopping                                     |
| `--scale / --no-scale`     | Scale time series before training                                 |
| `--train-fraction`         | Fraction of data used for training (rest is validation)           |
| `--output`                 | Directory to save artifacts                                       |


## View Training Results

Launch dashboard with training results:

```bash
tsft summary results/
```

Optional:

```bash
tsft summary results/ --port 9000
```


## Example Workflow

```bash
# 1. Explore dataset
tsft report data.csv

# 2. Train model
tsft run data.csv --output=output_dir --model=nbeats --epochs=5 --input-chunk=30 --output-chunk=10 --no-stopper

# 3. View results
tsft summary outputs/
```

## Dashboard Preview

![Report Dashboard](images/report.png)

![Training Summary](images/summary.png)