bear-utils 0.0.1__py3-none-any.whl

bear_utils/ai/ai_helpers/_parsers.py

@@ -0,0 +1,194 @@
+from collections.abc import Callable
+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 bear_utils import BaseLogger, EpochTimestamp, SettingsManager, get_settings_manager
+
+from . import AIEndpointConfig
+from ._types import ResponseParser
+
+SUCCESSFUL_STATUS_CODE = 200
+
+
+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: dict[str, Any] = 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[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())
+
+    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[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={
+                "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]:
+        """Return the raw output from the response without parsing."""
+        output = raw_response.get("output", "")
+        return {"output": output, "logger": logger}
+
+    def get_default_response(self) -> dict[str, Any]:
+        return {"output": ""}
+
+
+class ModularAIEndpoint[T_Response](SingletonBase):
+    """Modular AI endpoint for flexible communication patterns."""
+
+    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
+        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) -> None:
+        """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 == SUCCESSFUL_STATUS_CODE:
+                    return await parser.parse(response.json(), self.logger)
+                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,15 @@
+from abc import ABC, abstractmethod
+
+from bear_utils.logger_manager import BaseLogger
+
+
+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."""
+
+    @abstractmethod
+    def get_default_response(self) -> T_Response:
+        """Return a default response structure."""

bear_utils/cache/__init__.py

@@ -0,0 +1,131 @@
+"""A set of helper caching utilities for bear_utils."""
+
+import functools
+from pathlib import Path
+from typing import Any
+
+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: 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.
+            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: Any, default: Any = None) -> Any:
+        """Get a value from the cache."""
+        return self.cache.get(key, default=default)
+
+    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: 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.
+        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
+    """
+    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(local_directory, size_limit=size_limit, **kwargs)
+
+    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)
+            expire (int, optional): Expiration time in seconds.
+            key (callable, optional): Custom key function.
+
+        Returns:
+            callable: Decorated function or decorator
+        """
+
+        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()))
+
+                result = cache_instance.get(cache_key, default=None)
+                if result is not None:
+                    return result
+
+                # If not in cache, compute and store
+                result: Any = 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", "cache_factory"]

bear_utils/cli/__init__.py

@@ -0,0 +1,22 @@
+"""A set of command-line interface (CLI) utilities for bear_utils."""
+
+from ._args import FAILURE, SUCCESS, ExitCode, args_process
+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",
+    "FAILURE",
+    "SUCCESS",
+    "BaseShellCommand",
+    "ExitCode",
+    "GitCommand",
+    "MaskShellCommand",
+    "OPShellCommand",
+    "SimpleShellSession",
+    "UVShellCommand",
+    "args_process",
+    "shell_session",
+]

bear_utils/cli/_args.py

@@ -0,0 +1,12 @@
+import sys
+
+from bear_utils.constants._exit_code import FAILURE, SUCCESS, ExitCode
+
+
+def args_process(args: list[str] | None = None) -> tuple[list[str], ExitCode]:
+    args = sys.argv[1:] if args is None else args
+
+    if not args:
+        return [], FAILURE
+
+    return args, SUCCESS

