Train a Next-Event Prediction Model from CSV Event Logs

A CSV of events is not yet a training set for next-event prediction. The rows need an owner, an order, and a prediction question. This walkthrough turns ordered event histories into leakage-controlled training windows, trains a next-event model, and checks both its saved checkpoint and held-out predictions. If the owner, order, or prediction time is ambiguous, a training run can complete while learning from the wrong history—or from information that would not yet have existed.

The example predicts the next action in a product session from actions already observed. The first nine synthetic rows make the sequence contract visible; a deterministic generator expands them to 240 sessions for an executed pipeline smoke test. That run used Sequifier source v3.1.1.0, Git commit bf49d7b05f02abb21f8b3ebcbc3d4bff1a7f01ee. Its observed files and predictions are shown below. The generated patterns are deliberately simple, so the run verifies mechanics rather than performance on real users. The same questions apply to equipment events, transactions, or patient encounters, although their split and validation rules may differ substantially.

Raw event export → define the sequence and prediction time → sort, audit, and split → encode and window → train and compare with a baseline → save and export → run held-out inference and inspect errors.

The useful question is not simply “How do I load a CSV?” It is: what information should be visible when predicting each next event, and how can I prove that every pipeline stage respects that boundary?

Give every row a sequence and an order

Suppose an application records actions within a session. A source export might contain a session identifier, timestamp, event type, and a later outcome such as whether the session converted. To predict the next event, the input at a given step must contain only actions already observed. The eventual conversion outcome is not an input unless it was genuinely known at that step.

For the minimal example, reduce the export to sequenceId, itemPosition, and event. A nine-row CSV example appears in the annex.

Here, sequenceId identifies one session and itemPosition is its chronological event index. Nine rows alone cannot establish a useful model or reliable holdout. The annex contains generate_sessions.py, which reproduces those two sessions and adds 238 deterministic sessions. Save it in a project directory and run python generate_sessions.py from there. It creates data/sessions.csv with 240 sessions and 3,868 event rows.

The synthetic rule creates repeated searches and views, then an optional cart event and a terminal action. It is useful for tracing the pipeline and deliberately poor evidence for a model’s value in a live application. If the original log has timestamps, preserve them in a raw audit table even if the model input uses only positions. Resolve duplicate timestamps with a stable rule, identify events that arrived late, and make sure two session IDs do not accidentally describe the same continuing history. A model cannot repair a broken event order.

What constitutes one sequence depends on the prediction. A session is appropriate if the next action should be predicted from the current visit. If the question concerns behaviour across visits, a user history is a different sequence with different privacy, identity, and evaluation implications. Conversely, treating a whole user history as one sequence when the system resets state between visits may teach dependencies that are irrelevant at serving time.

Write down the prediction contract before encoding anything:

Decision	Choice in this example	Why it matters
Unit of history	One session	A target never borrows actions from another session.
Visible information	Events through position t	Later actions and eventual outcomes are unavailable.
Target	Event at position t + 1	This is a next-event, not an end-of-session, task.
Prediction horizon	One event	A multistep forecast would need a separate inference design.
Evaluation unit	Held-out sessions	Repeated windows from the same session must not be treated as independent test sessions.

For session 101, the context open → search → view has add_to_cart as its next-event target. The context open → search → view → add_to_cart has checkout as its target. That temporal relationship—not the CSV format—is what makes this sequence learning.

Split before learning the encoding

Randomly splitting individual rows is a bad default. Several windows from one session would then appear in both training and evaluation, and the model could see adjacent pieces of the same history on either side. Instead, assign whole sequenceId values to train, validation, and test when the intended question is generalisation to new sessions. In Sequifier this is the between_sequence split method; its preprocessing guide also documents within_sequence and value_cutoff for different questions. The choice must match how the model will be used.

Keeping sessions apart does not automatically solve every leakage problem. If the same person appears in many sessions and the intended deployment population is new people, split by person before assigning session IDs to partitions. If the application or event vocabulary changed over calendar time, a chronological holdout may be more revealing than a random session holdout. Conversely, a chronological cut through a long sequence needs careful control over how much pre-cut context may be used for post-cut predictions. Define that policy explicitly rather than assuming one split method covers all use cases.

