Fix TensorFlow/Keras 3 compatibility for exported .h5 models

.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+name: Deploy Docs
+
+# Builds the mkdocs site and deploys it to GitHub Pages.
+#
+# One-time setup required before this workflow can deploy: in the repo
+# Settings -> Pages -> "Build and deployment" -> Source, switch it from
+# "Deploy from a branch" to "GitHub Actions". Until that switch is made,
+# this workflow will build the site successfully but the deploy job will
+# fail (Pages is still serving from the legacy `documentation` branch).
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "requirements.txt"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install mkdocs "mkdocstrings[python]"
+
+      # mkdocstrings imports the package to pull in its docstrings, so
+      # `python -m mkdocs` (not the bare `mkdocs` entry point) is used to
+      # make sure the repo root (and therefore `src/`) is on sys.path.
+      - name: Build site
+        run: python -m mkdocs build --site-dir _site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+# Triggered when a GitHub Release is published (create a Release from a
+# version tag, e.g. v1.3.0). Uses PyPI Trusted Publishing (OIDC) — no
+# API token needs to be stored as a secret.
+#
+# One-time setup required on PyPI before this workflow can publish:
+#   https://pypi.org/manage/project/teachable_machine/settings/publishing/
+#   Add a trusted publisher with:
+#     Owner:      MeqdadDev
+#     Repository: teachable-machine
+#     Workflow:   publish.yml
+#     Environment: pypi
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/teachable_machine/
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run tests
+        run: pytest -v

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.3.0]
+
+### Fixed
+
+- **TensorFlow/Keras 3 compatibility**: Teachable Machine's exported `.h5` models embed a legacy `DepthwiseConv2D` layer config (`'groups': 1`) that current Keras (Keras 3, bundled by default since TensorFlow 2.16) rejects during deserialization, causing model loading to fail with `TypeError`/`ValueError: Unrecognized keyword arguments passed to DepthwiseConv2D: {'groups': 1}`. `TeachableMachine` now loads models with a compatibility shim that discards the unused key, so exported models work on up-to-date TensorFlow/Keras installs without pinning an old TensorFlow version. Fixes [#2](https://github.com/MeqdadDev/teachable-machine/issues/2).
+
+### Changed
+
+- `install_requires` now specifies `tensorflow>=2.16` (previously unpinned, which could silently resolve to a broken combination).
+- `python_requires` raised to `>=3.9` to match current TensorFlow's supported Python range; removed unsupported 3.7/3.8 classifiers.
+- `requirements.txt` (dev/test) updated to current dependency versions and now includes `pytest`, `pytest-mock`, and `h5py`.
+
+### Added
+
+- Regression tests covering the legacy `DepthwiseConv2D` config shape, including an end-to-end test that saves a model, tampers its config to reproduce Teachable Machine's legacy export, and verifies it still loads and classifies correctly.
+- CI workflow to run the test suite on pushes/PRs, and a release workflow to publish to PyPI on tagged GitHub releases.
+
+## [1.2.1] - 2024-08-18
+
+- Added `setup.py` for packaging.
+
+## [1.2.0]
+
+- Added package logo, expanded documentation (how-to guide, requirements, code examples), and unit tests.
+
+## [1.1] and [1.0]
+
+- Initial releases of the `TeachableMachine` class for image classification with exported Keras models.

README.md

@@ -23,9 +23,19 @@ Read more about the project (requirements, installation, examples and more) in t
 
 **Image Classification**: use exported keras model from Teachable Machine platform.
 
