FNSE - Fractal Neural Simulation Engine

Fractal Neural Simulation Engine

A production-grade, self-evolving multi-agent simulation framework with recursive skill compilation, graph-based memory, and enterprise safeguards.

Version 1.0.0

AGPL-3.0 License

Python 3.11+

FastAPI 0.109+

Redis 7.0+

Docker Ready

🏗️ The Five Engine Pillars

🏭 MacroSwarm

Hierarchical multi-agent orchestration with role-based agents (Explorer, Optimizer, Critic, Synthesizer, Coordinator), dynamic scaling, tick-based execution, and cross-agent consensus.

Graph-based retrieval-augmented generation with vector similarity search, knowledge graph traversal, entity linking, episodic memory, and semantic clustering.

⚙️ SkillCompiler

Recursive self-improving skill system with dynamic code generation, sandboxed execution, test-driven compilation, skill versioning, and dependency tracking.

🛡️ SafeguardSystem

Enterprise-grade safety with computational circuit breakers, divergence monitoring, automated state rollback, and multi-level alerting.

Full-featured FastAPI server with epoch lifecycle management, real-time WebSocket streaming, GraphRAG query interface, and skill compilation endpoints.

🚀 Quick Start

Get up and running in minutes with Docker:

# Clone and start
git clone https://github.com/nasirquant/fractal-neural-engine
cd fractal-neural-engine
docker-compose up -d

# Create your first epoch
curl -X POST http://localhost:8000/epochs \
  -H "Content-Type: application/json" \
  -d '{"num_agents": 10, "max_ticks": 100, "global_objective": "minimize_loss"}'

Requires: Python 3.11+, Redis, OpenAI API key (or Anthropic). See Environment Variables for full configuration.

📚 Documentation

5-Minute Quickstart

Install dependencies
```
pip install -r requirements.txt
```

Configure environment

cp .env.example .env
# Edit .env with your OPENAI_API_KEY

Start Redis

docker run -d -p 6379:6379 redis:7-alpine

Run the API server
```
python main.py
```

Create an epoch

curl -X POST http://localhost:8000/epochs \
  -H "Content-Type: application/json" \
  -d '{"num_agents": 10, "max_ticks": 100}'

Next: Explore Architecture or API Reference

System Architecture

FNSE follows a layered architecture:

Layer	Components
Client	CLI, REST API, Python SDK
Gateway	FastAPI, WebSocket, Auth
Core	MacroSwarm, Tick Scheduler, State Manager
Runtime	5 Agent Roles (Explorer, Optimizer, Critic, Synthesizer, Coordinator)
Intelligence	GraphRAG, SkillCompiler, LiteLLM Router
Safety	Circuit Breakers, Rollback, Alerting
Persistence	Redis Cache, Checkpoints

See Architecture Overview for detailed diagrams.

REST API Endpoints

Endpoint	Method	Description
`/epochs`	POST	Create new simulation epoch
`/epochs/{id}`	GET	Get epoch status
`/epochs/{id}/ticks`	GET	Stream tick events (WebSocket)
`/epochs/{id}/agents`	GET	List all agents
`/epochs/{id}/graph/query`	POST	Query GraphRAG
`/skills/compile`	POST	Compile new skill

Full docs: API Reference

Docker Deployment

# docker-compose.yml
services:
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]
  
  fnse-api:
    build: .
    ports: ["8000:8000"]
    environment:
      - REDIS_URL=redis://redis:6379/0
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on: [redis]

Production: See Monitoring for Prometheus/Grafana setup.

🔬 How It Works

The Simulation Loop

    graph LR
    A[Spawn Agents] --> B[Tick Scheduler]
    B --> C[Agent Think]
    C --> D[GraphRAG Query]
    D --> E[Skill Execute]
    E --> F[Message Pass]
    F --> G[Evaluate Loss]
    G --> H{Converged?}
    H -- No --> B
    H -- Yes --> I[Checkpoint & Exit]

Each epoch runs for max_ticks or until global loss converges below convergence_threshold. Agents operate in parallel, sharing knowledge through GraphRAG and evolving skills through the SkillCompiler.

🏢 Enterprise Ready

🔒 Circuit Breakers

Automatic failure isolation with configurable thresholds, half-open testing, and state-change callbacks.

📊 Observability

Prometheus metrics, Grafana dashboards, structured JSON logging, and distributed tracing ready.

🔄 Auto Rollback

Periodic checkpointing with instant rollback on divergence detection or critical alerts.

🌐 Multi-Model

LiteLLM router with fallback chains, cost tracking, and per-agent model selection.

📦 Skill Versioning

Git-like skill registry with semantic versioning, dependency graph, and rollback.

⚡ Horizontal Scale

Stateless agents, Redis-backed state, and Kubernetes-ready deployment manifests.

📖 Learn More

📖 Quickstart Guide

Step-by-step installation, configuration, and your first simulation run.

🏗️ Architecture Deep Dive

Detailed system design, data flows, and component interactions.

🔌 API Reference

Complete REST API documentation with request/response examples.

🏭 MacroSwarm Guide

Agent roles, tick lifecycle, message passing, and consensus protocols.

🧠 GraphRAG Guide

Knowledge graph operations, semantic search, and multi-hop reasoning.

⚙️ SkillCompiler Guide

Failure analysis, code generation, sandboxing, and skill lifecycle.

🛡️ Safeguards Guide

Circuit breakers, divergence monitoring, alerts, and rollback procedures.

📊 Monitoring & Observability

Prometheus metrics, Grafana dashboards, health checks, and alerting.

🤝 Community & Support

💬

Join the conversation:

GitHub Discussions — Ask questions, share ideas
Issues — Bug reports and feature requests
Discord — Real-time community chat (invite in repo)

⭐ GitHub Repository

Source code, releases, and issue tracker

💬 Discussions

Community Q&A, ideas, and showcases

📧 Enterprise Contact

Commercial licensing and support inquiries

📄 License

FNSE is licensed under AGPL-3.0 — free for commercial use, modification, and distribution. Network use requires source disclosure.

View License • Commercial Licensing

Built with ❤️ for the future of autonomous AI systems