Encoding is also part of the split boundary. A categorical map built from all data knows which categories appear in the holdout; a numerical standardisation fitted on all rows uses holdout statistics. Sequifier’s preprocessing guide says its default normalize_on_all_data: false fits numerical statistics and dynamic categorical vocabularies on split 0, with later-only categories mapped to [other] unless hashing is configured. Keep the fitted metadata with the model, and inspect how often unknown categories occur in validation and test. The general “fit on train, transform the rest” rule is also explained in scikit-learn’s data leakage guidance.

For this example, a preflight audit should count sequences and events per partition, check that session IDs are disjoint, reject duplicate (sequenceId, itemPosition) pairs, and check that positions increase within each session. It should also count missing event values and compare the event vocabulary across partitions. If a rare checkout event lands only in the test set, the model cannot learn that class as an ordinary target from the training set; no transformer setting fixes that data problem.

Turn ordered events into model windows

A sequence model consumes a bounded context, not an indefinitely long CSV group. Let the model see the previous eight event positions and predict the next one. One physical stored window therefore needs room for eight input positions plus one future target position. In Sequifier terms, that is context_length: 8, max_target_offset: 1, and a nine-position preprocessing window_length. Short histories are left-padded; long histories produce multiple windows. The training guide distinguishes the stored-window width from the model’s context_length.

The four-event prefix open, search, view, add_to_cart illustrates what the model sees when asked to predict checkout. The stored nine-position window is four padding positions followed by open, search, view, add_to_cart, and the target checkout. The model sees the first eight positions; checkout is the ninth, withheld position.

That description shows the input and target relationship, rather than Sequifier’s literal on-disk format. In the executed run, session 101’s first stored window reported startItemPosition: -4 and leftPadLength: 4. Its encoded values decoded to four padding positions, then open, search, view, add_to_cart, checkout. The first eight positions are the context and checkout is the target. The important invariant is that the target is to the right of the visible context. Inspect a few generated windows manually: an off-by-one error can yield a very low loss by asking the model to repeat an event it already saw.

Stride determines which windows are stored. With a preprocessing window_stride of one, neighbouring windows overlap heavily and many successive target positions can be used. This increases storage and compute. A larger stride reduces that cost but, with prediction_length: 1, may train on far fewer target positions. The preprocessing guide’s stride discussion makes this distinction explicit: context positions are not all necessarily loss positions. For a first experiment, measure the number of target events actually contributing to training rather than reasoning only from the number of raw rows.

Window length is a modelling choice, not a universal property of the data. Eight events may miss the start of a long session; 128 may waste compute and padding on short ones. Plot session-length percentiles and ask how far back evidence of the next event plausibly lies. Try a short context first, then test whether longer context improves a held-out metric enough to justify the extra memory and latency. If only the last action matters, a transition model may be sufficient.

There is a subtler issue with short sessions. A session with just open → exit supplies little history, while a session with dozens of actions can supply many targets under a small stride. The longer session can therefore dominate a window-weighted loss even if your product cares equally about each session. Report both event-weighted and session-weighted evaluation, or at least show their denominators. If the application asks for one prediction per session at a particular point, evaluate at that point; do not treat every intermediate position as an equally relevant decision.

The training target also defines what a “correct” row means. If exit is recorded only when a client sends a clean close event, abandoned sessions may end without an exit row. The model then learns from the logging process as much as from user behaviour. Decide whether session termination is a target, a censoring condition, or simply missing telemetry. Similar questions arise with maintenance events, payment reversals, and clinical discharge records. A windowing tool can build windows consistently, but the meaning of the final event remains the engineer’s responsibility.

Establish a baseline before training a transformer

The simplest baseline predicts the most frequent next event in the training set. A more informative one estimates a transition table: among training events following search, how often was the next event view, another search, or exit? A smoothed transition table can produce probabilities, not just a top class. A tree model over the last few event codes and counts is another credible baseline if it is built and evaluated under the same split contract.

