nodetool-mlx 0.7.0__tar.gz

nodetool_mlx-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# A new push to a PR makes the in-flight run obsolete.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install linters
+        # Pinned: an unpinned linter turns an upstream release into a red build
+        # on an unrelated PR. Bump deliberately, fixing any new findings in the
+        # same change. Keep in sync with requirements-dev.txt.
+        run: pip install "ruff==0.15.8" "black==26.3.1"
+
+      - name: ruff
+        run: ruff check .
+
+      - name: black
+        run: black --check --diff .
+
+  # The MLX runtimes (mlx, mflux, mlx-audio, ...) are Apple Silicon only, so the
+  # bulk of the suite is written to run without them and this job installs the
+  # package with --no-deps. It is the fast signal on every push, and it also
+  # covers the "node modules import without the MLX stack" property that the
+  # package metadata scanner relies on.
+  test-linux:
+    name: Test (linux, no MLX runtime)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install nodetool-core and test dependencies
+        run: |
+          pip install --upgrade pip
+          pip install "nodetool-core>=0.7.0"
+          pip install pytest pytest-asyncio pytest-cov
+
+      - name: Install this package without the Apple-Silicon-only dependencies
+        run: pip install --no-deps -e .
+
+      - name: Run tests
+        # Tests needing mflux / mlx-audio skip themselves via importorskip.
+        run: pytest tests -q
+
+  # The real thing: Apple Silicon runners install the full dependency set, so
+  # nothing is skipped here. Slower and heavier, hence a single Python version.
+  test-macos:
+    name: Test (macOS, full MLX runtime)
+    runs-on: macos-14
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package with all dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-asyncio pytest-cov
+
+      - name: Show installed MLX stack
+        run: pip list | grep -Ei "^(mlx|mflux|nodetool)" || true
+
+      - name: Run tests
+        run: pytest tests -q
+
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tooling
+        run: pip install --upgrade pip build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distributions
+        run: twine check dist/*

nodetool_mlx-0.7.0/.github/workflows/publish-wheel.yml

@@ -0,0 +1,230 @@
+name: Build and Publish Wheel
+
+on:
+  # Trigger on version tags
+  push:
+    tags:
+      - "v*.*.*"
+
+  # Manual trigger for testing
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g., 0.6.0)"
+        required: true
+        type: string
+      prerelease:
+        description: "Mark as prerelease"
+        required: false
+        default: false
+        type: boolean
+      publish_pypi:
+        description: "Also publish to PyPI / TestPyPI"
+        required: false
+        default: "none"
+        type: choice
+        options:
+          - none
+          - testpypi
+          - pypi
+
+env:
+  PACKAGE_NAME: ${{ github.event.repository.name }} # e.g., "nodetool-base"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get-version.outputs.version }}
+      tag-name: ${{ steps.get-version.outputs.tag-name }}
+      is-prerelease: ${{ steps.get-version.outputs.is-prerelease }}
+    steps:
+      - name: Get version from tag or input
+        id: get-version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+            TAG_NAME="v${VERSION}"
+            IS_PRERELEASE="${{ github.event.inputs.prerelease }}"
+          else
+            TAG_NAME="${{ github.ref_name }}"
+            VERSION="${TAG_NAME#v}"
+            IS_PRERELEASE="false"
+          fi
+
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag-name=$TAG_NAME" >> $GITHUB_OUTPUT
+          echo "is-prerelease=$IS_PRERELEASE" >> $GITHUB_OUTPUT
+
+          echo "📋 Version: $VERSION"
+          echo "🏷️ Tag: $TAG_NAME"
+          echo "🔄 Prerelease: $IS_PRERELEASE"
+
+  build-wheel:
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.validate.outputs.tag-name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          pip install --upgrade pip
+          pip install build hatchling twine
+
+      - name: Download build helper
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/nodetool-ai/nodetool-core/main/build.py -o build.py
+
+      - name: Build wheel
+        run: |
+          echo "🏗️ Building wheel for ${{ env.PACKAGE_NAME }}"
+          python build.py build-wheel --expected-version "${{ needs.validate.outputs.version }}"
+
+      - name: Validate wheel
+        run: |
+          python build.py validate-wheel
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheel-${{ env.PACKAGE_NAME }}-${{ needs.validate.outputs.version }}
+          path: |
+            dist/*.whl
+            dist/*.whl.metadata
+          retention-days: 30
+
+  create-release:
+    needs: [validate, build-wheel]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.validate.outputs.tag-name }}
+
+      - name: Download build helper
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/nodetool-ai/nodetool-core/main/build.py -o build.py
+
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: wheel-${{ env.PACKAGE_NAME }}-${{ needs.validate.outputs.version }}
+          path: dist/
+
+      - name: Generate release notes
+        run: |
+          python build.py release-notes \
+            --package "${{ env.PACKAGE_NAME }}" \
+            --version "${{ needs.validate.outputs.version }}" \
+            --tag "${{ needs.validate.outputs.tag-name }}" \
+            --repository "${{ github.repository }}" \
+            --server-url "${{ github.server_url }}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ needs.validate.outputs.tag-name }}
+          name: "${{ env.PACKAGE_NAME }} v${{ needs.validate.outputs.version }}"
+          body_path: release_notes.md
+          files: |
+            dist/*.whl
+            dist/*.whl.metadata
+          draft: false
+          prerelease: ${{ needs.validate.outputs.is-prerelease }}
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Notify registry
+        if: success()
+        env:
+          REGISTRY_UPDATE_TOKEN: ${{ secrets.REGISTRY_UPDATE_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python build.py notify-registry \
+            --package "${{ env.PACKAGE_NAME }}" \
+            --version "${{ needs.validate.outputs.version }}" \
+            --tag "${{ needs.validate.outputs.tag-name }}" \
+            --repository "${{ github.repository }}" \
+            --server-url "${{ github.server_url }}"
+
+      - name: Create success summary
+        run: |
+          python build.py summary \
+            --package "${{ env.PACKAGE_NAME }}" \
+            --version "${{ needs.validate.outputs.version }}" \
+            --tag "${{ needs.validate.outputs.tag-name }}" \
+            --repository "${{ github.repository }}" \
+            --server-url "${{ github.server_url }}"
+
+  # Publish to PyPI via Trusted Publishing (OIDC). No stored tokens.
+  # Runs on every v*.*.* tag push, or a manual run with publish_pypi=pypi.
+  # PyPI pending publisher: workflow publish-wheel.yml, environment pypi.
+  publish-pypi:
+    needs: [validate, build-wheel]
+    if: github.event_name == 'push' || github.event.inputs.publish_pypi == 'pypi'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/nodetool-mlx/
+    permissions:
+      id-token: write # required for OIDC trusted publishing
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.validate.outputs.tag-name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Manual-only TestPyPI dry run (publish_pypi=testpypi).
+  publish-testpypi:
+    needs: [validate, build-wheel]
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish_pypi == 'testpypi'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/nodetool-mlx/
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.validate.outputs.tag-name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

nodetool_mlx-0.7.0/.gitignore

@@ -0,0 +1,56 @@
+__pycache__
+*.pyc
+*.pyo
+*.dmypy.json
+*.jar
+.mypy_cache
+*.egg-info
+*.egg
+*.pth
+*.torchscript
+*.ckpt
+*.gguf
+*.pt
+*.pth
+*.safetensors
+build/
+dist/
+electron/apps/build/
+electron/dist/
+electron/dist-web/
+electron/dist-electron/
+# Temporary build files
+.tmp/
+__notebooks/
+package/
+postgres_data/
+.ipynb_checkpoints
+.huggingface
+
+.bin
+.vite
+.venv
+node_modules
+docs.chromadb
+
+# Cache
+.cache
+.eslintcache
+
+# Testing
+/coverage
+*.lcov
+
+# Environment variables
+*.override.env
+
+# macOS
+# https://github.com/github/gitignore/blob/master/Global/macOS.gitignore
+.DS_Store
+
+.env
+cert.pem
+key.pem
+.aider*
+
+.codegpt

nodetool_mlx-0.7.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: nodetool-mlx
+Version: 0.7.0
+Summary: Apple Silicon MLX nodes for Nodetool
+Author-email: Matthias Georgi <matti.georgi@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: huggingface-hub>=0.24.6
+Requires-Dist: mflux>=0.18.1
+Requires-Dist: mlx-audio>=0.4.4
+Requires-Dist: mlx-lm>=0.31.3
+Requires-Dist: mlx-vlm>=0.4.4
+Requires-Dist: mlx-whisper>=0.4.3
+Requires-Dist: mlx>=0.30
+Requires-Dist: nodetool-core>=0.7.0
+Requires-Dist: numba>=0.62.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: sentencepiece>=0.2
+Provides-Extra: dev
+Requires-Dist: black>=24.10.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.4; extra == 'dev'
+Provides-Extra: stable
+Requires-Dist: nodetool-core==0.7.0; extra == 'stable'
+Description-Content-Type: text/markdown
+
+# nodetool-mlx
+
+[![CI](https://github.com/nodetool-ai/nodetool-mlx/actions/workflows/ci.yml/badge.svg)](https://github.com/nodetool-ai/nodetool-mlx/actions/workflows/ci.yml)
+
+High-performance MLX-native nodes for [Nodetool](https://github.com/nodetool-ai/nodetool) on Apple Silicon. This package wraps the community MLX implementations of Whisper, Kokoro/Sesame TTS, MFlux FLUX.1 image generation, and Stability AI's Stable Audio 3 so you can run state-of-the-art audio and vision workflows locally on macOS.
+
+## Why nodetool-mlx?
+
+- **Local-first** – keep data on-device by running speech, TTS, and image models without cloud calls
+- **Optimised for Apple Silicon** – uses MLX kernels and quantized checkpoints to achieve strong throughput on M-series chips
+- **Drop-in nodes** – integrates seamlessly with the Nodetool graph editor and `nodetool-core` runtime
+
+## Provided Nodes
+
+All nodes live under `src/nodetool/nodes/mlx`. Audio nodes wrap the
+[`mlx-audio`](https://github.com/Blaizzy/mlx-audio) library.
+
+### Text-to-Speech (`mlx.text_to_speech`)
+
+- `KokoroTTS` – fast multilingual TTS with 54 voice presets
+- `SesameTTS` – CSM voice cloning from a reference clip
+- `SparkTTS` – controllable speed / pitch / gender presets
+- `Qwen3TTS` – multilingual TTS with speaker voices and voice design
+- `KittenTTS` – compact, edge-friendly English voices
+- `DiaTTS` – dialogue TTS with `[S1]` / `[S2]` speaker tags
+- `OuteTTS` – efficient multilingual TTS with optional cloning
+- `OmniVoiceTTS` – zero-shot multilingual (646+ languages)
+- `MeloTTS` – lightweight VITS2 English accents
+- `VoxtralTTS` – Mistral's multilingual TTS with voice presets
+- `ChatterboxTTS` – expressive TTS with exaggeration control and cloning
+- `HiggsAudioTTS` – conversational TTS with zero-shot cloning
+- `LongCatAudioTTS` – diffusion TTS with zero-shot cloning
+- `MLXTextToSpeech` – generic node that runs any `mlx-audio` TTS repo id
+
+### Speech-to-Text (`mlx.automatic_speech_recognition`, `mlx.speech_to_text`)
+
+- `Whisper` – MLX Whisper transcription with optional word timestamps
+- `Parakeet` – NVIDIA Parakeet high-accuracy multilingual ASR
+- `Qwen3ASR` – Alibaba's multilingual ASR with long-form chunking
+- `Qwen3ForcedAligner` – word-level timestamp alignment for a known transcript
+- `MLXSpeechToText` – generic node that runs any `mlx-audio` STT repo id
+
+### Speech Enhancement (`mlx.speech_enhancement`)
+
+- `DeepFilterNet` – real-time noise suppression (v1/v2/v3) at 48 kHz
+- `MossFormer2` – high-quality 48 kHz speech enhancement
+
+### Image (`mlx.text_to_image`, `mlx.image_to_image`)
+
+- `MFlux` and the `MFlux*` family – FLUX.1 / Qwen-Image / Z-Image / FIBO generation
+  and editing via the MFlux project (supports quantized models)
+
+### Image-to-Text (`mlx.image_to_text`)
+
+- `MLXVisionLanguage` – image captioning, visual Q&A, and OCR via MLX vision-language models (Qwen3-VL, Gemma 4)
+
+### Text-to-Audio (`mlx.text_to_audio`)
+
+- `StableAudio3` – text-to-audio music & sound effects with [Stable Audio 3](https://github.com/Stability-AI/stable-audio-3) (44.1 kHz stereo)
+- `StableAudio3AudioToAudio` – prompt-guided variations of an input clip
+- `StableAudio3Inpaint` – regenerate a time range inside an audio clip
+
+### Text-to-Music (`mlx.text_to_music`)
+
+- `ACEStepMusicGeneration` – local text-to-music generation with [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) (prompt + lyrics → full songs)
+- `ACEStepSongPlanner` – use the ACE-Step 5Hz language model to turn an idea into a caption, lyrics and musical metadata
+
+### Text (`mlx.text_generation`)
+
+- `TextGeneration` – local LLM text generation via `mlx-lm`
+
+### Stable Audio 3
+
+The Stable Audio 3 nodes run Stability AI's optimized MLX implementation (no PyTorch at
+runtime), vendored under `nodetool.mlx.stable_audio_3` (MIT licensed — see that folder's
+`LICENSE` and `NOTICE.md`). Three DiT variants are available via the **model** field:
+
+- `sm-music` (50M) – fast music generation
+- `sm-sfx` (50M) – sound effects
+- `medium` (1.4B) – higher-fidelity music
+
+Weights are pulled on demand from the Hugging Face repo
+[`stabilityai/stable-audio-3-optimized`](https://huggingface.co/stabilityai/stable-audio-3-optimized)
+(only the `MLX/*` files) and cached locally; you can also pre-download them from the
+Models Manager.
+
+### ACE-Step 1.5 (music generation)
+
+The ACE-Step nodes wrap the official [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5)
+project, which uses MLX for the diffusion transformer, VAE and language model on
+Apple Silicon. ACE-Step 1.5 is **not** distributed on PyPI (the `ace-step` package
+there is the older 1.0 release), so it must be installed separately:
+
+```bash
+git clone https://github.com/ace-step/ACE-Step-1.5.git
+cd ACE-Step-1.5
+uv sync   # installs the macOS/MLX dependencies
+```
+
+Install it into the same environment as `nodetool-mlx`. If the package is missing,
+the nodes raise a clear error pointing back to the repository.
+
+Checkpoints are downloaded automatically from HuggingFace on first use into
+`~/.cache/nodetool/acestep/checkpoints` (override with the `ACESTEP_CHECKPOINTS_DIR`
+environment variable). The main bundle `ACE-Step/Ace-Step1.5` includes the VAE, the
+turbo DiT and the 1.7B planner LM; additional DiT and LM checkpoints are listed as
+recommended models on each node.
+
+
+## Requirements
+
+- macOS 14+ on Apple Silicon (MLX currently supports Apple hardware only)
+- Python 3.11
+- [nodetool-core](https://github.com/nodetool-ai/nodetool-core) v0.6.0+
+- Required MLX checkpoints managed via the Nodetool Models Manager (see [_Managing Models_](#managing-models))
+
+## Installation
+
+### From the Nodetool UI
+
+1. Open Nodetool → **Tools ▸ Packages**
+2. Install the `nodetool-mlx` pack from the package registry
+3. Nodetool will handle dependencies and expose the MLX nodes in the graph editor once installed
+
+### From source (development)
+
+```bash
+git clone https://github.com/nodetool-ai/nodetool-mlx.git
+cd nodetool-mlx
+uv pip install -e .
+uv pip install -r requirements-dev.txt
+```
+
+If you prefer Poetry or pip, install the project the same way—just ensure dependencies are resolved against Python 3.11.
+
+## Managing Models
+
+All MLX nodes rely on locally cached checkpoints. The recommended way to download and update them is through the **Models Manager** built into Nodetool:
+
+1. Open Nodetool → **Menu ▸ Models**
+2. Select the `mlx` tab to view the recommended checkpoints for each node
+3. Click **Download** for the models you plan to use; Nodetool stores them in the Hugging Face cache automatically
+4. The UI will keep track of model availability and prompt you when updates are available
+
+Advanced users can still seed the Hugging Face cache manually, but using the UI integration ensures consistent paths and avoids missing-model errors in workflows.
+
+## Usage
+
+1. Install `nodetool-core` and this package in the same environment
+2. Run `nodetool-pkg scan --write --enrich` to generate package metadata
+3. Build workflows in the Nodetool UI using the `mlx` nodes
+
+## Development
+
+Run tests and lint checks before submitting PRs:
+
+```bash
+pytest -q
+ruff check .
+black --check .
+```
+
+Most of the suite is written to run on any platform: the MLX runtimes are
+imported lazily and the node logic is exercised against mocks. The handful of
+tests that need `mflux` or `mlx-audio` skip themselves when those Apple Silicon
+packages are unavailable, so a Linux run reports skips rather than failures.
+
+If you change a node's `get_recommended_models()`, regenerate the committed
+package metadata:
+
+```bash
+nodetool-pkg scan --write --enrich
+```
+
+`tests/test_package_metadata.py` fails when the two drift apart — the Nodetool
+UI reads that file to populate the model picker, so a stale entry becomes a
+model users cannot select or a download offer for a repository that no longer
+exists.
+
+### Continuous integration
+
+`.github/workflows/ci.yml` runs on every pull request:
+
+| Job | Runner | What it covers |
+| --- | --- | --- |
+| Lint and format | ubuntu | `ruff check .` and `black --check .` |
+| Test (linux) | ubuntu, Python 3.11 + 3.12 | the platform-independent suite, installed with `--no-deps` |
+| Test (macOS) | macos-14 (Apple Silicon) | the full suite against the real MLX stack |
+| Build wheel | ubuntu | `python -m build` plus `twine check` |
+
+Please open issues or pull requests for bug fixes, new MLX models, or performance improvements. Contributions are welcome!