Add verbose parameter to recognize_vosk()

[ftnext]

Close #592

[Copilot]

Pull Request Overview

This PR adds a verbose flag to the recognize_vosk method, allowing callers to receive either plain text or the full parsed JSON response.

• Introduces verbose: bool parameter with proper type overloads and handling in the Vosk recognizer
• Updates tests to cover both default (text) and verbose (dict) outputs
• Updates the library reference documentation to include the new parameter and return types

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/recognizers/test_vosk.py	Added pytest fixture for audio data and tests for verbose output
speech_recognition/recognizers/vosk.py	Implemented verbose parameter, JSON parsing, and overloads
reference/library-reference.rst	Updated function signature in docs to reflect verbose parameter

Comments suppressed due to low confidence (2)

tests/recognizers/test_vosk.py:21

• It may be helpful to add a test explicitly passing verbose=False to verify the method still returns a plain string even when the flag is set.

def test_recognize_vosk_verbose(audio_data):

reference/library-reference.rst:283

• [nitpick] The docs reference Dict[str, Any] without importing Dict or Any in this context. Consider using the built-in dict in the signature or adding a note about required typing imports for clarity.

``recognizer_instance.recognize_vosk(audio_data: AudioData, *, verbose: bool = False) -> Union[str, Dict[str, Any]]``

[Copilot]

[nitpick] The recognizer parameter is declared but unused in the function body, which could confuse readers. Consider renaming it to _recognizer or adding a brief comment explaining it’s required for interface consistency.

Suggested change

	recognizer, audio_data: AudioData, *, verbose: Literal[False]
	) -> str: ...
	@overload
	def recognize(
	recognizer, audio_data: AudioData, *, verbose: Literal[True]
	) -> VoskResponse: ...
	def recognize(
	recognizer, audio_data: AudioData, *, verbose: bool = False
	_recognizer, audio_data: AudioData, *, verbose: Literal[False]
	) -> str: ...
	@overload
	def recognize(
	_recognizer, audio_data: AudioData, *, verbose: Literal[True]
	) -> VoskResponse: ...
	def recognize(
	_recognizer, audio_data: AudioData, *, verbose: bool = False

[Copilot]

Pull Request Overview

Adds a verbose flag to the Vosk recognizer so callers can choose between receiving just the recognized text or the full result dictionary.

• Introduce verbose: bool parameter with overloads and updated return types in recognize().
• Refactor tests to use a pytest fixture and add a verbose=True test case.
• Update docstring and library reference to document the new parameter and return signature.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
speech_recognition/recognizers/vosk.py	Added verbose parameter, type overloads, and conditional return of full JSON result or text.
tests/recognizers/test_vosk.py	Created audio_data fixture; updated existing test and added verbose mode test.
reference/library-reference.rst	Updated recognize_vosk signature to include verbose and return type.

Comments suppressed due to low confidence (1)

speech_recognition/recognizers/vosk.py:4

• The os module is imported but never used in this file. Consider removing this unused import to keep dependencies clean.

import os

[Copilot]

[nitpick] The docs specify a generic Dict[str, Any] return type, but the code returns a specific VoskResponse TypedDict. Updating this to the precise type (or at least Dict[str, str]) would improve clarity.

[Copilot]

[nitpick] The docstring describes the verbose flag but doesn't use a structured :param verbose: block. Adding a proper parameter section could make the docs more consistent and easier to parse.

Suggested change

	If ``verbose`` is ``False`` (default), only the recognized text is returned.
	If ``verbose`` is ``True``, the parsed result dictionary from Vosk is returned.
	:param recognizer: The recognizer instance performing the recognition.
	:param audio_data: The audio data to recognize, provided as an instance of ``AudioData``.
	:param verbose: If ``False`` (default), only the recognized text is returned. If ``True``, the parsed result dictionary from Vosk is returned.
	:return: The recognized text as a string if ``verbose`` is ``False``, or the parsed result dictionary if ``verbose`` is ``True``.