first commit

Author: da578

.coverage

@@ -0,0 +1,76 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  UV_SYSTEM_PYTHON: 1
+
+jobs:
+  check:
+    name: Code Quality & Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run Ruff Check
+        run: uv run ruff check .
+
+      - name: Run Ruff Format Check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run Tests
+        run: uv run pytest
+
+      - name: Run Benchmarks
+        run: uv run python benches/mlp_benchmark.py --fast -o benchmark_results.json
+
+      - name: Run Memory Profiler
+        run: uv run memray run -o memray_results.bin benches/profile_mlp.py
+
+      - name: Generate HTML Flamegraph
+        run: uv run memray flamegraph -f -o memray_report.html memray_results.bin
+
+      - name: Generate JSON Stats
+        run: uv run memray stats --json -f -o memray_report.json memray_results.bin
+
+      - name: Upload Memory Profile Reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-memory-reports
+          path: |
+            memray_report.html
+            memray_report.json

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+*_cache
+htmlcov
+
+benchmark_report.html
+benchmark_results.json
+problem.txt
+source.txt

.gitignore

@@ -0,0 +1 @@
+3.14

.python-version

@@ -0,0 +1,73 @@
+# Architecture & Design (Python)
+
+This document describes the high-level architecture of the `gate_learner` Python package.
+
+## Module Overview
+
+The project is structured as a decoupled library with a Typer CLI wrapper. This separation ensures that the core mathematical engine remains independent of I/O, CLI parsing, and plotting logic.
+
+```text
++-----------------------------------------------------------------------+
+|                              CLI Module                               |
+|                     (gate_learner/cli.py, main)                       |
++-----------------------------------+-----------------------------------+
+                                    |
+                                    v
++-----------------------------------+-----------------------------------+
+|                           Dataset Generator                           |
+|                     (gate_learner/dataset.py)                         |
++-----------------------------------+-----------------------------------+
+                                    |
+                                    v
++-----------------------------------+-----------------------------------+
+|                           Core ML Engine                              |
+|                     (gate_learner/core.py)                            |
+|   +---------------------------------------------------------------+   |
+|   |                     MultilayerPerceptron                      |   |
+|   |  - Forward Pass (Sigmoid / ReLU Activation)                   |   |
+|   |  - Gradient Accumulation (BCE Loss)                           |   |
+|   +-------------------------------+-------------------------------+   |
+|                                   |                                   |
+|                                   v                                   |
+|   +---------------------------------------------------------------+   |
+|   |                        AdamOptimizer                          |   |
+|   |  - Parameter Update (L2 Regularisation & Bias Correction)     |   |
+|   +-------------------------------+-------------------------------+   |
++-----------------------------------+-----------------------------------+
+                                    |
+                                    +-----------------------+
+                                    |                       |
+                                    v                       v
++-----------------------------------+---+               +---+--------------------+
+|            Storage Module             |               |  Plot Module (Feature) |
+|       (gate_learner/storage.py)       |               | (gate_learner/plot.py) |
++---------------------------------------+               +------------------------+
+```
+
+### 1. Core ML Engine (`core.py`)
+Contains the mathematical representation of the neural network.
+- **`Layer`**: Represents a single layer containing weights, biases, and an activation function.
+- **`MultilayerPerceptron`**: Manages a sequence of layers. It holds pre-allocated internal buffers for activations, deltas, and gradients to avoid list allocations during the training loop.
+- **`AdamOptimizer`**: Implements the Adam optimization algorithm. It maintains its own state buffers (first and second moments) matching the network's architecture.
+
+### 2. Dataset Generator (`dataset.py`)
+Generates truth tables for $N$-input OR and XOR gates. It includes safety checks to prevent memory exhaustion by limiting $N < 20$ (since dataset size scales exponentially as $2^N$).
+
+### 3. Storage Module (`storage.py`)
+Handles JSON serialisation and deserialisation of the trained model weights and training history.
+
+### 4. Plot Module (`plot.py`)
+Gated under optional `matplotlib` import. It renders a dual-axis PNG chart showing the training loss and accuracy curves over epochs.
+
+### 5. CLI Module (`cli.py` & `main.py`)
+Parses command-line arguments using `typer`, coordinates the training loop, manages early stopping, and handles output generation.
+
+## Key Architectural Decisions
+
+### Memory Management & Allocation
+To achieve high performance in pure Python, list allocations are avoided inside the training loop. 
+- The `MultilayerPerceptron` allocates its activation, delta, and gradient buffers once during initialization via `ensure_buffers()`.
+- During the forward and backward passes, these buffers are mutated in-place.
+
+### Concurrency & Serialization
+The `MultilayerPerceptron` and `Layer` classes are designed to be fully picklable (serialisable). This allows the model to be safely transferred across processes using Python's `multiprocessing` module for parallel hyperparameter grid search.

ARCHITECTURE.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-25
+
+### Added
+- Initial release of the `gate_learner` neural network engine in Python.
+- Custom Multilayer Perceptron (MLP) implementation with support for arbitrary hidden layer architectures.
+- Sigmoid and ReLU activation functions with Xavier/Glorot and He Uniform weight initialisation.
+- Adam Optimizer with L2 regularisation, momentum, and bias correction.
+- Pre-allocated internal buffers for activations, deltas, and gradients to avoid repetitive memory allocations during training.
+- Dynamic dataset generator for $N$-input OR and XOR logic gates.
+- Early stopping mechanisms based on convergence (Loss < 0.01) and stalling (Loss change < 1e-6 over 50 epochs).
+- JSON serialisation and deserialisation for models and training histories.
+- Dual-axis plotting of training loss and accuracy curves (gated under the `visualise` extra feature using `matplotlib`).
+- Comprehensive unit tests, integration tests, and performance benchmarks using `pytest` and `pytest-benchmark`.

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologising to those affected by our mistakes, and learning from the experience
+* Focusing on what is best for the overall community, not just the individual
+
+Examples of unacceptable behaviour include:
+
+* The use of sexualised language or imagery, and unwelcome sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behaviour and will take appropriate and fair corrective action in response to any behaviour that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the community leaders at **dzulkiflianwar2@gmail.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributing to Gate Learner
+
+Thank you for your interest in contributing to `gate_learner`! We welcome contributions from everyone.
+
+## Development Setup
+
+Ensure you have Python 3.12+ and `uv` installed.
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/ios-community/gate-learner.git
+   cd gate-learner
+   ```
+
+2. Set up the virtual environment and install dependencies:
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. Run the test suite to verify your setup:
+   ```bash
+   uv run pytest
+   ```
+
+## Code Style & Quality
+
+We enforce strict code quality standards using `ruff`. Before submitting a pull request, please ensure your code is formatted and free of lint errors:
+
+```bash
+# Run linter checks
+uv run ruff check .
+
+# Format code
+uv run ruff format .
+```
+
+## Documentation
+
+All public APIs must be fully documented using the **Google Style Python Docstrings** format. Code examples in docstrings should be written as runnable doctests and will be validated during testing.
+
+## Submitting a Pull Request
+
+1. Fork the repository and create your branch from `main`.
+2. Ensure all tests, doctests, and linter checks pass.
+3. Commit your changes with clear, descriptive commit messages.
+4. Submit a pull request to the `main` branch.