spikeling 1.0.2__tar.gz

spikeling-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavin Branaa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spikeling-1.0.2/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: spikeling
+Version: 1.0.2
+Summary: A domain-specific language and runtime for spiking neural networks: one .spk file, four backends (Python, C, Verilog, GDScript).
+Author-email: Gavin Branaa <gbranaa4@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tritsystem/Spikeling
+Project-URL: Repository, https://github.com/tritsystem/Spikeling
+Project-URL: Issues, https://github.com/tritsystem/Spikeling/issues
+Project-URL: Changelog, https://github.com/tritsystem/Spikeling/blob/main/CHANGELOG.md
+Keywords: spiking neural network,neuromorphic,dsl,lif,stdp,reservoir computing,fpga
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# 🧠 Spikeling
+
+A neuromorphic **domain-specific language and runtime for spiking neural
+networks**, by Gavin Branaa. You describe a network of spiking neurons and
+synapses in a compact `.spk` file, and run that one description on any of four
+backends:
+
+- an **interactive Python runtime** (development + STDP learning),
+- generated **C** (embedded / production),
+- generated **Verilog** (FPGA / hardware simulation), and
+- **GDScript** (give a Godot game a live spiking "mind").
+
+One language, four targets.
+
+---
+
+## Quick start
+
+```bash
+cd core
+python -m core                     # run the default example, interactively
+python -m core path/to/network.spk # run your own .spk network
+```
+
+Full DSL reference, runtime details, and the C-compilation path are in
+[`core/README.md`](core/README.md).
+
+## The `.spk` language in 30 seconds
+
+```spk
+neuron LeftMic  threshold=110 leak=5 type=LIF
+neuron RightMic threshold=110 leak=5 type=LIF
+neuron Motor    threshold=80  leak=3 type=LIF
+
+connect LeftMic  -> Motor weight=0.8
+connect RightMic -> Motor weight=0.8
+
+action Motor -> [MOTOR_FIRE]
+
+refractory=400ms
+learn=STDP rate=0.01
+```
+
+| Directive | Meaning |
+|---|---|
+| `neuron <name> threshold=<n> leak=<n> [type=LIF]` | define a neuron |
+| `connect <src> -> <dst> weight=<w>` | weighted synapse |
+| `action <neuron> -> [<COMMAND>]` | map a spike to a named command |
+| `refractory=<n>ms` | global refractory period |
+| `learn=STDP rate=<r>` | enable spike-timing-dependent plasticity |
+
+*(The GDScript backend uses a compact variant — `synapse SRC -> DST weight=N` —
+documented in [`godot-runtime/`](godot-runtime/README.md).)*
+
+## Neuron types
+
+| Type | What it is |
+|---|---|
+| `LIF` | Leaky integrate-and-fire — fast, standard |
+| `Izhikevich` | Cortical model — bursting, adaptation |
+| `AdEx` | Adaptive exponential — realism/speed balance |
+| `Resonator` | Damped oscillator — responds only to input near its own frequency (a frequency-domain primitive). See [`resonator-prototype/`](resonator-prototype/README.md) |
+
+---
+
+## Repository map
+
+| Folder | What it is | Status |
+|---|---|---|
+| [`core/`](core/README.md) | The canonical Python package: compiler, runtime, encoder, stdlib, examples. **Start here.** | Active — source of truth |
+| [`resonator-prototype/`](resonator-prototype/README.md) | The `Resonator` neuron type + benchmarks vs Goertzel/FFT | Active |
+| [`godot-runtime/`](godot-runtime/README.md) | GDScript backend — run a `.spk` brain live inside Godot | Active |
+| [`godot-plugin/`](godot-plugin/README.md) | Godot editor addon wrapping the brain | Active |
+| [`sdk-verilog/`](sdk-verilog/README_INDEX.md) | C + Verilog hardware backend, with testbench | Active |
+| [`parallel-audio/`](parallel-audio/README_INDEX.md) | Real-time microphone/audio input engine (C, miniaudio + FFT) | Active, newest |
+| [`benchmarks/`](benchmarks/BENCHMARKS.md) | Performance studies (dormant-vs-polling, gated resonators) | Active |
+| [`fps-game/`](fps-game/README_INDEX.md) | An FPS whose enemy AI is driven by Spikeling brains | Complete |
+| [`ai-apps/`](ai-apps/README_INDEX.md) | Ollama/RAG assistant apps built around Spikeling | Active |
+| [`research/`](research/README_INDEX.md) | Stochastic-resonance experiments (does noise help inference?) | Exploratory |
+| [`legacy-versions/`](legacy-versions/README_INDEX.md) | Superseded earlier scripts | Reference only |
+| `build-artifacts/` | Compiled binaries (generated; excluded from git) | Generated |
+
+**Not included here:** a separate, unrelated project is kept out of this
+repository via `.gitignore`.
+
+## Agent orchestration as an SNN
+
+An experimental line of work tests whether a spiking neural network can serve
+as the control layer for a multi-agent pipeline — routing tasks, managing
+concurrency, and arbitrating conflicts through spike-based inhibition rather
+than classical scheduling logic.
+
+| File | What it does | What was verified |
+|---|---|---|
+| [`core/examples/agent_brain.spk`](core/examples/agent_brain.spk) | SNN definition for agent-routing and winner-take-all inhibition | Routing and lateral inhibition fire correctly in the Python runtime |
+| [`spiking_orchestrator.py`](spiking_orchestrator.py) | Drives the agent pipeline from spike events | Integrates with the runtime; event dispatch works end-to-end |
+| [`spiking_scheduler.py`](spiking_scheduler.py) | Maps spike activity to agent-slot concurrency scheduling | Mechanism works; falsified as a differentiator — produces identical assignments to classical greedy graph coloring |
+| [`agent_runner.py`](agent_runner.py) | Executes individual agents under scheduler control | Runs agents correctly within the allocated slots |
+| [`benchmark_scheduler.py`](benchmark_scheduler.py) | Compares SNN scheduler against greedy coloring across workloads | Confirms parity; no throughput advantage found |
+| [`test_soft_conflicts.py`](test_soft_conflicts.py) | Tests a ternary consensus gate for soft (probabilistic) conflicts | Shows a small, real accuracy win under high conflict load, at substantial added complexity |
+| [`test_incremental_scheduling.py`](test_incremental_scheduling.py) | Tests online incremental task arrival against classical online coloring | Exact tie — no advantage from the SNN path on incremental arrival |
+
+The honest summary: the SNN routing and inhibition primitives work, but the
+scheduling and arbitration results did not beat well-known classical baselines.
+
+---
+
+## License
+
+MIT (source code). See [`LICENSE`](LICENSE).

