FEAGI

Framework for Evolutionary Artificial General Intelligence - High-performance Rust libraries for bio-inspired neural computation.

What is FEAGI?

FEAGI (Framework for Evolutionary Artificial General Intelligence) is a bio-inspired neural architecture that models brain structures and dynamics. FEAGI Core provides the foundational Rust libraries for building neural networks that learn and adapt like biological brains.

Unlike traditional neural networks, FEAGI:

Models individual neurons with realistic dynamics (membrane potential, leak, refractory periods)
Supports heterogeneous brain regions with distinct properties
Enables structural plasticity (neurogenesis, synaptogenesis)
Runs in real-time with spike-based computation
Scales from microcontrollers to servers

Key Features

Bio-Inspired Architecture: Cortical areas, synaptic plasticity, and realistic neuron models
High Performance: 50-100x faster than Python implementations through optimized Rust
Cross-Platform: Runs on desktop, server, embedded (ESP32, Arduino, STM32), and cloud
GPU Acceleration: Optional WGPU (cross-platform) and CUDA (NVIDIA) backends
No-Std Compatible: Core algorithms work in resource-constrained environments
Modular Design: Use individual crates or the complete framework
Python Bindings: Integrate with existing Python workflows via PyO3

Installation

Add to your Cargo.toml:

[dependencies]
feagi = "0.0.1-beta.1"  # Umbrella crate (includes everything)

Or use individual building blocks:

[dependencies]
feagi-npu-burst-engine = "0.0.1-beta.1"  # Just the NPU
feagi-npu-neural = "0.0.1-beta.1"        # Just core types

Or umbrella with specific features:

[dependencies]
feagi = { version = "0.0.1-beta.1", features = ["gpu"] }

Quick Start

Create and Run a Neural Network

use feagi::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize neural processing unit
    let mut npu = RustNPU::new(100_000, 1_000_000, 20)?;
    
    // Load brain configuration
    npu.load_connectome("brain.json")?;
    
    // Process neural burst cycle
    npu.process_burst()?;
    
    Ok(())
}

Embedded Target (no_std)

#![no_std]
use feagi_neural::NeuronDynamics;
use feagi_runtime_embedded::EmbeddedRuntime;

// Configure for resource-constrained systems
let runtime = EmbeddedRuntime::new(1000, 5000);
let mut dynamics = NeuronDynamics::new(&runtime);

Python Integration

import feagi_rust

# Create high-performance engine
engine = feagi_rust.SynapticPropagationEngine()

# Build synaptic connectivity
engine.build_index(source_neurons, target_neurons, weights, conductances, types, valid_mask)

# Process neural activity
result = engine.propagate(fired_neurons)

Architecture

FEAGI Core is organized as a workspace of focused crates:

Core Types and Algorithms

feagi-types: Fundamental data structures (neurons, synapses, cortical areas)
feagi-neural: Platform-agnostic neuron dynamics (no_std compatible)
feagi-synapse: Synaptic computation algorithms (no_std compatible)

Neural Processing

feagi-burst-engine: High-performance burst cycle execution
feagi-brain-development: Brain development (neurogenesis, synaptogenesis)
feagi-plasticity: Synaptic learning (STDP, memory consolidation)
feagi-evolutionary: Genome I/O and evolutionary algorithms

Infrastructure

feagi-state-manager: Runtime state and lifecycle management
feagi-config: Configuration loading and validation
feagi-observability: Logging, telemetry, and profiling

I/O and Integration

feagi-io: I/O system (sensory input, motor output)
feagi-agent: Client library for agent integration
feagi-api: REST API server
feagi-transports: Network transport abstractions (ZMQ, UDP, HTTP)

Platform Adapters

feagi-runtime-std: Desktop and server deployment (Vec, Rayon, async)
feagi-runtime-embedded: Embedded systems (fixed arrays, no_std)
feagi-hal: Platform abstraction layer for ESP32, Arduino, STM32

Utilities

feagi-connectome-serialization: Brain persistence and loading
feagi-services: High-level service compositions

Performance

FEAGI Core delivers significant performance improvements over interpreted implementations:

Synaptic Propagation: 50-100x faster than Python/NumPy
Burst Frequency: Supports 30Hz+ with millions of neurons
Memory Efficiency: Minimal allocations, cache-friendly data structures
Parallel Processing: Multi-threaded execution with Rayon
GPU Acceleration: Optional WGPU or CUDA backends for massive parallelism

