Module capability

Expand description

Explicit architecture capability registry for the generic GGUF path.

Mirrors the pinned llama.cpp llm_arch / LLM_ARCH_NAMES inventory (.scratch/llama.cpp/src/llama-arch.{h,cpp}) with Frink-side classification into decoder families, memory kinds, and scope. Unknown strings and detected-but-unimplemented features fail closed (LoadError) instead of silently defaulting into fluent-but-wrong logits.

Architecture names are registry keys only. Hot-path kernels never branch on them; load-time resolution produces an ArchProfile whose fields the decoder reads as plain data.

Structs§

ArchProfile: Load-time resolved profile for one GGUF general.architecture string.
SwaPattern: llama.cpp’s hardcoded alternating sliding-window layout for one architecture: the period, and which end of each period is the full-attention layer.
UnauditedTriage: One architecture’s triage verdict, carried on its own catalog row.

Enums§

ArchPath: How the generic Decoder / ModelConfig::from_gguf path treats a GGUF architecture string.
ArchScope: How far this architecture is in Frink’s delivery scope (plan: text-generation parity; encoder/multimodal/diffusion/audio deferred).
DecoderFamily: Shared execution family (maps many GGUF strings onto one engine path).
MemoryKind: Memory / KV backend selected once at load (llama.cpp create_memory).
QkNormStyle: How attn_q_norm / attn_k_norm weights are applied (when present).
SwaWindowOverride: What llama.cpp does with a nonzero attention.sliding_window the file declares, for the architectures whose load_arch_hparams does not simply honour it.
TriageClass: How much work admitting one UNAUDITED architecture to the generic path would actually be.

Constants§

