NEURAX

The Analytical Compiler for Neural Architectures

NEURAX predicts the cost, memory, and performance of neural network architectures before training — in under 50 ms, with zero GPU, and fully deterministically.

• Live Demo
• GitHub Repository
• Releases

About

NEURAX is an analytical compiler for neural network architectures. Whereas training frameworks (PyTorch, TensorFlow) execute models and runtime compilers (IREE, OpenXLA) lower them for execution, NEURAX operates at design time: it answers the questions you need resolved before committing GPU resources.

• Will this architecture fit in VRAM?
• What is the training cost on 8x H100?
• Where are the memory bottlenecks?
• Is inference stable? What is the hallucination risk?
• Which parallelism strategy is optimal?

All in under 50 ms. Zero GPU required. Fully deterministic.

Key capabilities

• 11 architecture families — Transformer, CNN, MoE, SSM, Diffusion, GNN, GAN, RL, SNN, RNN, Experimental.
• 680+ configurable blocks and 88 reference templates.
• 10-pass analytical IR pipeline producing 55+ metrics.
• MLIR / LLVM 18 compiler backend with 13 custom dialects.
• Visual design canvas, AI copilot agent, Inference Intelligence and Time Machine.
• Export to PyTorch, ONNX, Triton, MLIR, Rust/Burn, JSON and Network Graph.

Documentation

Use the sidebar to navigate the full documentation set. Start with the Architecture & Design chapter to understand how NEURAX works internally, then the API Reference and Deployment Guide to run it yourself.

NEURAX Architecture Design

This document describes the architecture, design principles, and data flow of the NEURAX compiler system.

Table of Contents

1. Overview
2. System Architecture
3. Data Flow
4. Component Deep Dive
5. Design Principles
6. Adding a New Model Family

Overview

NEURAX is an analytical compiler for neural network architectures. Unlike traditional compilers that emit machine code, NEURAX emits a complete engineering report of a model’s behaviour on target hardware — cost, memory, speed, safety, and feasibility — in milliseconds, before a single GPU spins up.

The system is composed of:

System Architecture

graph TB
    subgraph "Frontend"
        UI[neurax-ui<br/>React 18 + TypeScript]
        TUI[neurax-tui<br/>Ratatui]
        CLI[neurax-cli<br/>Rust CLI]
    end

    subgraph "Service Layer"
        HTTP_API[neurax-service<br/>actix-web HTTP API<br/>38 REST routes]
        AI_AGENT[neurax-agent<br/>FastAPI + LangChain<br/>Natural language → architecture]
        MCP[neurax-mcp<br/>MCP server]
    end

    subgraph "Core Engine"
        CORE[neurax-core<br/>Pipeline orchestrator<br/>+ ONNX export + streaming]
        PARSER[neurax-parser<br/>JSON → ModelConfig]
        IR[neurax-ir<br/>10 IR dialects<br/>+ inference + dynamic passes]
        FORMULAS[neurax-formulas<br/>FLOPs / params / memory]
        HWDB[neurax-hardware-db<br/>20 GPUs • CPUs • interconnects]
        MLIR[neurax-mlir<br/>13 MLIR dialects<br/>LLVM 18 • IREE]
    end

    subgraph "External Services"
        SUPABASE[Supabase<br/>Auth • Database • Storage]
        STRIPE[Stripe<br/>Billing • Subscriptions]
        OPENAI[OpenAI / Anthropic<br/>LLM API]
        GITHUB[GitHub<br/>Repository • Pull Requests]
    end

    UI -- HTTP --> HTTP_API
    TUI -- direct --> CORE
    CLI -- direct --> CORE
    MCP -- HTTP --> HTTP_API

    AI_AGENT -- HTTP --> HTTP_API
    AI_AGENT -- LLM --> OPENAI

    HTTP_API --> CORE
    CORE --> PARSER
    CORE --> IR
    CORE --> FORMULAS
    CORE --> HWDB
    CORE --> MLIR

    HTTP_API -- JWT --> SUPABASE
    HTTP_API -- Billing --> STRIPE
    HTTP_API -- GitHub push --> GITHUB

    style CORE fill:#2ecc71,color:#fff
    style IR fill:#3498db,color:#fff
    style MLIR fill:#e74c3c,color:#fff
    style UI fill:#9b59b6,color:#fff
    style AI_AGENT fill:#f39c12,color:#fff

Data Flow

The primary data flow for architecture analysis:

