feat: add Parakeet MLX sidecar integration

- Implement Parakeet MLX sidecar for offline transcription
- Add Python sidecar with Pydantic v2 compatibility
- Fix SegmentPayload structure for AlignedSentence handling
- Add build script for PyInstaller bundling
- Integrate with Tauri command system
- Add .gitignore for build artifacts

Author: moinulmoin

scripts/build-parakeet-sidecar.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build the Parakeet MLX sidecar as a standalone binary using uv + PyInstaller.
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+SIDECAR_DIR="$ROOT_DIR/sidecar/parakeet"
+DIST_DIR="$SIDECAR_DIR/dist"
+
+cd "$SIDECAR_DIR"
+
+# Ensure dependencies for the build group are installed
+uv sync --group build
+
+# Clean previous artifacts
+rm -rf "$DIST_DIR"
+
+# Build the single-file sidecar binary
+uv run --group build pyinstaller \
+  --clean \
+  --onefile \
+  --name parakeet-sidecar \
+  --hidden-import mlx._reprlib_fix \
+  --collect-submodules mlx \
+  --collect-submodules parakeet_mlx \
+  --collect-data parakeet_mlx \
+  --collect-data mlx \
+  src/parakeet_sidecar/main.py
+
+# Create a target-suffixed copy for Tauri bundling
+HOST_TRIPLE=$(rustc -vV | sed -n 's/^host: //p')
+BIN_PATH="$DIST_DIR/parakeet-sidecar"
+SUFFIXED_PATH="$DIST_DIR/parakeet-sidecar-$HOST_TRIPLE"
+
+if [[ -f "$BIN_PATH" ]];
+then
+  cp "$BIN_PATH" "$SUFFIXED_PATH"
+  echo "Created suffixed binary: $SUFFIXED_PATH"
+else
+  echo "ERROR: sidecar binary not found at $BIN_PATH" >&2
+  exit 1
+fi
+
+echo "Parakeet sidecar built at $DIST_DIR"

sidecar/parakeet/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.venv/
+venv/
+
+# PyInstaller build artifacts
+build/
+dist/
+*.spec
+
+# UV
+uv.lock
+.uv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

