What Does the overwrite_reason Field in Magika Results Indicate?

The overwrite_reason field indicates why Magika's final content-type output differs from the raw deep-learning model's prediction, using an enum to distinguish between no change, configuration-based overwrites, or low-confidence fallbacks.

The overwrite_reason field is a critical component of the results returned by the google/magika content-type detection library. As implemented in the Python, Rust, and JavaScript bindings, this field provides transparency into the post-processing pipeline that transforms raw model outputs into final predictions. Understanding this field helps developers debug classification results and implement conditional logic based on why a specific label was selected.

Understanding the overwrite_reason Field

The overwrite_reason is part of the MagikaPrediction dataclass that accompanies every Magika result. It tells the caller why the final output content-type (prediction.output) differs from the raw deep-learning model's prediction (prediction.dl), or why it remains identical. This field is essential for debugging systematic misclassifications and understanding when confidence thresholds have triggered fallbacks.

The OverwriteReason Enum Values

The field is an instance of the OverwriteReason enum defined in magika/types/overwrite_reason.py. The enum provides three possible values:

• OverwriteReason.NONE — No post-processing was applied. The final output label matches exactly what the deep-learning model predicted.
• OverwriteReason.OVERWRITE_MAP — The model's label was replaced according to the overwrite map shipped with the model configuration. This map corrects systematic mis-classifications, such as remapping generic application/* labels to more specific content types.
• OverwriteReason.LOW_CONFIDENCE — The model's confidence score fell below the threshold for the selected prediction mode (high, medium, or best-guess). Magika falls back to a generic label (TXT or UNKNOWN). If this fallback happens to equal the original model label, the reason is downgraded to NONE.

The Internal Logic Flow

The logic that sets this field lives in _get_output_label_from_dl_label_and_score within python/src/magika/magika.py (around lines 78–90), with mirrored implementations in the Rust and JavaScript bindings. The pipeline follows these steps:

1. Apply the overwrite map — If the configuration map changes the label, overwrite_reason becomes OVERWRITE_MAP.
2. Check confidence thresholds — Depending on the prediction_mode, the score may be high enough to retain the (possibly overwritten) label.
3. Force generic fallback — If confidence is insufficient, the result is forced to TXT or UNKNOWN, and overwrite_reason is set to LOW_CONFIDENCE.
4. Validate necessity — If the forced generic label equals the original DL label, the reason resets to NONE because no actual overwrite occurred.

Code Examples for Checking overwrite_reason

You can inspect the overwrite_reason field programmatically across all supported languages to build conditional processing logic.

Python Implementation

When using the Python API, access the field directly from the prediction object:

from magika import Magika
from magika.types import OverwriteReason

magika = Magika(prediction_mode="HIGH_CONFIDENCE")
result = magika.identify_path("example.pdf")

print("DL label:", result.prediction.dl.label)
print("Output label:", result.prediction.output.label)
print("Overwrite reason:", result.prediction.overwrite_reason)

# Typical output:

# DL label: application/pdf

# Output label: application/pdf

# Overwrite reason: OverwriteReason.NONE

If the file triggers an overwrite map entry, the reason reflects the configuration change:

magika = Magika()
result = magika.identify_path("some_binary")
print(result.prediction.overwrite_reason)

# → OverwriteReason.OVERWRITE_MAP

JavaScript and Rust Usage

The JavaScript implementation exposes the enum as lowercase strings:

import { Magika } from "magika";

(async () => {
  const magika = new Magika();
  const { prediction } = await magika.identifyPath("example.bin");
  console.log("Reason:", prediction.overwrite_reason); 
  // Outputs: "none", "overwrite_map", or "low_confidence"
})();

In Rust, the field is accessible after obtaining a result:

use magika::magika::Magika;

let magika = Magika::new().unwrap();
let result = magika.identify_path("example.txt").unwrap();

println!("Reason: {}", result.prediction.overwrite_reason);

Key Source Files and Functions

Understanding overwrite_reason requires familiarity with these specific files in the google/magika repository:

• python/src/magika/types/overwrite_reason.py — Defines the OverwriteReason enum used across all language bindings.
• python/src/magika/types/magika_prediction.py — Contains the MagikaPrediction dataclass that stores the DL prediction, final output, and overwrite reason.
• python/src/magika/magika.py — Implements _get_output_label_from_dl_label_and_score, the core function that determines when and why to overwrite predictions.
• js/src/overwrite-reason.ts — JavaScript/TypeScript enum mirroring the Python implementation.
• rust/lib/src/model.rs — Rust representation of the overwrite map and the logic that yields an OverwriteReason.

Summary

• The overwrite_reason field explains deviations between raw model predictions and final output labels in Magika results.
• Valid values are NONE, OVERWRITE_MAP, and LOW_CONFIDENCE, defined in magika/types/overwrite_reason.py.
• OVERWRITE_MAP indicates the model's prediction was replaced via the configuration's overwrite map to correct systematic errors.
• LOW_CONFIDENCE triggers when prediction scores fall below mode-specific thresholds, forcing fallback to TXT or UNKNOWN.
• The logic resides in _get_output_label_from_dl_label_and_score within the Python implementation and is mirrored in Rust and JavaScript bindings.

Frequently Asked Questions

What is the difference between the dl and output fields in Magika results?

The dl field contains the raw label and confidence score produced by the deep-learning model before any post-processing. The output field contains the final content-type label after applying the overwrite map and confidence threshold checks. The overwrite_reason field specifically tracks why these two values might differ.

When does Magika use the LOW_CONFIDENCE overwrite reason?

Magika sets LOW_CONFIDENCE when the model's confidence score falls below the threshold defined by the current prediction mode (high, medium, or best-guess). In this case, the system disregards the model's prediction and falls back to a generic TXT or UNKNOWN label to avoid false positives.

How can I disable the overwrite map in Magika?

You cannot directly disable the overwrite map through the public API, as it is baked into the model configuration files (such as config.min.json). However, you can compare result.prediction.dl.label with result.prediction.output.label and ignore the overwrite logic by using the raw DL prediction when overwrite_reason equals OVERWRITE_MAP.

Is overwrite_reason available in all Magika language bindings?

Yes, the overwrite_reason field is available in the Python, JavaScript/TypeScript, and Rust implementations of Magika. While the Python API uses the OverwriteReason enum class, the JavaScript and Rust versions expose the values as strings ("none", "overwrite_map", "low_confidence"), ensuring consistent behavior across platforms.

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