# How MEDIUM_CONFIDENCE Prediction Mode Works in Magika: Threshold Logic and Fallback Behavior

> Understand Magika's MEDIUM_CONFIDENCE prediction mode unlock its threshold logic and fallback behavior for accurate file type identification.

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

---

**In Magika's `MEDIUM_CONFIDENCE` mode, a file is assigned its deep-learning predicted content type only when the model's confidence score meets or exceeds the global `medium_confidence_threshold` (default 0.5); otherwise, the prediction falls back to generic `TXT` or `UNKNOWN` labels.**

Google's Magika library provides three prediction modes—`BEST_GUESS`, `MEDIUM_CONFIDENCE`, and `HIGH_CONFIDENCE`—that determine how strictly the model interprets its own confidence scores. When you configure Magika to use `MEDIUM_CONFIDENCE` mode, it applies a single global threshold to decide whether to trust the neural network's output or return a conservative generic type, making it ideal for applications requiring balanced accuracy without per-content-type customization.

## The Confidence Threshold Logic

The core validation logic resides in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) within the `_get_output_label_from_dl_label_and_score` method. For every file analyzed, the deep-learning model returns a content-type label (`dl_label`) and a floating-point confidence score (`score`). The `MEDIUM_CONFIDENCE` mode evaluates this score against exactly one threshold:

```python

# Conceptual flow for MEDIUM_CONFIDENCE

if score >= self._model_config.medium_confidence_threshold:
    # Trust the model output

    output_label = dl_label
else:
    # Fall back to generic label

    output_label = ContentTypeLabel.TXT or ContentTypeLabel.UNKNOWN

```

