How MTPLX Classifies Models Before Execution Using Runtime Contracts

MTPLX classifies models into compatibility tiers—verified, arch-compatible, needs-verification, mtp-missing, and others—through a lightweight metadata scan that never memory-maps tensor data, using runtime contracts as gate-keepers to promote unverified models to verified status without heavy I/O.

Model classification at scale requires balancing speed against safety. MTPLX solves this by separating metadata inspection from tensor loading. When you browse models in the MTPLX picker, the system executes a fast pipeline that reads config.json, detects Multi-Token Prediction (MTP) artifacts, and evaluates runtime contracts—all before a single safetensors file is mapped into memory. This article breaks down exactly how MTPLX classifies models before execution using its runtime contract system, based on the source code in youssofal/MTPLX.

The Six-Stage Classification Pipeline

The classification process in MTPLX follows a deterministic pipeline implemented across mtplx/ui/onboarding.py and mtplx/backends/registry.py. Each stage builds a StubInspection object that eventually feeds into a CompatibilityVerdict.

Stage 1: Extract Architecture Hints from config.json

The scanner begins by parsing the model's config.json to identify core metadata:

• architecture – the model's class name
• model_type – the Hugging Face model type identifier
• MTP-specific fields: mtp_num_hidden_layers, num_nextn_predict_layers, num_mtp_modules

These fields hint at MTP capability but do not confirm tensor availability.

Stage 2: Detect MTP Artifacts Without Loading Tensors

MTPLX performs two zero-copy checks:

Check	Implementation	Output Flag
Side-car file existence	Tests for mtp.safetensors adjacent to model weights	mtp_artifact_exists
Embedded key scan	_scan_embedded_mtp_keys searches weight index for MTP tensor names	mtp_tensor_gate

Both operations inspect file metadata or index structures only—no tensor data is read.

Stage 3: Load the Runtime Contract

If mtplx_runtime.json exists in the model directory, MTPLX parses it via load_runtime_contract in mtplx/backends/registry.py. The contract deserialization uses RuntimeContract.from_dict to validate and bind fields:

# Example: inspecting the parsed runtime contract

from mtplx.backends.registry import load_runtime_contract

contract, err = load_runtime_contract(
    "/home/user/.cache/huggingface/hub/models--Qwen--qwen2-1.5b"
)
if contract:
    print(contract.to_dict())
else:
    print(f"Failed to load contract: {err}")

The RuntimeContract schema includes:

• mtplx_version – contract format version
• arch_id – canonical architecture identifier
• mtp_depth_max – maximum MTP layers supported
• recommended_profile – execution profile hint
• exactness_baseline – numerical accuracy requirements
• verified_on – provenance metadata
• mtp_contract (optional) – MTP-specific parameters

Stage 4: Build the Stub Inspection Object

The scanner aggregates all gathered metadata into a StubInspection object. This stub contains:

• Architecture and model type
• MTP layer counts from config
• Boolean flags for artifact existence
• Parsed runtime_contract_data
• File paths for contract and weight files

No safetensors are memory-mapped at this stage. The stub is strictly metadata.

Stage 5: Execute the Compatibility Engine

The stub passes to compatibility_for_inspection in mtplx/backends/registry.py. This engine returns a CompatibilityVerdict with three critical fields:

1. Raw tier – the base classification (verified, family-compatible-unverified, architecture-compatible-but-unverified, etc.)
2. can_run – boolean indicating basic executability
3. runtime_compatibility – detailed status of contract evaluation

Stage 6: Apply Contract-Driven Override Logic

The final tier resolution occurs in _classify_scanned_model (mtplx/ui/onboarding.py, lines ~500-540). This function implements the promotion logic that makes runtime contracts powerful:

Verified tier – If the raw tier is verified, the model receives final classification verified regardless of contract presence.

Arch-compatible tier – If can_run is true or the model is family-compatible, classification becomes arch-compatible.

Contract promotion path – For architecture-compatible-but-unverified models, MTPLX applies a three-condition gate:

• verdict.runtime_contract is present
• contract.arch_id matches SUPPORTED_ARCH_IDS
• Contract parsing succeeded without error

