ClikaRT::io

namespace

Classes

Name	Description
AdaptCompose	N source parts produce ONE adapted entry under to, the value view. The parts are CONSUMED (their names leave the adapted key space); to may equal one of the parts (the weight + weight_scale → weight shape).
AdaptDrop	One key removed from the adapted key space (consumed, never bound), how a checkpoint's unread extras leave the strict walk's accounting.
AdaptRename	One key rename: the entry under from appears under to; metadata only (byte range, laziness, and quantization metadata are preserved). reverse_dims additionally relabels a DENSE ≥2-D entry's shape with its dims reversed, the row-contiguous-first export re-labeled to the C order a consumer's slots declare; a quantized payload's logical shape is already row-contiguous-first, so the flag passes it through unchanged. The relabel is this explicit flag, never implicit.
AudioData	A decoded waveform plus its effective layout.
AudioInfo	An audio stream's effective layout, read from its header. With non-zero target_* the figures reflect what a decode to that target would produce (duration in seconds = frames/sample_rate).
FrameBatch	A decoded batch of frames plus the alignment metadata a video model needs: the packed [K, H, W, 3] UInt8 frames, the source frame indices they were taken from, and per-frame pts_seconds / duration_seconds. Indexable / iterable: operator[] yields a single-frame view, and begin()/end() iterate single-frame views in order.
GgufCheckpoint	A GGUF checkpoint opened lazily: the tensors as a TensorsContainer (materialize-on-get) plus the file's metadata key/value pairs as JSON.
GgufModel	A loaded GGUF checkpoint: the tensors plus the file's metadata key/value pairs as a JSON object (e.g. metadata.at("general.architecture")).
ImageInfo	An image's native pixel geometry (channels-last), read from its header.
LoadPlan	The recommended load PLAN: the policy plus the placement budget a weight-residency scheduler consumes: how many bytes of weights to KEEP device-resident (the rest streams; evicted after use, prefetched ahead of it). When the checkpoint fits under the runtime's offload-headroom share of the device's available memory, the budget is the checkpoint's total_bytes() (keep everything) and policy.sticky is false; when it doesn't fit, the budget is that headroom share and policy.sticky is true; when the available figure is unknown, the budget is 0 and the policy is plain; the runtime never guesses.
LoadPolicy	How a policy-taking loader materializes tensors.
OnnxAttr	A typed node attribute for add_node: the attribute name plus one of the ONNX attribute kinds: INT, FLOAT, STRING, INTS, or FLOATS.
OnnxModel	An ONNX model, opened from disk or built from scratch. Move-only.
OnnxModelOptions	Options governing an OnnxModel's editing and serialization behavior; pass to open / create, they hold for the model's lifetime.
TensorsAdapter	The declarative adaptation adapt applies. Keys no entry references pass through under their own names.
TensorsContainer	A lazily-materializing view of a checkpoint's tensors. Move-only: the container caches each materialized tensor so repeated gets share one storage, and that cache must have a single owner.
VideoData	A decoded clip plus its stream info: the returned FrameBatch carries every frame [T, H, W, 3] UInt8 (host). Guarded against a decompression bomb; a large clip should use VideoReader (ClikaRT/io/video.h) for per-index access. path is copied.
VideoInfo	A video stream's static geometry / timing, read from its header. Named VideoInfo (NOT VideoMetadata, which is the processor's 3-field timing struct) since it is a superset: geometry + codec identity too.
VideoReader	A lazily-opened video. open reads the header only; info() reports the stream metadata; the frames_* getters decode on demand. frames_at is the primitive; a custom sampling policy computes its own indices against info() and calls it. Move-only.
VideoWriter	Encode a stream of channels-last RGB [H, W, 3] UInt8 frames to a video file. Move-only. Every fallible method raises ClikaRT::Error on failure.

Functions

peek_image(string_view)

ImageInfo peek_image(std::string_view path)

Read an image header. Supports the common encoded formats (PNG/JPEG/…). A missing/unreadable file or an undecodable header → a failure Result. path is copied, not retained.

Declared in ClikaRT/io/io.h, line 49

peek_image(Span< uint8_t>)

