spikeforge-io 0.1.0__py3-none-any.whl

spikeforge_io/__init__.py

@@ -0,0 +1,88 @@
+"""``spikeforge-io``: dependency-light I/O adapters and the windowing surface.
+
+PT-W7's second deliverable. The distribution is deliberately thin: it adapts a
+recorded numeric source (CSV, JSON, NPY, in-memory, or any object implementing
+the dataset hook) into the core frozen window/normalize/encode contract, and
+replays it into ``spikeforge-serve``'s ``/v1/stream``.
+
+The windowing *implementation* stays in core
+(:mod:`spikeforge.streaming.window_spec`) because core must never depend on a
+satellite; :mod:`spikeforge_io.windowing` re-exports that one canonical
+contract. No pandas, no fastapi, no client SDK is imported here.
+
+    from spikeforge_io import CsvAdapter, replay_to_stream
+
+    adapter = CsvAdapter("recording.csv")
+    frames = adapter.stream()          # [N, D]
+    windows = adapter.windows(spec)    # [W, L, D], z-scored by the frozen spec
+"""
+
+from spikeforge_io.adapters import (
+    DATASET_METHODS,
+    FACTORIES,
+    CsvAdapter,
+    DatasetAdapter,
+    InMemoryAdapter,
+    JsonAdapter,
+    NpyAdapter,
+    StreamAdapter,
+    adapter_for,
+    as_stream,
+)
+from spikeforge_io.errors import (
+    AdapterDependencyError,
+    AdapterError,
+    AdapterFormatError,
+    AdapterShapeError,
+    AdapterUnsupportedError,
+    IoError,
+)
+from spikeforge_io.replay import (
+    ReplayReport,
+    replay,
+    replay_to_stream,
+    stream_messages,
+)
+from spikeforge_io.windowing import (
+    WINDOW_SPEC_VERSION,
+    WindowSpec,
+    delta_over_window,
+    encode_windows,
+    fit_window_spec,
+    normalize_windows,
+    window_spec_from_bundle,
+    window_stream,
+    windows,
+)
+
+__all__ = [
+    "DATASET_METHODS",
+    "FACTORIES",
+    "WINDOW_SPEC_VERSION",
+    "AdapterDependencyError",
+    "AdapterError",
+    "AdapterFormatError",
+    "AdapterShapeError",
+    "AdapterUnsupportedError",
+    "CsvAdapter",
+    "DatasetAdapter",
+    "InMemoryAdapter",
+    "IoError",
+    "JsonAdapter",
+    "NpyAdapter",
+    "ReplayReport",
+    "StreamAdapter",
+    "WindowSpec",
+    "adapter_for",
+    "as_stream",
+    "delta_over_window",
+    "encode_windows",
+    "fit_window_spec",
+    "normalize_windows",
+    "replay",
+    "replay_to_stream",
+    "stream_messages",
+    "window_spec_from_bundle",
+    "window_stream",
+    "windows",
+]

