# Magika HIGH_CONFIDENCE Prediction Mode: Technical Deep Dive and Implementation Guide

> Explore Magika HIGH_CONFIDENCE prediction mode. Learn how Magika ensures accurate content type identification by exceeding confidence thresholds, falling back to TXT or UNKNOWN when needed.

- Repository: [Google/magika](https://github.com/google/magika)
- Tags: deep-dive
- Published: 2026-04-16

---

**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`](https://github.com/google/magika/blob/main/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:

```python
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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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:

```python
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`](https://github.com/google/magika/blob/main/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:

```json
{
  "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:

```python
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:

```python
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:

```python
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:

```python

# 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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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.