flowchart LR
    INPUT["User Request<br/>(JSON model config)"] --> PARSER["Parser<br/>neurax-parser"]
    PARSER --> AST["ModelConfig<br/>Typed AST"]
    AST --> PIPELINE["Analytical IR Pipeline<br/>10 passes"]

    subgraph PIPELINE_CONTENT [" "]
        direction LR
        A["Arch.<br/>IR"] --> G["Graph<br/>IR"] --> T["Tensor<br/>IR"] --> O["Op<br/>IR"] --> C["Compute<br/>IR"]
        C --> M["Memory<br/>IR"] --> P["Parall.<br/>IR"] --> H["Hardware<br/>IR"] --> CO["Cost<br/>IR"] --> R["Report<br/>IR"]
    end

    PIPELINE --> REPORT["Report<br/>40+ metrics<br/>JSON / Markdown"]
    PIPELINE --> MLIR_OUT["NEURAX-MLIR<br/>model.mlir"]
    MLIR_OUT --> LLVM["LLVM 18 / IREE<br/>CPU • CUDA • ROCm<br/>Metal • Vulkan"]

    style INPUT fill:#4a90d9,color:#fff
    style REPORT fill:#2ecc71,color:#fff
    style MLIR_OUT fill:#e74c3c,color:#fff

The 10-Pass IR Pipeline

Each pass transforms the representation and computes metrics:

Dynamic Analysis (Parallel, Post-Pipeline)

Three dynamic passes run in parallel after the static pipeline:

Component Deep Dive

neurax-parser

The parser ingests JSON model configurations conforming to the NEURAX universal schema (v1.0) and produces a strongly-typed ModelConfig.

Key types:

• ModelConfig — top-level configuration (model, training, hardware, parallelism)
• ModelType enum — Transformer, CNN, MoE, SSM, Diffusion, GNN, GAN, RL, SNN, RNN, Multimodal, Custom
• LayerType enum — Attention, Mlp, Embedding, Conv2d, etc.
• Schema validation via ModelValidator

Supported model types: transformer, cnn, moe, ssm, diffusion, gnn, gan, rl, snn, rnn, multimodal, custom

neurax-ir

The IR crate implements 10 dialect-like modules, each with its own Pass struct implementing the IrPass trait:

#![allow(unused)]
fn main() {
pub trait IrPass {
    type Input;
    type Output;
    type Metrics;

    fn build(&self, input: &Self::Input, ctx: &NeuraxContext) -> Result<Self::Output, NeuraxError>;
    fn compute_metrics(&self, output: &mut Self::Output, ctx: &NeuraxContext) -> Result<Self::Metrics, NeuraxError>;
    fn validate(&self, output: &Self::Output, metrics: &Self::Metrics) -> Result<(), NeuraxError>;
}
}

Diagnostic system: Standardized diagnostic codes (E001-E005 errors, W001-W006 warnings, I001-I003 info, H001-H005 hints) with severity levels and precision impact scoring.

neurax-core

The orchestrator that wires together the 10-pass pipeline, dynamic analysis, and export. Also provides:

• run_analysis() — full pipeline entry point
• analyze_json() — JSON string → AnalysisResult
• validate_json() — JSON validation
• get_model_summary() — quick model summary
• ONNX export via neurax-core/src/export/

neurax-mlir

MLIR compiler backend with 13 custom dialects:

Lowering pipeline: Architecture → Graph → Tensor → Operator → Compute → Memory → Hardware → Cost → Report → LLVM IR → Assembly → Object file.

Target backends: CPU, CUDA, Vulkan, Metal, ROCm — plus IREE integration for cross-platform deployment.

neurax-formulas

Pure analytical formulas for ML operations. Hot path — maximum optimization.

Modules: attention, conv, mlp, embedding, normalization, moe, ssm, rnn, diffusion, gnn, custom, cnn_blocks.

neurax-hardware-db

Built-in database with 20 GPUs, 2 CPUs, and 5 interconnect specifications.

GPU specs include: H200, GH200, H100-SXM, H100-PCIe, A100-SXM, A100-PCIe, L40S, L40, V100, RTX 4090, RTX 4080, RTX 3090, RTX 6000 Ada, RTX A5000, A10G, A30, T4, K80.

Key metrics per GPU: TFLOPS (FP64/FP32/FP16/BF16/INT8/FP8), memory bandwidth, NVLink, TDP, L2 cache, SM count.

neurax-service

Production actix-web HTTP server with:

• 38 REST routes (analysis, inference, export, projects, billing, credits, compliance, API keys, agent control, presets, hardware, plugin)
• Supabase JWT authentication + API key authentication with scope-based authorization
• Stripe billing integration
• SSE streaming for real-time analysis
• CORS, gzip compression
• Health checks

neurax-agent

Python/FastAPI/LangChain AI copilot with a 3-phase declarative pipeline:

1. Planning — LLM generates a complete ArchSpec (nodes + edges) using structured output
2. Validation — Pure Python topology validator checks DAG, fan-in, connectivity
3. Materialization — Stream tool calls to the canvas with auto-correction (up to 3 retries)

Supports 11 model families with catalogues containing 400+ blocks.

neurax-ui

React 18 + TypeScript + Vite single-page application with:

• Visual canvas (React Flow) with drag-and-drop, parameter editing, minimap
• 88 reference templates across 11 families
• Metrics dashboard with 40+ metrics and charts
• AI Chat Drawer with SSE streaming
• Hyperparameter Optimization panel
• Time Machine cost/carbon projection
• Inference Intelligence panel
• Project management (cloud CRUD)
• Credits system with plan-based limits
• Export panel (ONNX, JSON, Network Graph)
• GitHub export with PR creation

