Merge branch 'main' into dev

Author: Klus3kk

.github/workflows/ci.yml

@@ -25,20 +25,23 @@ jobs:
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         pip install pytest pytest-cov flake8 black
         pip install -e .
+    - name: Format with black
+      run: |
+        # Format the code with black before checking
+        black .
+        # Check if any changes were made
+        git diff --exit-code || { echo "Code was not properly formatted before commit. Black has fixed the formatting issues."; exit 0; }
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Format with black
-      run: |
-        black --check .
     - name: Test with pytest
       run: |
         pytest --cov=./ --cov-report=xml
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
       with:
         file: ./coverage.xml
-        fail_ci_if_error: false
+        fail_ci_if_error: false

Dockerfile

@@ -9,4 +9,4 @@ COPY . .
 RUN pip install -e .
 
 # Default command runs tests
-CMD ["python", "-m", "pytest", "tests/"]
+CMD ["python", "-m", "pytest", "tests/"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Bielaszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -71,4 +71,3 @@ trainer.fit(X, y, epochs=100)
 # Make predictions
 predictions = model(X)
 ```
-

core/checks.py

@@ -1,8 +1,23 @@
+"""
+This module provides gradient checking utilities to verify backpropagation calculations.
+"""
+
 import numpy as np
 
+
 def check_gradients(model, x, y, loss_fn, epsilon=1e-5, threshold=1e-3):
-    """
-    Compares analytical gradients from backprop to numerical gradients.
+    """Compare analytical gradients from backpropagation to numerical gradients.
+
+    Args:
+        model: The neural network model to check
+        x: Input tensor
+        y: Target tensor
+        loss_fn: Loss function
+        epsilon: Small perturbation for numerical gradient calculation
+        threshold: Maximum allowable relative error
+
+    Raises:
+        AssertionError: If the relative error between analytical and numerical gradients exceeds threshold
     """
     # Forward and backward to compute analytical gradients
     preds = model(x)
@@ -41,4 +56,6 @@ def check_gradients(model, x, y, loss_fn, epsilon=1e-5, threshold=1e-3):
         print(f"  Param shape: {param.data.shape}")
         print(f"  Mean relative error: {relative_error:.6e}")
 
-        assert relative_error < threshold, f"Gradient check failed! Relative error: {relative_error}"
+        assert (
+            relative_error < threshold
+        ), f"Gradient check failed! Relative error: {relative_error}"

core/tensor.py

@@ -1,7 +1,26 @@
+"""
+This module implements the Tensor class for automatic differentiation in the ML framework.
+"""
+
 import numpy as np
 
+
 class Tensor:
+    """
+    Core tensor class with automatic differentiation capabilities.
+
+    Implements a computational graph with automatic gradient calculation
+    for building and training neural networks.
+    """
+
     def __init__(self, data, requires_grad=False):
+        """
+        Initialize a new Tensor.
+
+        Args:
+            data: Input data (numpy array or convertible to numpy array)
+            requires_grad: Whether the tensor requires gradient computation
+        """
         if not isinstance(data, np.ndarray):
             data = np.array(data, dtype=np.float32)
 
@@ -12,11 +31,24 @@ def __init__(self, data, requires_grad=False):
         self._prev = set()
 
     def __repr__(self):
+        """Return string representation of the tensor."""
         return f"Tensor(data={self.data}, grad={self.grad})"
 
     def __add__(self, other):
+        """
+        Add two tensors or a tensor and a scalar.
+
+        Args:
+            other: Another tensor or scalar value
+
+        Returns:
+            A new tensor containing the result
+        """
         other = other if isinstance(other, Tensor) else Tensor(other)
-        out = Tensor(self.data + other.data, requires_grad=self.requires_grad or other.requires_grad)
+        out = Tensor(
+            self.data + other.data,
+            requires_grad=self.requires_grad or other.requires_grad,
+        )
 
         def _backward():
             if self.requires_grad:
@@ -36,8 +68,20 @@ def _backward():
         return out
 
     def __mul__(self, other):
+        """
+        Multiply two tensors or a tensor and a scalar.
+
+        Args:
+            other: Another tensor or scalar value
+
+        Returns:
+            A new tensor containing the result
+        """
         other = other if isinstance(other, Tensor) else Tensor(other)
-        out = Tensor(self.data * other.data, requires_grad=self.requires_grad or other.requires_grad)
+        out = Tensor(
+            self.data * other.data,
+            requires_grad=self.requires_grad or other.requires_grad,
+        )
 
         def _backward():
             if self.requires_grad:
@@ -57,18 +101,51 @@ def _backward():
         return out
 
     def __sub__(self, other):
+        """
+        Subtract a tensor or scalar from this tensor.
+
+        Args:
+            other: Another tensor or scalar value
+
+        Returns:
+            A new tensor containing the result
+        """
         other = other if isinstance(other, Tensor) else Tensor(other)
         return self + (-other)
 
     def __neg__(self):
+        """
+        Negate this tensor.
+
+        Returns:
+            A new tensor with negated values
+        """
         return self * -1
 
     def __truediv__(self, other):
+        """
+        Divide this tensor by another tensor or scalar.
+
+        Args:
+            other: Another tensor or scalar value
+
+        Returns:
+            A new tensor containing the result
+        """
         other = other if isinstance(other, Tensor) else Tensor(other)
         return self * other**-1
 
     def __pow__(self, power):
-        out = Tensor(self.data ** power, requires_grad=self.requires_grad)
+        """
+        Raise this tensor to a power.
+
+        Args:
+            power: Exponent value
+
+        Returns:
+            A new tensor containing the result
+        """
+        out = Tensor(self.data**power, requires_grad=self.requires_grad)
 
         def _backward():
             if self.requires_grad:
@@ -80,8 +157,20 @@ def _backward():
         return out
 
     def __matmul__(self, other):
+        """
+        Perform matrix multiplication with another tensor.
+
+        Args:
+            other: Another tensor for matrix multiplication
+
+        Returns:
+            A new tensor containing the result
+        """
         other = other if isinstance(other, Tensor) else Tensor(other)
-        out = Tensor(self.data @ other.data, requires_grad=self.requires_grad or other.requires_grad)
+        out = Tensor(
+            self.data @ other.data,
+            requires_grad=self.requires_grad or other.requires_grad,
+        )
 
         def _backward():
             if self.requires_grad:
@@ -101,6 +190,15 @@ def _backward():
         return out
 
     def __getitem__(self, idx):
+        """
+        Get items from the tensor at specified indices.
+
+        Args:
+            idx: Index or slice to retrieve
+
+        Returns:
+            A new tensor with the selected items
+        """
         out = Tensor(self.data[idx], requires_grad=self.requires_grad)
 
         def _backward():
@@ -114,12 +212,24 @@ def _backward():
         return out
 
     def __hash__(self):
+        """Hash function for tensor objects."""
         return id(self)
 
     def __eq__(self, other):
+        """Check if two tensor objects are the same."""
         return id(self) == id(other)
 
     def sum(self, axis=None, keepdims=False):
+        """
+        Sum tensor elements along specified axis.
+
+        Args:
+            axis: Axis along which to sum
+            keepdims: Whether to keep the summed dimensions
+
+        Returns:
+            A new tensor with summed values
+        """
         out_data = np.sum(self.data, axis=axis, keepdims=keepdims)
         out = Tensor(out_data, requires_grad=self.requires_grad)
 
@@ -136,6 +246,12 @@ def _backward():
         return out
 
     def mean(self):
+        """
+        Calculate the mean of all tensor elements.
+
+        Returns:
+            A new tensor containing the mean value
+        """
         out = Tensor(self.data.mean(), requires_grad=self.requires_grad)
 
         def _backward():
@@ -148,6 +264,12 @@ def _backward():
         return out
 
     def exp(self):
+        """
+        Calculate the exponential of all tensor elements.
+
+        Returns:
+            A new tensor with exponential values
+        """
         out = Tensor(np.exp(self.data), requires_grad=self.requires_grad)
 
         def _backward():
@@ -160,6 +282,12 @@ def _backward():
         return out
 
     def log(self):
+        """
+        Calculate the natural logarithm of all tensor elements.
+
+        Returns:
+            A new tensor with logarithm values
+        """
         out = Tensor(np.log(self.data), requires_grad=self.requires_grad)
 
         def _backward():
@@ -172,6 +300,16 @@ def _backward():
         return out
 
     def max(self, axis=None, keepdims=False):
+        """
+        Find maximum values along specified axis.
+
+        Args:
+            axis: Axis along which to find maximum values
+            keepdims: Whether to keep the dimensions
+
+        Returns:
+            A new tensor with maximum values
+        """
         data = self.data
         max_data = np.max(data, axis=axis, keepdims=keepdims)
         out = Tensor(max_data)
@@ -192,6 +330,12 @@ def _backward():
         return out
 
     def backward(self):
+        """
+        Perform backpropagation starting from this tensor.
+
+        Computes gradients for all tensors in the computational graph
+        that require gradients.
+        """
         if self.grad is None:
             self.grad = np.ones_like(self.data)
         print("Backward on:", self.data)
@@ -215,7 +359,10 @@ def topo(tensor):
 
     def clip_gradients(self, max_norm):
         """
-        Clips gradients to prevent exploding gradients
+        Clip gradients to prevent exploding gradients.
+
+        Args:
+            max_norm: Maximum gradient norm
         """
         if self.grad is None:
             return
@@ -226,4 +373,3 @@ def clip_gradients(self, max_norm):
         # Clip if necessary
         if grad_norm > max_norm:
             self.grad = self.grad * (max_norm / (grad_norm + 1e-12))
-

docker-compose.yml

@@ -13,4 +13,4 @@ services:
       - .:/app
     ports:
       - "8888:8888"
-    command: jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token='' --NotebookApp.password=''
+    command: jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token='' --NotebookApp.password=''