Magika Prediction Modes: Controlling Confidence Thresholds in File Type Detection

Magika offers three prediction modes—HIGH_CONFIDENCE (default), MEDIUM_CONFIDENCE, and BEST_GUESS—that determine how strictly the deep-learning model's confidence scores are filtered before returning a final content-type label.

Magika, Google's AI-powered file type detection library, provides configurable Magika prediction modes that let developers balance precision against recall. As implemented in the google/magika repository, these modes control whether the tool returns a specific content-type prediction or falls back to a generic label based on internal confidence thresholds.

The Three Magika Prediction Modes

The PredictionMode enum is defined in python/src/magika/types/prediction_mode.py and exposes three distinct behaviors:

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

High-Confidence Mode

High-confidence mode is the default setting that prioritizes precision over recall. In this mode, the model consults per-content-type thresholds defined in self._model_config.thresholds within the Magika class. A prediction is returned only if the confidence score exceeds the high-confidence threshold for that specific content type; otherwise, the system falls back to a generic type such as TXT or UNKNOWN. This mode is ideal when you need to minimize false positives, as it leverages thresholds tuned on large validation sets (for example, requiring >99% confidence for PDFs while accepting ~80% for JavaScript).

Medium-Confidence Mode

Medium-confidence mode applies a single, generic threshold across all content types. If the model's confidence score meets or exceeds the medium_confidence_threshold, the prediction is kept; otherwise, it returns a generic type. This provides a balanced trade-off between precision and recall, offering more predictions than high-confidence mode while still filtering out low-confidence results.

Best-Guess Mode

Best-guess mode disables thresholding entirely. The raw model prediction is always returned regardless of confidence score, maximizing recall at the potential cost of occasional misclassifications. Use this mode when you prefer to receive the model's best estimate for every file and can tolerate lower-confidence predictions.

Implementation in the Source Code

The prediction mode logic resides in python/src/magika/magika.py within the _get_output_label_from_dl_label_and_score method (lines 593-613). This internal function examines the selected mode and applies the appropriate threshold logic:

• For HIGH_CONFIDENCE, it checks against individual content-type thresholds stored in the model configuration.
• For MEDIUM_CONFIDENCE, it validates against a universal medium-confidence threshold.
• For BEST_GUESS, it bypasses all threshold checks and returns the raw prediction directly.

When instantiating the Magika class without specifying a mode, the constructor defaults to PredictionMode.HIGH_CONFIDENCE, as seen in lines 60-62 of python/src/magika/magika.py.

Using Prediction Modes in Python

Import the PredictionMode enum and pass it to the Magika constructor to control threshold behavior:

from magika import Magika, PredictionMode

# High-confidence (default) - strictest filtering

magika_hc = Magika(prediction_mode=PredictionMode.HIGH_CONFIDENCE)
result = magika_hc.predict_path("document.pdf")
print(result.prediction.output.label)  # PDF or generic fallback

# Medium-confidence - balanced approach

magika_mc = Magika(prediction_mode=PredictionMode.MEDIUM_CONFIDENCE)
result = magika_mc.predict_path("script.js")
print(result.prediction.output.label)  # Usually JS if score > generic threshold

# Best-guess - maximum recall

magika_bg = Magika(prediction_mode=PredictionMode.BEST_GUESS)
result = magika_bg.predict_path("ambiguous.bin")
print(result.prediction.output.label)  # Raw model output regardless of confidence

Using Prediction Modes in the CLI

The command-line interface exposes prediction modes through the --prediction-mode flag, which maps directly to the Python enum values defined in python/src/magika/cli/magika_client.py (lines 101-106):

# High-confidence (default)

magika --prediction-mode high-confidence path/to/file

# Medium-confidence

magika --prediction-mode medium-confidence path/to/file

# Best-guess

magika --prediction-mode best-guess path/to/file

Summary

• High-confidence mode (default) applies per-content-type thresholds from the model configuration to minimize false positives.
• Medium-confidence mode uses a single generic threshold to balance precision and recall across all file types.
• Best-guess mode returns raw model predictions without threshold filtering, maximizing recall.
• The PredictionMode enum is defined in python/src/magika/types/prediction_mode.py, with threshold logic implemented in python/src/magika/magika.py.
• Both the Python API and CLI default to high-confidence mode unless explicitly configured otherwise.

Frequently Asked Questions

What is the default Magika prediction mode?

By default, Magika uses PredictionMode.HIGH_CONFIDENCE. This is hardcoded in the Magika class constructor at python/src/magika/magika.py (lines 60-62) and applies strict per-content-type thresholds to reduce false positives.

How can I get predictions for every file without threshold filtering?

Use PredictionMode.BEST_GUESS. This mode, defined in python/src/magika/types/prediction_mode.py, instructs the _get_output_label_from_dl_label_and_score method to skip all threshold checks and return the model's top prediction regardless of confidence score.

What is the difference between medium and high confidence in Magika?

High-confidence mode uses per-content-type thresholds tuned individually for each file format (e.g., stricter for PDFs than JavaScript), while medium-confidence applies a single, uniform threshold across all content types. High-confidence reduces false positives but may return more generic labels; medium-confidence offers a middle ground.

Where are the confidence thresholds defined for high-confidence mode?

The thresholds are stored in self._model_config.thresholds within the Magika class and are compared against model outputs in python/src/magika/magika.py (lines 593-613). These values were optimized on a large validation set to maximize accuracy for each specific content type.

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