spikeforge_io/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m spikeforge_io`` entry point for the I/O CLI."""
+
+from spikeforge_io.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spikeforge_io/adapters.py

@@ -0,0 +1,320 @@
+"""Dependency-light adapters for ingesting numeric streams into the contract.
+
+Every adapter answers one question — "what is this recorded source, as an
+``[N, D]`` numeric stream?" — and nothing more. Windowing, normalization, and
+encoding are then the shared core contract (see
+:mod:`spikeforge_io.windowing`), so an adapter can never invent its own
+preprocessing. Only the standard library and torch are used for CSV/JSON and
+in-memory data; numpy is imported lazily and only for ``.npy``, and its absence
+is a typed :class:`~spikeforge_io.errors.AdapterDependencyError` rather than an
+``ImportError`` at the call site.
+
+The dataset-adapter **hook** (:class:`DatasetAdapter`) is deliberately
+duck-typed: any object exposing ``to_tensor()``/``array()`` or the sequence
+protocol (``__len__`` + ``__getitem__``) adapts, so a future dataset lib can
+join without this module depending on it.
+"""
+
+import csv
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+import torch
+
+from spikeforge_io.errors import (
+    AdapterDependencyError,
+    AdapterFormatError,
+    AdapterShapeError,
+    AdapterUnsupportedError,
+)
+
+#: Methods the dataset-adapter hook recognises, in probing order.
+DATASET_METHODS: Tuple[str, ...] = ("to_tensor", "array", "numpy")
+
+#: Keys a JSON object may use to carry the stream payload.
+JSON_KEYS: Tuple[str, ...] = ("data", "stream", "values")
+
+
+def as_stream(payload: Any, source: str) -> torch.Tensor:
+    """Return ``payload`` as an ``[N, D]`` float32 tensor, or a typed error.
+
+    A 1-D payload is promoted to a single channel; a 2-D payload is taken as
+    ``[N, D]``; anything else is refused with
+    :class:`~spikeforge_io.errors.AdapterShapeError`. A non-numeric payload is
+    a :class:`~spikeforge_io.errors.AdapterFormatError`.
+    """
+    try:
+        tensor = torch.as_tensor(payload, dtype=torch.float32)
+    except (TypeError, ValueError) as error:
+        raise AdapterFormatError(
+            source, f"stream is not numeric: {error}"
+        ) from None
+    if tensor.dim() == 0:
+        return tensor.reshape(1, 1)
+    if tensor.dim() == 1:
+        return tensor.unsqueeze(-1)
+    if tensor.dim() != 2:
+        raise AdapterShapeError(
+            source, f"a stream must be 1-D or 2-D, got {tuple(tensor.shape)}"
+        )
+    return tensor
+
+
+class StreamAdapter(ABC):
+    """Base class for every recorded-stream adapter.
+
+    Subclasses implement :meth:`stream`; :meth:`windows` and :meth:`encoded`
+    are provided here so windowing/encoding always flow through the one core
+    contract.
+    """
+
+    #: Human-readable source label used in error messages.
+    source: str = "<adapter>"
+
+    @abstractmethod
+    def stream(self) -> torch.Tensor:
+        """Return the source as a ``[N, D]`` float32 tensor."""
+
+    def windows(self, spec: Any) -> torch.Tensor:
+        """Return the z-scored ``[W, L, D]`` windows of :meth:`stream`."""
+        spec.validate()
+        return spec.windows(self.stream())
+
+    def encoded(
+        self, spec: Any, encode_spec: Any, **kwargs: Any
+    ) -> torch.Tensor:
+        """Return windows encoded with the shared window->spike contract."""
+        from spikeforge_io.windowing import encode_windows
+
+        return encode_windows(self.windows(spec), encode_spec, **kwargs)
+
+    def __len__(self) -> int:
+        """Return the number of samples in the stream."""
+        return int(self.stream().size(0))
+
+
+class InMemoryAdapter(StreamAdapter):
+    """Adapt an already-materialized payload (tensor, nested list, ndarray)."""
+
+    def __init__(self, payload: Any, source: str = "<memory>") -> None:
+        """Wrap ``payload`` and label it with ``source``."""
+        self._payload = payload
+        self.source = source
+
+    def stream(self) -> torch.Tensor:
+        """Return the payload as a ``[N, D]`` tensor."""
+        return as_stream(self._payload, self.source)
+
+
+def _read_rows(path: str, delimiter: str) -> List[List[str]]:
+    """Read a CSV file into raw rows, or raise a typed format error."""
+    try:
+        with open(path, newline="", encoding="utf-8") as handle:
+            return list(csv.reader(handle, delimiter=delimiter))
+    except OSError as error:
+        raise AdapterFormatError(path, f"cannot read: {error}") from None
+
+
+def _parse_csv_row(path: str, index: int, row: Sequence[str]) -> List[float]:
+    """Parse one CSV row into floats, naming the first bad field."""
+    values: List[float] = []
+    for column, cell in enumerate(row):
+        text = cell.strip()
+        if not text:
+            continue
+        try:
+            values.append(float(text))
+        except ValueError:
+            raise AdapterFormatError(
+                path,
+                f"row {index} column {column} is not numeric: {cell!r}",
+                position=index,
+            ) from None
+    if not values:
+        raise AdapterFormatError(
+            path, f"row {index} has no numeric fields", position=index
+        )
+    return values
+
+
+class CsvAdapter(StreamAdapter):
+    """Read a ``.csv`` file of numeric rows into an ``[N, D]`` stream."""
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        delimiter: str = ",",
+        has_header: bool = True,
+        channels: Optional[int] = None,
+    ) -> None:
+        """Record the ``path``, delimiter, header flag, and expected width."""
+        self.source = path
+        self._delimiter = delimiter
+        self._has_header = has_header
+        self._channels = channels
+
+    def stream(self) -> torch.Tensor:
+        """Return the CSV's numeric rows as a ``[N, D]`` tensor."""
+        rows = _read_rows(self.source, self._delimiter)
+        if self._has_header and rows:
+            rows = rows[1:]
+        if not rows:
+            raise AdapterShapeError(self.source, "CSV has no data rows")
+        parsed = [
+            _parse_csv_row(self.source, index, row)
+            for index, row in enumerate(rows)
+        ]
+        width = len(parsed[0])
+        for index, row in enumerate(parsed):
+            if len(row) != width:
+                raise AdapterFormatError(
+                    self.source,
+                    f"row {index} has {len(row)} fields, expected {width}",
+                    position=index,
+                )
+        if self._channels is not None and width != self._channels:
+            raise AdapterShapeError(
+                self.source,
+                f"expected {self._channels} channels, got {width}",
+            )
+        return as_stream(parsed, self.source)
+
+
+def _json_payload(payload: Any, path: str) -> Any:
+    """Return the stream payload inside a JSON document to adapt."""
+    if isinstance(payload, dict):
+        for key in (JSON_KEYS + ("payload",)):
+            if key in payload:
+                return payload[key]
+        raise AdapterFormatError(
+            path, f"JSON object has no stream key ({', '.join(JSON_KEYS)})"
+        )
+    return payload
+
+
+class JsonAdapter(StreamAdapter):
+    """Read a ``.json`` file (rows, scalars, or an object) as a stream."""
+
+    def __init__(self, path: str, *, key: Optional[str] = None) -> None:
+        """Record the ``path`` and an optional explicit object ``key``."""
+        self.source = path
+        self._key = key
+
+    def _load(self) -> Any:
+        """Return the raw JSON payload, or raise a typed format error."""
+        try:
+            with open(self.source, encoding="utf-8") as handle:
+                return json.load(handle)
+        except OSError as error:
+            raise AdapterFormatError(
+                self.source, f"cannot read: {error}"
+            ) from None
+        except json.JSONDecodeError as error:
+            raise AdapterFormatError(
+                self.source, f"malformed JSON: {error}"
+            ) from None
+
+    def stream(self) -> torch.Tensor:
+        """Return the JSON stream as a ``[N, D]`` tensor."""
+        payload = self._load()
+        if self._key is not None:
+            if not isinstance(payload, dict) or self._key not in payload:
+                raise AdapterFormatError(
+                    self.source, f"JSON object has no {self._key!r} key"
+                )
+            payload = payload[self._key]
+        else:
+            payload = _json_payload(payload, self.source)
+        try:
+            return as_stream(payload, self.source)
+        except AdapterFormatError as error:
+            raise AdapterFormatError(
+                self.source, f"JSON rows are not rectangular: {error.detail}"
+            ) from None
+
+
+class NpyAdapter(StreamAdapter):
+    """Read a ``.npy`` array into an ``[N, D]`` stream via numpy."""
+
+    def __init__(self, path: str) -> None:
+        """Record the ``path`` to the ``.npy`` file."""
+        self.source = path
+
+    def stream(self) -> torch.Tensor:
+        """Return the array as a ``[N, D]`` tensor, or report numpy absent."""
+        try:
+            import numpy as np
+        except ImportError:
+            raise AdapterDependencyError("numpy", "a .npy stream") from None
+        try:
+            payload = np.load(self.source, allow_pickle=False)
+        except (OSError, ValueError) as error:
+            raise AdapterFormatError(
+                self.source, f"cannot read .npy: {error}"
+            ) from None
+        return as_stream(payload, self.source)
+
+
+class DatasetAdapter(StreamAdapter):
+    """Adapt any object implementing the documented dataset hook.
+
+    The hook is intentionally tiny and library-agnostic: an object is adapt-
+    able when it exposes ``to_tensor()`` (or ``array()``/``numpy()``) returning
+    an array-like, **or** when it supports the sequence protocol
+    (``__len__`` + ``__getitem__``). This is the seam a future dataset
+    distribution plugs into without ``spikeforge-io`` importing it.
+    """
+
+    def __init__(self, dataset: Any, source: Optional[str] = None) -> None:
+        """Wrap ``dataset`` and label it with ``source`` or its type name."""
+        self._dataset = dataset
+        self.source = source or type(dataset).__name__
+
+    def _payload(self) -> Any:
+        """Return the array-like the dataset exposes, or a typed refusal."""
+        for name in DATASET_METHODS:
+            method = getattr(self._dataset, name, None)
+            if callable(method):
+                return method()
+        if hasattr(self._dataset, "__len__") and hasattr(
+            self._dataset, "__getitem__"
+        ):
+            indices = range(len(self._dataset))
+            return [self._dataset[index] for index in indices]
+        raise AdapterFormatError(
+            self.source,
+            "dataset must expose to_tensor()/array() or the sequence protocol",
+        )
+
+    def stream(self) -> torch.Tensor:
+        """Return the dataset's samples as a ``[N, D]`` tensor."""
+        return as_stream(self._payload(), self.source)
+
+
+#: Adapter factories keyed by a lower-cased filename suffix.
+FACTORIES: Dict[str, Callable[..., StreamAdapter]] = {
+    ".csv": CsvAdapter,
+    ".tsv": lambda path, **kwargs: CsvAdapter(path, delimiter="\t", **kwargs),
+    ".json": JsonAdapter,
+    ".npy": NpyAdapter,
+}
+
+
+def adapter_for(path: str, **kwargs: Any) -> StreamAdapter:
+    """Return the adapter registered for ``path``'s suffix.
+
+    An unrecognised suffix is refused with
+    :class:`~spikeforge_io.errors.AdapterUnsupportedError` naming the supported
+    formats, so a caller never gets a silent misparse.
+    """
+    lowered = path.lower()
+    for suffix, factory in FACTORIES.items():
+        if lowered.endswith(suffix):
+            return factory(path, **kwargs)
+    raise AdapterUnsupportedError(
+        path,
+        "no adapter for this suffix; supported: "
+        + ", ".join(sorted(FACTORIES)),
+    )

