# Magika Prediction Modes: Controlling Confidence Thresholds in File Type Detection

> Explore Magika's prediction modes: HIGH_CONFIDENCE, MEDIUM_CONFIDENCE, and BEST_GUESS. Control confidence thresholds for precise file type detection with this Google AI tool.

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

---

**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`](https://github.com/google/magika/blob/main/python/src/magika/types/prediction_mode.py) and exposes three distinct behaviors:

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

```python
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`](https://github.com/google/magika/blob/main/python/src/magika/cli/magika_client.py) (lines 101-106):

```bash

# 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`](https://github.com/google/magika/blob/main/python/src/magika/types/prediction_mode.py), with threshold logic implemented in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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.