feat: add AI photo organizer with face recognition and multi-language support

Add the `pdx organize` command that uses a vision-language model via
Ollama to describe photos and group them into named folders by date.

- YAML-based configuration with example template
- Family context file for personalized AI descriptions
- Folder history as style examples for AI naming
- Face recognition via insightface with reference photo directories
- HEIC/HEIF conversion for VLM compatibility
- Multi-language prompts (Czech and English)
- Video discovery and organization alongside photos
- GPS/EXIF-based location extraction with home location filtering
- Helpful error when config.yaml is missing
- Documentation for setup, configuration, and all features

Bug fixes:
- fix: move text tokens to GPU and results back to CPU in prompt_to_vector
- fix: filter files by supported extensions in handle_path to prevent
  indexing non-photo files passed as arguments

Author: iswiac

.gitignore

@@ -1,2 +1,9 @@
+# Configuration and Personal Data
+config.yaml
+family_context.txt
+history_cache.json
+
+# Python artifacts
+.venv/
 /pdx.egg-info/
 __pycache__/

README-Windows.md

@@ -43,9 +43,78 @@ cd pdx
 cd /mnt/c/Users/<YourWindowsUser>/
 ```
 
+## Install exiftool
+
+The `organize` command requires `exiftool` for EXIF and GPS metadata extraction.
+Without it, all photos will show as "Unknown location".
+
+```
+sudo apt install -y libimage-exiftool-perl
+```
+
+## Connect to Ollama on Windows
+
+If Ollama is installed on Windows (not inside WSL), you need to make it accessible from WSL.
+
+### 1. Make Ollama listen on all interfaces
+
+Set a Windows environment variable:
+
+- **Settings → System → About → Advanced system settings → Environment Variables**
+- Add a new variable: `OLLAMA_HOST` = `0.0.0.0`
+- Fully quit Ollama from the system tray (right-click → Quit) and relaunch it
+
+Verify in PowerShell:
+
+```
+netstat -an | findstr 11434
+```
+
+You should see `0.0.0.0:11434` in the output.
+
+### 2. Add a firewall rule
+
+Find the WSL network address. In WSL, run:
+
+```
+ip -4 addr show eth0 | grep -oP 'inet \K[\d.]+'
+```
+
+Replace the host part of the IP with `0` to get the network address (e.g. if the
+command prints `a.b.c.d`, use `a.b.0.0`). Then open PowerShell as Administrator:
+
+```
+netsh advfirewall firewall add rule name="Ollama WSL" dir=in action=allow protocol=TCP localport=11434 remoteip=<a.b.0.0>/20
+```
+
+This restricts access to the WSL subnet only.
+
+### 3. Update config.yaml
+
+Find your WSL gateway IP (this is the Windows host as seen from WSL):
+
+```
+ip route show default | awk '{print $3}'
+```
+
+Update `config.yaml` with that IP:
+
+```yaml
+ai:
+  ollama_url: "http://<gateway-ip>:11434/api/chat"
+```
+
+### 4. Verify connectivity
+
+```
+curl http://<gateway-ip>:11434/api/version
+```
+
+You should get a JSON response with the Ollama version.
+
 ## Additional Debian packages (optional)
 
-- To view the photos selected after a `pdx` query, use `qimgv` instead of `gwenview` due to stability in Windows 
+- To view the photos selected after a `pdx` query, use `qimgv` instead of `gwenview` due to stability in Windows
 ```
 sudo apt install -y qimgv
 ```

README.md

@@ -1,5 +1,15 @@
 # Photo inDeXer (pdx)
 
+## Prerequisites
+
+- Python 3.13+
+- [Ollama](https://ollama.com) with a vision-language model pulled (e.g. `ollama pull gemma4:26b`)
+- [Podman](https://podman.io) for running Qdrant
+- `exiftool` for EXIF/GPS metadata extraction (`sudo apt install -y libimage-exiftool-perl`)
+- `libGL` for face recognition (`sudo apt install -y libgl1` on Debian/Ubuntu, `sudo dnf install -y mesa-libGL` on Fedora) — optional, only needed if using the `faces` config
+
+See [README-Windows.md](README-Windows.md) for Windows/WSL-specific setup.
+
 ## Set up a virtual Python environment
 
 ```sh