spikeforge_io/cli.py

@@ -0,0 +1,135 @@
+"""The ``spikeforge-io`` console script.
+
+A small inspection/replay surface over the adapters: ``formats`` lists the
+registered suffixes, ``info`` describes a recorded stream, and ``replay``
+prints the ``/v1/stream`` messages an adapter would send (a dry run, so it can
+be used in CI without a running service). Mirrors the argparse style of
+:mod:`spikeforge_hub.cli`.
+"""
+
+import argparse
+import json
+from typing import Any, Dict, List, Optional
+
+import torch
+
+from spikeforge_io.adapters import FACTORIES, adapter_for
+from spikeforge_io.errors import IoError
+from spikeforge_io.replay import stream_messages
+
+
+def _print(payload: Any) -> None:
+    """Print a payload as indented JSON."""
+    print(json.dumps(payload, indent=2, default=_default))
+
+
+def _default(value: Any) -> Any:
+    """Coerce a non-JSON value (a tensor shape) for printing."""
+    if isinstance(value, torch.Tensor):
+        return value.tolist()
+    return str(value)
+
+
+def _fail(message: str) -> int:
+    """Print an error message and return the failure status."""
+    print(message)
+    return 1
+
+
+def _run_formats(_args: argparse.Namespace) -> int:
+    """Print the registered adapter suffixes."""
+    _print({"formats": sorted(FACTORIES)})
+    return 0
+
+
+def _run_info(args: argparse.Namespace) -> int:
+    """Describe a recorded stream: shape, channels, and value range."""
+    try:
+        adapter = adapter_for(
+            args.path,
+            delimiter=args.delimiter,
+            has_header=not args.no_header,
+        )
+        stream = adapter.stream()
+    except IoError as error:
+        return _fail(str(error))
+    _print(
+        {
+            "source": adapter.source,
+            "samples": int(stream.size(0)),
+            "channels": int(stream.size(1)),
+            "min": float(stream.min().item()) if stream.numel() else None,
+            "max": float(stream.max().item()) if stream.numel() else None,
+            "mean": float(stream.mean().item()) if stream.numel() else None,
+        }
+    )
+    return 0
+
+
+def _run_replay(args: argparse.Namespace) -> int:
+    """Print the ``/v1/stream`` messages an adapter would send (a dry run)."""
+    try:
+        adapter = adapter_for(
+            args.path,
+            delimiter=args.delimiter,
+            has_header=not args.no_header,
+        )
+        spec = None
+        if args.length is not None:
+            from spikeforge_io.windowing import fit_window_spec
+
+            spec = fit_window_spec(
+                adapter.stream(), int(args.length), int(args.stride or 1)
+            )
+        messages: List[Dict[str, Any]] = list(
+            stream_messages(
+                adapter,
+                window_spec=spec,
+                encoded=args.encoded,
+                session_id=args.session_id,
+                reset=args.reset,
+            )
+        )
+    except IoError as error:
+        return _fail(str(error))
+    _print({"source": adapter.source, "messages": messages})
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Parse ``argv`` and dispatch to an I/O subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="spikeforge-io",
+        description="Inspect and replay recorded numeric streams.",
+    )
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    formats = subs.add_parser("formats", help="list adapter formats")
+    formats.set_defaults(handler=_run_formats)
+
+    info = subs.add_parser("info", help="describe a recorded stream")
+    _add_source(info)
+    info.set_defaults(handler=_run_info)
+
+    replay = subs.add_parser("replay", help="print /v1/stream messages")
+    _add_source(replay)
+    replay.add_argument("--length", type=int, default=None)
+    replay.add_argument("--stride", type=int, default=None)
+    replay.add_argument("--encoded", action="store_true")
+    replay.add_argument("--reset", action="store_true")
+    replay.add_argument("--session-id", dest="session_id", default=None)
+    replay.set_defaults(handler=_run_replay)
+
+    args = parser.parse_args(argv)
+    return int(args.handler(args))
+
+
+def _add_source(parser: argparse.ArgumentParser) -> None:
+    """Add the shared source arguments to ``parser``."""
+    parser.add_argument("path")
+    parser.add_argument("--delimiter", default=",")
+    parser.add_argument("--no-header", action="store_true")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spikeforge_io/errors.py

