nous

Distributed AI simulation platform combining Gray-Scott reaction-diffusion with neuroevolution and peer-to-peer networking.

GitLab Project Metadata:

• Description: Production-ready, secure, distributed AI simulation combining Gray-Scott reaction-diffusion with neuroevolution and peer-to-peer networking.
• Topics / Tags: crystal, crystal-lang, simulation, reaction-diffusion, turing-patterns, artificial-life, neuroevolution, distributed-systems, p2p, ipfs, rocm, hip, ameba

Vision

Nous is a production-grade distributed AI simulation platform that demonstrates the convergence of reaction-diffusion systems, neural evolution, and peer-to-peer networking. Built with Crystal's performance and safety guarantees, it serves as both a research tool and a reference implementation for distributed evolutionary algorithms.

What is Nous?

At its core, Nous simulates a Gray-Scott reaction-diffusion system—a mathematical model that produces Turing patterns through the interaction of two chemical substances. What makes Nous unique is the integration of four neural agents (Grok, Harper, Benjamin, Lucas) that evolve in real-time to optimize the beauty of emerging patterns.

Key Innovation

The platform employs adversarial neural evolution where:

• Generator agents (MLPs) perturb reaction-diffusion parameters to create novel patterns
• Discriminator networks evaluate pattern quality via mean squared error
• Collective intelligence emerges through horizontal gene transfer across the network
• Self-healing mechanisms ensure continuous operation and recovery from failures

Architecture

Core Components

Nous/
├── Core/
│   ├── Version          # Constants, PHI, configuration
│   ├── Types            # Data structures and type aliases
│   └── Errors           # Exception hierarchy
├── Neural/
│   ├── MLP              # StaticArray-based neural networks
│   ├── DiscriminatorMLP # Adversarial evaluation network
│   └── Agents           # MindAgent, DiscriminatorAgent
├── Security/
│   ├── GenomeValidator  # Input validation and sanitization
│   ├── RateLimiter      # Token bucket rate limiting
│   └── PeerAuth         # Peer whitelist/blacklist
├── Network/
│   ├── NoosphereNetwork # LAN peer discovery (UDP)
│   └── IPFSClient       # Global peer discovery
├── Simulation/
│   ├── GrayScottSimulation  # Reaction-diffusion engine
│   └── Orchestrator         # Main simulation controller
└── Web/
    └── Dashboard        # WebSocket-powered visualization

Neural Network Architecture

Generator MLP (4→2→2):

• Input: Cell state (u, v) + Laplacians (lap_u, lap_v)
• Hidden: 2 neurons with tanh activation
• Output: Feed rate (F) and kill rate (K) perturbations
• Memory: Zero-allocation using StaticArray

Discriminator MLP (9→6→1):

• Input: 3×3 image patches
• Hidden: 6 neurons with tanh activation
• Output: Center pixel prediction
• Purpose: Evaluate pattern complexity via prediction error

Security Features

• Genome Validation: Strict dimensional and range checking on received genomes
• Rate Limiting: Token bucket algorithm prevents DoS (30 req/min default)
• Peer Authentication: Whitelist/blacklist with CIDR-based network filtering
• Input Sanitization: Clamps extreme values, validates JSON structure
• Challenge-Response: Optional peer challenge mechanism

Installation

Prerequisites

• Crystal >= 1.21.0
• Optional: IPFS daemon for global connectivity
• Optional: ROCm/HIP for AMD GPU acceleration

Quick Start

# Clone repository
git clone git@gitlab.com:renich/nous.git
cd nous

# Install dependencies
shards install

# Build release binary
make build

# Run simulation
./bin/nous

ROCm GPU Acceleration

# Fedora/RHEL
sudo dnf install rocm-hip rocm-hip-devel

# Build with GPU support
ROCM=1 make build

Usage

Basic Usage

# Run with defaults (port 1618)
./bin/nous

# Custom port
NOUS_PORT=8080 ./bin/nous

