bear-utils 0.7.21__py3-none-any.whl → 0.7.23__py3-none-any.whl

bear_utils/__init__.py

@@ -1,3 +1,5 @@
+"""A module for Bear Utils, providing various utilities and tools."""
+
 from importlib.metadata import version
 
 from bear_epoch_time import EpochTimestamp, TimeTools
@@ -12,4 +14,25 @@ from .logging.logger_manager._common import VERBOSE_CONSOLE_FORMAT
 from .logging.logger_manager._styles import VERBOSE
 from .logging.loggers import BaseLogger, BufferLogger, ConsoleLogger, FileLogger
 
-__version__: str = version("bear-utils")
+__version__: str = version(distribution_name="bear_utils")
+
+__all__ = [
+    "DATE_FORMAT",
+    "DATE_TIME_FORMAT",
+    "VERBOSE",
+    "VERBOSE_CONSOLE_FORMAT",
+    "BaseLogger",
+    "BufferLogger",
+    "CacheWrapper",
+    "ConsoleLogger",
+    "DatabaseManager",
+    "EpochTimestamp",
+    "Events",
+    "FileHandlerFactory",
+    "FileLogger",
+    "SettingsManager",
+    "TimeTools",
+    "cache",
+    "cache_factory",
+    "get_settings_manager",
+]

bear_utils/ai/__init__.py

