feat(enhancement): LocalVQE AEC with safe streaming and benchmark validation (beta)

.github/workflows/localvqe-benchmark.yml

@@ -0,0 +1,119 @@
+name: LocalVQE Benchmark
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/workflows/localvqe-benchmark.yml'
+      - 'Sources/FluidAudio/Enhancement/**'
+      - 'Sources/FluidAudio/ASR/Parakeet/**'
+      - 'Sources/FluidAudio/Shared/Download/**'
+      - 'Sources/FluidAudio/ModelNames.swift'
+      - 'Sources/FluidAudio/ModelRegistry.swift'
+      - 'Sources/FluidAudioCLI/Commands/EnhanceBenchmark*.swift'
+      - 'Sources/FluidAudioCLI/Utils/WERCalculator.swift'
+      - 'Sources/FluidAudioCLI/Utils/TextNormalizer.swift'
+      - 'Tests/FluidAudioTests/CLI/EnhanceBenchmark*'
+      - 'Tests/FluidAudioTests/CLI/WERCalculatorTests.swift'
+      - 'Scripts/verify_localvqe_benchmark.py'
+      - 'Scripts/test_verify_localvqe_benchmark.py'
+      - 'Scripts/localvqe-dataset.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: localvqe-benchmark-${{ github.ref }}
+  cancel-in-progress: true
+
+# The 200-example run is ~7 min on an M5 Pro but far slower on the 3-core
+# macOS runner (a single job exceeded 60 min), so it is split into contiguous
+# shards that a final job merges and verifies as one 200-example report.
+env:
+  SHARD_COUNT: 5
+
+jobs:
+  regressions:
+    name: Scoring and manifest regressions
+    runs-on: macos-15
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      - name: Swift scorer / dataset / registry tests
+        run: swift test --filter 'EnhanceBenchmark|WERCalculatorTests|ModelRegistryTests'
+      - name: Python verifier tests
+        run: python3 Scripts/test_verify_localvqe_benchmark.py
+
+  shard:
+    name: Score shard ${{ matrix.shard }}
+    runs-on: macos-15
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [0, 1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Record environment
+        run: |
+          mkdir -p localvqe-results
+          {
+            git rev-parse HEAD
+            swift --version
+            xcodebuild -version
+            sw_vers
+            sysctl -n machdep.cpu.brand_string
+          } > localvqe-results/environment.txt
+
+      - name: Build release benchmark
+        run: swift build -c release --product fluidaudiocli
+
+      - name: Score shard ${{ matrix.shard }}/${{ env.SHARD_COUNT }} of the fixed 200-example dataset
+        run: |
+          set -o pipefail
+          .build/release/fluidaudiocli enhance-benchmark \
+            --variants v1.3,v1.2 --chunk 256ms --compute-units cpu-only \
+            --shard ${{ matrix.shard }}/${{ env.SHARD_COUNT }} \
+            --output localvqe-results/benchmark.json 2>&1 | tee localvqe-results/benchmark.log
+
+      - name: Upload shard evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: localvqe-shard-${{ matrix.shard }}-${{ github.sha }}
+          path: localvqe-results/
+          retention-days: 30
+
+  verify:
+    name: LocalVQE 200-example ASR benchmark
+    needs: [shard]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Download shard reports
+        uses: actions/download-artifact@v4
+        with:
+          pattern: localvqe-shard-*-${{ github.sha }}
+          path: shards
+
+      - name: Merge shards and verify coverage, scores and improvement over unprocessed audio
+        run: |
+          mkdir -p localvqe-results
+          ls shards/*/benchmark.json
+          python3 Scripts/verify_localvqe_benchmark.py shards/*/benchmark.json \
+            --merged localvqe-results/benchmark.json \
+            --expected-files 200 --require-improvement --markdown "$GITHUB_STEP_SUMMARY"
+          LOCALVQE_BENCHMARK_REPORT=localvqe-results/benchmark.json \
+            python3 Scripts/test_verify_localvqe_benchmark.py
+
+      - name: Upload merged benchmark evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: localvqe-benchmark-${{ github.sha }}
+          path: localvqe-results/
+          retention-days: 30

.github/workflows/tests.yml

@@ -24,8 +24,14 @@ jobs:
       - name: Build package
         run: swift build
 
-      - name: Run tests
-        run: swift test --parallel --num-workers $(sysctl -n hw.ncpu)
+      # Enrollment tests load the same Sortformer cache from separate XCTest
+      # workers. Serialize them on a cold runner to avoid racing .partial files.
+      - name: Run speaker enrollment tests serially
+        run: swift test --filter SpeakerEnrollmentTests
+        timeout-minutes: 20
+
+      - name: Run remaining tests
+        run: swift test --parallel --num-workers $(sysctl -n hw.ncpu) --skip SpeakerEnrollmentTests
         timeout-minutes: 20
 
   build-without-nemo-text-processing:
@@ -96,4 +102,4 @@ jobs:
           xcodebuild -scheme FluidAudio \
             -destination 'generic/platform=iOS' \
             -derivedDataPath .build \
-            build
+            build

Documentation/CLI.md

@@ -109,6 +109,32 @@ swift run fluidaudiocli vad-benchmark --all-files --output vad_results.json --de
 `swift run fluidaudiocli vad-analyze --help` lists every tuning option (padding,
 negative threshold overrides, max-duration splitting, etc.).
 
+## Speech Enhancement (LocalVQE)
+
+```bash
+# Echo cancellation + noise suppression: mic capture plus what the speaker played
+swift run -c release fluidaudiocli enhance mic.wav --reference speaker.wav --output clean.wav
+
+# Noise suppression / dereverb only (silent far end)
+swift run -c release fluidaudiocli enhance mic.wav --output clean.wav
+
+# Drive the streaming API in 256-sample buffers with the 16 ms export and report per-call latency
+swift run -c release fluidaudiocli enhance mic.wav -r speaker.wav --chunk 16ms --streaming --buffer-samples 256
+```
+
+`--variant v1.2` selects the 1.3M-param checkpoint, `--compute-units gpu`
+moves the model off the CPU, and `--model-dir DIR` loads local `.mlmodelc`
+bundles instead of downloading.
+
+```bash
+# Near-end word recall / WER / far-end leakage on the AEC-Challenge synthetic mini set (auto-downloads)
+swift run -c release fluidaudiocli enhance-benchmark
+swift run -c release fluidaudiocli enhance-benchmark --max-files 50 --variants v1.3 --no-reference --output results.json
+# Split the run across machines: contiguous shard i of n, then merge + verify the shard reports
+swift run -c release fluidaudiocli enhance-benchmark --shard 0/5 --output shard0.json
+python3 Scripts/verify_localvqe_benchmark.py shard*.json --merged results.json --expected-files 200
+```
+
 ## Datasets
 
 ```bash