bear-utils 0.7.11__py3-none-any.whl

bear_utils/__init__.py

@@ -0,0 +1,13 @@
+from .cache import CacheWrapper, cache, cache_factory
+from .config.settings_manager import SettingsManager, get_settings_manager
+from .constants.date_related import DATE_FORMAT, DATE_TIME_FORMAT
+from .database import DatabaseManager
+from .events import Events
+from .files.file_handlers.file_handler_factory import FileHandlerFactory
+from .logging.logger_manager._common import VERBOSE_CONSOLE_FORMAT
+from .logging.logger_manager._styles import VERBOSE
+from .logging.loggers import BaseLogger, BufferLogger, ConsoleLogger, FileLogger
+from .time._time_class import EpochTimestamp
+from .time.time_manager import TimeTools
+
+__version__ = "__version__ = "0.7.11""

bear_utils/ai/__init__.py

@@ -0,0 +1,30 @@
+from .ai_helpers._common import (
+    GPT_4_1,
+    GPT_4_1_MINI,
+    GPT_4_1_NANO,
+    PRODUCTION_MODE,
+    TESTING_MODE,
+    AIModel,
+    EnvironmentMode,
+)
+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",
+    "GPT_4_1_MINI",
+    "GPT_4_1_NANO",
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "AIModel",
+    "EnvironmentMode",
+    "AIEndpointConfig",
+    "CommandResponseParser",
+    "PassthroughResponseParser",
+    "ResponseParser",
+    "TypedResponseParser",
+    "T_Response",
+    "BaseResponseParser",
+]

bear_utils/ai/ai_helpers/__init__.py