bear_utils/cli/_get_version.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from contextlib import redirect_stdout
+from importlib.metadata import PackageNotFoundError, version
+from io import StringIO
+import sys
+from typing import Literal, Self
+
+from pydantic import BaseModel
+
+from bear_utils.constants import ExitCode
+from bear_utils.constants._meta import IntValue as Value, RichIntEnum
+from bear_utils.extras import zap_as
+
+
+class VerParts(RichIntEnum):
+    """Enumeration for version parts."""
+
+    MAJOR = Value(0, "major")
+    MINOR = Value(1, "minor")
+    PATCH = Value(2, "patch")
+
+    @classmethod
+    def choices(cls) -> list[str]:
+        """Return a list of valid version parts."""
+        return [version_part.text for version_part in cls]
+
+    @classmethod
+    def parts(cls) -> int:
+        """Return the total number of version parts."""
+        return len(cls.choices())
+
+
+VALID_BUMP_TYPES: list[str] = VerParts.choices()
+ALL_PARTS: int = VerParts.parts()
+
+
+class Version(BaseModel):
+    """Model to represent a version string."""
+
+    major: int = 0
+    """Major version number."""
+    minor: int = 0
+    """Minor version number."""
+    patch: int = 0
+    """Patch version number."""
+
+    @classmethod
+    def from_string(cls, version_str: str) -> Self:
+        """Create a Version instance from a version string.
+
+        Args:
+            version_str: A version string in the format "major.minor.patch".
+
+        Returns:
+            A Version instance.
+
+        Raises:
+            ValueError: If the version string is not in the correct format.
+        """
+        try:
+            major, minor, patch = zap_as("-+", version_str, 3, replace=".", func=int)
+            return cls(major=int(major), minor=int(minor), patch=int(patch))
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid version string format: {version_str}. Expected integers for major, minor, and patch."
+            ) from e
+
+    def increment(self, attr_name: str) -> None:
+        """Increment the specified part of the version."""
+        setattr(self, attr_name, getattr(self, attr_name) + 1)
+
+    @property
+    def version_string(self) -> str:
+        """Return the version as a string in the format "major.minor.patch".
+
+        Returns:
+            A string representation of the version.
+        """
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+    def default(self, part: str) -> None:
+        """Clear the specified part of the version.
+
+        Args:
+            part: The part of the version to clear.
+        """
+        if hasattr(self, part):
+            setattr(self, part, 0)
+
+    def new_version(self, bump_type: str) -> Version:
+        """Return a new version string based on the bump type."""
+        bump_part: VerParts = VerParts.get(bump_type, default=VerParts.PATCH)
+        self.increment(bump_part.text)
+        for part in VerParts:
+            if part.value > bump_part.value:
+                self.default(part.text)
+        return self
+
+    @classmethod
+    def from_func(cls, package_name: str) -> Self:
+        """Create a Version instance from the current package version.
+
+        Returns:
+            A Version instance with the current package version.
+
+        Raises:
+            PackageNotFoundError: If the package is not found.
+        """
+        try:
+            current_version = version(package_name)
+            return cls.from_string(current_version)
+        except PackageNotFoundError as e:
+            raise PackageNotFoundError(f"Package '{package_name}' not found: {e}") from e
+
+
+def _bump_version(version: str, bump_type: Literal["major", "minor", "patch"]) -> Version:
+    """Bump the version based on the specified type.
+
+    Args:
+        version: The current version string (e.g., "1.2.3").
+        bump_type: The type of bump ("major", "minor", or "patch").
+
+    Returns:
+        The new version string.
+
+    Raises:
+        ValueError: If the version format is invalid or bump_type is unsupported.
+    """
+    ver: Version = Version.from_string(version)
+    return ver.new_version(bump_type)
+
+
+def _get_version(package_name: str) -> str:
+    """Get the version of the specified package.
+
+    Args:
+        package_name: The name of the package to get the version for.
+
+    Returns:
+        A Version instance representing the current version of the package.
+
+    Raises:
+        PackageNotFoundError: If the package is not found.
+    """
+    record = StringIO()
+    with redirect_stdout(record):
+        cli_get_version([package_name])
+    return record.getvalue().strip()
+
+
+def cli_get_version(args: list[str] | None = None) -> ExitCode:
+    """Get the version of the current package.
+
+    Returns:
+        The version of the package.
+    """
+    if args is None:
+        args = sys.argv[1:]
+    parser = ArgumentParser(description="Get the version of the package.")
+    parser.add_argument("package_name", nargs="?", type=str, help="Name of the package to get the version for.")
+    arguments: Namespace = parser.parse_args(args)
+    if not arguments.package_name:
+        print("No package name provided. Please specify a package name.")
+        return ExitCode.FAILURE
+    package_name: str = arguments.package_name
+    try:
+        current_version = version(package_name)
+        print(current_version)
+    except PackageNotFoundError:
+        print(f"Package '{package_name}' not found.")
+        return ExitCode.FAILURE
+    return ExitCode.SUCCESS
+
+
+def cli_bump(args: list[str] | None = None) -> ExitCode:
+    if args is None:
+        args = sys.argv[1:]
+    parser = ArgumentParser(description="Bump the version of the package.")
+    parser.add_argument("bump_type", type=str, choices=VALID_BUMP_TYPES, default="patch")
+    parser.add_argument("package_name", nargs="?", type=str, help="Name of the package to bump the version for.")
+    parser.add_argument("current_version", type=str, help="Current version of the package.")
+    arguments: Namespace = parser.parse_args(args)
+    bump_type: Literal["major", "minor", "patch"] = arguments.bump_type
+    if not arguments.package_name:
+        print("No package name provided.")
+        return ExitCode.FAILURE
+    package_name: str = arguments.package_name
+    if bump_type not in VALID_BUMP_TYPES:
+        print(f"Invalid argument '{bump_type}'. Use one of: {', '.join(VALID_BUMP_TYPES)}.")
+        return ExitCode.FAILURE
+    current_version: str = arguments.current_version or _get_version(package_name)
+    try:
+        new_version: Version = _bump_version(version=current_version, bump_type=bump_type)
+        print(new_version.version_string)
+        return ExitCode.SUCCESS
+    except ValueError as e:
+        print(f"Error: {e}")
+        return ExitCode.FAILURE
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return ExitCode.FAILURE
+
+
+if __name__ == "__main__":
+    cli_bump(["patch", "bear-utils", "0.9.2-fart.build-alpha"])

bear_utils/cli/commands.py

@@ -0,0 +1,105 @@
+"""Shell Commands Module for Bear Utils."""
+
+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) -> None:
+        """Initialize the OPShellCommand with the op command."""
+        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) -> None:
+        """Initialize the UVShellCommand with the uv command."""
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def pip(cls, s: str = "", *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) -> None:
+        """Initialize the MaskShellCommand with the mask command."""
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def maskfile(cls, maskfile: str, *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)
+
+
+class GitCommand(BaseShellCommand):
+    """Base class for Git commands"""
+
+    command_name = "git"
+
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize the GitCommand with the git command."""
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def init(cls, *args, **kwargs) -> "GitCommand":
+        """Initialize a new Git repository"""
+        return cls.sub("init", *args, **kwargs)
+
+    @classmethod
+    def status(cls, *args, **kwargs) -> "GitCommand":
+        """Get the status of the Git repository"""
+        return cls.sub("status", *args, **kwargs)
+
+    @classmethod
+    def log(cls, *args, **kwargs) -> "GitCommand":
+        """Show the commit logs"""
+        return cls.sub("log", *args, **kwargs)
+
+    @classmethod
+    def add(cls, files: str, *args, **kwargs) -> "GitCommand":
+        """Add files to the staging area"""
+        return cls.sub("add", *args, **kwargs).value(files)
+
+    @classmethod
+    def diff(cls, *args, **kwargs) -> "GitCommand":
+        """Show changes between commits, commit and working tree, etc."""
+        return cls.sub("diff", *args, **kwargs)
+
+    @classmethod
+    def commit(cls, message: str, *args, **kwargs) -> "GitCommand":
+        """Commit changes with a message"""
+        return cls.sub("commit -m", *args, **kwargs).value(f"'{message}'")
+
+
+__all__ = [
+    "GitCommand",
+    "MaskShellCommand",
+    "OPShellCommand",
+    "UVShellCommand",
+]