Install the engine

Add the dependency

// build.zig.zon
.dependencies = .{
    .tomoul = .{
        .url  = "https://github.com/tomoul/tomoul/archive/<commit-or-tag>.tar.gz",
        .hash = "...",
    },
},

Until 1.0, pin a commit hash rather than a tag — the public API may break between minor versions. See Stability & versioning.

Import in build.zig

const tomoul = b.dependency("tomoul", .{
    .target   = target,
    .optimize = optimize,
});
exe.root_module.addImport("tomoul", tomoul.module("tomoul"));

System dependencies

• BLAS (optional). OpenBLAS or Apple Accelerate. Pass -Dblas=true to link. If you don't, the engine uses the bundled pure-Zig zblas fallback — fast enough for small models, no system dep needed.
• Vulkan loader (Linux/Windows GPU). System-provided.
• Metal (macOS). Built-in. No extra dep.
• WebGPU (browser target). Emitted via Emscripten.

tomoul doctor from the CLI flags what's available on your machine.

Zig version support

The engine tracks the latest stable Zig. We test against the previous stable for one release after a Zig bump. CI matrix: latest, prev, master (allowed-to-fail).

Converting weights from HuggingFace

The engine reads weights in two formats: HuggingFace safetensors (with config.json next to them) or the in-house .tl format. To produce .tl from a HuggingFace model, use the Python bridge in tools/:

python tools/export_to_tl.py \
    --model BAAI/bge-m3 \
    --quant q8_0 \
    --out   weights/bge-m3.tl

.tl is a tiny binary container — magic bytes, dimensions, raw floats. Read tools/tl_format.py in five minutes if you want to verify what's inside.

For day-to-day use, the per-model HuggingFace release repos at huggingface.co/tomoul already host pre-converted .tl artifacts — pull those directly with tomoul pull <model> from the CLI.