From 4af584cf331b12eb9097a1b47c8f3a808d72f34d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 06:33:14 +0000 Subject: [PATCH 1/2] Initial plan From e09202e11bb8217179a5f8e4f2d40b9c9ee035c9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 06:37:44 +0000 Subject: [PATCH 2/2] Add HandyVoiceParser to delegate voice input to @cjpais/Handy Co-authored-by: tathagata <68151+tathagata@users.noreply.github.com> --- requirements.txt | 3 +- src/voice_parser.py | 111 +++++++++++++++++++++++++++++++++++++ tests/test_voice_parser.py | 111 ++++++++++++++++++++++++++++++++++++- 3 files changed, 222 insertions(+), 3 deletions(-) diff --git a/requirements.txt b/requirements.txt index 3f22697..8f684da 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ pytest SpeechRecognition -anthropic \ No newline at end of file +anthropic +pyperclip \ No newline at end of file diff --git a/src/voice_parser.py b/src/voice_parser.py index 93bf84b..67bb503 100644 --- a/src/voice_parser.py +++ b/src/voice_parser.py @@ -1,5 +1,7 @@ import logging import re +import subprocess +import time logger = logging.getLogger(__name__) @@ -63,6 +65,115 @@ def speech_to_text(self): return self.sanitize(raw_text) +class HandyVoiceParser: + """Delegates voice input to a running Handy instance (https://github.com/cjpais/Handy). + + Handy is a free, open-source, offline speech-to-text desktop application. + This class triggers Handy's transcription via its CLI flag and monitors the + clipboard for the resulting text, providing the same ``speech_to_text`` + interface as :class:`VoiceParser`. + + Handy must be installed and running before calling :meth:`speech_to_text`. + See https://github.com/cjpais/Handy for installation instructions. + """ + + DEFAULT_HANDY_EXECUTABLE = "handy" + DEFAULT_TIMEOUT = 30 + DEFAULT_POLL_INTERVAL = 0.25 + + def __init__(self, handy_executable=None, timeout=None, poll_interval=None): + self._executable = handy_executable or self.DEFAULT_HANDY_EXECUTABLE + self._timeout = timeout if timeout is not None else self.DEFAULT_TIMEOUT + self._poll_interval = poll_interval if poll_interval is not None else self.DEFAULT_POLL_INTERVAL + try: + import pyperclip + self._pyperclip = pyperclip + except ImportError: + self._pyperclip = None + logger.warning("pyperclip library not available. Install it with: pip install pyperclip") + + def trigger(self): + """Toggle Handy transcription by invoking the CLI flag. + + Sends ``--toggle-transcription`` to a running Handy instance. + Raises :class:`VoiceParserError` if the Handy executable is not found + or returns a non-zero exit code. + """ + try: + result = subprocess.run( + [self._executable, "--toggle-transcription"], + capture_output=True, + text=True, + ) + if result.returncode != 0: + raise VoiceParserError( + f"Handy returned exit code {result.returncode}: {result.stderr.strip()}" + ) + logger.info("Handy transcription toggled.") + except FileNotFoundError as e: + raise VoiceParserError( + f"Handy executable not found: '{self._executable}'. " + "Ensure Handy is installed and available in PATH." + ) from e + + def wait_for_transcript(self, previous_clipboard=""): + """Wait for Handy to paste new text to the clipboard. + + Polls the clipboard until its content changes from *previous_clipboard* + or until *timeout* seconds have elapsed. + + Returns the new clipboard content (stripped of surrounding whitespace). + Raises :class:`VoiceParserError` on timeout or if pyperclip is unavailable. + """ + if self._pyperclip is None: + raise VoiceParserError( + "pyperclip is required to read Handy's transcript from the clipboard. " + "Install it with: pip install pyperclip" + ) + deadline = time.monotonic() + self._timeout + while time.monotonic() < deadline: + try: + current = self._pyperclip.paste() + except Exception as e: + raise VoiceParserError(f"Failed to read clipboard: {e}") from e + if current != previous_clipboard: + logger.info("Handy transcript received from clipboard.") + return current.strip() + time.sleep(self._poll_interval) + raise VoiceParserError( + f"Timed out waiting for Handy transcript after {self._timeout}s. " + "Ensure Handy is running and has finished transcribing." + ) + + def speech_to_text(self): + """Delegate voice capture to Handy and return the transcribed text. + + Captures the current clipboard content, triggers Handy transcription, + waits for the clipboard to be updated with the transcript, sanitizes + the result, and returns it. + + The sanitization step reuses :meth:`VoiceParser.sanitize` logic: + collapses internal whitespace and raises :class:`VoiceParserError` for + empty results. + """ + if self._pyperclip is None: + raise VoiceParserError( + "pyperclip is required for HandyVoiceParser. " + "Install it with: pip install pyperclip" + ) + try: + previous = self._pyperclip.paste() + except Exception as e: + raise VoiceParserError(f"Failed to read clipboard: {e}") from e + + self.trigger() + raw_text = self.wait_for_transcript(previous_clipboard=previous) + + if not raw_text: + raise VoiceParserError("Handy returned an empty transcript.") + return re.sub(r"\s+", " ", raw_text.strip()) + + # Example usage if __name__ == "__main__": parser = VoiceParser() diff --git a/tests/test_voice_parser.py b/tests/test_voice_parser.py index 0b6c0c9..b834ecb 100644 --- a/tests/test_voice_parser.py +++ b/tests/test_voice_parser.py @@ -1,7 +1,7 @@ import pytest -from unittest.mock import MagicMock +from unittest.mock import MagicMock, patch, call -from voice_parser import VoiceParser, VoiceParserError +from voice_parser import VoiceParser, VoiceParserError, HandyVoiceParser class TestVoiceParserSanitize: @@ -49,3 +49,110 @@ def test_transcribe_request_error_raises(self): mock_recognizer.recognize_google.side_effect = sr.RequestError("service down") with pytest.raises(VoiceParserError, match="service error"): parser.transcribe(MagicMock()) + + +class TestHandyVoiceParser: + def _make_parser(self, **kwargs): + """Create a HandyVoiceParser with a mocked pyperclip.""" + mock_pyperclip = MagicMock() + parser = HandyVoiceParser(**kwargs) + parser._pyperclip = mock_pyperclip + return parser, mock_pyperclip + + # --- trigger() --- + + def test_trigger_calls_handy_toggle_transcription(self): + parser, _ = self._make_parser(handy_executable="handy") + with patch("voice_parser.subprocess.run") as mock_run: + mock_run.return_value = MagicMock(returncode=0, stderr="") + parser.trigger() + mock_run.assert_called_once_with( + ["handy", "--toggle-transcription"], + capture_output=True, + text=True, + ) + + def test_trigger_raises_when_executable_not_found(self): + parser, _ = self._make_parser(handy_executable="handy") + with patch("voice_parser.subprocess.run", side_effect=FileNotFoundError): + with pytest.raises(VoiceParserError, match="not found"): + parser.trigger() + + def test_trigger_raises_on_nonzero_exit_code(self): + parser, _ = self._make_parser(handy_executable="handy") + with patch("voice_parser.subprocess.run") as mock_run: + mock_run.return_value = MagicMock(returncode=1, stderr="some error") + with pytest.raises(VoiceParserError, match="exit code 1"): + parser.trigger() + + # --- wait_for_transcript() --- + + def test_wait_for_transcript_returns_new_clipboard_content(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.side_effect = ["old text", "old text", "new transcript"] + result = parser.wait_for_transcript(previous_clipboard="old text") + assert result == "new transcript" + + def test_wait_for_transcript_strips_whitespace(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.return_value = " transcribed text " + result = parser.wait_for_transcript(previous_clipboard="") + assert result == "transcribed text" + + def test_wait_for_transcript_times_out(self): + parser, mock_pyperclip = self._make_parser(timeout=0.05, poll_interval=0.01) + mock_pyperclip.paste.return_value = "unchanged" + with pytest.raises(VoiceParserError, match="Timed out"): + parser.wait_for_transcript(previous_clipboard="unchanged") + + def test_wait_for_transcript_raises_without_pyperclip(self): + parser, _ = self._make_parser() + parser._pyperclip = None + with pytest.raises(VoiceParserError, match="pyperclip is required"): + parser.wait_for_transcript() + + def test_wait_for_transcript_raises_on_clipboard_error(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.side_effect = Exception("clipboard unavailable") + with pytest.raises(VoiceParserError, match="Failed to read clipboard"): + parser.wait_for_transcript(previous_clipboard="") + + # --- speech_to_text() --- + + def test_speech_to_text_returns_sanitized_transcript(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.side_effect = ["", " write a sort function "] + with patch("voice_parser.subprocess.run") as mock_run: + mock_run.return_value = MagicMock(returncode=0, stderr="") + result = parser.speech_to_text() + assert result == "write a sort function" + + def test_speech_to_text_raises_on_empty_transcript(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.side_effect = ["old", " "] + with patch("voice_parser.subprocess.run") as mock_run: + mock_run.return_value = MagicMock(returncode=0, stderr="") + with pytest.raises(VoiceParserError, match="empty transcript"): + parser.speech_to_text() + + def test_speech_to_text_raises_without_pyperclip(self): + parser, _ = self._make_parser() + parser._pyperclip = None + with pytest.raises(VoiceParserError, match="pyperclip is required"): + parser.speech_to_text() + + def test_speech_to_text_triggers_handy_once(self): + parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01) + mock_pyperclip.paste.side_effect = ["before", "after transcription"] + with patch("voice_parser.subprocess.run") as mock_run: + mock_run.return_value = MagicMock(returncode=0, stderr="") + parser.speech_to_text() + mock_run.assert_called_once() + + def test_default_executable_is_handy(self): + parser = HandyVoiceParser() + assert parser._executable == "handy" + + def test_custom_executable_is_used(self): + parser = HandyVoiceParser(handy_executable="/usr/local/bin/handy") + assert parser._executable == "/usr/local/bin/handy"