Add comprehensive type hints to neural network optimizers

- Add type hints to all internal helper functions as required by algorithms-keeper bot
- Fix function signatures for _adagrad_update_recursive, _adam_update_recursive, _nag_update_recursive, and _check_shapes_and_get_velocity
- Add type hints to example functions: rosenbrock, gradient_f, f
- Update imports to include Tuple type where needed
- Maintain all existing functionality with 58 passing doctests
- Resolve all algorithms-keeper bot feedback for PR approval

Author: shretadas

neural_network/optimizers/adagrad.py

@@ -119,46 +119,50 @@ def update(
             ValueError: If parameters and gradients have different shapes
         """
 
-        def _adagrad_update_recursive(params, grads, acc_grads):
+        def _adagrad_update_recursive(
+            parameters: Union[float, List[Union[float, List[float]]]], 
+            gradients: Union[float, List[Union[float, List[float]]]], 
+            accumulated_gradients: Union[float, List[Union[float, List[float]]]]
+        ) -> tuple[Union[float, List[Union[float, List[float]]]], Union[float, List[Union[float, List[float]]]]]:
             # Handle scalar case
-            if isinstance(params, (int, float)):
-                if not isinstance(grads, (int, float)):
+            if isinstance(parameters, (int, float)):
+                if not isinstance(gradients, (int, float)):
                     raise ValueError(
                         "Shape mismatch: parameter is scalar but gradient is not"
                     )
 
-                if acc_grads is None:
-                    acc_grads = 0.0
+                if accumulated_gradients is None:
+                    accumulated_gradients = 0.0
 
                 # Accumulate squared gradients: G = G + g^2
-                new_acc_grads = acc_grads + grads * grads
+                new_acc_grads = accumulated_gradients + gradients * gradients
 
                 # Adaptive learning rate: α / √(G + ε)
                 adaptive_lr = self.learning_rate / math.sqrt(
                     new_acc_grads + self.epsilon
                 )
 
                 # Parameter update: θ = θ - adaptive_lr * g
-                new_param = params - adaptive_lr * grads
+                new_param = parameters - adaptive_lr * gradients
 
                 return new_param, new_acc_grads
 
             # Handle list case
-            if len(params) != len(grads):
+            if len(parameters) != len(gradients):
                 raise ValueError(
-                    f"Shape mismatch: parameters length {len(params)} vs "
-                    f"gradients length {len(grads)}"
+                    f"Shape mismatch: parameters length {len(parameters)} vs "
+                    f"gradients length {len(gradients)}"
                 )
 
-            if acc_grads is None:
-                acc_grads = [None] * len(params)
-            elif len(acc_grads) != len(params):
+            if accumulated_gradients is None:
+                accumulated_gradients = [None] * len(parameters)
+            elif len(accumulated_gradients) != len(parameters):
                 raise ValueError("Accumulated gradients shape mismatch")
 
             new_params = []
             new_acc_grads = []
 
-            for i, (p, g, ag) in enumerate(zip(params, grads, acc_grads)):
+            for i, (p, g, ag) in enumerate(zip(parameters, gradients, accumulated_gradients)):
                 if isinstance(p, list) and isinstance(g, list):
                     # Recursive case for nested lists
                     new_p, new_ag = _adagrad_update_recursive(p, g, ag)

neural_network/optimizers/adam.py

@@ -16,7 +16,7 @@
 from __future__ import annotations
 
 import math
-from typing import List, Union
+from typing import List, Union, Tuple
 
 from .base_optimizer import BaseOptimizer
 
@@ -161,45 +161,50 @@ def update(
         bias_correction1 = 1 - self.beta1**self._time_step
         bias_correction2 = 1 - self.beta2**self._time_step
 
-        def _adam_update_recursive(params, grads, first_moment, second_moment):
+        def _adam_update_recursive(
+            parameters: Union[float, List],
+            gradients: Union[float, List],
+            first_moment: Union[float, List],
+            second_moment: Union[float, List]
+        ) -> Tuple[Union[float, List], Union[float, List], Union[float, List]]:
             # Handle scalar case
-            if isinstance(params, (int, float)):
-                if not isinstance(grads, (int, float)):
+            if isinstance(parameters, (int, float)):
+                if not isinstance(gradients, (int, float)):
                     raise ValueError(
                         "Shape mismatch: parameter is scalar but gradient is not"
                     )
 
                 # Update first moment: m = β₁ * m + (1-β₁) * g
-                new_first_moment = self.beta1 * first_moment + (1 - self.beta1) * grads
+                new_first_moment = self.beta1 * first_moment + (1 - self.beta1) * gradients
 
                 # Update second moment: v = β₂ * v + (1-β₂) * g²
                 new_second_moment = self.beta2 * second_moment + (1 - self.beta2) * (
-                    grads * grads
+                    gradients * gradients
                 )
 
                 # Bias-corrected moments
                 m_hat = new_first_moment / bias_correction1
                 v_hat = new_second_moment / bias_correction2
 
                 # Parameter update: θ = θ - α * m̂ / (√v̂ + ε)
-                new_param = params - self.learning_rate * m_hat / (
+                new_param = parameters - self.learning_rate * m_hat / (
                     math.sqrt(v_hat) + self.epsilon
                 )
 
                 return new_param, new_first_moment, new_second_moment
 
             # Handle list case
-            if len(params) != len(grads):
+            if len(parameters) != len(gradients):
                 raise ValueError(
-                    f"Shape mismatch: parameters length {len(params)} vs "
-                    f"gradients length {len(grads)}"
+                    f"Shape mismatch: parameters length {len(parameters)} vs "
+                    f"gradients length {len(gradients)}"
                 )
 
             new_params = []
             new_first_moments = []
             new_second_moments = []
 
-            for p, g, m1, m2 in zip(params, grads, first_moment, second_moment):
+            for p, g, m1, m2 in zip(parameters, gradients, first_moment, second_moment):
                 if isinstance(p, list) and isinstance(g, list):
                     # Recursive case for nested lists
                     new_p, new_m1, new_m2 = _adam_update_recursive(p, g, m1, m2)
@@ -309,11 +314,11 @@ def __str__(self) -> str:
     x_adagrad = [-1.0, 1.0]
     x_adam = [-1.0, 1.0]
 
-    def rosenbrock(x, y):
+    def rosenbrock(x: float, y: float) -> float:
         """Rosenbrock function: f(x,y) = 100*(y-x²)² + (1-x)²"""
         return 100 * (y - x * x) ** 2 + (1 - x) ** 2
 
-    def rosenbrock_gradient(x, y):
+    def rosenbrock_gradient(x: float, y: float) -> List[float]:
         """Gradient of Rosenbrock function"""
         df_dx = -400 * x * (y - x * x) - 2 * (1 - x)
         df_dy = 200 * (y - x * x)

neural_network/optimizers/momentum_sgd.py

@@ -15,7 +15,7 @@
 
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Union, Tuple
 
 from .base_optimizer import BaseOptimizer
 
@@ -115,40 +115,44 @@ def update(
             ValueError: If parameters and gradients have different shapes
         """
 
-        def _check_shapes_and_get_velocity(params, grads, velocity):
+        def _check_shapes_and_get_velocity(
+            parameters: Union[float, List[Union[float, List[float]]]], 
+            gradients: Union[float, List[Union[float, List[float]]]], 
+            velocity_values: Union[float, List[Union[float, List[float]]]]
+        ) -> Tuple[Union[float, List[Union[float, List[float]]]], Union[float, List[Union[float, List[float]]]]]:
             # Handle scalar case
-            if isinstance(params, (int, float)):
-                if not isinstance(grads, (int, float)):
+            if isinstance(parameters, (int, float)):
+                if not isinstance(gradients, (int, float)):
                     raise ValueError(
                         "Shape mismatch: parameter is scalar but gradient is not"
                     )
 
-                if velocity is None:
-                    velocity = 0.0
+                if velocity_values is None:
+                    velocity_values = 0.0
 
                 # Update velocity: v = β * v + (1-β) * g
-                new_velocity = self.momentum * velocity + (1 - self.momentum) * grads
+                new_velocity = self.momentum * velocity_values + (1 - self.momentum) * gradients
                 # Update parameter: θ = θ - α * v
-                new_param = params - self.learning_rate * new_velocity
+                new_param = parameters - self.learning_rate * new_velocity
 
                 return new_param, new_velocity
 
             # Handle list case
-            if len(params) != len(grads):
+            if len(parameters) != len(gradients):
                 raise ValueError(
-                    f"Shape mismatch: parameters length {len(params)} vs "
-                    f"gradients length {len(grads)}"
+                    f"Shape mismatch: parameters length {len(parameters)} vs "
+                    f"gradients length {len(gradients)}"
                 )
 
-            if velocity is None:
-                velocity = [None] * len(params)
-            elif len(velocity) != len(params):
+            if velocity_values is None:
+                velocity_values = [None] * len(parameters)
+            elif len(velocity_values) != len(parameters):
                 raise ValueError("Velocity shape mismatch")
 
             new_params = []
             new_velocity = []
 
-            for i, (p, g, v) in enumerate(zip(params, grads, velocity)):
+            for i, (p, g, v) in enumerate(zip(parameters, gradients, velocity_values)):
                 if isinstance(p, list) and isinstance(g, list):
                     # Recursive case for nested lists
                     new_p, new_v = _check_shapes_and_get_velocity(p, g, v)

neural_network/optimizers/nag.py

@@ -18,7 +18,7 @@
 
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Union, Tuple
 
 from .base_optimizer import BaseOptimizer
 
@@ -117,10 +117,14 @@ def update(
             ValueError: If parameters and gradients have different shapes
         """
 
-        def _nag_update_recursive(params, grads, velocity):
+        def _nag_update_recursive(
+            parameters: Union[float, List], 
+            gradients: Union[float, List], 
+            velocity: Union[float, List, None]
+        ) -> Tuple[Union[float, List], Union[float, List]]:
             # Handle scalar case
-            if isinstance(params, (int, float)):
-                if not isinstance(grads, (int, float)):
+            if isinstance(parameters, (int, float)):
+                if not isinstance(gradients, (int, float)):
                     raise ValueError(
                         "Shape mismatch: parameter is scalar but gradient is not"
                     )
@@ -129,32 +133,32 @@ def _nag_update_recursive(params, grads, velocity):
                     velocity = 0.0
 
                 # Update velocity: v = β * v + (1-β) * g
-                new_velocity = self.momentum * velocity + (1 - self.momentum) * grads
+                new_velocity = self.momentum * velocity + (1 - self.momentum) * gradients
 
                 # NAG update: θ = θ - α * (β * v + (1-β) * g)
                 nesterov_update = (
-                    self.momentum * new_velocity + (1 - self.momentum) * grads
+                    self.momentum * new_velocity + (1 - self.momentum) * gradients
                 )
-                new_param = params - self.learning_rate * nesterov_update
+                new_param = parameters - self.learning_rate * nesterov_update
 
                 return new_param, new_velocity
 
             # Handle list case
-            if len(params) != len(grads):
+            if len(parameters) != len(gradients):
                 raise ValueError(
-                    f"Shape mismatch: parameters length {len(params)} vs "
-                    f"gradients length {len(grads)}"
+                    f"Shape mismatch: parameters length {len(parameters)} vs "
+                    f"gradients length {len(gradients)}"
                 )
 
             if velocity is None:
-                velocity = [None] * len(params)
-            elif len(velocity) != len(params):
+                velocity = [None] * len(parameters)
+            elif len(velocity) != len(parameters):
                 raise ValueError("Velocity shape mismatch")
 
             new_params = []
             new_velocity = []
 
-            for i, (p, g, v) in enumerate(zip(params, grads, velocity)):
+            for i, (p, g, v) in enumerate(zip(parameters, gradients, velocity)):
                 if isinstance(p, list) and isinstance(g, list):
                     # Recursive case for nested lists
                     new_p, new_v = _nag_update_recursive(p, g, v)
@@ -250,11 +254,11 @@ def __str__(self) -> str:
     x_momentum = [2.5]
     x_nag = [2.5]
 
-    def gradient_f(x):
+    def gradient_f(x: float) -> float:
         """Gradient of f(x) = 0.1*x^4 - 2*x^2 + x is f'(x) = 0.4*x^3 - 4*x + 1"""
         return 0.4 * x**3 - 4 * x + 1
 
-    def f(x):
+    def f(x: float) -> float:
         """The function f(x) = 0.1*x^4 - 2*x^2 + x"""
         return 0.1 * x**4 - 2 * x**2 + x
 

neural_network/optimizers/sgd.py

@@ -98,24 +98,27 @@ def update(
             ValueError: If parameters and gradients have different shapes
         """
 
-        def _check_and_update_recursive(params, grads):
+        def _check_and_update_recursive(
+            parameters: Union[float, List[Union[float, List[float]]]], 
+            gradients: Union[float, List[Union[float, List[float]]]]
+        ) -> Union[float, List[Union[float, List[float]]]]:
             # Handle 1D case (list of floats)
-            if isinstance(params, (int, float)):
-                if not isinstance(grads, (int, float)):
+            if isinstance(parameters, (int, float)):
+                if not isinstance(gradients, (int, float)):
                     raise ValueError(
                         "Shape mismatch: parameter is scalar but gradient is not"
                     )
-                return params - self.learning_rate * grads
+                return parameters - self.learning_rate * gradients
 
             # Handle list case
-            if len(params) != len(grads):
+            if len(parameters) != len(gradients):
                 raise ValueError(
-                    f"Shape mismatch: parameters length {len(params)} vs "
-                    f"gradients length {len(grads)}"
+                    f"Shape mismatch: parameters length {len(parameters)} vs "
+                    f"gradients length {len(gradients)}"
                 )
 
             result = []
-            for p, g in zip(params, grads):
+            for p, g in zip(parameters, gradients):
                 if isinstance(p, list) and isinstance(g, list):
                     # Recursive case for nested lists
                     result.append(_check_and_update_recursive(p, g))