Merge pull request #12 from FFMG/feature/python

Initial python module

Author: FFMG

.github/workflows/python.yml

@@ -0,0 +1,36 @@
+name: Python Binding CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-verify-python:
+    runs-on: windows-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install pybind11 dependency
+      run: |
+        python -m pip install --upgrade pip
+        pip install pybind11
+
+    - name: Add MSBuild to PATH
+      uses: microsoft/setup-msbuild@v2
+
+    - name: Build Python Binding Module
+      run: msbuild python/neuralnetwork_py.sln /p:Configuration=Release /p:Platform=x64
+      env:
+        PYTHON_HOME: ${{ env.pythonLocation }}
+
+    - name: Verify Module Import and Functionality
+      run: python python/import_check.py

CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to the `neural-network` library will be documented in this f
 - Created the `myoddweb::nn` namespace.
 - Wrapped all core neural network library classes, structures, and helper functions in the new `myoddweb::nn` namespace (including `NeuralNetwork`, `Layer`, `Neuron`, `activation`, `NeuralNetworkOptions`, etc.).
 - Added explicit documentation in the `README.md` explaining how to import and use the new namespace.
+- Created a new `/python/` subdirectory containing a C++ binding toolchain (using `pybind11` and NuGet package restore) to compile the C++ library into a Python extension module (`neuralnetwork.pyd`).
+- Added a Python test script `example.py` demonstrating how to train and use the neural network from Python.
+- Added explicit documentation in `python/README.md` explaining how to build and call the Python module.
 
 ### Changed
 - Updated all stand-alone example header files in `src/neuralnetwork/examples/` to use the `myoddweb::nn` namespace.

GEMINI.md

@@ -0,0 +1,83 @@
+# Gemini Project Context: neural-network
+
+This document provides context and guidelines for interacting with the `neural-network` project.
+
+My name is Florent
+
+## Project Overview
+
+The `neural-network` project is a lightweight, dependency-free Feedforward and Recurrent Neural Network library implemented in modern C++. It is designed for both educational purposes and practical application in financial market analysis and trading.
+
+### Key Features
+- **Neural Network Architecture:** Supports standard Feedforward (FF), Elman RNN, and Gated Recurrent Unit (GRU) layers.
+- **Advanced Training:** Includes Adam, AdamW, Nadam, and NadamW optimizers, Backpropagation Through Time (BPTT), residual connections, gradient clipping, and dropout (dilution).
+- **Learning Rate Strategies:** Implements warmup, exponential decay, periodic restarts with boosts, and adaptive learning rate scheduling.
+- **Market Integration:** A dedicated `market` class handles technical indicators (RSI, Bollinger Bands, EMA, MACD, etc.) and data normalization for trading strategies.
+- **Visualization:** A built-in `Chart` tool using the `olcPixelGameEngine` for real-time visualization of market data, predictions, and trade signals.
+- **Persistence:** Supports saving and loading trained models via a custom serializer.
+- **Zero Dependencies:** Built from scratch with minimal external dependencies (embedded `sqlite3`, `TinyJSON`, `olcPixelGameEngine`).
+
+### Technology Stack
+- **Language:** C++17/C++20
+- **Platform:** Windows (Win32 API for screen metrics, MSVC for compilation)
+- **Profiling:** Integrated with Tracy Profiler, disabled by default.
+
+---
+
+## Building and Running
+
+### Prerequisites
+- **Visual Studio 2022** (or compatible version) with C++ development workload.
+- **Windows OS** (due to Win32 API usage in the charting tool).
+- Try and support C++ 99 where possible, comment if not possible.
+
+### Build Instructions
+1.  Open `examples/neuralnetwork.sln` in Visual Studio.
+2.  Select the desired configuration (Debug/Release) and platform (x64).
+3.  Build the solution (`Ctrl+Shift+B`).
+
+### Running the Project
+- The primary entry point is `examples/main.cpp`.
+
+### Examples
+Multiple standalone examples are located in `examples/`, including:
+- `xor.h`: Classic XOR problem.
+- `threebitparity.h`: 3-bit parity check.
+- `twomoon.h`: Two moons classification.
+- `addingproblem.h`: RNN benchmark for long-term dependencies.
+
+- Examples are commented out by default, the user will enable the example(s) needed where and when needed.
+
+---
+
+## Development Conventions
+
+### Coding Style
+- Use 2 spaces, never tab.
+- **Naming:**
+  - Classes: `PascalCase` (e.g., `NeuralNetwork`).
+  - Methods/Functions: `snake_case` (e.g., `train`, `think`).
+  - Private Members: Prefixed with an underscore (e.g., `_learning_rate`).
+- **Headers:** Uses `#pragma once` for include guards.
+- **Error Handling:** Uses `Logger` for logging and standard exceptions for critical failures.
+
+### Architecture Patterns
+- **Options Pattern:** `NeuralNetworkOptions` uses a builder-like pattern for configuration.
+- **RAII:** Strict adherence to RAII for memory and resource management (though some raw pointers are used in legacy parts).
+- **Thread Safety:** Uses `std::shared_mutex` for concurrent access to market data and network states.
+
+### Logging and Profiling
+- Use `Logger::info`, `Logger::debug`, `Logger::error`, etc., for all output.
+- Every new function my start with MYODDWEB_PROFILE_FUNCTION("Name-Of-Class")
+- If you see a function that does not have MYODDWEB_PROFILE_FUNCTION("Name-Of-Class") as a first line, please flag it to me.
+- **important** The MACRO MYODDWEB_PROFILE_FUNCTION has no impact on performance, when I ask you to review my code for performance, ignore MYODDWEB_PROFILE_FUNCTION as it has no impact.
+
+---
+
+- When looking at the Layer Class, remember to look at all the derived classes.
+- Do not worry about Git commits, I will deal will them.
+
+## Key Files
+- `include/neuralnetwork/neuralnetwork.h`: The main interface for the NN library.
+- `examples/config.json`: Main configuration for the examples runner.
+- `examples/strategy.json`: Trading strategy definitions.

