# Magika Model Output vs Tool Output: Understanding the Difference in Google Magika > Understand the Magika model output dl vs tool output. Learn how Magika applies confidence thresholds and rules to deliver a final, processed label for your files. - Repository: [Google/magika](https://github.com/google/magika) - Tags: deep-dive - Published: 2026-04-16 --- **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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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`](https://github.com/google/magika/blob/main/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: ```python 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: ```python # 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`](https://github.com/google/magika/blob/main/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.