bear-utils 0.0.1__py3-none-any.whl

bear_utils/__init__.py

@@ -0,0 +1,51 @@
+"""A module for Bear Utils, providing various utilities and tools."""
+
+from bear_utils.cache import CacheWrapper, cache, cache_factory
+from bear_utils.config.settings_manager import SettingsManager, get_settings_manager
+from bear_utils.constants import DEVNULL, STDERR, STDOUT, ExitCode, HTTPStatusCode
+from bear_utils.database import DatabaseManager
+from bear_utils.events import Events
+from bear_utils.extras.responses import FunctionResponse
+from bear_utils.files.file_handlers.file_handler_factory import FileHandlerFactory
+from bear_utils.logger_manager import BaseLogger, BufferLogger, ConsoleLogger, FileLogger, LoggingClient, LoggingServer
+from bear_utils.logger_manager._common import VERBOSE_CONSOLE_FORMAT
+from bear_utils.logger_manager._styles import VERBOSE
+from bear_utils.time import (
+    DATE_FORMAT,
+    DATE_TIME_FORMAT,
+    EpochTimestamp,
+    TimeTools,
+    convert_to_milliseconds,
+    seconds_to_time,
+)
+
+__all__ = [
+    "DATE_FORMAT",
+    "DATE_TIME_FORMAT",
+    "DEVNULL",
+    "STDERR",
+    "STDOUT",
+    "VERBOSE",
+    "VERBOSE_CONSOLE_FORMAT",
+    "BaseLogger",
+    "BufferLogger",
+    "CacheWrapper",
+    "ConsoleLogger",
+    "DatabaseManager",
+    "EpochTimestamp",
+    "Events",
+    "ExitCode",
+    "FileHandlerFactory",
+    "FileLogger",
+    "FunctionResponse",
+    "HTTPStatusCode",
+    "LoggingClient",
+    "LoggingServer",
+    "SettingsManager",
+    "TimeTools",
+    "cache",
+    "cache_factory",
+    "convert_to_milliseconds",
+    "get_settings_manager",
+    "seconds_to_time",
+]

bear_utils/__main__.py

