backfire_kernel/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Commercial license available
3// © Concepts 1996–2026 Miroslav Šotek. All rights reserved.
4// © Code 2020–2026 Miroslav Šotek. All rights reserved.
5// ORCID: 0009-0009-3560-0851
6// Contact: www.anulum.li | protoscience@anulum.li
7// Director-Class AI — lib
8// ─────────────────────────────────────────────────────────────────────
9// Director-Class AI — Backfire Kernel PyO3 FFI Bindings
10// © 1998-2026 Miroslav Šotek. All rights reserved.
11// License: Apache-2.0
12// ─────────────────────────────────────────────────────────────────────
13// Note: #[deny(unsafe_code)] not applied — PyO3 proc macros generate
14// unsafe blocks internally. All hand-written code in this crate is safe.
15//! Python-callable wrappers around the Rust Backfire Kernel.
16//!
17//! Exposes `RustSafetyKernel`, `RustStreamingKernel`, `RustCoherenceScorer`,
18//! and supporting types to Python via PyO3.
19//!
20//! This is a facade: one binding submodule per subsystem, each with a
21//! `register` hook called from the `#[pymodule]` entry point below, so
22//! the flat `backfire_kernel.*` Python surface is unchanged.
23//!
24//! # FFI Safety
25//!
26//! - GIL acquired via `Python::attach` before every Python callback.
27//! - Python exceptions → safe Rust defaults (0.0 for scores, None for strings).
28//! - No borrowed references escape the GIL lock scope.
29//! - All config validated before storage (`BackfireConfig::validate()`).
30//!
31//! Install: `cd backfire-kernel && pip install -e crates/backfire-ffi`
32//! (requires maturin).
33//!
34//! Usage from Python:
35//! ```python
36//! from backfire_kernel import RustSafetyKernel, RustStreamingKernel
37//!
38//! kernel = RustSafetyKernel(hard_limit=0.5)
39//! result = kernel.stream_output(["Hello ", "world"], lambda t: 0.8)
40//! ```
41
42use pyo3::prelude::*;
43
44mod compute_accel;
45mod core_gate;
46mod observers;
47mod physics;
48mod pii;
49mod retrieval;
50mod safety_hooks;
51mod signals;
52mod ssgf;
53mod stats;
54mod zk_range;
55
56// Backfire Kernel — Rust-accelerated safety gate for Director-Class AI.
57//
58// This module exposes the entire hot-path safety gate to Python:
59// - BackfireConfig, RustSafetyKernel, RustStreamingKernel
60// - RustCoherenceScorer, CoherenceScore, StreamSession
61// - Verification signal functions (Rust-accelerated)
62// - RustBM25 — BM25 sparse retrieval engine
63
64#[pymodule]
65fn backfire_kernel(m: &Bound<'_, PyModule>) -> PyResult<()> {
66    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
67    // Core safety gate
68    core_gate::register(m)?;
69    // Physics engine
70    physics::register(m)?;
71    // Boundary observers
72    observers::register(m)?;
73    // SSGF geometry engine
74    ssgf::register(m)?;
75    // Zero-knowledge range-proof attestation (Bulletproofs over Ristretto)
76    m.add_function(wrap_pyfunction!(
77        zk_range::rust_bulletproof_prove_threshold,
78        m
79    )?)?;
80    m.add_function(wrap_pyfunction!(
81        zk_range::rust_bulletproof_verify_threshold,
82        m
83    )?)?;
84    // Verification signals + injection detection (Rust-accelerated)
85    signals::register(m)?;
86    // BM25 retrieval engine
87    retrieval::register(m)?;
88    // Compute accelerators
89    compute_accel::register(m)?;
90    // Statistical helpers
91    stats::register(m)?;
92    // Heuristic parity constants (mirror _heuristics.py)
93    m.add(
94        "NEGATION_FLIP_OVERLAP",
95        backfire_core::compute::NEGATION_FLIP_OVERLAP,
96    )?;
97    // PII regex multi-pattern scanner
98    pii::register(m)?;
99    // Safety-hook acceleration (cyber-physical geometry/IK +
100    // zk-attestation Merkle + challenge derivation)
101    safety_hooks::register(m)?;
102    Ok(())
103}
backfire_kernel/lib.rs

backfire_kernel/
lib.rs
