Contributing

StableTested and in active use. Breaking changes will be called out.

noeira is developed in the open and was selected for a Modular Community Grant in 2026. Bug reports and contributions are welcome — the project status is honest about which parts are settled and which are not.

Setup

git clone https://github.com/noeira/noeira.git
cd noeira
pixi install
pixi run install-pre-commit

See Installation for GPU environments and optional dependencies, and Toolchain for the pinned versions and the native shims (pixi run build-http, build-qhull, …) that some code paths need at run time.

Workflow

pixi run format                  # mojo format -l 80
pixi run test-smoke              # the CI gate
pixi run examples-compile        # catch example rot

Formatting is 80 columns via mojo format, enforced by pre-commit.

Mojo 1.1

The project is pinned to Mojo 1.1.0 / MAX 26.6.0 — exact versions, not nightly. Code written against older Mojo, or against examples on the web, often uses spellings the pinned compiler rejects:

Older	Mojo 1.1
fn	def — the only function keyword; a function that can raise says raises
inout	mut
owned (argument)	var
alias	comptime
from std.gpu… import …	from max.gpu… import …
Atomic[DType.int64]	Atomic[Int64]
@parameter closure + parallelize[f](n)	def f(i: Int) {imm}: + parallelize(f, n)

The last three came with the 1.1 upgrade; Toolchain has the details and what is still pending. Your editor’s language server may lag the pinned compiler and report false warnings on valid code — the compiler is the authority.

Compiler traps worth knowing

These are not bugs in your code. Each has cost real time here.

Probe compilation with --emit=llvm

pixi run mojo build --emit=llvm <file>

macOS ld rejects the very long generic symbol names this design produces, so a link failure can be a false negative unrelated to your code. Stop at LLVM emission when you only want to know whether it type-checks.

Note also that mojo precompile skips generic instantiation, so a green package build can still hide real errors in generic code.

When the link itself is the goal, large drivers on macOS need the classic linker: -Xlinker -ld_classic. See the symbol-length assertion.

Instantiation depth can hang the compiler

Two known shapes: ~80+ calls in one function triggers an inliner explosion, and a deep comptime loop building nested modules can hang outright. Both are fixed by extracting the body into a helper function.

If a build stops making progress rather than failing, suspect depth first.

Stale noeira.mojoc shadows the source tree

rm -f noeira.mojoc

A stale precompiled package produces errors pointing at code that no longer exists.

The precompiled package has its own traps

pixi run build-pkg / run-pkg cut a large driver’s warm rebuild (38 s to 8 s on the SAC HalfCheetah driver), but the source tree shadows the package whenever noeira/ is in the working directory, and a package older than your edits builds against the old library. Use the tasks rather than calling mojo against build/pkg/ by hand — see the precompiled package.

A missing shim fails at run time

The C shims are not in git. Code that needs one compiles cleanly and then aborts at the first call. Build the shim once per machine (pixi run build-http, build-serial, build-qhull, build-opencv, build-imgui).

Intra-package imports should name the module: from .mod import X, not from . import X — the latter misses wildcard re-exports.

_DLCallable discards arguments. get_function[T](name)(args) silently becomes a no-op. Unwrap with () first, then call.

Where the sharp edges are

If you are looking for something to work on, these are known and documented:

Area	Issue
Replay gather	Dominates step time at pixel scale; unoptimized
Dreamer 4	Perceptual loss corrupts token reconstruction
Elliptic contacts	Drift vs. MuJoCo; affects Sawyer
CarRacing	Reward shaping unfinished
Env CUDA-graph capture	Blocked by the cooperative blocked-Newton kernel
nn Trainer capture	Captured training now runs with shuffle and augmentation and matches the eager run byte for byte, and on NVIDIA most GEMMs run on cuBLAS over a workspace they own. The supervised Trainer’s USE_TRAIN_CUDA_GRAPH still defaults to off, and stays fp32-only
NHWC conv	End-to-end migration designed but not landed
Documentation	README and package READMEs have drifted from the code

Documentation drift

The repository’s READMEs are written by hand and drift from the code; corrections are welcome. This site is checked instead: its build fails on any repository path a page cites that does not exist — see docs-site/scripts/check-refs.mjs.

Adding things

• A new environment
• A new agent
• A new network layer

Working on the docs

cd docs-site
pnpm install
pnpm dev          # http://localhost:4321
pnpm build        # runs check-refs, then builds

Every repo path cited in a page is validated at build time. If a page quotes code, take it from a file under examples/ rather than writing it fresh — that is the difference between docs that survive a refactor and docs that do not.

Demo videos are generated from gifs/:

node docs-site/scripts/build-media.mjs

The dev server caches content collections

If a frontmatter change appears not to land, restart the dev server before debugging it. The production build is authoritative.

Roadmap

From the project’s own roadmap:

Stabilize and harden — battle-test the 3D physics engine and the complex agents for community use.

Land the model-based agents — finish AlphaZero, MuZero, DreamerV3 and TD-MPC2 in the fully-GPU pipeline.

Publish benchmarks — rigorous comparisons against Gymnasium, Stable-Baselines3 and PyTorch.

Developer experience — cleaner APIs, documentation, and example templates for new agents and environments.

Next

• Testing — the tiers and the discipline
• Algorithms overview — what exists today