From 112acae1104297574b3bb2cda561ace248919389 Mon Sep 17 00:00:00 2001 From: Abhishek Shivakumar Date: Mon, 17 Aug 2026 10:39:58 +0100 Subject: [PATCH] Harden CI and add GitHub Pages site --- .github/pull_request_template.md | 15 +++ .github/workflows/ci.yml | 151 ++++++++++++++----------------- .github/workflows/pages.yml | 40 ++++++++ CONTRIBUTING.md | 25 +++++ README.md | 142 +++++++++-------------------- SECURITY.md | 11 +++ site/index.html | 109 ++++++++++++++++++++++ 7 files changed, 308 insertions(+), 185 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/pages.yml create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 site/index.html diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8f5d3df --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What changed + +Describe the change and the problem it solves. + +## Verification + +Describe the build, tests and any controlled benchmarks you ran. + +## Checklist + +- [ ] The change is focused and does not include unrelated churn. +- [ ] The registered CTest suite passes locally. +- [ ] Public API or behaviour changes are documented. +- [ ] New code respects the licensing boundary documented in `LICENSING.md`. +- [ ] Performance claims, if any, include hardware, compiler and build configuration. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 70877f5..1a8ea68 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,62 +1,56 @@ name: CI on: - # Fast check on PRs โ€” build + unit tests only (no benchmarks) pull_request: - branches: [ main ] - - # Same check on main, so the branch keeps a current status. Without this - # the README and profile badges stay frozen on whatever ran last. + branches: [main] push: - branches: [ main ] + branches: [main] + tags: ['v*'] + workflow_dispatch: + +permissions: + contents: read - # Release builds: triggered by version tags (v1.0.0, v2.3.1, etc.) - tags: - - 'v*' +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true jobs: - # --------------------------------------------------------------- - # Quick CI gate โ€” runs on every PR to main and every push to main - # Builds the library and runs only fast unit tests (<2 min total). - # Benchmarks and long-running tests are SKIPPED here because - # GitHub's free runners are too slow / unreliable for them. - # See TESTING.md for the full rationale. - # --------------------------------------------------------------- build-and-test: + name: ${{ matrix.compiler }} / Release runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - compiler: GCC + cc: gcc + cxx: g++ + - compiler: Clang + cc: clang + cxx: clang++ + env: + CC: ${{ matrix.cc }} + CXX: ${{ matrix.cxx }} steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Set up C++ environment - run: | - sudo apt-get update - sudo apt-get install -y build-essential cmake g++ libgtest-dev - - - name: Build and install Google Test - run: | - cd /usr/src/gtest - sudo cmake . - sudo make - sudo cp lib/*.a /usr/lib - - - name: Configure CMake - run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release - - - name: Build the project - run: cmake --build build -j$(nproc) - - - name: Run unit tests (benchmarks excluded) - run: | - cd build - ctest --output-on-failure --timeout 120 - echo "See TESTING.md for info on skipped/disabled tests" - - # --------------------------------------------------------------- - # Release job โ€” only runs when a version tag is pushed. - # Builds an optimised binary and uploads it as a GitHub Release. - # --------------------------------------------------------------- + - name: Checkout + uses: actions/checkout@v4 + + - name: Install build tools + run: | + sudo apt-get update + sudo apt-get install -y ninja-build + + - name: Configure + run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build --parallel 2 + + - name: Test + run: ctest --test-dir build --output-on-failure --timeout 120 + release: if: startsWith(github.ref, 'refs/tags/v') needs: build-and-test @@ -65,40 +59,29 @@ jobs: contents: write steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Set up C++ environment - run: | - sudo apt-get update - sudo apt-get install -y build-essential cmake g++ libgtest-dev - - - name: Build and install Google Test - run: | - cd /usr/src/gtest - sudo cmake . - sudo make - sudo cp lib/*.a /usr/lib - - - name: Build release binaries - run: | - cmake -S . -B build -DCMAKE_BUILD_TYPE=Release - cmake --build build -j$(nproc) - - - name: Package binaries - run: | - mkdir -p release - # Copy library - cp build/libTinyML.a release/ - # Copy test/benchmark executables (if they exist) - find build/bin -type f -executable -exec cp {} release/ \; 2>/dev/null || true - find build -maxdepth 1 -type f -executable -exec cp {} release/ \; 2>/dev/null || true - # Create tarball - tar -czf tinyml-${{ github.ref_name }}-linux-x86_64.tar.gz -C release . - ls -lh tinyml-${{ github.ref_name }}-linux-x86_64.tar.gz - - - name: Create GitHub Release - uses: softprops/action-gh-release@v2 - with: - files: tinyml-${{ github.ref_name }}-linux-x86_64.tar.gz - generate_release_notes: true + - name: Checkout + uses: actions/checkout@v4 + + - name: Install build tools + run: | + sudo apt-get update + sudo apt-get install -y ninja-build + + - name: Configure + run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build --parallel 2 + + - name: Package + run: | + mkdir -p release + cp build/libTinyML.a release/ + find build/bin -type f -executable -exec cp {} release/ \; 2>/dev/null || true + tar -czf tinyml-${{ github.ref_name }}-linux-x86_64.tar.gz -C release . + + - name: Publish GitHub release + uses: softprops/action-gh-release@v2 + with: + files: tinyml-${{ github.ref_name }}-linux-x86_64.tar.gz + generate_release_notes: true diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..4a2c224 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,40 @@ +name: Pages + +on: + push: + branches: [main] + paths: + - 'site/**' + - '.github/workflows/pages.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Configure Pages + uses: actions/configure-pages@v5 + + - name: Upload site + uses: actions/upload-pages-artifact@v3 + with: + path: site + + - name: Deploy + id: deployment + uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..46861d8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing to TinyML + +Thanks for improving TinyML. Changes should be narrowly scoped, reproducible and accompanied by the smallest useful test coverage. + +## Before opening a pull request + +Build and run the registered test suite: + +```bash +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build --parallel +ctest --test-dir build --output-on-failure +``` + +If a change affects wall-clock performance, benchmark it on controlled hardware and include the hardware, compiler, build type and command used. Do not use shared GitHub-hosted runners as benchmark evidence. + +Keep public API changes documented. New algorithms should include a focused example or test showing the intended behaviour. Avoid unrelated formatting or generated-file churn in functional pull requests. + +## Pull requests + +Describe the problem, the approach, how it was verified and any compatibility or licensing implications. CI must pass before merge. + +## Licensing + +Read `LICENSING.md` before adding new public headers or dependencies. Contributions must preserve the documented boundary between the MIT core and the separately licensed extended model library. diff --git a/README.md b/README.md index a88c69d..e2cf7bd 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,69 @@ -# TinyML: High-Performance C++ Machine Learning Library +# TinyML +[![CI](https://github.com/godofecht/tinyML/actions/workflows/ci.yml/badge.svg)](https://github.com/godofecht/tinyML/actions/workflows/ci.yml) +[![Pages](https://github.com/godofecht/tinyML/actions/workflows/pages.yml/badge.svg)](https://godofecht.github.io/tinyML/) +![C++](https://img.shields.io/badge/C%2B%2B-17%2F20-blue.svg) ![License](https://img.shields.io/badge/license-MIT%20core%20%2B%20commercial-blue.svg) -![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg) -![Standard](https://img.shields.io/badge/C%2B%2B-17%2F20-blue.svg) -**TinyML** is a high-performance, lightweight machine learning library written in modern C++ (17/20). It is designed for educational exploration and production-grade embedded deployment, featuring a zero-dependency core, SIMD optimizations, and a rich interactive playground. +**TinyML is a lightweight, high-performance C++ machine-learning and statistical-computing library aimed at real-time and embedded use.** It implements the stack directly in modern C++, with SIMD-aware kernels, quantization, neural-network architectures, scientific ML, reinforcement learning, graph models, generative models and an interactive playground. -Unlike standard frameworks (PyTorch/TensorFlow) that abstract away the details, TinyML implements algorithms from scratch to demonstrate deep understanding of the underlying mathematics and systems engineering required for high-performance ML. +**Project site:** https://godofecht.github.io/tinyML/ ---- +## What is here -## ๐Ÿš€ Key Features +The library includes feed-forward networks, CNNs, RNNs, streaming Transformers, Bayesian neural networks, VAEs, GANs, PINNs, policy-gradient and Q-learning examples, graph neural networks, time-series forecasting, quantized inference, SIMD operations and production-oriented serving helpers. -### ๐Ÿง  Advanced Architectures -* **Deep Learning**: Custom implementation of Feed-Forward Networks, CNNs (Convolutional), and RNNs. -* **Transformers**: Real-time streaming Transformer implementation with self-attention mechanisms. -* **Bayesian Neural Networks (BNN)**: Uncertainty estimation using Monte Carlo Dropout and Variational Inference. -* **Generative Models**: Variational Autoencoders (VAE) and 2D Generative Adversarial Networks (GAN). -* **Scientific ML**: Physics-Informed Neural Networks (PINNs) for solving PDEs (e.g., Heat Equation). -* **Reinforcement Learning**: Policy Gradient and Q-Learning implementations (CartPole, Pong). -* **Graph Neural Networks (GNN)**: Spatiotemporal modeling for traffic forecasting. +The `playground/` directory contains a C++ backend plus a browser frontend for interactive scenarios such as CartPole, Pong, attention visualisation, CNN operations, PINNs and graph diffusion. The GitHub Pages site is a separate static project front page; the full playground still runs against the local C++ server. -### โšก Performance & Systems -* **SIMD Optimization**: Explicit AVX2/NEON vectorization for core linear algebra operations (`SIMDOperations.h`, `XSIMDOperations.h`). -* **Quantization**: Support for integer-only inference for edge devices. -* **Memory Management**: Smart pointer usage and custom memory pools for minimal overhead. -* **Thread Safety**: Thread-safe model serving infrastructure (`ModelManager`). +## Build -### ๐ŸŽฎ Interactive Playground -A built-in web-based dashboard to visualize training and inference in real-time. -* **Real-time Visualization**: Canvas-based rendering of environments (CartPole, Pong) and internal model states (Attention maps, CNN filters). -* **Interactive Scenarios**: 7+ scenarios covering different ML domains. -* **Live Training**: "Loop Train" functionality to watch models learn. - ---- - -## ๐Ÿ› ๏ธ Installation & Build - -### Prerequisites -* CMake (3.15+) -* C++ Compiler (GCC 9+, Clang 10+, MSVC 2019+) -* Make or Ninja - -### Build Instructions ```bash -git clone https://github.com/your-username/tinyML.git +git clone https://github.com/godofecht/tinyML.git cd tinyML -mkdir build && cd build -cmake .. -make -j$(nproc) +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build --parallel +ctest --test-dir build --output-on-failure ``` ---- - -## ๐Ÿ–ฅ๏ธ Running the Playground - -The playground consists of a C++ backend server and a vanilla JS/HTML frontend. - -1. **Start the Server**: - ```bash - ./bin/PlaygroundServer - ``` - *Server listens on port 8081.* +CMake fetches xsimd and GoogleTest when they are not already available. See [TESTING.md](TESTING.md) for the distinction between correctness tests, disabled long-running tests and opt-in timing assertions. -2. **Access the Dashboard**: - Open `http://localhost:8081` in your browser. +## Playground -3. **Explore Scenarios**: - * **CartPole (RL)**: Watch an agent balance a pole. - * **Pong (RL)**: AI agent playing against a heuristic opponent. - * **CNN**: Visual convolution operations. - * **Heat Equation (PINN)**: Solving partial differential equations. - * **Traffic (GNN)**: Graph diffusion simulation. +```bash +cmake --build build --target PlaygroundServer --parallel +./build/bin/PlaygroundServer +``` ---- +Then open `http://localhost:8081`. -## ๐Ÿ“‚ Project Structure +## Repository map +```text +include/ public library headers +src/ implementation +examples/ usage examples +benchmarks/ local benchmark programs +playground/ C++ server + browser UI +tests/ GoogleTest suite +docs/ API, demo and wiki documentation +blog/ implementation and architecture notes +site/ static GitHub Pages site ``` -tinyML/ -โ”œโ”€โ”€ include/ # Core Library Headers -โ”‚ โ”œโ”€โ”€ Network.h # Base Neural Network abstractions -โ”‚ โ”œโ”€โ”€ RealTimeTransformer.h # Transformer implementation -โ”‚ โ”œโ”€โ”€ SIMDOperations.h # AVX/NEON optimizations -โ”‚ โ””โ”€โ”€ ... -โ”œโ”€โ”€ src/ # Library Implementation -โ”œโ”€โ”€ playground/ # Interactive Web Dashboard -โ”‚ โ”œโ”€โ”€ server.cpp # HTTP Server (using httplib) -โ”‚ โ”œโ”€โ”€ ModelManager.h # Thread-safe model orchestration -โ”‚ โ”œโ”€โ”€ Scenarios.h # Scenario logic (Pong, CartPole, etc.) -โ”‚ โ””โ”€โ”€ script.js # Frontend visualization logic -โ”œโ”€โ”€ benchmarks/ # Performance benchmarks -โ”œโ”€โ”€ tests/ # GoogleTest suite -โ””โ”€โ”€ blog/ # Detailed architectural documentation -``` - ---- -## ๐Ÿงช Testing & Benchmarks +## CI and releases -The project maintains a high standard of correctness through a comprehensive test suite. +Every pull request and push to `main` builds the project with both GCC and Clang and runs the registered CTest suite. Version tags matching `v*` additionally produce a Linux x86-64 release archive. -```bash -# Run Unit Tests -cd build -./TinyMLTests - -# Run Benchmarks -./SIMDBenchmark -``` +Wall-clock performance assertions are intentionally opt-in because shared CI hardware is not a meaningful benchmark environment. Use `TINYML_PERF_ASSERTS=1` locally when you explicitly want those thresholds enforced. ---- +## Documentation -## ๐Ÿ“š Documentation -Detailed design documents and phase breakdowns can be found in the `blog/` directory, covering topics from "SIMD Optimization Foundation" to "Reinforcement Learning". +Start with [PRODUCTION_API.md](docs/PRODUCTION_API.md), [TESTING.md](TESTING.md), [ROADMAP.md](ROADMAP.md), [DEMO_ROADMAP.md](docs/DEMO_ROADMAP.md) and the material in `docs/wiki/` and `blog/`. ---- +## Contributing and security -## ๐Ÿ“ License +See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a change. Security-sensitive reports should follow [SECURITY.md](SECURITY.md). -tinyML is dual licensed. The zero-dependency core is MIT, free for any use -including commercial. The extended model library (attention, transformers, -generative, graph, RL, forecasting, production API) requires xsimd and is -covered by a commercial license: free for research, education and personal -projects, paid for commercial use. +## Licensing -[LICENSING.md](LICENSING.md) lists exactly which headers fall on each side. -No MIT header includes a commercial one, so the core builds and ships alone. +TinyML is dual licensed. The zero-dependency core is MIT-licensed, including commercial use. The extended model library is covered by the commercial terms described in [LICENSING.md](LICENSING.md). That file is the authoritative map of which headers belong to each side of the license boundary. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1db4f49 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a vulnerability + +Please do not open a public issue for a vulnerability that could put users at risk. Use GitHub's private vulnerability reporting for this repository when available. If that channel is unavailable, contact the repository owner privately through the contact method listed on the owner's GitHub profile. + +Include the affected component, a minimal reproduction, expected impact and any mitigation you have already identified. Avoid including secrets, personal data or unnecessary exploit automation. + +## Supported code + +Security fixes target the current `main` branch. Older snapshots and unmaintained forks are not guaranteed to receive backports. diff --git a/site/index.html b/site/index.html new file mode 100644 index 0000000..12f6783 --- /dev/null +++ b/site/index.html @@ -0,0 +1,109 @@ + + + + + + + TinyML โ€” high-performance C++ machine learning + + + +
+ + +
+
+
Modern C++ ยท Real-time ยท Embedded
+

