# 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.
- Shared TurboQuant-style quantization utilities for compact SNN memory and checkpoint handling.

## Installation

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

```bash
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:

```bash
sara-chat --model models/distilled_sara_llm.msgpack
```

Dialogue memory training from JSONL:

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

JSONL format:

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

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

```bash
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](/Users/Shared/Program/python310/sara-engine-project/src/sara_engine/utils/project_paths.py).

## Release Validation

Recommended pre-release flow:

```bash
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
```

For final shipping decisions, use the extended soak profile:

```bash
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.