The transition table cannot directly distinguish search → view from search → search → view if it uses only the last event. A sequence model can condition on a longer ordered prefix, which is useful when that extra order contains predictive information. But the model also has more parameters, needs more data, and can learn accidental correlations in rare event paths. The decision is empirical: measure whether longer context improves the held-out outcome and whether the gain survives a later time period or a changed event mix.

Choose metrics that correspond to the intended use. Next-event negative log likelihood measures the probability assigned to the observed event and punishes confident mistakes; top-one accuracy asks whether the most likely event was correct. Report both alongside the majority-class and transition baselines. If checkout is rare but operationally important, also report its recall or precision at a threshold chosen on validation data. A single aggregate accuracy can improve while the rare event gets worse. Compute confidence intervals or repeat across several holdout partitions where the dataset permits; overlapping windows should not be counted as independent sessions when estimating uncertainty.

This comparison should hold the information budget constant. A transition baseline that sees only the last action and a transformer that sees eight actions answer different feature questions as well as using different model classes. One fair set of comparisons is: majority class; last-event transition table; a baseline using the last eight actions or summary counts; then the transformer with an eight-event context. If the richer baseline closes most of the gap, the result may be attributable to additional history rather than attention. Tune each method on validation data and touch the test set once, after the comparison protocol is fixed.

An apparent gain also needs a failure analysis. Break errors out by event type, session length, first versus later prediction, and whether a category was unseen in training. Check whether the model assigns implausible probabilities to impossible transitions. If the system’s action vocabulary changes, a held-out set from the same month may overstate future performance. A later, untouched time period is valuable even when the main development split is by session. These checks can overturn an attractive average metric without requiring a more elaborate model.

Train, save, and distinguish the artifacts

Once the source contract and baseline are established, Sequifier can standardise the sequence-specific middle of the workflow. Its README documents make, preprocess, train, and infer; the project scaffold supplies config files to adapt. The following settings are those used in the executed CPU smoke test with Sequifier v3.1.1.0 at the pinned commit above. They follow the preprocess and train guides. For real modelling, replace the synthetic generator with a substantially larger, audited dataset.

To reproduce this run, use an isolated Python environment with Python 3.10 or newer. The annex gives the commands to install the pinned source revision and the complete configuration files. The version available through a general pip install sequifier may differ from the one used here.

The full configs/preprocess.yaml used for this run is in the annex.

Save the annex’s preprocessing configuration as configs/preprocess.yaml and run sequifier preprocess --config-path configs/preprocess.yaml from the project root. In the executed run, this wrote data/sessions-split0.parquet with 1,565 windows from 193 sessions, split 1 with 215 windows from 25 sessions, and split 2 with 193 windows from 22 sessions. The metadata at configs/metadata_configs/sessions.json contains the category mappings and the paths and contract that training uses. Check the split counts and decoded examples before moving on. An empty validation split, unexpected [other] frequency, or an implausible number of windows is a data issue, not a reason to tune the transformer.

The training guide’s singleton form is suitable for one interface and one dataset. This compact example predicts the categorical event column from itself. Its small architecture is only a smoke-test setting, not a recommended production size.

The full configs/train.yaml used for this run is in the annex.

Save the annex’s training configuration as configs/train.yaml and run sequifier train --config-path configs/train.yaml after confirming that the preprocessed files and metadata match. The physical width, model context, and one-step target must agree. Here, 9 = 8 + 1. Changing one of those values without revisiting the others changes the task or makes the configuration invalid. Five epochs completed in the smoke test. Sequifier’s validation log recorded a loss of 0.360 at epoch 5; because the data comes from a simple generator, this is an execution check, not a measure of likely performance on real sessions.

The word checkpoint deserves precision. A resumable training checkpoint records the state needed to continue a run, including the optimisation lifecycle; interval settings refresh a latest checkpoint and can create persistent snapshots. The run wrote checkpoints/runs/session-next-event/session-next-event-latest.pt and five epoch snapshots. It also exported models/session-next-event-best-5.onnx for inference. Sequifier’s training artifact guide describes ONNX as the default export and PT inference bundles as an opt-in path. An ONNX export is not interchangeable with a resumable training checkpoint. Keep the chosen artifact, the exact preprocessing metadata, the configuration, code version, and evaluation results together in the experiment record. A file existing on disk proves only that a stage wrote it; it does not prove the model is useful.