neurax-mcp

Model Context Protocol server that exposes NEURAX capabilities to MCP-compatible clients (e.g., Claude Desktop). Provides 9 tools: analyze_architecture, list_templates, get_template, list_hardware, estimate_training_cost, get_compliance_config, get_credits, get_user_info, health_check.

Design Principles

1. Analytical, not empirical — All metrics are computed via pure analytical formulas. No GPU is needed, no simulation is run. Results are deterministic and available in milliseconds.

2. Compiler-inspired pipeline — The system follows the traditional compiler architecture: parse → IR → optimize → generate. Each pass is independent and composable.

3. Multi-language ecosystem — Rust for performance-critical analysis, Python for the AI agent, TypeScript for the web UI. Each language is chosen for its strengths.

4. Schema-first design — The JSON model config schema (v1.0) is the universal interchange format. All components read from and write to this schema.

5. Deterministic by default — The core analysis pipeline is fully deterministic. The AI agent uses LLMs but validates every output before materialization.

6. Extensible catalogues — Model families, blocks, and constraints are defined in JSON catalogues that can be extended without code changes.

7. Observability-first — Every analysis includes phase timing, diagnostics, and recommendations. The system explains not just what the metrics are, but why.

Adding a New Model Family

To add a new model family to NEURAX:

1. Add to the Rust parser

In neurax-parser/src/model_config.rs, add the new family to ModelType::from_str():

#![allow(unused)]
fn main() {
"my_family" => Ok(Self::MyFamily),
}

Add the corresponding serialization:

#![allow(unused)]
fn main() {
Self::MyFamily => "my_family",
}

2. Add formulas

In neurax-formulas/src/, create a new module (e.g., my_family.rs) with FLOPs, parameter, and memory formulas. Register it in lib.rs.

3. Add catalogue entries

In neurax-agent/catalogue.json, add blocks for the new family. Each block should include type, name, family, params, description, and max_inputs.

4. Add template

In templates.ts, add reference templates for the new family.

5. Add constraints

In neurax-agent/block_constraints.json, add fan-in limits for the new family’s blocks.

6. Add to arch_planner

In neurax-agent/arch_planner.py, add a family template in FAMILY_TEMPLATES describing the typical flow for the new family.

NEURAX API Reference

neurax-service is a production actix‑web HTTP server (default 0.0.0.0:9098) exposing 38 REST routes with CORS, gzip compression, and authentication via Supabase JWT or API keys.

Base URL

http://localhost:9098

Authentication

Two authentication methods are supported:

1. Supabase JWT (Web UI Users)

Pass a valid Supabase access token in the Authorization header:

Authorization: Bearer <supabase-jwt>

2. API Keys (Programmatic Access)

Pass an API key (prefixed with nrx_) in either the X-API-Key header or the Authorization: Bearer header:

X-API-Key: nrx_<64-hex-chars>

API Key Scopes

Error Codes

Endpoint Summary

System

Analysis

Inference

Time Machine

Export

Presets

Hardware

Projects

Credits & Billing

Compliance

API Keys

Agent Control (API Key Auth)

Plugin

Endpoint Details

GET /health

Health check endpoint. No authentication required.

Response 200 OK:

{
  "status": "ok"
}

POST /analyze

Run the full 10‑pass analytical pipeline on a model configuration.

Request Body:

{
  "topology": {
    "schema_version": "1.0",
    "model": {
      "name": "MyModel",
      "type": "transformer",
      "global_params": {
        "num_layers": 12,
        "sequence_length": 2048,
        "vocab_size": 50257,
        "embedding_dim": 768
      },
      "layers": [
        {
          "id": "layer_1",
          "layer_type": "embedding",
          "params": {
            "vocab_size": 50257,
            "embedding_dim": 768
          }
        }
      ]
    },
    "training": {
      "batch_size": 128,
      "max_steps": 100000
    },
    "hardware": {
      "gpus": [
        {"name": "A100-SXM", "count": 8}
      ]
    }
  }
}

Response 200 OK:

{
  "report": {
    "model_name": "MyModel",
    "total_parameters": 125000000,
    "total_flops": 2.5e17,
    "peak_vram_bytes": 42000000000,
    "training_cost_usd": 45000.00,
    "training_time_hours": 120.5,
    "energy_kwh": 15000.0,
    "co2_kg": 4500.0,
    "metrics": { },
    "diagnostics": [ ],
    "phase_timeline": [ ]
  }
}

Error Responses:

POST /analyze/stream

Start a streaming analysis job. Returns a job ID for SSE streaming.

Request Body (same as /analyze).

Response 200 OK:

{
  "job_id": "abc123-...",
  "status": "running"
}

GET /analyze/stream/{job_id}

Stream Server‑Sent Events for a running analysis job.

Response text/event-stream:

event: phase
data: {"phase": "Architecture", "status": "running", "progress": 10}

event: metric
data: {"name": "total_parameters", "value": 125000000, "unit": "params"}