spikeling-1.0.2/README.md

@@ -0,0 +1,110 @@
+# 🧠 Spikeling
+
+A neuromorphic **domain-specific language and runtime for spiking neural
+networks**, by Gavin Branaa. You describe a network of spiking neurons and
+synapses in a compact `.spk` file, and run that one description on any of four
+backends:
+
+- an **interactive Python runtime** (development + STDP learning),
+- generated **C** (embedded / production),
+- generated **Verilog** (FPGA / hardware simulation), and
+- **GDScript** (give a Godot game a live spiking "mind").
+
+One language, four targets.
+
+---
+
+## Quick start
+
+```bash
+cd core
+python -m core                     # run the default example, interactively
+python -m core path/to/network.spk # run your own .spk network
+```
+
+Full DSL reference, runtime details, and the C-compilation path are in
+[`core/README.md`](core/README.md).
+
+## The `.spk` language in 30 seconds
+
+```spk
+neuron LeftMic  threshold=110 leak=5 type=LIF
+neuron RightMic threshold=110 leak=5 type=LIF
+neuron Motor    threshold=80  leak=3 type=LIF
+
+connect LeftMic  -> Motor weight=0.8
+connect RightMic -> Motor weight=0.8
+
+action Motor -> [MOTOR_FIRE]
+
+refractory=400ms
+learn=STDP rate=0.01
+```
+
+| Directive | Meaning |
+|---|---|
+| `neuron <name> threshold=<n> leak=<n> [type=LIF]` | define a neuron |
+| `connect <src> -> <dst> weight=<w>` | weighted synapse |
+| `action <neuron> -> [<COMMAND>]` | map a spike to a named command |
+| `refractory=<n>ms` | global refractory period |
+| `learn=STDP rate=<r>` | enable spike-timing-dependent plasticity |
+
+*(The GDScript backend uses a compact variant — `synapse SRC -> DST weight=N` —
+documented in [`godot-runtime/`](godot-runtime/README.md).)*
+
+## Neuron types
+
+| Type | What it is |
+|---|---|
+| `LIF` | Leaky integrate-and-fire — fast, standard |
+| `Izhikevich` | Cortical model — bursting, adaptation |
+| `AdEx` | Adaptive exponential — realism/speed balance |
+| `Resonator` | Damped oscillator — responds only to input near its own frequency (a frequency-domain primitive). See [`resonator-prototype/`](resonator-prototype/README.md) |
+
+---
+
+## Repository map
+
+| Folder | What it is | Status |
+|---|---|---|
+| [`core/`](core/README.md) | The canonical Python package: compiler, runtime, encoder, stdlib, examples. **Start here.** | Active — source of truth |
+| [`resonator-prototype/`](resonator-prototype/README.md) | The `Resonator` neuron type + benchmarks vs Goertzel/FFT | Active |
+| [`godot-runtime/`](godot-runtime/README.md) | GDScript backend — run a `.spk` brain live inside Godot | Active |
+| [`godot-plugin/`](godot-plugin/README.md) | Godot editor addon wrapping the brain | Active |
+| [`sdk-verilog/`](sdk-verilog/README_INDEX.md) | C + Verilog hardware backend, with testbench | Active |
+| [`parallel-audio/`](parallel-audio/README_INDEX.md) | Real-time microphone/audio input engine (C, miniaudio + FFT) | Active, newest |
+| [`benchmarks/`](benchmarks/BENCHMARKS.md) | Performance studies (dormant-vs-polling, gated resonators) | Active |
+| [`fps-game/`](fps-game/README_INDEX.md) | An FPS whose enemy AI is driven by Spikeling brains | Complete |
+| [`ai-apps/`](ai-apps/README_INDEX.md) | Ollama/RAG assistant apps built around Spikeling | Active |
+| [`research/`](research/README_INDEX.md) | Stochastic-resonance experiments (does noise help inference?) | Exploratory |
+| [`legacy-versions/`](legacy-versions/README_INDEX.md) | Superseded earlier scripts | Reference only |
+| `build-artifacts/` | Compiled binaries (generated; excluded from git) | Generated |
+
+**Not included here:** a separate, unrelated project is kept out of this
+repository via `.gitignore`.
+
+## Agent orchestration as an SNN
+
+An experimental line of work tests whether a spiking neural network can serve
+as the control layer for a multi-agent pipeline — routing tasks, managing
+concurrency, and arbitrating conflicts through spike-based inhibition rather
+than classical scheduling logic.
+
+| File | What it does | What was verified |
+|---|---|---|
+| [`core/examples/agent_brain.spk`](core/examples/agent_brain.spk) | SNN definition for agent-routing and winner-take-all inhibition | Routing and lateral inhibition fire correctly in the Python runtime |
+| [`spiking_orchestrator.py`](spiking_orchestrator.py) | Drives the agent pipeline from spike events | Integrates with the runtime; event dispatch works end-to-end |
+| [`spiking_scheduler.py`](spiking_scheduler.py) | Maps spike activity to agent-slot concurrency scheduling | Mechanism works; falsified as a differentiator — produces identical assignments to classical greedy graph coloring |
+| [`agent_runner.py`](agent_runner.py) | Executes individual agents under scheduler control | Runs agents correctly within the allocated slots |
+| [`benchmark_scheduler.py`](benchmark_scheduler.py) | Compares SNN scheduler against greedy coloring across workloads | Confirms parity; no throughput advantage found |
+| [`test_soft_conflicts.py`](test_soft_conflicts.py) | Tests a ternary consensus gate for soft (probabilistic) conflicts | Shows a small, real accuracy win under high conflict load, at substantial added complexity |
+| [`test_incremental_scheduling.py`](test_incremental_scheduling.py) | Tests online incremental task arrival against classical online coloring | Exact tie — no advantage from the SNN path on incremental arrival |
+
+The honest summary: the SNN routing and inhibition primitives work, but the
+scheduling and arbitration results did not beat well-known classical baselines.
+
+---
+
+## License
+
+MIT (source code). See [`LICENSE`](LICENSE).

