Seahorse¶

A modular, research-grade framework for end-to-end development, training, and evaluation of
spatio-temporal point-process (STPP) models.

Seahorse couples declarative YAML configuration with PyTorch Lightning execution, Ray Tune hyper-parameter optimisation, and version-controlled run artifacts to support rapid prototyping and reproducible benchmarking on streaming event data.

Run One Model model.fit(train, val, test) Fit, evaluate, and sample from any registered model through a consistent Python API. Python API Run a Benchmark python -m seahorse bench Compare presets across datasets and seeds from one CLI command with saved, reproducible artifacts. Run a Benchmark Evaluate Results model.evaluate(test) Run metric profiles — likelihood, predictive, surface — on any saved run directory. Evaluation Guide Add Your Model @ConfigRegistry.register(...) Register a preset and your model works with fit, bench, and the metric profiles without changing import paths. Developer Guide

What Seahorse Provides¶

Capability	What it gives you
Unified Python API	Train, evaluate, and sample any supported model through one interface.
YAML-driven experiments	Keep hyperparameters, data paths, and run settings explicit and reproducible.
Model presets	Switch among AutoSTPP, DeepSTPP, neural CNF families, diffusion models, NSMPP, SMASH, THP, RMTPP, and parametric baselines.
Benchmark campaigns	Run multi-preset, multi-dataset, multi-seed evaluations with comparable metrics.
Artifact-backed evaluation	Save run directories, metric tables, predictive samples, and surface diagnostics for later inspection.

Quick Start¶

Python APICLI

from seahorse import AutoSTPP, PoissonGMM, load_jsonl

train = load_jsonl("dataset_root/train.jsonl")
val   = load_jsonl("dataset_root/val.jsonl")
test  = load_jsonl("dataset_root/test.jsonl")

model    = AutoSTPP(device="cpu")
baseline = PoissonGMM()

model.fit(train, val, test, epochs=50, batch_size=64)
scores  = model.evaluate(test)
samples = model.predict_next(test, n_samples=32)

python -m seahorse fit \
  --preset auto_stpp \
  --train dataset_root/train.jsonl \
  --val   dataset_root/val.jsonl \
  --test  dataset_root/test.jsonl \
  --out   runs/quickstart

Benchmarking Workflow¶

Seahorse reads JSONL event-sequence splits from local files or compatible Hugging Face datasets. Every benchmark run applies a shared data contract so models are evaluated on the same train, validation, and test splits with the same metric definitions.

Seahorse overview: event data, model, and YAML config feed into the framework, which outputs reproducible metrics and tuned results.

Start with the end-to-end case study, run a small benchmark, or open the tutorial notebooks.