@@ -0,0 +1,72 @@
+"""Typed errors raised by the ``spikeforge-io`` adapters.
+
+Grouped here (mirroring :mod:`spikeforge_hub.errors` and
+:mod:`spikeforge.serving.errors`) so a caller can react to a missing file, a
+malformed row, a wrong channel count, or an absent optional dependency without
+parsing a message. An adapter never silently reshapes bad input: a refusal is a
+named type.
+"""
+
+from typing import Optional
+
+
+class IoError(Exception):
+    """Base class for every typed I/O-adapter failure."""
+
+
+class AdapterError(IoError):
+    """Base error for reading one recorded source.
+
+    The offending ``source`` (a path, a dataset name, or ``"<memory>"``) and a
+    human ``detail`` are stored as attributes.
+    """
+
+    def __init__(self, source: str, detail: str) -> None:
+        """Record ``source`` and ``detail`` and build a clear message."""
+        super().__init__(f"I/O adapter failed for {source!r}: {detail}")
+        self.source: str = source
+        self.detail: str = detail
+
+
+class AdapterFormatError(AdapterError):
+    """Raised when a source cannot be parsed into a numeric stream."""
+
+    def __init__(
+        self, source: str, detail: str, position: Optional[int] = None
+    ) -> None:
+        """Record the malformed ``detail`` and an optional ``position``."""
+        super().__init__(source, detail)
+        self.position: Optional[int] = position
+
+
+class AdapterShapeError(AdapterError):
+    """Raised when a source's shape is not a usable ``[N, D]`` stream."""
+
+    def __init__(self, source: str, detail: str) -> None:
+        """Record the shape ``detail``."""
+        super().__init__(source, detail)
+
+
+class AdapterUnsupportedError(AdapterError):
+    """Raised when no adapter is registered for a source's suffix."""
+
+    def __init__(self, source: str, detail: str) -> None:
+        """Record why the source has no adapter."""
+        super().__init__(source, detail)
+
+
+class AdapterDependencyError(IoError):
+    """Raised when an optional dependency (for example ``numpy``) is absent.
+
+    The message names the dependency and how to install it, so an unavailable
+    format is reported rather than guessed at.
+    """
+
+    def __init__(self, dependency: str, feature: str) -> None:
+        """Name the missing dependency and the feature that needs it."""
+        super().__init__(
+            f"{dependency} is required to read {feature}; install the "
+            "`spikeforge-io[npy]` extra"
+        )
+        self.dependency: str = dependency
+        self.feature: str = feature