When all conditions pass, the tier promotes from unverified to verified. This is the core mechanism: runtime contracts act as cryptographic attestations that elevate trust without tensor inspection.

Failure paths – Depending on runtime_compatibility status, models may classify as:

• mtp-missing – MTP weights absent where required
• mtp-invalid – MTP tensor layout malformed
• needs-verification – contract present but insufficient for promotion
• backend-pending – backend support incomplete
• incompatible – fundamental architecture mismatch

Runtime Contract as Gate-Keeper

The RuntimeContract system in mtplx/backends/registry.py enables MTPLX to delegate trust. Rather than requiring every user to tensor-verify every model, the ecosystem can rely on signed or attested contracts from trusted publishers. The contract schema is versioned (mtplx_version) and architecture-bound (arch_id), preventing stale or mismatched attestations from granting false verified status.

Key verification points:

• Contracts are optional — models without contracts can still reach arch-compatible tier
• Contracts are strict — any parsing error or arch_id mismatch voids promotion
• Contracts are fast — JSON parsing adds microseconds, not milliseconds

Working with Model Classification Programmatically

You can invoke the same classification pipeline used by the MTPLX UI:

# Example: manually classifying a local model directory

from pathlib import Path
from mtplx.ui.onboarding import _classify_scanned_model

model_dir = Path("/home/user/.cache/huggingface/hub/models--Qwen--qwen2-1.5b")
scanned = _classify_scanned_model(model_dir)

print(f"Model tier: {scanned.tier}")          # e.g. "verified"

print(f"Arch ID: {scanned.arch_id}")          # e.g. "qwen2-mtp"

print(f"Runtime contract path: {scanned.runtime_contract_path}")

The returned scanned object exposes the final tier, architecture identifier, and contract file path—useful for building custom model registries or CI verification pipelines.

Key Source Files

Understanding MTPLX model classification requires familiarity with these components:

• mtplx/backends/registry.py — Defines RuntimeContract, load_runtime_contract, compatibility_for_inspection, and SUPPORTED_ARCH_IDS
• mtplx/ui/onboarding.py — Implements _classify_scanned_model, the orchestration layer that sequences config parsing, MTP detection, and contract evaluation
• mtplx/artifacts.py — Utility functions for locating model artifacts; used indirectly by the scanner
• mtplx/hf_loader.py — Demonstrates how the runtime contract influences actual model loading from Hugging Face

Summary

• MTPLX classifies models through six lightweight stages that never memory-map tensor data
• The runtime contract (mtplx_runtime.json) can promote models from architecture-compatible-but-unverified to verified when arch_id matches SUPPORTED_ARCH_IDS
• Zero-copy checks for mtp.safetensors and embedded MTP keys establish MTP capability without I/O overhead
• The CompatibilityVerdict and _classify_scanned_model implement a tiered trust system with explicit failure modes
• All classification logic resides in mtplx/backends/registry.py and mtplx/ui/onboarding.py

Frequently Asked Questions

What happens if a model has no runtime contract?

The model can still achieve arch-compatible tier if its architecture is recognized and basic compatibility checks pass. Without a contract, it cannot be promoted to verified status even if tensor verification would succeed—contracts are the only path from unverified to verified in the current implementation.

Can runtime contracts be forged or tampered with?

The base RuntimeContract schema in MTPLX does not include cryptographic signatures, though the verified_on field provides provenance metadata. Downstream deployments may wrap contracts in additional attestation layers. The arch_id binding prevents simple cross-model reuse of contracts.

Why does MTPLX avoid memory-mapping tensors during classification?

Memory-mapping safetensors files adds latency (disk I/O, kernel page table setup) and memory pressure. For model pickers scanning hundreds of candidates, this overhead dominates. The stub-based approach keeps classification under milliseconds per model, enabling responsive UI experiences.

What is the difference between mtp-missing and needs-verification tiers?

mtp-missing indicates that MTP functionality was expected (config hints present) but weight files or embedded tensors are absent—this is a concrete artifact problem. needs-verification indicates that a contract exists but is insufficient to auto-promote the model, or no contract exists and the architecture requires explicit user confirmation before execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}