For the first run, inspect the training and validation curves. A decreasing training loss with a rising validation loss suggests that more epochs or capacity are unlikely to help without a better data or regularisation strategy. If both are flat, verify that target windows exist, that labels are meaningful, and that the event vocabulary was encoded as intended before increasing model size. Checkpoint selection should use validation information; reserve the test partition for a final estimate after decisions are fixed.

Close the loop with held-out inference

Inference must receive data encoded under the same contract as training. Sequifier’s inference guide explains how current model exports and metadata provide the columns, types, and window settings, and how it rejects conflicting explicit values. This executed config used the generated test split and the ONNX file produced by the run. If a different epoch wins in a rerun, update model_path to that export.

The full configs/infer.yaml used for this run is in the annex.

Save the annex’s inference configuration as configs/infer.yaml and run sequifier infer --config-path configs/infer.yaml. The run wrote 193 predictions to outputs/predictions/session-next-event-best-5/part-000.csv; all 193 (sequenceId, itemPosition) pairs matched rows in the original CSV. The output includes window identifiers so predictions can be joined to their observed targets. For example:

Held-out row	Observed next event	Predicted event
Session 123, position 12	view	search
Session 123, position 13	view	view

Across the 193 test-window targets, the top prediction matched 151 observed events; a majority-class baseline fixed from the training targets (view) matched 121 of those same targets. These are smoke-test counts on hand-generated sequences, not evidence of real-world utility or a general transformer advantage. More revealingly, all 42 mistakes occurred where the observed event changed from the previous event: the model got all 144 repeated-event targets right but only 7 of 49 transition targets. The apparent aggregate result mostly reflects the generator’s long runs of repeated actions. Review complete sessions, rare classes, and short left-padded histories rather than stopping at the aggregate. If probabilities are needed, the inference guide documents optional categorical probability output; the default prediction file alone is not a calibration analysis.

The final handoff can be audited without trusting a training dashboard. This table is a compact record of what each stage receives, writes, and must preserve:

Stage	Input and output	Check before proceeding
Event preparation	Raw log → ordered (sequenceId, itemPosition, event) rows	Inspect tie-breaking, missing events, duplicate positions, and whether each row belongs to the intended history.
Split	Ordered rows → disjoint train, validation, test populations	Check the split unit against deployment and verify that no identity or future outcome crosses the boundary.
Preprocess	Split rows → encoded windows plus metadata	Decode sample windows, count target positions, inspect unknown categories, and confirm the scaler and vocabulary came from training data.
Train	Windows and objective → checkpoints and exported models	Check that context and target offsets agree, losses move sensibly, and the chosen artifact corresponds to a recorded validation run.
Infer	Export, metadata, held-out windows → predictions	Join by sequence and window identifiers, confirm output positions, compare with baselines, and inspect error slices.

If a checkpoint is handed to another team, attach this record to it. Without the category map, the same integer ID might mean something else in a later dataset. Without a split policy, a reported score is hard to interpret. Without the exact target definition, a next-event predictor can be mistaken for an outcome model. Those are reproducibility failures even if the model file loads successfully.

This example predicts one step using observed history. It does not establish realistic multistep simulation. Feeding each prediction back changes the input distribution and can compound errors. Sequifier supports autoregressive inference only under specified conditions, including a causal model, identical input and target columns, and one-step targets; check those conditions and evaluate rollout behaviour separately before using generated sessions for decisions.

When this pipeline is the right tool

The practical journey is a sequence of contracts: rows have an owner and order; splits define what is unknown; windows define what the model sees; the objective defines what it predicts; metadata defines how values are encoded; the checkpoint preserves training state; the export defines inference. At each handoff, inspect a concrete sample and test the invariant. That practice is useful with or without Sequifier.

If a majority-class or transition baseline is adequate, a transformer adds cost without a clear benefit. If the question truly depends on longer ordered context across many examples, a configurable sequence workflow can reduce the amount of custom windowing, training, and export code an engineer must maintain. Start with the Sequifier preprocessing guide, then adapt the training and inference configs to the actual dataset. The model’s value still has to be demonstrated against the right baseline and holdout.

