# How BEST_GUESS Prediction Mode Works in Magika: Complete Technical Guide

> Explore how Magika's BEST_GUESS prediction mode works. This technical guide explains high-recall classification for complete detection, prioritizing completeness over precision.

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

---

**BEST_GUESS is Magika's high-recall prediction mode that returns the deep-learning model's raw content-type classification without confidence threshold checks, prioritizing detection completeness over absolute precision.**

Magika is Google's open-source file-type detection system that identifies content using a **deep-learning model** to generate content-type labels and confidence scores. The **BEST_GUESS prediction mode** represents one of three architectural configurations in the `google/magika` repository that determines how aggressively the system trusts its neural network outputs. Understanding this mode requires tracing the prediction pipeline from enum definitions through threshold logic to final label selection.

## Architecture of BEST_GUESS Prediction Mode in Magika

The Magika prediction pipeline first runs inference that returns a **content-type label** together with a numeric **confidence score** between 0.0 and 1.0. Whether the system keeps this raw prediction or falls back to generic labels depends entirely on the **prediction mode** selected during the Magika class initialization.

### The PredictionMode Enum Definition

The three available configurations are defined as string enums in [`magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/magika/types/prediction_mode.py) (lines 25-33):

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

```

### Core Pipeline Logic in magika.py

After model inference completes, Magika calls the method `_get_output_label_from_dl_label_and_score` located in [`magika/magika.py`](https://github.com/google/magika/blob/main/magika/magika.py) (lines 88-108). This function evaluates the raw deep-learning label (`dl_label`) and its accompanying score against the active **prediction mode** to determine the final output.

## How BEST_GUESS Differs from Other Prediction Modes

The primary distinction of **BEST_GUESS** lies in its explicit bypass of confidence validation. While other modes enforce minimum probability thresholds, this mode accepts the model's output regardless of uncertainty levels.

### No Threshold Validation

When **BEST_GUESS** is active, the code branch explicitly passes without checking numeric thresholds:

```python
if self._prediction_mode == PredictionMode.BEST_GUESS:
    # We take the (potentially overwritten) model prediction, no matter

    # what the score is.

    pass

```

This contrasts sharply with alternative modes:
- **MEDIUM_CONFIDENCE**: Requires `score >= self._model_config.medium_confidence_threshold`
- **HIGH_CONFIDENCE**: Requires `score >= self._model_config.thresholds.get(...)` per content-type

### Potential Label Overwrites

Even in **BEST_GUESS** mode, the system may modify results through the `overwrite_map` supplied in the model configuration. This mapping replaces specific raw labels with alternatives before the final return, operating independently of the **confidence score** or **prediction mode** selection.

## Practical Implementation Code Examples

### Using BEST_GUESS in Python Applications

The following implementation demonstrates how to instantiate Magika with the high-recall prediction mode:

```python
from magika import Magika, PredictionMode

# Create a Magika instance that always trusts the model's raw output

magika = Magika(prediction_mode=PredictionMode.BEST_GUESS)

# Classify a file

result = magika.predict_path("example.pdf")
print(f"Detected type: {result.output.content_type}")

# Even if the confidence score is low, the type will be the model's raw prediction

```

### Comparing All Three Modes Side-by-Side

This runnable script illustrates the behavioral differences between architectures:

```python
from magika import Magika, PredictionMode

paths = ["example.pdf", "tiny.bin", "script.js"]

for mode in (PredictionMode.HIGH_CONFIDENCE,
             PredictionMode.MEDIUM_CONFIDENCE,
             PredictionMode.BEST_GUESS):
    print(f"\n=== Mode: {mode.value} ===")
    m = Magika(prediction_mode=mode)
    
    for p in paths:
        r = m.predict_path(p)
        print(f"{p}: {r.output.content_type} (score={r.prediction.score:.2f})")

```

When executed, this demonstrates that **BEST_GUESS** never falls back to `TXT` or `UNKNOWN`, while threshold-dependent modes suppress low-confidence predictions.

## When to Use BEST_GUESS Prediction Mode

Select **BEST_GUESS** when your application requires maximum detection coverage and can tolerate potential misclassifications downstream. This mode excels in content discovery pipelines, forensic analysis, or preprocessing stages where identifying probable file types is preferable to generic fallback labels. Avoid this mode when absolute precision is critical, opting instead for **HIGH_CONFIDENCE** or explicit threshold validation.

## Summary

- **BEST_GUESS prediction mode** accepts every deep-learning output without validating **confidence score** thresholds against minimum limits.
- The enum is defined in [`magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/magika/types/prediction_mode.py) (lines 25-33) alongside **MEDIUM_CONFIDENCE** and **HIGH_CONFIDENCE** variants.
- Runtime logic resides in [`magika/magika.py`](https://github.com/google/magika/blob/main/magika/magika.py) specifically within `_get_output_label_from_dl_label_and_score` (lines 88-108) where the conditional branch executes `pass` for BEST_GUESS.
- The `overwrite_map` configuration may still alter final labels regardless of the selected prediction mode.
- According to the Magika source code, this mode maximizes recall at the potential expense of precision.

## Frequently Asked Questions

### How does BEST_GUESS prediction mode handle low-confidence predictions?

The system accepts predictions regardless of probability strength. Unlike **MEDIUM_CONFIDENCE** or **HIGH_CONFIDENCE** modes that validate against specific thresholds in [`magika/magika.py`](https://github.com/google/magika/blob/main/magika/magika.py), **BEST_GUESS** executes the `pass` branch inside `_get_output_label_from_dl_label_and_score`. This means it returns the raw `dl_label` even when the accompanying **confidence score** approaches 0.0.

### What is the main difference between BEST_GUESS and HIGH_CONFIDENCE prediction modes?

**BEST_GUESS** prioritizes maximum recall by returning every model prediction without validation, while **HIGH_CONFIDENCE** requires the **confidence score** to exceed content-type specific thresholds defined in the model configuration. The **HIGH_CONFIDENCE** implementation explicitly checks `score >= self._model_config.thresholds.get(...)` in [`magika/magika.py`](https://github.com/google/magika/blob/main/magika/magika.py), whereas **BEST_GUESS** performs no numeric comparison.

### Where is the BEST_GUESS prediction mode implemented in the Magika source code?

The **BEST_GUESS** constant is defined as an enum member in [`magika/types/prediction_mode.py`](https://github.com/google/magika/blob/main/magika/types/prediction_mode.py) within the `PredictionMode` class (lines 25-33). The runtime logic that implements the mode-specific behavior resides in [`magika/magika.py`](https://github.com/google/magika/blob/main/magika/magika.py) specifically inside the `_get_output_label_from_dl_label_and_score` method around lines 88-108 where the conditional branch checks `self._prediction_mode == PredictionMode.BEST_GUESS`.

### How does BEST_GUESS interact with the label overwrite map?

Even when using **BEST_GUESS prediction mode**, the system may modify final outputs through the `overwrite_map` defined in the **model configuration**. This mapping replaces specific raw labels with alternatives before the final return, operating independently of the **prediction mode** selection or **confidence score** values.