According to the source code analysis, `MEDIUM_CONFIDENCE` uses a **single global threshold** defined in the model configuration file ([`assets/models/standard_v3_3/config.min.json`](https://github.com/google/magika/blob/main/assets/models/standard_v3_3/config.min.json)). Unlike `HIGH_CONFIDENCE` mode—which checks per-type thresholds first—`MEDIUM_CONFIDENCE` applies the same threshold universally across all content types.

## Configuration and Default Values

The threshold value is stored in the model's JSON configuration:

- **File**: [`assets/models/standard_v3_3/config.min.json`](https://github.com/google/magika/blob/main/assets/models/standard_v3_3/config.min.json)
- **Key**: `medium_confidence_threshold`
- **Default value**: `0.5`

You can inspect this configuration to verify the threshold used by your specific model version. If a prediction's score falls below this value, Magika triggers the fallback mechanism regardless of the specific content type being predicted.

## Comparison with HIGH_CONFIDENCE Mode

Understanding `MEDIUM_CONFIDENCE` requires contrasting it with the stricter `HIGH_CONFIDENCE` alternative:

| Mode | Threshold Strategy | Behavior When Condition Fails |
|------|-------------------|------------------------------|
| **BEST_GUESS** | None (always trust) | Never falls back |
| **MEDIUM_CONFIDENCE** | Global threshold only | Falls back to `TXT`/`UNKNOWN` |
| **HIGH_CONFIDENCE** | Per-type threshold first, then global fallback | Falls back to `TXT`/`UNKNOWN` |

In `HIGH_CONFIDENCE` mode, Magika first checks if the score meets a content-type-specific threshold (e.g., `0.9` for certificate files) before falling back to the global medium threshold. `MEDIUM_CONFIDENCE` skips the per-type check entirely, using only the global `medium_confidence_threshold` for all file types.

## Fallback Behavior When Confidence Is Low

When operating in `MEDIUM_CONFIDENCE` mode, scores below the threshold trigger the overwrite logic found in [`magika.py`](https://github.com/google/magika/blob/main/magika.py):

```python
overwrite_reason = OverwriteReason.LOW_CONFIDENCE
if self._get_ct_info(output_label).is_text:
    output_label = ContentTypeLabel.TXT
else:
    output_label = ContentTypeLabel.UNKNOWN

```

This means:
- **Text-like files** receive the `TXT` label
- **Binary files** receive the `UNKNOWN` label
- The `overwrite_reason` field is set to `LOW_CONFIDENCE` in the prediction result

## Code Examples

### Initializing Magika with MEDIUM_CONFIDENCE Mode

```python
from magika import Magika
from magika.types import PredictionMode

# Explicitly select medium confidence mode

magika = Magika(prediction_mode=PredictionMode.MEDIUM_CONFIDENCE)

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

```

### Observing the Threshold Boundary

```python
from magika import Magika
from magika.types import PredictionMode, OverwriteReason

magika = Magika(prediction_mode=PredictionMode.MEDIUM_CONFIDENCE)

# Process multiple files

paths = ["image.png", "script.sh", "tiny_fragment.bin"]
results = magika.identify_paths(paths)

for r in results:
    if r.prediction.overwrite_reason == OverwriteReason.LOW_CONFIDENCE:
        print(f"{r.path}: Below threshold (score={r.prediction.score:.2f}) → {r.prediction.output.label}")
    else:
        print(f"{r.path}: Accepted (score={r.prediction.score:.2f}) → {r.prediction.output.label}")

```

### Programmatic Threshold Check Logic

While you cannot change the threshold at runtime without modifying the model config, you can verify the current threshold programmatically:

```python
magika = Magika(prediction_mode=PredictionMode.MEDIUM_CONFIDENCE)
threshold = magika._model_config.medium_confidence_threshold
print(f"Current medium confidence threshold: {threshold}")  # Typically 0.5

```

## Summary

- **MEDIUM_CONFIDENCE** applies a single global threshold (`medium_confidence_threshold`, default 0.5) to all content types equally.
- When scores fall below this threshold, Magika returns `TXT` for text-like content and `UNKNOWN` for binary content, setting `overwrite_reason` to `LOW_CONFIDENCE`.
- This mode is less strict than `HIGH_CONFIDENCE` (which uses per-type thresholds) but more conservative than `BEST_GUESS` (which never falls back).
- The implementation resides in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py), specifically within the `_get_output_label_from_dl_label_and_score` method.
- Configuration values are loaded from [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json) in the model assets directory.

## Frequently Asked Questions

### What is the difference between MEDIUM_CONFIDENCE and HIGH_CONFIDENCE in Magika?

**MEDIUM_CONFIDENCE** uses only the global `medium_confidence_threshold` (typically 0.5) for every file type, while **HIGH_CONFIDENCE** first checks per-content-type thresholds defined in the model configuration before falling back to the global threshold. This makes `HIGH_CONFIDENCE` stricter for specific file types that require higher certainty, whereas `MEDIUM_CONFIDENCE` applies uniform validation across all formats.

### How does Magika handle predictions that fail the MEDIUM_CONFIDENCE threshold?

When a prediction's confidence score is below the `medium_confidence_threshold`, Magika overwrites the model output with a generic label. Text-like files are labeled as `TXT`, while binary files are labeled as `UNKNOWN`. The result object includes `overwrite_reason: LOW_CONFIDENCE` to indicate that the deep-learning prediction was rejected due to insufficient confidence.

### Can I customize the medium confidence threshold value?

The threshold is defined in the model configuration file ([`assets/models/standard_v3_3/config.min.json`](https://github.com/google/magika/blob/main/assets/models/standard_v3_3/config.min.json)) and loaded at initialization. You cannot override this value via the Python API without modifying the underlying configuration JSON or loading a custom model. The default value of `0.5` is optimized for balanced precision-recall trade-offs across the standard model.

### When should I use MEDIUM_CONFIDENCE instead of HIGH_CONFIDENCE?

Use **MEDIUM_CONFIDENCE** when you need consistent behavior across all file types without requiring higher certainty for specific formats, or when you want to avoid the complexity of per-type thresholds. It is appropriate for batch processing pipelines where uniform confidence standards are preferable to type-specific scrutiny. Choose **HIGH_CONFIDENCE** when certain content types (like executables or certificates) require stricter validation before classification.