spikeforge_io/replay.py

@@ -0,0 +1,146 @@
+"""Replay a recorded stream into a sink or into ``spikeforge-serve``'s stream.
+
+Two entry points:
+
+* :func:`replay` feeds each adapted frame to any callable sink, so a recorded
+  file can drive the ``encode`` function, an
+  :class:`~spikeforge.serving.session.InferenceSession`, or a test double.
+* :func:`stream_messages` / :func:`replay_to_stream` build and send the exact
+  message shape the ``WS /v1/stream`` endpoint accepts (``{"frame": ...}`` with
+  an optional leading ``{"reset": true}``), so an adapter replays a recorded
+  stream into the live service without a bespoke transport.
+
+Neither function imports the serve or client distributions: the protocol is a
+plain dict, and the caller supplies the ``send`` callable, so
+``spikeforge-io`` stays dependency-light.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence
+
+import torch
+
+from spikeforge_io.adapters import StreamAdapter
+
+#: A callable that receives one frame tensor (or message dict).
+Sink = Callable[[Any], Any]
+
+
+@dataclass(frozen=True)
+class ReplayReport:
+    """What one replay sent: the source, frame count, and any replies."""
+
+    source: str
+    frames: int
+    windows: bool = False
+    replies: Sequence[Any] = field(default_factory=tuple)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the report as a JSON-able mapping."""
+        return {
+            "source": self.source,
+            "frames": int(self.frames),
+            "windows": bool(self.windows),
+            "replies": len(self.replies),
+        }
+
+
+def _frames(adapter: StreamAdapter, window_spec: Any) -> List[torch.Tensor]:
+    """Return the adapter's replay frames as a list of tensors.
+
+    Without a ``window_spec`` each frame is one raw ``[D]`` sample; with one,
+    each frame is a normalized ``[L, D]`` window.
+    """
+    if window_spec is None:
+        return list(adapter.stream())
+    return list(adapter.windows(window_spec))
+
+
+def replay(
+    adapter: StreamAdapter,
+    sink: Sink,
+    *,
+    window_spec: Any = None,
+) -> ReplayReport:
+    """Feed every frame of ``adapter`` to ``sink`` and return the report.
+
+    ``sink`` receives one frame at a time (a ``[D]`` sample, or an ``[L, D]``
+    window when ``window_spec`` is given); its return value is ignored. This is
+    the general hook an :class:`~spikeforge.serving.session.InferenceSession`,
+    the ``encode`` function, or a test double binds to.
+    """
+    frames = _frames(adapter, window_spec)
+    for frame in frames:
+        sink(frame)
+    return ReplayReport(
+        source=adapter.source,
+        frames=len(frames),
+        windows=window_spec is not None,
+    )
+
+
+def stream_messages(
+    adapter: StreamAdapter,
+    *,
+    window_spec: Any = None,
+    encoded: bool = False,
+    session_id: Optional[str] = None,
+    reset: bool = False,
+) -> Iterator[Dict[str, Any]]:
+    """Yield the ``/v1/stream`` messages that replay ``adapter``.
+
+    The first message is a ``{"reset": true}`` envelope when ``reset`` is set,
+    then one ``{"frame": ...}`` message per sample (or per normalized window
+    when ``window_spec`` is given). The shape matches
+    :func:`spikeforge_serve.app._stream_reply` exactly.
+    """
+    if reset:
+        yield _message({"reset": True}, session_id)
+    for frame in _frames(adapter, window_spec):
+        yield _message(
+            {"frame": frame.tolist(), "encoded": bool(encoded)}, session_id
+        )
+
+
+def _message(
+    body: Dict[str, Any], session_id: Optional[str]
+) -> Dict[str, Any]:
+    """Return ``body`` with an optional session id folded in."""
+    if session_id:
+        body["session_id"] = session_id
+    return body
+
+
+def replay_to_stream(
+    adapter: StreamAdapter,
+    send: Sink,
+    *,
+    window_spec: Any = None,
+    encoded: bool = False,
+    session_id: Optional[str] = None,
+    reset: bool = False,
+) -> ReplayReport:
+    """Replay ``adapter`` into ``/v1/stream`` through ``send``.
+
+    ``send`` takes one protocol message and returns the service reply (for a
+    WebSocket, ``send`` would serialize and await the response). The replies
+    are collected into the returned :class:`ReplayReport`.
+    """
+    frames = 0
+    replies: List[Any] = []
+    for message in stream_messages(
+        adapter,
+        window_spec=window_spec,
+        encoded=encoded,
+        session_id=session_id,
+        reset=reset,
+    ):
+        if "frame" in message:
+            frames += 1
+        replies.append(send(message))
+    return ReplayReport(
+        source=adapter.source,
+        frames=frames,
+        windows=window_spec is not None,
+        replies=tuple(replies),
+    )

