stark-engine 4.3.1__tar.gz → 4.4.1__tar.gz

{stark_engine-4.3.1 → stark_engine-4.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stark-engine
-Version: 4.3.1
+Version: 4.4.1
 Summary: S.T.A.R.K - Speech and Text Algorithmic Recognition Kit. Modern framework for creating powerfull voice assistants.
 License: CC BY-NC-SA 4.0
 License-File: LICENSE.md
@@ -19,7 +19,8 @@ Provides-Extra: silero
 Provides-Extra: sound
 Provides-Extra: spacy
 Provides-Extra: vosk
-Requires-Dist: asyncer (>=0.0.2,<0.0.3)
+Requires-Dist: anyio (>=4.0.0,<5.0.0)
+Requires-Dist: asyncer (>=0.0.8,<1.0.0)
 Requires-Dist: google-cloud-texttospeech (>=2.14.1,<3.0.0) ; extra == "gcloud" or extra == "all"
 Requires-Dist: numpy (>=2.3.3,<3.0.0) ; extra == "silero" or extra == "all"
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)

{stark_engine-4.3.1 → stark_engine-4.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "stark-engine"
-version = "4.3.1"
+version = "4.4.1"
 description = "S.T.A.R.K - Speech and Text Algorithmic Recognition Kit. Modern framework for creating powerfull voice assistants."
 authors = ["MarkParker5 <mark@parker-programs.com>"]
 license = "CC BY-NC-SA 4.0"
@@ -39,7 +39,8 @@ keywords = [
 [tool.poetry.dependencies]
 python = ">=3.12,<3.15"
 pydantic = "^2.0.0"
-asyncer = "^0.0.2"
+asyncer = ">=0.0.8,<1.0.0"
+anyio = ">=4.0.0,<5.0.0"
 numpy = "^2.3.3"
 
 # Optional dependencies
@@ -85,6 +86,7 @@ coverage = "^7.11.0"
 faker = "^37.11.0"
 pympler = "^1.1"
 psutil = "^7.1.1"
+trio = "^0.33.0"
 
 [build-system]
 requires = ["poetry-core"]

stark_engine-4.4.1/stark/__init__.py

@@ -0,0 +1,79 @@
+import asyncer
+
+from stark.core import (
+    Command,
+    CommandsContext,
+    CommandsManager,
+    Pattern,
+    Response,
+    ResponseStatus,
+)
+from stark.core.commands_context_processor import CommandsContextProcessor
+from stark.core.health_check import health_check
+from stark.core.processors.search_processor import SearchProcessor
+from stark.general.blockage_detector import BlockageDetector
+from stark.general.localisation import Localizer
+from stark.interfaces.protocols import (
+    SpeechRecognizer,
+    SpeechRecognizerDelegate,
+    SpeechSynthesizer,
+    SpeechSynthesizerResult,
+)
+from stark.voice_assistant import Mode, VoiceAssistant
+
+
+async def run(
+    manager: CommandsManager,
+    speech_recognizer: SpeechRecognizer | list[SpeechRecognizer],
+    speech_synthesizer: SpeechSynthesizer,
+    processors: list[CommandsContextProcessor] | None = None,
+    localizer: Localizer | None = None,
+):
+    if processors is None:
+        if localizer:
+            from stark.core.processors.corrections_processor import CorrectionsProcessor
+            processors = [CorrectionsProcessor(), SearchProcessor()]
+        else:
+            processors = [SearchProcessor()]
+
+    async with asyncer.create_task_group() as main_task_group:
+        context = CommandsContext(
+            task_group=main_task_group,
+            commands_manager=manager,
+            processors=processors,
+            localizer=localizer,
+        )
+
+        from stark.interfaces.microphone import Microphone
+
+        recognizers = speech_recognizer if isinstance(speech_recognizer, list) else [speech_recognizer]
+        use_relay = len(recognizers) > 1
+
+        if use_relay:
+            from stark.interfaces.recognizer_relay import SpeechRecognizerRelay
+            effective_recognizer = SpeechRecognizerRelay(recognizers)
+        else:
+            effective_recognizer = recognizers[0]
+
+        voice_assistant = VoiceAssistant(
+            speech_recognizer=effective_recognizer,
+            speech_synthesizer=speech_synthesizer,
+            commands_context=context,
+        )
+        effective_recognizer.delegate = voice_assistant
+        context.delegate = voice_assistant
+
+        health_check(context.pattern_parser, manager.commands)
+
+        if use_relay:
+            effective_recognizer.start_speech_recognizers(main_task_group)
+        else:
+            main_task_group.soonify(effective_recognizer.start_listening)()
+
+        microphone = Microphone(effective_recognizer.microphone_did_receive_sample)
+        main_task_group.soonify(microphone.start_listening)()
+
+        main_task_group.soonify(context.handle_responses)()
+
+        detector = BlockageDetector()
+        main_task_group.soonify(detector.monitor)()

{stark_engine-4.3.1 → stark_engine-4.4.1}/stark/core/command.py

@@ -29,12 +29,11 @@ import asyncer
 from pydantic import BaseModel, Field
 
 from ..general.classproperty import classproperty
+from ..general.localisation import LanguageCode, LocalizableString
 from .patterns import Pattern
 
 ResponseOptions = (
-    Optional["Response"]
-    | Generator[Optional["Response"], None, None]
-    | AsyncGenerator[Optional["Response"], None]
+    Optional["Response"] | Generator[Optional["Response"], None, None] | AsyncGenerator[Optional["Response"], None]
 )
 AwaitResponse = Awaitable[ResponseOptions]
 AsyncCommandRunner = Callable[..., AwaitResponse]
@@ -44,16 +43,21 @@ CommandRunner = TypeVar("CommandRunner", bound=SyncCommandRunner | AsyncCommandR
 
 class Command(Generic[CommandRunner]):
     name: str
-    pattern: Pattern
+    patterns: dict[LanguageCode, Pattern]
     _runner: CommandRunner
 
-    def __init__(self, name: str, pattern: Pattern, runner: CommandRunner):
-        assert isinstance(pattern, Pattern)
+    def __init__(self, name: str, patterns: dict[LanguageCode, Pattern], runner: CommandRunner):
+        assert patterns and all(isinstance(p, Pattern) for p in patterns.values())
         self.name = name
-        self.pattern = pattern
+        self.patterns = patterns
         self._runner = runner
         update_wrapper(self, runner)
 
+    def get_pattern(self, language_code: LanguageCode) -> Pattern:
+        if language_code in self.patterns:
+            return self.patterns[language_code]
+        return self.patterns["base"]
+
     def run(
         self,
         parameters_dict: dict[str, Any] | None = None,
@@ -74,9 +78,7 @@ class Command(Generic[CommandRunner]):
 
         runner: AsyncCommandRunner
 
-        if inspect.iscoroutinefunction(self._runner) or inspect.isasyncgen(
-            self._runner
-        ):
+        if inspect.iscoroutinefunction(self._runner) or inspect.isasyncgen(self._runner):
             # async functions (coroutines) and async generators are remain as is
             runner = cast(AsyncCommandRunner, self._runner)
         else:
@@ -84,21 +86,12 @@ class Command(Generic[CommandRunner]):
             # async generators are not supported yet by asyncer.asyncify (https://github.com/tiangolo/asyncer/discussions/86)
             runner = asyncer.asyncify(cast(SyncCommandRunner, self._runner))
 
-        if any(
-            p.kind == p.VAR_KEYWORD
-            for p in inspect.signature(self._runner).parameters.values()
-        ):
+        if any(p.kind == p.VAR_KEYWORD for p in inspect.signature(self._runner).parameters.values()):
             # if command runner accepts **kwargs, pass all parameters
             coroutine = runner(**parameters)
         else:
             # otherwise pass only parameters that are in command runner signature to prevent TypeError: got an unexpected keyword argument
-            coroutine = runner(
-                **{
-                    k: v
-                    for k, v in parameters.items()
-                    if k in self._runner.__code__.co_varnames
-                }
-            )
+            coroutine = runner(**{k: v for k, v in parameters.items() if k in self._runner.__code__.co_varnames})
 
         @wraps(runner)
         async def coroutine_wrapper() -> ResponseOptions:
@@ -139,8 +132,8 @@ class ResponseStatus(Enum):
 
 
 class Response(BaseModel):
-    voice: str = ""
-    text: str = ""
+    voice: str | LocalizableString = ""
+    text: str | LocalizableString = ""
     status: ResponseStatus = ResponseStatus.success
     needs_user_input: bool = False
     commands: list[Command] = []

{stark_engine-4.3.1 → stark_engine-4.4.1}/stark/core/commands_context.py

@@ -15,8 +15,10 @@ from stark.core.commands_context_processor import (
 )
 from stark.core.parsing import PatternParser
 from stark.core.types.object import Object
+from stark.general.localisation import LocaleString, Localizer
+from stark.general.localisation.language_code import LanguageCode
 
-from ..general.dependencies import DependencyManager, default_dependency_manager
+from ..general.dependencies import Dependency, DependencyManager, default_dependency_manager
 from .command import (
     AsyncResponseHandler,
     Command,
@@ -57,11 +59,12 @@ class CommandsContext:
         commands_manager: CommandsManager,
         dependency_manager: DependencyManager = default_dependency_manager,
         processors: list[Any] | None = None,
+        localizer: Localizer | None = None,
     ):
         assert isinstance(task_group, TaskGroup), task_group
         assert isinstance(commands_manager, CommandsManager)
         assert isinstance(dependency_manager, DependencyManager)
-        self.pattern_parser = PatternParser()
+        self.pattern_parser = PatternParser(localizer=localizer)
         self.commands_manager = commands_manager
         self.context_queue = [self.root_context]
         self._response_queue = []
@@ -88,7 +91,9 @@ class CommandsContext:
     def root_context(self):
         return CommandsContextLayer(self.commands_manager.commands, {})
 
-    async def process_string(self, string: str):
+    async def process_string(self, string: str | LocaleString):
+        string = LocaleString(string) if not isinstance(string, LocaleString) else string
+
         if not self.context_queue:
             self.context_queue.append(self.root_context)
 
@@ -117,7 +122,15 @@ class CommandsContext:
             parameters: dict[str, Object] = {}
             parameters.update(current_context.parameters)
             parameters.update(search_result.match_result.parameters)
+
+            substring = search_result.match_result.substring
+            lang = substring.language_code if isinstance(substring, LocaleString) else string.language_code
+            lang_dep = Dependency(None, LanguageCode, lang)
+            self.dependency_manager.dependencies.add(lang_dep)
             parameters.update(self.dependency_manager.resolve(search_result.command._runner))
+            # language is a command-specific temporary dependency
+            self.dependency_manager.dependencies.discard(lang_dep)
+
             self.run_command(search_result.command, parameters)
 
         return search_results or []

{stark_engine-4.3.1 → stark_engine-4.4.1}/stark/core/commands_context_processor.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING
 from stark.core.command import Command
 from stark.core.parsing import RecognizedEntity
 from stark.core.types.object import Object
+from stark.general.localisation import LocaleString
 
 from .commands_manager import SearchResult
 
@@ -42,7 +43,10 @@ class CommandsContextProcessor(ABC):
     """
 
     async def process_string(
-        self, string: str, context: CommandsContext, recognized_entities: list[RecognizedEntity]
+        self,
+        string: LocaleString,
+        context: CommandsContext,
+        recognized_entities: list[RecognizedEntity],
     ) -> tuple[list[SearchResult], int]:
         """
         Processes the entire context queue.
@@ -72,7 +76,7 @@ class CommandsContextProcessor(ABC):
 
     async def process_context_layer(
         self,
-        string: str,
+        string: LocaleString,
         context: CommandsContext,
         context_layer: CommandsContextLayer,
         recognized_entities: list[RecognizedEntity],

{stark_engine-4.3.1 → stark_engine-4.4.1}/stark/core/commands_manager.py

@@ -31,9 +31,14 @@ class CommandsManager:
                 return command
         return None
 
-    def new(self, pattern_str: str, hidden: bool = False):
+    def new(self, pattern_str: str | dict[str, str], hidden: bool = False):
         def creator(runner: CommandRunner) -> Command:
-            pattern = Pattern(pattern_str)
+            if isinstance(pattern_str, dict):
+                patterns = {lang: Pattern(p) for lang, p in pattern_str.items()}
+                if 'base' not in patterns:
+                    patterns['base'] = next(iter(patterns.values()))
+            else:
+                patterns = {'base': Pattern(pattern_str)}
 
             # take the main type from Optionals
             annotations = dict()
@@ -60,7 +65,7 @@ class CommandsManager:
 
             # create command
 
-            cmd = Command(f"{self.name}.{runner.__name__}", pattern, runner)
+            cmd = Command(f"{self.name}.{runner.__name__}", patterns, runner)
 
             if not hidden:
                 self.commands.append(cmd)

stark_engine-4.4.1/stark/core/health_check.py

@@ -0,0 +1,74 @@
+import warnings
+
+from stark.core.command import Command
+from stark.core.parsing import _LOCALIZER_KEY_REGEX, PatternParser
+
+
+def health_check(pattern_parser: PatternParser, commands: list[Command]) -> None:
+    # TODO: update schema and validation; handle optional parameters; handle short form where type is defined in object
+
+    # 1. Registered types: pattern parameters and annotations match; all used types are registered
+    for reg_type in pattern_parser.parameter_types_by_name.values():
+        for lang, type_pattern in reg_type.type.patterns.items():
+            pattern_params = set(type_pattern.parameters.keys())
+            class_params = set(reg_type.type.__annotations__.keys())
+            assert pattern_params <= class_params, (
+                f"Pattern parameters {pattern_params} do not match class annotations {class_params} for {reg_type.type.__name__} (language '{lang}')"
+            )
+            # 2. Registered types: All referenced parameter types are registered
+            for param_name in pattern_params:
+                assert type_pattern.parameters[param_name].type_name in pattern_parser.parameter_types_by_name, (
+                    f"Unknown parameter type '{param_name}' in pattern '{type_pattern}' of type '{reg_type.type.__name__}' (language '{lang}'). Known types: {sorted(pattern_parser.parameter_types_by_name.keys())}"
+                )
+
+    # 3. No duplicate parameter types registered
+    type_names = list(pattern_parser.parameter_types_by_name.keys())
+    if len(type_names) != len(set(type_names)):
+        duplicates = {name for name in type_names if type_names.count(name) > 1}
+        assert not duplicates, f"Duplicate parameter type names found: {sorted(duplicates)}"
+
+    # 4. Commands: validate @key references and parameter types
+    for command in commands:
+        for lang, cmd_pattern in command.patterns.items():
+            if pattern_parser.localizer and pattern_parser._has_localizer_keys(cmd_pattern):
+                for key in _LOCALIZER_KEY_REGEX.findall(cmd_pattern._origin):
+                    pattern_parser.localizer.verify_recognizable(key)
+        for param in command.get_pattern("base").parameters.values():
+            assert param.type_name in pattern_parser.parameter_types_by_name, (
+                f"Unknown parameter type '{param.type_name}' in pattern '{command.get_pattern('base')}' of command '{command.name}'. Known types: {sorted(pattern_parser.parameter_types_by_name.keys())}"
+            )
+
+    # 5. Commands: all pattern params are expected by the runner func
+    for command in commands:
+        pattern_params = set(command.get_pattern("base").parameters.keys())
+        runner_params = set(command._runner.__annotations__.keys())
+        assert pattern_params <= runner_params, (
+            f"Command '{command.name}' function missing parameters: {pattern_params - runner_params}"
+        )
+
+    # 6. Pattern syntax validity (TODO)
+    # for command in commands:
+    #     assert command.get_pattern("base").is_valid(), f"Invalid pattern syntax: {command.get_pattern("base").origin}"
+
+    # 7. Try compiling all patterns to catch syntax errors early
+    for reg_type in pattern_parser.parameter_types_by_name.values():
+        for lang, p in reg_type.type.patterns.items():
+            try:
+                pattern_parser._compile_pattern(p, language_code=lang)
+            except Exception as e:
+                warnings.warn(
+                    f"Failed to compile pattern '{p}' of type '{reg_type.type.__name__}' (language '{lang}'): {e}"
+                )
+    for command in commands:
+        for lang, p in command.patterns.items():
+            try:
+                pattern_parser._compile_pattern(p, language_code=lang)
+            except Exception as e:
+                warnings.warn(f"Failed to compile pattern '{p}' of command '{command.name}' (language '{lang}'): {e}")
+
+    # 8. No unused types
+    used_types = {param.type_name for command in commands for param in command.get_pattern("base").parameters.values()}
+    for type_name in pattern_parser.parameter_types_by_name:
+        # assert type_name in used_types, f"Registered type {type_name} is not used in any pattern"
+        if type_name not in used_types:
+            warnings.warn(f"Registered type {type_name} is not used in any pattern")