event: done
data: {"job_id": "abc123-...", "status": "completed"}

GET /analyze/result/{job_id}

Retrieve the completed analysis report for a job.

Response 200 OK:

{
  "job_id": "abc123-...",
  "status": "completed",
  "report": { }
}

POST /analyze/compare

Compare up to 8 hardware configurations for the same model.

Request Body:

{
  "topology": { },
  "configs": [
    {
      "hardware": "H100-SXM",
      "gpu_count": 8,
      "precision": "fp16",
      "gpu_memory_gb": 80,
      "gpu_bandwidth_gbs": 3352.0
    },
    {
      "hardware": "A100-SXM",
      "gpu_count": 8,
      "precision": "bf16",
      "gpu_memory_gb": 80,
      "gpu_bandwidth_gbs": 2039.0
    }
  ]
}

Response 200 OK:

{
  "results": [
    {
      "label": "8 × H100-SXM @ fp16",
      "report": { }
    },
    {
      "label": "8 × A100-SXM @ bf16",
      "report": { }
    }
  ]
}

POST /inference/simulate

Simulate inference behavior for a model configuration.

Request Body:

{
  "topology": { },
  "params": {
    "model_name": "MyModel",
    "num_layers": 12,
    "d_model": 768,
    "num_heads": 12,
    "seq_len": 2048,
    "vocab_size": 50257,
    "batch_size": 1,
    "precision": "fp16",
    "hardware": "A100-SXM"
  }
}

Response 200 OK:

{
  "report": {
    "model_name": "MyModel",
    "stability_index": 0.85,
    "hallucination_risk": 0.12,
    "sampling_volatility": 0.05,
    "latency_ms": 12.5,
    "throughput_tokens_per_s": 800.0
  }
}

POST /timemachine

Multi‑year cost/carbon projection.

Request Body:

{
  "topology": { },
  "years": 5,
  "hardware_growth_rate": 0.15,
  "energy_cost_per_kwh": 0.12,
  "carbon_intensity_g_per_kwh": 475
}

Response 200 OK:

{
  "projections": [
    {
      "year": 2026,
      "training_cost_usd": 45000.0,
      "energy_kwh": 15000.0,
      "co2_kg": 4500.0
    }
  ],
    "compliance": { }
}

POST /export/onnx

Export a model topology to ONNX binary format.

Request Body:

{
  "topology": { },
  "model_name": "MyModel"
}

Response 200 OK:

{
  "data": "<base64-encoded-onnx-protobuf>",
  "model_name": "MyModel",
  "node_count": 12
}

POST /export/github

Push model files to a GitHub repository and optionally create a pull request.

Request Body:

{
  "topology": { },
  "github_token": "<personal-access-token>",
  "owner": "username",
  "repo": "repo-name",
  "branch": "main",
  "create_pr": true,
  "pr_title": "Add MyModel architecture",
  "pr_body": "Auto-generated by NEURAX"
}

Response 200 OK:

{
  "success": true,
  "commit_sha": "abc123...",
  "pr_url": "https://github.com/username/repo-name/pull/1"
}

GET /projects

List all projects for the authenticated user.

Response 200 OK:

[
  {
    "id": "proj_123",
    "name": "My Project",
    "description": "A transformer model",
    "topology": { },
    "created_at": "2026-07-24T10:00:00Z",
    "updated_at": "2026-07-24T10:00:00Z"
  }
]

POST /projects

Create a new project.

Request Body:

{
  "name": "My Project",
  "description": "A transformer model",
  "topology": { }
}

Response 200 OK:

{
  "id": "proj_123",
  "name": "My Project",
  "description": "A transformer model",
  "topology": { },
  "created_at": "2026-07-24T10:00:00Z",
  "updated_at": "2026-07-24T10:00:00Z"
}

GET /credits

Get the current user’s credit balance and plan information.

Response 200 OK:

{
  "credits": {
    "used": 150,
    "limit": 1000,
    "plan": "elite",
    "period_start": "2026-07-01T00:00:00Z",
    "period_end": "2026-08-01T00:00:00Z"
  }
}

GET /compliance/config

Get regulatory compliance configuration (EU AI Act, CSRD, DSA).

Response 200 OK:

{
  "eu_ai_act": { },
  "csrd": { },
  "dsa": { }
}

API Key Management

POST /api-keys

Create a new API key.

Request Body:

{
  "name": "My API Key",
  "scopes": ["analyze", "inference", "export"]
}

Response 200 OK:

{
  "key": "nrx_abc123...",
  "name": "My API Key",
  "user_id": "user_123",
  "created_at": "2026-07-24T10:00:00Z",
  "active": true,
  "scopes": ["analyze", "inference", "export"]
}

GET /api-keys

List all API keys for the current user.

POST /api-keys/{key_id}/revoke

Revoke (deactivate) an API key.

DELETE /api-keys/{key_id}

Delete (permanently remove) an API key.

POST /plugin/validate

Validate a plugin architecture specification.

Request Body:

{
  "topology": { }
}

Response 200 OK:

