When Does Magika Return Generic Labels Like "Unknown Binary Data"

Magika returns generic labels such as "Unknown binary data" or "Generic text document" whenever the neural network's confidence score falls below per-content-type thresholds or when files are too small to process, defaulting to binary-versus-text heuristics.

In the google/magika repository, the content-type detection system relies on deep learning models with specific confidence requirements. When the model cannot provide a trustworthy prediction, Magika intentionally returns generic labels rather than guessing specific formats. Understanding when Magika returns generic labels helps developers interpret results and handle edge cases in file processing pipelines.

How Magika Decides Between Specific and Generic Labels

The core decision logic resides in python/src/magika/magika.py. Specifically, the _get_output_label_from_dl_label_and_score method (lines 998‑1026) evaluates whether to trust the model's raw prediction. When the confidence is insufficient, the code falls back to either ContentTypeLabel.TXT for text files or ContentTypeLabel.UNKNOWN for binary files, returning the human-readable descriptions "Generic text document" or "Unknown binary data" respectively.

This fallback occurs when the model's score fails to meet two possible criteria:

• The per-content-type high-confidence threshold (e.g., 0.9 for most types, 0.95 for unknown)
• The global medium-confidence threshold (typically 0.5 as defined in config.min.json)

If the score falls below both thresholds, Magika discards the specific prediction and assigns a generic label based solely on the file's binary versus text nature.

Three Scenarios That Trigger Generic Label Fallbacks

Low Confidence Scores Below Per-Content-Type Thresholds

Each content type in the standard_v3_3 model (defined in assets/models/standard_v3_3/config.min.json) maintains its own high-confidence threshold. For example, crt and handlebars require scores above 0.9, while the unknown label itself requires 0.95. If the model outputs a prediction with a confidence of 0.4 for a PE32 executable, Magika compares this against the type-specific threshold. When the score is insufficient, the code in magika.py triggers the generic fallback logic instead of returning the uncertain label.

Files Smaller Than the Minimum Ingest Size

Magika's neural network requires a minimum input size of approximately 8 bytes. Files smaller than this threshold never reach the model. Instead, Magika applies a lightweight heuristic to determine if the content appears textual or binary, then immediately returns the corresponding generic label. This behavior is documented in website-ng/src/content/docs/core-concepts/how-magika-works.md and implemented in the same fallback path as low-confidence predictions.

Explicit Label Overrides That Fail Validation

The model configuration supports an overwrite_map (referenced in magika.py lines 84‑90) that can remap raw predictions to different output labels. If the code applies an override from self._model_config.overwrite_map but the resulting label still fails the confidence checks described above, Magika applies the generic label fallback. This ensures that remapped but uncertain predictions do not bypass the safety mechanisms.

Confidence Threshold Configuration in Magika

The thresholds governing these decisions are stored in each model's config.min.json. For the default standard_v3_3 model, the configuration specifies:

{
  "thresholds": {
    "crt": 0.9,
    "handlebars": 0.9,
    "unknown": 0.95
  },
  "medium_confidence_threshold": 0.5
}

When magika.identify() processes a file, it compares the raw model score against the specific threshold for the predicted content type. If the score is below that threshold, it checks against the global medium_confidence_threshold. Failure to exceed either results in the generic label assignment through the logic in _get_output_label_from_dl_label_and_score.

Practical Examples: Generating Generic Labels

The following examples demonstrate how to trigger Magika's generic label returns using the Python API and CLI.

Python API with Low-Confidence Random Bytes

from magika import Magika

magika = Magika(prediction_mode="high-confidence")

# Random binary content that confuses the model

result = magika.identify(b"\x00\xff\xab\xcd\x12\x34")
print(result.prediction.output.label)        # → unknown

print(result.prediction.output.description)  # → Unknown binary data

Why this happens: The raw model score for the nearest content type remains below the per-type high-confidence threshold (0.95 for unknown), forcing the fallback to ContentTypeLabel.UNKNOWN.

CLI with Tiny Text Files

$ echo -n "a" > tiny.txt    # Creates a 1-byte file

$ magika tiny.txt
tiny.txt: Generic text document

The file size is below the model's minimum ingest size, so Magika skips inference and returns the generic text label based on character analysis.

CLI with Unrecognizable Binary Data

$ head -c 1024 /dev/urandom > random.bin
$ magika random.bin
random.bin: Unknown binary data

Despite sufficient file size, the random bytes produce no confident predictions. The model's highest score falls below the required thresholds, triggering the generic binary fallback.

Summary

• Magika returns generic labels whenever model confidence is insufficient to trust a specific content-type prediction.
• The decision occurs in python/src/magika/magika.py within the _get_output_label_from_dl_label_and_score method, which compares scores against per-type thresholds and a global medium-confidence threshold.
• Three main conditions trigger this behavior: scores below content-type thresholds, files smaller than ~8 bytes, and remapped labels that fail validation.
• The thresholds are configurable per model in config.min.json, with the default standard_v3_3 model using values ranging from 0.9 to 0.95 for high confidence and 0.5 for medium confidence.
• Generic outputs are either "Unknown binary data" for binary content or "Generic text document" for text content, never specific format identifications.

Frequently Asked Questions

What is the difference between "Unknown binary data" and "Generic text document"?

"Unknown binary data" (unknown) indicates that Magika detected binary content but could not identify a specific format with sufficient confidence. "Generic text document" (txt) indicates the content appears to be text, but Magika cannot determine a specific text-based format like HTML or JavaScript. The distinction is made by analyzing whether the bytes contain primarily text characters or binary data.

Can I adjust the confidence thresholds to reduce generic label returns?

Yes, you can modify the thresholds and medium_confidence_threshold values in the model's config.min.json file, located at assets/models/standard_v3_3/config.min.json for the default model. Lowering these values causes Magika to accept lower-confidence predictions, though this increases the risk of misclassification. Alternatively, instantiate Magika(prediction_mode="medium-confidence") to use less strict default thresholds without editing configuration files.

Why does Magika return generic labels instead of its best guess?

According to the source code in google/magika, the system prioritizes reliability over specificity. When the model's confidence score falls below the thresholds defined in _get_output_label_from_dl_label_and_score, returning a specific but potentially incorrect label would be less useful than indicating "unknown." This design prevents downstream tools from processing files based on incorrect format assumptions while still providing useful binary-versus-text categorization.

What file size triggers the generic label fallback?

Files smaller than approximately 8 bytes automatically receive generic labels because they fall below the model's minimum ingest size. For these tiny files, Magika never invokes the neural network; instead, it applies a simple heuristic to distinguish text from binary and returns the appropriate generic label immediately.

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