add type support for model.py

[scottmonster]

no functional change but this adds type support for model.py

[absadiki]

Thanks @scottmonster for the PR.
But we already have inline type annotations for most of the public API, so I am not entirely sure what additional benefit the separate .pyi stub files provide in this case ?

[scottmonster]

While reviewing this I noticed I didn't add **params in model.pyi ... I generated the intitial version with a script which is why the # Generated by coverage/generate_pyi.py. Do not edit by hand. line is at the top. I removed that line and added **params into model.pyi

Currently in model.py we do:

class Model:
  ...
  def __init__(self,
               ...
               **params):
      ...
      # assign params
      self.params = params
      self._set_params(params)
  

1. **params does not provide keyword or type support, but it does mean _set_params only has to process the arguments actually passed to Model(...).
2. I wanted to add full type support while making minimal changes to the current runtime behavior.
3. Types defined in model.pyi have no runtime effect and provide full keyword and type support.

If we use the following example

from pywhispercpp.model import Model
m = Model(n_threads = "6",
          initial_prompt = True,
          beam_search = { 'beam_size': "3",'patience': -1 },
          )

Currently:

class Model(
    model: str = 'tiny',
    models_dir: str = None,
    params_sampling_strategy: int = 0,
    redirect_whispercpp_logs_to: bool | TextIO | str | None = False,
    use_openvino: bool = False,
    openvino_model_path: str = None,
    openvino_device: str = 'CPU',
    openvino_cache_dir: str = None,
    **params: Unknown
)
Parameters
model
The name of the model, one of the AVAILABLE_MODELS, (default to tiny), or a direct path to a ggml model.

models_dir
The directory where the models are stored, or where they will be downloaded if they don't exist, default to MODELS_DIR <user_data_dir/pywhsipercpp/models>

params_sampling_strategy
0 -> GREEDY, else BEAM_SEARCH

redirect_whispercpp_logs_to
where to redirect the whisper.cpp logs, default to False (no redirection), accepts str file path, sys.stdout, sys.stderr, or use None to redirect to devnull

use_openvino
whether to use OpenVINO or not

openvino_model_path
path to the OpenVINO model

openvino_device
OpenVINO device, default to CPU

openvino_cache_dir
OpenVINO cache directory

params
keyword arguments for different whisper.cpp parameters, see PARAMS_SCHEMA

Note There is no keyword or type support

With model.pyi

class Model(
    model: str = 'tiny',
    models_dir: str | None = None,
    params_sampling_strategy: int = 0,
    redirect_whispercpp_logs_to: bool | TextIO | str | None = False,
    use_openvino: bool = False,
    openvino_model_path: str | None = None,
    openvino_device: str = 'CPU',
    openvino_cache_dir: str | None = None,
    *,
    n_threads: int | None = None,
    n_max_text_ctx: int = 16384,
    offset_ms: int = 0,
    duration_ms: int = 0,
    translate: bool = False,
    no_context: bool = False,
    single_segment: bool = False,
    print_special: bool = False,
    print_progress: bool = True,
    print_realtime: bool = False,
    print_timestamps: bool = True,
    token_timestamps: bool = False,
    thold_pt: float = 0.01,
    thold_ptsum: float = 0.01,
    max_len: int = 0,
    split_on_word: bool = False,
    max_tokens: int = 0,
    audio_ctx: int = 0,
    initial_prompt: str | None = None,
    prompt_tokens: Tuple[Any, ...] | None = None,
    prompt_n_tokens: int = 0,
    language: str = '',
    suppress_blank: bool = True,
    suppress_non_speech_tokens: bool = False,
    temperature: float = 0,
    max_initial_ts: float = 1,
    length_penalty: float = -1,
    temperature_inc: float = 0.2,
    entropy_thold: float = 2.4,
    logprob_thold: float = -1,
    no_speech_thold: float = 0.6,
    greedy: GreedyParams = { 'best_of': -1 },
    beam_search: BeamSearchParams = { 'beam_size': -1,'patience': -1 },
    vad: bool = False,
    vad_model_path: str | None = None,
    **params: Unknown
)
Parameters
model
The name of the model, one of the AVAILABLE_MODELS, (default to tiny), or a direct path to a ggml model.

models_dir
The directory where the models are stored, or where they will be downloaded if they don't exist, default to MODELS_DIR <user_data_dir/pywhsipercpp/models>

params_sampling_strategy
0 -> GREEDY, else BEAM_SEARCH

redirect_whispercpp_logs_to
where to redirect the whisper.cpp logs, default to False (no redirection), accepts str file path, sys.stdout, sys.stderr, or use None to redirect to devnull

use_openvino
whether to use OpenVINO or not

openvino_model_path
path to the OpenVINO model

openvino_device
OpenVINO device, default to CPU

openvino_cache_dir
OpenVINO cache directory

params
keyword arguments for different whisper.cpp parameters, see PARAMS_SCHEMA

we also get the following type errors

Argument of type "Literal['6']" cannot be assigned to parameter "n_threads" of type "int | None" in function "__init__"
  Type "Literal['6']" is not assignable to type "int | None"
    "Literal['6']" is not assignable to "int"
    "Literal['6']" is not assignable to "None"

Argument of type "Literal[True]" cannot be assigned to parameter "initial_prompt" of type "str | None" in function "__init__"
  Type "Literal[True]" is not assignable to type "str | None"
    "Literal[True]" is not assignable to "str"
    "Literal[True]" is not assignable to "None"

Argument of type "dict[str, str | int]" cannot be assigned to parameter "beam_search" of type "BeamSearchParams" in function "__init__"
  "Literal['3']" is not assignable to "int"

tldr: model.pyi provides keyword and type support while having no runtime effect

note I was planning on updating the docustrings once the api has been updated for issue 167