{
  "valid": true,
  "warnings": [],
  "errors": []
}

Python Agent API

The neurax-agent (FastAPI, port 8099) provides a separate API for AI‑driven architecture design.

POST /runs

Start a new agent run. The agent uses an LLM (OpenAI or Anthropic) to plan, validate, and materialize an architecture.

Request Body:

{
  "user_message": "Design a transformer model with 12 layers for text classification",
  "snapshot": {
    "family": "transformer",
    "nodes": [],
    "connections": [],
    "groups": [],
    "allowed_layer_types": [],
    "allowed_families": ["transformer", "cnn", "moe"],
    "catalogue_id": null,
    "catalogue": [],
    "missing_mandatory_fields": [],
    "hw_config": {},
    "analysis_warnings": []
  },
  "creativity": 0.3
}

Response 200 OK:

{
  "run_id": "abc123-..."
}

GET /runs/{run_id}/events

Stream Server‑Sent Events for an agent run.

Response text/event-stream:

event: assistant
data: {"content": "I'll design a transformer architecture for you..."}

event: tool
data: {"name": "add_node", "args": {"id": "input", "type": "input", "params": {}}}

event: done
data: {}

GET /health

Agent health check.

Response 200 OK:

{
  "status": "ok"
}

CLI Interface

The neurax CLI provides command‑line access to the core analysis pipeline.

# Analyze a model and generate a report
neurax analyze model.json -o report.md

# Analyze with JSON output
neurax analyze model.json -f json -o report.json

# Validate a JSON model configuration
neurax validate model.json

# Show a quick summary of the model
neurax summary model.json

# Full compilation: validate → analyze → generate MLIR
neurax compile model.json -o output/

# Show version
neurax version

Compile Output

The compile command generates:

MCP Server

The neurax-mcp package provides a Model Context Protocol server that exposes NEURAX capabilities to MCP‑compatible clients (e.g., Claude Desktop).

Available Tools

Deployment Guide

This guide covers how to deploy NEURAX in development and production environments.

Table of Contents

1. Quick Deploy (Docker Compose)
2. Development Setup
3. Production Deployment
4. Environment Variables
5. Health Checks
6. Troubleshooting

Quick Deploy (Docker Compose)

The fastest way to run all NEURAX services locally is via Docker Compose.

Prerequisites

• Docker Engine 24+
• Docker Compose v2+

Steps

# 1. Clone the repository
git clone https://github.com/rustnew/NEURAX.git
cd NEURAX

# 2. Configure environment files
cp neurax-service/.env.example neurax-service/.env
cp neurax-ui/.env.example neurax-ui/.env
cp neurax-agent/.env neurax-agent/.env  # Already exists, adjust as needed

# 3. Start all services
docker compose up

# 4. Verify
curl http://localhost:9098/health
curl http://localhost:8099/health
# Open http://localhost:8081 in your browser

Services

Stopping

docker compose down

Development Setup

For active development, run each service locally without Docker.

Option A: All-in-One Script

# Clone and enter the repo
git clone https://github.com/rustnew/NEURAX.git
cd NEURAX

# Run the development startup script
chmod +x start-dev.sh
./start-dev.sh

The start-dev.sh script launches all three services in the background:

• Rust backend (neurax-service) on port 9098
• Python agent (neurax-agent) on port 8099
• React frontend (neurax-ui) on port 8081

Option B: Manual Setup

1. Rust Backend (neurax-service)

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Run the service
cargo run -p neurax-service
# → http://localhost:9098

2. Python Agent (neurax-agent)

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r neurax-agent/requirements.txt

# Set environment variables
export OPENAI_API_KEY="sk-..."  # Or ANTHROPIC_API_KEY
export NEURAX_AGENT_HOST=127.0.0.1
export NEURAX_AGENT_PORT=8099

# Run the agent
cd neurax-agent
python3 -m uvicorn app:app --host 127.0.0.1 --port 8099 --reload
# → http://localhost:8099

3. React Frontend (neurax-ui)

# Install dependencies
cd neurax-ui
npm install  # or: pnpm install

# Configure environment
cp .env.example .env
# Edit .env:
#   VITE_SUPABASE_DISABLED=true
#   VITE_NEURAX_API_URL=http://127.0.0.1:9098
#   VITE_AGENT_BASE_URL=http://127.0.0.1:8099

# Start the dev server
npm run dev
# → http://localhost:8081

4. MCP Server (neurax-mcp)

# Install
pip install -e neurax-mcp

# Run (stdio mode, configured in Claude Desktop's claude_desktop_config.json)
# See: https://modelcontextprotocol.io/docs/develop/server

Production Deployment

Docker Compose (Recommended)

# 1. Create production .env files
cp neurax-service/.env.example neurax-service/.env
# Edit with real Supabase URL, Stripe keys, etc.

cp neurax-ui/.env.example neurax-ui/.env
# Set VITE_NEURAX_API_URL and VITE_AGENT_BASE_URL to production URLs

cp neurax-agent/.env neurax-agent/.env
# Set OPENAI_API_KEY or ANTHROPIC_API_KEY