# Multiple instances (auto-discovery)
./bin/nous                    # Terminal 1: Port 1618
NOUS_PORT=1619 ./bin/nous     # Terminal 2: Port 1619

Web Dashboard

Access the visualization at: http://localhost:1618

Features:

• Real-time pattern rendering via WebSocket
• Agent performance metrics
• Network peer status
• System health indicators

Configuration

Environment variables:

Configuration file (config/nous.yml):

simulation:
  grid_size: 192
  steps_per_frame: 12
  save_interval: 1800

security:
  max_peers_per_minute: 30
  allowed_networks:
    - "127.0.0.1/8"
    - "10.0.0.0/8"
    - "192.168.0.0/16"

Evolution Mechanics

Hill-Climbing with Adaptive Threshold

1. Backup current agent weights
2. Apply scaled mutation (Gaussian noise)
3. Run simulation for evaluation period
4. Calculate Exponential Moving Average (EMA) of beauty
5. Accept mutation if: gain ≥ 1% or beauty < 0.01 (escape hatch)
6. Revert if: fitness decline without escape threshold

Pattern Quality Metrics

• Pattern Density: Sum of spatial gradients (edges, not variance)
• Entropy: Shannon entropy of pixel intensity distribution
• Synergy Score: Weighted combination of density and entropy
• MSE: Discriminator prediction error (adversarial fitness)

Horizontal Gene Transfer

When peers discover each other:

1. Exchange genome pairs (generator + discriminator)
2. Validate received genomes for security
3. Inject into weakest local agent
4. Test for ≥1% local fitness improvement
5. Accept if beneficial, revert if not

Development

Project Structure

nous/
├── src/
│   ├── nous.cr              # Entry point
│   └── nous/
│       ├── core/            # Configuration, types, errors
│       ├── neural/          # Neural network implementations
│       ├── security/        # Validation, rate limiting, auth
│       ├── network/         # P2P networking
│       ├── simulation/      # Gray-Scott engine
│       └── web/             # Dashboard server
├── spec/                    # Test suite
├── config/                  # Configuration templates
└── scripts/                 # Helper scripts

Running Tests

# Run all tests
crystal spec

# Run specific test file
crystal spec spec/nous/neural/mlp_spec.cr

# With verbose output
crystal spec -v

Code Quality

# Format code
crystal tool format src/

# Run linter
make lint

# Type checking
crystal build src/nous.cr --no-codegen

Performance

• Simulation: 60 FPS at 192×192 resolution (single core)
• Neural Inference: Zero-allocation StaticArray operations
• Parallel Processing: Worker fiber pool with pre-spawned threads
• Network: Asynchronous UDP gossip with connection pooling
• Memory: < 50MB baseline, scales with grid size

API Reference

See the API Documentation for detailed module interfaces.

Contributing

See CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes with tests
4. Run test suite (make test)
5. Commit with clear messages
6. Push and create Pull Request

Security

Reporting Vulnerabilities

Please report security issues to: security@evalinux.com

Do not open public issues for security bugs.

Security Features

• Input validation on all network-received data
• Rate limiting prevents DoS attacks
• Peer authentication with challenge-response
• CIDR-based network filtering
• Genome sanitization prevents code injection

License

GPLv3 - See LICENSE file

Roadmap

Version 0.3.0

• Kubernetes deployment manifests
• Prometheus metrics export
• Distributed checkpoint synchronization
• Advanced genome compression

Version 0.4.0

• WASM browser client
• 3D reaction-diffusion extension
• Multi-species competitive evolution
• Academic paper publication

Authors

• Rénich Bon Ćirić renich@woralelandia.com — Creator & Lead Architect
• AI Collaborators — Grok, GLM 5, Gemini 3 Pro, Kimi k2.5

Acknowledgments

Built with:

• Crystal Language — Fast, type-safe, beautiful
• Gray-Scott Model — Mathematical elegance
• Reaction-Diffusion research community

Nous — Mathematics contemplating itself