How to Identify a File by Path with the Magika Python API

Instantiate the Magika class and call identify_path() with a file system path to receive a MagikaResult object containing the detected content type, confidence score, and MIME type.

The Magika Python API provides a robust interface for content type detection using machine learning models. Developed by Google and hosted at google/magika, this library is implemented primarily in python/src/magika/magika.py and supports both single-file and batch identification workflows.

Initializing the Magika Class

The API centers around the Magika class defined in python/src/magika/magika.py. According to the source code at lines 57‑66, the constructor accepts optional configuration parameters to customize model behavior and output formatting.

You can specify the model directory, prediction mode, logging verbosity, and colorized output during instantiation. The model_dir parameter accepts a Path to a custom ONNX model, while prediction_mode controls confidence thresholds using the PredictionMode enum defined in python/src/magika/types/prediction_mode.py.

Identifying a Single File by Path

To identify a file’s content type, call identify_path with a file system path (string or os.PathLike). As implemented at lines 39‑48 of magika.py, this method validates the input argument, converts it to a Path object, and forwards the request to the internal processing pipeline.

Under the hood, identify_path delegates to _get_result_from_path, which opens the file, extracts a small set of byte-level features, and runs the ONNX inference model. For very small files that lack sufficient features, it falls back to lightweight heuristics rather than neural inference. The final result is produced via _get_result_from_labels_and_score and returned as a MagikaResult object (defined in python/src/magika/types/magika_result.py).

Practical Code Examples

Basic File Identification

from magika import Magika

# Initialise with default model and high-confidence mode

magika = Magika()

# Identify the file at the given path

result = magika.identify_path("/path/to/your/file.png")

# Access the most useful fields

print("Detected label :", result.prediction.output.label)
print("Confidence     :", result.prediction.score)
print("MIME type      :", result.prediction.output.mime_type)

Custom Model Configuration

from pathlib import Path
from magika import Magika, PredictionMode

magika = Magika(
    model_dir=Path("/opt/magika/models/custom_v1"),
    prediction_mode=PredictionMode.BEST_GUESS,
    verbose=True,
    use_colors=True,
)

result = magika.identify_path(Path("example.pdf"))
print(result)          # Human-readable representation

print(result.to_dict())  # Full dictionary, handy for JSON output

Batch Processing Multiple Files

For processing multiple files efficiently, use identify_paths (plural), which delegates each path to the same inference pipeline used by identify_path:

from magika import Magika

files = [
    "doc1.docx",
    "image.jpg",
    "archive.zip",
]

magika = Magika()
batch_results = magika.identify_paths(files)

for res in batch_results:
    print(f"{res.path.name}: {res.prediction.output.label}")

Key Implementation Files

The following source files comprise the public API and underlying inference pipeline:

• python/src/magika/magika.py — Contains the core Magika class, including identify_path, identify_paths, and the internal methods _get_result_from_path and _get_result_from_labels_and_score.

• python/src/magika/types/magika_result.py — Defines MagikaResult, MagikaPrediction, and related data structures returned by identification methods.

• python/src/magika/types/content_type_label.py — Enum of supported content-type labels (e.g., PNG, PDF, TXT).

• python/src/magika/types/prediction_mode.py — Enum controlling confidence thresholds: HIGH_CONFIDENCE, MEDIUM_CONFIDENCE, and BEST_GUESS.

• python/src/magika/logger.py — Helper for coloured, level-aware logging used by the Magika class.

Summary

• The Magika Python API centers on the Magika class in python/src/magika/magika.py.
• Call identify_path() with a file path to obtain a MagikaResult containing the content type label, confidence score, and MIME type.
• Use identify_paths() for efficient batch processing of multiple files.
• Configure custom models, prediction modes, and logging via the constructor at lines 57‑66.

Frequently Asked Questions

What is the difference between identify_path and identify_paths?

identify_path processes a single file path and returns one MagikaResult object, while identify_paths accepts a list of paths and returns a list of results. Both methods use the same underlying ONNX model and feature extraction logic implemented in python/src/magika/magika.py.

What prediction modes are available in the Magika Python API?

The API supports three modes defined in python/src/magika/types/prediction_mode.py: HIGH_CONFIDENCE (strict thresholds, fewer misclassifications), MEDIUM_CONFIDENCE (balanced approach), and BEST_GUESS (always returns the top prediction regardless of confidence).

How does Magika handle very small files?

When identify_path delegates to _get_result_from_path, the implementation checks file size. For very small files that lack sufficient features for the ONNX model, Magika falls back to lightweight heuristics rather than neural inference, as implemented in the processing pipeline of magika.py.

Can I use a custom model with the Magika Python API?

Yes. Pass a Path object to the model_dir parameter when constructing the Magika instance (lines 57‑66). This directs the API to load your custom ONNX model from the specified directory instead of the bundled default model.

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