sidecar/parakeet/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "parakeet-sidecar"
+version = "0.1.0"
+description = "VoiceTypr Parakeet MLX transcription sidecar"
+authors = [{name = "VoiceTypr"}]
+requires-python = ">=3.11"
+dependencies = [
+  "parakeet-mlx>=0.3.0",
+  "mlx>=0.25.3",
+  "huggingface-hub>=0.23",
+  "soundfile>=0.12",
+  "numpy>=1.26",
+  "pydantic>=2.8",
+  "uvloop>=0.19; platform_system == 'Linux'",
+  "orjson>=3.10"
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.11"]
+build = ["pyinstaller>=6.8"]
+
+[project.scripts]
+parakeet-sidecar = "parakeet_sidecar.main:run"
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"

sidecar/parakeet/src/parakeet_sidecar/__init__.py

@@ -0,0 +1,5 @@
+"""Parakeet MLX transcription sidecar for VoiceTypr."""
+
+from .main import run  # re-export for entry point discovery
+
+__all__ = ["run"]

sidecar/parakeet/src/parakeet_sidecar/main.py

@@ -0,0 +1,183 @@
+"""Entry point for the Parakeet MLX transcription sidecar."""
+from __future__ import annotations
+
+import logging
+import signal
+import sys
+from typing import Any, Dict
+
+import orjson
+from pydantic import ValidationError
+
+from parakeet_sidecar.messages import (
+    CommandRequest,
+    ErrorResponse,
+    LoadModelRequest,
+    OkResponse,
+    ShutdownRequest,
+    StatusRequest,
+    StatusResponse,
+    TranscribeRequest,
+    TranscriptionResponse,
+    UnloadModelRequest,
+    parse_command,
+)
+from parakeet_sidecar.model_manager import ModelManager
+
+LOGGER = logging.getLogger("parakeet_sidecar")
+
+
+def configure_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+    )
+
+
+def write_response(response: Any) -> None:
+    try:
+        payload = orjson.dumps(response, default=_pydantic_default)
+    except Exception as exc:  # pragma: no cover - catastrophic failure
+        LOGGER.exception("Failed to serialise response: %s", exc)
+        payload = orjson.dumps(
+            ErrorResponse(message="Internal serialisation error", code="serialisation_error"),
+            default=_pydantic_default,
+        )
+    sys.stdout.buffer.write(payload + b"\n")
+    sys.stdout.flush()
+
+
+def _pydantic_default(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if hasattr(value, "dict"):
+        return value.dict()
+    raise TypeError(f"Object of type {type(value)} is not JSON serialisable")
+
+
+def handle_command(manager: ModelManager, command: CommandRequest) -> None:
+    try:
+        if isinstance(command, LoadModelRequest):
+            manager.load(command)
+            write_response(
+                OkResponse(
+                    command="load_model",
+                    payload={
+                        "model_id": command.model_id,
+                        "precision": command.precision,
+                        "attention": command.attention,
+                    },
+                )
+            )
+            return
+
+        if isinstance(command, UnloadModelRequest):
+            manager.unload()
+            write_response(OkResponse(command="unload_model"))
+            return
+
+        if isinstance(command, TranscribeRequest):
+            result = manager.transcribe(command)
+            write_response(result)
+            return
+
+        if isinstance(command, StatusRequest):
+            status = manager.status()
+            write_response(StatusResponse(**status))
+            return
+
+        if isinstance(command, ShutdownRequest):
+            manager.unload()
+            write_response(OkResponse(command="shutdown"))
+            raise SystemExit(0)
+
+    except FileNotFoundError as exc:
+        LOGGER.error("File not found: %s", exc)
+        write_response(
+            ErrorResponse(
+                code="file_not_found",
+                message=str(exc),
+            )
+        )
+    except ValidationError as exc:
+        LOGGER.error("Validation error: %s", exc)
+        write_response(
+            ErrorResponse(
+                code="validation_error",
+                message="Invalid command payload",
+                details={"errors": exc.errors()},
+            )
+        )
+    except RuntimeError as exc:
+        LOGGER.error("Runtime error: %s", exc)
+        write_response(
+            ErrorResponse(
+                code="runtime_error",
+                message=str(exc),
+            )
+        )
+    except Exception as exc:  # pragma: no cover - defensive
+        LOGGER.exception("Unhandled exception while processing command")
+        write_response(
+            ErrorResponse(
+                code="internal_error",
+                message=str(exc),
+            )
+        )
+
+
+def event_loop(manager: ModelManager) -> None:
+    for raw_line in sys.stdin:
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        try:
+            payload: Dict[str, Any] = orjson.loads(line)
+            command = parse_command(payload)
+        except ValidationError as exc:
+            LOGGER.error("Received invalid payload: %s", exc)
+            write_response(
+                ErrorResponse(
+                    code="validation_error",
+                    message="Invalid payload",
+                    details={"errors": exc.errors()},
+                )
+            )
+            continue
+        except ValueError as exc:
+            LOGGER.error("Failed to parse payload: %s", exc)
+            write_response(ErrorResponse(code="parse_error", message=str(exc)))
+            continue
+        except Exception as exc:  # pragma: no cover - defensive path
+            LOGGER.exception("Unexpected error decoding JSON")
+            write_response(ErrorResponse(code="parse_error", message=str(exc)))
+            continue
+
+        handle_command(manager, command)
+
+
+def _graceful_shutdown(signum: int, _frame: Any) -> None:  # pragma: no cover - signal path
+    LOGGER.info("Received signal %s, shutting down", signum)
+    raise SystemExit(0)
+
+
+def run() -> None:
+    configure_logging()
+    manager = ModelManager()
+
+    # Register signal handlers for graceful shutdown
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(sig, _graceful_shutdown)
+
+    try:
+        event_loop(manager)
+    except SystemExit:
+        pass
+    except Exception:  # pragma: no cover - ensure exit
+        LOGGER.exception("Fatal error running sidecar loop")
+        raise
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()