feat: update benchmark/docs pipeline and add forecasting guide demo

Author: jajupmochi

.github/copilot-instructions.md

@@ -61,4 +61,3 @@ wandb/
 
 # Scratch files
 _test_batch.py
-extra_info_work.md

.gitignore

@@ -15,6 +15,7 @@ def _base_config(
     model='lstm',
     split_mode='per_entity',
     id_integration=None,
+    **extra,
 ):
     from liulian.config import load_config
 
@@ -49,7 +50,12 @@ def _base_config(
         model=model,
         d_model=16,
         e_layers=1,
+        d_layers=1,
+        label_len=5,
         enc_in=None,
+        individual=False,
+        moving_avg=25,
+        embed='none',  # Skip temporal embedding (swiss-river has single time feature)
         batch_size=16,
         max_train_iters=5,
         max_eval_iters=5,
@@ -77,6 +83,7 @@ def _base_config(
         seed=2026,
         quick_test=False,
     )
+    cfg.update(extra)
     return cfg
 
 
@@ -121,6 +128,11 @@ def run_scenario(name, cfg):
     'patchtst_single_emb': lambda: _base_config('embedding', False, model='patchtst', split_mode='multi_channel'),
     'patchtst_tune_no_emb': lambda: _base_config('none', True, model='patchtst', split_mode='multi_channel'),
     'patchtst_tune_emb': lambda: _base_config('embedding', True, model='patchtst', split_mode='multi_channel'),
+    # Informer scenarios (multi_channel mode)
+    'informer_single_no_emb': lambda: _base_config('none', False, model='informer', split_mode='multi_channel', factor=3),
+    'informer_single_emb': lambda: _base_config('embedding', False, model='informer', split_mode='multi_channel', factor=3),
+    'informer_tune_no_emb': lambda: _base_config('none', True, model='informer', split_mode='multi_channel', factor=3),
+    'informer_tune_emb': lambda: _base_config('embedding', True, model='informer', split_mode='multi_channel', factor=3),
 }
 
 

INTEGRATION_PLAN.md

