How the MTPLX Model Compatibility Inspection System Evaluates Runtime Safety

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, 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, the compatibility_for_inspection function serves as the primary gateway for compatibility checks. It accepts an inspection dictionary—typically loaded from mtplx.json or 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 and 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 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, 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 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 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

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

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

# 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: Defines compatibility_for_inspection and the RuntimeCompatibilityMode enum
• mtplx/backends/descriptors.py: Provides model_family_from_inspection for backend selection
• mtplx/server/request_policy.py: Applies compatibility verdicts to incoming server requests
• mtplx/cli/public.py: CLI entry point that adapts launch arguments based on compatibility mode
• tests/test_artifacts.py and 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, 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 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 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.

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