Magika Model Output vs Tool Output: Understanding the Difference in Google Magika

Magika's model output (dl) is the raw label predicted by the deep learning neural network, while the tool output (output) is the final label returned after confidence thresholds, overwrite rules, and special-case handling are applied.

When using the google/magika Python library to identify file content types, you encounter two distinct prediction fields: dl and output. Understanding the difference between Magika's model output and tool output is essential for debugging classification results and choosing the correct field for production applications.

What Is Magika Model Output?

The model output represents the raw prediction from Magika's deep learning neural network. In the codebase, this is exposed as the dl field (short for "deep learning") within the MagikaPrediction dataclass defined in python/src/magika/types/magika_prediction.py.

When you access result.prediction.dl.label, you see the exact content type label the neural network predicted based on the file's byte patterns. This value does not account for confidence scores, file system metadata, or post-processing rules. The model output is primarily useful for debugging, research, or when you need to inspect the raw neural network behavior before any business logic is applied.

What Is Magika Tool Output?

The tool output represents the final, user-facing content type label after Magika applies its complete decision pipeline. This is exposed as the output field in the MagikaPrediction dataclass and is the default value returned to users.

According to the source code in python/src/magika/magika.py, the tool output is constructed through get_output_content_types(), which merges model labels with special types (directory, symlink, empty) and applies the overwrite map. Most production code should use this field because it reflects Magika's complete decision process rather than just the neural network's raw guess.

Post-Processing Steps Between Model and Tool Output

Several transformations occur between the raw model prediction and the final tool output:

Confidence Threshold Filtering

Low-confidence predictions are discarded and may be replaced with generic labels or handled according to fallback rules. If the model's confidence score falls below the configured threshold, the tool output may differ significantly from the model output.

Overwrite Map Rules

The overwrite_map configuration deliberately replaces certain labels with alternatives. For example, a zero-byte file might have its model prediction overwritten from "txt" to "empty" based on file system properties rather than content analysis.

Special Case Handling

Directories, symbolic links, empty files, and other non-standard inputs are handled without invoking the deep learning model at all. The get_output_content_types() method in python/src/magika/magika.py (lines 13-20) explicitly includes these special types in the tool output set, while get_model_content_types() (lines 41-48) only returns labels the neural network can actually predict.

Heuristic Overrides

Additional checks such as magic-byte pattern matching can override the deep learning result when the tool detects specific file signatures that contradict or refine the model's prediction.

How to Access Both Outputs in Python

When using the magika Python library, both outputs are available through the MagikaResult object returned by identification methods:

from magika import Magika

m = Magika()

# Identify a file

result = m.identify_path("example.pdf")

# Access raw model output (deep learning prediction)

print("Model output:", result.prediction.dl.label)      # e.g., "pdf"

print("Model score:", result.prediction.dl.score)       # confidence 0.0-1.0

# Access final tool output (after post-processing)

print("Tool output:", result.prediction.output.label)   # e.g., "pdf" or "txt"

print("Tool score:", result.prediction.output.score)

# Convenience shortcuts

print("Shortcut - model:", result.dl.label)
print("Shortcut - tool:", result.output.label)

For special cases like empty files, the model output may be undefined while the tool output remains valid:

# Empty file handling

empty_res = m.identify_bytes(b"")
print("Empty file tool output:", empty_res.output.label)   # "empty"

# empty_res.dl would raise an error or be undefined since no model was invoked

Summary

• Model output (dl): The raw content type label predicted by Magika's deep learning neural network, available before any post-processing rules are applied.
• Tool output (output): The final label returned to users after confidence thresholds, overwrite maps, special-case handling, and heuristics are applied.
• Production usage: Always use output (tool output) for production applications, as it reflects Magika's complete decision pipeline including handling of directories, symlinks, and empty files.
• Debugging: Use dl (model output) only when debugging model behavior or conducting research on the raw neural network predictions.

Frequently Asked Questions

What happens when Magika encounters a directory instead of a file?

When Magika identifies a directory, it bypasses the deep learning model entirely. The model output (dl) is not populated because the neural network only processes file content. However, the tool output (output) returns a special label such as "directory" or "symlink" based on file system metadata. This distinction is handled in get_output_content_types() in python/src/magika/magika.py, which includes these special types in the tool's possible output set.

Why would the model output and tool output have different labels for the same file?

The tool output applies post-processing rules that can override the model's raw prediction. If the model predicts "txt" with low confidence, the confidence threshold filtering may change the output to a generic label. Additionally, the overwrite_map configuration can deliberately replace specific labels—such as forcing "txt" to "empty" for zero-byte files. Heuristic checks like magic-byte validation can also override the neural network when file signatures contradict the model's guess.

Is the model output ever undefined or null?

Yes, the model output (dl) can be undefined when the deep learning model is not invoked. This occurs with special inputs such as empty files, directories, symbolic links, or files below the minimum size threshold. In these cases, MagikaResult.prediction.dl may raise an error or return None, while MagikaResult.prediction.output remains valid and returns the appropriate special label like "empty" or "directory". Always check for the existence of model output before accessing it in code that handles diverse file types.

Which output should I use for production file classification?

Always use the tool output (output) for production applications. The tool output represents Magika's complete decision pipeline, incorporating confidence thresholds, overwrite rules, and special-case handling for non-file inputs. While the model output (dl) is useful for debugging the neural network's raw behavior, it lacks the safety checks and business logic that make Magika reliable for real-world file identification. Access the tool output via result.output.label or result.prediction.output.label in the Python API.

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