# How MTPLX Classifies Models Before Execution Using Runtime Contracts

> Discover how MTPLX classifies models using runtime contracts, promoting unverified models to verified status through a lightweight metadata scan without memory mapping tensor data.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: internals
- Published: 2026-09-06

---

**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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/ui/onboarding.py) and [`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py). Each stage builds a `StubInspection` object that eventually feeds into a `CompatibilityVerdict`.

### Stage 1: Extract Architecture Hints from [`config.json`](https://github.com/youssofal/MTPLX/blob/main/config.json)

The scanner begins by parsing the model's [`config.json`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx_runtime.json) exists in the model directory, MTPLX parses it via `load_runtime_contract` in [`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py). The contract deserialization uses `RuntimeContract.from_dict` to validate and bind fields:

```python

# 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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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:

```python

# 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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py)** — Defines `RuntimeContract`, `load_runtime_contract`, `compatibility_for_inspection`, and `SUPPORTED_ARCH_IDS`
- **[`mtplx/ui/onboarding.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/ui/onboarding.py)** — Implements `_classify_scanned_model`, the orchestration layer that sequences config parsing, MTP detection, and contract evaluation
- **[`mtplx/artifacts.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/artifacts.py)** — Utility functions for locating model artifacts; used indirectly by the scanner
- **[`mtplx/hf_loader.py`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py)** and **[`mtplx/ui/onboarding.py`](https://github.com/youssofal/MTPLX/blob/main/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.