Metadata-Version: 2.4
Name: sara_engine
Version: 0.4.4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: transformers
Requires-Dist: msgpack
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: tqdm
License-File: LICENSE
Summary: A bio-inspired Spiking Neural Network engine with Hugging Face-like pipeline APIs (CPU-only, Backprop-free).
Author-email: matsushibadenki <apple.darwin@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/matsushibadenki/sara-engine-project

# **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:** \* **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.  
* **Function Calling (Agentic SARA):** Capable of emitting specific spikes (e.g., \<CALC\>) to trigger and integrate external Python tools.

## **🚀 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.)*

## **💬 CLI Tools & Instruction Tuning**

SARA comes with built-in CLI tools to easily interact with and train the engine on custom dialogue data without heavy GPU resources.

### **Interactive Chat**

Start an interactive chat session using the distilled SNN model:

sara-chat \--model models/distilled\_sara\_llm.msgpack

### **Instruction Tuning (Training)**

You can easily fine-tune or override SARA's personality and knowledge using a simple JSONL file.

sara-train data/chat\_data.jsonl \--model models/distilled\_sara\_llm.msgpack

**JSONL Data Format Example (chat\_data.jsonl):**

Each line should be a JSON object containing user and sara (or assistant) keys.

{"user": "こんにちは", "sara": "こんにちは！SARAです。何かお手伝いしましょうか？"}  
{"user": "SARAって何？", "sara": "私はスパイキングニューラルネットワークで動くローカルAIエンジンです。"}

## **🌐 Integration Examples**

SARA's lightweight CPU inference makes it perfect for integrating into modern web frameworks and bots.

### **1\. FastAPI Integration**

Serve SARA via a REST API:

from fastapi import FastAPI  
from pydantic import BaseModel  
from sara\_engine.inference import SaraInference

app \= FastAPI()  
sara \= SaraInference(model\_path="models/distilled\_sara\_llm.msgpack")

class ChatRequest(BaseModel):  
    message: str

@app.post("/chat")  
def chat\_endpoint(req: ChatRequest):  
    sara.reset\_buffer()  
    prompt \= f"You: {req.message}\\nSARA:"  
    response \= sara.generate(prompt, max\_length=100, temperature=0.1)  
    return {"response": response.strip()}

### **2\. Discord Bot Integration**

Build a fast, local Discord bot:

import discord  
import os  
from sara\_engine.inference import SaraInference

intents \= discord.Intents.default()  
intents.message\_content \= True  
client \= discord.Client(intents=intents)  
sara \= SaraInference(model\_path="models/distilled\_sara\_llm.msgpack")

@client.event  
async def on\_message(message):  
    if message.author \== client.user:  
        return  
          
    sara.reset\_buffer()  
    prompt \= f"You: {message.content}\\nSARA:"  
    response \= sara.generate(prompt, max\_length=100, temperature=0.1)  
    await message.channel.send(response.strip())

client.run(os.getenv('DISCORD\_TOKEN'))

## **🛠️ Architecture & Modules**

* 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., SpikingCausalLM, BioTransformer).  
* sara\_engine.memory: Implementations of SDR, Hippocampus, and Vector Stores.  
* sara\_engine.agent: Agentic frameworks for MoE and Function Calling.

## **🗺️ Roadmap & Documentation**

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

* doc/ROADMAP.md \- Short-term development goals.  
* doc/SARA\_EVOLUTION\_ROADMAP.md \- Long-term evolutionary roadmap.  
* doc/stateful\_snn\_theory.md \- Theoretical background on Stateful SNNs and NeuroFEM.

## **📄 License**

This project is licensed under the MIT License.