@@ -0,0 +1,14 @@
+"""Entry-point module, in case you use `python -m bear_utils`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from bear_utils._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

bear_utils/_internal/_version.py

@@ -0,0 +1 @@
+version = "0.0.1"

bear_utils/_internal/cli.py

@@ -0,0 +1,119 @@
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m bear_utils` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `bear_utils.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `bear_utils.__main__` in `sys.modules`.
+from __future__ import annotations
+
+from argparse import Action, ArgumentParser, Namespace
+import sys
+from typing import Any
+
+from bear_utils._internal import debug
+from bear_utils._internal._version import version as _version
+from bear_utils.cli._get_version import VALID_BUMP_TYPES, cli_bump
+from bear_utils.constants import STDERR, ExitCode
+
+
+class _DebugInfo(Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *_: Any, **__: Any) -> None:
+        debug._print_debug_info()
+        sys.exit(ExitCode.SUCCESS)
+
+
+class _About(Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *_: Any, **__: Any) -> None:
+        print(debug._get_package_info())
+        sys.exit(ExitCode.SUCCESS)
+
+
+class _Version(Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *_: Any, **__: Any) -> None:
+        version: str = f"{debug._get_name()} v{_version}"
+        print(version)
+        sys.exit(ExitCode.SUCCESS)
+
+
+def get_version() -> ExitCode:
+    """CLI command to get the version of the package."""
+    print(_version)
+    return ExitCode.SUCCESS
+
+
+def bump_version(args: list[str] | None = None) -> ExitCode:
+    """CLI command to bump the version of the package."""
+    parser = ArgumentParser(description="Bump the version of the package.")
+    parser.add_argument(
+        "bump_type",
+        type=str,
+        choices=VALID_BUMP_TYPES,
+        help=f"Type of version bump: {', '.join(VALID_BUMP_TYPES)}",
+    )
+    _args: Namespace = parser.parse_args(args or sys.argv[1:])
+    return cli_bump([_args.bump_type, debug.__PACKAGE_NAME__, _version])
+
+
+def get_parser() -> ArgumentParser:
+    name = debug._get_name()
+    parser = ArgumentParser(description=name.capitalize(), prog=name, exit_on_error=False)
+    parser.add_argument("-V", "--version", action=_Version, help="Print the version of the package")
+    subparser = parser.add_subparsers(dest="command", required=False, help="Available commands")
+    subparser.add_parser("get-version", help="Get the current version of the package")
+    bump = subparser.add_parser("bump-version", help="Bump the version of the package")
+    bump.add_argument("bump_type", type=str, choices=VALID_BUMP_TYPES, help="major, minor, or patch")
+    parser.add_argument("--about", action=_About, help="Print information about the package")
+    parser.add_argument("--debug_info", action=_DebugInfo, help="Print debug information")
+    return parser
+
+
+def main(args: list[str] | None = None) -> ExitCode:
+    """Main entry point for the CLI.
+
+    This function is called when the CLI is executed. It can be used to
+    initialize the CLI, parse arguments, and execute commands.
+
+    Args:
+        args (list[str] | None): A list of command-line arguments. If None, uses sys.argv[1:].
+
+    Returns:
+        int: Exit code of the CLI execution. 0 for success, non-zero for failure.
+    """
+    if args is None:
+        args = sys.argv[1:]
+    try:
+        parser: ArgumentParser = get_parser()
+        opts: Namespace = parser.parse_args(args)
+        command: str | None = opts.command
+        if command is None:
+            parser.print_help()
+            return ExitCode.SUCCESS
+        if command == "get-version":
+            return get_version()
+        if command == "bump-version":
+            if not hasattr(opts, "bump_type"):
+                print("Error: 'bump-version' command requires a 'bump_type' argument.", STDERR)
+                return ExitCode.FAILURE
+            bump_type: str = opts.bump_type
+            return bump_version([bump_type])
+    except Exception as e:
+        print(f"Error initializing CLI: {e}", STDERR)
+        return ExitCode.FAILURE
+    return ExitCode.SUCCESS
+
+
+if __name__ == "__main__":
+    main()

bear_utils/_internal/debug.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import importlib.metadata
+from importlib.metadata import PackageNotFoundError, metadata, version
+import os
+import platform
+import sys
+
+from bear_utils._internal._version import version as _version
+from bear_utils.cli._get_version import Version
+
+__PACKAGE_NAME__ = "bear-utils"
+
+
+@dataclass
+class _Package:
+    """Dataclass to store package information."""
+
+    name: str = __PACKAGE_NAME__
+    """Package name."""
+    version: str = _version
+    """Package version."""
+    _version: Version = field(default_factory=lambda: Version.from_string(_version))
+    description: str = "No description available."
+    """Package description."""
+
+    def __post_init__(self) -> None:
+        """Post-initialization to ensure version is a string."""
+        if not isinstance(self.version, str) or "0.0.0" in self.version:
+            self.version = version(self.name) if self.name else "0.0.0"
+        if not self.description:
+            try:
+                self.description = metadata(self.name)["Summary"]
+            except PackageNotFoundError:
+                self.description = "No description available."
+
+    def __str__(self) -> str:
+        """String representation of the package information."""
+        return f"{self.name} v{self.version}: {self.description}"
+
+
+@dataclass
+class _Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class _Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[_Package]
+    """Installed packages."""
+    variables: list[_Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def _get_package_info(dist: str = __PACKAGE_NAME__) -> _Package:
+    try:
+        return _Package(
+            name=dist,
+            version=_version or version(dist),
+            description=metadata(dist)["Summary"],
+        )
+    except PackageNotFoundError:
+        return _Package(name=dist)
+
+
+def _get_name(dist: str = __PACKAGE_NAME__) -> str:
+    """Get name of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A package name.
+    """
+    return _get_package_info(dist).name
+
+
+def _get_version(dist: str = __PACKAGE_NAME__) -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    return _get_package_info(dist).version
+
+
+def _get_description(dist: str = __PACKAGE_NAME__) -> str:
+    """Get description of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A description string.
+    """
+    return _get_package_info(dist).description
+
+
+def _get_debug_info() -> _Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages: list[str] = [__PACKAGE_NAME__]
+    variables: list[str] = [
+        "PYTHONPATH",
+        *[var for var in os.environ if var.startswith(__PACKAGE_NAME__.replace("-", "_"))],
+    ]
+    return _Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
+    )
+
+
+def get_installed_packages() -> list[_Package]:
+    """Get all installed packages in current environment"""
+    packages = []
+    for dist in importlib.metadata.distributions():
+        packages.append({"name": dist.metadata["Name"], "version": dist.version})
+    return packages
+
+
+def _print_debug_info() -> None:
+    """Print debug/environment information."""
+    info: _Environment = _get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    # _print_debug_info()
+    print(_get_package_info())

bear_utils/ai/__init__.py

@@ -0,0 +1,30 @@
+"""AI Helpers Module for Bear Utils."""
+
+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
+
+__all__ = [
+    "GPT_4_1",
+    "GPT_4_1_MINI",
+    "GPT_4_1_NANO",
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "AIEndpointConfig",
+    "AIModel",
+    "BaseResponseParser",
+    "CommandResponseParser",
+    "EnvironmentMode",
+    "PassthroughResponseParser",
+    "ResponseParser",
+    "TypedResponseParser",
+]

bear_utils/ai/ai_helpers/__init__.py

@@ -0,0 +1,136 @@
+"""This module provides helper functions to create AI endpoints with various response parsing strategies."""
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from rich.markdown import Markdown
+
+from bear_utils.logger_manager import BaseLogger
+
+from ._common import 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[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](
+    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]:
+    """Create an endpoint that returns a command response with Markdown formatting."""
+    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[T_Response] = TypedResponseParser(
+        default_response=default_response,
+        response_transformers={"response": lambda x: Markdown(str(x))},
+    )
+    return ModularAIEndpoint(config=config, logger=logger, response_parser=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=required_fields, response_transformers=transformers)
+    return ModularAIEndpoint(config=config, logger=logger, response_parser=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] = [
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "AIEndpointConfig",
+    "EnvironmentMode",
+    "ModularAIEndpoint",
+    "create_command_endpoint",
+    "create_flexible_endpoint",
+    "create_simple_endpoint",
+    "create_typed_endpoint",
+]

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