Machine learning without the heavyweight runtime.

+

TinyML is a compact C++ machine-learning and statistical-computing library built around direct implementations, SIMD-aware kernels, quantization and deployable real-time systems.

+
+ View source + Production API + Testing model +
+
+ +
+
C++17baseline language standard
+
SIMDAVX2 / NEON-oriented kernels
+
CTestautomated correctness gate
+
Edge-firstquantized and real-time workloads
+
+ +
+

One small stack, unusually broad coverage.

+

The repository spans classical infrastructure and modern architectures without handing execution to a Python framework runtime.

+
+

Neural architectures

Feed-forward networks, CNNs, RNNs and streaming Transformers.

+

Uncertainty & generation

Bayesian neural networks, Monte Carlo dropout, variational inference, VAEs and GANs.

+

Scientific ML

Physics-informed neural networks for PDE-oriented workloads.

+

Reinforcement learning

Policy-gradient and Q-learning implementations with interactive scenarios.

+

Graph & time series

Graph neural networks, spatiotemporal modelling and forecasting components.

+

Systems layer

SIMD operations, quantization, memory-conscious execution and serving helpers.

+
+
+ +
+

Build it like a C++ library.

+

No Python environment is required. CMake resolves xsimd and GoogleTest when they are not already installed.

+ 
git clone https://github.com/godofecht/tinyML.git
+cd tinyML
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+
+ +
+

There is a real playground behind the landing page.

+

The repository includes a C++ HTTP backend and browser UI for training and visualisation scenarios. The static Pages site stays dependency-free; the interactive playground runs locally against the native server.

+ 
cmake --build build --target PlaygroundServer --parallel
+./build/bin/PlaygroundServer
+# open http://localhost:8081
+
+ +
+

CI that checks correctness, not runner speed.

+

Pull requests and main-branch pushes build under GCC and Clang and run CTest. Wall-clock performance thresholds remain opt-in because shared CI machines are unsuitable benchmark hardware.

+
Open ActionsLicensingRoadmap
+
+
+ + +
+ +