feat(smollm3): add native SmolLM3 model family

[ruiling-smartbear]

Background

HuggingFaceTB/SmolLM3-3B is an Apache-2.0 dense decoder that no existing family resolves. Its published configuration declares model_type: "smollm3" and SmolLM3ForCausalLM, so it is not an alias of a Llama or Qwen checkpoint, and one architectural difference keeps it off the dense Llama path: SmolLM3 interleaves NoPE layers among its RoPE layers, published as no_rope_layers (a 1 marks a layer that applies RoPE) or derived from no_rope_layer_interval. For SmolLM3-3B that is layers 3, 7, 11, ... 35 — nine of thirty-six carry no positional encoding at all. Every other dense-contract requirement is already met: GQA 16/4, head_dim 128, SiLU, RMSNorm, no attention or MLP bias, tied embeddings, layer_types uniformly full_attention.

Opened as a draft: the implementation is complete and locally validated, but the engine build and the parity run still need a TensorRT box. Marking it ready once those are in.

Closes #1146.

Exit Criteria

• trtmc build HuggingFaceTB/SmolLM3-3B produces a family-owned bundle without trust_remote_code, passing continuation parity against the hf_transformers reference at the declared thresholds.
• The builder applies RoPE on exactly the layers upstream does, and leaves the NoPE layers unrotated.
• The served chat prompt reproduces the upstream chat template byte for byte in both reasoning modes.
• The 128k configuration the model card documents (YaRN, factor: 2.0, original_max_position_embeddings: 65536) builds.
• Out of scope for v1: the native KV graph with scaled RoPE, and any long-context qualification beyond the pinned contract case.

Implementation

• Python family families/smollm3/. ModelConfig.rope_layer_schedule() resolves the per-layer NoPE schedule from no_rope_layers, falling back to no_rope_layer_interval and finally to all-RoPE. Both decoder builders consult it at their RoPE application site, so NoPE layers reach attention unrotated; the cos/sin tables stay global and are simply unused there. A malformed schedule is rejected during build routing rather than surfacing deep in the graph builder.
• YaRN scaling. The family's existing RoPE table gained a yarn branch rather than a parallel path, so both builders pick it up unchanged. Upstream folds attention_factor (0.1 * ln(factor) + 1) into cos/sin inside the rotary embedding instead of applying it to attention scores; omitting it leaves every entry ~6.9% short at factor: 2.0, so it is applied to the table and asserted separately.
• Runtime DSO src/runtime/models/smollm3/ with strategy key smollm3_decoder_kv_cache. SmolLM3's chat template is ChatML-framed but always emits a system block — metadata plus mode-specific custom instructions — even with no system message, and does not close that block with <|im_end|>. It is implemented as its own format, matched ahead of the generic ChatML fallback, with the date injectable so the contract is testable.
• E2E root tests/e2e/models/smollm3/ with one manifest pinned to revision a07cc9a04f16550a088caea529712d1d335b0ac1, bf16, exclusive GPU, hf_transformers oracle, causal_base_continuation / continuation_parity.
• The native KV graph continues to decline scaled RoPE other than llama3, matching the other native-KV family; such checkpoints route to the standard decoder rather than failing, and the routing reason now says so.
• No shared infrastructure changed. The tokenizer needed no work: SmolLM3 carries the Llama-3 style pre-tokenizer regex, which the shared native BPE tokenizer already classifies as its kQwen3 variant with digit group 3 and the \s+(?!\S) rule.

Change categories

• Model or runtime behavior
• Public API
• ABI
• Bundle or artifact format
• Dependencies
• Documentation only
• CI or developer tooling

Validation

Rebased onto 61ac37f2; all results below were re-run on that base.

Commands and Results

• python3 tools/model_ci.py validate: passed, 93 registered model families, smollm3 present, no descriptor errors.
• CMake runtime-manifest parse driven in isolation: smollm3 resolves to libtrtmc_model_smollm3.so, plugin plugin.cpp|register_smollm3_plugin, strategy smollm3_decoder_kv_cache unique repository-wide, all four declared runtime tests present.
• pytest tests/e2e/models/smollm3/: 58 passed, 13 skipped. The 6 remaining failures are the engine-building cases that require a real TensorRT module; the same six fail identically for the llama family in the same environment.
• pytest tests/e2e/models/smollm3/test_smollm3_rope_scaling.py: 7 passed — YaRN table against an exact float64 reference, the attention-factor fold, an explicit attention_factor override, three malformed-config rejections, and an unscaled-RoPE regression guard.
• pytest tests/e2e/models/smollm3/test_smollm3_build_contract.py: 6 passed — pinned revision, family runtime contract, bf16 for the native KV path, exclusive GPU, hf_transformers oracle, no trust_remote_code.
• pytest tests/e2e/models/smollm3/test_smollm3_family_plugin_weights.py: 3 passed, including tied embeddings (w_out == embedding.T when lm_head.weight is absent, which is the case for this checkpoint).
• C++ chat-template test built and run: all cases passed, including both reasoning modes byte-for-byte against the captured upstream rendering (297 and 1369 bytes).

Reference cross-checks