@@ -8,6 +18,60 @@ source .venv/bin/activate
 pip install -e .
 ```
 
+## Configuration
+
+Copy the example config and adjust it for your setup:
+
+```sh
+cp config.example.yaml config.yaml
+```
+
+| Section | Key | Description |
+|---------|-----|-------------|
+| `ai` | `language` | Output language: `cs` (Czech) or `en` (English) |
+| `ai` | `ollama_url` | URL of the Ollama API endpoint |
+| `ai` | `model_name` | Vision-language model to use (e.g. `gemma4:26b`) |
+| `location` | `home_names` | List of city names considered "home" — photos taken here won't have the location in the folder name |
+| `faces` | `reference_dir` | Directory with reference face photos for recognition (one subdirectory per person) |
+| `faces` | `similarity_threshold` | Face matching threshold (lower = stricter, default `0.4`) |
+| `faces` | `name_map` | Map directory names to display names (e.g. `john: "Johnny"`) |
+| `storage` | `context_file` | Path to a text file with family/personal context for the AI |
+| `storage` | `history_file` | JSON list of past folder names (e.g. `"210619 - Beach volleyball"`) used as style examples for AI naming |
+
+### Face recognition (optional)
+
+To enable face recognition, create a reference directory with one subdirectory per person, each containing a few clear photos of their face (one face per photo):
+
+```
+~/results/pdx/faces/
+├── john/
+│   ├── photo1.jpg
+│   ├── photo2.jpg
+│   └── photo3.jpg
+└── jane/
+    ├── photo1.jpg
+    └── photo2.jpg
+```
+
+Directory names are used as identifiers. Use `name_map` in the config to map them to display names (e.g. `john: "Johnny"`). 3-5 reference photos per person is usually enough.
+
+### Family context (optional)
+
+The `context_file` (default: `family_context.txt`) gives the AI background knowledge about your family — names, hobbies, sports, travel habits. This helps it generate more accurate photo descriptions and folder names. Write it in the same language as your `language` setting. Example:
+
+```
+FAMILY MEMBERS:
+- Dad: Born 1985. Hobbies, sports.
+- Mom: Born 1987. Hobbies, interests.
+- Child1: Born 2013. Sport (team name, jersey color).
+
+SPORTS:
+- Sport1 (Child1 only): Jersey description, equipment.
+- Sport2 (Dad): Gear, typical events.
+```
+
+If the file is missing, the AI falls back to generic descriptions.
+
 ## Start/stop Qdrant (podman)
 
 Storage is in the `pdx` directory under XDG data home (default: `~/.local/share/pdx`).
@@ -29,6 +93,11 @@ pdx index -c private /path/to/private_photos    # create or extend the `private`
 pdx erase -c private                            # delete the `private` collection
 ```
 
