AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4 
5ZML is a Zig project built with Bazel. Core library code lives in `zml/`, with IO under `zml/io/`, tokenizers under `zml/tokenizer/`, attention implementations under `zml/attention/`, and MoE support under `zml/moe/`. Shared Zig utilities are in `stdx/`; FFI and C helpers are in `ffi/` and `upb/`. Bazel rules and workspace helpers live in `bazel/` and `third_party/`. Runnable examples are in `examples/`, while user-facing documentation is in `docs/`. Keep tests close to implementation files unless a package already has a separate test file.
6 
7## Build, Test, and Development Commands
8 
9- `bazel build //zml`: builds the main ZML library.
10- `bazel test //zml:test`: runs the core Zig test target.
11- `bazel test //stdx:test`: runs shared utility tests.
12- `bazel test //zml/tokenizer:test`: runs tokenizer tests.
13- `bazel run //examples/mnist`: runs the quick MNIST smoke test.
14- `bazel run //examples/llm -- --model=hf://... --prompt="..."`: runs the LLM example.
15- `bazel build //...` and `bazel test //...`: use before broad or shared changes.
16- `./tools/buildifier.sh`: formats Bazel/Starlark files.
17- `echo "$(bazel info output_base)/$(bazel cquery --output=files "$(bazel cquery "filter('zig_toolchain', deps(//zml))" 2>/dev/null | cut -d' ' -f1 | head -n1)" 2>/dev/null | rg "/lib\$")/std"`: find the current Zig standard library used by Bazel.
18 
19Append platform flags when relevant, for example `--@zml//platforms:cuda=true`, `--@zml//platforms:rocm=true`, `--@zml//platforms:tpu=true`, or `--@zml//platforms:cpu=false`.
20 
21## Coding Style & Naming Conventions
22 
23Follow the Zig style guide and format Zig code with `zig fmt`; CI checks `zig fmt --check` outside `third_party/`. Use four-space indentation. Prefer `const x: Foo = .{ .bar = 1 };`, `pub fn method(self: Foo)`, and module imports such as `const foo = @import("foo.zig"); foo.bar()`. Use `PascalCase` for types and `lowerCamelCase` for functions, fields, and locals. Add comments only for non-obvious invariants, ownership, tensor shape semantics, or platform behavior.
24 
25## Testing Guidelines
26 
27Tests are generally inline Zig `test "..." {}` blocks near the code they cover. Use descriptive test names and narrow Bazel targets first, then broaden when touching shared APIs. For tensor or graph changes, cover shape/tag inference and runtime behavior when practical. CI builds all targets and runs tests on CPU, CUDA, and ROCm where available.
28 
29## Commit & Pull Request Guidelines
30 
31Recent history uses scoped, imperative commit subjects such as `zml/tensor: add Tensor.onMemory()` or `workspace: use latest version of upstreamable rules_zig`. Keep subjects concise and mention the affected area first. Pull requests should include a short description, relevant linked issue, platform impact if any, and the exact `bazel build` or `bazel test` commands run. Include screenshots only for docs or UI-visible changes.
32