# How the MTPLX Model Compatibility Inspection System Evaluates Runtime Safety

> Discover how the MTPLX model compatibility inspection system ensures runtime safety. Analyze model metadata to verify safe execution and understand required runtime modes for your MTPLX models.

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

---

**The MTPLX model compatibility inspection system determines whether a model can execute safely by analyzing its metadata dictionary through the `compatibility_for_inspection` function in [`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py), producing a verdict that includes safety status, reasoning, and required runtime mode.**

The MTPLX repository implements a rigorous validation layer that prevents incompatible models from launching on unsupported hardware or runtime configurations. At the heart of this system lies a structured inspection protocol that parses model metadata and translates it into actionable compatibility decisions used by both the server and command-line interfaces.

## Core Architecture of the Inspection System

The compatibility inspection pipeline centers on a single authoritative function that consumes model metadata and returns a typed verdict. This design ensures consistent evaluation across all entry points in the codebase.

### The `compatibility_for_inspection` Entry Point

Located in [`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py), the **`compatibility_for_inspection`** function serves as the primary gateway for compatibility checks. It accepts an inspection dictionary—typically loaded from [`mtplx.json`](https://github.com/youssofal/MTPLX/blob/main/mtplx.json) or [`inspect.json`](https://github.com/youssofal/MTPLX/blob/main/inspect.json) within a model package—and returns a **`CompatibilityVerdict`** named tuple containing three critical fields:

- `safe`: Boolean indicating whether the model may launch
- `reason`: Human-readable explanation when `safe` is `False`
- `mode`: The `RuntimeCompatibilityMode` enum value required for execution

### Inspection Metadata Structure

The system expects the inspection dictionary to contain specific keys that drive the decision logic. Critical fields include:

- **`runtime_contract`**: Verification status of the model's runtime contract (e.g., `{"verified": true}`)
- **`runtime_compatibility`**: String identifier for required backend support (`"native"`, `"native-ar-only"`, `"needs-contract"`, or `"native-contract-gated"`)
- **`tier`**: Overall compatibility classification (`"verified"`, `"incompatible-architecture"`, etc.)
- **`can_run`** and **`exit_code`**: Optional boolean and integer fields for rapid rejection shortcuts

These fields are validated in unit tests such as [`tests/test_artifacts.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_artifacts.py) and [`tests/test_no_mlx_imports.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_no_mlx_imports.py).

## Compatibility Decision Logic

The inspection system applies a three-phase evaluation strategy to determine model viability. Each phase can short-circuit the process and return an immediate verdict.

### Contract Validation

The function first examines the **`runtime_contract`** field. If the contract exists but lacks verification, the system immediately returns an unsafe verdict with a reason such as *"runtime contract missing"*. This security gate ensures that only signed or verified models proceed to subsequent checks.

### Runtime Compatibility Mapping

When the contract validates successfully, the system maps the **`runtime_compatibility`** string to the **`RuntimeCompatibilityMode`** enum. The mapping logic handles four distinct modes:

- **`native`**: Full compatibility with any supported backend
- **`native-ar-only`**: Requires the AR-specific backend (e.g., Laguna AR)
- **`needs-contract`**: Demands a signed contract before execution
- **`native-contract-gated`**: Native mode with additional contract gating

If the current process cannot satisfy the required mode, the verdict marks the model unsafe and specifies the missing capability in the `reason` field.

### Tier and Exit-Code Short-Circuit

For performance optimization, the inspection system respects pre-computed shortcuts. When the inspection dictionary contains **`can_run`** set to `False` or a non-zero **`exit_code`**, the function bypasses detailed analysis and returns the corresponding failure state. This allows the server in [`mtplx/server/request_policy.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/request_policy.py) to reject requests instantly without redundant processing.

## Integration Points in the Codebase

The compatibility verdict propagates through three primary subsystems, each invoking `compatibility_for_inspection` to enforce runtime safety.

### Server Request Handling

In **[`mtplx/server/request_policy.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/request_policy.py)**, the request pipeline calls `compatibility_for_inspection` to evaluate incoming model loads. The function `request_read_only_inspection_force_answer` uses the returned verdict to determine whether to process the request or return an early rejection response based on the `safe` boolean and `exit_code` values.

### CLI Launch Arguments

The public command-line interface in **[`mtplx/cli/public.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/cli/public.py)** integrates compatibility checks through **`_apply_runtime_compatibility_mode`**. This helper inspects the verdict's `mode` field and adjusts launch arguments accordingly. For example, when the verdict specifies `native-ar-only`, the CLI automatically appends `--runtime-compatibility native-ar-only` to the execution context.

### Backend Selection

Complementary to compatibility checking, **[`mtplx/backends/descriptors.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/descriptors.py)** provides **`model_family_from_inspection`** to select the appropriate backend family based on inspection metadata. While this function handles backend categorization, it operates alongside the compatibility system to ensure the selected backend matches the runtime constraints identified by `compatibility_for_inspection`.

## Practical Implementation Examples

### Querying Compatibility Directly

```python
from mtplx.backends.registry import compatibility_for_inspection

# inspection dict loaded from model's mtplx.json

verdict = compatibility_for_inspection(inspection)

if verdict.safe:
    print(f"Model cleared for launch with mode: {verdict.mode}")
else:
    print(f"Launch blocked: {verdict.reason}")

```

### Server-Side Request Validation

```python
from mtplx.backends.registry import compatibility_for_inspection
from mtplx.server.request_policy import RequestPolicy

def validate_model_request(request):
    verdict = compatibility_for_inspection(request.inspection)
    if not verdict.safe:
        return {"error": verdict.reason, "code": 403}
    return RequestPolicy.process(request)

```

### CLI Runtime Mode Override

```bash

# Force AR-only backend for models requiring native-ar-only compatibility

mtplx launch ./my_model --runtime-compatibility native-ar-only

```

The CLI internally invokes `compatibility_for_inspection` and passes the verdict to `_apply_runtime_compatibility_mode` to configure the execution environment before spawning the model process.

## Key Source Files

- **[`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py)**: Defines `compatibility_for_inspection` and the `RuntimeCompatibilityMode` enum
- **[`mtplx/backends/descriptors.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/descriptors.py)**: Provides `model_family_from_inspection` for backend selection
- **[`mtplx/server/request_policy.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/request_policy.py)**: Applies compatibility verdicts to incoming server requests
- **[`mtplx/cli/public.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/cli/public.py)**: CLI entry point that adapts launch arguments based on compatibility mode
- **[`tests/test_artifacts.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_artifacts.py)** and **[`tests/test_forge_cli.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_forge_cli.py)**: Unit tests validating inspection logic against various metadata configurations

## Summary

- The **model compatibility inspection system** centers on the `compatibility_for_inspection` function in [`mtplx/backends/registry.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/registry.py), which returns a structured `CompatibilityVerdict`.
- Inspection metadata must contain `runtime_contract`, `runtime_compatibility`, and optionally `tier` or `exit_code` fields to drive the decision process.
- The evaluation follows three phases: contract validation, runtime mode mapping, and short-circuit checks for pre-determined failures.
- The resulting verdict integrates with the server request pipeline, CLI argument parsing, and backend selection to prevent incompatible models from executing.
- Tests in [`tests/test_artifacts.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_artifacts.py) and related files ensure the system correctly handles both verified contracts and various compatibility tiers.

## Frequently Asked Questions

### What happens if a model's runtime contract is not verified?

If the inspection dictionary contains a `runtime_contract` field that is not marked as verified, `compatibility_for_inspection` immediately returns a verdict with `safe=False` and a reason indicating the missing contract. This prevents the model from proceeding to backend selection or execution regardless of other compatibility indicators.

### How does MTPLX handle the "native-ar-only" runtime compatibility mode?

When the inspection specifies `runtime_compatibility: "native-ar-only"`, the system maps this to the `RuntimeCompatibilityMode.NATIVE_AR_ONLY` enum value. The verdict will include this mode, signaling to the CLI's `_apply_runtime_compatibility_mode` helper and the server that the model requires the AR-specific backend (such as Laguna AR) to function correctly.

### Can the compatibility inspection be bypassed using the exit_code field?

Yes, the inspection system respects pre-computed rejection signals. If the inspection dictionary includes `can_run: False` or a non-zero `exit_code`, `compatibility_for_inspection` short-circuits its logic and returns an unsafe verdict immediately. This optimization allows the server to reject requests instantly without re-evaluating contract or runtime compatibility details.

### Where does MTPLX store the compatibility verdict during a server request?

The server request handler in [`mtplx/server/request_policy.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/request_policy.py) computes the verdict by calling `compatibility_for_inspection` against the request's inspection metadata. While the verdict itself is computed on-demand rather than stored persistently, it determines whether the request pipeline continues processing or returns an error response to the client.