Resolve open Dependabot security alerts (Pillow 13, drop Python 3.10)

.github/copilot-instructions.md

@@ -8,7 +8,7 @@ PhotoMapAI is an AI-powered image browser and search tool that enables semantic
 
 ### Tech Stack
 - **Frontend**: HTML, CSS, JavaScript (ES6 modules), Swiper.js, Plotly.js
-- **Backend**: Python 3.10-3.13, FastAPI, Uvicorn
+- **Backend**: Python 3.11-3.14, FastAPI, Uvicorn
 - **AI/ML**: CLIP (clip-anytorch), PyTorch, scikit-learn, UMAP
 - **Image Processing**: Pillow, pillow-heif
 - **Testing**: pytest (Python), Jest (JavaScript)
@@ -134,7 +134,7 @@ The backend uses FastAPI with modular routers:
 
 - Keep dependencies minimal and well-maintained
 - Use `pillow-heif` for HEIC image support
-- Pin setuptools<67 to avoid CLIP deprecation warnings
+- Import CLIP via `encoders.import_openai_clip()`, never `import clip` (it needs `pkg_resources`, which current setuptools lacks)
 - All image processing is local; no data sent to external services
 
 ### Documentation

.github/workflows/lint.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Install dependencies
         run: |

.github/workflows/run_tests.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.10', '3.14']
+        python-version: ['3.11', '3.14']
 
     steps:
       - name: Checkout code

CLAUDE.md

@@ -9,7 +9,7 @@ PhotoMapAI is a local-first image browser for large photo collections. It uses C
 ## Common Commands
 
 ```bash
-# Install for development (Python 3.10–3.13) — uv is preferred (see below)
+# Install for development (Python 3.11–3.14) — uv is preferred (see below)
 uv sync --extra testing --extra development   # creates .venv + editable install + locked deps
 npm install
 # (legacy equivalent: pip install -e .[testing,development])
@@ -44,7 +44,7 @@ uv sync --extra testing --extra development
 git fetch origin && git rebase origin/master && git push --force-with-lease
 ```
 
-Ruff is configured for line-length 120, target py310, rules E/W/F/I/UP/B (see pyproject.toml). Jest runs in jsdom with experimental ESM (the project is `"type": "module"`).
+Ruff is configured for line-length 120, target py311, rules E/W/F/I/UP/B (see pyproject.toml). Jest runs in jsdom with experimental ESM (the project is `"type": "module"`).
 
 ## Worktrees are mandatory for ANY code change — read before editing
 
