Contribute

UAII is MIT licensed and developed in the open. Every change starts with a GitHub issue, so scope is agreed before code is written.

Where to start

Pick the entry point that matches how much context you already have. If you are new to the codebase, an issue labelled good first issue is the fastest way in.

You want to	Do this
Report a bug	Open a bug report with OS, compiler, CMake version, and the exact failing command
Propose a feature	Open a feature request describing the workload it unblocks, not only the API you have in mind
Fix something small	Browse good first issues and comment to claim one
Add an architecture or operator	Start with Plugins. New formats and operators belong in a plugin before they belong in core
Improve the docs	Edit `docs/` for the repository or `website/` for this site

Step 1 — Open or claim an issue

Discussion happens on GitHub Issues. Use the templates so triage is quick, and comment on an existing issue to claim it rather than opening a duplicate. Wait for a maintainer to confirm scope on anything that touches core, the C ABI, or backend selection. Small fixes with an obvious correct answer do not need that round trip.

Step 2 — Fork and build

Fork the repository, then branch from main with a descriptive name such as fix/gguf-iq4nl-stride.

git clone https://github.com/<you>/Universal-AI-Inference.git
cd Universal-AI-Inference
git checkout -b fix/short-description

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DUAII_BUILD_TESTS=ON -DUAII_BUILD_PLUGINS=ON
cmake --build build --config Release --parallel

Full prerequisites are on the Quick start page. On Windows, App Control frequently blocks unsigned executables; build under WSL with bash scripts/build_uaii_wsl.sh if that happens.

Step 3 — Verify before you push

uaii doctor --load-plugins
ctest --test-dir build -C Release --output-on-failure
clang-format -i <files you touched>

Extend the tests that cover the behaviour you changed. Performance work should include uaii_bench output for the affected suite so the claim is reviewable. See Benchmarks for the reproduction commands.

Step 4 — Open the pull request

Push your branch and open a pull request against main. A reviewable PR does five things:

Links the issue it resolves
Explains why the change is needed, not only what it does
Stays focused on one concern, so unrelated cleanup ships separately
Updates the docs describing any behaviour or public API you changed
Passes CI, including the CodeQL and wheel workflows

Expect review comments on ABI compatibility and honesty of claims. Both are enforced deliberately.

Design rules

These constraints keep the runtime modular, and reviews will hold you to them:

Core never imports model-specific code
External formats convert to UAII IR before execution
Backends understand UAII IR and planned kernels, nothing else
Prefer a new plugin over a change to core
Return uaii::Error rather than throwing on hot paths; log through uaii::log::* with a short component name
Plugin entry points stay extern "C" and versioned
Documentation states what is measured and what is a scaffold. Host-fallback GPU backends and demo loaders are described as such until real device paths land

Where code lives

Path	Role
`include/uaii/`	Public headers and interfaces
`libs/uaii-core/`	Errors, logging, configuration, plugin host
`libs/uaii-*/`	Modular libraries: ir, runtime, kernels, backends, loaders, capi
`bindings/python/`	Python SDK
`plugins/`	Reference plugins for discovery and operator registration
`website/`	This documentation site, built with Next.js static export
`docs/`	Architecture, features, roadmap, and stability policy
`tests/`	Smoke and runtime integration tests

Editing this site

cd website
npm install
npm run dev    # http://localhost:3000
npm run build  # static export

Pages are React components under website/app/. Add a documentation page by creating app/docs/<slug>/page.tsx and registering it in the sidebar groups in components/DocLayout.tsx.

Reference

CONTRIBUTING.md — the authoritative version of this process
Code of Conduct — expected behaviour in issues and reviews
Architecture — module boundaries before you change them
Plugins — the extension path for formats, operators, and backends