Implement python

.dockerignore

@@ -48,6 +48,8 @@ vite/*
 secrets/*
 # Local testing @ildyria
 public/uploads-bck/*
+public/uploads/*
+*.sql
 
 # Node
 node_modules/
@@ -56,8 +58,12 @@ npm-debug.log
 # Mapping for database and config used by docker compose
 lychee/*
 
+# Python
+ai-vision-service/*
+
 # Laravel
 /storage/logs/*
+/storage/tmp/*
 /storage/framework/cache/*
 /storage/framework/sessions/*
 /storage/framework/views/*

.github/dependabot.yml

@@ -18,9 +18,6 @@ updates:
         dependency-type: "production"
       development-dependencies:
         dependency-type: "development"
-    ignore:
-      - dependency-name: "typescript"
-        versions: [ ">=6.0.0" ]
 
   - package-ecosystem: composer
     directory: /

.github/workflows/CICD.yml

@@ -11,11 +11,13 @@ on:
       - '**/*.md'
       - 'public/dist/*.js'
       - 'public/dist/**/*.js'
+      - 'ai-vision-service/**'
   pull_request:
     paths-ignore:
       - '**/*.md'
       - 'public/dist/*.js'
       - 'public/dist/**/*.js'
+      - 'ai-vision-service/**'
   # Allow manually triggering the workflow.
   workflow_dispatch:
 

.github/workflows/dependency-review.yml

@@ -25,3 +25,8 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        with:
+          # No fix available yet
+          # Note that the model is directly baked into the inage
+          # So the risk is limited.
+          allow-ghsas: GHSA-hqmj-h5c6-369m

.github/workflows/python_ai_vision_face_recognition.yml

@@ -0,0 +1,154 @@
+name: Python AI Vision Service for face recognition
+
+on:
+  push:
+    branches:
+      - master
+      - assisted-vision
+    paths:
+      - 'ai-vision-service/face-recognition/**'
+  pull_request:
+    paths:
+      - 'ai-vision-service/face-recognition/**'
+  workflow_dispatch:
+
+# Declare default permissions as read only.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !contains(github.ref, 'master') && !startsWith(github.ref, 'refs/tags/') }}
+
+defaults:
+  run:
+    working-directory: ai-vision-service/face-recognition
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint – formatting and style
+  # ---------------------------------------------------------------------------
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+
+      - name: Install dev dependencies
+        run: uv sync --frozen
+
+      - name: Check formatting
+        run: uv run ruff format --check app/ tests/
+
+      - name: Lint
+        run: uv run ruff check app/ tests/
+
+  # ---------------------------------------------------------------------------
+  # Type check
+  # ---------------------------------------------------------------------------
+  typecheck:
+    name: Type check (ty)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+
+      - name: Install dev dependencies
+        run: uv sync --frozen
+
+      - name: Type check
+        run: uv run ty check app/
+
+  # ---------------------------------------------------------------------------
+  # Test matrix – Python 3.13 and 3.14
+  # ---------------------------------------------------------------------------
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest --cov=app --cov-report=xml -v
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        with:
+          files: ai-vision-service/face-recognition/coverage.xml
+          flags: ai-vision-service/face-recognition
+        continue-on-error: true
+
+  # ---------------------------------------------------------------------------
+  # Docker build verification
+  # ---------------------------------------------------------------------------
+  docker-build:
+    name: Docker build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd #v4.0.0
+
+      - name: Build Docker image (no model bake in CI to save time)
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        with:
+          context: ai-vision-service/face-recognition
+          push: false
+          load: true
+          tags: lychee-ai-vision:ci
+          # Override the model-bake step by targeting the builder stage
+          # to avoid downloading 300MB of model weights in CI.
+          target: builder
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -38,6 +38,8 @@ clover.xml
 .NO_AUTO_COMPOSER_MIGRATE
 storage/bootstrap/cache/*
 storage/image-jobs/*
+**/__pycache__/**
+.coverage
 
 # used by Vite
 public/hot

Makefile

@@ -166,6 +166,9 @@ class-leak:
 docker-build:
 	docker build -t lychee-frankenphp .
 
+docker-build-legacy:
+	docker build -t lychee-frankenphp -f Dockerfile-legacy .
+
 docker-build-no-cache:
 	docker build -t lychee-frankenphp . --no-cache
 

ai-vision-service/face-recognition/.insightface/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

ai-vision-service/face-recognition/Dockerfile

@@ -0,0 +1,54 @@
+# Multi-stage build: keep the runtime image lean.
+
+# ---------------------------------------------------------------------------
+# Stage 1 – builder: install dependencies and bake the model weights.
+# ---------------------------------------------------------------------------
+FROM python:3.13-slim@sha256:739e7213785e88c0f702dcdc12c0973afcbd606dbf021a589cab77d6b00b579d AS builder
+
+# Install uv from the official image.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Build tools required to compile insightface's Cython extension (mesh_core_cython).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        g++ \
+        libgl1 \
+        libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install dependencies only (no source code) so layer cache is reused when
+# only application code changes.
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --frozen --no-dev
+
+# Bake buffalo_l model weights into the image at build time (~300 MB download).
+# The resulting image is ~1 GB larger but starts instantly and works in
+# airgapped environments. Model updates require an image rebuild.
+RUN uv run python -c \
+    "from insightface.app import FaceAnalysis; \
+     a = FaceAnalysis(name='buffalo_l', root='/root/.insightface', providers=['CPUExecutionProvider']); \
+     a.prepare(ctx_id=-1); \
+     print('buffalo_l model downloaded.')"
+
+# ---------------------------------------------------------------------------
+# Stage 2 – runtime: copy only what's needed to run.
+# ---------------------------------------------------------------------------
+FROM python:3.13-slim@sha256:739e7213785e88c0f702dcdc12c0973afcbd606dbf021a589cab77d6b00b579d AS runtime
+
+WORKDIR /app
+
+# Copy the pre-built virtualenv and baked model weights from the builder stage.
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /root/.insightface /root/.insightface
+
+# Copy application source.
+COPY app/ ./app/
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 8000
+
+# Use a shell-form CMD so that the ${VISION_FACE_WORKERS:-1} variable is
+# expanded at container startup, not at image build time.
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers ${VISION_FACE_WORKERS:-1}"]