@anonympins/fingerprint 0.7.0 → 0.7.2

package/src/php/Optimization/FunctionRegistry.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Registre pour exposer de manière contrôlée les fonctions de la bibliothèque d'optimisation.
+ * Registry to safely expose optimization library routines to task runners.
  */
 class FunctionRegistry
 {
@@ -13,17 +13,17 @@ class FunctionRegistry
     private static array $functions = [];
 
     /**
-     * Initialise le registre avec les fonctions disponibles.
+     * Initializes registry with built-in solvers and evaluators.
      */
     private static function initialize(): void
     {
         if (empty(self::$functions)) {
-            // Fonctions de "Scoring"
+            // Evaluators & Scoring Adapters
             self::$functions['tsp.calculateEnergy'] = [OptimizationUtils::class, 'evaluatePathDistance'];
             self::$functions['portfolio.calculateMetrics'] = [OptimizationOperators::class, 'calculatePortfolioMetrics'];
             self::$functions['facility.calculateEnergy'] = [OptimizationOperators::class, 'evaluateFacilityLocation'];
 
-            // Fonctions de "Résolution"
+            // Full Optimization Solvers
             self::$functions['tsp.solve'] = [OptimizationOperators::class, 'solveTSP'];
             self::$functions['portfolio.solve'] = [OptimizationOperators::class, 'solvePortfolio'];
             self::$functions['fraud.solve'] = [OptimizationOperators::class, 'solveFraudDetection'];
@@ -33,7 +33,7 @@ class FunctionRegistry
     }
 
     /**
-     * Récupère une fonction depuis le registre.
+     * Retrieves a function from the registry.
      */
     public static function get(string $name): ?callable
     {
@@ -41,7 +41,7 @@ class FunctionRegistry
         return self::$functions[$name] ?? null;
     }
     /**
-     * Enregistre une nouvelle fonction. Principalement pour les tests.
+     * Registers a custom function. Primarily intended for testing.
      * @internal
      * @param string $name
      * @param callable $function
@@ -54,7 +54,7 @@ class FunctionRegistry
     }
 
     /**
-     * Réinitialise le registre. Uniquement pour les tests.
+     * Resets function registry. Intended for testing.
      * @internal
      */
     public static function __internal_resetRegistry(): void

package/src/php/Optimization/Optimization.php

@@ -5,12 +5,12 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Bibliothèque d'algorithmes d'optimisation.
+ * Optimization algorithms library.
  */
 class Optimization
 {
     /**
-     * Génère un nombre flottant aléatoire cryptographiquement sûr entre 0 (inclus) et 1 (exclus).
+     * Generates a cryptographically secure random float in [0, 1).
      */
     private static function secureRandom(): float
     {
@@ -22,12 +22,12 @@ class Optimization
     }
 
     /**
-     * Algorithme génétique multi-objectifs (inspiré de NSGA-II).
+     * Multi-objective genetic algorithm (inspired by NSGA-II).
      * @param callable $createIndividual
      * @param callable $fitnessFunction
      * @param callable $crossover
      * @param callable $mutate
-     * @param array|null $currentConfig La configuration actuelle pour guider l'initialisation et la mutation.
+     * @param array|null $currentConfig Reference baseline configuration.
      * @param array $options
      * @return array<int, array{solution: mixed, objectives: array<float>}>
      */
@@ -35,8 +35,8 @@ class Optimization
         callable $createIndividual,
         callable $fitnessFunction,
         callable $crossover,
-        callable $mutate, // La fonction mutate doit maintenant accepter $currentConfig
-        ?array $currentConfig = null, // NOUVEAU: La configuration actuelle
+        callable $mutate, // The mutate function must accept $currentConfig
+        ?array $currentConfig = null, // Reference baseline configuration
         array $options = []
     ): array {
         $generations = $options['generations'] ?? 150;
@@ -53,14 +53,14 @@ class Optimization
         }
 
         for ($gen = 0; $gen < $generations; $gen++) {
-            // 1. Créer une population d'enfants
+            // 1. Generate offspring population
             $offspring = [];
             for ($i = 0; $i < $populationSize; $i++) {
                 $parent1 = $population[random_int(0, count($population) - 1)];
                 $parent2 = $population[random_int(0, count($population) - 1)];
                 $childIndividual = $crossover($parent1['individual'], $parent2['individual']);
                 if (self::secureRandom() < $mutationRate) {
-                    $childIndividual = $mutate($childIndividual, $currentConfig); // Passer $currentConfig à mutate
+                    $childIndividual = $mutate($childIndividual, $currentConfig);
                 }
                 $offspring[] = [
                     'individual' => $childIndividual,
@@ -68,20 +68,20 @@ class Optimization
                 ];
             }
 
-            // 2. Combiner parents et enfants
+            // 2. Combine parent and offspring populations
             $combinedPopulation = array_merge($population, $offspring);
 
-            // 3. Trier la population combinée en fronts
+            // 3. Sort into non-dominated Pareto fronts
             $fronts = self::nonDominatedSort($combinedPopulation);
 
-            // 4. Construire la nouvelle population
+            // 4. Build next generation
             $newPopulation = [];
             foreach ($fronts as $front) {
                 if (count($newPopulation) + count($front) <= $populationSize) {
                     $newPopulation = array_merge($newPopulation, $front);
                 } else {
                     self::calculateCrowdingDistance($front);
-                    // Trier par distance décroissante
+                    // Sort by crowding distance descending
                     usort($front, fn ($a, $b) => $b['crowdingDistance'] <=> $a['crowdingDistance']);
                     $remaining = $populationSize - count($newPopulation);
                     $newPopulation = array_merge($newPopulation, array_slice($front, 0, $remaining));
@@ -91,11 +91,11 @@ class Optimization
             $population = $newPopulation;
         }
 
-        // Retourner le premier front de la population finale
+        // Return the first non-dominated front of the final population
         $finalFronts = self::nonDominatedSort($population);
         $bestFront = $finalFronts[0] ?? [];
 
-        // Filtrer pour ne garder que les solutions avec des objectifs uniques
+        // Deduplicate solutions with identical objective scores
         $uniqueSolutionsMap = [];
         foreach ($bestFront as $p) {
             $key = json_encode($p['objectives']);
@@ -110,7 +110,7 @@ class Optimization
     }
 
     /**
-     * Détermine si la solution A domine la solution B.
+     * Determines whether solution A Pareto-dominates solution B (minimization).
      * @param array<float> $objectivesA
      * @param array<float> $objectivesB
      */
@@ -119,17 +119,17 @@ class Optimization
         $aIsBetterInOne = false;
         for ($i = 0; $i < count($objectivesA); $i++) {
             if ($objectivesA[$i] > $objectivesB[$i]) {
-                return false; // A est pire sur au moins un objectif
+                return false; // A is worse on at least one objective
             }
             if ($objectivesA[$i] < $objectivesB[$i]) {
-                $aIsBetterInOne = true; // A est strictement meilleur sur au moins un
+                $aIsBetterInOne = true; // A is strictly better on at least one objective
             }
         }
         return $aIsBetterInOne;
     }
 
     /**
-     * Trie une population en fronts de Pareto non-dominés.
+     * Sorts population into non-dominated Pareto fronts (NSGA-II).
      * @param array<int, array> &$populationWithObjectives
      * @return array<int, array>
      */
@@ -182,7 +182,7 @@ class Optimization
     }
 
     /**
-     * Calcule la distance de promiscuité (crowding distance) pour un front.
+     * Computes crowding distance for a front to preserve diversity.
      * @param array<int, array> &$front
      */
     private static function calculateCrowdingDistance(array &$front): void
@@ -197,13 +197,13 @@ class Optimization
         }
 
         for ($i = 0; $i < $numObjectives; $i++) {
-            // Trier le front par l'objectif courant
+            // Sort front by current objective
             usort($front, fn ($a, $b) => $a['objectives'][$i] <=> $b['objectives'][$i]);
 
             $minObj = $front[0]['objectives'][$i];
             $maxObj = $front[$l - 1]['objectives'][$i];
 
-            // Les solutions aux extrémités ont une distance infinie
+            // Boundary solutions receive infinite distance to encourage spread
             $front[0]['crowdingDistance'] = INF;
             $front[$l - 1]['crowdingDistance'] = INF;
 
@@ -218,11 +218,11 @@ class Optimization
     }
 
     /**
-     * Calcule la déviation d'une série de chiffres par rapport à la loi de Benford.
-     * @public
+     * Calculates deviation from Benford's Law distribution.
+     * Elevated values indicate synthetic or automated intervals.
      * @param array<int|float> $numbers
      */
-    public static function benfordTest(array $numbers): float // Rendre la méthode publique et statique
+    public static function benfordTest(array $numbers): float // Public static helper for digit distribution test
     {
         $counts = array_fill(1, 9, 0);
         $validCount = 0;

package/src/php/Optimization/OptimizationOperators.php

@@ -5,14 +5,14 @@ declare(strict_types=1);
 namespace Anonympins\Fingerprint\Optimization;
 
 /**
- * Opérateurs pour les problèmes d'optimisation.
+ * Operators and objective function factories for optimization problems.
  */
 class OptimizationOperators
 {
     /**
-     * Crée une fonction de sélection par tournoi pour un algorithme génétique.
-     * @param array $options Options pour le tournoi.
-     * @return callable Une fonction de sélection.
+     * Creates a tournament selection operator for genetic algorithms.
+     * @param array $options Tournament configuration options.
+     * @return callable Selection operator function.
      */
     public static function createTournamentSelection(array $options = []): callable
     {
@@ -37,7 +37,7 @@ class OptimizationOperators
     }
 
     /**
-     * Génère un nombre flottant aléatoire cryptographiquement sûr entre 0 (inclus) et 1 (exclus).
+     * Generates a cryptographically secure random float in [0, 1).
      */
     private static function secureRandom(): float
     {
@@ -49,7 +49,7 @@ class OptimizationOperators
     }
 
     /**
-     * Évalue un portefeuille pour un payload donné.
+     * Evaluates a portfolio for a given payload.
      * 
      * @param array $weights
      * @param array $payload
@@ -62,22 +62,21 @@ class OptimizationOperators
     }
 
     /**
-     * Crée un évaluateur pour l'optimisation de portefeuille.
+     * Creates a portfolio allocation evaluator.
      * @param array $config
      * @return callable
      */
     public static function createPortfolioAllocator(array $config): callable
     {
-        // Cette fonction est un placeholder. Une implémentation complète nécessiterait
-        // une logique de calcul de rendement et de volatilité de portefeuille.
+        // Baseline portfolio evaluator minimizing negative expected return
         return function (array $weights) use ($config): float {
-            // Minimiser le rendement négatif (donc maximiser le rendement)
+            // Minimize negative return (maximizes positive return)
             return -array_sum($weights);
         };
     }
 
     /**
-     * Crée un évaluateur pour l'auto-tuning complet de la configuration de sécurité.
+     * Creates an evaluator for full security configuration auto-tuning.
      * @param array $context
      * @return callable
      */
@@ -145,6 +144,7 @@ class OptimizationOperators
             ];
 
             // 1. Évaluation sur les logs de trafic réels
+            // 1. Evaluate on real traffic logs
             foreach ($trafficData as $log) {
                 $weight = (float)($log['weight'] ?? 1.0);
                 $confidence = ($confidenceWeights[$log['type'] ?? ''] ?? 1.0) * $weight;
@@ -206,6 +206,7 @@ class OptimizationOperators
             }
 
             // 3. Pénalité de dérive d'échelle (L2 Regularization par rapport au profil d'origine)
+            // 3. Scale drift penalty (L2 regularization against baseline profile)
             $regularizationPenalty = 0.0;
             if ($currentConfig && isset($currentConfig['weights'])) {
                 foreach ($config['weights'] as $key => $val) {
@@ -215,6 +216,7 @@ class OptimizationOperators
             }
 
             // 4. Maximisation de la marge
+            // 4. Margin separation maximization
             $marginOverlap = max(0.0, $maxHumanScore - $minBotScore);
             $marginPenalty = $marginOverlap / 100.0;
 
@@ -226,7 +228,7 @@ class OptimizationOperators
     }
 
     /**
-     * Résout le problème de l'auto-tuning complet de la configuration de sécurité.
+     * Solves end-to-end security configuration auto-tuning.
      * @param array $context
      * @param array $options
      * @return array
@@ -256,7 +258,7 @@ class OptimizationOperators
                 if (isset($config[$section]) && is_array($config[$section])) {
                     foreach ($config[$section] as $k => $v) {
                         if (is_numeric($v)) {
-                            $randomVariation = 1.0 + (self::secureRandom() - 0.5) * 0.5; // Variation de +/- 25%
+                            $randomVariation = 1.0 + (self::secureRandom() - 0.5) * 0.5; // +/- 25% variation
                             $ind[$section][$k] = $v * $randomVariation;
                         } else {
                             $ind[$section][$k] = $v;
@@ -330,7 +332,7 @@ class OptimizationOperators
     }
 
     /**
-     * Crée un évaluateur pour trouver les seuils de détection de fraude optimaux.
+     * Creates an evaluator to find optimal fraud detection thresholds.
      * @param array $context
      * @return callable
      */
@@ -374,7 +376,7 @@ class OptimizationOperators
     }
 
     /**
-     * Résout le problème de la détection de fraude.
+     * Solves fraud detection threshold optimization.
      * @param array $context
      * @param array $options
      * @return array
@@ -411,19 +413,18 @@ class OptimizationOperators
     }
 
     /**
-     * Placeholder pour le solveur TSP.
+     * TSP solver baseline implementation.
      * @param array $cities
      * @param array $options
      * @return array
      */
     public static function solveTSP(array $cities, array $options = []): array
     {
-        // Implémentation factice pour la complétude
         return ['solution' => array_keys($cities), 'energy' => 100];
     }
 
     /**
-     * Placeholder pour le solveur de portefeuille.
+     * Portfolio allocator baseline implementation.
      * @param array $assets
      * @param float $maxVolatility
      * @param array $options
@@ -431,7 +432,6 @@ class OptimizationOperators
      */
     public static function solvePortfolio(array $assets, float $maxVolatility, array $options = []): array
     {
-        // Implémentation factice pour la complétude
         return ['solution' => array_fill(0, count($assets), 1 / count($assets)), 'fitness' => -0.1];
     }
 
@@ -440,7 +440,7 @@ class OptimizationOperators
         $fixedCostPerFacility = $options['fixedCostPerFacility'] ?? 0;
         $initialTemperature = $options['initialTemperature'] ?? 100000.0;
         $coolingRate = $options['coolingRate'] ?? 0.999;
-        $maxIterations = $options['maxIterations'] ?? 15000; // Borne raisonnable pour PHP
+        $maxIterations = $options['maxIterations'] ?? 15000;
 
         $evaluator = function (array $facilities) use ($customers, $fixedCostPerFacility): float {
             $totalConnectionCost = 0.0;
@@ -473,6 +473,7 @@ class OptimizationOperators
         };
 
         // Génération d'une solution initiale aléatoire
+        // Random initial placement
         $currentSolution = [];
         for ($i = 0; $i < $numFacilities; $i++) {
             $currentSolution[] = [
@@ -509,12 +510,12 @@ class OptimizationOperators
     }
 
     /**
-     * Évalue de manière indépendante l'énergie d'une solution de placement d'infrastructures.
-     * Appelée par le serveur pour valider les calculs soumis par le client.
+     * Independently evaluates total cost of a facility placement proposal.
+     * Invoked server-side to verify client-submitted solutions.
      * 
-     * @param array $facilities Liste des positions proposées par le client.
-     * @param array $payload Configuration initiale contenant les clients et les coûts fixes.
-     * @return float Le coût total vérifié.
+     * @param array $facilities Facility coordinates proposed by client.
+     * @param array $payload Base payload containing customer coordinates and fixed costs.
+     * @return float Verified total connection and maintenance cost.
      */
     public static function evaluateFacilityLocation(array $facilities, array $payload): float
     {

package/src/php/Optimization/ProblemInitializers.php

@@ -1,53 +1,53 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Anonympins\Fingerprint\Optimization;
-
-/**
- * Fonctions pour générer dynamiquement les données d'un problème.
- */
-class ProblemInitializers
-{
-    /** @var array<string, callable> */
-    private static array $initializers = [];
-
-    private static function initialize(): void
-    {
-        if (empty(self::$initializers)) {
-            self::$initializers['generate:randomPoints'] = function (array $params): array {
-                $count = $params['count'] ?? 0;
-                $bounds = $params['bounds'] ?? ['x' => 1000, 'y' => 1000];
-                if (!is_numeric($count)) return [];
-                $points = [];
-                for ($i = 0; $i < $count; $i++) {
-                    $points[] = [
-                        'x' => mt_rand() / mt_getrandmax() * $bounds['x'],
-                        'y' => mt_rand() / mt_getrandmax() * $bounds['y']
-                    ];
-                }
-                return $points;
-            };
-
-            self::$initializers['generate:randomAssets'] = function (array $params): array {
-                $count = $params['count'] ?? 0;
-                if (!is_numeric($count)) return [];
-                $assets = [];
-                for ($i = 0; $i < $count; $i++) {
-                    $assets[] = [
-                        'name' => 'Asset ' . ($i + 1),
-                        'expectedReturn' => mt_rand() / mt_getrandmax() * 0.2,
-                        'volatility' => 0.1 + mt_rand() / mt_getrandmax() * 0.3
-                    ];
-                }
-                return $assets;
-            };
-        }
-    }
-
-    public static function get(string $name): ?callable
-    {
-        self::initialize();
-        return self::$initializers[$name] ?? null;
-    }
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint\Optimization;
+
+/**
+ * Generators for dynamically seeding problem instance datasets.
+ */
+class ProblemInitializers
+{
+    /** @var array<string, callable> */
+    private static array $initializers = [];
+
+    private static function initialize(): void
+    {
+        if (empty(self::$initializers)) {
+            self::$initializers['generate:randomPoints'] = function (array $params): array {
+                $count = $params['count'] ?? 0;
+                $bounds = $params['bounds'] ?? ['x' => 1000, 'y' => 1000];
+                if (!is_numeric($count)) return [];
+                $points = [];
+                for ($i = 0; $i < $count; $i++) {
+                    $points[] = [
+                        'x' => mt_rand() / mt_getrandmax() * $bounds['x'],
+                        'y' => mt_rand() / mt_getrandmax() * $bounds['y']
+                    ];
+                }
+                return $points;
+            };
+
+            self::$initializers['generate:randomAssets'] = function (array $params): array {
+                $count = $params['count'] ?? 0;
+                if (!is_numeric($count)) return [];
+                $assets = [];
+                for ($i = 0; $i < $count; $i++) {
+                    $assets[] = [
+                        'name' => 'Asset ' . ($i + 1),
+                        'expectedReturn' => mt_rand() / mt_getrandmax() * 0.2,
+                        'volatility' => 0.1 + mt_rand() / mt_getrandmax() * 0.3
+                    ];
+                }
+                return $assets;
+            };
+        }
+    }
+
+    public static function get(string $name): ?callable
+    {
+        self::initialize();
+        return self::$initializers[$name] ?? null;
+    }
 }