Annex: CSV, generator, commands, and configs

Use a single project directory. Save the Python file in its root and the three YAML files in configs/. Run the generator first, then install Sequifier and run preprocessing, training, and inference in that order.

Nine-row CSV example

sequenceId,itemPosition,event
101,0,open
101,1,search
101,2,view
101,3,add_to_cart
101,4,checkout
102,0,open
102,1,search
102,2,search
102,3,exit

Generate the full CSV

Save as generate_sessions.py and run python generate_sessions.py.

import csv
from pathlib import Path
from random import Random

ROOT = Path(__file__).resolve().parent
DEST = ROOT / "data" / "sessions.csv"
rng = Random(987)

def generated_session():
    events = ["open"]
    events.extend(["search"] * rng.randint(2, 12))
    events.extend(["view"] * rng.randint(2, 12))
    if rng.random() < 0.72:
        events.append("add_to_cart")
        events.append("checkout" if rng.random() < 0.63 else "exit")
    else:
        events.append("exit")
    return events

sequences = {
    101: ["open", "search", "view", "add_to_cart", "checkout"],
    102: ["open", "search", "search", "exit"],
}
for sequence_id in range(103, 341):
    sequences[sequence_id] = generated_session()

DEST.parent.mkdir(parents=True, exist_ok=True)
with DEST.open("w", newline="") as handle:
    writer = csv.writer(handle)
    writer.writerow(["sequenceId", "itemPosition", "event"])
    for sequence_id, events in sequences.items():
        for position, event in enumerate(events):
            writer.writerow([sequence_id, position, event])

Install the pinned Sequifier revision

git clone https://github.com/0xideas/sequifier.git
git -C sequifier checkout bf49d7b05f02abb21f8b3ebcbc3d4bff1a7f01ee
python -m pip install ./sequifier

Preprocessing config

Save as configs/preprocess.yaml.

# configs/preprocess.yaml — used in the synthetic run
project_root: .
preprocessing_data_path: data/sessions.csv
read_format: csv
write_format: parquet
selected_columns: [event]
categorical_columns: [event]
window_length: 9
max_target_offset: 1
window_stride: 1
split_method: between_sequence
split_ratios: [0.8, 0.1, 0.1]
normalize_on_all_data: false
seed: 1010

Training config

Save as configs/train.yaml.

# configs/train.yaml — used in the synthetic run
project_root: .
model_name: session-next-event
device: cpu
seed: 1010

global_training:
  read_format: parquet
  training_objective: causal
  context_length: 8
  target_offset: 1
  inference_batch_size: 128
  batch_size: 128
  learning_rate: 0.0001
  save_interval_epochs: 1
  torch_compile: none

model:
  backbone:
    architecture:
      dim_model: 64
      max_context_length: 8
      num_layers: 2
      attention: {type: mha, n_heads: 4, n_kv_heads: 4, output_projection: true}
      feed_forward: {dim: 256, activation: swiglu}
      normalization: {type: rmsnorm, norm_first: true}
      position_encoding: {type: rope, theta: 10000}
      dropout: 0.1
      shared_layer_groups: []
  interface:
    input_columns: [event]
    target_columns: [event]
    ingestion: {type: embedding, output_dim: 64}
    decoder: {type: linear, prediction_length: 1, support: 1}

dataset:
  part: {metadata_config_path: configs/metadata_configs/sessions.json}
  criterion: {event: CrossEntropyLoss}

training_plan:
  epochs: 5

evaluation: true
export_generative_model: true
export_onnx: true

Inference config

Save as configs/infer.yaml.

# configs/infer.yaml — used in the synthetic run
project_root: .
model_path: models/session-next-event-best-5.onnx
metadata_config_path: configs/metadata_configs/sessions.json
data_path: data/sessions-split2.parquet
model_type: generative
device: cpu
read_format: parquet
write_format: csv

Run the pipeline

From the project root, after generating the CSV and installing Sequifier:

sequifier preprocess --config-path configs/preprocess.yaml
sequifier train --config-path configs/train.yaml
sequifier infer --config-path configs/infer.yaml