Metadata-Version: 2.4
Name: spikeforge
Version: 0.3.2
Summary: Spiking neural network trainer/experiments for MNIST built with snnTorch and PyTorch.
Author-email: Capsize LLC <contact@capsizegames.com>
Maintainer-email: Capsize LLC <contact@capsizegames.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/capsize-games/spikeforge
Project-URL: Repository, https://github.com/capsize-games/spikeforge
Keywords: spiking neural networks,snn,snntorch,pytorch,mnist
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.5
Requires-Dist: torchvision>=0.20
Requires-Dist: snntorch>=1.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: Pillow>=10.0
Requires-Dist: numpy>=1.26
Requires-Dist: psutil>=5.9
Provides-Extra: all
Requires-Dist: spikeforge-targets~=0.1.0; extra == "all"
Requires-Dist: spikeforge-hub~=0.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Requires-Dist: tomli; python_version < "3.11" and extra == "dev"
Provides-Extra: nir
Requires-Dist: nir>=1.0; extra == "nir"
Requires-Dist: nirtorch>=1.0; extra == "nir"
Provides-Extra: events
Requires-Dist: tonic>=1.4; extra == "events"
Provides-Extra: onnx
Requires-Dist: onnx>=1.14; extra == "onnx"
Requires-Dist: onnxruntime>=1.16; extra == "onnx"
Provides-Extra: tracking
Requires-Dist: tensorboard>=2.0; extra == "tracking"
Provides-Extra: tracking-wandb
Requires-Dist: wandb; extra == "tracking-wandb"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Dynamic: license-file

# spikeforge

[![CI](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml/badge.svg)](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml)
[![Discord](https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white)](https://capsizegames.com/discord)
[![Status: pre-1.0](https://img.shields.io/badge/status-pre--1.0-orange.svg)](OPEN_SOURCE_CHECKLIST.md)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
[![Docs](https://img.shields.io/badge/docs-long--form%20reference-blue.svg)](documentation/README.md)

![spikeforge dashboard](images/dashboard.png)

A spiking-neural-network (SNN) toolkit built on
[snnTorch](https://snntorch.readthedocs.io/) and PyTorch. Loads MNIST-style
and neuromorphic event datasets, encodes them into rate, latency, delta, and
random spikes, and trains, validates, exports, and deploys LIF networks —
with a live browser dashboard served over WebSockets.

> **Pre-1.0.** Before trusting any number this produces, read
> [Implications and boundaries](documentation/implications-and-boundaries.md).

## Quickstart

```bash
git clone https://github.com/capsize-games/spikeforge.git
cd spikeforge
docker compose up --build
```

Open <http://localhost:8877> — the dashboard connects to the WebSocket on
the same host and port. No separate backend or proxy to run.

Prefer a local install, a headless example, or the CLI tools instead? See
[Usage](documentation/usage.md) and [Quickstart](documentation/quickstart.md)
for every path (`./install.sh`, local dev with Vite, `examples/`, and the
eight `spikeforge-*` console scripts).

## Features

- **Encoding** — rate, latency, delta, and random spike coders.
- **Training** — fully-connected and convolutional LIF networks with
  surrogate-gradient cross-entropy, checkpointing, and opt-in AMP / gradient
  checkpointing / truncated BPTT / multi-GPU.
- **Topologies** — `fc_legacy`, `fc_small`, `conv_net`, `recurrent_net`, plus
  the sequence presets `sequence_mlp` and `sequence_attn`.
- **Datasets** — MNIST, Fashion-MNIST, KMNIST, QMNIST, USPS, EMNIST,
  CIFAR-10, and (via the `events` extra) N-MNIST, DVS128 Gesture,
  CIFAR10-DVS, and Spiking Speech Commands.
- **Interpreter spine** — NIR export, an independent NIR interpreter, and
  numerical drift validation.
- **Introspection** — educational-mode `U[t]`/`I[t]`/`S[t]` traces,
  trajectory metrics, and surrogate-derivative curves.
- **Deployment** — a capability matrix, weight quantization, energy
  accounting, and executable `reference`, `norse`, and `lava_loihi2`
  backends.
- **Model hub** — a curated, offline-first catalog plus optional live
  Hugging Face search.
- **Dashboard** — a React + TypeScript UI with training, introspection,
  analysis, targets, energy, and hub panels, and seven guided walkthroughs.

## Packages

This repository is a single workspace that publishes four distributions:

| Distribution | Import root | Purpose |
|---|---|---|
| `spikeforge` | `spikeforge` | Core package: encoders, topologies, training, simulator, NIR bridge, tracking |
| `spikeforge-targets` | `spikeforge_targets` | Deployment targets, quantization, energy accounting, sparse event runtime |
| `spikeforge-hub` | `spikeforge_hub` | Curated model hub and optional Hugging Face access |
| `spikeforge-server` | `server` | FastAPI + WebSocket server and dashboard hosting |

## Documentation

This README stays short on purpose.
[`documentation/`](documentation/README.md) is the full reference — install
paths, the CLI tools, architecture, module layout, and the dev workflow —
written for contributors and coding agents alike. Also see
[COOKBOOK.md](COOKBOOK.md) for copy-pasteable recipes,
[examples/](examples/) for runnable end-to-end scripts, and
[plans/](plans/) for design documents and the roadmap.

See [CONTRIBUTING.md](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
and [rules.md](rules.md) before opening a pull request.

## Citing

If spikeforge is useful in your research, please cite it — see
[CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository"
button from it automatically).

## License

Released under the **BSD 3-Clause License** — see [LICENSE](LICENSE) and
[AUTHORS](AUTHORS).