ImageInfo peek_image(ClikaRT::Span<const std::uint8_t> bytes)

Header peek over an in-memory encoded image (e.g. an uploaded body). bytes is read during the call, not retained.

Declared in ClikaRT/io/io.h, line 53

peek_audio(string_view, int, int)

AudioInfo peek_audio(
    std::string_view path,
    int target_sample_rate = 0,
    int target_channels = 0
)

Read an audio header (WAV/MP3/FLAC/OGG/…). target_sample_rate / target_channels of 0 report the file's native values; a non-zero value reports the effective figures after the resample/downmix a decode would apply. A missing/unreadable file or an undecodable header → a failure Result. path is copied, not retained.

Declared in ClikaRT/io/io.h, line 61

peek_audio(Span< uint8_t>, int, int)

AudioInfo peek_audio(
    ClikaRT::Span<const std::uint8_t> bytes,
    int target_sample_rate = 0,
    int target_channels = 0
)

Header peek over an in-memory encoded audio payload; same target_* semantics as the path overload. bytes is read during the call, not retained.

Declared in ClikaRT/io/io.h, line 65

load_npy()

Tensor load_npy(std::string_view path, Device device = Device::cpu())

Load a NumPy .npy array as a Tensor on device. path is copied.

Declared in ClikaRT/io/io.h, line 84

save_npy()

void save_npy(const Tensor& tensor, std::string_view path)

Write tensor as a .npy file at path (materialized contiguous on host).

Declared in ClikaRT/io/io.h, line 87

load_image(string_view, int)

Tensor load_image(std::string_view path, int requested_channels = 0)

Decode an image to a host Tensor [H, W, C] (channels-last). requested_channels of 0 keeps the native channel count; 1/3/4 force gray/RGB/RGBA. Move it to a device with .to(...).

Declared in ClikaRT/io/io.h, line 93

load_image(Span< uint8_t>, int)

Tensor load_image(ClikaRT::Span<const std::uint8_t> bytes, int requested_channels = 0)

Decode an in-memory encoded image (an uploaded body, say); same requested_channels contract as the path overload. bytes is not retained.

Declared in ClikaRT/io/io.h, line 97

encode_image()

std::vector<std::uint8_t> encode_image(const Tensor& image)

Encode a host image Tensor as an untagged PNG payload (exactly IHDR/IDAT/IEND; no color-profile chunks, so a color-managing decoder such as a browser canvas never perturbs the pixel values; class-index masks and depth maps round-trip exactly). image is [H, W] or [H, W, C] channels-last: UInt8 with 1/3/4 channels (gray/RGB/RGBA), or UInt16 single-channel (16-bit gray). Strided views and device tensors are materialized internally.

Declared in ClikaRT/io/io.h, line 107

save_image()

void save_image(const Tensor& image, std::string_view path)

Encode an image Tensor as an untagged PNG file at path (created / truncated). Same accepted shapes/dtypes as encode_image.

Declared in ClikaRT/io/io.h, line 111

load_audio(string_view, int, int)

AudioData load_audio(
    std::string_view path,
    int target_sample_rate = 0,
    int target_channels = 0
)

Decode audio to a host Float32 Tensor + its layout. target_sample_rate / target_channels of 0 keep the native values; non-zero resamples/downmixes.

Declared in ClikaRT/io/io.h, line 116

load_audio(Span< uint8_t>, int, int)

AudioData load_audio(
    ClikaRT::Span<const std::uint8_t> bytes,
    int target_sample_rate = 0,
    int target_channels = 0
)

Decode an in-memory encoded audio payload; same target_* semantics as the path overload. bytes is not retained.

Declared in ClikaRT/io/io.h, line 120

encode_audio()

std::vector<std::uint8_t> encode_audio(const Tensor& samples, int sample_rate)

