Facial Recognition - part 1

.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/dependency-review.yml

@@ -25,3 +25,8 @@ jobs:
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.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/php_tests.yml

@@ -33,6 +33,7 @@ jobs:
           - Webshop
           - ImageProcessing
           - Precomputing
+          - AssistedVision
         exclude:
         # Some skips to reduce the number of runs
           - php-version: 8.4
@@ -45,6 +46,8 @@ jobs:
             test-suite: ImageProcessing
           - php-version: 8.4
             test-suite: Precomputing
+          - php-version: 8.4
+            test-suite: AssistedVision
     # Service containers to run with `container-job`
     services:
       # Label used to access the service container

.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

@@ -154,6 +154,9 @@ test_ImageProcessing:
 test_precomputing:
 	vendor/bin/phpunit --testsuite Precomputing --stop-on-failure --stop-on-error --no-coverage --log-junit report_precomputing.xml
 
+test_assisted_vision:
+	vendor/bin/phpunit --testsuite AssistedVision --stop-on-failure --stop-on-error --no-coverage --log-junit report_assisted_vision.xml
+
 test_v2:
 	vendor/bin/phpunit --testsuite Feature_v2 --stop-on-failure --stop-on-error --no-coverage --log-junit report_v2.xml
 

app/Actions/Albums/Flow.php

@@ -118,7 +118,7 @@ private function getQuery(Album|null $base, bool $with_relations): AlbumBuilder
 				'min_privilege_cover', 'min_privilege_cover.size_variants',
 				'statistics',
 				'photos',
-				'photos.statistics', 'photos.size_variants', 'photos.palette', 'photos.tags', 'photos.rating']);
+				'photos.statistics', 'photos.size_variants', 'photos.palette', 'photos.tags', 'photos.rating', 'photos.faces', 'photos.faces.person', ]);
 		}
 
 		// Only join what we need for ordering.

app/Actions/Diagnostics/Errors.php

@@ -9,6 +9,8 @@
 namespace App\Actions\Diagnostics;
 
 use App\Actions\Diagnostics\Pipes\Checks\AdminUserExistsCheck;
+use App\Actions\Diagnostics\Pipes\Checks\AiVisionServiceCheck;
+use App\Actions\Diagnostics\Pipes\Checks\AiVisionServiceConfigCheck;
 use App\Actions\Diagnostics\Pipes\Checks\AppUrlMatchCheck;
 use App\Actions\Diagnostics\Pipes\Checks\AuthDisabledCheck;
 use App\Actions\Diagnostics\Pipes\Checks\BasicPermissionCheck;
@@ -76,6 +78,8 @@ class Errors
 		SupporterCheck::class,
 		ImagickPdfCheck::class,
 		WatermarkerEnabledCheck::class,
+		AiVisionServiceCheck::class,
+		AiVisionServiceConfigCheck::class,
 		StatisticsIntegrityCheck::class,
 		WebshopCheck::class,
 		SecurityAdvisoriesCheck::class,

app/Actions/Diagnostics/Pipes/Checks/AiVisionServiceCheck.php