+## Compatibility with recent TensorFlow/Keras releases
+
+Teachable Machine's exported `.h5` models embed a legacy `DepthwiseConv2D` layer config that current Keras (Keras 3, bundled by default since TensorFlow 2.16) rejects with an error such as:
+
+```
+TypeError: Unrecognized keyword arguments passed to DepthwiseConv2D: {'groups': 1}
+```
+
+Since `v1.3.0`, this package patches the model loader so exported models load correctly on up-to-date TensorFlow/Keras installs, with no need to pin an old TensorFlow version. See [issue #2](https://github.com/MeqdadDev/teachable-machine/issues/2) for background.
+
 ## Requirements
 
-``` Python >= 3.7 ```
+``` Python >= 3.9 ```
 
 ## How to install package
 

docs/changelog.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.3.0]
+
+### Fixed
+
+- **TensorFlow/Keras 3 compatibility**: Teachable Machine's exported `.h5` models embed a legacy `DepthwiseConv2D` layer config (`'groups': 1`) that current Keras (Keras 3, bundled by default since TensorFlow 2.16) rejects during deserialization, causing model loading to fail with `TypeError`/`ValueError: Unrecognized keyword arguments passed to DepthwiseConv2D: {'groups': 1}`. `TeachableMachine` now loads models with a compatibility shim that discards the unused key, so exported models work on up-to-date TensorFlow/Keras installs without pinning an old TensorFlow version. Fixes [#2](https://github.com/MeqdadDev/teachable-machine/issues/2).
+
+### Changed
+
+- `install_requires` now specifies `tensorflow>=2.16` (previously unpinned, which could silently resolve to a broken combination).
+- `python_requires` raised to `>=3.9` to match current TensorFlow's supported Python range; removed unsupported 3.7/3.8 classifiers.
+- `requirements.txt` (dev/test) updated to current dependency versions and now includes `pytest`, `pytest-mock`, and `h5py`.
+
+### Added
+
+- Regression tests covering the legacy `DepthwiseConv2D` config shape, including an end-to-end test that saves a model, tampers its config to reproduce Teachable Machine's legacy export, and verifies it still loads and classifies correctly.
+- CI workflow to run the test suite on pushes/PRs, and a release workflow to publish to PyPI on tagged GitHub releases.
+
+## [1.2.1] - 2024-08-18
+
+- Added `setup.py` for packaging.
+
+## [1.2.0]
+
+- Added package logo, expanded documentation (how-to guide, requirements, code examples), and unit tests.
+
+## [1.1] and [1.0]
+
+- Initial releases of the `TeachableMachine` class for image classification with exported Keras models.

docs/index.md

@@ -29,6 +29,16 @@ Source Code is published on [GitHub](https://github.com/MeqdadDev/teachable-mach
 
 **Image Classification**
 
+## Compatibility with recent TensorFlow/Keras releases
+
+Teachable Machine's exported `.h5` models embed a legacy `DepthwiseConv2D` layer config that current Keras (Keras 3, bundled by default since TensorFlow 2.16) rejects with an error such as:
+
+```
+TypeError: Unrecognized keyword arguments passed to DepthwiseConv2D: {'groups': 1}
+```
+
+Since `v1.3.0`, this package patches the model loader so exported models load correctly on up-to-date TensorFlow/Keras installs, with no need to pin an old TensorFlow version. See [issue #2](https://github.com/MeqdadDev/teachable-machine/issues/2) for background.
+
 ## Links
 
 - [PyPI](https://pypi.org/project/teachable-machine/)

docs/requirements.md

@@ -1,12 +1,22 @@
 ## Requirements
 
 ### Python Version
-``` Python >= 3.7 ```
+``` Python >= 3.9 ```
 
 ### Dependencies
 
 ```bash
 numpy
 Pillow
-tensorflow
+tensorflow>=2.16
 ```
+
+## Compatibility with recent TensorFlow/Keras releases
+
+Teachable Machine's exported `.h5` models embed a legacy `DepthwiseConv2D` layer config that current Keras (Keras 3, bundled by default since TensorFlow 2.16) rejects with an error such as:
+
+```
+TypeError: Unrecognized keyword arguments passed to DepthwiseConv2D: {'groups': 1}
+```
+
+Since `v1.3.0`, this package patches the model loader so exported models load correctly on up-to-date TensorFlow/Keras installs, with no need to pin an old TensorFlow version. See [issue #2](https://github.com/MeqdadDev/teachable-machine/issues/2) for background.

mkdocs.yml

@@ -12,4 +12,5 @@ nav:
   - Requirements: requirements.md
   - Code Examples: codeExamples.md
   - Explanation: explanation.md
+  - Changelog: changelog.md
   - Contributing: contribution.md

setup.py

@@ -5,15 +5,13 @@
 
 setup(
     name="teachable_machine",
-    version="1.2.1",
+    version="1.3.0",
     description="A Python package designed to simplify the integration of exported models from Google's Teachable Machine platform into various environments. \
     This tool was specifically crafted to work seamlessly with Teachable Machine, making it easier to implement and use your trained models.",
     py_modules=["teachable_machine"],
     package_dir={"": "src"},
     classifiers=[
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
@@ -30,9 +28,9 @@
     install_requires=[
         "numpy",
         "Pillow",
-        "tensorflow",
+        "tensorflow>=2.16",
     ],
-    python_requires=">=3.7",
+    python_requires=">=3.9",
     url="https://github.com/MeqdadDev/teachable-machine",
     author="Meqdad Dev",
     author_email="[email protected]",