A modern, compiled language designed for high-performance AI development.

Status: Alpha — Phase 1 Core MVP & Phase 1.5 stabilization complete · Phase 1.7 (ownership) active · Phase 2 overlapping

Table of Contents

• Overview
• Quick Example
• Current Capabilities
• Installation
• Usage
• Language Syntax
• Architecture
• Roadmap
• Development
• VSCode Extension
• File Extensions
• Contributing
• License
• Acknowledgments
• Security
• Code of Conduct
• Design Rationale

Overview

Neuro is an Ahead-of-Time (AOT) compiled language built from the ground up for AI workloads. Unlike Python — an interpreted glue language — Neuro generates native code through an LLVM 20 backend, with a roadmap toward:

• MLIR-based tensor operations for static, shape-verified tensor types
• IR-level automatic differentiation via Enzyme
• GPU acceleration via MLIR GPU dialects (nvgpu, rocdl, Triton)

Quick Example

A single perceptron with ReLU activation; uses structs, impl blocks, associated functions, instance methods, if-expressions, and implicit returns. This file compiles and runs today.

struct Neuron {
    weight: f64,
    bias: f64
}

impl Neuron {
    func new(weight: f64, bias: f64) -> Neuron {
        Neuron { weight: weight, bias: bias }
    }

    // ReLU: pass-through if active, clamp to zero if not
    func activate(&self, input: f64) -> f64 {
        val z = (input * self.weight) + self.bias
        if z > 0.0 { z } else { 0.0 }
    }

    func is_active(&self, input: f64) -> bool {
        val z = (input * self.weight) + self.bias
        z > 0.0
    }
}

func main() -> i32 {
    val neuron = Neuron::new(0.5, -0.1)

    val dead   = neuron.activate(0.0)   // 0.0 * 0.5 − 0.1 = −0.1 → clamped to 0.0
    val active = neuron.activate(1.0)   // 1.0 * 0.5 − 0.1 =  0.4 → passes through
    val fired  = neuron.is_active(1.0)  // true

    return 0
}

Current Capabilities

Phase 1 and Phase 1.5 are complete; Phase 1.7 (ownership) is active with Phase 2 overlapping. The following features are fully implemented and tested (546 Tests Passing):

Current Memory Model

⚠️ Alpha Memory Warning — no ownership system yet

Stack-allocated values (integers, booleans, structs with primitive fields) are reclaimed automatically on function return via LLVM alloca. String literals are emitted into read-only program memory (.rodata) and consume no heap, so a program that only reads literal strings does not leak today.

However, no destructor, drop, or ownership system exists yet. As soon as runtime string operations (concatenation, formatting, dynamic builders) land, every heap buffer they allocate will leak until the borrow checker and drop semantics are in place. The same applies to any future heap-allocated value (boxed types, dynamic arrays, owning collections).

Building the ownership tracker, borrow checker, and deterministic destruction is the primary goal of Phase 1.7. Do not assume memory safety semantics until those land.

If memory safety semantics and compiler backend design are your thing, this is exactly where contributors are needed.

String fat pointers have already landed; the remaining work — ownership semantics, move-by-default, borrow checker, and drop — is tracked under Phase 1.7 in the roadmap.

Installation

Prerequisites

Arch Linux / CachyOS

# 1. Install LLVM 20
sudo pacman -S llvm20

# 2. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 3. Set the LLVM prefix (add to ~/.bashrc or ~/.zshrc to persist)
export LLVM_SYS_201_PREFIX=/usr/lib/llvm20

# 4. Clone and build
git clone https://github.com/PanzerPeter/Neuro.git
cd Neuro
cargo build --release

# 5. Run the test suite
cargo test --workspace

# 6. (Optional) Install the compiler globally
cargo install --path compiler/neurc

Ubuntu / Debian

# 1. Install LLVM 20 via the official APT script
wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- 20
# Alternatively, use the full dev package set:
# sudo apt-get install llvm-20 llvm-20-dev llvm-20-tools libpolly-20-dev

# 2. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 3. Set the LLVM prefix (add to ~/.bashrc to persist)
export LLVM_SYS_201_PREFIX=/usr/lib/llvm-20
echo 'export LLVM_SYS_201_PREFIX=/usr/lib/llvm-20' >> ~/.bashrc

# 4. Clone and build
git clone https://github.com/PanzerPeter/Neuro.git
cd Neuro
cargo build --release

# 5. Run the test suite
cargo test --workspace

# 6. (Optional) Install the compiler globally
cargo install --path compiler/neurc

macOS (Homebrew)

# 1. Install LLVM 20
brew install llvm@20

# 2. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 3. Set the LLVM prefix (add to ~/.zshrc or ~/.bash_profile to persist)
export LLVM_SYS_201_PREFIX="$(brew --prefix llvm@20)"
echo "export LLVM_SYS_201_PREFIX=$(brew --prefix llvm@20)" >> ~/.zshrc