# 2. Build and start
docker compose up -d

# 3. Verify health
./healthcheck.sh

Docker Build (Individual Services)

# Build the Rust service
docker build -t neurax-service -f Dockerfile .

# Build the UI
docker build -t neurax-ui -f Dockerfile.ui .

# Build the agent
docker build -t neurax-agent -f Dockerfile.agent .

Kubernetes

A Kubernetes deployment manifest is planned. For now, use Docker Compose with a reverse proxy (nginx/Caddy) for TLS termination and load balancing.

Example nginx reverse proxy config:

server {
    listen 443 ssl http2;
    server_name neurax.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
    }

    location /api/ {
        proxy_pass http://localhost:9098/;
        proxy_set_header Host $host;
    }

    location /agent/ {
        proxy_pass http://localhost:8099/;
        proxy_set_header Host $host;
    }
}

Environment Variables

neurax-service

neurax-agent

neurax-ui

Health Checks

Use the included health check script to verify all services are running:

./healthcheck.sh

Expected output:

[✓] neurax-service (port 9098): healthy
[✓] neurax-agent (port 8099): healthy
[✓] neurax-ui (port 8081): healthy

Troubleshooting

Port Already in Use

# Check what's using a port
lsof -i :9098

# Kill the process
kill -9 <PID>

Docker Build Fails (MLIR)

The MLIR backend requires LLVM 18. If you don’t need MLIR code generation, build without the mlir feature:

cargo build -p neurax-service  # Without MLIR
# Or with MLIR (requires LLVM 18):
sudo apt install llvm-18 llvm-18-dev libmlir-18-dev mlir-18-tools
export LLVM_SYS_180_PREFIX=/usr/lib/llvm-18
export MLIR_SYS_180_PREFIX=/usr/lib/llvm-18
cargo build -p neurax-service --features mlir

Agent LLM Not Responding

Ensure OPENAI_API_KEY or ANTHROPIC_API_KEY is set in neurax-agent/.env.

Supabase Connection Issues

Verify SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are set correctly in neurax-service/.env.

🚀 NEURAX 2.0 - Roadmap Stratégique

Date : 31 Juillet 2026
Version Actuelle : 0.6.3
Version Cible : 2.0
Horizon : 24 mois (2026-2028)

🎯 Vision NEURAX 2.0

“Le Figma de l’Intelligence Artificielle”

Transformer NEURAX d’un design tool excellent en une plateforme end-to-end pour la recherche et le déploiement d’architectures IA.

Mission Statement

Permettre à tout chercheur/ingénieur ML de :

1. Designer une architecture en quelques minutes
2. Valider sa faisabilité instantanément (coût, mémoire, performance)
3. Prototyper avec export automatique vers PyTorch/HuggingFace
4. Collaborer en temps réel avec son équipe
5. Déployer en un clic vers le cloud
6. Apprendre de chaque run pour améliorer les prédictions

📊 État Actuel vs Vision 2.0

Priorités :

• P0 : Critique pour crédibilité (Validation)
• P1 : Haute valeur ajoutée (Export, Training, Learning)
• P2 : Différenciation importante (Collaboration, Cloud, Community)
• P3 : Nice-to-have (Mobile, Education)

🗺️ Roadmap par Phase (24 mois)

gantt
    title NEURAX 2.0 Development Roadmap
    dateFormat YYYY-MM
    
    section Phase 1: Validation ✅
    Benchmark Suite             :p1a, 2026-08, 3M
    Dataset Training Costs      :p1b, 2026-08, 3M
    Research Paper              :p1c, 2026-09, 4M
    
    section Phase 2: Training Integration 🔧
    PyTorch Export              :p2a, 2026-11, 3M
    HuggingFace Integration     :p2b, 2026-12, 2M
    Real-time Monitoring        :p2c, 2027-01, 4M
    Learning Loop               :p2d, 2027-03, 3M
    
    section Phase 3: Collaboration 🤝
    Template Hub                :p3a, 2027-02, 3M
    Multi-user Editing (CRDT)   :p3b, 2027-04, 4M
    Comments & Reviews          :p3c, 2027-06, 2M
    
    section Phase 4: Intelligence 🧠
    Auto-optimization Engine    :p4a, 2027-06, 4M
    What-If Analysis            :p4b, 2027-08, 3M
    Neural Architecture Search  :p4c, 2027-09, 4M
    
    section Phase 5: Cloud & Deploy ☁️
    AWS/GCP/Azure Integration   :p5a, 2027-08, 4M
    Production Monitoring       :p5b, 2027-10, 3M
    Auto-scaling                :p5c, 2028-01, 2M
    
    section Phase 6: Ecosystem 🌍
    Mobile Apps (iOS/Android)   :p6a, 2027-11, 5M
    Education Mode              :p6b, 2028-02, 3M
    API Marketplace             :p6c, 2028-04, 3M

📦 Délivrables par Phase

Phase 1 : Validation & Crédibilité (Mois 1-4)

Objectif : Prouver scientifiquement que NEURAX est précis