spikeforge_io/windowing.py

@@ -0,0 +1,71 @@
+"""Windowing and normalization surface for ``spikeforge-io``.
+
+The plan places "windowing/normalization" on the ``spikeforge-io``
+distribution. The *implementation*, however, stays in the core
+:mod:`spikeforge.streaming.window_spec` module, because core must never depend
+on a satellite: the training recipe, the serving session, and the UC-1 tests
+all consume the frozen :class:`~spikeforge.streaming.window_spec.WindowSpec`
+directly. This module therefore **re-exports** the one canonical contract
+rather than copying it, so there is a single definition of "how a stream
+becomes a normalized window"; ``spikeforge_io.windows(...)`` is byte-for-byte
+the core behaviour.
+
+A caller that only wants the I/O surface can import everything here:
+
+    from spikeforge_io.windowing import WindowSpec, window_stream
+"""
+
+from typing import Any
+
+from spikeforge.streaming.encoding import (
+    delta_over_window,
+    encode_windows,
+)
+from spikeforge.streaming.window_spec import (
+    WINDOW_SPEC_VERSION,
+    WindowSpec,
+    fit_window_spec,
+    normalize_windows,
+    window_stream,
+)
+
+__all__ = [
+    "WINDOW_SPEC_VERSION",
+    "WindowSpec",
+    "delta_over_window",
+    "encode_windows",
+    "fit_window_spec",
+    "normalize_windows",
+    "window_spec_from_bundle",
+    "window_stream",
+]
+
+
+def window_spec_from_bundle(bundle: Any) -> WindowSpec:
+    """Return the frozen window contract a bundle carries.
+
+    A bundle whose ``preprocessing`` block has no ``window`` entry cannot be
+    windowed by this helper; the caller must fit a spec instead. The returned
+    spec is validated, so a corrupt recorded contract is refused rather than
+    used.
+    """
+    preprocessing = dict(getattr(bundle, "preprocessing", None) or {})
+    recorded = preprocessing.get("window")
+    if not recorded:
+        raise ValueError(
+            "bundle carries no frozen window contract; fit a WindowSpec "
+            "with fit_window_spec"
+        )
+    spec = WindowSpec.from_dict(recorded)
+    spec.validate()
+    return spec
+
+
+def windows(bundle: Any, stream: Any) -> Any:
+    """Return ``stream``'s normalized ``[W, L, D]`` windows for ``bundle``.
+
+    This is the one-call path an adapter uses: the window geometry and the
+    z-score statistics both come from the bundle's frozen contract, so a
+    recorded stream is normalized exactly as training was.
+    """
+    return window_spec_from_bundle(bundle).windows(stream)