spikeling-1.0.2/core/__init__.py

@@ -0,0 +1 @@
+# Spikeling — Neuromorphic AI Runtime

spikeling-1.0.2/core/__main__.py

@@ -0,0 +1,81 @@
+"""
+spikeling/__main__.py
+=====================
+Entry point for the Spikeling neuromorphic runtime.
+
+Usage:
+  python -m spikeling                               # reflex demo (sound localizer)
+  python -m spikeling --train                       # interactive trainer
+  python -m spikeling --train path/to/network.spk  # train a specific network
+  python -m spikeling path/to/network.spk           # run any network interactively
+  python -m spikeling --no-interactive              # compile only
+"""
+
+import sys
+import os
+
+# Windows' legacy console codepage (cp1252 etc.) can't encode the box-drawing
+# characters the interactive runtime prints (runtime.py's banner) -- crashes the
+# very first `python -m core` a new user tries, on a default Windows terminal,
+# with no non-ASCII input involved at all. Reconfigure as early as possible,
+# before any print happens; a no-op on already-UTF-8 setups (Linux/macOS, or a
+# UTF-8 Windows Terminal).
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try:
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+from compiler.compiler import compile_file
+from runtime.runtime   import SpikelingRuntime
+
+
+def main():
+    args         = sys.argv[1:]
+    train_mode   = "--train" in args
+    no_ui        = "--no-interactive" in args
+    spk_args     = [a for a in args if not a.startswith("--")]
+
+    # Default networks
+    base = os.path.dirname(__file__)
+    default_demo    = os.path.join(base, "examples", "sound_localizer.spk")
+    default_learner = os.path.join(base, "examples", "word_learner.spk")
+
+    if train_mode:
+        spk_path = spk_args[0] if spk_args else default_learner
+    else:
+        spk_path = spk_args[0] if spk_args else default_demo
+
+    if not os.path.exists(spk_path):
+        print(f"[spikeling] error: file not found - {spk_path}")
+        sys.exit(1)
+
+    print(f"[spikeling] compiling {spk_path} ...")
+    output_dir = os.path.dirname(os.path.abspath(spk_path))
+    ast        = compile_file(spk_path, output_dir=output_dir)
+    rt         = SpikelingRuntime(ast)
+
+    if no_ui:
+        print("[spikeling] compiled successfully (--no-interactive mode)")
+        print(rt.state_report())
+        return
+
+    if train_mode:
+        # Wire in the trainer
+        from trainer.trainer import SpikelingTrainer
+        memory_path = os.path.join(output_dir, "spikeling_memory.json")
+        trainer     = SpikelingTrainer(rt, memory_path=memory_path)
+        trainer.run_interactive()
+    else:
+        # Reflex / benchmark demo
+        for action in ast.actions:
+            cmd = action.command
+            rt.register_handler(cmd, lambda c=cmd: None)
+        rt.run_interactive()
+
+
+if __name__ == "__main__":
+    main()