---
title: How-to guides
slug: /how-to
description: Problem-oriented recipes. Each guide answers one "how do I X" with a worked example, verified against the bundle.
---

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](../getting-started/first-program/01-your-first-program.mdx) 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](../bindings.md)): 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](load-quantized-weights.mdx): read a block-quantized checkpoint and serve it at its on-disk footprint.
- [Load images and audio for inference](load-images-and-audio.mdx): decode files into tensors, resample audio, preprocess with `ops::`.

## Models and graphs

- [Run an ONNX model](run-an-onnx-model.mdx): open or build a graph, compile it into a `ModelGraph`, optimize and finalize it, execute by position or by name.
- [Preprocess inputs with processors](preprocess-with-processors.mdx): 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](author-a-model-in-python.mdx): a decoder-only language model as `nn.Module`s 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](query-a-graph.mdx): 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](edit-a-graph.mdx): 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](optimize-and-finalize.mdx): 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](write-a-transform.mdx): 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](merge-and-split.mdx): join `ModelGraph`s 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](export-a-graph-to-onnx.mdx): 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](tokenize-and-chat-templates.mdx): 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](serve-over-http.mdx): routes, a JSON inference endpoint, and server-sent events for streaming.

## Execution and memory

- [Control asynchronous execution](control-async-execution.mdx): dispatch vs ready, safe host reads, completion callbacks, synchronous and tracing scopes.
- [Trace eager code to graphs](trace-eager-code-to-graphs.mdx): capture a function as a `ModelGraph` with `trace`, optimize, finalize and run it, and wrap hot paths in `compile`.
- [Wrap existing memory without copying](wrap-existing-memory.mdx): tensors over buffers your application already owns.
- [Write a custom operator](write-a-custom-operator.mdx): compose built-ins in an `nn::Module`, or launch your own kernel on the stream's native handle.
- [Structure inputs and outputs as pytrees](pytrees.mdx): 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](existing-cmake-project.md): `find_package` against the bundle, or `add_subdirectory`, in a project that already builds.
- [Coming from PyTorch or Hugging Face](coming-from-pytorch.mdx): 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](use-clikart-from-python.mdx): the `clika-runtime` wheel, the NumPy boundary, models as `nn.Module`, errors you can branch on.
- [Use ClikaRT with PyTorch](use-clikart-with-pytorch.mdx): `torch.compile(model, backend="clika")`, zero-copy tensor exchange over DLPack, and `from_torch_module` for an eager module tree.
- [Handle errors by code](handle-errors-by-code.mdx): the three channels every failure carries, the stable code name to branch on, the coarse status for policy.
- [License the runtime](license-the-runtime.mdx): 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](package-clikart-in-an-android-app.mdx): 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](/examples.md): the bundle's standalone projects, one per subsystem, each building its topic up chapter by chapter.

For every public name, the [API reference](/api/index.md).