Design Principles

Biologically Plausible

Individual neuron modeling with realistic parameters
Spike-based computation (not rate-coded)
Synaptic delays and conductances
Structural and functional plasticity

Cross-Platform from Day One

Core algorithms are platform-agnostic (no_std compatible)
Runtime adapters for different deployment targets
Conditional compilation for embedded, desktop, and server
No reliance on OS-specific features in core logic

Performance Critical

No allocations in hot paths (pre-allocated buffers)
Cache-friendly data layouts (#[repr(C)], AoS patterns)
SIMD-friendly operations where applicable
Optional GPU acceleration without compromising portability

Type Safety

Strong typing with newtypes (NeuronId, SynapseId)
Compile-time guarantees over runtime checks
Zero-cost abstractions throughout

Feature Flags

Umbrella Crate (feagi)

[features]
default = ["std", "full"]
std = [...]           # Standard library support
no_std = [...]        # Embedded/bare-metal
wasm = [...]          # WebAssembly target
full = ["compute", "io"]
compute = [...]       # Neural computation only
io = [...]            # I/O and networking

Burst Engine

[features]
gpu = [...]           # Cross-platform GPU (WGPU)
cuda = [...]          # NVIDIA CUDA acceleration
all-gpu = [...]       # All GPU backends

Building from Source

# Clone repository
git clone https://github.com/feagi/feagi-core
cd feagi-core

# Build the crate
cargo build --release

# Run tests
cargo test --workspace

# Build with GPU support
cargo build --release --features gpu

# Generate documentation
cargo doc --open

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or optimizing performance, your help is appreciated.

Getting Started

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following our guidelines
Run tests and linting (cargo test && cargo clippy)
Submit a pull request

Code Standards

All contributions must:

Pass cargo clippy with zero warnings
Pass cargo test (all tests)
Include documentation for public APIs
Follow Rust API guidelines
Support cross-platform compilation where applicable

Development Workflow

# Check compilation
cargo check --workspace

# Run tests
cargo test --workspace

# Lint code
cargo clippy --workspace -- -D warnings

# Format code
cargo fmt --all

# Build release
cargo build --workspace --release

Areas for Contribution

Performance optimization: SIMD, GPU kernels, cache optimization
Platform support: Additional embedded targets (Teensy, Nordic nRF, RISC-V)
Neural algorithms: New plasticity rules, neuron models
Documentation: Examples, tutorials, API documentation
Testing: Edge cases, integration tests, benchmarks
Tools: Visualization, debugging, profiling utilities

Documentation

API Reference: docs.rs/feagi
Architecture Guide: docs/ARCHITECTURE.md

Generate local documentation:

cargo doc --open

Testing

# All tests
cargo test --workspace

# Specific crate
cargo test -p feagi-burst-engine

# With features
cargo test -p feagi-burst-engine --features gpu

# Benchmarks
cargo bench -p feagi-burst-engine

Platform Support

Tested Platforms

Desktop: Linux, macOS, Windows
Embedded: ESP32 (WROOM, S3, C3)
Cloud: Docker, Kubernetes

Planned Support

Arduino (Due, MKR, Nano 33 IoT)
STM32 (F4, F7, H7 series)
Teensy (4.0, 4.1)
Nordic nRF (nRF52, nRF53)
Raspberry Pi Pico (RP2040)

Use Cases

Robotics: Real-time control with adaptive learning
Edge AI: On-device intelligence for IoT
Research: Neuroscience modeling and experimentation
AGI Development: Evolutionary and developmental AI systems
Embedded Intelligence: Neural processing on microcontrollers

Project Status

Version: 0.0.1
Status: Active development
Minimum Rust Version: 1.75+

FEAGI Core is under active development. The core APIs are stabilizing, but breaking changes may occur in minor releases.

Community and Support

Discord: discord.gg/neuraville
Website: neuraville.com/feagi
Repository: github.com/feagi/feagi-core
Issues: GitHub Issues
Email: feagi@neuraville.com

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Citation

If you use FEAGI in your research, please cite:

@article{nadji2020brain,
  title={A brain-inspired framework for evolutionary artificial general intelligence},
  author={Nadji-Tehrani, Mohammad and Eslami, Ali},
  journal={IEEE transactions on neural networks and learning systems},
  volume={31},
  number={12},
  pages={5257--5271},
  year={2020},
  publisher={IEEE}
}

Built with Rust for performance, safety, and portability.

feagi 0.0.1-beta.4