# 4. Clone and build
git clone https://github.com/PanzerPeter/Neuro.git
cd Neuro
cargo build --release

# 5. Run the test suite
cargo test --workspace

# 6. (Optional) Install the compiler globally
cargo install --path compiler/neurc

Windows 10 / 11 (x64)

Windows requires the MSVC toolchain (not GNU). Make sure Visual Studio Build Tools 2019 or later are installed with the C++ build tools workload before proceeding.

Step 1 — Install Visual Studio Build Tools

Download from visualstudio.microsoft.com/downloads → Tools for Visual Studio → Build Tools for Visual Studio 2022. Select the Desktop development with C++ workload.

Step 2 — Install Rust

Download and run rustup-init.exe from rustup.rs. When prompted, choose 1) Proceed with standard installation. Rustup will automatically select the stable-x86_64-pc-windows-msvc default toolchain.

Open a new PowerShell window after installation so the cargo and rustc commands are on your PATH.

Step 3 — Install LLVM 20

Download the official Windows installer from the LLVM GitHub releases page:

# PowerShell — download and run the installer silently
$version = "20.1.8"
$url = "https://github.com/llvm/llvm-project/releases/download/llvmorg-$version/LLVM-$version-win64.exe"
curl.exe -fsSL -o "$env:TEMP\llvm-installer.exe" $url
Start-Process "$env:TEMP\llvm-installer.exe" -ArgumentList "/S /D=C:\LLVM" -Wait -PassThru | Out-Null

Or download and run the installer manually from the LLVM GitHub releases page — install to C:\LLVM (the path must not contain spaces; the NSIS installer enforces this).

Step 4 — Set the LLVM environment variable

# Set permanently for your user account (no admin required)
[Environment]::SetEnvironmentVariable(
    "LLVM_SYS_201_PREFIX", "C:\LLVM",
    [EnvironmentVariableTarget]::User
)
# Also add C:\LLVM\bin to your PATH
$current = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$current;C:\LLVM\bin", "User")

Close and reopen PowerShell so the changes take effect, then verify:

llvm-config --version   # should print 20.x.y

Step 5 — Clone and build

git clone https://github.com/PanzerPeter/Neuro.git
cd Neuro
cargo build --release

Step 6 — Run the test suite

Step 7 — (Optional) Install the compiler globally

cargo install --path compiler/neurc
# The binary is placed in %USERPROFILE%\.cargo\bin\neurc.exe
# which is already on PATH after rustup setup.

Troubleshooting Windows build errors

• llvm-sys build script cannot find LLVM: confirm LLVM_SYS_201_PREFIX is set in the current shell session (echo $env:LLVM_SYS_201_PREFIX) and points to a directory that contains bin\llvm-config.exe.
• link.exe not found: the MSVC Build Tools are not on PATH. Run the build from a Developer PowerShell / x64 Native Tools Command Prompt or install the C++ build tools workload as described in Step 1.
• Version mismatch (llvm-sys-201 requires LLVM 20): an older LLVM is on PATH. Set LLVM_SYS_201_PREFIX explicitly to the LLVM 20 prefix and ensure C:\LLVM\bin precedes any other LLVM entries in PATH.

Usage

# Type-check a source file (no binary produced)
cargo run -p neurc -- check examples/basics/hello.nr

# Compile to a native executable
cargo run -p neurc -- compile examples/basics/factorial.nr

# Run the compiled binary
./examples/factorial

# After cargo install --path compiler/neurc:
neurc compile examples/basics/factorial.nr

Language Syntax

Variables and Types

// Immutable by default
val x: i32 = 42
val name: string = "Neuro"

// Mutable with reassignment
mut counter: i32 = 0
counter = counter + 1

// Type inference works for both val and mut
val pi = 3.14159   // inferred f64
val n  = 100       // inferred i32
mut count = 0      // inferred i32; type annotation optional

Functions

// Explicit return
func add(a: i32, b: i32) -> i32 {
    return a + b
}

// Expression-based implicit return (trailing expression)
func multiply(a: i32, b: i32) -> i32 {
    a * b
}

Control Flow

func fizzbuzz(n: i32) -> i32 {
    mut i: i32 = 1
    while i <= n {
        i = i + 1
    }
    i
}

func sum(n: i32) -> i32 {
    mut total: i32 = 0
    for i in 0..n {
        total = total + i
    }
    total
}

Structs

struct Point {
    x: f64,
    y: f64
}

func distance(p: Point) -> f64 {
    // field read
    val dx = p.x
    val dy = p.y
    dx * dx + dy * dy   // placeholder (no sqrt yet)
}

