cognisoc / zigllm
Chapter zero · Setup

Clone it. Test it. Read it.

zigllm needs one toolchain and no accelerator. The fastest way to understand a transformer is to run the tests and follow the code — here is the shortest path from zero to a streaming forward pass.

  1. 1

    Install Zig 0.14+

    zigllm targets Zig 0.14 or newer. Grab it from ziglang.org/download (or a version manager like zvm) and confirm it is on your PATH with `zig version`. A modern CPU with AVX/AVX2 helps the SIMD paths but is not required.

    $ zig version
# 0.14.0 or newer
  2. 2

    Clone the repository

    Clone zigllm from GitHub. The repo is laid out as a book: src/ holds the six layers and docs/ holds the matching chapters.

    $ git clone https://github.com/cognisoc/zigllm
$ cd zigllm
  3. 3

    Run the tests — they are the documentation

    Run the full suite with `zig build test`. The 285+ tests are executable documentation: each one demonstrates a concept and validates the math, so a green run means the toolchain works and the examples are live.

    $ zig build test
# 285+ tests double as worked examples
  4. 4

    Read the doc tree bottom-up

    Open docs/01-foundations/ alongside src/foundation/ and walk up the stack chapter by chapter. Do not skip — each layer assumes the one below it. When something feels handwavy, find the matching test.

    $ ls docs/
# 01-foundations  02-linalg  03-primitives …
  5. 5

    Run a forward pass and generate

    By Layer 5 you can memory-map a GGUF model compatible with the llama.cpp ecosystem; by Layer 6 you can drive the generation loop and watch tokens stream out. Follow the example in the inference chapter.

    $ zig build run -- --model model.gguf --prompt "Once upon a time"
Where to go next

Follow the six-layer curriculum in order, or jump to the architectures you recognise. Full reference lives in the docs ↗.