Encode a waveform as a 16-bit PCM WAV payload (RIFF/WAVE: the 44-byte header with one PCM fmt chunk and one data chunk, then little-endian interleaved frames); load_audio reads it back with the same layout. samples is [frames] (mono) or [frames, channels] interleaved: a float tensor (Float16 / BFloat16 / Float32 / Float64) holds values in [-1, 1] and converts to 16-bit codes (a value outside [-1, 1] clips); an Int16 tensor is written as is. sample_rate is in Hz. Strided views and device tensors are materialized internally. Any other rank or dtype, an empty tensor, a non-positive sample_rate, or a payload past the format's 4 GiB data limit is a failure Result (INVALID_ARGUMENT). To write a decoded clip back, pass audio.samples with audio.info.sample_rate.

Declared in ClikaRT/io/io.h, line 134

save_audio()

void save_audio(
    const Tensor& samples,
    int sample_rate,
    std::string_view path
)

Write a waveform as a 16-bit PCM WAV file at path (created / truncated); the file's bytes are exactly encode_audio's. Same accepted shapes and dtypes as encode_audio; a file that cannot be opened or written is a failure Result naming the path. path is copied, not retained.

Declared in ClikaRT/io/io.h, line 140

load_safetensors(string_view, Device)

NamedTensors load_safetensors(std::string_view path, Device device = Device::cpu())

Load a safetensors checkpoint (single-file or sharded *.index.json) into a NamedTensors on device. path is copied.

Declared in ClikaRT/io/io.h, line 145

save_safetensors()

void save_safetensors(const NamedTensors& tensors, std::string_view path)

Write tensors to a single-file safetensors checkpoint at path (created / truncated).

Declared in ClikaRT/io/io.h, line 148

load_safetensors(string_view, LoadPolicy)

TensorsContainer load_safetensors(std::string_view path, LoadPolicy policy)

Open a safetensors checkpoint (single-file or sharded *.index.json) as a lazy TensorsContainer materializing per policy (ClikaRT/io/tensors_container.h). path is copied.

Declared in ClikaRT/io/io.h, line 154

peek_safetensors_metadata()

json::Json peek_safetensors_metadata(std::string_view path)

Header-only peek at a safetensors checkpoint's CHECKPOINT-LEVEL metadata: eager, and no tensor payload is read. A single .safetensors file yields the header's reserved __metadata__ object (an empty object when the file carries none, not an error); a sharded checkpoint (*.index.json, or a directory carrying the index) yields the index document's own top-level "metadata" object, absent likewise meaning empty. A malformed header, a non-object metadata entry, or an unresolvable path fails with a typed error naming the file. path is copied.

Declared in ClikaRT/io/io.h, line 165

load_torch_checkpoint(string_view, Device)

NamedTensors load_torch_checkpoint(std::string_view path, Device device = Device::cpu())

Load a torch checkpoint (the modern zip container: pytorch_model.bin single-file or sharded *.bin.index.json) into a NamedTensors on device. The metadata pickle is parsed by a RESTRICTED interpreter that never executes code (a closed allowlist of state-dict constructors); the legacy pre-zip stream and compressed archives are rejected with a clear error. path is copied.

Declared in ClikaRT/io/io.h, line 174

load_torch_checkpoint(string_view, LoadPolicy)

TensorsContainer load_torch_checkpoint(std::string_view path, LoadPolicy policy)

