stark-engine 4.2.2__tar.gz → 4.3.0__tar.gz

{stark_engine-4.2.2 → stark_engine-4.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: stark-engine
-Version: 4.2.2
+Version: 4.3.0
 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
 Keywords: python,open-source,natural-language-processing,framework,cross-platform,natural-language,voice,voice-commands,python3,voice-recognition,speech-recognition,speech-to-text,community-project,voice-assistant,voice-interface,NLP,machine-learning,AI,text-analysis,stark,stark-place,stark-engine,mark parker
 Author: MarkParker5
 Author-email: mark@parker-programs.com
-Requires-Python: >=3.12,<4.0
+Requires-Python: >=3.12,<3.15
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -17,6 +17,7 @@ Provides-Extra: all
 Provides-Extra: gcloud
 Provides-Extra: silero
 Provides-Extra: sound
+Provides-Extra: spacy
 Provides-Extra: vosk
 Requires-Dist: asyncer (>=0.0.2,<0.0.3)
 Requires-Dist: google-cloud-texttospeech (>=2.14.1,<3.0.0) ; extra == "gcloud" or extra == "all"
@@ -24,6 +25,7 @@ Requires-Dist: numpy (>=2.3.3,<3.0.0) ; extra == "silero" or extra == "all"
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
 Requires-Dist: sounddevice (>=0.4.5,<0.5.0) ; extra == "gcloud" or extra == "vosk" or extra == "silero" or extra == "sound" or extra == "all"
 Requires-Dist: soundfile (>=0.11.0,<0.12.0) ; extra == "gcloud" or extra == "sound" or extra == "all"
+Requires-Dist: spacy (>=3.8.11,<4.0.0) ; extra == "spacy" or extra == "all"
 Requires-Dist: torch (>=1.13.1,<2.0.0) ; extra == "silero" or extra == "all"
 Requires-Dist: vosk (==0.3.44) ; extra == "vosk" or extra == "all"
 Project-URL: Documentation, https://stark.markparker.me

{stark_engine-4.2.2 → stark_engine-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "stark-engine"
-version = "4.2.2"
+version = "4.3.0"
 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"
@@ -37,7 +37,7 @@ keywords = [
 
 
 [tool.poetry.dependencies]
-python = "^3.12"
+python = ">=3.12,<3.15"
 pydantic = "^2.0.0"
 asyncer = "^0.0.2"
 numpy = "^2.3.3"
@@ -48,12 +48,14 @@ soundfile = { version = "^0.11.0", optional = true }
 vosk = { version = "0.3.44", optional = true }
 google-cloud-texttospeech = { version = "^2.14.1", optional = true }
 torch = { version = "^1.13.1", optional = true }
+spacy = { version = "^3.8.11", optional = true }
 
 [tool.poetry.extras]
 gcloud = ["google-cloud-texttospeech", "sounddevice", "soundfile"]
 vosk = ["vosk", "sounddevice"]
 silero = ["torch", "numpy", "sounddevice"]
 sound = ["sounddevice", "soundfile"]
+spacy = ["spacy"]
 all = [
     "google-cloud-texttospeech",
     "vosk",
@@ -61,6 +63,7 @@ all = [
     "numpy",
     "sounddevice",
     "soundfile",
+    "spacy",
 ]
 
 [tool.poetry.group.dev.dependencies]

{stark_engine-4.2.2 → stark_engine-4.3.0}/stark/__init__.py

@@ -1,46 +1,50 @@
 import asyncer
 
-from stark.interfaces.protocols import (
-    SpeechRecognizer,
-    SpeechRecognizerDelegate,
-    SpeechSynthesizer,
-    SpeechSynthesizerResult
-)   
 from stark.core import (
     Command,
+    CommandsContext,
+    CommandsManager,
     Pattern,
     Response,
     ResponseStatus,
-    CommandsContext,
-    CommandsManager
-)
-from stark.voice_assistant import (
-    VoiceAssistant,
-    Mode
 )
+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.interfaces.protocols import (
+    SpeechRecognizer,
+    SpeechRecognizerDelegate,
+    SpeechSynthesizer,
+    SpeechSynthesizerResult,
+)
+from stark.voice_assistant import Mode, VoiceAssistant
 
 
 async def run(
     manager: CommandsManager,
     speech_recognizer: SpeechRecognizer,
-    speech_synthesizer: SpeechSynthesizer
+    speech_synthesizer: SpeechSynthesizer,
+    processors: list[CommandsContextProcessor] = [SearchProcessor()],
 ):
     async with asyncer.create_task_group() as main_task_group:
         context = CommandsContext(
-            task_group = main_task_group, 
-            commands_manager = manager
+            task_group=main_task_group,
+            commands_manager=manager,
+            processors=processors,
         )
         voice_assistant = VoiceAssistant(
-            speech_recognizer = speech_recognizer,
-            speech_synthesizer = speech_synthesizer,
-            commands_context = context
+            speech_recognizer=speech_recognizer,
+            speech_synthesizer=speech_synthesizer,
+            commands_context=context,
         )
         speech_recognizer.delegate = voice_assistant
         context.delegate = voice_assistant
-        
+
+        health_check(context.pattern_parser, manager.commands)
+
         main_task_group.soonify(speech_recognizer.start_listening)()
         main_task_group.soonify(context.handle_responses)()
-        
+
         detector = BlockageDetector()
         main_task_group.soonify(detector.monitor)()

{stark_engine-4.2.2 → stark_engine-4.3.0}/stark/core/__init__.py

@@ -1,4 +1,3 @@
-from .patterns import Pattern, PatternParameter, rules
 from . import types
 from .command import (
     AsyncResponseHandler,
@@ -13,6 +12,4 @@ from .commands_context import (
     CommandsContextLayer,
 )
 from .commands_manager import CommandsManager
-
-Pattern.add_parameter_type(types.String)
-Pattern.add_parameter_type(types.Word)
+from .patterns import Pattern, PatternParameter, rules

{stark_engine-4.2.2 → stark_engine-4.3.0}/stark/core/command.py

@@ -31,11 +31,16 @@ from pydantic import BaseModel, Field
 from ..general.classproperty import classproperty
 from .patterns import Pattern
 
-ResponseOptions = Optional['Response'] | Generator[Optional['Response'], None, None] | AsyncGenerator[Optional['Response'], None]
+ResponseOptions = (
+    Optional["Response"]
+    | Generator[Optional["Response"], None, None]
+    | AsyncGenerator[Optional["Response"], None]
+)
 AwaitResponse = Awaitable[ResponseOptions]
 AsyncCommandRunner = Callable[..., AwaitResponse]
-SyncCommandRunner = Callable[..., Optional['Response']]
-CommandRunner = TypeVar('CommandRunner', bound = SyncCommandRunner | AsyncCommandRunner)
+SyncCommandRunner = Callable[..., Optional["Response"]]
+CommandRunner = TypeVar("CommandRunner", bound=SyncCommandRunner | AsyncCommandRunner)
+
 
 class Command(Generic[CommandRunner]):
     name: str
@@ -49,7 +54,12 @@ class Command(Generic[CommandRunner]):
         self._runner = runner
         update_wrapper(self, runner)
 
-    def run(self, parameters_dict: dict[str, Any] | None = None, / , **kwparameters: dict[str, Any]) -> AwaitResponse:
+    def run(
+        self,
+        parameters_dict: dict[str, Any] | None = None,
+        /,
+        **kwparameters: dict[str, Any],
+    ) -> AwaitResponse:
         # allow call both with and without dict unpacking
         # e.g. command.run(foo = bar, lorem = ipsum), command.run(**parameters) and command.run(parameters)
         # where parameters is dict {'foo': bar, 'lorem': ipsum}
@@ -64,20 +74,31 @@ class Command(Generic[CommandRunner]):
 
         runner: AsyncCommandRunner
 
-        if inspect.iscoroutinefunction(self._runner) or inspect.isasyncgen(self._runner):
-             # async functions (coroutines) and async generators are remain as is
+        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:
             # sync functions are wrapped with asyncer.asyncify to make them async (coroutines)
             # 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:
@@ -86,13 +107,15 @@ class Command(Generic[CommandRunner]):
             except Exception as e:
                 logger.error(e)
                 response = Response(
-                    text = f'Command {self} raised an exception: {e.__class__.__name__}',
-                    voice = f'Command {self} raised an exception: {e.__class__.__name__}',
-                    status = ResponseStatus.error
+                    text=f"Command {self} raised an exception: {e.__class__.__name__}",
+                    voice=f"Command {self} raised an exception: {e.__class__.__name__}",
+                    status=ResponseStatus.error,
                 )
             if inspect.isgenerator(response):
-                message = f'[WARNING] Command {self} is a sync GeneratorType that is not fully supported and may block the main thread. ' + \
-                            'Consider using the ResponseHandler.respond() or async approach instead.'
+                message = (
+                    f"[WARNING] Command {self} is a sync GeneratorType that is not fully supported and may block the main thread. "
+                    + "Consider using the ResponseHandler.respond() or async approach instead."
+                )
                 warnings.warn(message, UserWarning)
             return response
 
@@ -103,7 +126,8 @@ class Command(Generic[CommandRunner]):
         return self.run(*args, **kwargs)
 
     def __repr__(self):
-        return f'<Command {self.name}>'
+        return f"<Command {self.name}>"
+
 
 class ResponseStatus(Enum):
     none = auto()
@@ -113,9 +137,10 @@ class ResponseStatus(Enum):
     info = auto()
     error = auto()
 
+
 class Response(BaseModel):
-    voice: str = ''
-    text: str = ''
+    voice: str = ""
+    text: str = ""
     status: ResponseStatus = ResponseStatus.success
     needs_user_input: bool = False
     commands: list[Command] = []
@@ -124,7 +149,7 @@ class Response(BaseModel):
     id: UUID = Field(default_factory=uuid4)
     time: datetime = Field(default_factory=datetime.now)
 
-    _repeat_last: ClassVar[Response | None] = None # static instance
+    _repeat_last: ClassVar[Response | None] = None  # static instance
 
     @classproperty
     def repeat_last(cls) -> Response:
@@ -139,12 +164,24 @@ class Response(BaseModel):
     def __eq__(self, other):
         return self.id == other.id
 
+
 class ResponseHandler(Protocol):
-    def respond(self, response: Response): pass
-    def unrespond(self, response: Response): pass
-    def pop_context(self): pass
+    def respond(self, response: Response):
+        pass
+
+    def unrespond(self, response: Response):
+        pass
+
+    def pop_context(self):
+        pass
+
 
 class AsyncResponseHandler(Protocol):
-    async def respond(self, response: Response): pass
-    async def unrespond(self, response: Response): pass
-    async def pop_context(self): pass
+    async def respond(self, response: Response):
+        pass
+
+    async def unrespond(self, response: Response):
+        pass
+
+    async def pop_context(self):
+        pass

{stark_engine-4.2.2 → stark_engine-4.3.0}/stark/core/commands_context.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+import logging
 import warnings
-from dataclasses import dataclass
 from types import AsyncGeneratorType, GeneratorType
 from typing import Any, Protocol, runtime_checkable
 
@@ -9,6 +9,13 @@ import anyio
 from asyncer import syncify
 from asyncer._main import TaskGroup
 
+from stark.core.commands_context_processor import (
+    CommandsContextLayer,
+    RecognizedEntity,
+)
+from stark.core.parsing import PatternParser
+from stark.core.types.object import Object
+
 from ..general.dependencies import DependencyManager, default_dependency_manager
 from .command import (
     AsyncResponseHandler,
@@ -18,47 +25,58 @@ from .command import (
     ResponseHandler,
     ResponseOptions,
 )
-from .commands_manager import CommandsManager, SearchResult
+from .commands_manager import CommandsManager
 
+logger = logging.getLogger(__name__)
 
-@dataclass
-class CommandsContextLayer:
-    commands: list[Command]
-    parameters: dict[str, Any]
 
 @runtime_checkable
 class CommandsContextDelegate(Protocol):
-    async def commands_context_did_receive_response(self, response: Response): pass
-    def remove_response(self, response: Response): pass
+    async def commands_context_did_receive_response(self, response: Response):
+        pass
 
-class CommandsContext:
+    def remove_response(self, response: Response):
+        pass
 
+
+class CommandsContext:
     is_stopped = False
     commands_manager: CommandsManager
     dependency_manager: DependencyManager
+    pattern_parser: PatternParser
     last_response: Response | None = None
-    fallback_command: Command | None = None
+    context_queue: list[CommandsContextLayer]
 
     _delegate: CommandsContextDelegate | None = None
     _response_queue: list[Response]
-    _context_queue: list[CommandsContextLayer]
     _task_group: TaskGroup
 
-    def __init__(self, task_group: TaskGroup, commands_manager: CommandsManager, dependency_manager: DependencyManager = default_dependency_manager):
+    def __init__(
+        self,
+        task_group: TaskGroup,
+        commands_manager: CommandsManager,
+        dependency_manager: DependencyManager = default_dependency_manager,
+        processors: list[Any] | None = None,
+    ):
         assert isinstance(task_group, TaskGroup), task_group
         assert isinstance(commands_manager, CommandsManager)
         assert isinstance(dependency_manager, DependencyManager)
+        self.pattern_parser = PatternParser()
         self.commands_manager = commands_manager
-        self._context_queue = [self.root_context]
+        self.context_queue = [self.root_context]
         self._response_queue = []
         self._task_group = task_group
         self.dependency_manager = dependency_manager
         self.dependency_manager.add_dependency(None, AsyncResponseHandler, self)
         self.dependency_manager.add_dependency(None, ResponseHandler, SyncResponseHandler(self))
-        self.dependency_manager.add_dependency('inject_dependencies', None, self.inject_dependencies)
+        self.dependency_manager.add_dependency("inject_dependencies", None, self.inject_dependencies)
+        from .processors import SearchProcessor
+
+        self.processors = processors if processors is not None else [SearchProcessor()]
 
     @property
-    def delegate(self):
+    def delegate(self) -> CommandsContextDelegate:
+        assert self._delegate is not None
         return self._delegate
 
     @delegate.setter
@@ -71,46 +89,48 @@ class CommandsContext:
         return CommandsContextLayer(self.commands_manager.commands, {})
 
     async def process_string(self, string: str):
+        if not self.context_queue:
+            self.context_queue.append(self.root_context)
 
-        if not self._context_queue:
-            self._context_queue.append(self.root_context)
+        # Run the string and context queue through all the processors
 
-        # search commands
-        search_results = []
-        while self._context_queue:
-
-            current_context = self._context_queue[0]
-            search_results = await self.commands_manager.search(string = string, commands = current_context.commands)
+        recognized_entities: list[RecognizedEntity] = []
+        search_results: list[Any] = []
+        context_pops: int = 0
 
+        for processor in self.processors:
+            logger.debug(f"Processing context {processor=} with {string=} {recognized_entities=} {self.context_queue=}")
+            search_results, context_pops = await processor.process_string(string, self, recognized_entities)
             if search_results:
+                # Pop contexts as directed by processor
+                for _ in range(context_pops):
+                    if self.context_queue:
+                        self.context_queue.pop(0)
                 break
-            else:
-                self._context_queue.pop(0)
+        else:  # no results found at all
+            self.context_queue = [self.root_context]  # nothing found, reset to root context
 
-        if not search_results and self.fallback_command and (matches := await self.fallback_command.pattern.match(string)):
-            for match in matches:
-                search_results = [SearchResult(
-                    command = self.fallback_command,
-                    match_result = match,
-                    index = 0
-                )]
+        # Prepare and execute found commands;
 
         for search_result in search_results or []:
-
-            parameters = current_context.parameters
+            current_context = self.context_queue[0]
+            parameters: dict[str, Object] = {}
+            parameters.update(current_context.parameters)
             parameters.update(search_result.match_result.parameters)
             parameters.update(self.dependency_manager.resolve(search_result.command._runner))
-
             self.run_command(search_result.command, parameters)
 
+        return search_results or []
+
     def inject_dependencies(self, runner: Command[CommandRunner] | CommandRunner) -> CommandRunner:
         def injected_func(**kwargs) -> ResponseOptions:
             kwargs.update(self.dependency_manager.resolve(runner._runner if isinstance(runner, Command) else runner))
-            return runner(**kwargs) # type: ignore
-        return injected_func # type: ignore
+            return runner(**kwargs)  # type: ignore
+
+        return injected_func  # type: ignore
 
     def run_command(self, command: Command, parameters: dict[str, Any] = {}):
-        async def command_runner():
+        async def command_task():
             command_return = await command(parameters)
 
             if isinstance(command_return, Response):
@@ -122,8 +142,10 @@ class CommandsContext:
                         await self.respond(response)
 
             elif isinstance(command_return, GeneratorType):
-                message = f'[WARNING] Command {command} is a sync GeneratorType that is not fully supported and may block the main thread. ' + \
-                            'Consider using the ResponseHandler.respond() or async approach instead.'
+                message = (
+                    f"[WARNING] Command {command} is a sync GeneratorType that is not fully supported and may block the main thread. "
+                    + "Consider using the ResponseHandler.respond() or async approach instead."
+                )
                 warnings.warn(message, UserWarning)
                 for response in command_return:
                     if response:
@@ -133,13 +155,15 @@ class CommandsContext:
                 pass
 
             else:
-                raise TypeError(f'Command {command} returned {command_return} of type {type(command_return)} instead of Response or AsyncGeneratorType[Response]')
+                raise TypeError(
+                    f"Command {command} returned {command_return} of type {type(command_return)} instead of Response or AsyncGeneratorType[Response]"
+                )
 
-        self._task_group.soonify(command_runner)()
+        self._task_group.soonify(command_task)()
 
     # ResponseHandler
 
-    async def respond(self, response: Response): # async forces to run in main thread
+    async def respond(self, response: Response):  # async forces to run in main thread
         assert isinstance(response, Response)
         self._response_queue.append(response)
 
@@ -149,15 +173,15 @@ class CommandsContext:
         self.delegate.remove_response(response)
 
     async def pop_context(self):
-        self._context_queue.pop(0)
+        self.context_queue.pop(0)
 
     # Context
 
     def pop_to_root_context(self):
-        self._context_queue = [self.root_context]
+        self.context_queue = [self.root_context]
 
     def add_context(self, context: CommandsContextLayer):
-        self._context_queue.insert(0, context)
+        self.context_queue.insert(0, context)
 
     # ResponseQueue
 
@@ -181,18 +205,19 @@ class CommandsContext:
 
         if response.commands:
             newContext = CommandsContextLayer(response.commands, response.parameters)
-            self._context_queue.insert(0, newContext)
+            self.context_queue.insert(0, newContext)
 
         await self.delegate.commands_context_did_receive_response(response)
 
-class SyncResponseHandler: # needs for changing thread from worker to main in commands ran with asyncify
 
+class SyncResponseHandler:  # needs for changing thread from worker to main in commands ran with asyncify
     async_response_handler: ResponseHandler
 
     def __init__(self, async_response_handler: ResponseHandler):
         self.async_response_handler = async_response_handler
 
     # ResponseHandler
+    # TODO: review
 
     def respond(self, response: Response):
         syncify(self.async_response_handler.respond)(response)

stark_engine-4.3.0/stark/core/commands_context_processor.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import logging
+from abc import ABC
+from dataclasses import dataclass
+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 .commands_manager import SearchResult
+
+if TYPE_CHECKING:
+    from stark.core.commands_context import CommandsContext
+
+
+@dataclass
+class CommandsContextLayer:
+    commands: list[Command]
+    parameters: dict[str, Object]
+
+
+logger = logging.getLogger(__name__)
+
+
+class CommandsContextProcessor(ABC):
+    """
+    Abstract base class for processors in the CommandsContext pipeline.
+
+    Use cases:
+    - Override `process` for processors that need to view or operate on the entire context queue at once.
+      Example: NER markup for the string or AI-powered command search that considers all available contexts and commands in a single shot.
+    - Override `process_context` for processors that operate on each context layer individually.
+      Example: Classic pattern-based search.
+
+    In most cases you should only override/implement one.
+
+    The default implementation of `process` loops through the context queue, calling `process_context` for each layer.
+    If any layer returns non-empty results, processing stops and returns those results along with the number of contexts popped.
+    If all layers return empty results, all contexts are popped and an empty result list is returned.
+    """
+
+    async def process_string(
+        self, string: str, context: CommandsContext, recognized_entities: list[RecognizedEntity]
+    ) -> tuple[list[SearchResult], int]:
+        """
+        Processes the entire context queue.
+        Returns a tuple: (results, pops)
+          - results: list of SearchResult objects found (may be empty)
+          - pops: number of context layers to pop after processing (0 if found a command in the current context)
+
+        Default behavior: loop through context_queue, calling process_context for each.
+        Stops at the first non-empty result and returns (results, pops).
+        If all contexts return empty, returns ([], len(context_queue)). If no results, pop amount doesn't matter.
+
+        If don't implement a command search (for example, implementing some type of pre-processing), return ([], 0)
+        """
+        pops = 0
+        for layer in context.context_queue:
+            logger.debug(f"Command search processing context {layer=} with {recognized_entities=}")
+            results = await self.process_context_layer(
+                string,
+                context,
+                layer,
+                recognized_entities,
+            )
+            if results:
+                return results, pops
+            pops += 1
+        return [], pops
+
+    async def process_context_layer(
+        self,
+        string: str,
+        context: CommandsContext,
+        context_layer: CommandsContextLayer,
+        recognized_entities: list[RecognizedEntity],
+    ) -> list[SearchResult]:
+        """
+        Processes a single context layer.
+        Returns a list of SearchResult objects (may be empty).
+
+        Use case: Implement classic command search or other per-context logic.
+        If results are empty, the context will be popped by the caller.
+        """
+        ...