Délivrables :

• Benchmark suite publique (100+ modèles)
• Dataset de training costs réels
• Paper académique (NeurIPS/ICML)
• Dashboard de validation public

KPIs :

• 95%+ accuracy confirmée sur benchmark
• 1,000+ citations du paper (12 mois post-publication)
• 50+ researchers contribuant au dataset

Phase 2 : Training Integration (Mois 5-11)

Objectif : NEURAX devient compagnon de training, pas juste design tool

Délivrables :

• .to_pytorch() export automatique
• HuggingFace Trainer integration
• Real-time monitoring pendant training
• Learning loop (calibration automatique)

KPIs :

• 70% des users exportent vers PyTorch
• 5% réduction d’erreur de prédiction via learning loop
• 10,000+ modèles trackés en training

Phase 3 : Collaboration (Mois 6-13)

Objectif : Devenir le “Figma de l’IA”

Délivrables :

• Template Hub (community templates)
• Real-time co-editing (CRDT)
• Comments, reviews, versions
• Team workspaces

KPIs :

• 5,000+ templates community
• 30% des sessions sont multi-user
• 50+ entreprises avec team plans

Phase 4 : Intelligence (Mois 12-17)

Objectif : NEURAX propose des optimisations automatiques

Délivrables :

• Auto-optimization engine
• What-if analysis (“change X → gain Y”)
• Neural Architecture Search intégré
• Recommendation system

KPIs :

• 80% des suggestions acceptées par users
• 20% amélioration coût moyen via auto-optim
• 1,000+ architectures découvertes par NAS

Phase 5 : Cloud & Deploy (Mois 14-20)

Objectif : Du design au déploiement en un clic

Délivrables :

• AWS SageMaker integration
• GCP Vertex AI integration
• Azure ML integration
• Production monitoring dashboard
• Auto-scaling policies

KPIs :

• 40% des users déploient via NEURAX
• 99.9% uptime monitoring
• $10M+ infrastructure managée

Phase 6 : Ecosystem (Mois 15-24)

Objectif : Construire un écosystème complet

Délivrables :

• Mobile apps (iOS/Android)
• Education mode + certifications
• API marketplace (plugins tiers)
• NEURAX Conference annuelle

KPIs :

• 100,000+ app downloads
• 10,000+ certifications délivrées
• 200+ plugins tiers sur marketplace

🎯 Métriques de Succès Globales

Adoption

• 100,000 users actifs (vs 10,000 aujourd’hui)
• 1,000 entreprises clientes
• Top 10 ML tools (par usage GitHub/research)

Revenue

• $10M ARR (Annual Recurring Revenue)
• 50% du marché “ML design tools”
• Break-even atteint mois 18

Impact Scientifique

• 10,000+ citations du paper NEURAX
• 50+ universités utilisant NEURAX pour enseigner
• 20+ startups construites sur NEURAX

Technique

• 99% accuracy prédictions (vs 95% aujourd’hui)
• <25ms analyse (vs <50ms aujourd’hui)
• 1M+ modèles analysés cumulatifs

💰 Investissement Requis

Budget Total : $15M sur 24 mois

Équipe Requise

Année 1 (10 personnes) :

• 4 ML Engineers (Rust/Python)
• 2 Research Scientists
• 1 DevOps Engineer
• 1 Product Manager
• 1 Designer
• 1 Community Manager

Année 2 (25 personnes) :

• +6 ML Engineers
• +2 Research Scientists
• +2 DevOps Engineers
• +2 Product Managers
• +1 Designer
• +2 Sales/Marketing

🚧 Risques & Mitigation

Risque 1 : Validation échoue (P0)

Impact : Crédibilité détruite
Probabilité : 15%
Mitigation :

• Commencer small (10 modèles), puis scale
• Collaborer avec labs académiques (Meta, OpenAI)
• Publier résultats intermédiaires (transparency)

Risque 2 : Concurrence (Weights & Biases, etc.)

Impact : Perte de market share
Probabilité : 40%
Mitigation :

• Focus sur “design-time” (notre avantage unique)
• Partnerships vs competition (intégrer W&B)
• Move fast (ship Phase 1-2 en 12 mois)

Risque 3 : Adoption lente

Impact : Revenue goals manqués
Probabilité : 30%
Mitigation :

• Free tier généreux (attirer users)
• Education program (universities)
• Case studies (OpenAI, Anthropic testimonials)

Risque 4 : Technical debt (scalability)

Impact : Performance dégradée
Probabilité : 25%
Mitigation :

• Refactoring continu (20% time budget)
• Load testing dès Phase 1
• Microservices architecture

📚 Documents Détaillés

Cette roadmap est accompagnée de documents détaillés pour chaque phase :

1. ROADMAP_PHASE1_VALIDATION.md — Validation & benchmark
2. ROADMAP_PHASE2_TRAINING.md — Training integration
3. ROADMAP_PHASE3_COLLABORATION.md — Multi-user features
4. ROADMAP_PHASE4_INTELLIGENCE.md — Auto-optimization & NAS
5. ROADMAP_PHASE5_CLOUD.md — Cloud deployment
6. ROADMAP_PHASE6_ECOSYSTEM.md — Mobile, education, marketplace