func main() -> i32 {
    val origin = Point { x: 0.0, y: 0.0 }

    // field mutation requires mut binding
    mut cursor = Point { x: 3.0, y: 4.0 }
    cursor.x = 1.0

    return 0
}

Planned (Phase 3+): Tensor Types

Tensor types and compile-time shape verification require the MLIR lowering infrastructure planned for Phase 3. Shape constraints ([784, 128]) are encoded as static type parameters and verified at compile time via the MLIR type system — this is not a simple feature and depends on both the melior bindings and a typed High-Level IR (neuro-hir) that does not yet exist.

// Static tensor — shape verified at compile time (Phase 3)
val weights: Tensor<f32, [784, 128]> = ...

// Automatic differentiation via Enzyme MLIR (Phase 4)
@grad(model) {
    val loss = model.forward(batch).cross_entropy(labels)
    model.backward(loss)
}

Architecture

Neuro follows Vertical Slice Architecture (VSA) — organized by language feature, not technical layer.

Workspace Layout

compiler/
├── infrastructure/          # Shared types, diagnostics, AST definitions
│   ├── ast-types/
│   ├── diagnostics/
│   ├── shared-types/
│   └── ...
├── lexical-analysis/        # Tokenizer (logos, Unicode XID)
├── syntax-parsing/          # Pratt + statement parser → AST
├── semantic-analysis/       # Type checker, scope analysis
├── control-flow/            # CFG builder (Phase 2+)
├── llvm-backend/            # inkwell 0.9 / LLVM 20 codegen
└── neurc/                   # CLI compiler driver

Compilation Pipeline

Current (Phase 1):

Source (.nr)
  → Lexical Analysis   (tokens)
  → Syntax Parsing     (AST)
  → Semantic Analysis  (type-checked AST)
  → LLVM Backend       (object code via inkwell / LLVM 20)
  → System Linker      (native executable)

Planned extension (Phase 3+):

Tensor/AI path: AST → Neuro High-Level IR
  → MLIR (linalg/tensor/func/arith, LLVM 20 / MLIR 20)
  → Enzyme MLIR AD pass (@grad)
  → GPU dialects (nvgpu/rocdl/Triton) or llvm dialect
  → inkwell → native code

Quick Roadmap

Development

Set LLVM_SYS_201_PREFIX for your platform before running any Cargo command (see Installation for the correct path per OS).

# Build the full workspace
cargo build --workspace

# Run all tests
cargo test --workspace

# Lint
cargo clippy --workspace --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

# Apply formatting
cargo fmt --all

On Windows, use PowerShell or a Developer Command Prompt. The env var must be set in the current session; prefix it inline if needed:

$env:LLVM_SYS_201_PREFIX = "C:\LLVM"
cargo build --workspace

VSCode Extension

Syntax highlighting for .nr files is included in neuro-language-support/.

cd neuro-language-support
npm install -g @vscode/vsce
vsce package
# Install the generated .vsix via: VSCode → Extensions → Install from VSIX

File Extensions

Contributing

See CONTRIBUTING.md for architecture guidelines, coding standards, and the pull request process.

The project is in early alpha — breaking changes are expected. Contributions should focus on Phase 1.7 and Phase 2 items.

Why Neuro?

AI development is stuck in a fragmented paradigm: developers iterate in an interpreted glue language (Python), while underlying libraries are written in unmanaged, safety-critical systems languages (C++/CUDA).

Neuro is built to unify this stack:

1. True Native Performance: Compiled AOT via LLVM 20—no heavy runtime interpreter, no global interpreter lock (GIL).
2. AI-First Type System: Native compile-time shape verification for tensors using MLIR (Phase 3), preventing runtime dimension mismatches before a single line of training executes.
3. Immutability by Default: A modern val/mut paradigm to ensure highly parallelized tensor computations are thread-safe by design.

License

Licensed under the Neuro Shared Source License v2.1.

Why not MIT/Apache 2.0 right now? Neuro is in a critical pre-stabilization phase. The license protects against three specific risks: commercial re-packaging of the compiler before the language spec is stable, AI-assisted reproduction of the compiler for a competing product, and misleading forks that fragment the early ecosystem. None of these restrictions affect normal use.

What you can do freely:

• Use, study, and modify the compiler for any personal or internal purpose
• Write Neuro programs and distribute or sell the compiled output under any terms you choose. programs you compile are wholly exempt from this license
• Build tools, plugins, and editor integrations that call into the compiler
• Contribute code back to the project

What requires a commercial license:

• Redistributing the Neuro compiler itself (or a fork of it) as part of a commercial product

See LICENSE for full terms.

Acknowledgments

Inspired by Rust (ownership, type system), Python (AI ecosystem simplicity), Swift (language ergonomics), and Mojo (AI-first design). Built with inkwell, logos, and the LLVM infrastructure.