@@ -0,0 +1,116 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Actions\Diagnostics\Pipes\Checks;
+
+use App\Contracts\DiagnosticPipe;
+use App\DTO\DiagnosticData;
+use App\Repositories\ConfigManager;
+use App\Services\Image\FacialRecognitionService;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Check if the AI Vision service is properly configured and reachable.
+ */
+class AiVisionServiceCheck implements DiagnosticPipe
+{
+	public function __construct(
+		protected readonly ConfigManager $config_manager,
+		protected readonly FacialRecognitionService $facial_recognition_service,
+	) {
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function handle(array &$data, \Closure $next): array
+	{
+		if (!Schema::hasTable('configs')) {
+			return $next($data);
+		}
+
+		// Skip check if AI Vision is disabled
+		if (!$this->config_manager->getValueAsBool('ai_vision_enabled')) {
+			return $next($data);
+		}
+
+		if (!$this->facial_recognition_service->isConfigured()) {
+			$data[] = DiagnosticData::error(
+				'AI Vision: Service URL is not configured. Set AI_VISION_FACE_URL in your .env file.',
+				self::class,
+				[]
+			);
+
+			return $next($data);
+		}
+
+		$this->checkServiceHealth($data);
+
+		return $next($data);
+	}
+
+	/**
+	 * Check if the AI Vision service health endpoint is reachable and returns proper data.
+	 *
+	 * @param DiagnosticData[] &$data
+	 *
+	 * @return void
+	 */
+	private function checkServiceHealth(array &$data): void
+	{
+		$service_url = config('features.ai-vision-service.face-url', '');
+
+		try {
+			$response = $this->facial_recognition_service->checkHealthRaw(5);
+
+			if (!$response->successful()) {
+				$data[] = DiagnosticData::error(
+					'AI Vision: Service health check failed with status ' . $response->status() . '. The service may be offline or unreachable.',
+					self::class,
+					['Check that the AI Vision service is running at: ' . $service_url]
+				);
+
+				return;
+			}
+
+			$health_data = $response->json();
+			if (!is_array($health_data) || !isset($health_data['status'])) {
+				$data[] = DiagnosticData::error(
+					'AI Vision: Service health endpoint returned invalid response format. Expected JSON with "status" field.',
+					self::class,
+					['Response: ' . $response->body()]
+				);
+
+				return;
+			}
+
+			if ($health_data['status'] !== 'ok' && $health_data['status'] !== 'healthy') {
+				$data[] = DiagnosticData::warn(
+					'AI Vision: Service reported unhealthy status: ' . $health_data['status'],
+					self::class,
+					[]
+				);
+			}
+		} catch (ConnectionException $e) {
+			$data[] = DiagnosticData::error(
+				'AI Vision: Could not connect to service at ' . rtrim($service_url, '/') . '/health',
+				self::class,
+				['Check that the AI Vision service is running and the URL is correct.', $e->getMessage()]
+			);
+		} catch (\Exception $e) {
+			// @codeCoverageIgnoreStart
+			$data[] = DiagnosticData::error(
+				'AI Vision: Service health check failed with error: ' . $e->getMessage(),
+				self::class,
+				[]
+			);
+			// @codeCoverageIgnoreEnd
+		}
+	}
+}

app/Actions/Diagnostics/Pipes/Checks/AiVisionServiceConfigCheck.php

@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Actions\Diagnostics\Pipes\Checks;
+
+use App\Contracts\DiagnosticPipe;
+use App\DTO\DiagnosticData;
+use App\Repositories\ConfigManager;
+use App\Services\Image\FacialRecognitionService;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * In debug mode, expose the AI Vision runtime configuration in diagnostics.
+ */
+class AiVisionServiceConfigCheck implements DiagnosticPipe
+{
+	public function __construct(
+		protected readonly ConfigManager $config_manager,
+		protected readonly FacialRecognitionService $facial_recognition_service,
+	) {
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function handle(array &$data, \Closure $next): array
+	{
+		if (config('app.debug') !== true) {
+			return $next($data);
+		}
+
+		if (!Schema::hasTable('configs')) {
+			return $next($data);
+		}
+
+		if ($this->config_manager->getValueAsBool('ai_vision_enabled') !== true) {
+			return $next($data);
+		}
+
+		if (!$this->facial_recognition_service->isConfigured()) {
+			return $next($data);
+		}
+
+		$configuration = $this->facial_recognition_service->getConfiguration();
+		if ($configuration === null) {
+			$data[] = DiagnosticData::warn(
+				'AI Vision: Could not fetch runtime configuration from the service while APP_DEBUG is enabled.',
+				self::class,
+				[]
+			);
+
+			return $next($data);
+		}
+
+		$details = [];
+		foreach ($configuration as $key => $value) {
+			$details[] = $key . ': ' . $value;
+		}
+
+		$data[] = DiagnosticData::info(
+			'AI Vision: Runtime configuration from service (debug mode).',
+			self::class,
+			$details
+		);
+
+		return $next($data);
+	}
+}

app/Actions/Photo/Create.php

@@ -206,6 +206,7 @@ private function handleStandalone(InitDTO $init_dto): Photo
 			Shared\GeodecodeLocation::class,
 			Shared\ExtractColourPalette::class,
 			Shared\NotifyAlbums::class,
+			Standalone\AutoScanFacesOnUpload::class,
 		];
 
 		return $this->executePipeOnDTO($pipes, $dto)->getPhoto();

app/Actions/Photo/Pipes/Standalone/AutoScanFacesOnUpload.php

@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Actions\Photo\Pipes\Standalone;
+
+use App\Contracts\PhotoCreate\StandalonePipe;
+use App\DTO\PhotoCreate\StandaloneDTO;
+use App\Jobs\DispatchFaceScanJob;
+use App\Repositories\ConfigManager;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Automatically trigger face scanning when a photo is uploaded,
+ * if the AI Vision face scanning feature is enabled.
+ */
+class AutoScanFacesOnUpload implements StandalonePipe
+{
+	public function __construct(
+		protected readonly ConfigManager $config_manager,
+	) {
+	}
+
+	public function handle(StandaloneDTO $state, \Closure $next): StandaloneDTO
+	{
+		// Process through the rest of the pipeline first
+		$state = $next($state);
+
+		if ($state->photo->isPhoto() === false) {
+			// If this is not a photo (e.g., a video), we skip face scanning
+			return $state;
+		}
+
+		// Check if AI vision is enabled
+		if ($this->config_manager->getValueAsString('ai_vision_enabled') !== '1') {
+			return $state;
+		}
+
+		// Check if face scanning is enabled
+		if ($this->config_manager->getValueAsString('ai_vision_face_enabled') !== '1') {
+			return $state;
+		}
+
+		// Dispatch face scanning job for the uploaded photo
+		Log::info("AutoScanFacesOnUpload: dispatching face scan for photo {$state->photo->id}.");
+		DispatchFaceScanJob::dispatch($state->photo->id);
+
+		return $state;
+	}
+}