✅ Next Steps (Week 1)

1. Validation du plan avec stakeholders
2. Fundraising ($5M seed pour Phase 1-2)
3. Hiring (2 Research Scientists + 2 ML Engineers)
4. Kick-off Phase 1 (Benchmark suite)

Créé par : Kiro AI Agent
Date : 31 Juillet 2026
Version : 1.0
Statut : DRAFT — À valider

🚀 Let’s build the future of AI development together!

Changelog

All notable changes to NEURAX — The Pre‑Flight Compiler for Artificial Intelligence are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.6.3] — 2026‑08

Changed

• Replace generic emojis with the Notionists avatar family across the UI.
• Add Multimodal (VLM) support: new ModelType::Multimodal for vision+language models (CLIP, LLaVA-style, mobile VLMs) — parser, agent planning template (parallel vision+text branches with fusion), and tests.
• Fix parameter calculation: fall back to ffn_dim/num_heads when intermediate_size/num_attention_heads are absent.
• Add .cargo/config.toml pointing MLIR crates at LLVM 18.
• Add MIT LICENSE, ROADMAP_NEURAX_2.0.md, deployment scripts, and examples/models reference configs.

[0.6.2] — 2026‑08

Changed

• Refactor README, increase fonts, integrate Notionists avatars system.

[0.6.1] — 2026‑07

Added

• Modernized landing page with 5 components + Notionists avatar system.
• Hyperparameter Optimization system (3 strategies, 11 families, hardware-aware).
• LLM-builder implementation and testing.

[0.5.0] — 2026‑07

✅ Complete (v0.5.0)

🚧 In Progress

• NEURAX‑MLIR → IREE kernels — Lowering NEURAX MLIR dialects to runnable IREE kernels for cross‑platform deployment (CPU, CUDA, Vulkan, Metal, ROCm).
• Public benchmark suite — Validation set comparing analytical predictions against measured real‑world runs across 11 model families.
• Batch HPO backend API — Server‑side batch hyperparameter optimization via backend API (frontend already has client‑side HPO).

📋 Planned

• PostgreSQL persistence for cloud project storage
• Multi‑node distributed training projections
• Model Hub with HuggingFace integration
• Fine‑tuning cost projections (LoRA, QLoRA, full)
• Integration with actual training frameworks (PyTorch Lightning, HF Trainer)
• Collaborative multi‑user editing with CRDT

[0.4.0] — 2026‑06

Added

• Hyperparameter Optimization system with 3 strategies (Grid Search, Random Search, Bayesian), 6 objectives, and hardware‑aware recommendations across 11 model families.
• 14‑GPU frontend database (H200, GH200, H100 SXM/PCIe, A100 SXM/PCIe, L40S, L40, V100, RTX 4090/4080/3090, RTX A6000, T4).
• Hardware‑aware optimizer with VRAM, bandwidth, and ridge‑point capacity analysis.
• Inference Intelligence panel with 22 parameters and 10 widgets (stability, hallucination risk, sampling volatility).
• Time Machine compliance overlay with EU AI Act, CSRD, DSA regulatory data.
• GitHub export panel with direct push and PR creation.
• Credits system with plan‑based usage limits and billing integration.
• API key management with scope‑based authorization.

Changed

• Aligned README claims with audited codebase reality.
• Replaced ASCII art diagrams with Mermaid diagrams for better rendering.

[0.3.0] — 2026‑02

Added

• Streaming SSE analysis with authentication.
• Multi‑hardware comparison (up to 8 configurations).
• Cloud project CRUD (create, read, update, delete).
• ONNX binary export.
• GitHub push with PR creation.
• Billing, credits, and compliance infrastructure.
• Docker multi‑service orchestration.

Changed

• Web platform visual canvas, drag‑and‑drop, and live metrics.
• AI Chat Drawer with agent integration.

[0.2.0] — 2025‑06

Added

• 10‑pass analytical IR pipeline (Architecture → Graph → Tensor → Operator → Compute → Memory → Parallelism → Hardware → Cost → Report).
• MLIR compiler backend with 13 custom dialects (Architecture, Graph, Tensor, Operator, Compute, Memory, Parallelism, Hardware, Cost, Report, Training, Data, Optimization).
• CLI with analyze, compile, validate, and summary commands.
• Hardware database with 20 GPUs, 2 CPUs, and 5 interconnect specifications.
• 88 reference architecture templates across 11 model families.
• Terminal UI (TUI) for model compilation visualization.

[0.1.0] — 2024‑12

Added

• Initial analytical compiler framework.
• JSON model config parser with schema validation.
• Core IR pipeline with FLOPs, parameter count, memory, and cost formulas.
• MLIR code generation backend.
• Foundation for 11 model families: Transformer, MoE, CNN, SSM, Diffusion, GNN, GAN, RL, SNN, RNN, Experimental.