Design Principles¶

ZigLlama is governed by a small set of non-negotiable principles. Every pull request, every new module, and every documentation paragraph is evaluated against these tenets. This page states them explicitly so that contributors and readers can understand the why behind the code.

1. Educational First, Performance Second¶

The primary purpose of ZigLlama is to teach. A reader who has never seen a transformer implementation should be able to open any source file and, by reading the comments alone, understand what mathematical operation is being performed, why it matters for language modelling, and how it relates to the components above and below it in the stack.

Concrete practices¶

• Every public function begins with a doc-comment that states the mathematical definition, the transformer context, and a minimal worked example where appropriate.
• Inline comments annotate non-obvious algorithmic steps with references to the corresponding equation numbers in the canonical literature (Vaswani et al., 2017; Touvron et al., 2023).
• Where an optimised path coexists with a naive path, both are present in the source: the naive version for readability, the optimised version for production use.

/// Rectified Linear Unit (ReLU)
///
/// ## Mathematical Definition
/// ```
/// ReLU(x) = max(0, x) = { x if x > 0, 0 otherwise }
/// ```
///
/// ## Transformer Context
/// ReLU was used in the original Transformer feed-forward network.
/// Modern architectures (LLaMA) have replaced it with SwiGLU.
pub fn relu(x: f32) f32 {
    return @max(0.0, x);
}

2. Progressive Component Architecture¶

The codebase is organised into six layers that build from the simplest abstractions (tensors, memory maps) to the most complex (text generation, streaming inference). This mirrors the way a textbook introduces concepts: fundamentals first, composition second.

Layer 6  Inference
Layer 5  Models
Layer 4  Transformers
Layer 3  Neural Primitives
Layer 2  Linear Algebra
Layer 1  Foundation

Benefits¶

3. Test-Driven Development¶

ZigLlama currently contains 285+ tests spanning four categories:

Test counts by layer¶

4. Documentation as Code¶

Documentation is not an afterthought -- it is a deliverable on par with the implementation. ZigLlama treats three kinds of documentation as first-class:

4.1 Inline documentation (source files)¶

Every source file opens with a module-level doc-comment that states:

1. Educational Objectives -- what the reader will learn.
2. Mathematical Foundation -- the relevant equations.
3. Transformer Context -- how the component fits into the larger model.

4.2 MkDocs site (this documentation)¶

The MkDocs site provides long-form exposition that cannot fit into source comments: architectural diagrams, cross-cutting comparisons, learning paths, and reference tables. It uses:

• LaTeX for inline (\( x \)) and display ([ \sum_{i=1}^{n} x_i ]) mathematics.
• Mermaid for architectural and data-flow diagrams.
• Material for MkDocs admonitions for definitions, theorems, algorithms, and warnings.

4.3 Historical and theoretical context¶

Where appropriate, documentation references the original papers, explains the historical evolution of a technique (e.g. LayerNorm to RMSNorm), and provides intuition for why the technique works, not just how to implement it.

5. Feature Parity and Beyond¶

ZigLlama aims for meaningful feature parity with llama.cpp, the industry-standard C++ inference engine. "Meaningful" is defined as covering the features that matter for understanding and using large language models, rather than chasing every niche backend or quantisation variant.

Current parity targets¶

6. Iterative Refinement¶

Development follows a three-pass strategy for every component:

Pass 1 -- Naive implementation¶

Write the simplest correct version. Prioritise readability. Use \( O(n^3) \) matrix multiplication with three nested loops. Document the algorithm thoroughly.

Pass 2 -- Optimised implementation¶

Add SIMD, cache blocking, and quantisation paths. Keep the naive version in the code (guarded behind a comptime flag or as a separate function) so that readers can compare.

Pass 3 -- Documentation and testing¶

Write the MkDocs page, add performance benchmarks, and record the speed-up ratios. This pass ensures that the educational value of the optimisation is captured, not just its runtime benefit.

7. Implementation Standards¶

The following standards apply to all contributions.

7.1 Code quality¶

7.2 Documentation standards¶

7.3 Testing standards¶

Summary¶

The seven principles form a coherent whole:

graph TD
    A[Educational First] --> B[Progressive Architecture]
    B --> C[Test-Driven Development]
    C --> D[Documentation as Code]
    D --> E[Feature Parity]
    E --> F[Iterative Refinement]
    F --> G[Implementation Standards]
    G --> A

Each principle reinforces the others. Progressive architecture makes testing easier; testing makes documentation concrete; documentation keeps education front and centre; and the implementation standards ensure that the cycle repeats with every new contribution.