How BEST_GUESS Prediction Mode Works in Magika: Complete Technical Guide

BEST_GUESS is Magika's high-recall prediction mode that returns the deep-learning model's raw content-type classification without confidence threshold checks, prioritizing detection completeness over absolute precision.

Magika is Google's open-source file-type detection system that identifies content using a deep-learning model to generate content-type labels and confidence scores. The BEST_GUESS prediction mode represents one of three architectural configurations in the google/magika repository that determines how aggressively the system trusts its neural network outputs. Understanding this mode requires tracing the prediction pipeline from enum definitions through threshold logic to final label selection.

Architecture of BEST_GUESS Prediction Mode in Magika

The Magika prediction pipeline first runs inference that returns a content-type label together with a numeric confidence score between 0.0 and 1.0. Whether the system keeps this raw prediction or falls back to generic labels depends entirely on the prediction mode selected during the Magika class initialization.

The PredictionMode Enum Definition

The three available configurations are defined as string enums in magika/types/prediction_mode.py (lines 25-33):

class PredictionMode(LowerCaseStrEnum):
    BEST_GUESS = enum.auto()
    MEDIUM_CONFIDENCE = enum.auto()
    HIGH_CONFIDENCE = enum.auto()

Core Pipeline Logic in magika.py

After model inference completes, Magika calls the method _get_output_label_from_dl_label_and_score located in magika/magika.py (lines 88-108). This function evaluates the raw deep-learning label (dl_label) and its accompanying score against the active prediction mode to determine the final output.

How BEST_GUESS Differs from Other Prediction Modes

The primary distinction of BEST_GUESS lies in its explicit bypass of confidence validation. While other modes enforce minimum probability thresholds, this mode accepts the model's output regardless of uncertainty levels.

No Threshold Validation

When BEST_GUESS is active, the code branch explicitly passes without checking numeric thresholds:

if self._prediction_mode == PredictionMode.BEST_GUESS:
    # We take the (potentially overwritten) model prediction, no matter

    # what the score is.

    pass

This contrasts sharply with alternative modes:

• MEDIUM_CONFIDENCE: Requires score >= self._model_config.medium_confidence_threshold
• HIGH_CONFIDENCE: Requires score >= self._model_config.thresholds.get(...) per content-type

Potential Label Overwrites

Even in BEST_GUESS mode, the system may modify results through the overwrite_map supplied in the model configuration. This mapping replaces specific raw labels with alternatives before the final return, operating independently of the confidence score or prediction mode selection.

Practical Implementation Code Examples

Using BEST_GUESS in Python Applications

The following implementation demonstrates how to instantiate Magika with the high-recall prediction mode:

from magika import Magika, PredictionMode

# Create a Magika instance that always trusts the model's raw output

magika = Magika(prediction_mode=PredictionMode.BEST_GUESS)

# Classify a file

result = magika.predict_path("example.pdf")
print(f"Detected type: {result.output.content_type}")

# Even if the confidence score is low, the type will be the model's raw prediction

Comparing All Three Modes Side-by-Side

This runnable script illustrates the behavioral differences between architectures:

from magika import Magika, PredictionMode

paths = ["example.pdf", "tiny.bin", "script.js"]

for mode in (PredictionMode.HIGH_CONFIDENCE,
             PredictionMode.MEDIUM_CONFIDENCE,
             PredictionMode.BEST_GUESS):
    print(f"\n=== Mode: {mode.value} ===")
    m = Magika(prediction_mode=mode)
    
    for p in paths:
        r = m.predict_path(p)
        print(f"{p}: {r.output.content_type} (score={r.prediction.score:.2f})")

When executed, this demonstrates that BEST_GUESS never falls back to TXT or UNKNOWN, while threshold-dependent modes suppress low-confidence predictions.

When to Use BEST_GUESS Prediction Mode

Select BEST_GUESS when your application requires maximum detection coverage and can tolerate potential misclassifications downstream. This mode excels in content discovery pipelines, forensic analysis, or preprocessing stages where identifying probable file types is preferable to generic fallback labels. Avoid this mode when absolute precision is critical, opting instead for HIGH_CONFIDENCE or explicit threshold validation.

Summary

• BEST_GUESS prediction mode accepts every deep-learning output without validating confidence score thresholds against minimum limits.
• The enum is defined in magika/types/prediction_mode.py (lines 25-33) alongside MEDIUM_CONFIDENCE and HIGH_CONFIDENCE variants.
• Runtime logic resides in magika/magika.py specifically within _get_output_label_from_dl_label_and_score (lines 88-108) where the conditional branch executes pass for BEST_GUESS.
• The overwrite_map configuration may still alter final labels regardless of the selected prediction mode.
• According to the Magika source code, this mode maximizes recall at the potential expense of precision.

Frequently Asked Questions

How does BEST_GUESS prediction mode handle low-confidence predictions?

The system accepts predictions regardless of probability strength. Unlike MEDIUM_CONFIDENCE or HIGH_CONFIDENCE modes that validate against specific thresholds in magika/magika.py, BEST_GUESS executes the pass branch inside _get_output_label_from_dl_label_and_score. This means it returns the raw dl_label even when the accompanying confidence score approaches 0.0.

What is the main difference between BEST_GUESS and HIGH_CONFIDENCE prediction modes?

BEST_GUESS prioritizes maximum recall by returning every model prediction without validation, while HIGH_CONFIDENCE requires the confidence score to exceed content-type specific thresholds defined in the model configuration. The HIGH_CONFIDENCE implementation explicitly checks score >= self._model_config.thresholds.get(...) in magika/magika.py, whereas BEST_GUESS performs no numeric comparison.

Where is the BEST_GUESS prediction mode implemented in the Magika source code?

The BEST_GUESS constant is defined as an enum member in magika/types/prediction_mode.py within the PredictionMode class (lines 25-33). The runtime logic that implements the mode-specific behavior resides in magika/magika.py specifically inside the _get_output_label_from_dl_label_and_score method around lines 88-108 where the conditional branch checks self._prediction_mode == PredictionMode.BEST_GUESS.

How does BEST_GUESS interact with the label overwrite map?

Even when using BEST_GUESS prediction mode, the system may modify final outputs through the overwrite_map defined in the model configuration. This mapping replaces specific raw labels with alternatives before the final return, operating independently of the prediction mode selection or confidence score values.

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