# cascade base generator (genesis "base" king)

A self-contained cascade data generator that adapts a curated subset of
[TempoPFN](https://github.com/automl/TempoPFN)'s procedural synthetic time-series
priors into a single deterministic `Generator(DataGenerator)`. Intended as the
launch/genesis king for the cascade subnet.

## What's inside

| file | purpose |
|------|---------|
| `generator.py` | `class Generator(DataGenerator)` — the entrypoint |
| `config.json` | length band, per-family mixing weights, sanitisation knobs |
| `requirements.txt` | hash-locked, allowlisted deps (`numpy, scipy, pandas, torch, scikit-learn, gpytorch, networkx`) |
| `tempo_gen/` | vendored, import-rewritten TempoPFN subset (Apache-2.0) |
| `NOTICE`, `LICENSE` | TempoPFN attribution + Apache-2.0 text |
| `tests/` | contract tests + a diversity sanity check |

## Generator families

Ten families are mixed by weight: **ForecastPFN, SineWave, SawTooth, Step,
Anomaly, Spikes, OrnsteinUhlenbeck, GP-prior, KernelSynth, CauKer**. Each is
drawn at `generate_length` (4096) and deterministically random-cropped into the
`[min_length, max_length]` band for length diversity.

The GP/kernel family — **GP-prior** (gpytorch), **KernelSynth** (scikit-learn)
and **CauKer** (networkx + scikit-learn) — was added in v2: those deps are now
on cascade's allowlist (`chain.toml [dependencies]`). The TempoPFN ablation
shows this family carries a large share of the downstream signal. CauKer is
multivariate (an SCM DAG of GP-prior nodes); each channel is flattened into its
own univariate series so the emitted corpus stays 1-D. Its upstream GPU
(`cupy`) draw was replaced with NumPy's seeded `multivariate_normal` to keep the
generate path CPU-only and reproducible.

The pyo-backed **audio** generators remain **excluded**: pyo runs a real-time
audio server and seeds via `hash()`, both of which break the cross-process
determinism contract below (and pyo is not on the allowlist).

## Determinism

The corpus is a pure function of `(seed, n_series)`. We seed NumPy / torch /
Python `random` from `seed`, run torch on CPU with deterministic algorithms,
derive every per-family and per-series sub-seed from the master seed, and use a
separate seeded RNG for cropping. The upstream `hash()`-based per-generator seed
offset — salted per process by `PYTHONHASHSEED` — was replaced with a stable
`zlib.crc32` in `tempo_gen/.../abstract_classes.py`, so two audit runs in
*separate processes* produce byte-identical corpora.

## Verify / test

```bash
# from the cascade repo root, with deps installed and cascade importable
cascade verify ./base_generator                       # full trainer-side checks
PYTHONPATH=$PWD pytest base_generator/tests -q           # contract tests
PYTHONPATH=$PWD python base_generator/tests/diversity_check.py
```

## Config knobs (`config.json`)

- `min_length` / `max_length` — per-series length band (defaults 64 / 4096, matching `chain.toml` — and `[training] context_length`, so series can fill the model's context as Toto 2.0's do).
- `generate_length` — length generators are drawn at before cropping (>= `max_length`).
- `batch_size` — internal generation batch size (memory/throughput knob).
- `weights` — per-family mixing weights (normalised; families with weight 0 or absent are skipped).
- `standardize` — z-normalise each series (default `false`; off preserves scale diversity).
- `clip_sigma` — if > 0, clip each series to `mean ± clip_sigma·std` (default `0`, disabled).
- `max_abs_value` — hard magnitude clip to keep output trainer-safe finite.