sara-engine 0.2.3

A bio-inspired Spiking Neural Network engine with Hugging Face-like pipeline APIs (CPU-only, Backprop-free).

SARA Engine

SARA (Spiking Architecture for Reasoning and Adaptation) Engine is a cutting-edge AI framework that bridges the gap between biological intelligence and modern artificial neural networks.

It provides a highly efficient, event-driven Spiking Neural Network (SNN) core accelerated by Rust, combined with an intuitive PyTorch-like API. SARA goes beyond standard deep learning by natively supporting biological mechanisms such as NeuroFEM, Predictive Coding, and Hippocampal-inspired memory systems.

🧠 Key Features

• High-Performance Event-Driven Core: Rust-based SNN simulation engine that minimizes computational overhead and maximizes simulation speed.
• PyTorch-like API (sara_engine.nn): Build, train, and deploy complex spiking networks using familiar, modular, and declarative syntax.
• Advanced Biologically-Plausible Mechanisms:
  • NeuroFEM: Neuro-Finite Element Method for modeling spatial neural dynamics in 2D/3D spaces.
  • Predictive Coding: Cortex-inspired architecture supporting top-down predictions and bottom-up error processing.
  • Hippocampal Memory System: Long-Term (LTM) and Short-Term (STM) memory supporting Million-Token contexts and SDR (Sparse Distributed Representations).
  • Synaptic Plasticity: Native support for STDP (Spike-Timing-Dependent Plasticity) and Reward-Modulated STDP (R-STDP).
• Spiking LLMs & Transformers: Innovative spike-based attention mechanisms and fully operational Spiking Language Models.
• Multimodal Integration: Built-in encoders and pipelines for Vision, Audio, Physical, and Textual data.
• Hardware & Edge Ready: Includes a Hardware Abstraction Layer (HAL) and exporters for edge deployment (e.g., SARA Board).

🚀 Installation

Ensure you have Python 3.10 or higher and a working Rust toolchain installed.

# Clone the repository
git clone [https://github.com/matsushibadenki/sara-engine-project.git\](https://github.com/matsushibadenki/sara-engine-project.git)
cd sara-engine-project

# Install the package in editable mode (compiles the Rust core automatically)
pip install -e .

(Note: If changes to the core are not reflecting, ensure you re-run pip install -e . to rebuild the Rust extensions.)

💡 Quick Start

Here is a simple example of building and running a Spiking Neural Network using the SARA Engine:

import numpy as np
from sara_engine import nn

# Define a simple SNN model
class SimpleSNN(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.LinearSpike(in_features=784, out_features=256)
self.fc2 = nn.LinearSpike(in_features=256, out_features=10)

def forward(self, spikes):  
    x \= self.fc1(spikes)  
    x \= self.fc2(x)  
    return x

# Initialize model
model = SimpleSNN()

# Create dummy input spikes (Batch Size: 1, Features: 784)
input_spikes = np.random.rand(1, 784) > 0.8

# Forward pass
output_spikes = model(input_spikes)
print("Output Spikes Shape:", output_spikes.shape)

🛠️ Examples and Tools

The repository contains a massive collection of 70+ scripts covering demos, interactive tools, benchmarks, and unit tests.

🌟 Demos (examples/)

Explore over 50 demonstration scripts showing SARA's capabilities:

• Spiking LLMs & Transformers: demo_spiking_llm.py, demo_bio_transformer.py
• Agent Frameworks: demo_agent_chat.py, demo_million_token_agent.py
• Multimodal Pipelines: demo_multimodal_pipeline.py, demo_crossmodal_recall.py
• Learning & Plasticity: demo_rl_training.py, demo_snn_learning.py
• Advanced Bio-Mechanisms: demo_predictive_coding.py, demo_semantic_spike_routing.py

📊 Benchmarks (examples/)

Measure performance and scaling:

• benchmark_rust_acceleration.py: Compare Python vs. Rust core speeds.
• benchmark_long_context.py: Evaluate memory usage over massive contexts.

🧪 Tests (tests/)

Comprehensive test suite ensuring stability:

• test_neurofem.py, test_hippocampal_system.py, test_event_driven_snn.py

👉 For a complete and detailed list of all available scripts, please refer to doc/About-Tools-EN.md.

🏗️ Architecture & Modules

The project is structured to provide both high-level usability and low-level performance:

• sara_engine.core: The fundamental building blocks, interfacing with the Rust backend.
• sara_engine.nn: High-level PyTorch-like API for model construction.
• sara_engine.models: Pre-built architectures (e.g., SpikingImageClassifier, BioTransformer, SpikingLLM).
• sara_engine.pipelines: End-to-end inference pipelines (Text, Vision, Audio).
• sara_engine.memory: Implementations of SDR, Hippocampus, and Vector Stores.
• sara_engine.edge: Exporters and runtime utilities for hardware deployment.

🗺️ Roadmap & Documentation

To understand the future direction and deep theoretical background of the SARA Engine, check the following documents:

• ROADMAP.md - Short-term development goals.
• SARA_EVOLUTION_ROADMAP.md - Long-term evolutionary roadmap.
• stateful_snn_theory.md - Theoretical background on Stateful SNNs and NeuroFEM.

🤝 Contributing

We welcome contributions! Please review our policy.md for coding standards and contribution guidelines. When developing, remember our core philosophy: avoid relying on backpropagation or dense matrix multiplications where biological spike-driven mechanisms (like STDP) are intended, and ensure hardware agnosticism (no hard GPU dependencies).

📄 License

This project is licensed under the MIT License.