Open a torch checkpoint as a lazy TensorsContainer materializing per policy: zero-copy per tensor on a CPU target (the archive's STORED entries mmap in place).

Declared in ClikaRT/io/io.h, line 180

load_gguf(string_view, Device)

GgufModel load_gguf(std::string_view path, Device device = Device::cpu())

Load a GGUF checkpoint (tensors + metadata) onto device. path is copied.

Declared in ClikaRT/io/io.h, line 184

load_gguf(string_view, LoadPolicy)

GgufCheckpoint load_gguf(std::string_view path, LoadPolicy policy)

Open a GGUF checkpoint as a lazy GgufCheckpoint materializing per policy: the TensorsContainer analog of load_gguf. path is copied.

Declared in ClikaRT/io/io.h, line 195

peek_video(string_view)

VideoInfo peek_video(std::string_view path)

Peek a video stream's header WITHOUT decoding frames. path is copied.

Declared in ClikaRT/io/io.h, line 231

peek_video(Span< uint8_t>)

VideoInfo peek_video(ClikaRT::Span<const std::uint8_t> bytes)

Header peek over in-memory encoded video bytes. bytes is not retained.

Declared in ClikaRT/io/io.h, line 234

load_video(string_view)

VideoData load_video(std::string_view path)

Decode the whole video at path: every frame [T, H, W, 3] UInt8 on host, plus the stream info.

Throws

• ClikaRT::Error: on a missing or undecodable file, or when no decode backend exists (see video_capability).

Declared in ClikaRT/io/io.h, line 248

load_video(Span< uint8_t>)

VideoData load_video(ClikaRT::Span<const std::uint8_t> bytes)

Decode an in-memory encoded video. bytes is not retained.

Declared in ClikaRT/io/io.h, line 251

video_capability()

bool video_capability()

Whether a usable video decode backend exists on this host (e.g. an ffmpeg discoverable on PATH for the Linux backend). The video decode entries raise a readable error when this is false. Infallible.

Declared in ClikaRT/io/io.h, line 257

temp_directory_path()

std::string temp_directory_path()

The system temporary directory (honoring TMPDIR / the platform default), as a string; a std::filesystem::path cannot cross the ABI. Raises ClikaRT::Error if no temporary directory can be resolved.

Declared in ClikaRT/io/io.h, line 265

adapt()

TensorsContainer adapt(TensorsContainer source, TensorsAdapter adapter)

Declared in ClikaRT/io/tensors_container.h, line 278

recommended_load_policy()

LoadPolicy recommended_load_policy(const TensorsContainer& container, StreamOrDevice device)

Declared in ClikaRT/io/tensors_container.h, line 294

recommended_load_plan()

LoadPlan recommended_load_plan(const TensorsContainer& container, StreamOrDevice device)

Declared in ClikaRT/io/tensors_container.h, line 314

ClikaRT/io/io.h

#include <ClikaRT/io/io.h>

File I/O for tensors and media: the header-only metadata probes (peek_*), the weight/checkpoint loaders (safetensors, gguf, npy), the image/audio decoders, and their writers (encode_image / save_image to PNG, encode_audio / save_audio to 16-bit PCM WAV). Loaders return a Tensor (single array) or a NamedTensors (a checkpoint's name-to-tensor map). The target device places the result; the image/audio decoders produce a host Tensor (move it with .to(...)).

ClikaRT/io/onnx_model.h

#include <ClikaRT/io/onnx_model.h>

io::OnnxModel: an ONNX model as a FORMAT-LEVEL object: open an existing .onnx file or create one from scratch, inspect and edit it (inputs, outputs, initializers, nodes), save it back, and, when you want to run it, compile it into an executable ClikaRT::ModelGraph.

The split is deliberate: OnnxModel is the REPRESENTATION (the ONNX graph as data; no inference happens here); graph::ModelGraph is the EXECUTION form. compile is the one crossing between them.

Every fallible operation returns its value directly and raises ClikaRT::Error on failure. Wrap a call in CLIKART_TRY(...) to inspect a Result instead of catching.

ClikaRT/io/tensors_container.h

#include <ClikaRT/io/tensors_container.h>

Lazy checkpoint access: a TensorsContainer is what the policy-taking checkpoint loaders return. Construction parses HEADERS only, walking a large checkpoint's names, shapes, and byte sizes costs no payload IO; a tensor materializes on get(name) (zero-copy from the file mapping on CPU; uploaded on a device target). Evicted tensors restore transparently from the checkpoint on their next use, so a model's weights can be streamed rather than held resident.

ClikaRT/io/video.h

#include <ClikaRT/io/video.h>

Lazy video decode / encode: a torchcodec-shaped VideoReader (open → metadata → index/timestamp frame access → iterable batches) and a VideoWriter. The one-shot load_video / peek_video / video_capability live on the umbrella ClikaRT/io/io.h; reach for VideoReader when a clip is large or you want per-index / batched access.

Frames are host [K, H, W, 3] UInt8 (channels-last RGB); move to a device with .to(...). Every returned FrameBatch carries the source indices + per-frame pts_seconds, which a video model needs upstream to align frames (grid, timestamp tokens). The decode backend is first-party per OS (an ffmpeg subprocess on Linux); io::video_capability() reports availability.