# How to Probe a Hugging Face Repository with MTPLX Forge

> Learn to probe Hugging Face repositories with MTPLX Forge. Inspect models and directories to create MTPLX-compatible artifacts efficiently. Discover the forging process today.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx_runtime.json) and [`config.json`](https://github.com/youssofal/MTPLX/blob/main/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:

```python
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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/commands/public.py) (lines 750–770). This command forwards the probe results directly to the terminal as formatted JSON:

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

```

Example output:

```json
{
  "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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/hf_loader.py)** – Wraps `huggingface_hub` utilities to handle token logic and metadata downloads.
- **[`mtplx/artifacts.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/artifacts.py)** – Validates and loads MTPLX artifacts when the probe discovers existing runtime metadata.
- **[`mtplx/commands/public.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/commands/public.py)** – CLI entry point that exposes the `mtplx forge probe <source>` command interface.

## Summary

- **`probe_source`** in [`mtplx/commands/forge.py`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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.