yaab-core 0.1.0__tar.gz

yaab_core-0.1.0/Cargo.lock

@@ -0,0 +1,315 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memchr"
+version = "2.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "yaab-core"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+ "serde",
+ "serde_json",
+ "sha2",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

yaab_core-0.1.0/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "yaab-core"
+version = "0.1.0"
+edition = "2021"
+description = "Rust performance core for the YAAB agent SDK (orchestration, checkpoint serialization, vector ops)."
+license = "MIT"
+repository = "https://github.com/sthitaprajnas/yaab"
+homepage = "https://github.com/sthitaprajnas/yaab"
+readme = "README.md"
+
+[lib]
+name = "yaab_core"
+# cdylib for the Python extension module; rlib so the engine can be reused by other bindings.
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+# abi3-py311: build a single stable-ABI wheel that works on CPython 3.11+ —
+# including future versions (3.13, 3.14, …) — so users never fall back to the
+# pure-Python core just because their interpreter is newer than our wheels.
+pyo3 = { version = "0.23", features = ["extension-module", "abi3-py311"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.10"
+
+[profile.release]
+opt-level = 3
+lto = true

yaab_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YAAB contributors
+
+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.

yaab_core-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: yaab-core
+Version: 0.1.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3.11
+License-File: LICENSE
+Summary: Rust performance core for the YAAB agent SDK.
+Home-Page: https://github.com/sthitaprajnas/yaab
+Author: YAAB contributors
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# yaab-core
+
+The Rust performance core for [YAAB](../README.md), exposed to Python via PyO3.
+
+It provides the hot-path primitives the Python layer calls into:
+
+- **vector** — cosine similarity + top-k for memory retrieval
+- **checkpoint** — framed (de)serialization of graph state
+- **channels** — state-channel reducers (last-value / append / add)
+- **scheduler** — BSP superstep planning for the orchestration engine
+- **actors** — tamper-evident hash-chaining + cost aggregation for the audit log
+
+Every function has a pure-Python fallback in `yaab._core`, so the SDK installs
+and runs without this extension. Build it for the accelerated path:
+
+```bash
+maturin develop -m yaab-core/Cargo.toml --release
+```
+

yaab_core-0.1.0/README.md

@@ -0,0 +1,18 @@
+# yaab-core
+
+The Rust performance core for [YAAB](../README.md), exposed to Python via PyO3.
+
+It provides the hot-path primitives the Python layer calls into:
+
+- **vector** — cosine similarity + top-k for memory retrieval
+- **checkpoint** — framed (de)serialization of graph state
+- **channels** — state-channel reducers (last-value / append / add)
+- **scheduler** — BSP superstep planning for the orchestration engine
+- **actors** — tamper-evident hash-chaining + cost aggregation for the audit log
+
+Every function has a pure-Python fallback in `yaab._core`, so the SDK installs
+and runs without this extension. Build it for the accelerated path:
+
+```bash
+maturin develop -m yaab-core/Cargo.toml --release
+```

yaab_core-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["maturin>=1.5,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "yaab-core"
+version = "0.1.0"
+description = "Rust performance core for the YAAB agent SDK."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "YAAB contributors" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3.11",
+]
+
+[tool.maturin]
+# Pure Rust extension module: produces the importable `yaab_core` module.
+module-name = "yaab_core"

yaab_core-0.1.0/src/actors.rs

@@ -0,0 +1,41 @@
+//! Tamper-evident audit hashing and cost aggregation.
+//!
+//! The audit log is hash-chained: each entry's hash folds in the previous
+//! entry's hash plus the current payload, so any retroactive edit breaks the
+//! chain. Hashing the chain in Rust keeps the audit hot-path cheap.
+
+use sha2::{Digest, Sha256};
+
+/// Compute the chained hash for an audit entry: `sha256(prev_hash || payload)`.
+pub fn hash_event(prev_hash: &str, payload: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(prev_hash.as_bytes());
+    hasher.update(b"\x1f"); // unit separator, avoids boundary ambiguity
+    hasher.update(payload.as_bytes());
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        out.push_str(&format!("{:02x}", byte));
+    }
+    out
+}
+
+/// Verify a chain of `(payload, recorded_hash)` entries against a genesis hash.
+/// Returns the index of the first broken link, or `None` if the chain is intact.
+pub fn verify_chain(genesis: &str, entries: &[(String, String)]) -> Option<usize> {
+    let mut prev = genesis.to_string();
+    for (i, (payload, recorded)) in entries.iter().enumerate() {
+        let expected = hash_event(&prev, payload);
+        if &expected != recorded {
+            return Some(i);
+        }
+        prev = expected;
+    }
+    None
+}
+
+/// Sum a set of per-call costs into a single total. Trivial today, but a
+/// stable seam for moving cost aggregation fully into Rust later.
+pub fn aggregate_cost(values: &[f64]) -> f64 {
+    values.iter().sum()
+}

yaab_core-0.1.0/src/channels.rs

@@ -0,0 +1,94 @@
+//! State channel reducers and whole-superstep state advancement.
+//!
+//! Channels define how a node's write to a key is merged into graph state.
+//! The semantics mirror LangGraph channels: last-value (overwrite),
+//! append (accumulate into a list), and add (numeric aggregation).
+//!
+//! `advance_superstep` applies an entire superstep's node updates against the
+//! current state in a single call — the compute-bound part of graph
+//! orchestration the Python engine can offload to Rust when the developer
+//! opts into the native engine.
+
+use serde_json::{Map, Value};
+use std::collections::HashMap;
+
+/// Reduce a single `current`/`update` pair at the `Value` level.
+fn reduce_value(reducer: &str, current: &Value, update: Value) -> Value {
+    match reducer {
+        "append" => {
+            let mut list = match current {
+                Value::Array(items) => items.clone(),
+                Value::Null => Vec::new(),
+                other => vec![other.clone()],
+            };
+            match update {
+                Value::Array(items) => list.extend(items),
+                other => list.push(other),
+            }
+            Value::Array(list)
+        }
+        "add" => {
+            let a = current.as_f64().unwrap_or(0.0);
+            let b = update.as_f64().unwrap_or(0.0);
+            let sum = a + b;
+            if sum.fract() == 0.0 {
+                Value::from(sum as i64)
+            } else {
+                Value::from(sum)
+            }
+        }
+        // "last_value" and any unknown reducer overwrite.
+        _ => update,
+    }
+}
+
+/// Reduce `current` with `update` according to `reducer` (JSON-string API).
+pub fn reduce(reducer: &str, current_json: &str, update_json: &str) -> Result<String, String> {
+    let update: Value = serde_json::from_str(update_json).map_err(|e| e.to_string())?;
+    let current: Value = serde_json::from_str(current_json).map_err(|e| e.to_string())?;
+    let result = reduce_value(reducer, &current, update);
+    serde_json::to_string(&result).map_err(|e| e.to_string())
+}
+
+/// Apply a whole superstep's node updates to `state` in one pass.
+///
+/// * `state_json` — the current graph state object (JSON object).
+/// * `reducers_json` — a JSON object mapping channel key -> reducer name.
+///   Keys absent from this map use last-value semantics.
+/// * `updates_json` — a JSON array of update objects, one per node that ran in
+///   the superstep, applied in order.
+///
+/// Returns the new state as a JSON object string. Doing the full fold in Rust
+/// avoids one Python<->Rust round-trip per (key, node) pair.
+pub fn advance_superstep(
+    state_json: &str,
+    reducers_json: &str,
+    updates_json: &str,
+) -> Result<String, String> {
+    let mut state: Map<String, Value> =
+        match serde_json::from_str(state_json).map_err(|e| e.to_string())? {
+            Value::Object(m) => m,
+            _ => return Err("state must be a JSON object".to_string()),
+        };
+    let reducers: HashMap<String, String> =
+        serde_json::from_str(reducers_json).map_err(|e| e.to_string())?;
+    let updates: Vec<Value> = serde_json::from_str(updates_json).map_err(|e| e.to_string())?;
+
+    for update in updates {
+        let obj = match update {
+            Value::Object(m) => m,
+            Value::Null => continue, // a node may return no update
+            _ => return Err("each node update must be a JSON object or null".to_string()),
+        };
+        for (key, value) in obj {
+            let reducer = reducers
+                .get(&key)
+                .map(|s| s.as_str())
+                .unwrap_or("last_value");
+            let current = state.get(&key).cloned().unwrap_or(Value::Null);
+            state.insert(key, reduce_value(reducer, &current, value));
+        }
+    }
+
+    serde_json::to_string(&Value::Object(state)).map_err(|e| e.to_string())
+}

yaab_core-0.1.0/src/checkpoint.rs

@@ -0,0 +1,33 @@
+//! Checkpoint (de)serialization for durable graph execution.
+//!
+//! State snapshots are framed with a small magic header + version byte so the
+//! format can evolve without ambiguity. The payload is compact JSON; the Rust
+//! path validates structure on the way in and out.
+
+use serde_json::Value;
+
+const MAGIC: &[u8] = b"YAAB";
+const VERSION: u8 = 1;
+
+/// Encode a JSON document (passed as a string) into a framed checkpoint blob.
+pub fn encode(json_str: &str) -> Result<Vec<u8>, String> {
+    let value: Value = serde_json::from_str(json_str).map_err(|e| e.to_string())?;
+    let payload = serde_json::to_vec(&value).map_err(|e| e.to_string())?;
+    let mut out = Vec::with_capacity(payload.len() + 5);
+    out.extend_from_slice(MAGIC);
+    out.push(VERSION);
+    out.extend_from_slice(&payload);
+    Ok(out)
+}
+
+/// Decode a framed checkpoint blob back into a compact JSON string.
+pub fn decode(blob: &[u8]) -> Result<String, String> {
+    if blob.len() < 5 || &blob[0..4] != MAGIC {
+        return Err("invalid checkpoint: bad magic header".to_string());
+    }
+    if blob[4] != VERSION {
+        return Err(format!("unsupported checkpoint version: {}", blob[4]));
+    }
+    let value: Value = serde_json::from_slice(&blob[5..]).map_err(|e| e.to_string())?;
+    serde_json::to_string(&value).map_err(|e| e.to_string())
+}

yaab_core-0.1.0/src/lib.rs

@@ -0,0 +1,102 @@
+//! `yaab_core` — the Rust performance core for the YAAB agent SDK.
+//!
+//! This crate exposes a small, stable surface of hot-path primitives to
+//! Python via PyO3: vector similarity for memory retrieval, framed checkpoint
+//! (de)serialization for durable graph execution, channel reducers for graph
+//! state, BSP superstep planning for the orchestration engine, and
+//! tamper-evident hash-chaining for the audit log.
+//!
+//! Every function here has a pure-Python fallback in `yaab._core`, so the SDK
+//! installs and runs even when this extension is unavailable. The Rust path is
+//! an accelerator, never a hard dependency.
+
+use pyo3::prelude::*;
+
+mod actors;
+mod channels;
+mod checkpoint;
+mod scheduler;
+mod vector;
+
+/// Cosine similarity between two equal-length vectors.
+#[pyfunction]
+fn cosine_similarity(a: Vec<f32>, b: Vec<f32>) -> f32 {
+    vector::cosine(&a, &b)
+}
+
+/// Indices and scores of the `k` rows most similar to `query`.
+#[pyfunction]
+fn top_k(query: Vec<f32>, matrix: Vec<Vec<f32>>, k: usize) -> Vec<(usize, f32)> {
+    vector::top_k(&query, &matrix, k)
+}
+
+/// Encode a JSON document string into a framed checkpoint blob.
+#[pyfunction]
+fn encode_checkpoint(json_str: &str) -> PyResult<Vec<u8>> {
+    checkpoint::encode(json_str).map_err(pyo3::exceptions::PyValueError::new_err)
+}
+
+/// Decode a framed checkpoint blob back into a JSON string.
+#[pyfunction]
+fn decode_checkpoint(blob: Vec<u8>) -> PyResult<String> {
+    checkpoint::decode(&blob).map_err(pyo3::exceptions::PyValueError::new_err)
+}
+
+/// Reduce `current` with `update` under the named channel reducer.
+#[pyfunction]
+fn reduce_channel(reducer: &str, current_json: &str, update_json: &str) -> PyResult<String> {
+    channels::reduce(reducer, current_json, update_json)
+        .map_err(pyo3::exceptions::PyValueError::new_err)
+}
+
+/// Apply a whole superstep's node updates to graph state in one call.
+#[pyfunction]
+fn advance_superstep(
+    state_json: &str,
+    reducers_json: &str,
+    updates_json: &str,
+) -> PyResult<String> {
+    channels::advance_superstep(state_json, reducers_json, updates_json)
+        .map_err(pyo3::exceptions::PyValueError::new_err)
+}
+
+/// Plan BSP supersteps for the given nodes and edges.
+#[pyfunction]
+fn plan_supersteps(nodes: Vec<String>, edges: Vec<(String, String)>) -> Vec<Vec<String>> {
+    scheduler::plan(&nodes, &edges)
+}
+
+/// Chained hash for an audit entry: `sha256(prev_hash || payload)`.
+#[pyfunction]
+fn hash_event(prev_hash: &str, payload: &str) -> String {
+    actors::hash_event(prev_hash, payload)
+}
+
+/// Verify a hash chain; returns the index of the first broken link or `None`.
+#[pyfunction]
+fn verify_chain(genesis: &str, entries: Vec<(String, String)>) -> Option<usize> {
+    actors::verify_chain(genesis, &entries)
+}
+
+/// Sum per-call costs into a single total.
+#[pyfunction]
+fn aggregate_cost(values: Vec<f64>) -> f64 {
+    actors::aggregate_cost(&values)
+}
+
+#[pymodule]
+fn yaab_core(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
+    m.add("RUST", true)?;
+    m.add_function(wrap_pyfunction!(cosine_similarity, m)?)?;
+    m.add_function(wrap_pyfunction!(top_k, m)?)?;
+    m.add_function(wrap_pyfunction!(encode_checkpoint, m)?)?;
+    m.add_function(wrap_pyfunction!(decode_checkpoint, m)?)?;
+    m.add_function(wrap_pyfunction!(reduce_channel, m)?)?;
+    m.add_function(wrap_pyfunction!(advance_superstep, m)?)?;
+    m.add_function(wrap_pyfunction!(plan_supersteps, m)?)?;
+    m.add_function(wrap_pyfunction!(hash_event, m)?)?;
+    m.add_function(wrap_pyfunction!(verify_chain, m)?)?;
+    m.add_function(wrap_pyfunction!(aggregate_cost, m)?)?;
+    Ok(())
+}

yaab_core-0.1.0/src/scheduler.rs

@@ -0,0 +1,77 @@
+//! Superstep scheduler (Bulk Synchronous Parallel).
+//!
+//! Given a node set and directed edges, group nodes into supersteps: each
+//! superstep is a set of nodes with no unresolved upstream dependency, so all
+//! nodes in a superstep can execute in parallel. This mirrors the Pregel /
+//! Apache Beam execution model LangGraph is built on.
+//!
+//! Cycles are expected (graphs support loops), so any nodes that remain after
+//! the acyclic layering are emitted as a final superstep rather than treated
+//! as an error — the runtime drives cycles via conditional edges at run time.
+
+use std::collections::{HashMap, HashSet, VecDeque};
+
+/// Plan the supersteps for a graph.
+pub fn plan(nodes: &[String], edges: &[(String, String)]) -> Vec<Vec<String>> {
+    let node_set: HashSet<&String> = nodes.iter().collect();
+
+    let mut indegree: HashMap<&String, usize> = nodes.iter().map(|n| (n, 0usize)).collect();
+    let mut adj: HashMap<&String, Vec<&String>> = HashMap::new();
+    for (src, dst) in edges {
+        if !node_set.contains(src) || !node_set.contains(dst) || src == dst {
+            continue;
+        }
+        adj.entry(src).or_default().push(dst);
+        *indegree.entry(dst).or_insert(0) += 1;
+    }
+
+    let mut layers: Vec<Vec<String>> = Vec::new();
+    let mut ready: VecDeque<&String> = indegree
+        .iter()
+        .filter(|(_, &d)| d == 0)
+        .map(|(&n, _)| n)
+        .collect();
+    let mut visited: HashSet<&String> = HashSet::new();
+
+    while !ready.is_empty() {
+        let mut layer: Vec<String> = Vec::new();
+        let current: Vec<&String> = ready.drain(..).collect();
+        for node in &current {
+            if visited.contains(node) {
+                continue;
+            }
+            visited.insert(node);
+            layer.push((*node).clone());
+        }
+        layer.sort();
+        let mut next: Vec<&String> = Vec::new();
+        for node in &current {
+            if let Some(children) = adj.get(node) {
+                for child in children {
+                    if let Some(d) = indegree.get_mut(*child) {
+                        *d = d.saturating_sub(1);
+                        if *d == 0 && !visited.contains(*child) {
+                            next.push(child);
+                        }
+                    }
+                }
+            }
+        }
+        if !layer.is_empty() {
+            layers.push(layer);
+        }
+        ready.extend(next);
+    }
+
+    // Any nodes left participate in a cycle; emit them as a trailing superstep.
+    let mut remaining: Vec<String> = nodes
+        .iter()
+        .filter(|n| !visited.contains(n))
+        .cloned()
+        .collect();
+    if !remaining.is_empty() {
+        remaining.sort();
+        layers.push(remaining);
+    }
+    layers
+}

yaab_core-0.1.0/src/vector.rs

@@ -0,0 +1,39 @@
+//! Vector similarity operations used by `MemoryService` retrieval.
+//!
+//! These run outside the GIL on the Python side and operate on plain
+//! `f32` slices, which keeps memory-retrieval cheap even for large stores.
+
+/// Cosine similarity between two equal-length vectors.
+///
+/// Returns 0.0 for mismatched lengths or zero-magnitude vectors so callers
+/// never have to special-case degenerate input.
+pub fn cosine(a: &[f32], b: &[f32]) -> f32 {
+    if a.len() != b.len() || a.is_empty() {
+        return 0.0;
+    }
+    let mut dot = 0.0f32;
+    let mut na = 0.0f32;
+    let mut nb = 0.0f32;
+    for i in 0..a.len() {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if na == 0.0 || nb == 0.0 {
+        return 0.0;
+    }
+    dot / (na.sqrt() * nb.sqrt())
+}
+
+/// Return the indices and scores of the `k` rows most similar to `query`,
+/// sorted by descending cosine similarity.
+pub fn top_k(query: &[f32], matrix: &[Vec<f32>], k: usize) -> Vec<(usize, f32)> {
+    let mut scored: Vec<(usize, f32)> = matrix
+        .iter()
+        .enumerate()
+        .map(|(i, row)| (i, cosine(query, row)))
+        .collect();
+    scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+    scored.truncate(k);
+    scored
+}