@@ -0,0 +1,130 @@
+from collections.abc import Callable
+from typing import Any
+
+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 ._config import AIEndpointConfig
+from ._parsers import JSONResponseParser, ModularAIEndpoint, PassthroughResponseParser, TypedResponseParser
+
+
+def create_typed_endpoint[T_Response](
+    response_type: type[T_Response],
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    transformers: dict[str, Callable] | None = None,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[T_Response]:
+    """Create an endpoint with strict TypedDict response typing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        environment=environment,
+        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]
+
+
+def create_command_endpoint[T_Response](
+    default_response: T_Response,
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    environment: EnvironmentMode = EnvironmentMode.PRODUCTION,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[T_Response]:
+    from rich.markdown import Markdown
+
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+
+    parser = TypedResponseParser(
+        default_response=default_response,
+        response_transformers={"response": lambda x: Markdown(str(x))},
+    )
+
+    return ModularAIEndpoint(config, logger, parser)
+
+
+def create_flexible_endpoint(
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    required_fields: list | None = None,
+    transformers: dict[str, Callable] | None = None,
+    append_json: bool = True,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[dict[str, Any]]:
+    """Create an endpoint with flexible JSON parsing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        append_json_suffix=append_json,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+    parser = JSONResponseParser(required_fields, transformers)
+    return ModularAIEndpoint(config, logger, parser)
+
+
+def create_simple_endpoint(
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[dict[str, Any]]:
+    """Create an endpoint that returns raw output without JSON parsing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        append_json_suffix=False,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+    parser = PassthroughResponseParser()
+    return ModularAIEndpoint(config, logger, parser)
+
+
+__all__: list[str] = [
+    "create_typed_endpoint",
+    "create_command_endpoint",
+    "create_flexible_endpoint",
+    "create_simple_endpoint",
+    "AIEndpointConfig",
+    "EnvironmentMode",
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "ModularAIEndpoint",
+]

bear_utils/ai/ai_helpers/_common.py

@@ -0,0 +1,19 @@
+from enum import Enum, StrEnum
+
+
+class EnvironmentMode(Enum):
+    TESTING = "testing"
+    PRODUCTION = "production"
+
+
+class AIModel(StrEnum):
+    GPT_4_1_NANO = "gpt-4.1-nano"
+    GPT_4_1_MINI = "gpt-4.1-mini"
+    GPT_4_1 = "gpt-4.1"
+
+
+GPT_4_1_NANO = AIModel.GPT_4_1_NANO
+GPT_4_1_MINI = AIModel.GPT_4_1_MINI
+GPT_4_1 = AIModel.GPT_4_1
+TESTING_MODE = EnvironmentMode.TESTING
+PRODUCTION_MODE = EnvironmentMode.PRODUCTION

bear_utils/ai/ai_helpers/_config.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+
+from ._common import GPT_4_1_NANO, PRODUCTION_MODE, AIModel, EnvironmentMode
+
+
+@dataclass
+class AIEndpointConfig:
+    """Configuration for AI endpoint communication."""
+
+    project_name: str
+    bearer_token: str
+    prompt: str
+    testing_url: str
+    production_url: str
+    connection_timeout: int = 20
+    append_json_suffix: bool = True
+    json_suffix: str = " \nEnsure to output your response as json as specified in the prompt"
+    chat_model: AIModel | str = GPT_4_1_NANO
+    environment: EnvironmentMode = PRODUCTION_MODE
+
+    @property
+    def url(self) -> str:
+        """Get the appropriate URL based on environment."""
+        return self.testing_url if self.environment == EnvironmentMode.TESTING else self.production_url

bear_utils/ai/ai_helpers/_parsers.py

@@ -0,0 +1,188 @@
+import json
+from collections.abc import Callable
+from typing import Any, Generic, 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 . import AIEndpointConfig
+from ._types import ResponseParser, T_Response
+
+
+class JSONResponseParser(ResponseParser[dict[str, Any]]):
+    """Parser for JSON responses with flexible output structure."""
+
+    def __init__(self, required_fields: list | None = None, response_transformers: dict[str, Callable] | None = None):
+        self.required_fields = required_fields or []
+        self.response_transformers = response_transformers or {}
+
+    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()
+
+        output = raw_response.get("output", "")
+        if not output:
+            logger.error("No output received from AI.")
+            return default
+
+        try:
+            response_dict = json.loads(output)
+            if not isinstance(response_dict, dict):
+                logger.error("Response is not a valid JSON object.")
+                return default
+
+            logger.verbose(json.dumps(response_dict, indent=4))
+
+            if self.required_fields:
+                missing_fields = [field for field in self.required_fields if field not in response_dict]
+                if missing_fields:
+                    logger.error(f"Response JSON missing required fields: {missing_fields}")
+                    return default
+
+            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 response_dict
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse response JSON: {e}")
+            return default
+
+    def get_default_response(self) -> dict[str, Any]:
+        """Return a basic default response."""
+        return {"error": "Failed to parse response"}
+
+
+class TypedResponseParser(ResponseParser[T_Response], Generic[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())
+
+    def get_default_response(self) -> T_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."""
+        default = self.get_default_response()
+
+        output = raw_response.get("output", "")
+        if not output:
+            logger.error("No output received from AI.")
+            return default
+
+        try:
+            response_dict = json.loads(output)
+            if not isinstance(response_dict, dict):
+                logger.error("Response is not a valid JSON object.")
+                return default
+
+            logger.verbose(json.dumps(response_dict, indent=4))
+
+            missing_fields = [field for field in self.required_fields if field not in response_dict]
+            if missing_fields:
+                logger.error(f"Response JSON missing required fields: {missing_fields}")
+                return default
+
+            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)
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse response JSON: {e}")
+            return default
+
+
+class CommandResponseParser(TypedResponseParser):
+    """Specialized parser for command-based responses."""
+
+    def __init__(self, response_type: type[T_Response]):
+
+        super().__init__(
+            default_response=response_type(),
+            response_transformers={
+                "output": lambda x: Markdown(x) if isinstance(x, str) else x,
+            },
+        )
+
+
+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]:
+        output = raw_response.get("output", "")
+        return {"output": output}
+
+    def get_default_response(self) -> dict[str, Any]:
+        return {"output": ""}
+
+
+class ModularAIEndpoint(SingletonBase, Generic[T_Response]):
+    """Modular AI endpoint for flexible communication patterns."""
+
+    def __init__(self, config: AIEndpointConfig, logger: BaseLogger, response_parser: ResponseParser[T_Response]):
+        self.config: AIEndpointConfig = config
+        self.logger: BaseLogger = logger
+        self.response_parser: ResponseParser[T_Response] = response_parser
+        self.session_id: str | None = None
+
+        self.logger.verbose(f"Using URL: {self.config.url}")
+        self.logger.verbose(f"Using prompt: {self.config.prompt[:50]}...")
+
+        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.
+
+        Args:
+            new (bool): If True, start a new session; otherwise, continue the existing session.
+        """
+        if new or not self.settings_manager.has("session_id"):
+            self.logger.verbose("Starting a new session.")
+            self.session_id = str(EpochTimestamp.now())
+            self.settings_manager.set("session_id", self.session_id)
+        else:
+            self.logger.verbose("Continuing existing session with AI.")
+            self.session_id = self.settings_manager.get("session_id")
+        self.logger.debug(f"Using session ID: {self.session_id}")
+
+    def _prepare_message(self, message: str) -> str:
+        """Prepare the message with optional JSON suffix."""
+        if self.config.append_json_suffix:
+            return f"{message}{self.config.json_suffix}"
+        return message
+
+    async def send_message(self, message: str, override_parser: ResponseParser[T_Response] | None = None) -> T_Response:
+        """Send a message to the AI endpoint with flexible response parsing."""
+        parser: ResponseParser[T_Response] = override_parser or self.response_parser
+        async with AsyncClient(timeout=self.config.connection_timeout) as client:
+            try:
+                response: Response = await client.post(
+                    url=self.config.url,
+                    json={
+                        "chatModel": self.config.chat_model,
+                        "chatInput": self._prepare_message(message),
+                        "sessionId": self.session_id,
+                        "systemPrompt": self.config.prompt,
+                    },
+                    headers=Headers(
+                        {
+                            "Content-Type": "application/json",
+                            "Authorization": f"Bearer {self.config.bearer_token}",
+                        }
+                    ),
+                )
+                if response.status_code == 200:
+                    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()
+            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

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from ... import BaseLogger
+
+T_Response = TypeVar("T_Response")
+
+
+class ResponseParser(ABC, Generic[T_Response]):
+    """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