• NoPE schedule. Against transformers, the builder's schedule equals SmolLM3Attention.use_rope on all 36 layers. Cross-checked behaviourally: driving one RoPE layer and one NoPE layer in isolation with identical hidden states but different relative spacing moves the RoPE layer by 1.5e-03 and the NoPE layer by exactly 0. A global position shift is deliberately not used as the probe, since RoPE is a relative encoding and is invariant to it.
• YaRN table. Against an exact float64 reference, the table sits 5.9e-08 away at positions 0-7 and 5.9e-08 at positions 70000-70007. Hugging Face's own float32 result is 3.2e-07 and 4.1e-03 at those positions, so the difference observed against SmolLM3RotaryEmbedding at long positions is upstream's float32 angle error, not this table's.
• Tokenizer. Read from the pinned tokenizer.json: Llama-3 style split regex, \p{N}{1,3}, \s+(?!\S) present, ByteLevel with add_prefix_space: false, BPE with ignore_merges: true. The shared pre-tokenizer selects kQwen3 and parses digit group 3, so no family-owned tokenizer work is required.
• Chat template. Captured from apply_chat_template() at the pinned revision for both reasoning modes and asserted verbatim.
• Checkpoint mapping. The 36-layer checkpoint carries nine tensors per layer under standard names, no lm_head.weight, no QK-norm, no biases. Running the family mapper over a checkpoint with that exact naming consumes every tensor and produces the tied output projection.

Hardware, Environment, and Revisions

• Checkpoint: HuggingFaceTB/SmolLM3-3B at a07cc9a04f16550a088caea529712d1d335b0ac1.
• Base: 61ac37f2.
• Engine build and E2E proof environment: pending, see below.

Not Run / Remaining Gaps

• The engine has not been built and no numerical parity run has been executed. The six engine-building tests, the E2E manifest case, and tools.ci model-proof all still need a TensorRT box. This is why the PR is a draft.
• v1 covers the 65536-token native window. The 128k YaRN configuration builds, but no long-context case is declared and none has been qualified.
• The native KV graph declines YaRN; those builds route to the standard decoder. That path is not qualified here either.
• Tensor parallel, quantized builds, FP32-layer overrides, and the -Base checkpoint are untested; v1 is scoped to one pinned contract case.
• Chat-instruct E2E is not declared: the family ships one validated case, so the contract plugins seeded from the template family that no manifest exercises were removed rather than left dormant.

Notes For Future Readers

• Read config.py::rope_layer_schedule() first, then its three call sites; that single boolean is the whole architectural delta from the dense Llama contract.
• The YaRN attention_factor fold is easy to drop when copying a RoPE table from another family. test_attention_factor_is_folded_into_the_table exists to catch exactly that.
• The chat-template expectations are the captured upstream rendering, not a reading of the Jinja source. Re-capture them if the checkpoint revision moves.

Risk level

• Low
• Medium
• High

Risk rationale: a new self-contained family. No public API, ABI, bundle format, or dependency change. Every changed file sits under the four smollm3 roots — the Python family, the runtime DSO, the E2E root, and the C++ runtime tests — so nothing shared is touched and no existing family changes behavior.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[Moviw]

Hi @ruiling-smartbear — thanks for the thorough implementation. I pulled your feat/smollm3 branch onto an RTX 3090 (TensorRT 11.2.1.2) to help with the engine-build gap, and hit a blocking issue before any engine can actually be built.

Repro

python3 tools/model_ci.py validate                                            # passes: 93 families, smollm3 present
pytest tests/e2e/models/smollm3/test_smollm3_standard_decoder.py -q           # 11 failed, 1 passed
pytest tests/e2e/models/smollm3/test_smollm3_builder_engine.py -q             # 6 failed, 10 passed
pytest tests/e2e/models/llama/test_llama_standard_decoder.py -q               # 12 passed (control, same box)

Every failure shares the same traceback:

AttributeError: 'ModelConfig' object has no attribute 'rope_layer_schedule'
  python/tensorrt_model_connect/families/smollm3/standard_decoder_builder.py:430
  python/tensorrt_model_connect/families/smollm3/dual_profile_decoder_builder.py:616

Root cause

rope_layer_schedule() is defined on the family-local ModelConfig in families/smollm3/config.py, but the production build path (engine_builder.py / build_cli.py) constructs the config through the shared tensorrt_model_connect.config.ModelConfig, which has no such method. The two builders call it directly, so they raise; build_routing.py uses getattr(config, "rope_layer_schedule", None) and therefore silently no-ops (which also means the malformed-schedule validation is skipped in production).

Suggested fix

Resolve the schedule from config.raw in a module-level helper (works on the shared ModelConfig too), and call that from both builders and from build_routing.py, instead of a family-local method. I have this working locally if it helps.

Want me to push a small PR against feat/smollm3 with the fix, or would you rather fold it in yourself?

[Moviw]

Hi @ruiling-smartbear — one small attribution request on the fix I posted.

If you'd like to fold the rope_layer_schedule fix into your branch, please merge it in a way that keeps the commit's author (Moviw xvzimo@gmail.com) or adds a Co-authored-by: Moviw xvzimo@gmail.com trailer — happy to help you get to a real TensorRT box to finish the engine build + parity run, too. Thanks again for the family work.