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++ and a Python arm, each a program that builds and runs against the release with its output recorded beside it, and a Kotlin note where the binding reaches the surface. 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 is an INFERENCE-level binding (the two kinds): a Kotlin tab shows what runs a ready model, and where a guide reaches past that level the tab 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 six graph guides (query, edit, optimize and finalize, write a transform, merge and split, and export to ONNX) carry a C++ and a Python arm, the two APIs that read and change a graph's structure. 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 ModelGraph, optimize and finalize it, 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.
• Query a graph: a ModelGraph's nodes, values and edges, search, walks and orders, paths and the critical path, dominance, regions and the cheapest cut, and views across edits.
• Edit a graph: change a ModelGraph before finalize(), from rewiring a value's reads and changing what a node reads to renaming nodes and editing the inputs and outputs, then optimize, finalize and run it.
• Optimize and finalize: run the graph optimizer on a ModelGraph and read its report, choose its transforms and defaults, place it with to(), and finalize() it to run.
• Write a transform: functions over the graph edits that optimize() runs beside the runtime's transforms, operators built with add_node, insert and replace, and rewrite rules over a Pattern.
• Merge and split: join ModelGraphs side by side, as a pipeline or across two devices, cut one into parts at its cheapest cut or by a function, extract the operators between values, and merge the parts back.
• Export a graph to ONNX: write a ModelGraph as an ONNX model file with export_onnx, or build the same model in memory with OnnxModel::from_graph; read it back, keep a named dynamic dimension, choose where the weights go and the opset, and meet what the export refuses.

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 ModelGraph with trace, optimize, finalize and run it, 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.
• Coming from PyTorch or Hugging Face: the conventions that differ, each with the one line that bridges it: channels-last and OHWI, integer slots, reads that wait, the accessors, the tokenizer's files, and the generate calls side by side.
• 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.
• 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: the two artifacts and the libraries copied beside them, the build requirements, the license credential, the thread count and the cache root, a model on the phone, and a server that outlives the screen.

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.