AUDITED_GENERIC_GQA: Architectures on the shared generic-GQA path that somebody has actually PROVEN, and the evidence for each.
BIASED_LAYER_NORM: Architectures that normalise with a LayerNorm with a learned weight AND bias – build_norm(x, w, b, LLM_NORM, il) – at every norm site, the weights and the biases all REQUIRED.
BIASED_RMS_NORM: Architectures that normalise with an RMSNorm with a learned weight AND bias – build_norm(x, w, b, LLM_NORM_RMS, il) – at every norm site, all REQUIRED: phimoe (Phi-3.5-MoE), whose tensors are phimoe.cpp:20-21,28-29,35-36 and whose graph is phi3’s (phi3.cpp:99-102,137-139,174-177 pass the bias; phi3 never creates one). Measured: grep -B3 LLM_NORM_RMS src/models/*.cpp | grep norm_b is phi3 (this row’s graph), chameleon (passes NULL), and deepseek32 / glm-dsa / rwkv6qwen2 / arwkv7 on other engines. crate::norm::NormOp::RmsBias; tests/phimoe_graphs.rs.
LOGIT_SOFTCAP_ARCHITECTURES: Architectures outside the Gemma family whose graph applies the two logit softcaps frink implements – attn_logit_softcapping on the attention scores and final_logit_softcapping after the lm_head.
NON_PARAMETRIC_LAYER_NORM: Architectures that normalise with a non-parametric LayerNorm – subtract the mean, divide by the standard deviation, no learned weight and no bias – at every norm site.
NON_PARAMETRIC_RMS_NORM: Architectures that normalise with a non-parametric RMSNorm – build_norm(x, nullptr, nullptr, LLM_NORM_RMS, il) – at every norm site: no attn_norm, ffn_norm or output_norm tensor in the file.
PER_HEAD_DISTINCT_QK_NORM: Architectures whose Q/K norm is the per-head RMSNorm with one weight row per head (QkNormStyle::PerHeadDistinct). Measured over the 155 graphs: attn_q_norm created {n_embd_head_k, n_head} in five (chameleon, command-r, stablelm, which norm with LLM_NORM and are crate::qk_layer_norm’s; talkie, whose weight is {1, n_head}; and plamo2, the one RMS row).
PER_HEAD_SCALAR_QK_GAIN: Architectures whose Q norm weight is one scalar per head and whose K norm has no weight (QkNormStyle::PerHeadScalar). Measured: attn_q_norm created {1, n_head} in one of 155 graphs, talkie.cpp:26.
POST_NORM_ONLY_ARCHITECTURES: Architectures whose layers have no pre-attention norm and no pre-FFN norm at all: the post-norm-only residual topology.
SMALLTHINKER_PINNED_WINDOW: The third case’s one row: src/models/smallthinker.cpp:4-8 reads attention.sliding_window into n_swa, tests it for > 0, and on that branch assigns hparams.n_swa = 4096 – the value it just read is used as a flag and then overwritten. So a SmallThinker file declaring 3 slides at 4096, and libllama’s logits for a fixture declaring 3 and the same fixture declaring 4096 are BYTE-IDENTICAL (measured, tests/router_input_graphs.rs). A file declaring 0 or nothing takes the other branch (:16-18): no window, every layer rotated.
TRIAGE_PENDING: Unaudited generic-path architectures nobody has read against llama.cpp’s graph yet.
WEIGHTED_LAYER_NORM: Architectures that normalise with a LayerNorm with a learned weight and no bias – build_norm(x, w, NULL, LLM_NORM, il) – at every norm site.

Functions§

architecture_catalog: Full inventory keyed by GGUF general.architecture string. Kept in sync with .scratch/llama.cpp/src/llama-arch.cpp LLM_ARCH_NAMES.
attention_scale_override: llama.cpp’s hparams.f_attention_scale, but only when it DIFFERS from the 1/sqrt(head_dim) every frink attention kernel already applies. None means “the kernels’ own scale is already right”, so a caller stores it straight into ModelConfig::attention_scale.
canonical_architecture: Resolve a GGUF general.architecture value. None means the string is not in the registry – callers must fail closed rather than guess. The architecture whose TABLES an alias should be read from.
coverage_report_markdown: Markdown coverage table for docs / CI drift checks.
default_swa_layout
embeddings_scaled_by_sqrt_n_embd: True when this architecture’s graph multiplies every token embedding by sqrt(n_embd) as ARITHMETIC, reading no key for it.
is_audited_generic: Is this architecture’s use of the shared generic path backed by evidence?
is_post_norm_only: Does this architecture read the raw residual at both sublayers? See POST_NORM_ONLY_ARCHITECTURES.
resolve_architecture
resolve_profile: Resolve a GGUF general.architecture value to its profile.
swa_disabled_by_arch: Every architecture for which llama.cpp seeds a sliding-window period before letting {arch}.attention.sliding_window_pattern override it, transcribed from src/models/*.cpp.
swa_rope_base_follows_model: True when this architecture’s SWA layers use the model’s own RoPE base rather than llama.cpp’s rope_freq_base_train_swa default of 10000.
swa_rope_scale_follows_model: True when this architecture’s SWA layers inherit the model’s TRAINED RoPE position scale rather than llama.cpp’s rope_freq_scale_train_swa default of 1.0.
swa_window_override: See SwaWindowOverride.
unaudited_refusal_detail: The triage half of the UnauditedArchitecture refusal, rendered for the user.
unaudited_triage: This architecture’s triage verdict, or None when it has not been triaged (see TRIAGE_PENDING) or does not need one.
unsupported_feature_keys: Metadata keys that, when present with a nonzero value, require math frink’s generic decoder does not implement unless the architecture profile opts into those features (Gemma family), or the architecture is named in LOGIT_SOFTCAP_ARCHITECTURES for the softcaps.
unsupported_scaling_keys: Scalar multipliers a checkpoint can declare in metadata that the generic decoder does not apply, with the value that means “no-op”.
uses_biased_layer_norm: See BIASED_LAYER_NORM.
uses_biased_rms_norm: See BIASED_RMS_NORM.
uses_geglu: Architectures whose FFN gate uses GELU rather than SiLU, i.e. GeGLU rather than SwiGLU.
uses_gelu_ungated: Architectures whose FFN is the UNGATED GELU MLP: build_ffn(up, up_b, NULL gate, down, down_b, LLM_FFN_GELU, LLM_FFN_SEQ), i.e. down(gelu(up(x) + up_b)) + down_b (starcoder2.cpp:125-131, codeshell.cpp:120-126).
uses_non_parametric_layer_norm: Does this architecture normalise without any learned parameters? See NON_PARAMETRIC_LAYER_NORM.
uses_non_parametric_rms_norm: See NON_PARAMETRIC_RMS_NORM.
uses_per_head_distinct_qk_norm: See PER_HEAD_DISTINCT_QK_NORM.
uses_per_head_scalar_qk_gain: See PER_HEAD_SCALAR_QK_GAIN.
uses_reglu: Architectures whose experts are the GATED ReLU MLP: build_moe_ffn(..., LLM_FFN_RELU, ...) with gate_exps present, which llama-graph.cpp:2195-2197 runs as ggml_reglu_split(gate, up), i.e. down(relu(gate(x)) * up(x)) (smallthinker.cpp:62,158).
uses_relu_sqr: Architectures whose FFN is the UNGATED ReLU-squared MLP: build_ffn(up, NULL gate, down, LLM_FFN_RELU_SQR, LLM_FFN_SEQ), i.e. down(relu(up(x))^2) (arcee.cpp:123-128).
uses_weighted_layer_norm: Does this architecture normalise with a weighted LayerNorm? See WEIGHTED_LAYER_NORM.