How to Use a Custom Model Directory with Magika: Complete Implementation Guide

Yes, Magika supports custom model directories through the Python API constructor, CLI --model-dir flag, or the MAGIKA_MODEL_DIR environment variable.

The Magika file identification library from Google's open-source repository provides flexible model loading capabilities. Whether you are deploying fine-tuned models or testing experimental weights, you can override the bundled default by pointing the library to any compatible directory containing the required ONNX artifacts.

How Custom Model Support Works

Magika implements custom model loading through a cascading fallback system that prioritizes explicit arguments over environment variables and bundled defaults.

The Magika Constructor

In python/src/magika/magika.py lines 86‑94, the __init__ method signature accepts an optional model_dir parameter:

Magika(model_dir: Optional[Path] = None, …)

If you supply a Path object, the instance stores it internally in _model_dir. When omitted, Magika automatically resolves to the bundled default model located at magika/models/<default-name> alongside the source code.

Validation Requirements

Before loading, Magika validates the directory structure in lines 97‑102 of magika.py. The library verifies that the path exists and contains both required files. If validation fails, Magika raises a MagikaError immediately, preventing runtime failures during inference.

CLI and Environment Variable Fallbacks

The command-line interface in python/src/magika/cli/magika_client.py lines 27‑33 exposes a --model-dir option that passes directly to the constructor. If you omit the flag, Magika checks the MAGIKA_MODEL_DIR environment variable before falling back to the default model.

Required Files in a Custom Model Directory

A valid custom model directory must contain exactly two files:

• model.onnx – The ONNX-encoded neural network containing trained weights and architecture.
• config.min.json – Minimal configuration specifying input window sizes, confidence thresholds, and the label-to-content-type mapping.

The directory layout mirrors the bundled models structure:

my-custom-model/
├── model.onnx
└── config.min.json

Both files are generated when you export a trained Magika model using the training pipeline tools.

Implementation Examples

Python API with Explicit Path

Pass the directory path directly to the constructor when instantiating the Magika class:

from pathlib import Path
from magika import Magika

# Path to directory containing model.onnx + config.min.json

custom_dir = Path("/home/user/custom_magika_model")

# Initialize with custom model

magika = Magika(model_dir=custom_dir)

# Identify file content type

result = magika.identify_path("example.pdf")
print(result.prediction.output.label)   # ContentTypeLabel.PDF or custom label

Command-Line Interface

Use the --model-dir flag to override the default model for CLI operations:

magika --model-dir /home/user/custom_magika_model myfile.bin

Environment Variable Configuration

Set MAGIKA_MODEL_DIR to avoid hardcoding paths in scripts or shell commands:

export MAGIKA_MODEL_DIR=/home/user/custom_magika_model
magika myfile.bin          # CLI automatically picks up the environment variable

For Python applications that rely on default initialization:

import os
from magika import Magika

os.environ["MAGIKA_MODEL_DIR"] = "/home/user/custom_magika_model"
magika = Magika()          # No constructor argument needed

Summary

• Constructor parameter: Pass model_dir=Path("/your/path") to Magika() in python/src/magika/magika.py.
• CLI flexibility: Use --model-dir flag in magika_client.py for command-line operations.
• Environment fallback: Set MAGIKA_MODEL_DIR when you want system-wide configuration without code changes.
• Validation: Both model.onnx and config.min.json must exist in the target directory or MagikaError is raised.
• Structure: Custom directories must mirror the bundled model layout exactly.

Frequently Asked Questions

What files must a custom Magika model directory contain?

Every custom model directory must contain model.onnx (the neural network weights) and config.min.json (metadata and thresholds). These files are generated during the model export process in the Magika training pipeline. Missing either file triggers a MagikaError during initialization.

Can I use an environment variable instead of passing paths in code?

Yes. Set the MAGIKA_MODEL_DIR environment variable to your model directory path. When the Magika constructor is called without arguments, or when using the CLI without --model-dir, the library automatically checks this environment variable before falling back to the bundled default model.

What happens if the model files are missing or corrupted?

Magika performs strict validation in python/src/magika/magika.py lines 97‑102. If the directory does not exist, or if either model.onnx or config.min.json is missing, the library raises a MagikaError with a descriptive message. This prevents silent failures and ensures clear debugging information.

Does Magika support loading multiple custom models simultaneously?

No. Each Magika instance loads exactly one model directory specified at initialization. To use multiple models concurrently, instantiate separate Magika objects with different model_dir paths. Each instance maintains its own model session and configuration independently.

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