sara-engine 0.4.9

A CPU-first bio-inspired Spiking Neural Network engine with bounded-state CLI, evaluation, and release validation flows.

SARA Engine

SARA (Spiking Architecture for Reasoning and Adaptation) Engine is a CPU-first spiking AI framework for learning, inference, and lightweight agent workflows without backpropagation-heavy runtime assumptions.

The project combines an event-driven Rust core with Python model, evaluation, and CLI layers. It prioritizes biological plausibility, bounded runtime state, and managed output paths suitable for local and edge-oriented deployment.

Key Features

• Rust-accelerated event-driven SNN core for CPU-focused execution.
• Backpropagation-free, matrix-light learning flows centered on STDP, predictive coding, FORCE, and direct memory updates.
• Spiking language and agent components including SaraInference, SpikingLLM, and SaraAgent.
• Managed release validation with soak reports, release gates, and Phase 3 quality benchmarks.
• Shipping gates now require both stage_a_acceptance and stage_b_readiness, including lightweight world-model minimums such as transition, command, predictor snapshot, runtime tracking, and shift tracking readiness.
• Shared TurboQuant-style quantization utilities for compact SNN memory and checkpoint handling.
• Fluid-inspired supplementary dynamics for bounded predictive support tracing without backpropagation or matrix-heavy runtime dependencies.

Installation

Ensure Python 3.10+ and a working Rust toolchain are available.

git clone https://github.com/matsushibadenki/sara-engine-project.git
cd sara-engine-project
pip install -e .

If Rust core changes are not reflected, rerun pip install -e ..

CLI

Interactive chat with a saved memory model:

sara-chat --model models/distilled_sara_llm.msgpack

Dialogue memory training from JSONL:

sara-train data/raw/chat_data.jsonl --model models/distilled_sara_llm.msgpack

JSONL format:

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

Subword SNN LM training with optional TurboQuant-style checkpoint compression:

python scripts/train/train_snn_lm.py \
  --corpus data/processed/corpus.txt \
  --save-dir models/snn_lm_pretrained \
  --turboquant

Managed Output Policy

Generated artifacts must stay inside managed directories:

• data/raw, data/interim, data/processed
• workspace
• models

Repository-root outputs and ad hoc directories are not part of the supported production flow. Path helpers live in src/sara_engine/utils/project_paths.py.

Release Validation

Recommended pre-release flow:

pytest -q tests/test_release_soak.py tests/test_sara_cli_dispatch.py tests/test_cli_entrypoints.py tests/test_inference_reliability.py tests/test_inference_memory_io.py tests/test_spiking_llm_memory_io.py tests/test_direct_map_utils.py tests/test_chat_agent_calculator.py tests/test_sara_agent_dialogue.py tests/test_practical_reliability.py
python scripts/eval/release_soak.py --include-accuracy
python scripts/eval/release_gate.py

The release path now expects Phase 3 results to satisfy both the Stage A evaluation gate and the Stage B lightweight world-model gate. In practice, the human-readable summaries should show PASS for stage_a_acceptance, stage_b_readiness, the Stage B minimum checks, and the operator/speculative trace checks such as stage_b_operator_consistency_ready and stage_b_speculative_acceptance_ready.

For final shipping decisions, use the extended soak profile:

python scripts/eval/release_soak.py --profile extended --include-accuracy

Managed outputs:

• Soak report: workspace/release/release_soak_report.json
• Soak summary: workspace/release/release_soak_summary.txt
• Phase 3 accuracy suite: workspace/evaluation/phase3_accuracy_suite.json

Core Modules

• sara_engine.core: low-level spiking layers and Rust-facing building blocks.
• sara_engine.models: prebuilt SNN language, classifier, reservoir, and multimodal models.
• sara_engine.learning: plasticity, predictive coding, FORCE, and structural update rules.
• sara_engine.memory: SDR, hippocampal memory, long-term memory, and vector-store components.
• sara_engine.agent: bounded-state agent runtime and tool integration.
• sara_engine.evaluation: release, reliability, and Phase 3 benchmark evaluators.

Documentation

• doc/ROADMAP.md: implementation priorities and milestone status.
• doc/RELEASE_CHECKLIST.md: pre-release validation and packaging checklist.
• doc/RELEASE_NOTES.md: current pre-release changes and known gaps.
• doc/SARA-Engine_Documentation_Hub.md: broader documentation hub.

License

MIT License.