photonamer 0.1.0__tar.gz

photonamer-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: photonamer
+Version: 0.1.0
+Summary: Autonomous AI Photo Namer using MLX
+Requires-Dist: typer>=0.24.1
+Requires-Dist: rich>=14.3.3
+Requires-Dist: mlx-vlm>=0.4.2
+Requires-Dist: Pillow>=12.1.1
+Requires-Dist: exifread>=3.5.1
+Requires-Dist: transformers>=5.4.0
+Requires-Dist: qwen-vl-utils>=0.0.14
+Requires-Dist: torchvision>=0.26.0

photonamer-0.1.0/README.md

@@ -0,0 +1,70 @@
+# Photonamer: Autonomous AI Image File Renamer for Apple Silicon Macs
+
+PhotoNamer is a fast, privacy-first CLI tool that uses local a Vision-Language Model (specifically Qwen2.5-VL) to analyze your photos and automatically rename them based on their visual composition, lighting, and mood. 
+
+Built specifically for Apple Silicon using the MLX framework, it processes heavy RAW and JPEG files entirely offline—meaning your personal photos never leave your Mac.
+
+## Features
+* **True Visual Understanding:** Powered by Qwen2.5-VL, it looks at the image and extracts the subject, mood, lighting, and photographic principles.
+* **100% Local & Private:** No API keys, no cloud uploads, no subscriptions. Everything runs on your own hardware.
+* **Apple Silicon Optimized:** Uses Apple's native MLX framework for unified memory processing, keeping RAM usage perfectly stable even when processing thousands of photos.
+* **Fail-Safe Dry Runs:** By default, the app runs in "Preview Mode" so you can see exactly how files will be renamed before altering your file system.
+* **Highly Customizable:** Interactive wizard lets you build your naming template on the fly and choose your preferred casing (PascalCase, snake_case, UPPERCASE, lowercase).
+
+---
+
+## Installation
+
+### Prerequisites
+* A Mac with an Apple Silicon chip (M1/M2/M3/M4), at least 16GB of RAM is recommended.
+* Python 3.10 or newer.
+
+### For Photographers & End-Users (Recommended)
+The safest and easiest way to install PhotoNamer globally is using `pipx`. This ensures the heavy AI dependencies don't conflict with your Mac's system files.
+
+1. Install `pipx` via Homebrew (if you haven't already):
+   ```bash
+   brew install pipx
+   pipx ensurepath
+   ```
+2. Install the app via `pipx`:
+   ```bash
+   pipx install git+https://github.com/Kevo-03/Automatic-Photo-Namer.git
+   ```
+
+### For Developers
+
+If you want to modify the source code or contribute, install it in editable mode:
+
+```bash
+git clone https://github.com/Kevo-03/Automatic-Photo-Namer.git
+cd Automatic-Photo-Namer
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+Navigate to any folder containing your photos (.jpg, .jpeg, .png, .nef) and simply run the command:
+
+```bash
+photonamer
+```
+The interactive wizard will guide you through the process:
+
+1. **Fields:** Choose what information you want in the filename (Options: date, subject, mood, lighting, principle).
+2. **Separator:** Choose how fields are connected (e.g., _ or -).
+3. **Casing Style:** Format the text (pascal, snake, upper, lower).
+4. **Execution:** Confirm if you want a safe dry-run (Preview) or a live execution.
+
+### Dry Run Example
+![Dry Run Example](figures/figure.png)
+
+
+### Architecture Under the Hood
+
+- **Engine:** Apple mlx-vlm for hardware-accelerated inference.
+- **Model:**  Qwen/Qwen2.5-VL-3B-Instruct for optimal speed-to-accuracy ratio.
+- **Memory Management:** Implements isolated sequential processing. The 5GB AI model loads into unified memory exactly once, and Python's garbage collector destroys individual image tensors post-inference, preventing thermal throttling or RAM overflow during massive batch jobs.
+- **CLI Framework:** Built with Typer and Rich for a beautiful, type-safe terminal experience. 

photonamer-0.1.0/photonamer/cli.py

@@ -0,0 +1,103 @@
+import typer
+from pathlib import Path
+from rich import print
+from rich.progress import track
+
+from . import vision
+from . import parser
+from . import utils
+
+app = typer.Typer(help="Autonomous AI Photo Namer")
+
+@app.command()
+def process_photos(
+    folder: Path = typer.Argument(
+        Path.cwd(), 
+        help="The directory containing the photos."
+    ),
+    fields: str = typer.Option(
+        "date, subject, mood, principle", 
+        "--fields", "-f",
+        prompt="\nWhat fields do you want in the filename? (comma-separated)\n[Options: date, subject, mood, lighting, principle] (Default: date, subject, mood, principle)",
+        show_default=False, 
+        help="Comma-separated list of tags to include."
+    ),
+    separator: str = typer.Option(
+        "_", 
+        "--sep", "-s",
+        prompt="\nWhat separator should connect the words? (e.g., '_' or '-') (Default: '_')",
+        show_default=False,
+        help="Character to separate the fields."
+    ),
+    casing: str = typer.Option(
+        "pascal", 
+        "--casing", "-c",
+        prompt="\nWhich casing style? (pascal, snake, kebab, upper, lower) (Default: pascal)",
+        show_default=False,
+        help="Text formatting style."
+    ),
+    dry_run: bool = typer.Option(
+        True, 
+        "--execute", "-e",
+        prompt="\nIs this a safe dry-run? (Default: Yes)",
+        show_default=False,
+        help="Set to False to actually rename the files."
+    )
+):
+    """
+    Scans a folder of images, uses local AI to extract visual tags, 
+    and renames them according to a custom template.
+    """
+    valid_extensions = {".jpg", ".jpeg", ".png", ".nef"}
+    images = [p for p in folder.iterdir() if p.is_file() and p.suffix.lower() in valid_extensions]
+
+    if not images:
+        print(f"[bold red]No valid images found in {folder}[/bold red]")
+        raise typer.Exit()
+
+    allowed_fields = {"date", "subject", "mood", "lighting", "principle"}
+    
+    selected_fields = [f.strip().lower() for f in fields.split(",")]
+   
+    for field in selected_fields:
+        if field not in allowed_fields:
+            print(f"\n[bold red]Error: '{field}' is not a valid option.[/bold red]")
+            print(f"[yellow]Please choose from: {', '.join(allowed_fields)}[/yellow]\n")
+            raise typer.Exit(code=1)
+            
+    generated_template = separator.join([f"{{{f}}}" for f in selected_fields])
+
+    print(f"\n[bold blue]Found {len(images)} images.[/bold blue]")
+    print(f"[dim]Generated Naming Template: {generated_template}[/dim]\n")
+    
+    if dry_run:
+        print("[bold yellow]DRY RUN MODE ACTIVATED. No files will actually be changed.[/bold yellow]\n")
+
+    analyzer = vision.ImageAnalyzer()
+
+    for img_path in track(images, description="Processing Photos..."):
+        
+        original_ext = img_path.suffix
+        date_str = utils.get_photo_date(img_path)
+        
+        raw_ai_text = analyzer.analyze_image(img_path)
+        
+        tags = parser.parse_ai_output(raw_ai_text)
+        
+        base_name = parser.format_filename(tags, date_str, generated_template, casing)
+        
+        new_path = utils.get_safe_filepath(folder, base_name, original_ext)
+        
+        if dry_run:
+            print(f"[dim]Preview:[/dim] {img_path.name} [bold green]➔[/bold green] {new_path.name}")
+        else:
+            try:
+                img_path.rename(new_path)
+                print(f"[dim]Renamed:[/dim] {img_path.name} [bold green]➔[/bold green] {new_path.name}")
+            except Exception as e:
+                print(f"[bold red]Failed to rename {img_path.name}: {e}[/bold red]")
+
+    print("\n[bold green]Processing complete![/bold green]\n")
+
+if __name__ == "__main__":
+    app()

photonamer-0.1.0/photonamer/parser.py

@@ -0,0 +1,82 @@
+import json
+
+def clean_json_string(raw_text: str) -> str:
+    """Strips markdown and conversational filler from LLM outputs."""
+    text = raw_text.strip()
+    
+    if text.startswith("```json"):
+        text = text[7:]
+    elif text.startswith("```"):
+        text = text[3:]
+        
+    if text.endswith("```"):
+        text = text[:-3]
+        
+    start_idx = text.find('{')
+    end_idx = text.rfind('}')
+    
+    if start_idx != -1 and end_idx != -1:
+        return text[start_idx:end_idx+1]
+        
+    return text.strip()
+
+
+def parse_ai_output(raw_text: str) -> dict:
+    """Safely converts the AI text into a dictionary, with fail-safes."""
+    cleaned_text = clean_json_string(raw_text)
+    
+    try:
+        return json.loads(cleaned_text)
+    except json.JSONDecodeError:
+        print(f"\nWarning: AI hallucinated invalid JSON. Skipping advanced tags.\nRaw text: {cleaned_text}")
+        return {
+            "subject": "UnknownSubject",
+            "mood": "UnknownMood",
+            "lighting": "UnknownLighting",
+            "photography_principle": "None"
+        }
+
+
+def format_filename(tags: dict, date_str: str, template: str, casing: str = "pascal") -> str:
+    """
+    Injects the parsed tags into the user's template using their preferred casing.
+    Example template: "{date}_{subject}_{mood}_{principle}"
+    """
+    
+    def apply_casing(val: str, style: str) -> str:
+        if not val or val.lower() == "none": 
+            return ""
+            
+        clean_val = "".join(c for c in val if c.isalnum() or c.isspace())
+        
+        if style == "pascal":
+            return clean_val.title().replace(" ", "")        # -> RuleOfThirds
+        elif style == "snake":
+            return clean_val.lower().replace(" ", "_")   # -> rule_of_thirds
+        elif style == "kebab":
+            return clean_val.lower().replace(" ", "-")       # -> rule-of-thirds
+        elif style == "upper":
+            return clean_val.upper().replace(" ", "")        # -> RULEOFTHIRDS
+        elif style == "lower":
+            return clean_val.lower().replace(" ", "")        # -> ruleofthirds
+        else:
+            return clean_val.replace(" ", "")                # Default fallback
+
+    formatted_tags = {
+        "date": date_str,
+        "subject": apply_casing(tags.get("subject", "Unknown"), casing),
+        "mood": apply_casing(tags.get("mood", "Neutral"), casing),
+        "lighting": apply_casing(tags.get("lighting", "Unknown"), casing),
+        "principle": apply_casing(tags.get("photography_principle", "None"), casing)
+    }
+
+    try:
+        base_name = template.format(**formatted_tags)
+        
+        base_name = base_name.replace("__", "_").replace("--", "-").strip("_-")
+        
+        return base_name
+        
+    except KeyError as e:
+        print(f"\nWarning: Invalid template key {e}. Using default format.")
+        return f"{formatted_tags['date']}_{formatted_tags['subject']}"

photonamer-0.1.0/photonamer/test.py

@@ -0,0 +1,73 @@
+import mlx.core as mx
+from mlx_vlm import load, generate
+from mlx_vlm.prompt_utils import apply_chat_template
+from mlx_vlm.utils import load_config
+from PIL import Image
+import json
+from pathlib import Path
+
+def clean_json_string(raw_text):
+    text = raw_text.strip()
+    
+    if text.startswith("```json"):
+        text = text[7:] 
+    elif text.startswith("```"):
+        text = text[3:]
+        
+    if text.endswith("```"):
+        text = text[:-3] 
+        
+    start_idx = text.find('{')
+    end_idx = text.rfind('}')
+    
+    if start_idx != -1 and end_idx != -1:
+        return text[start_idx:end_idx+1]
+        
+    return text.strip()
+
+model_path = "mlx-community/Qwen2.5-VL-7B-Instruct-4bit"
+model, processor = load(model_path)
+config = load_config(model_path)
+
+image_path = "/Users/kivanc/Desktop/Reflection/DSC_1008.JPG"
+og_extension = Path(image_path).suffix
+img = Image.open(image_path)
+max_size = 512
+img.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
+image = [img]
+prompt = """
+Analyze this image and extract its core visual characteristics. 
+You must output your response ONLY as a valid, parsable JSON object. 
+Do not include any conversational text, explanations, or markdown formatting (like ```json).
+
+Use the following exact JSON schema:
+{
+  "subject": "A 1-3 word description of the main subject (e.g., Galata Tower, Neon Sign, Golden Retriever)",
+  "mood": "A 1-2 word description of the emotional vibe or atmosphere (e.g., Vibrant, Moody, Melancholic, Uplifting)",
+  "lighting": "A 1-2 word description of the lighting condition (e.g., Golden Hour, Neon, Harsh, Soft, Low Key)",
+  "photography_principle": "The dominant photographic technique or composition rule used (e.g., Rule of Thirds, Reflection, Motion Blur, Bokeh, Symmetry, Leading Lines)"
+}
+"""
+
+formatted_prompt = apply_chat_template(
+    processor, config, prompt, num_images=len(image)
+)
+
+output = generate(model, processor, formatted_prompt, image, verbose=False)
+
+raw_text = output.text
+
+cleaned_text = clean_json_string(raw_text)
+
+try:
+    tags = json.loads(cleaned_text)
+    
+    subject = tags.get("subject", "Unknown").title().replace(" ", "")
+    mood = tags.get("mood", "Neutral").title().replace(" ", "")
+    principle = tags.get("photography_principle", "None").title().replace(" ", "")
+    
+    new_filename = f"{subject}_{mood}_{principle}{og_extension}"
+    print(f"\nSuccessfully parsed! Proposed filename: {new_filename}")
+
+except json.JSONDecodeError:
+    print(f"\nError: Failed to parse JSON even after cleaning.\nCleaned Text: {cleaned_text}")

photonamer-0.1.0/photonamer/utils.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+from datetime import datetime
+import exifread
+
+def get_photo_date(image_path: Path) -> str:
+  
+    try:
+        with open(image_path, 'rb') as f:
+            tags = exifread.process_file(f, details=False, stop_tag="EXIF DateTimeOriginal")
+            
+            if "EXIF DateTimeOriginal" in tags:
+                date_str = str(tags["EXIF DateTimeOriginal"])
+                date_obj = datetime.strptime(date_str, "%Y:%m:%d %H:%M:%S")
+                
+                return date_obj.strftime("%Y%m%d")
+                
+    except Exception as e:
+        print(f"Warning: Could not read EXIF date for {image_path.name}")
+        
+    return "UnknownDate"
+
+
+def get_safe_filepath(target_directory: Path, proposed_base_name: str, original_extension: str) -> Path:
+    """
+    Checks if a filename exists. If it does, appends _1, _2 safely.
+    Example: NeonSign_Vibrant.JPG -> NeonSign_Vibrant_1.JPG
+    """
+    proposed_path = target_directory / f"{proposed_base_name}{original_extension}"
+    
+    if not proposed_path.exists():
+        return proposed_path
+        
+    counter = 1
+    while True:
+        new_path = target_directory / f"{proposed_base_name}_{counter}{original_extension}"
+        
+        if not new_path.exists():
+            return new_path
+            
+        counter += 1

photonamer-0.1.0/photonamer/vision.py

@@ -0,0 +1,45 @@
+from PIL import Image
+
+class ImageAnalyzer:
+    def __init__(self):
+        import os
+        
+        os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+        os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+        
+        from mlx_vlm import load
+        from mlx_vlm.utils import load_config
+
+        self.model_path = "mlx-community/Qwen2.5-VL-7B-Instruct-4bit"
+        self.model, self.processor = load(self.model_path)
+        self.config = load_config(self.model_path)
+        self.prompt = """
+        Analyze this image and extract its core visual characteristics. 
+        You must output your response ONLY as a valid, parsable JSON object. 
+        Do not include any conversational text, explanations, or markdown formatting (like ```json).
+
+        Use the following exact JSON schema:
+        {
+        "subject": "A 1-3 word description of the main subject (e.g., Galata Tower, Neon Sign, Golden Retriever)",
+        "mood": "A 1-2 word description of the emotional vibe or atmosphere (e.g., Vibrant, Moody, Melancholic, Uplifting)",
+        "lighting": "A 1-2 word description of the lighting condition (e.g., Golden Hour, Neon, Harsh, Soft, Low Key)",
+        "photography_principle": "The dominant photographic technique or composition rule used (e.g., Rule of Thirds, Reflection, Motion Blur, Bokeh, Symmetry, Leading Lines)"
+        }
+        """
+    def analyze_image(self, image_path):
+
+        from mlx_vlm import generate
+        from mlx_vlm.prompt_utils import apply_chat_template
+
+        img = Image.open(image_path)
+        max_size = 512
+        img.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
+        image = [img]
+
+        formatted_prompt = apply_chat_template(
+            self.processor, self.config, self.prompt, num_images=len(image)
+        )
+
+        output = generate(self.model, self.processor, formatted_prompt, image, verbose=False)
+        return output.text
+

photonamer-0.1.0/photonamer.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: photonamer
+Version: 0.1.0
+Summary: Autonomous AI Photo Namer using MLX
+Requires-Dist: typer>=0.24.1
+Requires-Dist: rich>=14.3.3
+Requires-Dist: mlx-vlm>=0.4.2
+Requires-Dist: Pillow>=12.1.1
+Requires-Dist: exifread>=3.5.1
+Requires-Dist: transformers>=5.4.0
+Requires-Dist: qwen-vl-utils>=0.0.14
+Requires-Dist: torchvision>=0.26.0

photonamer-0.1.0/photonamer.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+photonamer/__init__.py
+photonamer/cli.py
+photonamer/parser.py
+photonamer/test.py
+photonamer/utils.py
+photonamer/vision.py
+photonamer.egg-info/PKG-INFO
+photonamer.egg-info/SOURCES.txt
+photonamer.egg-info/dependency_links.txt
+photonamer.egg-info/entry_points.txt
+photonamer.egg-info/requires.txt
+photonamer.egg-info/top_level.txt

photonamer-0.1.0/photonamer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

photonamer-0.1.0/photonamer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+photonamer = photonamer.cli:app

photonamer-0.1.0/photonamer.egg-info/requires.txt

@@ -0,0 +1,8 @@
+typer>=0.24.1
+rich>=14.3.3
+mlx-vlm>=0.4.2
+Pillow>=12.1.1
+exifread>=3.5.1
+transformers>=5.4.0
+qwen-vl-utils>=0.0.14
+torchvision>=0.26.0

photonamer-0.1.0/photonamer.egg-info/top_level.txt

@@ -0,0 +1 @@
+photonamer

photonamer-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "photonamer"
+version = "0.1.0"
+description = "Autonomous AI Photo Namer using MLX"
+dependencies = [
+    "typer>=0.24.1",
+    "rich>=14.3.3",
+    "mlx-vlm>=0.4.2",
+    "Pillow>=12.1.1",
+    "exifread>=3.5.1",
+    "transformers>=5.4.0",
+    "qwen-vl-utils>=0.0.14",
+    "torchvision>=0.26.0"
+]
+
+[project.scripts]
+photonamer = "photonamer.cli:app"
+
+[tool.setuptools]
+packages = ["photonamer"]

photonamer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+