spikeforge — long-form reference

This is the complete reference for spikeforge, a spiking-neural-network toolkit built on snnTorch and PyTorch — install paths, the CLI tools, the architecture, and every shipped capability with an honest note on how far each one actually goes.

Where to start depends on why you are here:

• Evaluating it — Quickstart for the first run, then Features for the inventory and Implications and boundaries for what the numbers do and do not mean.
• Building on it — Architecture and Project layout are the map, then follow the capability you need from the tables below.
• Contributing to it — Development, then Plans for the design records behind each workstream.

The documentation is implementation-oriented and deliberately detailed, which is also what makes it the reference contributors and coding agents work from. The top-level README is the short entry point and links back here.

Editing this documentation? If you also see a docs/ folder locally, that is a generated, git-ignored MkDocs build (scripts/build_docs.sh regenerates it from this folder plus plans/) and never appears on GitHub. This folder is the one source of truth to read or edit.

Orientation

Document	What it covers
Quickstart	Install paths and the first run
Requirements	Dependencies, optional extras, and licensing
Usage	Docker, local dev, CLI, and device selection
Architecture	The TopologySpec spine and the data flow
Project layout	Module-by-module map and code conventions
Development	The scripts/dev.sh task runner
Benchmarks	What the reference configurations score, and how to reproduce it

Capabilities

• Features — the full feature inventory.
• Benchmarks — published accuracy for each shipped dataset/topology reference configuration, with reproduction commands.
• Interpreter spine (Phase 1) — topology presets, neuron registry, NIR export/validation.
• Dual-mode introspection (Phase 2) — educational/production execution, trajectory metrics, surrogate curves.
• Dashboard (Phase 3) — panels, walkthroughs, and WebSocket actions.
• Event datasets (Phase 4) — N-MNIST, DVS, Tonic, and the event bridge.
• Targets and interoperability (Phase 5) — deployment targets, capability matrix, NIR round-trips.
• Production workflows (Phase 6) — manifests, model registry, scale-ups, benchmarks.
• Model hub (WS-A) — curated catalog, downloads, inspect → compat → promote.
• Backend execution (WS-B) — substitutions and the reference/Norse/Lava backends.
• Sequence primitives (WS-C) — per-stage neurons and attention presets.
• Streaming time series (UC-1) — windowing, a synthetic stream, train/eval, and bundle serving parity.
• Event runtime and energy (WS-D) — sparse runner and SOP/MAC/AC accounting.
• Operational maturity (WS-E) — persisted metrics, tracking sinks, determinism, docs site.
• Interop fold-ins (WS-F) — event training, ONNX bridge, nirtorch extraction, quantization.
• Model deployment: bundles and modules — bundling a checkpoint, running it headless, and installing it as a standalone command.

Honesty and limits

Read these before trusting a number:

• Implications and boundaries — the six cross-cutting limitations, why they exist, and what they imply.
• Notes — phase-specific limitations and caveats.

Related material

• Project rules — code style, hard limits, and design invariants.
• Cookbook — copy-pasteable recipes.
• Examples — fifteen runnable end-to-end scripts.
• Protocol contract — the WebSocket JSON Schema source of truth.
• Open-source checklist — pre-release readiness.
• plans/ — the ARCH-0001 repository-split design, roadmaps, and workstream plans; use that folder's index.md as its table of contents.