spikeforge_io-0.1.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: spikeforge-io
+Version: 0.1.0
+Summary: Recorded-stream I/O adapters and the windowing surface for spikeforge.
+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,streaming,io,adapters,windowing
+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: spikeforge~=0.3.0
+Requires-Dist: torch>=2.5
+Requires-Dist: numpy>=1.26
+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"
+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)
+[![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)
+
+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 and unpublished.** `install.sh` is the supported path today;
+> PyPI ships once the distributions are published. 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).

spikeforge_io-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+spikeforge_io/__init__.py,sha256=efoHQ054E3hy2YW4EPlz7CbweXx761poc_1YdvfktFA,2241
+spikeforge_io/__main__.py,sha256=Hgs4w5-Bt7I-A4oHBiuw6kqHv7QPmUVAUA7KWpFePWs,156
+spikeforge_io/adapters.py,sha256=PRomCj5yVbQwv3KdEryeV3alAKBbvHZaWz5Z2yinmBo,11708
+spikeforge_io/cli.py,sha256=106viYV8T7CNuG0Rwu8xcOPQI4UGbq5VJi6Mc8v94AQ,4359
+spikeforge_io/errors.py,sha256=os4tn7wHI8K9KlZwj38Uo57MSJNZCT8W4zDrXTWytrQ,2500
+spikeforge_io/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spikeforge_io/replay.py,sha256=UNqO42RH57z4Gh65w6mJj7a3yC-M_rsj3pQuY_C9pxM,4640
+spikeforge_io/windowing.py,sha256=BorQIB6sojDOf79_XPRw1mZ-_2oknWVQXvZBDgXRCjI,2411
+spikeforge_io-0.1.0.dist-info/licenses/LICENSE,sha256=AMWvpmlE0gnq9edII9aRBnpbGNM7wBhbJ6ysoraXjgE,1511
+spikeforge_io-0.1.0.dist-info/METADATA,sha256=dBjKU_yABJ6Q1Ewy7K1U0fkiW-aTBVheglt-BThkGI8,6036
+spikeforge_io-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+spikeforge_io-0.1.0.dist-info/entry_points.txt,sha256=s10Y4NEvwNAepc7_etOdxLSUTKY4unTGWh11KZXEOR4,57
+spikeforge_io-0.1.0.dist-info/top_level.txt,sha256=tKiX2s0Qc1ujeCvxOoarR0vcW0HycDucd2FUCh67Y9g,14
+spikeforge_io-0.1.0.dist-info/RECORD,,

spikeforge_io-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spikeforge_io-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spikeforge-io = spikeforge_io.cli:main

spikeforge_io-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2018 Capsize LLC
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

spikeforge_io-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spikeforge_io