+## Organize photos
+```sh
+pdx organize -c private /path/to/organized_folder   # Use AI and EXIF to group photos into a structured directory tree.
+```
+
 ## Query photos
 
 ```sh

config.example.yaml

@@ -0,0 +1,22 @@
+# PDX Configuration Template
+# Copy this file to config.yaml and adjust for your setup.
+
+ai:
+  language: en  # cs or en
+  ollama_url: "http://localhost:11434/api/chat"
+  model_name: "gemma4:26b"
+
+location:
+  # Add names of cities or districts you consider "Home"
+  home_names:
+    - "City"
+
+faces:
+  reference_dir: "faces"
+  similarity_threshold: 0.4
+  name_map:                       # optional: folder name -> display name
+    john: "John"
+
+storage:
+  context_file: "family_context.txt"
+  history_file: "folder_history.json"

pdx/cli.py

@@ -56,6 +56,26 @@ def index(collection: str, force_cpu: bool, real_path: bool, paths: tuple[str, .
     idx.index_photos(collection, photos)
 
 
+@pdx.command()
+@click.argument("target", type=click.Path())
+@click.option("--collection", "-c", default="default", help="Qdrant collection name.")
+@click.option("--config", "-f", default="config.yaml", help="Path to config file.")
+def organize(target: str, collection: str, config: str):
+    """Organize indexed photos into a structured directory tree."""
+    from pdx.organizer import Organizer
+
+    logging.basicConfig(level=logging.INFO)
+    config_path = os.path.realpath(config)
+    if not os.path.isfile(config_path):
+        raise click.BadParameter(
+            f"Config file not found: {config}\n"
+            "Copy config.example.yaml to config.yaml and adjust it for your setup.",
+            param_hint="'--config'",
+        )
+    org = Organizer(collection, target, config_path=config_path)
+    org.organize()
+
+
 @pdx.command()
 @click.argument("query_args", nargs=-1)
 @click.option("--collection", "-c", default="default", help="Qdrant collection name.")

pdx/faces.py

@@ -0,0 +1,98 @@
+import logging
+import warnings
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+warnings.filterwarnings(
+    "ignore", message=".*estimate.*deprecated.*", category=FutureWarning
+)
+from insightface.app import FaceAnalysis
+
+
+PHOTO_EXTENSIONS = {".jpg", ".jpeg", ".png", ".heic", ".heif"}
+
+
+class FaceRecognizer:
+    def __init__(
+        self,
+        reference_dir,
+        similarity_threshold=0.4,
+        det_size=(640, 640),
+        name_map=None,
+    ):
+        self.similarity_threshold = similarity_threshold
+        self.name_map = name_map or {}
+
+        self.app = FaceAnalysis(name="buffalo_l", providers=["CPUExecutionProvider"])
+        self.app.prepare(ctx_id=-1, det_size=det_size)
+
+        self.centroids = self._load_references(Path(reference_dir))
+        if self.centroids:
+            logging.info(
+                f"Face recognition: loaded {len(self.centroids)} persons: {', '.join(self.centroids.keys())}"
+            )
+        else:
+            logging.warning("Face recognition: no reference embeddings loaded")
+
+    def _load_references(self, reference_dir):
+        centroids = {}
+        for person_dir in sorted(reference_dir.iterdir()):
+            if not person_dir.is_dir():
+                continue
+            embeddings = []
+            for img_file in sorted(person_dir.iterdir()):
+                if img_file.suffix.lower() not in PHOTO_EXTENSIONS:
+                    continue
+                img = cv2.imread(str(img_file))
+                if img is None:
+                    logging.warning(f"Face ref: cannot read {img_file}")
+                    continue
+                faces = self.app.get(img)
+                if len(faces) == 0:
+                    logging.warning(f"Face ref: no face in {img_file}")
+                elif len(faces) > 1:
+                    logging.warning(f"Face ref: multiple faces in {img_file}, skipping")
+                else:
+                    embeddings.append(faces[0].embedding)
+            if embeddings:
+                centroids[person_dir.name] = np.mean(embeddings, axis=0)
+            else:
+                logging.warning(f"Face ref: no usable faces for '{person_dir.name}'")
+        return centroids
+
+    def _resolve_name(self, folder_name):
+        if folder_name in self.name_map:
+            return self.name_map[folder_name]
+        return folder_name[0].upper() + folder_name[1:]
+
+    def identify_faces(self, image_path):
+        try:
+            img = cv2.imread(str(image_path))
+            if img is None:
+                return []
+            faces = self.app.get(img)
+            if not faces:
+                return []
+        except Exception as e:
+            logging.warning(f"Face detection failed for {image_path}: {e}")
+            return []
+
+        identified = []
+        for face in faces:
+            best_name = None
+            best_score = -1
+            for name, centroid in self.centroids.items():
+                score = np.dot(face.embedding, centroid) / (
+                    np.linalg.norm(face.embedding) * np.linalg.norm(centroid)
+                )
+                if score > best_score:
+                    best_score = score
+                    best_name = name
+            if best_name and best_score >= self.similarity_threshold:
+                display_name = self._resolve_name(best_name)
+                if display_name not in identified:
+                    identified.append(display_name)
+
+        return identified

pdx/find.py

@@ -8,6 +8,7 @@
 
 
 PHOTOS_EXTS = ("heic", "heif", "jpeg", "jpg", "png")
+VIDEO_EXTS = ("mp4", "mov", "avi", "mkv", "mts", "m4v")
 
 
 class Finder:
@@ -42,8 +43,11 @@ def find_photos_in_dir(self, path: Path) -> None:
 
     def handle_path(self, path: Path) -> None:
         if path.is_file():
-            # take regular files as photos to index
-            self._photos.append(str(path))
+            ext = path.suffix[1:].lower() if path.suffix else ""
+            if ext in PHOTOS_EXTS:
+                self._photos.append(str(path))
+            else:
+                logging.warning(f"skipping unsupported file: {path}")
         elif path.is_dir():
             # traverse directories recursively and look for files matching PHOTOS_EXTS
             self.find_photos_in_dir(path)
@@ -59,3 +63,14 @@ def find_photos(paths: tuple[str, ...], include_symlinks: bool = False) -> list[
         finder.handle_path(path)
 
     return finder.photos
+
+
+def find_videos(directories: set[Path]) -> list[Path]:
+    videos = []
+    for d in directories:
+        if not d.is_dir():
+            continue
+        for f in d.iterdir():
+            if f.is_file() and f.suffix and f.suffix[1:].lower() in VIDEO_EXTS:
+                videos.append(f)
+    return videos

pdx/model.py

@@ -86,9 +86,13 @@ def tensors_to_vectors(self, tensors):
             return tensor.cpu().numpy()
 
     def prompt_to_vector(self, prompt):
+        """Fixed: Moves tokens to GPU and results to CPU."""
         with torch.no_grad():
-            text = self._tokenizer([prompt])
+            # Move text tokens to the device (GPU)
+            text = self._tokenizer([prompt]).to(self._device)
             encode_text_fn = cast(
                 Callable[..., torch.Tensor], getattr(self._model, "encode_text")
             )
-            return encode_text_fn(text).numpy().flatten().tolist()
+            # Move the resulting vector back to CPU
+            vector = encode_text_fn(text)
+            return vector.cpu().numpy().flatten().tolist()