@@ -1,3 +1,5 @@
+"""AI Helpers Module for Bear Utils."""
+
 from .ai_helpers._common import (
     GPT_4_1,
     GPT_4_1_MINI,
@@ -10,7 +12,6 @@ from .ai_helpers._common import (
 from .ai_helpers._config import AIEndpointConfig
 from .ai_helpers._parsers import CommandResponseParser, PassthroughResponseParser, ResponseParser, TypedResponseParser
 from .ai_helpers._types import ResponseParser as BaseResponseParser
-from .ai_helpers._types import T_Response
 
 __all__ = [
     "GPT_4_1",
@@ -18,13 +19,12 @@ __all__ = [
     "GPT_4_1_NANO",
     "PRODUCTION_MODE",
     "TESTING_MODE",
-    "AIModel",
-    "EnvironmentMode",
     "AIEndpointConfig",
+    "AIModel",
+    "BaseResponseParser",
     "CommandResponseParser",
+    "EnvironmentMode",
     "PassthroughResponseParser",
     "ResponseParser",
     "TypedResponseParser",
-    "T_Response",
-    "BaseResponseParser",
 ]

bear_utils/ai/ai_helpers/__init__.py

@@ -1,8 +1,13 @@
+"""This module provides helper functions to create AI endpoints with various response parsing strategies."""
+
 from collections.abc import Callable
-from typing import Any
+from typing import Any, cast
+
+from rich.markdown import Markdown
+
+from bear_utils.logging import BaseLogger
 
-from ...logging import BaseLogger
-from ._common import GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, PRODUCTION_MODE, TESTING_MODE, AIModel, EnvironmentMode
+from ._common import GPT_4_1_NANO, PRODUCTION_MODE, TESTING_MODE, AIModel, EnvironmentMode
 from ._config import AIEndpointConfig
 from ._parsers import JSONResponseParser, ModularAIEndpoint, PassthroughResponseParser, TypedResponseParser
 
@@ -29,8 +34,11 @@ def create_typed_endpoint[T_Response](
         chat_model=chat_model,
         **kwargs,
     )
-    parser = TypedResponseParser(default_response=response_type, response_transformers=transformers)
-    return ModularAIEndpoint(config, logger, parser)  # type: ignore[return-value, arg-type]
+    parser: TypedResponseParser[type[T_Response]] = TypedResponseParser(
+        default_response=response_type,
+        response_transformers=transformers,
+    )
+    return cast("ModularAIEndpoint[T_Response]", ModularAIEndpoint(config, logger, parser))
 
 
 def create_command_endpoint[T_Response](
@@ -44,8 +52,7 @@ def create_command_endpoint[T_Response](
     chat_model: AIModel = GPT_4_1_NANO,
     **kwargs,
 ) -> ModularAIEndpoint[T_Response]:
-    from rich.markdown import Markdown
-
+    """Create an endpoint that returns a command response with Markdown formatting."""
     config = AIEndpointConfig(
         project_name=project_name,
         prompt=prompt,
@@ -56,12 +63,11 @@ def create_command_endpoint[T_Response](
         **kwargs,
     )
 
-    parser = TypedResponseParser(
+    parser: TypedResponseParser[T_Response] = TypedResponseParser(
         default_response=default_response,
         response_transformers={"response": lambda x: Markdown(str(x))},
     )
-
-    return ModularAIEndpoint(config, logger, parser)
+    return ModularAIEndpoint(config=config, logger=logger, response_parser=parser)
 
 
 def create_flexible_endpoint(
@@ -88,8 +94,8 @@ def create_flexible_endpoint(
         chat_model=chat_model,
         **kwargs,
     )
-    parser = JSONResponseParser(required_fields, transformers)
-    return ModularAIEndpoint(config, logger, parser)
+    parser = JSONResponseParser(required_fields=required_fields, response_transformers=transformers)
+    return ModularAIEndpoint(config=config, logger=logger, response_parser=parser)
 
 
 def create_simple_endpoint(
@@ -118,13 +124,13 @@ def create_simple_endpoint(
 
 
 __all__: list[str] = [
-    "create_typed_endpoint",
-    "create_command_endpoint",
-    "create_flexible_endpoint",
-    "create_simple_endpoint",
-    "AIEndpointConfig",
-    "EnvironmentMode",
     "PRODUCTION_MODE",
     "TESTING_MODE",
+    "AIEndpointConfig",
+    "EnvironmentMode",
     "ModularAIEndpoint",
+    "create_command_endpoint",
+    "create_flexible_endpoint",
+    "create_simple_endpoint",
+    "create_typed_endpoint",
 ]

bear_utils/ai/ai_helpers/_parsers.py

@@ -1,14 +1,17 @@
-import json
 from collections.abc import Callable
-from typing import Any, Generic, cast
+import json
+from typing import Any, cast
 
 from httpx import AsyncClient, Headers, Response
 from rich.markdown import Markdown
 from singleton_base.singleton_base_new import SingletonBase
 
-from ... import BaseLogger, EpochTimestamp, SettingsManager, get_settings_manager
+from bear_utils import BaseLogger, EpochTimestamp, SettingsManager, get_settings_manager
+
 from . import AIEndpointConfig
-from ._types import ResponseParser, T_Response
+from ._types import ResponseParser
+
+SUCCESSFUL_STATUS_CODE = 200
 
 
 class JSONResponseParser(ResponseParser[dict[str, Any]]):
@@ -20,7 +23,7 @@ class JSONResponseParser(ResponseParser[dict[str, Any]]):
 
     async def parse(self, raw_response: dict, logger: BaseLogger) -> dict[str, Any]:
         """Parse JSON response with configurable validation and transformation."""
-        default = self.get_default_response()
+        default: dict[str, Any] = self.get_default_response()
 
         output = raw_response.get("output", "")
         if not output:
@@ -56,14 +59,14 @@ class JSONResponseParser(ResponseParser[dict[str, Any]]):
         return {"error": "Failed to parse response"}
 
 
-class TypedResponseParser(ResponseParser[T_Response], Generic[T_Response]):
+class TypedResponseParser[T_Response](ResponseParser[T_Response]):
     def __init__(self, default_response: T_Response, response_transformers: dict[str, Callable] | None = None):
         self.default_response: T_Response = default_response
         self.response_transformers = response_transformers or {}
-        self.required_fields = list(cast(dict, self.default_response).keys())
+        self.required_fields = list(cast("dict", self.default_response).keys())
 
     def get_default_response(self) -> T_Response:
-        return cast(T_Response, self.default_response)
+        return cast("T_Response", self.default_response)
 
     async def parse(self, raw_response: dict, logger: BaseLogger) -> T_Response:
         """Parse JSON response with strict typing."""
@@ -90,18 +93,17 @@ class TypedResponseParser(ResponseParser[T_Response], Generic[T_Response]):
             for field_name, transformer in self.response_transformers.items():
                 if field_name in response_dict:
                     response_dict[field_name] = transformer(response_dict[field_name])
-            return cast(T_Response, response_dict)
+            return cast("T_Response", response_dict)
 
         except json.JSONDecodeError as e:
             logger.error(f"Failed to parse response JSON: {e}")
             return default
 
 
-class CommandResponseParser(TypedResponseParser):
+class CommandResponseParser[T_Response](TypedResponseParser[T_Response]):
     """Specialized parser for command-based responses."""
 
     def __init__(self, response_type: type[T_Response]):
-
         super().__init__(
             default_response=response_type(),
             response_transformers={
@@ -114,17 +116,23 @@ class PassthroughResponseParser(ResponseParser[dict[str, Any]]):
     """Parser that returns the raw output without JSON parsing."""
 
     async def parse(self, raw_response: dict, logger: BaseLogger) -> dict[str, Any]:
+        """Return the raw output from the response without parsing."""
         output = raw_response.get("output", "")
-        return {"output": output}
+        return {"output": output, "logger": logger}
 
     def get_default_response(self) -> dict[str, Any]:
         return {"output": ""}
 
 
-class ModularAIEndpoint(SingletonBase, Generic[T_Response]):
+class ModularAIEndpoint[T_Response](SingletonBase):
     """Modular AI endpoint for flexible communication patterns."""
 
-    def __init__(self, config: AIEndpointConfig, logger: BaseLogger, response_parser: ResponseParser[T_Response]):
+    def __init__(
+        self,
+        config: AIEndpointConfig,
+        logger: BaseLogger,
+        response_parser: ResponseParser[T_Response],
+    ) -> None:
         self.config: AIEndpointConfig = config
         self.logger: BaseLogger = logger
         self.response_parser: ResponseParser[T_Response] = response_parser
@@ -136,9 +144,8 @@ class ModularAIEndpoint(SingletonBase, Generic[T_Response]):
         self.settings_manager: SettingsManager = get_settings_manager(self.config.project_name)
         self.set_session_id(new=True)
 
-    def set_session_id(self, new: bool = False):
-        """
-        Set the session ID for the current interaction.
+    def set_session_id(self, new: bool = False) -> None:
+        """Set the session ID for the current interaction.
 
         Args:
             new (bool): If True, start a new session; otherwise, continue the existing session.
@@ -178,11 +185,10 @@ class ModularAIEndpoint(SingletonBase, Generic[T_Response]):
                         }
                     ),
                 )
-                if response.status_code == 200:
+                if response.status_code == SUCCESSFUL_STATUS_CODE:
                     return await parser.parse(response.json(), self.logger)
-                else:
-                    self.logger.error(f"Failed to send message to AI: {response.status_code} - {response.text}")
-                    return parser.get_default_response()
+                self.logger.error(f"Failed to send message to AI: {response.status_code} - {response.text}")
+                return parser.get_default_response()
             except Exception as e:
                 self.logger.error(f"Exception during AI communication: {e}")
                 return parser.get_default_response()

bear_utils/ai/ai_helpers/_types.py

@@ -1,20 +1,15 @@
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar
 
-from ... import BaseLogger
+from bear_utils.logging import BaseLogger
 
-T_Response = TypeVar("T_Response")
 
-
-class ResponseParser(ABC, Generic[T_Response]):
+class ResponseParser[T_Response](ABC):
     """Abstract base class for response parsers."""
 
     @abstractmethod
     async def parse(self, raw_response: dict, logger: BaseLogger) -> T_Response:
         """Parse the raw response into the desired format."""
-        pass
 
     @abstractmethod
     def get_default_response(self) -> T_Response:
         """Return a default response structure."""
-        pass

bear_utils/cache/__init__.py

@@ -1,5 +1,8 @@
+"""A set of helper caching utilities for bear_utils."""
+
 import functools
 from pathlib import Path
+from typing import Any
 
 from diskcache import Cache
 
@@ -7,15 +10,20 @@ DEFAULT_CACHE_DIR = Path("~/.cache/app_cache").expanduser()
 
 
 class CacheWrapper:
-    """
-    A simple wrapper around diskcache.Cache to provide a consistent interface.
+    """A simple wrapper around diskcache.Cache to provide a consistent interface.
+
     This class allows for easy caching of function results with a specified directory,
     size limit, and default timeout.
     """
 
-    def __init__(self, directory=None, size_limit=None, default_timeout=None, **kwargs):
-        """
-        Initialize the CacheWrapper with a specified directory, size limit, and default timeout.
+    def __init__(
+        self,
+        directory: str | None = None,
+        size_limit: int | None = None,
+        default_timeout: int | None = None,
+        **kwargs,
+    ) -> None:
+        """Initialize the CacheWrapper with a specified directory, size limit, and default timeout.
 
         Args:
             directory (str, optional): Directory path for the cache. Defaults to ~/.cache/app_cache.
@@ -25,20 +33,24 @@ class CacheWrapper:
         self.cache = Cache(directory or DEFAULT_CACHE_DIR, size_limit=size_limit or 1_000_000_000, **kwargs)
         self.default_timeout = default_timeout
 
-    def get(self, key, default=None):
+    def get(self, key: Any, default: Any = None) -> Any:
         """Get a value from the cache."""
         return self.cache.get(key, default=default)
 
-    def set(self, key, value, expire=None) -> None:
+    def set(self, key: Any, value: Any, expire: int | None = None) -> None:
         """Set a value in the cache."""
         if expire is None:
             expire = self.default_timeout
         self.cache.set(key, value, expire=expire)
 
 
-def cache_factory(directory=None, size_limit=None, default_timeout=None, **kwargs):
-    """
-    Creates and configures a cache decorator factory.
+def cache_factory(
+    directory: str | None = None,
+    size_limit: int | None = None,
+    default_timeout: int | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Creates and configures a cache decorator factory.
 
     Args:
         directory (str, optional): Cache directory path. Defaults to ~/.cache/app_cache.
@@ -63,19 +75,18 @@ def cache_factory(directory=None, size_limit=None, default_timeout=None, **kwarg
         def another_function(x, y):
             return x * y
     """
-    if directory is None:
-        directory = Path(DEFAULT_CACHE_DIR)
-    if not directory.exists():
-        directory.mkdir(parents=True, exist_ok=True)
+    local_directory: Path | None = Path(directory).expanduser() if directory else None
+    if local_directory is None:
+        local_directory = Path(DEFAULT_CACHE_DIR)
+    local_directory.mkdir(parents=True, exist_ok=True)
 
     if size_limit is None:
         size_limit = 1_000_000_000
 
-    cache_instance = Cache(directory, size_limit=size_limit, **kwargs)
+    cache_instance = Cache(local_directory, size_limit=size_limit, **kwargs)
 
-    def decorator(func=None, *, expire=default_timeout, key=None):
-        """
-        Decorator that caches function results.
+    def decorator(func: object | None = None, *, expire: int | None = default_timeout, key: Any = None) -> object:
+        """Decorator that caches function results.
 
         Args:
             func: The function to cache (when used as @cache)
@@ -86,20 +97,21 @@ def cache_factory(directory=None, size_limit=None, default_timeout=None, **kwarg
             callable: Decorated function or decorator
         """
 
-        def actual_decorator(fn):
-            def wrapper(*args, **kwargs):
+        def actual_decorator(fn: Any) -> object:
+            """Actual decorator that wraps the function with caching logic."""
+
+            def wrapper(*args, **kwargs) -> tuple[Any, ...]:
                 if key is not None:
                     cache_key = key(fn, *args, **kwargs)
                 else:
                     cache_key = (fn.__module__, fn.__qualname__, args, frozenset(kwargs.items()))
 
-                # Try to get from cache
                 result = cache_instance.get(cache_key, default=None)
                 if result is not None:
                     return result
 
                 # If not in cache, compute and store
-                result = fn(*args, **kwargs)
+                result: Any = fn(*args, **kwargs)
                 cache_instance.set(cache_key, result, expire=expire)
                 return result
 
@@ -116,4 +128,4 @@ def cache_factory(directory=None, size_limit=None, default_timeout=None, **kwarg
 
 cache = cache_factory()
 
-__all__ = ["CacheWrapper", "cache_factory", "cache"]
+__all__ = ["CacheWrapper", "cache", "cache_factory"]

bear_utils/cli/__init__.py

@@ -1,4 +1,17 @@
+"""A set of command-line interface (CLI) utilities for bear_utils."""
+
 from .commands import GitCommand, MaskShellCommand, OPShellCommand, UVShellCommand
 from .shell._base_command import BaseShellCommand
 from .shell._base_shell import SimpleShellSession, shell_session
 from .shell._common import DEFAULT_SHELL
+
+__all__ = [
+    "DEFAULT_SHELL",
+    "BaseShellCommand",
+    "GitCommand",
+    "MaskShellCommand",
+    "OPShellCommand",
+    "SimpleShellSession",
+    "UVShellCommand",
+    "shell_session",
+]

bear_utils/cli/commands.py

@@ -1,3 +1,5 @@
+"""Shell Commands Module for Bear Utils."""
+
 from typing import Self
 
 from .shell._base_command import BaseShellCommand
@@ -8,7 +10,8 @@ class OPShellCommand(BaseShellCommand):
 
     command_name = "op"
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize the OPShellCommand with the op command."""
         super().__init__(*args, **kwargs)
 
     @classmethod
@@ -22,11 +25,12 @@ class UVShellCommand(BaseShellCommand):
 
     command_name = "uv"
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize the UVShellCommand with the uv command."""
         super().__init__(*args, **kwargs)
 
     @classmethod
-    def pip(cls, s="", *args, **kwargs) -> Self:
+    def pip(cls, s: str = "", *args, **kwargs) -> Self:
         """Create a piped command for uv"""
         if s:
             return cls.sub(f"pip {s}", *args, **kwargs)
@@ -38,11 +42,12 @@ class MaskShellCommand(BaseShellCommand):
 
     command_name = "mask"
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize the MaskShellCommand with the mask command."""
         super().__init__(*args, **kwargs)
 
     @classmethod
-    def maskfile(cls, maskfile, *args, **kwargs) -> Self:
+    def maskfile(cls, maskfile: str, *args, **kwargs) -> Self:
         """Create a maskfile command with the specified maskfile"""
         return cls.sub("--maskfile", *args, **kwargs).value(maskfile)
 
@@ -57,7 +62,8 @@ class GitCommand(BaseShellCommand):
 
     command_name = "git"
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize the GitCommand with the git command."""
         super().__init__(*args, **kwargs)
 
     @classmethod
@@ -76,7 +82,7 @@ class GitCommand(BaseShellCommand):
         return cls.sub("log", *args, **kwargs)
 
     @classmethod
-    def add(cls, files, *args, **kwargs) -> "GitCommand":
+    def add(cls, files: str, *args, **kwargs) -> "GitCommand":
         """Add files to the staging area"""
         return cls.sub("add", *args, **kwargs).value(files)
 
@@ -92,8 +98,8 @@ class GitCommand(BaseShellCommand):
 
 
 __all__ = [
+    "GitCommand",
     "MaskShellCommand",
     "OPShellCommand",
     "UVShellCommand",
-    "GitCommand",
 ]

bear_utils/cli/prompt_helpers.py

@@ -1,12 +1,16 @@
+"""Prompt Helpers Module for user input handling."""
+
 from typing import Any, overload
 
 from prompt_toolkit import prompt
 from prompt_toolkit.completion import WordCompleter
 from prompt_toolkit.validation import ValidationError, Validator
 
-from ..constants._exceptions import UserCancelled
-from ..constants._lazy_typing import LitBool, LitFloat, LitInt, LitStr, OptBool, OptFloat, OptInt, OptStr
-from ..logging.loggers import get_console
+from bear_utils.constants._exceptions import UserCancelledError
+from bear_utils.constants._lazy_typing import LitBool, LitFloat, LitInt, LitStr, OptBool, OptFloat, OptInt, OptStr
+from bear_utils.logging.loggers import get_console
+
+# TODO: Overhaul this trash, it is written like absolute garbage.
 
 
 @overload
@@ -25,12 +29,11 @@ def ask_question(question: str, expected_type: LitStr, default: OptStr = None, *
 def ask_question(question: str, expected_type: LitBool, default: OptBool = None, **kwargs) -> bool: ...
 
 
-def ask_question(question: str, expected_type: Any, default: Any = None, **kwargs) -> Any:
-    """
-    Ask a question and return the answer, ensuring the entered type is correct and a value is entered.
+def ask_question(question: str, expected_type: Any, default: Any = None, **_) -> Any:
+    """Ask a question and return the answer, ensuring the entered type is correct and a value is entered.
 
     This function will keep asking until it gets a valid response or the user cancels with Ctrl+C.
-    If the user cancels, a UserCancelled is raised.
+    If the user cancels, a UserCancelledError is raised.
 
     Args:
         question: The prompt question to display
@@ -41,19 +44,18 @@ def ask_question(question: str, expected_type: Any, default: Any = None, **kwarg
         The user's response in the expected type
 
     Raises:
-        UserCancelled: If the user cancels input with Ctrl+C
+        UserCancelledError: If the user cancels input with Ctrl+C
         ValueError: If an unsupported type is specified
     """
     console, sub = get_console("prompt_helpers.py")
     try:
         while True:
-            console.info(question)
+            console.print(question)
             response: str = prompt("> ")
             if response == "":
                 if default is not None:
                     return default
-                else:
-                    continue
+                continue
             match expected_type:
                 case "int":
                     try:
@@ -76,19 +78,17 @@ def ask_question(question: str, expected_type: Any, default: Any = None, **kwarg
                     lower_response = response.lower()
                     if lower_response in ("true", "t", "yes", "y", "1"):
                         return True
-                    elif lower_response in ("false", "f", "no", "n", "0"):
+                    if lower_response in ("false", "f", "no", "n", "0"):
                         return False
-                    else:
-                        sub.error("Invalid input. Please enter a valid boolean (true/false, yes/no, etc).")
+                    sub.error("Invalid input. Please enter a valid boolean (true/false, yes/no, etc).")
                 case _:
                     raise ValueError(f"Unsupported type: {expected_type}")
     except KeyboardInterrupt:
-        raise UserCancelled("User cancelled input")
+        raise UserCancelledError("User cancelled input") from None
 
 
-def ask_yes_no(question, default=None, **kwargs) -> None | bool:
-    """
-    Ask a yes or no question and return the answer.
+def ask_yes_no(question: str, default: None | Any = None, **kwargs) -> None | bool:
+    """Ask a yes or no question and return the answer.
 
     Args:
         question: The prompt question to display
@@ -97,6 +97,7 @@ def ask_yes_no(question, default=None, **kwargs) -> None | bool:
     Returns:
         True for yes, False for no, or None if no valid response is given
     """
+    kwargs = kwargs or {}
     sub, console = get_console("prompt_helpers.py")
     try:
         while True:
@@ -106,26 +107,23 @@ def ask_yes_no(question, default=None, **kwargs) -> None | bool:
             if response == "":
                 if default is not None:
                     return default
-                else:
-                    continue
+                continue
 
             if response.lower() in ["yes", "y"]:
                 return True
-            elif response.lower() in ["no", "n"]:
+            if response.lower() in ["no", "n"]:
                 return False
-            elif response.lower() in ["exit", "quit"]:
+            if response.lower() in ["exit", "quit"]:
                 return None
-            else:
-                console.error("Invalid input. Please enter 'yes' or 'no' or exit.")
-                continue
+            console.error("Invalid input. Please enter 'yes' or 'no' or exit.")
+            continue
     except KeyboardInterrupt:
         console.warning("KeyboardInterrupt: Exiting the prompt.")
         return None
 
 
-def restricted_prompt(question, valid_options, exit_command="exit", **kwargs):
-    """
-    Continuously prompt the user until they provide a valid response or exit.
+def restricted_prompt(question: str, valid_options: list[str], exit_command: str = "exit", **kwargs) -> None | str:
+    """Continuously prompt the user until they provide a valid response or exit.
 
     Args:
         question: The prompt question to display
@@ -135,15 +133,20 @@ def restricted_prompt(question, valid_options, exit_command="exit", **kwargs):
     Returns:
         The user's response or None if they chose to exit
     """
+    kwargs = kwargs or {}
     sub, console = get_console("prompt_helpers.py")
-    completer_options = valid_options + [exit_command]
+    completer_options: list[str] = [*valid_options, exit_command]
     completer = WordCompleter(completer_options)
 
     class OptionValidator(Validator):
-        def validate(self, document):
-            text = document.text.lower()
+        def validate(self, document: Any) -> None:
+            """Validate the user's input against the valid options."""
+            text: str = document.text.lower()
             if text != exit_command and text not in valid_options:
-                raise ValidationError(f'Please enter one of: {", ".join(valid_options)} (or "{exit_command}" to quit)')  # type: ignore
+                raise ValidationError(
+                    message=f"Invalid option: {text}. Please choose from {', '.join(valid_options)} or type '{exit_command}' to exit.",
+                    cursor_position=len(document.text),
+                )
 
     try:
         while True:
@@ -157,9 +160,12 @@ def restricted_prompt(question, valid_options, exit_command="exit", **kwargs):
                 )
                 response = response.lower()
 
-            if response == exit_command or response == "":
+            if response == exit_command:
                 return None
-            elif response in valid_options:
+            if response == "":
+                sub.error("No input provided. Please enter a valid option or exit.")
+                continue
+            if response in valid_options:
                 return response
     except KeyboardInterrupt:
         sub.warning("KeyboardInterrupt: Exiting the prompt.")