TagPup is a unified, private desktop suite for offline photo tagging, sequential renaming, camera clock time-shifting, and local semantic search. Just like a loyal retriever puppy, TagPup sniffs out your photos' visual features and faces, fetches metadata, and tags your files to keep them organized.
Unlike cloud-dependent services, TagPup operates 100% locally using PyTorch, CLIP, face recognition models, and ExifTool to manage your physical photo files securely on your hard drive.
TagPup is structured around two equally important pillars:
┌──────────────────┐ ┌──────────────────┐
│ TagPup GUI │ (tagpup_web.py) │ AI CLI Engine │ (tagpup_cli.py)
│ (Local Web UI) │ │ (Advanced CLI) │
└────────┬─────────┘ └────────┬─────────┘
│ │
├─ Folder Browser & Multiselect ├─ Semantic CLIP Embeddings
├─ Batch Keywords & People Tagging ├─ Vector Search Index (FAISS)
├─ Sequential Renaming & Eviction ├─ Face Clustering (DBSCAN)
├─ Camera Time-Shift Highlight ├─ Zero-Shot Year Consensus
└─ Interactive Taxonomy Tree └─ ExifTool Metadata Writes
The TagPup GUI is a lightweight, responsive local web interface designed to manage folder visual hierarchies and edit photo file metadata directly.
- Folder Tree & Grid Selection: Browse folder groups sorted by capture year, toggle thumbnail dimensions (Small, Medium, Large), and select photo ranges (Shift-Click support).
- Smart Sequential Renaming: Sequential renaming based on a custom
[Grouping] - [Index] - [Caption]format. Automatically evicts folder name conflicts to temporary filenames and stores the original filename in image metadata. - Tag Taxonomy Tree Manager: An interactive collapsible manager tree. Easily create sub-tags, toggle whether categories are autocomplete-hidden, mark folders as custom "People" roots, and safely check image usage before deleting tags. Supports dynamic renaming which cascades to descendant nodes and updates image tags on disk.
- Interactive Tag Resolution: When adding a new tag or person, TagPup displays placement prompts. It prompts which root category the tag belongs to, prevents duplicates, and resolves ambiguous leaf names.
- Camera Time-Shifting: Toggles a clock adjustment panel to offset capture timestamps recursively for specific camera models.
For details on the interface layout, shortcuts, and mechanics, refer to the TagPup GUI Specification.
The AI CLI Engine is the underlying machine learning backend that indexes visual features, matches face coordinates, and computes predictions.
- Incremental Indexing: Generates visual embeddings using CLIP, the photo model named in the library's settings (
ViT-H-14, 1024-dimensional, by default; SigLIP 2 SO400M, 1152-dimensional, once a library is switched to it), and face crops using MTCNN + Facenet. Incremental indexes scan quickly by skipping files with matching sizes and timestamps. - Semantic natural language search: Cosine similarity queries against the FAISS vector database index, allowing you to find files by writing natural text prompts (in the TagPup page's search).
- Automated Tag Suggestion: Infers keywords using visual similarity, decay-weighted capture timestamps, path hints, and event-level consensus.
- Face Profile Self-Tuning: Clusters face vectors using DBSCAN and labels identity centroids automatically by analyzing photo metadata. Recognizes known faces in untagged images to boost tagging predictions.
For CLI commands references, algorithmic rules, and parameters, refer to the CLI Specification.
Tip
For a conceptual, step-by-step walkthrough of how TagPup works—from importing photos to auto-matching faces and using AI suggestions—check out the Getting Started Tutorial.
- OS: Windows 10 or 11
- Python: Python 3.10+ added to your system PATH
- ExifTool: Installed on your computer (expected path:
%USERPROFILE%\AppData\Local\Programs\ExifTool\exiftool.exe, else the one on PATH; a library may name another in its settings).
-
Clone or download this repository.
-
Run the setup script to initialize the virtual environment (
.venv), install PyTorch (with GPU/CUDA acceleration if supported), CLIP, FAISS, and MTCNN.Using PowerShell:
powershell -ExecutionPolicy Bypass -File .\setup.ps1
Using Command Prompt:
setup.bat
-
Launch the Application: You can start each interface directly using a single command:
- Start Folder Tagging (TagPup GUI):
.venv\Scripts\python tagpup_web.py --open tagpup
- Start Face Matching (TagTuner):
.venv\Scripts\python tagpup_web.py --open tuner
- Start Folder Tagging (TagPup GUI):
For guides, tutorials, specifications, and schemas:
- 📖 Getting Started Tutorial: High-level concept tutorial on building your photo taxonomy and utilizing confidence-based AI suggestions.
- 💡 Usage & CLI Examples: Practical commands cheat sheet, setup instructions, indexing, clustering, and searching walkthroughs.
- 🖥️ TagPup GUI Specification: Detailed design guidelines, folder browser actions, tag taxonomy tree manager, and metadata resolution prompts.
- 🎯 TagTuner UI Specification: Face tuning grid mechanics, autocompletes, DBSCAN identity matching, and profile workflows.
- 🐶 AI CLI Engine Specification: Machine learning architecture, CLIP embeddings, consensus scoring formulas, and CLI parameters.
- 🗄️ Database Specification: SQLite schema table structures and visual Entity-Relationship/Data-Flow diagrams.
- 🛠️ Development Notes: running the suites, how the jsdom harness works, and the traps that have cost real time.
- 🏗️ Architecture: the layers the code is moving to, where each module goes, and the phases that get it there.
Each library holds its own settings: the CLIP model its vectors are made with, the face-detection thresholds, Suggest's candidate words, the rename format and the ExifTool program. Change them in TagTuner's gear, Library settings; the ones whose change has consequences (the model, face detection, ExifTool) are locked behind a Change... that lists each consequence to acknowledge. Every change is recorded in the library's history and can be undone (tagpup_cli.py --db <library> history, undo).
A new library starts with the defaults. The libraries are in data/ in the TagPup home: the folder the code is in, unless the TAGPUP_HOME environment variable names another. ExifTool is found where its installer puts it, else on PATH.
A config.ini from an older version is no longer read by anything; it can be deleted (TagPup never touches it).
This project is licensed under the MIT License. ExifTool is owned by Phil Harvey and licensed under its own terms.