How to Probe a Hugging Face Repository with MTPLX Forge

MTPLX Forge provides a programmatic way to inspect a Hugging Face model repository or local directory and determine whether the source can be forged into an MTPLX-compatible artifact.

The MTPLX library (youssofal/MTPLX) includes a specialized probing system that validates model sources before conversion. This guide examines the probe_source function in mtplx/commands/forge.py and explains how it analyzes repositories for compatibility, detects existing MTPLX artifacts, and estimates resource requirements.

How the Probe Source Function Works

The core inspection logic resides in mtplx/commands/forge.py within the probe_source function (lines 78–115). This function accepts a string argument representing either a local filesystem path, a Hugging Face repository identifier, or a full Hugging Face URL, then executes a multi-stage validation pipeline.

Input Normalization and Validation

First, _normalize_source parses the input to determine whether it represents a local Path or a remote repo_id. If the function cannot derive either a valid path nor a repository identifier, it immediately returns a probe_failed verdict (lines 78–92), preventing further processing of malformed inputs.

File Discovery and Size Estimation

For valid inputs, the function collects the complete file inventory:

• Remote repositories: The function creates a HfApi client via _make_hf_api and queries the Hugging Face model-info endpoint to retrieve the list of files and total repository size (lines 99–116).
• Local directories: When probing a local path, the function walks the filesystem using local.rglob("*") and sums individual file sizes (lines 31–38).

Artifact Compatibility Checks

Before proceeding, the probe scans for unsupported GGUF artifacts. If the system detects a GGUF marker in the file list, it rejects the source immediately (lines 42–55), as MTPLX Forge does not support converting quantized GGUF formats.

Metadata and Runtime Detection

The function attempts to load existing MTPLX metadata by searching for mtplx_runtime.json and config.json. For remote repositories, it uses hf_hub_download; for local sources, it reads directly from disk (lines 58–73).

The probe also recognizes already-forged Gemma-4 assistant-pair bundles, a special case that short-circuits further inspection (lines 89–107), allowing the system to identify compatible artifacts instantly.

Source Format Derivation and MTP Weight Analysis

Next, _source_format_from_config analyzes the configuration and runtime metadata to determine the source format classification. Simultaneously, _probe_runtime_mtp_evidence scans the artifact for MT-P (MTPLX) weights, setting the has_mtp_weights boolean in the final report.

Structured Report Generation

The function returns a comprehensive dictionary containing:

• verdict: Classification string (e.g., "already_mtplx", "no_mtp_heads", "probe_failed")
• forgeable: Boolean indicating conversion feasibility
• supported: Boolean for architecture compatibility
• source_format: Detected format classification
• has_mtp_weights: Presence of MTPLX-specific weight evidence
• estimated_size_bytes: Total repository size
• estimated_peak_gib: Projected peak memory usage in GiB
• message: Human-readable status description

Probing from Python and CLI

MTPLX Forge exposes the probing capability through both a Python API and a command-line interface.

Python API

Import the forge module and call probe_source directly with a repository URL or local path:

from mtplx.commands import forge

# Probe a public Hugging Face repository

result = forge.probe_source("https://huggingface.co/mtplx/example/tree/main")
print(result["verdict"])               # e.g., "already_mtplx" or "no_mtp_heads"

print(result["has_mtp_weights"])       # True or False

print(result["estimated_size_bytes"])  # Approximate total bytes

# Probe a local directory

local_result = forge.probe_source("/tmp/my-model")
print(local_result["forgeable"])       # Conversion feasibility

Command Line Interface

The MTPLX CLI exposes this functionality via the mtplx forge probe command, defined in mtplx/commands/public.py (lines 750–770). This command forwards the probe results directly to the terminal as formatted JSON:

$ mtplx forge probe https://huggingface.co/mtplx/example

Example output:

{
  "verdict": "already_mtplx",
  "forgeable": true,
  "supported": true,
  "source": "https://huggingface.co/mtplx/example",
  "hf_repo": "mtplx/example",
  "source_format": "mtplx_mlx_affine_with_mtp",
  "has_mtp_weights": true,
  "estimated_size_bytes": 842374912,
  "estimated_peak_gib": 0.8,
  "message": "Already MTPLX-branded; Forge can verify and restamp provenance."
}

Key Implementation Files

The probing system relies on several interconnected modules:

• mtplx/commands/forge.py – Contains the main probe_source implementation (lines 78–115) and helper functions including _make_hf_api, _source_format_from_config, and _probe_runtime_mtp_evidence.
• mtplx/hf_loader.py – Wraps huggingface_hub utilities to handle token logic and metadata downloads.
• mtplx/artifacts.py – Validates and loads MTPLX artifacts when the probe discovers existing runtime metadata.
• mtplx/commands/public.py – CLI entry point that exposes the mtplx forge probe <source> command interface.

Summary

• probe_source in mtplx/commands/forge.py serves as the primary entry point for repository inspection.
• The function accepts local paths, Hugging Face repo IDs, or full URLs and normalizes them via _normalize_source.
• Remote probing utilizes the HfApi client to enumerate files and calculate total size, while local probing uses filesystem walking.
• The system explicitly rejects GGUF artifacts and detects existing MTPLX-branded bundles including Gemma-4 assistant pairs.
• The returned dictionary provides actionable data including conversion verdicts, size estimates, and MT-P weight detection.

Frequently Asked Questions

What input formats does probe_source accept?

The function accepts three input types: a local filesystem path (e.g., /tmp/my-model), a Hugging Face repository identifier (e.g., mtplx/example), or a full Hugging Face URL (e.g., https://huggingface.co/mtplx/example/tree/main). The _normalize_source helper processes these variants into a standardized internal representation.

Why does the probe reject some repositories with a probe_failed verdict?

If _normalize_source cannot parse the input into either a valid local Path or a recognized Hugging Face repo_id, or if the system detects an unsupported GGUF artifact marker in the file list, it returns probe_failed. This prevents attempting conversion on incompatible or malformed sources.

How does the probe determine if a model already has MTPLX weights?

The function _probe_runtime_mtp_evidence scans the repository for MT-P (MTPLX) specific metadata evidence. It checks for the presence of mtplx_runtime.json and analyzes weight configurations to set the has_mtp_weights boolean in the returned report.

Can I use the probe results to estimate GPU memory requirements?

Yes. The returned dictionary includes estimated_peak_gib, which provides the projected peak memory usage in gigabytes based on the total file size and detected architecture. This value, alongside estimated_size_bytes, helps determine hardware requirements before initiating the forge process.

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