README.md

@@ -271,9 +271,10 @@ For more information on AVX2, see the [Intel Intrinsics Guide](https://www.intel
 
 ## Repository Layout
 
-*   `\include\neuralnetwork\`: The stand-alone core neural network library (including `/layers/`, `/helpers/`, and `/common/` subdirectories).
+*   `\include\neuralnetwork\`: The stand-alone core C++ neural network library (including `/layers/`, `/helpers/`, and `/common/` subdirectories).
 *   `\examples\`: Standalone example implementations, runner (`main.cpp`), and the main Visual Studio solution (`neuralnetwork.sln`).
 *   `\tests\`: Comprehensive unit test suite.
+*   `\python\`: Pybind11-based Visual Studio 2022 solution (`neuralnetwork_py.sln`) and Python usage examples.
 
 ## Building and Running
 

python/README.md

@@ -0,0 +1,77 @@
+# Python Bindings for neural-network
+
+This subdirectory contains the Visual Studio 2022 C++ project and code necessary to build and run native Python bindings for the `myoddweb::nn` neural network library using `pybind11`.
+
+---
+
+## Folder Layout
+
+*   `bindings.cpp`: C++ source file defining the `pybind11` wrapper layer, mapping C++ types, enums, and classes into Python.
+*   `neuralnetwork_py.vcxproj`: Visual Studio C++ project file configured to build a dynamic library output with a `.pyd` file extension.
+*   `neuralnetwork_py.vcxproj.filters`: Project filters mapping for Solution Explorer organization.
+*   `neuralnetwork_py.sln`: Main Visual Studio solution.
+*   `example.py`: Python script illustrating options configuration, model instantiation, callback monitoring, training, inference, and serialization.
+*   `import_check.py`: A lightweight validation script that verifies the binary module loads, initializes enums, and starts up correctly (used in CI).
+
+---
+
+## Build Prerequisites
+
+1.  **Visual Studio 2022** with the **Desktop development with C++** workload installed.
+2.  **Python 3.x** (64-bit version recommended, matching the target build platform).
+3.  **pybind11**: Install the header-only package via `pip`:
+    ```bash
+    pip install pybind11
+    ```
+4.  **Environment Setup**:
+    To allow Visual Studio to locate Python headers (`python.h`) and libraries (`python3x.lib`), you should configure the `PYTHON_HOME` environment variable on your computer:
+    *   Set `PYTHON_HOME` to your Python installation folder (e.g. `C:\Users\<Name>\AppData\Local\Programs\Python\Python312` or `C:\Program Files\Python312`).
+    *   *Alternatively*, if you have Visual Studio's **Python development** workload installed, MSBuild will automatically search for the default Python paths.
+
+---
+
+## Building the Module
+
+1.  Open the solution file [neuralnetwork_py.sln](file:///H:/projects/github/neural-network2/python/neuralnetwork_py.sln) in Visual Studio 2022.
+2.  Set the solution build configuration to:
+    *   **Configuration:** `Release`
+    *   **Platform:** `x64`
+3.  Build the solution (`Ctrl+Shift+B` or right-click the project -> **Build**).
+4.  This compiles the library and generates `neuralnetwork.pyd` inside the `python/x64/Release/` folder.
+
+---
+
+## Running the Python Example
+
+Once the `.pyd` module is built, you can run the example script:
+
+```bash
+python example.py
+```
+
+This script trains a neural network on the XOR classification task and validates predictions.
+
+---
+
+## API Usage Reference
+
+The Python bindings expose the C++ API in a clean, Pythonic wrapper inside the `neuralnetwork` module:
+
+### Enums
+*   `nn.ActivationMethod`: `Linear`, `Sigmoid`, `Tanh`, `Relu`, `LeakyRelu`, `PRelu`, `Selu`, `Swish`, `Mish`, `Gelu`, `Elu`, `Softmax`.
+*   `nn.OptimiserType`: `SGD`, `Momentum`, `Nesterov`, `RMSProp`, `Adam`, `AdamW`, `AdaGrad`, `AdaDelta`, `Nadam`, `NadamW`, `AMSGrad`, `LAMB`, `Lion`, `None`.
+*   `nn.ErrorCalculationType`: `None`, `HuberLoss`, `HuberDirectionLoss`, `MAE`, `MSE`, `RMSE`, `BCELoss`, `CrossEntropy`, etc.
+
+### Core Classes & Properties
+*   `nn.Activation(method, alpha, temperature=1.0)`: Represents the activation configuration.
+*   `nn.NeuralNetworkOptions.create(topology)`: Returns a builder options object. Exposes builder methods such as:
+    *   `.with_number_of_epoch(500)`
+    *   `.with_learning_rate(0.15)`
+    *   `.with_batch_size(4)`
+    *   `.with_progress_callback(callback_function)` (allows native Python functions to serve as callbacks during training).
+*   `nn.NeuralNetwork(options)`: Core model executor. Methods:
+    *   `.train(inputs, outputs)`: Input arguments are standard Python nested lists of floats (e.g. `[[0, 0, 1], [1, 0, 1]]`).
+    *   `.think(inputs)`: Returns predictions as Python lists.
+*   `nn.NeuralNetworkSerializer`: Exposes static methods:
+    *   `nn.NeuralNetworkSerializer.save(net, filepath)`
+    *   `nn.NeuralNetworkSerializer.load(filepath)` (returns a deserialized network instance).