API reference

This page indexes the supported public surfaces of Riftco Transformer 0.6.1. It is a navigation reference, not generated Doxygen: signatures are shortened where that improves scanning, and the linked headers remain authoritative. See Architecture for subsystem boundaries and Project structure for implementation ownership.

Package targets#

Installed consumers use CMake 3.24 or newer and C++20:

cmakefind_package(riftco_transformer 0.6 CONFIG REQUIRED)
target_link_libraries(app PRIVATE riftco_transformer::library)

The exported target definitions live in CMakeLists.txt and RiftcoTransformerInstall.cmake. The installed CMake package uses same-minor version compatibility. Only the C surface carries an explicit binary ABI version; C++ consumers should rebuild against the selected package release.

C++ core runtime#

All names below are in riftco_transformer unless another namespace is shown.

Representative tensor and autograd signatures:

cppTensor tensor({2, 3}, values, ExecutionBackend::Cpu);
Tensor product = tensor_ops::matmul(left, right);

Variable x(Tensor({2}, {2.0F, 3.0F}));
Variable loss = sum(x * x);
loss.backward();

See Tensor, Tensor operations, and Autograd for behavioral detail.

Modules, models, and optimization#

Model construction and forward:

cppstd::mt19937 random(42);
DecoderOnlyTransformer model(
    TransformerDimensions{256, 16, 32, 4, 2, 64}, random
);
Variable logits = model.forward(token_ids, {batch, time});

forward() returns [batch, time, vocabulary]. Training parameters come from model.parameters(); after LoRA attachment, adapter parameters come from model.lora_parameters(). Quantized frozen weights deliberately do not appear in either optimizer list. See Modules, Transformer, LoRA, QLoRA, and Adam. The distinct dense family topology and its current non-goals are listed in Dense Llama and Mistral runtime boundary.

Data, native serving, and artifacts#

The stage umbrella is stages/stages.hpp. Configuration defaults are listed in Configuration reference.

Compiler, lowering, and interpretation#

The compiler and analysis libraries do not depend on the tensor runtime. Lowering is the explicit one-way bridge into differentiable modules. Cajal is a finite, first-order language constructed through C++ APIs; it is not a text parser or a general lambda-calculus implementation. See Compiling to transformers.

Program-augmented composition#

ProgramAugmentedModel is a fixed-context, task-neutral composition. For token-plus-position state \(x\), residual width \(D\), and \(N\geq1\) independently parameterized causal-attention branches, its learned path is

Without a program, \(r_2=r_1+h\). With a ProgramBranch, the model selects the configured source span, runs ProgrammedSequenceCore, places the raw program output at the arbitrary configured target offset with zeros elsewhere, and computes

A final learned projection produces vocabulary logits. The branch config owns source/target offsets, core input layouts and shared projection groups, a lowered module, and optional merge bias. Forward options support affine program-input steering and one shared positive batch-roll shift for learned attention, selected program inputs, and/or raw program output. These are graph interventions: gradients still flow through placement and the selected model paths.

When capture is enabled, the owning host trace uses these stable names:

• embedding.sum
• residual.pre_attention
• learned_attention.merged
• program.source when a branch exists
• program.input.N and program.input.N.projected for each logical input
• program.output.raw and program.output.placed when a branch exists
• residual.post_merge
• logits

cross_entropy_time_range(logits, targets, time_offset, time_count) selects the same contiguous time interval independently in every [batch,time,vocab] row before taking mean cross entropy. Ordinary cross_entropy remains the all-position objective.

Stable C ABI#

c_api.h defines C ABI 2.8. It uses fixed-width constants, status returns, versioned value structures, and opaque handles:

crt_context* context = NULL;
rt_status status = rt_context_create(RT_BACKEND_CPU, &context);
/* use context */
rt_context_release(context);

Initialize every versioned structure with its matching rt_*_init function and its actual sizeof(...). Every successful create returns one handle that must be released exactly once. Derived handles retain model state, but a live decode session pins model backend and parameter values. Raw C calls are not internally lifetime-synchronized; callers must serialize operations involving the same state. Variable-size outputs support a null-output/zero-capacity size query. Copy rt_last_error() before the next status-returning call on that thread.

Python API#

Python 3.10+ has no runtime package dependencies. The top-level riftco_transformer module re-exports the native layer:

pythonfrom riftco_transformer import (
    Adam, Context, DecoderOnlyTransformer, LoraConfig, Tensor,
    LlamaMistralConfig, LlamaMistralTransformer, Tokenizer,
    TransformerConfig, Variable, backend_available, cross_entropy,
    cross_entropy_time_range,
)

Native wrappers are closeable context managers and cannot be copied. They retain related state and synchronize operations through shared locks. Important high-level packages are:

Repository research protocols are intentionally outside this installed API. Top-level labs contains Python-owned fine-tuning, LoRA-rank, and conditional-reversal labs; they compose the public packages above and write ignored runs/ output. In particular, the framework exposes no native F/P/T/I experiment type: conditional-reversal program construction, training, evaluation, PCA policy, and reporting remain in the Python lab.

Python loads the native library from the wheel, recognized source-build directories, the system loader, or the explicit RIFTCO_TRANSFORMER_LIBRARY path. See Troubleshooting for loader and ABI errors.