@@ -0,0 +1,119 @@
+import functools
+from pathlib import Path
+
+from diskcache import Cache
+
+DEFAULT_CACHE_DIR = Path("~/.cache/app_cache").expanduser()
+
+
+class CacheWrapper:
+    """
+    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.
+
+        Args:
+            directory (str, optional): Directory path for the cache. Defaults to ~/.cache/app_cache.
+            size_limit (int, optional): Maximum size of the cache in bytes. Defaults to 1_000_000_000.
+            default_timeout (int, optional): Default timeout for cache entries in seconds. Defaults to None.
+        """
+        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):
+        """Get a value from the cache."""
+        return self.cache.get(key, default=default)
+
+    def set(self, key, value, expire=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.
+
+    Args:
+        directory (str, optional): Cache directory path. Defaults to ~/.cache/app_cache.
+        size_limit (int, optional): Maximum size in bytes. Defaults to None.
+        default_timeout (int, optional): Default timeout in seconds. Defaults to None.
+        **kwargs: Additional arguments to pass to the Cache constructor.
+
+    Returns:
+        function: A decorator function that can be used to cache function results.
+
+    Examples:
+        # Create a custom cache
+        my_cache = cache_factory(directory='/tmp/mycache', default_timeout=3600)
+
+        # Use as a simple decorator
+        @my_cache
+        def expensive_function(x, y):
+            return x + y
+
+        # Use with custom parameters
+        @my_cache(expire=60)
+        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)
+
+    if size_limit is None:
+        size_limit = 1_000_000_000
+
+    cache_instance = Cache(directory, size_limit=size_limit, **kwargs)
+
+    def decorator(func=None, *, expire=default_timeout, key=None):
+        """
+        Decorator that caches function results.
+
+        Args:
+            func: The function to cache (when used as @cache)
+            expire (int, optional): Expiration time in seconds.
+            key (callable, optional): Custom key function.
+
+        Returns:
+            callable: Decorated function or decorator
+        """
+
+        def actual_decorator(fn):
+            def wrapper(*args, **kwargs):
+                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)
+                cache_instance.set(cache_key, result, expire=expire)
+                return result
+
+            # Preserve function metadata
+            return functools.update_wrapper(wrapper, fn)
+
+        # Handle both @cache and @cache(expire=300) styles
+        if func is None:
+            return actual_decorator
+        return actual_decorator(func)
+
+    return decorator
+
+
+cache = cache_factory()
+
+__all__ = ["CacheWrapper", "cache_factory", "cache"]

bear_utils/cli/__init__.py

@@ -0,0 +1,4 @@
+from .commands import MaskShellCommand, OPShellCommand, UVShellCommand
+from .shell._base_command import BaseShellCommand
+from .shell._base_shell import SimpleShellSession, shell_session
+from .shell._common import DEFAULT_SHELL

bear_utils/cli/commands.py

@@ -0,0 +1,59 @@
+from typing import Self
+
+from .shell._base_command import BaseShellCommand
+
+
+class OPShellCommand(BaseShellCommand):
+    """OP command for running 1Password CLI commands"""
+
+    command_name = "op"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def read(cls, *args, **kwargs) -> Self:
+        """Create a read command for 1Password"""
+        return cls.sub("read", *args, **kwargs)
+
+
+class UVShellCommand(BaseShellCommand):
+    """UV command for running Python scripts with uv"""
+
+    command_name = "uv"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def pip(cls, s="", *args, **kwargs) -> Self:
+        """Create a piped command for uv"""
+        if s:
+            return cls.sub(f"pip {s}", *args, **kwargs)
+        return cls.sub("pip", *args, **kwargs)
+
+
+class MaskShellCommand(BaseShellCommand):
+    """Mask command for running masked commands"""
+
+    command_name = "mask"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def maskfile(cls, maskfile, *args, **kwargs) -> Self:
+        """Create a maskfile command with the specified maskfile"""
+        return cls.sub("--maskfile", *args, **kwargs).value(maskfile)
+
+    @classmethod
+    def init(cls, *args, **kwargs) -> Self:
+        """Create an init command for mask"""
+        return cls.sub("init", *args, **kwargs)
+
+
+__all__ = [
+    "MaskShellCommand",
+    "OPShellCommand",
+    "UVShellCommand",
+]