Sidecar-tagger: A Non-Intrusive AI Metadata Engine with Four-Layer Pipeline for Intelligent File Management

Sidecar-tagger is a context-aware metadata engine designed specifically for semantic search UIs and OS-level file management systems. It uses a unique four-layer processing pipeline and stores metadata via the "sidecar file" mode without modifying original files. This addresses the pain points of traditional file tagging tools: time-consuming manual annotation, low accuracy of rule matching, and modification of original files. It balances cost and precision, and supports local-first processing.

In the field of digital asset management, traditional file tagging tools face a dilemma: manual annotation is time-consuming and labor-intensive, rule matching accuracy is limited, and many tools directly modify original files (e.g., embedding EXIF), which is unacceptable. Sidecar-tagger uses the sidecar mode to store metadata in independent JSON files, ensuring both the integrity of original files and rich semantic annotation.

The core of Sidecar-tagger is a layered progressive processing architecture that prioritizes local processing and calls cloud AI only when necessary:

1. Hash Gating: Calculate SHA-256 hash, reuse existing metadata, and efficiently handle duplicate files;
2. Native & OS Metadata: Extract ExifTool built-in metadata + OS information, directly output if confidence ≥0.8;
3. Semantic Cache: Generate ONNX vector embeddings locally, identify similar files via similarity (threshold 0.9) to reuse metadata;
4. LLM Refinement: Call Google Gemini 2.0 Flash for in-depth analysis, inject clustering context to reduce hallucinations.

Four preset analysis levels are provided for users to choose according to their needs:

• Minimal: Only hash gating, zero cost, fast deduplication;
• Fast: Hash + OS metadata, zero cost, ~100ms per file;
• Standard: Hash + OS + semantic cache, zero cost, default recommendation;
• Deep: Full four-layer pipeline, calls AI API, highest precision. The hierarchical design adapts to large-scale batch processing and high-precision professional scenarios.

The project is developed with Python3.11+, using strict type annotations to ensure maintainability; metadata structure is validated via Pydantic to ensure consistency; it relies on ExifTool (system-level, with installation methods for Windows/macOS/Linux) to support metadata extraction for professional formats; the command-line interface is concise, supporting batch processing of single files/directories, with analysis levels switchable via --level or fine-grained control via --layers.

Applicable to multiple scenarios:

• Personal users: Intelligent backend for local file managers, enabling searchable classification of photos and documents;
• Enterprise users: Integration into Digital Asset Management (DAM) systems for automated metadata annotation;
• Developers: Clear API and modular architecture facilitate secondary development. The feature of zero modification to original files makes it an ideal choice for data integrity-sensitive fields such as law, medical care, and scientific research.

Sidecar-tagger represents a new direction in metadata management: the layered architecture balances cost and precision, the sidecar mode protects original data, and local-first processing reduces cloud dependency. In the future, it can integrate multimodal AI (image understanding, document parsing, etc.) to become an all-around metadata engine, making it a worthwhile open-source project to try for building personal knowledge bases or enterprise content management systems.