birdword 0.1.0__tar.gz

birdword-0.1.0/.github/workflows/main.yaml

@@ -0,0 +1,30 @@
+name: CI / Publish
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run python -c "from birdword.cli import main; print('OK')"
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: check
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

birdword-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

birdword-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

birdword-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Till Hoffmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

birdword-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: birdword
+Version: 0.1.0
+Summary: Voice dictation daemon using NVIDIA Parakeet on Apple Silicon
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mlx-audio
+Requires-Dist: numpy
+Requires-Dist: pyobjc-core
+Requires-Dist: pyobjc-framework-cocoa
+Requires-Dist: pyobjc-framework-quartz
+Requires-Dist: sounddevice
+Description-Content-Type: text/markdown
+
+# 🐦 Birdword
+
+Contextual voice dictation for macOS. Powered by [NVIDIA Parakeet](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2) running locally on Apple Silicon via [MLX](https://github.com/ml-explore/mlx).
+
+Press a hotkey, speak, and your words are transcribed and pasted into whatever app is focused. A small LLM (Qwen2.5-0.5B) post-processes the transcription to fix errors, optionally using project-specific context from a `BIRDWORD.md` file.
+
+## Install
+
+```
+pip install birdword
+```
+
+Or run without installing:
+
+```
+uvx birdword
+```
+
+Requires macOS on Apple Silicon (M1+) and Python 3.10+.
+
+## Usage
+
+```bash
+# Run in the foreground
+birdword
+
+# Run in the background
+birdword start
+birdword stop
+birdword status
+```
+
+### Hotkeys
+
+| Action | Default |
+|---|---|
+| Toggle recording | Right ⌘ + Space |
+| Hold to record | Hold Right ⌘ for >1s, release to transcribe |
+
+### Options
+
+```
+--model MODEL        Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)
+--fix-model MODEL    Post-processor model (default: mlx-community/Qwen2.5-0.5B-Instruct-4bit)
+--no-fix             Disable LLM post-processing
+--hold-key KEY       Hold key (default: rcmd). Options: rcmd, lcmd, ralt, lalt, rshift, lshift, rctrl, lctrl
+--toggle-key KEY     Toggle key (default: space). Options: space, return, tab, escape
+```
+
+## Permissions
+
+Birdword needs three macOS permissions, granted to your terminal app:
+
+- **Microphone** — to record your voice
+- **Accessibility** — to paste text and intercept the hotkey
+- **Input Monitoring** — to detect the global hotkey
+
+Birdword checks these on startup and tells you what's missing.
+
+## Context-aware correction
+
+Drop a `BIRDWORD.md` file in your project directory with domain-specific terms, names, and jargon:
+
+```markdown
+This is a Rust networking project using tokio and hyper.
+
+Key terms: epoll, mio, AsyncRead, TcpListener
+Names: Till
+```
+
+When you dictate into a Terminal tab whose shell is in that directory (or a child), birdword feeds this context to the post-processor so it knows not to "correct" your domain terms.
+
+## Menu bar
+
+Birdword shows a bird icon in the menu bar:
+
+- **White** — idle
+- **Yellow** — connecting mic
+- **Red** — listening
+- **✨ Sparkles** — transcribing
+
+## License
+
+MIT

birdword-0.1.0/README.md

@@ -0,0 +1,84 @@
+# 🐦 Birdword
+
+Contextual voice dictation for macOS. Powered by [NVIDIA Parakeet](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2) running locally on Apple Silicon via [MLX](https://github.com/ml-explore/mlx).
+
+Press a hotkey, speak, and your words are transcribed and pasted into whatever app is focused. A small LLM (Qwen2.5-0.5B) post-processes the transcription to fix errors, optionally using project-specific context from a `BIRDWORD.md` file.
+
+## Install
+
+```
+pip install birdword
+```
+
+Or run without installing:
+
+```
+uvx birdword
+```
+
+Requires macOS on Apple Silicon (M1+) and Python 3.10+.
+
+## Usage
+
+```bash
+# Run in the foreground
+birdword
+
+# Run in the background
+birdword start
+birdword stop
+birdword status
+```
+
+### Hotkeys
+
+| Action | Default |
+|---|---|
+| Toggle recording | Right ⌘ + Space |
+| Hold to record | Hold Right ⌘ for >1s, release to transcribe |
+
+### Options
+
+```
+--model MODEL        Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)
+--fix-model MODEL    Post-processor model (default: mlx-community/Qwen2.5-0.5B-Instruct-4bit)
+--no-fix             Disable LLM post-processing
+--hold-key KEY       Hold key (default: rcmd). Options: rcmd, lcmd, ralt, lalt, rshift, lshift, rctrl, lctrl
+--toggle-key KEY     Toggle key (default: space). Options: space, return, tab, escape
+```
+
+## Permissions
+
+Birdword needs three macOS permissions, granted to your terminal app:
+
+- **Microphone** — to record your voice
+- **Accessibility** — to paste text and intercept the hotkey
+- **Input Monitoring** — to detect the global hotkey
+
+Birdword checks these on startup and tells you what's missing.
+
+## Context-aware correction
+
+Drop a `BIRDWORD.md` file in your project directory with domain-specific terms, names, and jargon:
+
+```markdown
+This is a Rust networking project using tokio and hyper.
+
+Key terms: epoll, mio, AsyncRead, TcpListener
+Names: Till
+```
+
+When you dictate into a Terminal tab whose shell is in that directory (or a child), birdword feeds this context to the post-processor so it knows not to "correct" your domain terms.
+
+## Menu bar
+
+Birdword shows a bird icon in the menu bar:
+
+- **White** — idle
+- **Yellow** — connecting mic
+- **Red** — listening
+- **✨ Sparkles** — transcribing
+
+## License
+
+MIT

birdword-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "birdword"
+version = "0.1.0"
+description = "Voice dictation daemon using NVIDIA Parakeet on Apple Silicon"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "mlx-audio",
+    "sounddevice",
+    "numpy",
+    "pyobjc-core",
+    "pyobjc-framework-Cocoa",
+    "pyobjc-framework-Quartz",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/birdword"]
+
+[project.scripts]
+birdword = "birdword.cli:main"

birdword-0.1.0/src/birdword/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m birdword."""
+
+from birdword.cli import main
+
+main()

birdword-0.1.0/src/birdword/cli.py

@@ -0,0 +1,205 @@
+"""CLI entry point for birdword."""
+
+import argparse
+import os
+import signal
+import subprocess
+import sys
+
+PIDFILE = os.path.expanduser("~/.birdword.pid")
+
+
+def _read_pid() -> int | None:
+    """Read PID from pidfile, return None if stale or missing."""
+    try:
+        with open(PIDFILE) as f:
+            pid = int(f.read().strip())
+        # Check if process is actually running
+        os.kill(pid, 0)
+        return pid
+    except (FileNotFoundError, ValueError, ProcessLookupError, PermissionError):
+        # Clean up stale pidfile
+        try:
+            os.unlink(PIDFILE)
+        except FileNotFoundError:
+            pass
+        return None
+
+
+def _write_pid():
+    """Write current PID to pidfile."""
+    with open(PIDFILE, "w") as f:
+        f.write(str(os.getpid()))
+
+
+def _remove_pid():
+    """Remove pidfile."""
+    try:
+        os.unlink(PIDFILE)
+    except FileNotFoundError:
+        pass
+
+
+def _check_permissions() -> bool:
+    """Check permissions, blocking until resolved."""
+    from birdword.permissions import verify_permissions
+
+    if not verify_permissions():
+        print("   Fix permissions above, then try again.")
+        return False
+    return True
+
+
+def _run_daemon(args):
+    """Run the daemon (blocking). Enforces singleton."""
+    existing = _read_pid()
+    if existing is not None:
+        print(f"🐦 Birdword is already running (pid {existing}).")
+        sys.exit(1)
+
+    if not _check_permissions():
+        sys.exit(1)
+
+    _write_pid()
+    try:
+        from birdword.daemon import Daemon
+
+        daemon = Daemon(
+            model_id=args.model,
+            fix_model_id=args.fix_model,
+            no_fix=args.no_fix,
+            hold_key=args.hold_key,
+            toggle_key=args.toggle_key,
+        )
+        daemon.run()
+    finally:
+        _remove_pid()
+
+
+def _cmd_start(args):
+    """Start birdword in the background."""
+    existing = _read_pid()
+    if existing is not None:
+        print(f"🐦 Birdword is already running (pid {existing}).")
+        return
+
+    # Check permissions in the foreground first
+    if not _check_permissions():
+        sys.exit(1)
+
+    print("🐦 Starting birdword in the background...")
+
+    # Build the command to run ourselves in blocking mode
+    cmd = [sys.executable, "-m", "birdword"]
+    if args.model:
+        cmd += ["--model", args.model]
+    if args.fix_model:
+        cmd += ["--fix-model", args.fix_model]
+    if args.no_fix:
+        cmd.append("--no-fix")
+    if args.hold_key != "rcmd":
+        cmd += ["--hold-key", args.hold_key]
+    if args.toggle_key != "space":
+        cmd += ["--toggle-key", args.toggle_key]
+
+    # Launch detached subprocess
+    log_path = os.path.expanduser("~/.birdword.log")
+    log_file = open(log_path, "a")
+
+    proc = subprocess.Popen(
+        cmd,
+        stdout=log_file,
+        stderr=log_file,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+    # Wait briefly to make sure it didn't crash immediately
+    try:
+        proc.wait(timeout=2)
+        # If we get here, the process exited
+        print(f"   ❌ Failed to start. Check {log_path}")
+        sys.exit(1)
+    except subprocess.TimeoutExpired:
+        pass  # Still running — good
+
+    print(f"   ✅ Started (pid {proc.pid}).")
+    print(f"   📄 Logs: {log_path}")
+
+
+def _cmd_stop(args):
+    """Stop birdword."""
+    pid = _read_pid()
+    if pid is None:
+        print("🐦 Birdword is not running.")
+        return
+
+    print(f"🐦 Stopping birdword (pid {pid})...")
+    try:
+        os.kill(pid, signal.SIGTERM)
+        print("   ✅ Stopped.")
+    except ProcessLookupError:
+        print("   ⚠️  Process already gone.")
+    _remove_pid()
+
+
+def _cmd_status(args):
+    """Check if birdword is running."""
+    pid = _read_pid()
+    if pid is not None:
+        print(f"🐦 Birdword is running (pid {pid}).")
+    else:
+        print("🐦 Birdword is not running.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Voice dictation using Parakeet on Apple Silicon"
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)",
+    )
+    parser.add_argument(
+        "--fix-model",
+        default=None,
+        help="Post-processor model (default: mlx-community/Qwen2.5-0.5B-Instruct-4bit)",
+    )
+    parser.add_argument(
+        "--no-fix",
+        action="store_true",
+        help="Disable LLM post-processing of transcription",
+    )
+    parser.add_argument(
+        "--hold-key",
+        default="rcmd",
+        help="Hold key for record (default: rcmd). Options: rcmd, lcmd, ralt, lalt",
+    )
+    parser.add_argument(
+        "--toggle-key",
+        default="space",
+        help="Toggle key pressed with hold key (default: space)",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("start", help="Start birdword in the background")
+    sub.add_parser("stop", help="Stop birdword")
+    sub.add_parser("status", help="Check if birdword is running")
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        _cmd_start(args)
+    elif args.command == "stop":
+        _cmd_stop(args)
+    elif args.command == "status":
+        _cmd_status(args)
+    else:
+        # No subcommand — run blocking (default)
+        _run_daemon(args)
+
+
+if __name__ == "__main__":
+    main()

birdword-0.1.0/src/birdword/context.py

@@ -0,0 +1,114 @@
+"""Detect the focused app and resolve project context."""
+
+import os
+import subprocess
+
+import AppKit
+
+
+def get_frontmost_app() -> tuple[str, str]:
+    """Return (bundle_id, app_name) of the frontmost application."""
+    workspace = AppKit.NSWorkspace.sharedWorkspace()
+    app = workspace.frontmostApplication()
+    return (app.bundleIdentifier() or "", app.localizedName() or "")
+
+
+def get_terminal_cwd() -> str | None:
+    """Get the cwd of the shell in the frontmost Terminal.app tab.
+
+    Only called when Terminal.app is the focused app.
+    Requires Automation permission for Terminal.app (prompts once).
+    """
+    try:
+        tty = subprocess.run(
+            [
+                "osascript",
+                "-e",
+                'tell application "Terminal" to tty of selected tab of front window',
+            ],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if tty.returncode != 0 or not tty.stdout.strip():
+            return None
+
+        tty_name = tty.stdout.strip()
+        # Strip /dev/ prefix for ps
+        tty_short = tty_name.replace("/dev/", "")
+
+        ps = subprocess.run(
+            ["ps", "-t", tty_short, "-o", "pid=,comm="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if ps.returncode != 0:
+            return None
+
+        # Find the shell process
+        pid = None
+        for line in ps.stdout.strip().splitlines():
+            parts = line.split()
+            if len(parts) >= 2 and any(
+                sh in parts[-1] for sh in ("zsh", "bash", "fish")
+            ):
+                pid = parts[0]
+                break
+
+        if pid is None:
+            return None
+
+        # Get the cwd of that process
+        lsof = subprocess.run(
+            ["lsof", "-a", "-p", pid, "-d", "cwd", "-Fn"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        for line in lsof.stdout.strip().splitlines():
+            if line.startswith("n/"):
+                return line[1:]
+
+    except Exception:
+        pass
+
+    return None
+
+
+def find_context_file(start_dir: str) -> str | None:
+    """Walk up from start_dir looking for a BIRDWORD.md file."""
+    current = os.path.abspath(start_dir)
+    while True:
+        candidate = os.path.join(current, "BIRDWORD.md")
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+    return None
+
+
+def get_context() -> tuple[str, str | None]:
+    """Get current context: (app_name, BIRDWORD.md contents or None).
+
+    Only queries Terminal.app for cwd when Terminal is the focused app.
+    """
+    bundle_id, app_name = get_frontmost_app()
+
+    context_content = None
+
+    # Only probe Terminal cwd when Terminal is actually focused
+    if bundle_id == "com.apple.Terminal":
+        cwd = get_terminal_cwd()
+        if cwd:
+            context_file = find_context_file(cwd)
+            if context_file:
+                try:
+                    with open(context_file) as f:
+                        context_content = f.read()
+                except Exception:
+                    pass
+
+    return app_name, context_content