@@ -140,7 +140,7 @@ This is the area under active refactor (current branch: `lstein/feature/refactor
 From `.github/copilot-instructions.md` — the parts that actually affect how you write code here:
 
 - **Python:** type hints on public functions, `pathlib.Path` (not `os.path`) for file operations, f-strings, imports ordered stdlib → third-party → local (`photomap` is first-party to isort). Code must pass `ruff check photomap tests`.
-- **Pinned quirk:** `setuptools<67` is intentional — avoids a deprecation warning from the CLIP dependency. Don't "fix" it.
+- **CLIP and `pkg_resources`:** `clip-anytorch` does `from pkg_resources import packaging`, and setuptools 81+ no longer ships `pkg_resources`. `OpenAIClipEncoder` supplies a throwaway stand-in while it imports `clip`. Don't bring back the old `setuptools<67` pin: those releases carry known advisories.
 - **New API endpoints:** add/extend a router under `photomap/backend/routers/`, use Pydantic models for request/response, include the router in `photomap_server.py`, add a `tests/backend/test_<name>.py`.
 - **New frontend features:** create a module in `static/javascript/`, wire shared state through `state.js`, register shortcuts in `events.js`, add a Jest test.
 - **JavaScript:** ES6 modules only, `const`/`let`, must pass `npm run lint` and `npm run format:check`.

INSTALL/install_linux_mac.sh

@@ -34,14 +34,14 @@ detect_os() {
 # Function to check Python version
 check_python() {
     if ! command -v python3 &> /dev/null; then
-        print_error "Python 3 is not installed. Please install Python 3.10 or higher."
+        print_error "Python 3 is not installed. Please install Python 3.11 or higher."
         exit 1
     fi
 
     local python_version=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
-    local required_version="3.10"
+    local required_version="3.11"
 
-    if ! python3 -c "import sys; exit(0 if sys.version_info >= (3, 10) else 1)" 2>/dev/null; then
+    if ! python3 -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then
         print_error "Python ${python_version} detected. PhotoMap requires Python ${required_version} or higher."
         exit 1
     fi
@@ -235,7 +235,7 @@ main() {
 
     # Step 6: Install the CLIP model
     print_info "Downloading CLIP model..."
-    python -c "import clip; clip.load('ViT-B/32')"
+    python -c "from photomap.backend.encoders import import_openai_clip; import_openai_clip().load('ViT-B/32')"
 
     # Step 7: Create desktop launcher
     print_info "Creating desktop launcher..."

INSTALL/lib/windows.ps1

@@ -92,7 +92,7 @@ $version = python -c "import sys; print(f'{sys.version_info.major}.{sys.version_
 if (-not $version) {
     Install-Python "Could not determine Python version."
 }
-if ([version]$version -lt [version]"3.10" -or [version]$version -ge [version]"3.15") {
+if ([version]$version -lt [version]"3.11" -or [version]$version -ge [version]"3.15") {
     Install-Python "An incompatible Python version is installed."
 }
 
@@ -186,7 +186,7 @@ pip install "$PSScriptRoot\..\.."
 
 # 7. install the clip model
 Write-Host "Installing the CLIP model..."
-python -c "import clip; clip.load('ViT-B/32')"
+python -c "from photomap.backend.encoders import import_openai_clip; import_openai_clip().load('ViT-B/32')"
 
 # 8. Create a batch script to start the server
 $desktopPath = [Environment]::GetFolderPath('Desktop')

README.md

@@ -84,7 +84,7 @@ For PyPI, Docker, and manual install instructions, see the [Installation guide](
 
 ### Install from PyPI (command line)
 
-If you already have Python 3.10–3.14 and prefer the command line:
+If you already have Python 3.11–3.14 and prefer the command line:
 
 ```bash
 uv tool install photomapai --torch-backend auto   # or: pip install photomapai

README.zh-TW.md

@@ -98,7 +98,7 @@ PhotoMapAI 也支援多相簿管理、依時間瀏覽照片、簡潔的全螢幕
 
 ### 從 PyPI 安裝（命令列）
 
-如果你已經安裝 Python 3.10–3.14，並偏好使用命令列：
+如果你已經安裝 Python 3.11–3.14，並偏好使用命令列：
 
 ```bash
 uv tool install photomapai --torch-backend auto   # 或：pip install photomapai

docker/Dockerfile

@@ -17,7 +17,7 @@ RUN pip install --no-cache-dir --upgrade pip \
     && pip install --no-cache-dir --extra-index-url https://download.pytorch.org/whl/cpu . \
     && python /tmp/remove_bundled_ffmpeg.py \
     && rm /tmp/remove_bundled_ffmpeg.py
-RUN python -c "import clip; clip.load('ViT-B/32')"
+RUN python -c "from photomap.backend.encoders import import_openai_clip; import_openai_clip().load('ViT-B/32')"
 
 RUN rm -rf ./photomap ./build ./dist ./demo_images/photomap_index/
 

docker/Dockerfile.demo

@@ -15,7 +15,7 @@ RUN pip install --no-cache-dir --upgrade pip \
     && pip install --no-cache-dir --extra-index-url https://download.pytorch.org/whl/cpu . \
     && python /tmp/remove_bundled_ffmpeg.py \
     && rm /tmp/remove_bundled_ffmpeg.py
-RUN python -c "import clip; clip.load('ViT-B/32')"
+RUN python -c "from photomap.backend.encoders import import_openai_clip; import_openai_clip().load('ViT-B/32')"
 
 # Copy contents of demo_images and its config file
 COPY ./demo_images ./demo_images

docs/index.md

@@ -127,7 +127,7 @@ See the [Installation guide](installation.md) for PyPI, Docker, source, GPU over
 
 ### Install from the command line
 
-If you already have Python 3.10–3.14:
+If you already have Python 3.11–3.14:
 
 ```bash
 uv tool install photomapai --torch-backend auto   # or: pip install photomapai

docs/installation.md

@@ -71,7 +71,7 @@ To also remove the downloaded Python/libraries, run `photomap --uninstall` (path
 
 ## Alternative: install from PyPI
 
-If you are comfortable with the command line and already have Python 3.10–3.14, you can install the package directly. We recommend [uv](https://docs.astral.sh/uv/):
+If you are comfortable with the command line and already have Python 3.11–3.14, you can install the package directly. We recommend [uv](https://docs.astral.sh/uv/):
 
 ```bash
 uv tool install photomapai --torch-backend auto

docs/installation/python.md

@@ -1,12 +1,12 @@
 # Installing Python
 
-You will need Python version 3.10 or higher. To determine if Python is already installed on your system, open up a command shell (Powershell or COM shell on Windows, Terminal on MacOS/Linux) and type:
+You will need Python version 3.11 or higher. To determine if Python is already installed on your system, open up a command shell (Powershell or COM shell on Windows, Terminal on MacOS/Linux) and type:
 
 ```bash
 python -V
 ```
 
-If the command responds with `Python 3.10.0` or higher you are good to go. Otherwise, go to [www.python.org](http://www.python.org), follow the download link, and install the version appropriate for your hardware and operating system.
+If the command responds with `Python 3.11.0` or higher you are good to go. Otherwise, go to [www.python.org](http://www.python.org), follow the download link, and install the version appropriate for your hardware and operating system.
 
 **Important message for Windows users**: When you run the Python installer, the installer has a checkbox to add python to your PATH. Please be sure to enable this! If you miss it the first time, run the installer again and make sure the checkbox is checked. It is also recommended to check the box that turns off file path length limits, which might otherwise cause problems down the road.