From 44f3468e4d847cbab445efc33560e242fc124dc7 Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Fri, 20 Mar 2026 16:17:21 +1300 Subject: [PATCH 1/4] Bump KaldiAG support to 3.2.x --- CHANGELOG.rst | 2 ++ documentation/kaldi_engine.txt | 5 ++++- dragonfly/engines/backend_kaldi/engine.py | 2 +- setup.py | 2 +- 4 files changed, 8 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 4741dc7b..4c109b98 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -28,6 +28,8 @@ Changed compiling them directly. - Change the CommandModule class' optional unload method to invoke top-level unload functions like the Natlink loader does. +- Bump the supported ``kaldi-active-grammar`` line to 3.2.x so the + ``dragonfly[kaldi]`` extra installs the updated dependency set. - Make the logging output of Dragonfly's CLI commands more sane. - Make some optimizations to the Natlink engine. - Rename the engines.backend_sphinx.misc module to config. diff --git a/documentation/kaldi_engine.txt b/documentation/kaldi_engine.txt index 83d8dbc2..c4990038 100644 --- a/documentation/kaldi_engine.txt +++ b/documentation/kaldi_engine.txt @@ -88,6 +88,9 @@ using:: pip install 'dragonfly[kaldi]' +This remains the canonical install path and now installs the supported +``kaldi-active-grammar`` 3.2.x line. + If you are installing to *develop* Dragonfly, use the following instead (from your Dragonfly git repository):: @@ -149,7 +152,7 @@ Updating To A New Version When updating to a new version of Dragonfly, you should always rerun ``pip install 'dragonfly[kaldi]'`` (or ``pip install '.[kaldi]'``, etc.) to -make sure you get the required version of kaldi_active_grammar. +make sure you get the required ``kaldi_active_grammar`` 3.2.x version. Engine Configuration diff --git a/dragonfly/engines/backend_kaldi/engine.py b/dragonfly/engines/backend_kaldi/engine.py index 50a0b4b1..a70ee687 100644 --- a/dragonfly/engines/backend_kaldi/engine.py +++ b/dragonfly/engines/backend_kaldi/engine.py @@ -66,7 +66,7 @@ class KaldiEngine(EngineBase, DelegateTimerManagerInterface): _name = "kaldi" # NOTE: Remember to also update setup.py to the same version! - _required_kag_version = "3.1.0" + _required_kag_version = "3.2.0" #----------------------------------------------------------------------- diff --git a/setup.py b/setup.py index 62110649..0a82f4dd 100644 --- a/setup.py +++ b/setup.py @@ -160,7 +160,7 @@ def _try_local_natlink_pyd(self): ], "kaldi": [ # NOTE: Remember to also update engine.py to the same version! - "kaldi-active-grammar ~= 3.1.0", + "kaldi-active-grammar ~= 3.2.0", "sounddevice == 0.3.*", "webrtcvad-wheels == 2.0.*", ], From bd56eeb75c6eb9193ac7f30953f4b94a5157a6b4 Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Fri, 20 Mar 2026 16:21:11 +1300 Subject: [PATCH 2/4] Trim Kaldi install docs wording --- documentation/kaldi_engine.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/documentation/kaldi_engine.txt b/documentation/kaldi_engine.txt index c4990038..83d8dbc2 100644 --- a/documentation/kaldi_engine.txt +++ b/documentation/kaldi_engine.txt @@ -88,9 +88,6 @@ using:: pip install 'dragonfly[kaldi]' -This remains the canonical install path and now installs the supported -``kaldi-active-grammar`` 3.2.x line. - If you are installing to *develop* Dragonfly, use the following instead (from your Dragonfly git repository):: @@ -152,7 +149,7 @@ Updating To A New Version When updating to a new version of Dragonfly, you should always rerun ``pip install 'dragonfly[kaldi]'`` (or ``pip install '.[kaldi]'``, etc.) to -make sure you get the required ``kaldi_active_grammar`` 3.2.x version. +make sure you get the required version of kaldi_active_grammar. Engine Configuration From 597727ad3fe675d2940dcef9d962845927aa7751 Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Sat, 21 Mar 2026 20:12:29 +1300 Subject: [PATCH 3/4] Document remaining language and geometry APIs --- documentation/geometry_classes.txt | 20 ++++++++ documentation/kaldi_engine.txt | 1 + documentation/language.txt | 79 ++++++++++++++++++++++++++++- documentation/related_resources.txt | 4 +- documentation/windows.txt | 4 +- dragonfly/language/base/digits.py | 7 +++ dragonfly/language/base/integer.py | 14 +++++ dragonfly/language/base/number.py | 8 +++ dragonfly/windows/point.py | 6 +++ dragonfly/windows/rectangle.py | 8 +++ 10 files changed, 147 insertions(+), 4 deletions(-) create mode 100644 documentation/geometry_classes.txt diff --git a/documentation/geometry_classes.txt b/documentation/geometry_classes.txt new file mode 100644 index 00000000..0678388f --- /dev/null +++ b/documentation/geometry_classes.txt @@ -0,0 +1,20 @@ +Geometry classes +============================================================================ + +Dragonfly's window and monitor APIs use a pair of small geometry classes to +represent points, bounds and movement calculations across supported +platforms. + + +Point class +---------------------------------------------------------------------------- + +.. autoclass:: dragonfly.windows.point.Point + :members: + + +Rectangle class +---------------------------------------------------------------------------- + +.. autoclass:: dragonfly.windows.rectangle.Rectangle + :members: diff --git a/documentation/kaldi_engine.txt b/documentation/kaldi_engine.txt index 83d8dbc2..ee86811d 100644 --- a/documentation/kaldi_engine.txt +++ b/documentation/kaldi_engine.txt @@ -197,6 +197,7 @@ The engine can also be configured via the :ref:`command-line interface .. autofunction:: dragonfly.engines.backend_kaldi.engine.KaldiEngine + :no-index: **Arguments (all optional):** diff --git a/documentation/language.txt b/documentation/language.txt index a917e824..e2e92dc2 100644 --- a/documentation/language.txt +++ b/documentation/language.txt @@ -135,13 +135,90 @@ The following languages are supported: English has additional time, date and character related classes. +Numeric language elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dragonfly exposes a small public numeric language API through the +:mod:`dragonfly.language` package. These classes use the current speech +recognition engine language to load the right spoken-number content. + +Use the direct element classes when building grammars inline: + +* :class:`Integer` for bounded spoken integers. +* :class:`Digits` for sequences of spoken digits. +* :class:`Number` for larger spoken numbers and number series. + +Use the ``*Ref`` variants when you want Dragonfly to wrap those elements in +named private rules for use as command extras: + +* :class:`IntegerRef` +* :class:`ShortIntegerRef` +* :class:`DigitsRef` +* :class:`NumberRef` + +:class:`ShortIntegerRef` uses a more permissive short-number grammar when a +language implements it and otherwise falls back to normal integer +pronunciations for that language. + + Language classes reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. automodule:: dragonfly.language.en.short_number +Integer class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Integer + :members: + + +IntegerRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.IntegerRef :members: +ShortIntegerRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.ShortIntegerRef + :members: + + +Digits class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Digits + :members: + + +DigitsRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.DigitsRef + :members: + + +Number class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.Number + :members: + + +NumberRef class ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. autoclass:: dragonfly.language.NumberRef + :members: + + +Short number pronunciation notes ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. automodule:: dragonfly.language.en.short_number + + .. rubric:: References .. [#f1] https://nuance.custhelp.com/app/answers/detail/a_id/6280/kw/Dragon%20NaturallySpeaking%20languages%20supported/related/1 diff --git a/documentation/related_resources.txt b/documentation/related_resources.txt index de9d5dec..43075d99 100644 --- a/documentation/related_resources.txt +++ b/documentation/related_resources.txt @@ -35,8 +35,8 @@ The following resources are used by the Dragonfly community and speech recognition users/developers: * `Gitter chat room `__ - (also `bridged to Matrix `__) - --- Real-time chat and historical discussions about Dragonfly + (also `bridged to Matrix `__) + --- Real-time chat and historical discussions about Dragonfly * `Dragonfly Speech Google Group `_ diff --git a/documentation/windows.txt b/documentation/windows.txt index c162fbf3..c94ba1e5 100644 --- a/documentation/windows.txt +++ b/documentation/windows.txt @@ -4,13 +4,15 @@ Windows sub-package Dragonfly includes several toolkits for non-speech user interfaces. These include for example, cross-platform generic window control, access to -monitor information and access to the system clipboard. +monitor information, simple geometry helpers and access to the system +clipboard. Contents of Dragonfly's windows sub-package: .. toctree:: :maxdepth: 2 + geometry_classes clipboard monitor_classes window_classes diff --git a/dragonfly/language/base/digits.py b/dragonfly/language/base/digits.py index 8c481d1b..335fb857 100644 --- a/dragonfly/language/base/digits.py +++ b/dragonfly/language/base/digits.py @@ -33,6 +33,12 @@ # Base class for digit-series element classes. class Digits(Repetition): + """ + Language-aware element for a spoken series of digits. + + The recognized value can be returned either as a list of digit values or + combined into an integer via the ``as_int`` argument. + """ _content = None _digit_name = "_digit" @@ -92,6 +98,7 @@ def value(self, node): # Digits reference class. class DigitsRef(RuleWrap): + """Named rule wrapper around :class:`Digits` for use in rule extras.""" def __init__(self, name=None, min=1, max=12, as_int=True, default=None): element = Digits(name=None, min=min, max=max, as_int=as_int) diff --git a/dragonfly/language/base/integer.py b/dragonfly/language/base/integer.py index a0e9f49b..d5d5f507 100644 --- a/dragonfly/language/base/integer.py +++ b/dragonfly/language/base/integer.py @@ -34,6 +34,13 @@ # Base class for integer element classes. class Integer(Alternative): + """ + Language-aware element for spoken integers within a numeric range. + + The active speech recognition engine language determines which spoken + forms are available unless a specific content implementation is passed + explicitly. + """ _content = None @@ -90,12 +97,19 @@ def _build_children(self, min, max): # Integer reference class. class IntegerRef(RuleWrap): + """Named rule wrapper around :class:`Integer` for use in rule extras.""" def __init__(self, name, min, max, default=None): element = Integer(None, min, max) RuleWrap.__init__(self, name, element, default=default) class ShortIntegerRef(RuleWrap): + """ + Variant of :class:`IntegerRef` that accepts shorter spoken forms. + + This uses language-specific short-number content when available and + otherwise falls back to the standard integer content for the language. + """ def __init__(self, name, min, max, default=None): element = Integer(None, min, max, content=language.ShortIntegerContent) diff --git a/dragonfly/language/base/number.py b/dragonfly/language/base/number.py index a6a17124..1992e956 100644 --- a/dragonfly/language/base/number.py +++ b/dragonfly/language/base/number.py @@ -34,6 +34,13 @@ # Number class. class Number(Alternative): + """ + Language-aware element for spoken whole numbers and number series. + + This combines the current language's integer content into a higher-level + element that can interpret a single number or a spoken series of smaller + numbers as one value. + """ _int_max = 1000000 _ser_len = 8 @@ -81,6 +88,7 @@ def value(self, node): # Number reference class. class NumberRef(RuleWrap): + """Named rule wrapper around :class:`Number` for use in rule extras.""" def __init__(self, name=None, zero=False, default=None): element = Number(None, zero=zero) diff --git a/dragonfly/windows/point.py b/dragonfly/windows/point.py index f10db552..fa21ef16 100644 --- a/dragonfly/windows/point.py +++ b/dragonfly/windows/point.py @@ -32,6 +32,12 @@ #=========================================================================== class Point(object): + """ + Two-dimensional point with floating-point coordinates. + + The class provides small geometry helpers used throughout Dragonfly's + window and monitor toolkits. + """ #----------------------------------------------------------------------- # Methods for initialization, copying, and introspection. diff --git a/dragonfly/windows/rectangle.py b/dragonfly/windows/rectangle.py index 4db7a477..1afbb645 100644 --- a/dragonfly/windows/rectangle.py +++ b/dragonfly/windows/rectangle.py @@ -30,6 +30,14 @@ # Rectangle class. class Rectangle(Point): + """ + Axis-aligned rectangle represented by an origin point and size. + + Rectangle inherits the position handling from + :class:`~dragonfly.windows.point.Point` and adds width, height, + centre-point, and containment helpers used by the window and monitor + APIs. + """ #----------------------------------------------------------------------- # Methods for initialization, copying, and introspection. From e0be5cdb42bc835dd5957c9e36279f82b45639df Mon Sep 17 00:00:00 2001 From: Kendon Bell Date: Sat, 21 Mar 2026 20:35:01 +1300 Subject: [PATCH 4/4] Refine windows documentation summary --- documentation/windows.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/windows.txt b/documentation/windows.txt index c94ba1e5..c53a37c9 100644 --- a/documentation/windows.txt +++ b/documentation/windows.txt @@ -4,8 +4,7 @@ Windows sub-package Dragonfly includes several toolkits for non-speech user interfaces. These include for example, cross-platform generic window control, access to -monitor information, simple geometry helpers and access to the system -clipboard. +monitor information and access to the system clipboard. Contents of Dragonfly's windows sub-package: