use case streaming timeseries

Spikeforge — UC-1: Streaming Time-Series Classification / Anomaly Detection

The first fully scoped production use case, and the reference implementation for the rest. Consumes the shared enablers from production_toolkit_plan.md; listed in the umbrella production_use_cases.md.

Design/spec only. Every claim about current code is grounded in a file/line reference so a Code-mode agent can execute this file-by-file. No implementation starts in this document.

---

1. Problem and users

What. Given a continuous numeric stream (vibration, machine telemetry, network-flow features, grid/sensor channels) delivered as windows, produce (a) a class label or (b) an anomaly score per window, with a bounded per-window latency, running on CPU (GPU optional), with no neuromorphic hardware.

Users. Reliability/ML engineers adding a low-latency monitor beside an existing pipeline; researchers who want a runnable SNN baseline on tabular time series.

Why SNN here. Temporal state is carried in membrane potentials rather than a framed RNN window; updates are sparse and event-driven; the per-step loop maps to a streaming sensor without large buffering. This is the use case where the SNN's structure is an advantage on conventional hardware.

Success criteria (SLAs).

• Latency: p99 per-window decision under a configured budget (target: single-digit milliseconds on CPU for a small fc_small/sequence_mlp).
• Quality: classification F1 / balanced accuracy, or anomaly AUROC, above a dataset-specific floor defined at kickoff.
• Throughput: N concurrent streams per process without exceeding the latency budget.
• Zero hardware: everything runs on a laptop or a small CPU container.

---

2. Reference architecture

flowchart LR
    A[Stream source] --> B[Windower and normalizer]
    B --> C[Encoding contract]
    C --> D[Stateful InferenceSession]
    D --> E[Classifier / anomaly head]
    D --> F[Bundle and spec]
    F --> D
    E --> G[spikeforge-serve REST and stream]
    G --> H[Client SDK]
    G --> I[Metrics and tracing]
    AG[Offline training] --> F

Loading

Legend: the offline half is largely existing; the online half is the new machinery (W1/W2/W3).

---

3. Offline: data, encoding, model, training

3.1 Data

• Sources: one public dataset (e.g. an industrial/telemetry or network-flow set) plus a synthetic generator for CI. Window length L, stride 1 for streaming, per-channel z-score normalization fitted on train only.
• Contract: a frozen preprocessing.json (normalization stats, window L, stride, channel order) stored in the bundle (W2). This is what prevents train/serve skew.
• Repo fit: windowing/normalization belongs to spikeforge-io (W7); the synthetic generator parallels sequence_source.py.

3.2 Encoding

• Primary coding: delta over the window (temporal change is the signal), with rate as a fallback baseline; both from spike_encoder.py and frozen in the bundle (encode_config.schema.json).
• Input shape: [T, B, L, D] windows, matching the sequence presets (sequence_presets.py) and the simulator's [T, …] contract.
• Deliverable: spikeforge.serving.preprocess.encode(sample, spec) -> spikes, the single function both training and serving must call (W2).

3.3 Model

• Topology: sequence_mlp (NIR-exportable, [T, B, L, D]) as the primary; fc_small/fc_legacy as the tabular baseline. Declared once as a TopologySpec (spec.py).
• Head: softmax classifier by default; an anomaly variant swaps the head for a one-class score (e.g. energy/negative-log-likelihood) while reusing the same temporal trunk.
• Reuse: TrainingEngine, surrogate gradients, AMP/BPTT scale-ups, checkpointing (checkpoint_mixin.py).

3.4 Evaluation

• Classification: F1 / balanced accuracy / per-class recall. Anomaly: AUROC / AUPRC with a false-positive budget.
• Validation: NIR drift (within_tolerance) and determinism (determinism.py).
• A reproducibility manifest is written with every run (manifest.py).

---

4. Online: bundle, runtime, service

4.1 Deployment bundle (W1)

• model.spkf with manifest.json (spec, versions, expected metrics, label map), weights.pt, encode_config.json, preprocessing.json, graph.nir.json, checksums/signature. Built from a checkpoint + the frozen encode/preprocessing specs.
• Anchors: model_store.py, serialization.py.

4.2 Stateful runtime (W1)

• InferenceSession.load(bundle), .reset(), .step(frame) -> Prediction, .run_stream(frames); carried state serializable via a StateTree (numpy-tagged, like array_codec.py).
• Shares the per-step body with the closed loop extracted from execution.py, so streaming and batch cannot diverge. Trajectory and run() stay unchanged.

4.3 Service (W3)

• spikeforge-serve endpoints: POST /v1/predict, POST /v1/reset, GET|WS /v1/stream, GET /health, GET /metrics, GET /v1/bundle.
• Per-stream session ids; batching; concurrency cap; auth token; timeouts.
• One model (classification or anomaly) per process by default; multi-model routing is a later extension.

4.4 Observability (W6)

• Prometheus/OTel over observability/registry.py: request latency histogram, throughput, queue depth, spike rate/sparsity per stage, anomaly-score distribution.
• Serving benchmark: p50/p99 latency, throughput at concurrency N, cold start, peak memory, wired into the regression gate (compare.py).

4.5 Delivery & operations (W7)

• Minimal inference container + compose profile; promotion dev -> staging -> prod with an approver and a signed bundle; rollback = repoint to the prior bundle.
• Drift: monitor input statistics and score distribution; retrain trigger.

---

5. Phased delivery

Phase	Deliverable	Depends on	Acceptance
P0	Data + synthetic generator + windowing spec	—	windowing reproducible; z-score frozen
P1	sequence_mlp trained on the dataset; metrics + manifest	P0	F1/AUROC above the floor; NIR validates
P2	InferenceSession (step/reset/run_stream) + tests	W1	streaming readout == closed-loop run within tolerance
P3	DeploymentBundle export/import	W1	fresh-process rebuild is exact; tamper is refused
P4	spikeforge-serve /predict + /stream + /health	W2, W3	parity with in-process; state persists; reset works
P5	/metrics, serving benchmark, CI latency gate	W6	p99 within budget in CI
P6	Container, rollback, drift monitor	W7	promote/rollback demo; drift alarm fires

MVP = P0–P4. That is the smallest end-to-end slice that demonstrates the chip-less production story.

---

6. Ticket breakdown (seeds)

• UC1-a Data adapter + synthetic generator + frozen windowing spec.
• UC1-b sequence_mlp baseline + anomaly head + evaluation report.
• UC1-c spikeforge/serving/ stateful InferenceSession (W1).
• UC1-d DeploymentBundle build/load + tamper check (W1).
• UC1-e Encode-at-inference shared function + bundle wiring (W2).
• UC1-f spikeforge-serve endpoints + session store + auth (W3).
• UC1-g Metrics/tracing + serving benchmark + CI latency gate (W6).
• UC1-h Container + promotion/rollback + drift monitor (W7).

7. Out of scope

• Neuromorphic hardware timing/energy (needs silicon; energy stays estimate: true).
• Full temporal ONNX (by design; NIR is the temporal graph).
• Distributed multi-model serving and autoscaling (later).
• Any claim of measured power.

8. Risks

Risk	Mitigation
Dataset choice weakens the story	pick a set with a genuine temporal signal; keep the synthetic CI fixture
Encoding mismatch train vs serve	W2 forces one encode function; bundle pins the spec
Latency budget unmet on CPU	start at sequence_mlp/fc_small, profile in P5, prune via W5 if needed
Anomaly head underperforms	keep classification as the primary deliverable; anomaly as an additive head