Neuro Programming Language

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

Status: Alpha — Phase 1 Core MVP complete · Phase 1.5 & Phase 2 in progress

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 is complete, Phase 1.5 and 2 is in progress. The following features are fully implemented and tested (493 Tests Passing):

Feature	Details
Static Typing + Inference	All integer types (i8–u64), f32/f64, bool, string; explicit `as` casting; contextual numeric literal inference; integer literal type suffixes (`42i64`, `255u8`); float literal type suffixes (`1.5f32`, `2.0f64`); underscore digit separators (`1_000_000`, `0xFF_FF`, `0b1010_0011`)
Functions	Parameters, explicit and expression-based implicit returns, recursion, forward references
Control Flow	if/else/elif, while loops, range-for (`for i in 0..n` and `0..=n`), break, continue
Mutable Variables	`val` (immutable) and `mut` (mutable) with type-safe reassignment
Compound Assignment	`+=`, `-=`, `*=`, `/=`, `%=` desugared at parse time to `target = target OP expr`
Constants	`const NAME: Type = expr` at module and function scope; constant-expression validation; forward references; emitted as LLVM globals
Integer Overflow	`+`/`-`/`*` trap at runtime on overflow in debug builds (`-O0`); wrap (two's complement) in release builds (`-O1..-O3`); division/modulo/bitwise/float unaffected
Bitwise Operators	`&`, `\|`, `^`, `~`, `<<` on integer types; correct precedence per Appendix B (Shl > BitAnd > BitXor > BitOr); floats and bools rejected
Attributes & Lints	`@name(args)` attributes on functions/methods; `while true` lint with `@allow(prefer_loop_over_while_true)` suppression
String Type	Literals with full escape sequence support (`\n`, `\t`, `\"`, `\\`, `\xNN`, `\u{NNNN}`); `==` and `!=` for byte-level comparison; `.len()` builtin method returning the `u64` byte length (O(1), excludes null terminator)
Builtin Methods	Compiler-known intrinsic method dispatch on primitive & string receivers (`receiver.method()`), alongside user-defined `impl` methods; first intrinsic `string.len()`
Structs	Definition, instantiation (`Name { field: value }`), field read (`obj.field`), field mutation on `mut` bindings; nominal typing; definition-order independent
Methods	`impl` blocks with `&self` instance methods; associated functions called via `TypeName::func(args)`; `&mut self` / consuming `self` rejected until ownership lands
If/Block Expressions	`val x = if cond { a } else { b }`; `val y = { stmts; expr }`; all arms type-checked; alloca-based lowering
LLVM Backend	Native executable generation via inkwell 0.8.0 (LLVM 20)
CLI	`neurc check` (type-check only) and `neurc compile` (produces native binary)

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

Requirement	Version	Notes
Rust	1.85+	Install via rustup
LLVM 20	20.x with dev libs	Platform instructions below
C linker	any	`gcc`/`clang` on Linux/macOS; MSVC on Windows

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

cargo test --workspace

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/hello.nr

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

# Run the compiled binary
./examples/factorial

# After cargo install --path compiler/neurc:
neurc compile examples/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.8 / 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

Phase	Goal	Status
1	Core MVP — types, functions, control flow, LLVM backend	✅ Complete
1.5	Syntax & semantics stabilization — parser fixes, `const`, `as` casts, compound assignment, bitwise ops, integer suffixes, if/block expressions, `while true` lint, IEEE-754 float comparisons, string fat pointers	🔄 In progress
1.7	Ownership & borrow checker — move semantics, `Copy` trait, `&`/`&mut`, lifetimes, drop / deterministic destruction, remove implicit copies	📋 Planned
1.8	Backend plumbing — `neuro-hir` typed IR crate, `melior` integration, HIR lowering pipeline shared by LLVM + future MLIR backends	📋 Planned
2	Core language — arrays, tuples, structs ✅, methods ✅, enums, pattern matching, generics, traits, closures, type aliases, newtypes, `Option`/`Result`, `??`, `?`, modules, prelude, string interpolation	🔄 In progress
3	Tensors & MLIR — `Tensor<T, [...]>`, shape generics, named dims, dynamic shapes, DLPack, MLIR linalg lowering, pool allocator, pipeline `	>`, composition` >>`, einstein notation
4	Automatic differentiation — Enzyme MLIR pass, `@grad(wrt: ...)`, `.backward()` / `.zero_grad()`, higher-order derivatives, SGD	📋 Planned
5	GPU acceleration — MLIR GPU dialects (nvgpu / rocdl / Triton), `@gpu`, `KernelOut<T>` aliasing model, device memory pool, CPU fallback	📋 Planned
6	Neural network standard library — `TrainableTensor`, `ParameterList`, optimizers, `@model`, Dense / Conv2d / Attention, `.nrm` serialization	📋 Planned
7	Async runtime — `async func`, `Future<T>`, `spawn`, `JoinHandle`, `join` / `race`, executor for data-loader / I/O overlap	📋 Planned
8	Interop & advanced features — Python FFI via DLPack, spread operator, advanced pattern matching, custom attributes, `defer`	📋 Planned
9	Developer experience — Language Server Protocol, diagnostics polish, formatter	📋 Planned
10	Package manager & optimization passes — `neurpm`, loop unrolling, AD-aware inlining heuristics	📋 Planned

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

Extension	Purpose
`.nr`	Neuro source files
`.nrl`	Compiled library modules
`.nrm`	Serialized model/matrix data
`.nrp`	Package definitions

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.5 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:

True Native Performance: Compiled AOT via LLVM 20—no heavy runtime interpreter, no global interpreter lock (GIL).
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.
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.

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.cargo		.cargo
.github		.github
assets		assets
compiler		compiler
docs		docs
examples		examples
neuro-language-support		neuro-language-support
tests/type_inference		tests/type_inference
tools		tools
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DESIGN.md		DESIGN.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VSA.md		VSA.md

Folders and files

Latest commit

History

Repository files navigation

Neuro Programming Language

Table of Contents

Overview

Quick Example

Current Capabilities

Current Memory Model

Installation

Prerequisites

Arch Linux / CachyOS

Ubuntu / Debian

macOS (Homebrew)

Windows 10 / 11 (x64)

Usage

Language Syntax

Variables and Types

Functions

Control Flow

Structs

Planned (Phase 3+): Tensor Types

Architecture

Workspace Layout

Compilation Pipeline

Quick Roadmap

Development

VSCode Extension

File Extensions

Contributing

Why Neuro?

License

Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages