MagikaInferencer¶

AI-powered file type detection using Google's Magika model.

from filetype_detector import MagikaInferencer

Overview¶

The MagikaInferencer uses Google's Magika AI model for advanced file type detection. It excels at detecting specific text file types (Python, JavaScript, JSON, INI, etc.) and provides confidence scores for predictions.

Class Definition¶

class MagikaInferencer(BaseInferencer):
    """Magika inferencer that uses Google's Magika AI to infer file format."""

Methods¶

`infer(file_path: Union[Path, str]) -> FileType`¶

Returns the detected file type as a FileType instance.

Parameters:

file_path (Union[Path, str]): Path to the file to analyze. Can be a string or Path object.

Returns:

FileType: A frozen dataclass with extensions and mime_types tuples based on Magika's prediction.

Raises:

FileNotFoundError: If the file does not exist.
ValueError: If the path is not a file.
RuntimeError: If Magika fails to analyze the file.

Examples:

from filetype_detector import MagikaInferencer
from pathlib import Path

inferencer = MagikaInferencer()

# String path
ft = inferencer.infer('document.pdf')
'.pdf' in ft.extensions  # True

# Path object
ft = inferencer.infer(Path('notes.txt'))
'.txt' in ft.extensions  # True

`infer_with_score(file_path: Union[Path, str], prediction_mode: PredictionMode = PredictionMode.MEDIUM_CONFIDENCE) -> Tuple[str, float]`¶

Core implementation that returns both extension and confidence score.

Parameters:

file_path (Union[Path, str]): Path to the file to analyze. Can be a string or Path object.
prediction_mode (PredictionMode, optional): Magika prediction mode controlling confidence level. Defaults to PredictionMode.MEDIUM_CONFIDENCE.

Returns:

Tuple[str, float]: Tuple of (extension, confidence_score) where extension includes the leading dot (e.g., '.pdf') and confidence_score is a float between 0.0 and 1.0.

Raises:

FileNotFoundError: If the file does not exist.
ValueError: If the path is not a file.
RuntimeError: If Magika fails to analyze the file.

Examples:

from filetype_detector import MagikaInferencer
from magika import PredictionMode

inferencer = MagikaInferencer()

# Default prediction mode
extension, score = inferencer.infer_with_score('document.pdf')
print(f"{extension}, {score:.2%}")  # Output: '.pdf, 99.00%'

# High confidence mode
extension, score = inferencer.infer_with_score(
    'script.py',
    prediction_mode=PredictionMode.HIGH_CONFIDENCE
)

Prediction Modes¶

Magika supports different prediction modes:

PredictionMode.MEDIUM_CONFIDENCE (default): Balanced speed and accuracy
PredictionMode.HIGH_CONFIDENCE: Higher accuracy, slightly slower
PredictionMode.BEST_GUESS: Fastest, lower threshold

from magika import PredictionMode

inferencer = MagikaInferencer()

# Medium confidence (default)
ext, score = inferencer.infer_with_score(
    "file.py",
    prediction_mode=PredictionMode.MEDIUM_CONFIDENCE
)

# High confidence
ext, score = inferencer.infer_with_score(
    "file.py",
    prediction_mode=PredictionMode.HIGH_CONFIDENCE
)

Usage Examples¶

Basic Usage¶

from filetype_detector import MagikaInferencer

inferencer = MagikaInferencer()
ft = inferencer.infer("script.py")
'.py' in ft.extensions  # True
ft.mime_types            # ('text/x-python',) or similar

With Confidence Scores¶

inferencer = MagikaInferencer()
extension, confidence = inferencer.infer_with_score("data.json")
print(f"Type: {extension}, Confidence: {confidence:.2%}")
# Output: Type: .json, Confidence: 98.00%

Detecting Specific Text File Types¶

inferencer = MagikaInferencer()

ft = inferencer.infer("script.py")
'.py' in ft.extensions   # True

ft = inferencer.infer("code.js")
'.js' in ft.extensions   # True

# JSON data in a .txt file
ft = inferencer.infer("data.txt")
'.json' in ft.extensions  # Possibly True

Filtering by Confidence¶

inferencer = MagikaInferencer()

extension, score = inferencer.infer_with_score("file.py")

if score >= 0.95:
    print(f"High confidence: {extension}")
elif score >= 0.80:
    print(f"Medium confidence: {extension}")
else:
    print(f"Low confidence: {extension}")

Error Handling¶

from filetype_detector import MagikaInferencer

inferencer = MagikaInferencer()

try:
    extension = inferencer.infer("nonexistent.pdf")
except FileNotFoundError:
    print("File not found")
except ValueError:
    print("Path is not a file")
except RuntimeError as e:
    print(f"Magika failed: {e}")

How It Works¶

File Validation: Checks if file exists and is accessible
AI Inference: Uses Magika model to analyze file content
Extension Extraction: Extracts extension from Magika's output
Format Normalization: Ensures extension starts with dot

Performance¶

Speed: ~5-10ms per file (after model load)
Model Load: ~100-200ms one-time overhead
Memory: High (~50-100MB for model)
Throughput: 100-200 files/second

See Examples and Patterns for optimization tips.

When to Use¶

✅ Good for: - Highest accuracy requirements - Text file type detection (especially effective) - Need confidence scores - Detecting specific code/data formats - Files with misleading extensions

❌ Not suitable for: - Maximum performance requirements (use LexicalInferencer) - Binary-only workflows (use MagicInferencer) - Very high-volume processing

Model Loading¶

The Magika model is loaded when the inferencer is instantiated:

# Model loads here (~100-200ms)
inferencer = MagikaInferencer()

# Subsequent calls are faster (~5-10ms)
extension = inferencer.infer("file.py")

Best Practice: Create one instance and reuse it for multiple files.

Output Format¶

Magika returns extensions in different formats. The MagikaInferencer normalizes this:

List format: ['py', 'pyi'] → Returns first: .py
String format: 'json' → Returns: .json
Empty result: Falls back to Magic result (in HybridInferencer)

Comparison with Other Inferencers¶

Aspect	MagikaInferencer	MagicInferencer	LexicalInferencer
Text detection	Learned labels and confidence	libmagic MIME database	Filename MIME database
Binary detection	Model-dependent	libmagic signatures	Filename MIME database
Speed	Slower	Fast	Fastest
Confidence scores	Yes	No	No
Memory usage	High	Low	Minimal

Compare actual results for each supported runtime in the backend conformance report.

Known Limitations¶

HWP not supported: HWP (Hangul Word Processor) is not in Magika's training data. infer() returns a FileType with empty extensions and mime_types.
ZIP-based formats misclassified: HWPX, ODF, ePub, and other ZIP-wrapped formats may be misidentified (e.g., HWPX is sometimes classified as .epub) because Magika does not inspect the internal XML structure.
Binary formats vs. text formats: The advantage over MagicInferencer is strongest for text files. For mainstream binary formats (PDF, PNG, ZIP), the two inferencers typically agree.
Model size: Requires ~50-100MB memory
Load time: Initial model load takes 100-200ms per new instance