@@ -90,13 +90,19 @@ dec_inp = cat([batch_y[:, :label_len, :], zeros(pred_len)])
 # Ground-truth warm-up + zero placeholders for prediction
 ```
 
-### Encoder-only models (DLinear, PatchTST)
+### Encoder-only and decoder-light models
 
-These models accept `(x_enc, x_mark_enc, x_dec, x_mark_dec)` for API
-compatibility but **completely ignore** `x_dec` and `x_mark_dec`.
-**Set `label_len=0`** for these models to avoid constructing unused
-decoder inputs. There is no data-leakage risk either way — the overlap
-region `[seq_len-label_len : seq_len]` is already visible to the encoder.
+Several models accept `(x_enc, x_mark_enc, x_dec, x_mark_dec)` for API
+compatibility but ignore part or all of the decoder path during the
+forecast forward pass. That means `label_len` often has no behavioral
+effect even when the benchmark config still carries a non-zero value.
+
+For strict TSL benchmark parity, many published `PatchTST` and `DLinear`
+scripts still keep the dataset default decoder overlap (`48` for the
+96-step benchmarks, `18` for ILI) even though the model does not use the
+decoder warm-up. By contrast, the TSL `TimeMixer` scripts intentionally
+set `label_len=0` across datasets, and we preserve that as a model-
+specific convention.
 
 ### Encoder-decoder models (Informer, Autoformer, etc.)
 
@@ -159,7 +165,9 @@ Produces **continuous features normalised to `[-0.5, 0.5]`**:
 | Monthly (`m`) | MonthOfYear | 1 |
 
 This is the encoding used by **all standard TSL benchmark scripts**
-(via `--embed timeF`).
+(via `--embed timeF`). Detailed minute offsets such as `10min` and
+`15min` are supported through pandas offset parsing and are preferable
+to ambiguous shorthand when the dataset cadence is known precisely.
 
 ### `timeenc=0` (categorical — manual)
 

_record_baselines.py

@@ -0,0 +1,20 @@
+# Demo Gallery
+
+This page collects runnable forecasting demos built on the unified LIULIAN pipeline.
+
+## Forecasting Demos
+
+- [PatchTST + Swiss River 1990](demo_patchtst_swiss1990.md)
+
+## How to Use
+
+1. Pick a demo page.
+2. Run the command exactly as shown.
+3. Inspect generated artifacts and metrics.
+4. Copy the pattern to your own dataset/model YAML.
+
+## Next Demos to Add
+
+- DLinear on ETTh1 (multi-channel)
+- Informer on ETTm1
+- TimeXer with identifier embeddings

docs/dataset_config_audit.md

@@ -0,0 +1,54 @@
+# Demo: PatchTST on Swiss River 1990
+
+This demo is a minimal, runnable baseline for LIULIAN forecasting.
+
+## Goal
+
+Run PatchTST on `swiss-river-1990` using the unified pipeline and verify that metrics + artifacts are generated.
+
+## Option A: Run the Python Demo Script
+
+```bash
+python examples/forecasting_patchtst_swiss1990_pipeline.py --quick-test
+```
+
+Full run:
+
+```bash
+python examples/forecasting_patchtst_swiss1990_pipeline.py
+```
+
+## Option B: Run Directly from CLI
+
+```bash
+liulian run experiments/swiss_river/patchtst_config.yaml --quick_test
+```
+
+## What This Uses
+
+- Config preset: `experiments/swiss_river/patchtst_config.yaml`
+- Runtime entrypoint: `liulian.pipeline.run_experiment`
+- Config merger: `liulian.config.load_config`
+
+## Expected Outputs
+
+At run completion, check the generated `artifacts` directory (path printed in terminal). You should find:
+
+- `results.json`
+- `predictions.npz`
+- `figures/` plots (if visualization is enabled)
+
+## Validation Checklist
+
+- Process exits with code `0`
+- Metrics are printed in terminal
+- `results.json` exists and includes `metrics` + `timing`
+
+## Adapt This Demo
+
+Try these incremental changes:
+
+1. Change `pred_len` from `7` to `14`
+2. Change `batch_size` from `32` to `16`
+3. Toggle `quick_test` off for full training
+4. Swap model config to another YAML under `experiments/swiss_river/`

docs/datasets.md

@@ -0,0 +1,123 @@
+# Forecasting Pipeline Guide
+
+This guide shows how to run forecasting experiments using the unified pipeline in `liulian/pipeline.py`.
+
+## Why This Pipeline
+
+The forecasting pipeline standardizes the full workflow:
+
+1. Seed and reproducibility setup
+2. Dataset construction
+3. Model construction
+4. Data loader creation
+5. Experiment run (train/eval)
+6. Artifacts and `results.json` export
+
+Use it when you want consistent behavior across datasets and models.
+
+## Pipeline API Map
+
+Core APIs:
+
+- `liulian.config.load_config`: merge `DEFAULT_CONFIG < YAML < CLI`
+- `liulian.pipeline.build_dataset`: create dataset from config
+- `liulian.pipeline.build_model`: create model from config
+- `liulian.pipeline.build_loaders`: create train/val/test loaders
+- `liulian.pipeline.build_experiment`: wire Task + Data + Model + Runtime
+- `liulian.pipeline.run_experiment`: run full end-to-end pipeline
+
+Most users should call only `run_experiment(config)`.
+
+## Quick Start (CLI)
+
+Run PatchTST on Swiss River 1990:
+
+```bash
+liulian run experiments/swiss_river/patchtst_config.yaml
+```
+
+Quick test mode (small, fast smoke run):
+
+```bash
+liulian run experiments/swiss_river/patchtst_config.yaml --quick_test
+```
+
+Override key hyperparameters from CLI:
+
+```bash
+liulian run experiments/swiss_river/patchtst_config.yaml \
+  --pred_len 14 \
+  --train_epochs 20 \
+  --batch_size 16
+```
+
+## Quick Start (Python)
+
+```python
+from liulian.config import load_config
+from liulian.pipeline import run_experiment
+
+cfg = load_config(
+    'experiments/swiss_river/patchtst_config.yaml',
+    cli_overrides={
+        'quick_test': True,
+        'hpo': False,
+    },
+)
+summary = run_experiment(cfg)
+print(summary.get('artifacts_dir'))
+```
+
+## Configuration Flow
+
+The config merge order is:
+
+1. `liulian.config.DEFAULT_CONFIG`
+2. YAML config file (for example `experiments/swiss_river/patchtst_config.yaml`)
+3. CLI or programmatic overrides
+
+Practical advice:
+
+- Keep experiment presets in YAML files under `experiments/`
+- Use CLI overrides for one-off comparisons
+- Use `quick_test: true` for sanity checks before long runs
+
+## Artifacts and Results
+
+After each run, the pipeline writes artifacts to an experiment directory (under `artifacts/`), typically including:
+
+- `results.json`: structured summary for auditing and comparison
+- `predictions.npz`: raw predictions and ground truth arrays
+- `figures/`: generated forecast visualizations (if enabled)
+
+For `results.json` fields, see [Results JSON](results_json.md).
+
+## Common Troubleshooting
+
+### OOM or very slow training
+
+- Reduce `batch_size`
+- Reduce model width (`d_model`, `d_ff`, `n_heads`)
+- Start with `--quick_test` to validate pipeline integrity first
+
+### Dataset not found
+
+- Confirm dataset key in config `data:` is valid
+- The pipeline attempts auto-download for supported datasets
+
+### Unexpected split behavior
+
+- Confirm `split_mode` and `train_split`
+- Check whether your model expects `multi_channel` or `per_entity`
+
+## Demo Gallery
+
+For ready-to-run examples, see [Demo Gallery](demo_gallery.md).
+
+## External Design References
+
+These resources were used as style references for clear forecasting quickstarts:
+
+- [PyTorch Forecasting tutorial](https://pytorch-forecasting.readthedocs.io/en/stable/tutorials/stallion.html)
+- [GluonTS quick start](https://ts.gluon.ai/stable/tutorials/forecasting/quick_start_tutorial.html)
+- [NeuralForecast quick start](https://nixtlaverse.nixtla.io/neuralforecast/docs/getting-started/quickstart.html)

docs/demo_gallery.md

@@ -25,6 +25,8 @@ python examples/quick_run.py
 ## Documentation
 
 - [Architecture](architecture.md) — Design decisions and module overview
+- [Forecasting Pipeline Guide](forecasting_pipeline.md) — End-to-end run flow using `liulian.pipeline`
+- [Demo Gallery](demo_gallery.md) — Runnable forecasting demos
 - [Adapter Guide](adapter_guide.md) — How to write model adapters
 - [Manifest Specification](manifest_spec.md) — YAML dataset manifest format
 - [Contributing](contributing.md) — How to contribute to liulian