feagi-runtime

Runtime abstraction traits for cross-platform FEAGI neural processing

Part of FEAGI - Framework for Evolutionary AGI

Overview

feagi-runtime defines the trait abstraction layer that enables FEAGI's burst engine to run on different platforms without code changes.

This crate contains ONLY trait definitions - no concrete implementations.

Supported Platforms (via runtime implementations)

Core Traits

1. Runtime Trait

Defines platform capabilities and creates storage:

pub trait Runtime: Send + Sync {
    type NeuronStorage<T: NeuralValue>: NeuronStorage<Value = T>;
    type SynapseStorage: SynapseStorage;
    
    fn create_neuron_storage<T: NeuralValue>(&self, capacity: usize) -> Result<Self::NeuronStorage<T>>;
    fn create_synapse_storage(&self, capacity: usize) -> Result<Self::SynapseStorage>;
    
    fn supports_parallel(&self) -> bool;
    fn memory_limit(&self) -> Option<usize>;
}

2. NeuronStorage Trait

Abstracts System-of-Arrays (SoA) for neurons:

pub trait NeuronStorage: Send + Sync {
    type Value: NeuralValue;
    
    fn membrane_potentials(&self) -> &[Self::Value];
    fn thresholds(&self) -> &[Self::Value];
    fn leak_coefficients(&self) -> &[f32];
    // ... 20+ properties
    
    fn add_neuron(&mut self, /* ... */) -> Result<usize>;
    fn add_neurons_batch(&mut self, /* ... */) -> Result<Vec<usize>>;
}

3. SynapseStorage Trait

Abstracts System-of-Arrays (SoA) for synapses:

pub trait SynapseStorage: Send + Sync {
    fn source_neurons(&self) -> &[u32];
    fn target_neurons(&self) -> &[u32];
    fn weights(&self) -> &[u8];
    // ... other properties
    
    fn add_synapse(&mut self, /* ... */) -> Result<usize>;
}

Usage

For Platform Implementers

Implement these traits for your platform:

use feagi_runtime::{Runtime, NeuronStorage, SynapseStorage};

// Your platform-specific storage
pub struct MyNeuronArray<T: NeuralValue> {
    membrane_potentials: MyPlatformVector<T>,
    // ...
}

impl<T: NeuralValue> NeuronStorage for MyNeuronArray<T> {
    type Value = T;
    
    fn membrane_potentials(&self) -> &[T] {
        self.membrane_potentials.as_slice()
    }
    
    // ... implement all required methods
}

// Your runtime
pub struct MyRuntime;

impl Runtime for MyRuntime {
    type NeuronStorage<T: NeuralValue> = MyNeuronArray<T>;
    type SynapseStorage = MySynapseArray;
    
    fn create_neuron_storage<T: NeuralValue>(&self, capacity: usize) -> Result<Self::NeuronStorage<T>> {
        Ok(MyNeuronArray::new(capacity))
    }
    
    fn supports_parallel(&self) -> bool { true }
    fn memory_limit(&self) -> Option<usize> { Some(1024 * 1024) }
}

For Application Developers

Use concrete runtime implementations:

use feagi_runtime_std::StdRuntime;
use feagi_burst_engine::RustNPU;
use std::sync::Arc;

// Desktop runtime
let runtime = Arc::new(StdRuntime);
let npu = RustNPU::new(runtime, 1_000_000, 10_000_000)?;
npu.process_burst()?;

Design Principles

1. Zero-Cost Abstractions

Traits compile to direct function calls (monomorphization):

// Generic code
fn process<R: Runtime>(runtime: &R) {
    let storage = runtime.create_neuron_storage(1000)?;
    // ... uses storage
}

// Compiles to platform-specific code (no vtables)
process(&StdRuntime);      // → Vec-based code
process(&EmbeddedRuntime); // → array-based code

2. Platform-Agnostic Burst Engine

Same burst processing code works everywhere:

// feagi-burst-engine works with any Runtime
pub struct RustNPU<R: Runtime, T: NeuralValue> {
    neuron_storage: RwLock<R::NeuronStorage<T>>,
    synapse_storage: RwLock<R::SynapseStorage>,
    runtime: Arc<R>,
}

// Used on desktop
let desktop_npu = RustNPU::<StdRuntime, f32>::new(/*...*/);

// Same code, different platform
let embedded_npu = RustNPU::<EmbeddedRuntime, f32>::new(/*...*/);

3. Type Safety

Compile-time guarantees for platform compatibility:

// This won't compile - embedded runtime has fixed capacity
let embedded = EmbeddedRuntime;
embedded.create_neuron_storage(1_000_000)?;  // ❌ Compile error

// This is correct
const MAX_NEURONS: usize = 10_000;
embedded.create_neuron_storage(MAX_NEURONS)?;  // ✅ OK

Trait Contract

NeuronStorage Contract

All implementations MUST guarantee:

1. ✅ Slice lengths match count() (not capacity())
2. ✅ Thread-safe (Send + Sync)
3. ✅ Mutable slices are exclusive (Rust borrow checker enforces)
4. ✅ add_neuron() increments count()
5. ✅ Coordinates stored as flat array: [x0, y0, z0, x1, y1, z1, ...]

SynapseStorage Contract

All implementations MUST guarantee:

1. ✅ Slice lengths match count()
2. ✅ Thread-safe (Send + Sync)
3. ✅ source_neurons[i] and target_neurons[i] are valid neuron IDs
4. ✅ Weights and PSPs are 0-255 (u8 range)

Testing

Trait contracts are tested in each runtime implementation:

# Test std runtime
cd feagi-runtime-std && cargo test

# Test embedded runtime
cd feagi-runtime-embedded && cargo test

# Test CUDA runtime
cd feagi-runtime-cuda && cargo test

Related Crates

Implementation Checklist

When implementing a new runtime:

• Create new crate feagi-runtime-{platform}
• Implement NeuronStorage trait
• Implement SynapseStorage trait
• Implement Runtime trait
• Add unit tests (all trait methods)
• Add integration tests (with feagi-burst-engine)
• Add benchmarks (vs CPU baseline)
• Document platform limitations
• Update this README with new runtime

Contributing

New runtime implementations welcome! See CONTRIBUTING.md

Platforms we'd love to support:

• FreeRTOS (real-time embedded)
• Distributed (MPI/gRPC clusters)
• Apple Neural Engine (ANE)
• Google TPU (Edge TPU)

License

Licensed under Apache License 2.0

Copyright © 2025 Neuraville Inc.

Links

• FEAGI Project
• Documentation
• Neural Processing Refactor Plan