How-to guides

Practical guides covering common tasks. Each guide answers one concrete "how do I X" with a worked example: real code, built against the bundle, with its real output. Read the tutorial first; the guides assume its ground (tensors, devices, the async model) and go deeper on one problem at a time, in any order. Entries marked as coming are planned and land here as they are written.

Every section carries a C++, C, Python, Kotlin, Go and Rust arm. The Go, Rust and Kotlin bindings serve every member the sections call (completion callbacks, the three from_blob forms, the execution scopes, audio decoding, typed readback), and each of those arms is a program that builds and runs against the release, with its output recorded beside it. Where a surface is the C++ tier's alone (the HTTP server, the processor family, a custom kernel), the tab says so and points at the tab that has it. The Kotlin binding still skips members whose C signature returns several handles at once, takes an array of structs (an operator taking a list of scalar-or-tensor operands, an index-entry or index-bound list, a tensor-spec list), takes a list of strings, or belongs to the trace-capture family; those members serve from C, C++, Python, Go and Rust, and a Kotlin tab that needs one names the member it lacks. Three guides are Python-only because their subject exists in the Python package alone: authoring a model in Python, PyTorch interop, and pytrees. The licensing guide's arms show where each language puts the runtime credential, not a program with an output.

Weights and data

• Load quantized weights from a GGUF file: read a block-quantized checkpoint and serve it at its on-disk footprint.
• Load images and audio for inference: decode files into tensors, resample audio, preprocess with ops::.

Models and graphs

• Run an ONNX model: open or build a graph, compile it into a runnable ModelGraph, execute by position or by name.
• Preprocess inputs with processors: the model's own resize/rescale/normalize recipe, or a log-mel front end, from knobs or its config file.
• Author a model in Python: a decoder-only language model as nn.Modules from a Hugging Face config and its safetensors, meta init, fused projections, a KV cache and a greedy decode loop, measured against the C++ command line.

Text and chat

• Tokenize text and apply a chat template: text to token ids and back, byte offsets, the model's own prompt format, batching for a model, streaming decode for a generation loop.

Serving

• Serve a model over HTTP: routes, a JSON inference endpoint, and server-sent events for streaming.

Execution and memory

• Control asynchronous execution: dispatch vs ready, safe host reads, completion callbacks, synchronous and tracing scopes.
• Trace eager code to graphs: capture a function as a runnable ModelGraph with trace, and wrap hot paths in compile.
• Wrap existing memory without copying: tensors over buffers your application already owns.
• Write a custom operator: compose built-ins in an nn::Module, or launch your own kernel on the stream's native handle.
• Structure inputs and outputs as pytrees: nested containers of tensors at every boundary (compile, trace, eval, save), the registry for your own classes, key paths and serialization.

Integration and packaging

• Add ClikaRT to an existing CMake project: find_package against the bundle, or add_subdirectory, in a project that already builds.
• Use ClikaRT from Python: the clika-runtime wheel, the NumPy boundary, models as nn.Module, errors you can branch on.
• Use ClikaRT with PyTorch: torch.compile(model, backend="clika"), zero-copy tensor exchange over DLPack, and from_torch_module for an eager module tree.
• Call ClikaRT from C or any FFI language: dlopen, the versioned api-table handshake, ops and typed errors in strict C99.
• Handle errors by code: the three channels every failure carries, the stable code name to branch on, the coarse status for policy.
• License the runtime: where the runtime reads the project's credential, one setting per language and packaging, and the code names a refused call carries.
• Package ClikaRT in an Android app (coming): bundle the .so files, wrap the pipeline in JNI, ship model files as assets.

Tools

• Build a command-line model tool (coming): typed argument parsing, progress bars and structured logging in one small tool.

Complete programs

• Additional examples: the bundle's standalone projects, one per subsystem, each building its topic up chapter by chapter.

For every public name, the API reference.