spikeforge 0.3.2__tar.gz → 0.3.4__tar.gz

{spikeforge-0.3.2/spikeforge.egg-info → spikeforge-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spikeforge
-Version: 0.3.2
+Version: 0.3.4
 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>
@@ -77,6 +77,27 @@ with a live browser dashboard served over WebSockets.
 
 ## Quickstart
 
+No clone, no Docker — five lines of Python:
+
+```bash
+pip install spikeforge
+```
+
+```python
+from spikeforge.training.training_engine import TrainingEngine
+
+engine = TrainingEngine(dataset="mnist", hidden=32, epochs=1, num_steps=5)
+for metrics in engine.train():
+    last = metrics
+print(last)  # {'loss': ..., 'train_accuracy': ..., 'test_accuracy': ...}
+```
+
+The first run downloads MNIST; later runs are offline. That's the training
+API — `spikeforge-verify`, `spikeforge-benchmark`, and the NIR/deployment/
+energy pieces live in [Usage](documentation/usage.md).
+
+Want the live browser dashboard instead? That's the richer, second path:
+
 ```bash
 git clone https://github.com/capsize-games/spikeforge.git
 cd spikeforge
@@ -86,10 +107,40 @@ 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)
+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).
+`spikeforge-*` console scripts).
+
+## Why not just snnTorch, Norse, Lava, or SpikingJelly?
+
+spikeforge doesn't replace those — it trains through
+[snnTorch](https://snntorch.readthedocs.io/) and can deploy to Norse and
+Lava. The question is what it adds on top: a
+[NIR](https://github.com/neuromorphs/NIR)-described interpreter spine with
+an *independent* interpreter that re-executes every exported graph and
+reports numerical drift against the original model (not just export —
+snnTorch and Norse both export NIR too; Lava-DL currently only reads it,
+not writes it), a deployment-capability
+matrix that reports per-target op support and availability instead of just
+declaring support, an event-driven energy estimator, and a live training/
+introspection dashboard. None of the other libraries ship the latter two as
+part of the library itself, to our knowledge — file an issue if that's
+stale.
+
+| | snnTorch | Norse | Lava | SpikingJelly | spikeforge |
+|---|---|---|---|---|---|
+| Surrogate-gradient training in PyTorch | ✅ | ✅ | ✅ (Lava-DL) | ✅ | ✅ (via snnTorch) |
+| NIR export (write) | ✅ | ✅ | import-only (Lava-DL reads NIR, doesn't write it) | not part of NIR's official framework list | ✅ |
+| Independent re-execution + drift check of the exported graph | — | — | — | — | ✅ |
+| Per-target deployment capability matrix (op support, honest availability) | — | — | Loihi-focused | — | ✅ (reference/Norse/Lava/SpiNNaker2/Speck/Xylo) |
+| Built-in event-driven energy estimator (SOP/MAC/AC) | — | — | — | — | ✅ (labelled `estimate`, not hardware-measured) |
+| Pretrained model zoo | — | — | — | ✅ (some vision tasks) | catalog infra ships; mostly untrained preset shapes today ([details](spikeforge_hub/models.json)) |
+| Live browser training/introspection dashboard | — | — | — | — | ✅ |
+
+If you already have a training loop in snnTorch/Norse/Lava/SpikingJelly and
+don't need interop, deployment reporting, energy estimates, or the
+dashboard, you may not need spikeforge on top of it — that's a fair
+"obviously no," and better than an uninformed "obviously yes."
 
 ## Features
 
@@ -114,9 +165,31 @@ eight `spikeforge-*` console scripts).
 - **Dashboard** — a React + TypeScript UI with training, introspection,
   analysis, targets, energy, and hub panels, and seven guided walkthroughs.
 
+## What's implemented vs. experimental vs. spec-only
+
+The features list above spans very different levels of maturity. This is
+the ten-second version; each row links to the honest detail.
+
+| Capability | Status | Detail |
+|---|---|---|
+| Training, encoding, topologies, checkpointing | Shipped | [Features](documentation/features.md) |
+| NIR export + independent-interpreter drift validation | Shipped | [Interpreter spine](documentation/interpreter-spine.md) |
+| Deployment — `reference` target | Shipped, always available | [Backend execution](documentation/backend-execution.md) |
+| Deployment — `norse`, `lava_loihi2` targets | Shipped, gated on an SDK extra (`pip install spikeforge-targets[norse]` or `[lava]`) | [Targets and interop](documentation/targets-and-interop.md) |
+| Deployment — `spinnaker2`, `speck`, `xylo` targets | Spec-only — registered in the capability matrix, no installable SDK integration yet | [Targets and interop](documentation/targets-and-interop.md) |
+| Energy accounting (SOP/MAC/AC) | Shipped as an explicit `estimate`, not hardware-measured | [Event runtime and energy](documentation/event-runtime-and-energy.md) |
+| Model hub catalog, CLI, dashboard panel, opt-in live HF search | Shipped | [Model hub](documentation/model-hub.md) |
+| Model hub catalog *content* | Thin — bundled NIR shapes today, not trained weights | [`spikeforge_hub/models.json`](spikeforge_hub/models.json) |
+| Sequence/attention topologies (`sequence_mlp`, `sequence_attn`) | Experimental — research scope, not production sequence training | [Sequence primitives](documentation/sequence-primitives.md) |
+| ONNX interop | Shipped, single-step export/import only | [Interop fold-ins](documentation/interop-foldins.md) |
+| Production use-case toolkit: streaming time-series (UC-1) | Shipped | [UC-1](plans/use_case_streaming_timeseries.md) |
+| Production use-case toolkit: UC-2 through UC-10 | Spec-only (design docs behind issues #13–#21) | [plans/index.md](plans/index.md#production-use-cases-pc-0) |
+| Live browser dashboard | Shipped | [Dashboard](documentation/dashboard.md) |
+
 ## Packages
 
-This repository is a single workspace that publishes four distributions:
+This repository is a single workspace that publishes seven distributions,
+each versioned independently:
 
 | Distribution | Import root | Purpose |
 |---|---|---|
@@ -124,11 +197,20 @@ This repository is a single workspace that publishes four distributions:
 | `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 |
+| `spikeforge-serve` | `spikeforge_serve` | Headless REST/WebSocket inference service for a deployment bundle |
+| `spikeforge-clients` | `spikeforge_clients` | Python/TypeScript/CLI clients for `spikeforge-serve` (no torch dependency) |
+| `spikeforge-io` | `spikeforge_io` | Recorded-stream I/O adapters and windowing |
+
+`spikeforge-hub` and `spikeforge-targets` sit at `0.1.x` while core is at
+`0.3.x` by design, not neglect — each package is versioned independently, and
+[`compatibility.json`](compatibility.json) is the source of truth for which
+satellite versions go with which core release. If you're pinning versions by
+hand, read that file rather than assuming semver alignment across packages.
 
 ## Documentation
 
-This README stays short on purpose.
-[`documentation/`](documentation/README.md) is the full reference — install
+This README covers first contact and positioning; it deliberately doesn't
+go deeper. [`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,

spikeforge-0.3.4/README.md

@@ -0,0 +1,177 @@
+# 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
+
+No clone, no Docker — five lines of Python:
+
+```bash
+pip install spikeforge
+```
+
+```python
+from spikeforge.training.training_engine import TrainingEngine
+
+engine = TrainingEngine(dataset="mnist", hidden=32, epochs=1, num_steps=5)
+for metrics in engine.train():
+    last = metrics
+print(last)  # {'loss': ..., 'train_accuracy': ..., 'test_accuracy': ...}
+```
+
+The first run downloads MNIST; later runs are offline. That's the training
+API — `spikeforge-verify`, `spikeforge-benchmark`, and the NIR/deployment/
+energy pieces live in [Usage](documentation/usage.md).
+
+Want the live browser dashboard instead? That's the richer, second path:
+
+```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.
+
+See [Usage](documentation/usage.md) and [Quickstart](documentation/quickstart.md)
+for every path (`./install.sh`, local dev with Vite, `examples/`, and the
+`spikeforge-*` console scripts).
+
+## Why not just snnTorch, Norse, Lava, or SpikingJelly?
+
+spikeforge doesn't replace those — it trains through
+[snnTorch](https://snntorch.readthedocs.io/) and can deploy to Norse and
+Lava. The question is what it adds on top: a
+[NIR](https://github.com/neuromorphs/NIR)-described interpreter spine with
+an *independent* interpreter that re-executes every exported graph and
+reports numerical drift against the original model (not just export —
+snnTorch and Norse both export NIR too; Lava-DL currently only reads it,
+not writes it), a deployment-capability
+matrix that reports per-target op support and availability instead of just
+declaring support, an event-driven energy estimator, and a live training/
+introspection dashboard. None of the other libraries ship the latter two as
+part of the library itself, to our knowledge — file an issue if that's
+stale.
+
+| | snnTorch | Norse | Lava | SpikingJelly | spikeforge |
+|---|---|---|---|---|---|
+| Surrogate-gradient training in PyTorch | ✅ | ✅ | ✅ (Lava-DL) | ✅ | ✅ (via snnTorch) |
+| NIR export (write) | ✅ | ✅ | import-only (Lava-DL reads NIR, doesn't write it) | not part of NIR's official framework list | ✅ |
+| Independent re-execution + drift check of the exported graph | — | — | — | — | ✅ |
+| Per-target deployment capability matrix (op support, honest availability) | — | — | Loihi-focused | — | ✅ (reference/Norse/Lava/SpiNNaker2/Speck/Xylo) |
+| Built-in event-driven energy estimator (SOP/MAC/AC) | — | — | — | — | ✅ (labelled `estimate`, not hardware-measured) |
+| Pretrained model zoo | — | — | — | ✅ (some vision tasks) | catalog infra ships; mostly untrained preset shapes today ([details](spikeforge_hub/models.json)) |
+| Live browser training/introspection dashboard | — | — | — | — | ✅ |
+
+If you already have a training loop in snnTorch/Norse/Lava/SpikingJelly and
+don't need interop, deployment reporting, energy estimates, or the
+dashboard, you may not need spikeforge on top of it — that's a fair
+"obviously no," and better than an uninformed "obviously yes."
+
+## 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.
+
+## What's implemented vs. experimental vs. spec-only
+
+The features list above spans very different levels of maturity. This is
+the ten-second version; each row links to the honest detail.
+
+| Capability | Status | Detail |
+|---|---|---|
+| Training, encoding, topologies, checkpointing | Shipped | [Features](documentation/features.md) |
+| NIR export + independent-interpreter drift validation | Shipped | [Interpreter spine](documentation/interpreter-spine.md) |
+| Deployment — `reference` target | Shipped, always available | [Backend execution](documentation/backend-execution.md) |
+| Deployment — `norse`, `lava_loihi2` targets | Shipped, gated on an SDK extra (`pip install spikeforge-targets[norse]` or `[lava]`) | [Targets and interop](documentation/targets-and-interop.md) |
+| Deployment — `spinnaker2`, `speck`, `xylo` targets | Spec-only — registered in the capability matrix, no installable SDK integration yet | [Targets and interop](documentation/targets-and-interop.md) |
+| Energy accounting (SOP/MAC/AC) | Shipped as an explicit `estimate`, not hardware-measured | [Event runtime and energy](documentation/event-runtime-and-energy.md) |
+| Model hub catalog, CLI, dashboard panel, opt-in live HF search | Shipped | [Model hub](documentation/model-hub.md) |
+| Model hub catalog *content* | Thin — bundled NIR shapes today, not trained weights | [`spikeforge_hub/models.json`](spikeforge_hub/models.json) |
+| Sequence/attention topologies (`sequence_mlp`, `sequence_attn`) | Experimental — research scope, not production sequence training | [Sequence primitives](documentation/sequence-primitives.md) |
+| ONNX interop | Shipped, single-step export/import only | [Interop fold-ins](documentation/interop-foldins.md) |
+| Production use-case toolkit: streaming time-series (UC-1) | Shipped | [UC-1](plans/use_case_streaming_timeseries.md) |
+| Production use-case toolkit: UC-2 through UC-10 | Spec-only (design docs behind issues #13–#21) | [plans/index.md](plans/index.md#production-use-cases-pc-0) |
+| Live browser dashboard | Shipped | [Dashboard](documentation/dashboard.md) |
+
+## Packages
+
+This repository is a single workspace that publishes seven distributions,
+each versioned independently:
+
+| 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 |
+| `spikeforge-serve` | `spikeforge_serve` | Headless REST/WebSocket inference service for a deployment bundle |
+| `spikeforge-clients` | `spikeforge_clients` | Python/TypeScript/CLI clients for `spikeforge-serve` (no torch dependency) |
+| `spikeforge-io` | `spikeforge_io` | Recorded-stream I/O adapters and windowing |
+
+`spikeforge-hub` and `spikeforge-targets` sit at `0.1.x` while core is at
+`0.3.x` by design, not neglect — each package is versioned independently, and
+[`compatibility.json`](compatibility.json) is the source of truth for which
+satellite versions go with which core release. If you're pinning versions by
+hand, read that file rather than assuming semver alignment across packages.
+
+## Documentation
+
+This README covers first contact and positioning; it deliberately doesn't
+go deeper. [`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).

spikeforge-0.3.4/main.py

@@ -0,0 +1,48 @@
+"""Entry point: train a rate-coded MNIST subset and export all visuals."""
+
+import argparse
+from typing import List, Optional
+
+
+def _parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the ``spikeforge`` demo CLI."""
+    return argparse.ArgumentParser(
+        prog="spikeforge",
+        description=(
+            "Train a rate-coded MNIST subset with snnTorch and export "
+            "every tutorial visual (video, GIFs, raster, reconstruction) "
+            "to build/. Downloads MNIST on first run; this is the "
+            "tutorial demo, not a general-purpose training CLI -- see "
+            "spikeforge-verify, spikeforge-benchmark, and "
+            "documentation/usage.md for the rest of the toolkit."
+        ),
+    )
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Parse ``argv``, then build the trainer and write every output."""
+    _parser().parse_args(argv)
+
+    # Imported lazily so ``--help`` never pays for (or fails on) the heavy
+    # snnTorch/matplotlib export stack before argparse has even run.
+    from spikeforge.exporters.presentation_exporter import (
+        PresentationGifExporter,
+    )
+    from spikeforge.exporters.raster_exporter import RasterExporter
+    from spikeforge.exporters.reconstruction_exporter import (
+        ReconstructionExporter,
+    )
+    from spikeforge.exporters.spike_gif_exporter import SpikeGifExporter
+    from spikeforge.exporters.video_exporter import VideoExporter
+    from spikeforge.training.logger import SNNTrainerLogger
+
+    trainer = SNNTrainerLogger(animation_interval=100)
+    VideoExporter(trainer).export()
+    SpikeGifExporter(trainer).export()
+    ReconstructionExporter(trainer).export()
+    RasterExporter(trainer).export()
+    PresentationGifExporter(trainer).export()
+
+
+if __name__ == "__main__":
+    main()

spikeforge-0.3.4/main_encodings.py

@@ -0,0 +1,62 @@
+"""Run the additional tutorial-1 encoding demos (latency/delta/random).
+
+Produces latency curve + rasters + animation, delta plots, and random
+spike visuals under build/.
+"""
+
+import argparse
+from typing import List, Optional
+
+
+def _parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the ``spikeforge-encodings`` CLI."""
+    return argparse.ArgumentParser(
+        prog="spikeforge-encodings",
+        description=(
+            "Train the latency/delta/random tutorial encoders and export "
+            "their visuals to build/. Downloads MNIST on first run; this "
+            "is the tutorial demo, not a general-purpose encoding CLI."
+        ),
+    )
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Parse ``argv``, then train the encoders and export their visuals."""
+    _parser().parse_args(argv)
+
+    # Imported lazily so ``--help`` never pays for (or fails on) the heavy
+    # snnTorch/matplotlib export stack before argparse has even run.
+    from spikeforge.encoding.delta_trainer import DeltaTrainer
+    from spikeforge.encoding.latency_trainer import LatencyTrainer
+    from spikeforge.encoding.random_spikegen import RandomSpikeGenerator
+    from spikeforge.exporters.delta_exporter import DeltaPlotExporter
+    from spikeforge.exporters.latency_curve_exporter import (
+        LatencyCurveExporter,
+    )
+    from spikeforge.exporters.latency_raster_exporter import (
+        LatencyRasterExporter,
+    )
+    from spikeforge.exporters.latency_video_exporter import (
+        LatencyVideoExporter,
+    )
+    from spikeforge.exporters.random_spike_raster_exporter import (
+        RandomSpikeRasterExporter,
+    )
+    from spikeforge.exporters.random_spike_video_exporter import (
+        RandomSpikeVideoExporter,
+    )
+
+    latency_trainer = LatencyTrainer(animation_interval=100)
+    LatencyCurveExporter(latency_trainer).export()
+    LatencyRasterExporter(latency_trainer).export()
+    LatencyVideoExporter(latency_trainer).export(key="clip")
+
+    DeltaPlotExporter(DeltaTrainer()).export()
+
+    random_spikegen = RandomSpikeGenerator(num_steps=100)
+    RandomSpikeRasterExporter(random_spikegen).export()
+    RandomSpikeVideoExporter(random_spikegen).export()
+
+
+if __name__ == "__main__":
+    main()

{spikeforge-0.3.2 → spikeforge-0.3.4}/pyproject.toml

@@ -15,7 +15,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spikeforge"
-version = "0.3.2"
+version = "0.3.4"
 description = "Spiking neural network trainer/experiments for MNIST built with snnTorch and PyTorch."
 # ``README.md`` and ``LICENSE`` are committed symlinks to the repository-root
 # files: the distribution metadata points at the root documents while

{spikeforge-0.3.2 → spikeforge-0.3.4}/spikeforge/__init__.py

@@ -7,10 +7,10 @@ from spikeforge.encoding.latency_trainer import (
 )
 from spikeforge.encoding.random_spikegen import RandomSpikeGenerator
 from spikeforge.training.logger import SNNTrainerLogger
-from spikeforge.training.trainer import SSNTrainer
+from spikeforge.training.trainer import SNNTrainer
 
 __all__ = [
-    "SSNTrainer",
+    "SNNTrainer",
     "SNNTrainerLogger",
     "LatencyTrainer",
     "DeltaTrainer",

spikeforge-0.3.4/spikeforge/affect/__init__.py

@@ -0,0 +1,5 @@
+"""SNN-native internal affect regulation primitives."""
+
+from spikeforge.affect.regulator import AffectiveOutput, AffectiveRegulator
+
+__all__ = ["AffectiveOutput", "AffectiveRegulator"]

spikeforge-0.3.4/spikeforge/affect/regulator.py

@@ -0,0 +1,77 @@
+"""Slow recurrent spiking state for downstream gain modulation."""
+
+from typing import NamedTuple, Optional
+
+import snntorch as snn
+import torch
+from torch import nn
+
+
+class AffectiveOutput(NamedTuple):
+    """One regulator step's spikes and continuous broadcast signal."""
+
+    spikes: torch.Tensor
+    broadcast: torch.Tensor
+
+
+class AffectiveRegulator(nn.Module):
+    """Integrate inputs into a slowly decaying SNN-native affect state.
+
+    The linear projection turns signals such as novelty or confidence into
+    currents. A recurrent LIF membrane integrates those currents and is
+    exposed as the continuous ``broadcast`` signal; spikes are provided for
+    consumers that want an event-native modulation path.
+    """
+
+    def __init__(
+        self,
+        input_size: int,
+        state_size: int = 2,
+        beta: float = 0.98,
+        threshold: float = 1.0,
+        device: Optional[torch.device] = None,
+    ) -> None:
+        """Create a regulator with a persistent state per batch item."""
+        super().__init__()
+        if input_size < 1 or state_size < 1:
+            raise ValueError("input_size and state_size must be positive")
+        if not 0.0 < beta < 1.0:
+            raise ValueError("beta must be between 0 and 1")
+        self.projection = nn.Linear(
+            input_size, state_size, bias=False, device=device,
+        )
+        self.neuron = snn.Leaky(
+            beta=beta,
+            threshold=threshold,
+            reset_mechanism="subtract",
+        ).to(device)
+        self._mem: Optional[torch.Tensor] = None
+
+    @property
+    def state_size(self) -> int:
+        """Return the number of broadcast channels."""
+        return self.projection.out_features
+
+    def reset_state(self, batch_size: int = 1) -> None:
+        """Clear the carried state before a new sequence."""
+        if batch_size < 1:
+            raise ValueError("batch_size must be positive")
+        device = self.projection.weight.device
+        self._mem = torch.zeros(batch_size, self.state_size, device=device)
+
+    def step(self, inputs: torch.Tensor) -> AffectiveOutput:
+        """Advance the regulator for inputs shaped ``[B, input_size]``."""
+        if inputs.ndim != 2 or inputs.size(1) != self.projection.in_features:
+            raise ValueError(
+                "inputs must have shape [B, input_size]"
+            )
+        batch_size = inputs.size(0)
+        if self._mem is None or self._mem.size(0) != batch_size:
+            self.reset_state(batch_size)
+        current = self.projection(inputs)
+        spikes, self._mem = self.neuron(current, self._mem)
+        return AffectiveOutput(spikes=spikes, broadcast=self._mem)
+
+    def forward(self, inputs: torch.Tensor) -> AffectiveOutput:
+        """Alias :meth:`step` for ordinary ``nn.Module`` use."""
+        return self.step(inputs)

{spikeforge-0.3.2 → spikeforge-0.3.4}/spikeforge/benchmark/energy.py

@@ -10,20 +10,28 @@ from typing import Any, Dict, Optional
 import torch
 
 from spikeforge.benchmark.config import BenchmarkConfig
+from spikeforge.targets_extra import require as require_targets
 from spikeforge.topology.stage_module import StageModule
-from spikeforge_targets.energy.accounting import account
-from spikeforge_targets.event_runtime.sparse_runner import sparse_run
 
 
 def energy_block(
     module: StageModule, spikes: torch.Tensor, config: BenchmarkConfig
 ) -> Optional[Dict[str, Any]]:
-    """Return the opt-in event-driven energy estimate, or None."""
+    """Return the opt-in event-driven energy estimate, or None.
+
+    ``spikeforge-targets`` is only imported here, once energy accounting is
+    actually requested, so a plain ``spikeforge`` install keeps every other
+    benchmark path working.
+    """
     if not config.energy:
         return None
+    accounting = require_targets("spikeforge_targets.energy.accounting")
+    sparse_runner = require_targets(
+        "spikeforge_targets.event_runtime.sparse_runner"
+    )
     with torch.no_grad():
-        result = sparse_run(module, spikes)
-    report = account(result, config.energy_target)
+        result = sparse_runner.sparse_run(module, spikes)
+    report = accounting.account(result, config.energy_target)
     return {
         "report": report.to_dict(),
         "counts": dict(result.counts),

{spikeforge-0.3.2 → spikeforge-0.3.4}/spikeforge/benchmark/memory.py

@@ -4,10 +4,14 @@ Every probe returns ``None`` when its metric is unavailable on this platform,
 so a benchmark degrades to skipping rather than failing.
 """
 
-import resource
 import tracemalloc
 from typing import Any, Callable, Dict, Optional
 
+try:
+    import resource
+except ImportError:  # Windows does not provide the POSIX resource module.
+    resource = None
+
 import torch
 
 
@@ -26,6 +30,8 @@ def cuda_peak_bytes(device: Any) -> Optional[int]:
 
 def process_rss_bytes() -> Optional[int]:
     """Return the process peak resident set size in bytes, or None."""
+    if resource is None:
+        return None
     try:
         usage = resource.getrusage(resource.RUSAGE_SELF)
     except (ValueError, OSError):

{spikeforge-0.3.2 → spikeforge-0.3.4}/spikeforge/cli/verify.py

@@ -5,9 +5,15 @@ Run as ``python -m spikeforge.cli.verify export --topology conv_net`` or
 ``validate`` command exits non-zero when the report falls outside tolerance,
 so it works as a CI gate. The deployment subcommands (``targets``, ``deploy``,
 ``roundtrip``, ``ingest``) are registered from
-:mod:`spikeforge_targets.cli.target_cli`, and the
-checkpoint-tracking subcommands (``records list|diff|manifest``) from
-:mod:`.records_cli`.
+:mod:`spikeforge_targets.cli.target_cli` when that optional package is
+installed, and the checkpoint-tracking subcommands (``records
+list|diff|manifest``) from :mod:`.records_cli`.
+
+``spikeforge-targets`` is not a hard dependency of the core distribution, so
+this module imports it defensively: without it, ``--help`` and the
+``export``/``validate``/``records``/``onnx-*`` subcommands still work, and
+the deployment subcommands are simply absent from the subcommand list (the
+``--help`` description names the install that brings them back).
 """
 
 import argparse
@@ -30,7 +36,11 @@ from spikeforge.topology import registry
 from spikeforge.topology.registry import build_topology
 from spikeforge.topology.spec import TopologySpec
 from spikeforge.topology.stage_module import StageModule
-from spikeforge_targets.cli import target_cli
+
+try:
+    from spikeforge_targets.cli import target_cli
+except ImportError:
+    target_cli = None
 
 _Input = Tuple[TopologySpec, StageModule, torch.Tensor]
 
@@ -124,9 +134,15 @@ def _run_validate(args: argparse.Namespace) -> int:
 
 def _parser() -> argparse.ArgumentParser:
     """Return the argument parser for the verify CLI."""
+    description = "Export and validate topology NIR graphs."
+    if target_cli is None:
+        description += (
+            " (deployment subcommands -- targets, deploy, roundtrip, "
+            "test-deploy, ingest -- need: pip install spikeforge-targets)"
+        )
     parser = argparse.ArgumentParser(
         prog="spikeforge-verify",
-        description="Export and validate topology NIR graphs.",
+        description=description,
     )
     subs = parser.add_subparsers(dest="command", required=True)
     export = subs.add_parser("export", help="export a topology to NIR")
@@ -140,7 +156,8 @@ def _parser() -> argparse.ArgumentParser:
     check.add_argument("--steps", type=int, default=10)
     check.add_argument("--seed", type=int, default=0)
     check.set_defaults(handler=_run_validate)
-    target_cli.add_subcommands(subs)
+    if target_cli is not None:
+        target_cli.add_subcommands(subs)
     records_cli.add_subcommands(subs)
     onnx_cli.add_subcommands(subs)
     return parser