Configuration reference

Riftco Transformer has four independent configuration layers: CMake chooses the native engine that is built, backend selectors choose storage and kernels, Python workflow configs choose training behavior, and source-only lab configs choose evaluation protocols. Changing one layer does not silently rewrite another.

Build requirements#

CMake options#

Source: CMakeLists.txt, RiftcoTransformerBackends.cmake, and RiftcoTransformerSanitizers.cmake.

When tests are enabled, RIFTCO_TRANSFORMER_BUILD_PYTHON_TESTS defaults to ON. The test-only switches RIFTCO_TRANSFORMER_TEST_REQUIRE_METAL, RIFTCO_TRANSFORMER_TEST_REQUIRE_CUDA, and RIFTCO_TRANSFORMER_TEST_REQUIRE_TPU default to OFF; turn one on to make absence of that accelerator fail the relevant conditional tests instead of skip them.

Presets#

bashcmake --preset release
cmake --build --preset release
ctest --preset release

Backend selection#

Python auto selects the first available backend in this order: TPU, CUDA, Metal, CPU. Explicit unavailable selections fail; they never fall back. C++ operations use the intrinsic backend of their tensor inputs, and newly created objects capture the calling thread's construction default. Use Tensor::to, Module::to, or Python .to() for explicit transfer.

Backend limitations and availability probes are documented in Backends and Python ABI.

Native dense Llama/Mistral settings#

LlamaMistralConfig selects the architecture identity plus vocabulary, maximum context, model/feed-forward widths, block count, query/KV head counts, RMSNorm epsilon, and RoPE theta. All dimensions are positive; model width must divide by query heads, query heads by KV heads, and the resulting head width must be even. Epsilon and theta are finite and positive.

An optional sliding window is accepted only when it covers the complete maximum context, where dense causal attention is equivalent. Smaller windows are rejected. The current full-sequence runtime is exposed through native C++, C ABI 2.8, and Python. These surfaces are not external checkpoint or tokenizer loaders and do not add incremental decode semantics. See the complete Llama/Mistral support matrix.

Native C++ serving settings#

stages::serving::ServingConfig#

Defaults: CPU, at most 256 new tokens, paged KV cache, 16-token blocks, and kv_cache_block_count=0. Zero block count allocates enough blocks for one maximum-length context. Serving has no optimizer or gradient settings.

The reusable native serving composition remains framework-owned. Its authoritative declarations are under include/riftco_transformer/stages.

Python stage settings#

Python configs are immutable dataclasses and validate at construction.

PretrainingConfig#

In addition to native model/execution choices, Python controls a validation fraction (0.1), validation batch count (4), evaluation interval (10), loss-average window (10), validation seed (17), and Adam state layout. Defaults are BPE, backend="auto", materialized attention, disabled block checkpointing, contiguous optimizer state, and 4096-element state pages.

PostTrainingConfig#

serving.ServingConfig#

Defaults: backend="auto", 256 maximum new tokens, 1 MiB maximum request, kv_cache="paged", and block size 16. The HTTP server is dependency-free and is configured through create_http_server or serve_model; there is no installed server CLI.

Source: python/riftco_transformer.

Neural-lowering settings#

lowering::NeuralLoweringConfig belongs only to the optional compiler-to-neural bridge.

mlp is a registered diagnostic strategy, but the current GELU MLP cannot exactly preserve a general multilinear map. It reports unsupported unless the configured policy permits a dense fallback.

See Compiling to transformers.

Program-augmented model settings#

The C++ ProgramAugmentedModelConfig and installed Python programmed.ProgramAugmentedModelConfig describe only generic model shape and initialization:

An optional Python ProgramBranch adds map, source and target offsets and lengths, logical ProgramInputLayout records, lowering policy, input_projection_bias, and merge_bias. Each layout selects whole_source or one source_position; equal projection_group values share one learned projection and parameter identity. Source and target spans must fit the fixed context, but their offsets are otherwise task-neutral.

ProgramAugmentedForwardOptions controls capture_representations, learned attention batch roll, affine steering, selected program-input batch rolls, program-output batch roll, and their shared positive batch_roll_shift. MultilinearMap.from_sparse accepts output-major nonzero indices and values; the current lowerer still applies max_coefficient_elements before allocating its dense native representation.

Research-lab settings#

Top-level labs/ owns experiment configuration, fixed seeds, candidate construction, held-out selection, and report paths. Those modules compose only public Python framework APIs and are not installed. Inspect a lab's current configuration with:

bashPYTHONPATH=python:. python3 -m labs.lora_rank.run --help
PYTHONPATH=python:. python3 -m labs.fine_tuning.run --help
PYTHONPATH=python:. python3 -m labs.conditional_reverse.run --help

The conditional-reversal lab owns named quick and paper profiles, F/P/T/I variant selection, backend, seeds, data sizes, optimization, validation/test policy, interpretation, and report paths. A short explicit invocation is:

bashPYTHONPATH=python:. python3 -m labs.conditional_reverse.run \
  --profile quick --variants F --backend cpu \
  --output runs/conditional-reverse/quick.json

Run --help to verify exact current flags and defaults before launching a profile. These settings are lab policy layered over riftco_transformer.programmed; they are not fields added to the C++ generic model.

Environment variables#

Example CUDA wheel build:

bashCMAKE_ARGS="-DRIFTCO_TRANSFORMER_ENABLE_CUDA=ON" python3 -m pip install .

For failure diagnosis, use Troubleshooting.