Magika HIGH_CONFIDENCE Prediction Mode: Technical Deep Dive and Implementation Guide

Magika's HIGH_CONFIDENCE prediction mode requires the deep learning model's confidence score to exceed per-type thresholds before returning a specific content type label, automatically falling back to generic TXT or UNKNOWN labels when confidence is insufficient.

The google/magika repository provides a Python library for content type identification using deep learning. When operating in HIGH_CONFIDENCE prediction mode, the system implements strict validation logic to ensure only high-certainty predictions are returned as specific content types, protecting your workflows from low-confidence misclassifications.

Understanding Magika's Three Prediction Modes

Magika defines three prediction modes in python/src/magika/types/prediction_mode.py through the PredictionMode enum:

• BEST_GUESS: Always returns the model's prediction regardless of confidence score
• MEDIUM_CONFIDENCE: Accepts predictions when score >= model_config.medium_confidence_threshold (default 0.5)
• HIGH_CONFIDENCE: Applies per-type thresholds from the model configuration, falling back to MEDIUM_CONFIDENCE thresholds when no specific threshold exists

When you instantiate the Magika class without specifying a mode, it defaults to HIGH_CONFIDENCE:

from magika import Magika
from magika.types import PredictionMode

# These are equivalent

magika = Magika()
magika = Magika(prediction_mode=PredictionMode.HIGH_CONFIDENCE)

According to the source code in python/src/magika/magika.py (lines 57-61), the constructor signature sets prediction_mode=PredictionMode.HIGH_CONFIDENCE as the default argument, making strict confidence filtering the out-of-the-box behavior.

How HIGH_CONFIDENCE Mode Evaluates Model Output

The core decision logic resides in the _get_output_label_from_dl_label_and_score method within python/src/magika/magika.py (lines 598-605). For each file analyzed, the deep learning model returns a content-type label (dl_label) and a confidence score (score). The HIGH_CONFIDENCE mode applies the following validation:

elif (
    self._prediction_mode == PredictionMode.HIGH_CONFIDENCE
    and score >= self._model_config.thresholds.get(
        dl_label, self._model_config.medium_confidence_threshold
    )
):
    # Keep the model prediction

    pass

This implementation checks whether the score meets or exceeds the specific threshold defined for that content type in the model configuration. If no per-type threshold exists, it falls back to the medium_confidence_threshold value (typically 0.5).

Per-Type Threshold Configuration

High-confidence thresholds are stored in the model's JSON configuration file, located at assets/models/standard_v3_3/config.min.json. The configuration contains a thresholds object mapping content type identifiers to their minimum required confidence scores.

For example, the configuration might specify:

{
  "medium_confidence_threshold": 0.5,
  "thresholds": {
    "crt": 0.9,
    "pdf": 0.85
  }
}

When analyzing a CRT certificate file, Magika requires a confidence score of at least 0.9 in HIGH_CONFIDENCE mode, whereas generic types without specific entries use the 0.5 fallback threshold.

The Fallback Mechanism for Low-Confidence Predictions

When operating in HIGH_CONFIDENCE mode, if the model's score fails to meet the required threshold, Magika triggers the low-confidence fallback path. The system sets overwrite_reason = OverwriteReason.LOW_CONFIDENCE and replaces the specific label with a generic alternative:

if self._get_ct_info(output_label).is_text:
    output_label = ContentTypeLabel.TXT
else:
    output_label = ContentTypeLabel.UNKNOWN

Binary files receive the UNKNOWN label, while text-based files are labeled TXT. This ensures your application never acts upon uncertain specific content type classifications when strict confidence is required.

Practical Implementation Examples

Default HIGH_CONFIDENCE Usage

The following example demonstrates standard usage where HIGH_CONFIDENCE mode filters predictions automatically:

from magika import Magika

magika = Magika()  # Defaults to HIGH_CONFIDENCE

result = magika.identify_path("suspicious_document.pdf")
print(f"Label: {result.prediction.output.label}")
print(f"Score: {result.prediction.score}")
print(f"Overwrite Reason: {result.prediction.overwrite_reason}")

# If score < threshold: label becomes TXT or UNKNOWN, overwrite_reason becomes LOW_CONFIDENCE

Explicit Mode Selection with Batch Processing

When processing multiple files with explicit mode declaration:

from magika import Magika
from magika.types import PredictionMode

magika = Magika(prediction_mode=PredictionMode.HIGH_CONFIDENCE)

paths = ["report.docx", "script.sh", "firmware.bin"]
results = magika.identify_paths(paths)

for r in results:
    print(f"{r.path}: {r.prediction.output.label} (confidence: {r.prediction.score:.2f})")

Observing Fallback Behavior

To demonstrate the fallback mechanism, analyze a tiny file that generates low model confidence:

# Create a minimal 2-byte file

with open("tiny_fragment.bin", "wb") as f:
    f.write(b"\x00\x01")

magika = Magika(prediction_mode=PredictionMode.HIGH_CONFIDENCE)
result = magika.identify_path("tiny_fragment.bin")

print(result.prediction.output.label)      # ContentTypeLabel.TXT or UNKNOWN

print(result.prediction.overwrite_reason)  # OverwriteReason.LOW_CONFIDENCE

Summary

• HIGH_CONFIDENCE is the default mode in the Magika constructor, providing strict confidence filtering without explicit configuration.
• Per-type thresholds are defined in config.min.json within the model assets, allowing fine-grained control over confidence requirements for specific content types.
• Automatic fallback occurs when scores fall below thresholds, returning generic TXT or UNKNOWN labels rather than uncertain specific classifications.
• Validation logic executes in _get_output_label_from_dl_label_and_score at lines 598-605 of magika.py, checking against model_config.thresholds with a fallback to medium_confidence_threshold.

Frequently Asked Questions

What is the default prediction mode in Magika?

According to the constructor in python/src/magika/magika.py, the default prediction mode is PredictionMode.HIGH_CONFIDENCE. When you instantiate Magika() without arguments, you automatically receive strict confidence filtering that validates predictions against per-type thresholds before returning specific content type labels.

How does HIGH_CONFIDENCE differ from MEDIUM_CONFIDENCE?

MEDIUM_CONFIDENCE applies a single global threshold (default 0.5) to all content types, accepting any prediction exceeding this universal value. HIGH_CONFIDENCE implements a two-tier system that first checks for content-type-specific thresholds in the model configuration, only falling back to the medium confidence threshold when no specific value exists for that type. This allows HIGH_CONFIDENCE to demand higher certainty for critical file types while maintaining baseline standards for others.

Where are per-type confidence thresholds defined?

Per-type thresholds reside in the model's JSON configuration file, typically located at assets/models/standard_v3_3/config.min.json within the repository. The file contains a thresholds object mapping content type identifiers (such as "crt" or "pdf") to their required floating-point confidence values. If a content type lacks a specific entry, Magika falls back to the medium_confidence_threshold value specified in the same configuration.

What happens when confidence is too low in HIGH_CONFIDENCE mode?

When the model's confidence score fails to meet the per-type or fallback threshold, Magika sets the overwrite_reason to LOW_CONFIDENCE and replaces the specific predicted label with a generic alternative. Text-based files receive the TXT label, while non-text files receive UNKNOWN. This ensures your application receives conservative, high-certainty classifications rather than potentially incorrect specific content type predictions.

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