edsl 0.1.14__py3-none-any.whl → 0.1.40__py3-none-any.whl

edsl/base/Base.py

@@ -0,0 +1,279 @@
+"""Base class for all classes in the package. It provides rich printing and persistence of objects."""
+
+from abc import ABC, abstractmethod, ABCMeta
+import gzip
+import io
+import json
+from typing import Any, Optional, Union
+from uuid import UUID
+from IPython.display import display
+from rich.console import Console
+
+
+class RichPrintingMixin:
+    """Mixin for rich printing and persistence of objects."""
+
+    def _for_console(self):
+        """Return a string representation of the object for console printing."""
+        with io.StringIO() as buf:
+            console = Console(file=buf, record=True)
+            table = self.rich_print()
+            console.print(table)
+            return console.export_text()
+
+    def __str__(self):
+        """Return a string representation of the object for console printing."""
+        return self._for_console()
+
+    def print(self):
+        """Print the object to the console."""
+        from edsl.utilities.utilities import is_notebook
+
+        if is_notebook():
+            display(self.rich_print())
+        else:
+            from rich.console import Console
+
+            console = Console()
+            console.print(self.rich_print())
+
+
+class PersistenceMixin:
+    """Mixin for saving and loading objects to and from files."""
+
+    def push(
+        self,
+        description: Optional[str] = None,
+        visibility: Optional[str] = "unlisted",
+    ):
+        """Post the object to coop."""
+        from edsl.coop import Coop
+
+        c = Coop()
+        return c.create(self, description, visibility)
+
+    @classmethod
+    def pull(cls, id_or_url: Union[str, UUID], exec_profile=None):
+        """Pull the object from coop."""
+        from edsl.coop import Coop
+
+        if id_or_url.startswith("http"):
+            uuid_value = id_or_url.split("/")[-1]
+        else:
+            uuid_value = id_or_url
+
+        c = Coop()
+
+        return c._get_base(cls, uuid_value, exec_profile=exec_profile)
+
+    @classmethod
+    def delete(cls, id_or_url: Union[str, UUID]):
+        """Delete the object from coop."""
+        from edsl.coop import Coop
+
+        c = Coop()
+        return c._delete_base(cls, id_or_url)
+
+    @classmethod
+    def patch(
+        cls,
+        id_or_url: Union[str, UUID],
+        description: Optional[str] = None,
+        value: Optional[Any] = None,
+        visibility: Optional[str] = None,
+    ):
+        """
+        Patch an uploaded objects attributes.
+        - `description` changes the description of the object on Coop
+        - `value` changes the value of the object on Coop. **has to be an EDSL object**
+        - `visibility` changes the visibility of the object on Coop
+        """
+        from edsl.coop import Coop
+
+        c = Coop()
+        return c._patch_base(cls, id_or_url, description, value, visibility)
+
+    @classmethod
+    def search(cls, query):
+        """Search for objects on coop."""
+        from edsl.coop import Coop
+
+        c = Coop()
+        return c.search(cls, query)
+
+    def save(self, filename, compress=True):
+        """Save the object to a file as zippped JSON.
+
+        >>> obj.save("obj.json.gz")
+
+        """
+        if filename.endswith("json.gz"):
+            import warnings
+
+            warnings.warn(
+                "Do not apply the file extensions. The filename should not end with 'json.gz'."
+            )
+            filename = filename[:-7]
+        if filename.endswith("json"):
+            filename = filename[:-4]
+            warnings.warn(
+                "Do not apply the file extensions. The filename should not end with 'json'."
+            )
+
+        if compress:
+            with gzip.open(filename + ".json.gz", "wb") as f:
+                f.write(json.dumps(self.to_dict()).encode("utf-8"))
+        else:
+            with open(filename + ".json", "w") as f:
+                f.write(json.dumps(self.to_dict()))
+
+    @staticmethod
+    def open_compressed_file(filename):
+        with gzip.open(filename, "rb") as f:
+            file_contents = f.read()
+            file_contents_decoded = file_contents.decode("utf-8")
+            d = json.loads(file_contents_decoded)
+        return d
+
+    @staticmethod
+    def open_regular_file(filename):
+        with open(filename, "r") as f:
+            d = json.loads(f.read())
+        return d
+
+    @classmethod
+    def load(cls, filename):
+        """Load the object from a file.
+
+        >>> obj = cls.load("obj.json.gz")
+
+        """
+
+        if filename.endswith("json.gz"):
+            d = cls.open_compressed_file(filename)
+        elif filename.endswith("json"):
+            d = cls.open_regular_file(filename)
+        else:
+            try:
+                d = cls.open_compressed_file(filename)
+            except:
+                d = cls.open_regular_file(filename)
+            finally:
+                raise ValueError("File must be a json or json.gz file")
+
+        return cls.from_dict(d)
+
+
+class RegisterSubclassesMeta(ABCMeta):
+    """Metaclass for registering subclasses."""
+
+    _registry = {}
+
+    def __init__(cls, name, bases, nmspc):
+        """Register the class in the registry upon creation."""
+        super(RegisterSubclassesMeta, cls).__init__(name, bases, nmspc)
+        if cls.__name__ != "Base":
+            RegisterSubclassesMeta._registry[cls.__name__] = cls
+
+    @staticmethod
+    def get_registry():
+        """Return the registry of subclasses."""
+        return dict(RegisterSubclassesMeta._registry)
+
+
+class DiffMethodsMixin:
+    def __sub__(self, other):
+        """Return the difference between two objects."""
+        from edsl.BaseDiff import BaseDiff
+
+        return BaseDiff(self, other)
+
+
+class Base(
+    RichPrintingMixin,
+    PersistenceMixin,
+    DiffMethodsMixin,
+    ABC,
+    metaclass=RegisterSubclassesMeta,
+):
+    """Base class for all classes in the package."""
+
+    # def __getitem__(self, key):
+    #     return getattr(self, key)
+
+    # @abstractmethod
+    # def _repr_html_(self) -> str:
+    #     raise NotImplementedError("This method is not implemented yet.")
+
+    # @abstractmethod
+    # def _repr_(self) -> str:
+    #     raise NotImplementedError("This method is not implemented yet.")
+
+    def keys(self):
+        """Return the keys of the object."""
+        _keys = list(self.to_dict().keys())
+        if "edsl_version" in _keys:
+            _keys.remove("edsl_version")
+        if "edsl_class_name" in _keys:
+            _keys.remove("edsl_class_name")
+        return _keys
+
+    def values(self):
+        """Return the values of the object."""
+        data = self.to_dict()
+        keys = self.keys()
+        return {data[key] for key in keys}
+
+    def _repr_html_(self):
+        from edsl.utilities.utilities import data_to_html
+
+        return data_to_html(self.to_dict())
+
+    def __eq__(self, other):
+        """Return whether two objects are equal."""
+        import inspect
+
+        if not isinstance(other, self.__class__):
+            return False
+        if "sort" in inspect.signature(self.to_dict).parameters:
+            return self.to_dict(sort=True) == other.to_dict(sort=True)
+        else:
+            return self.to_dict() == other.to_dict()
+
+    @abstractmethod
+    def example():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def rich_print():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def to_dict():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def from_dict():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def code():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    def show_methods(self, show_docstrings=True):
+        """Show the methods of the object."""
+        public_methods_with_docstrings = [
+            (method, getattr(self, method).__doc__)
+            for method in dir(self)
+            if callable(getattr(self, method)) and not method.startswith("_")
+        ]
+        if show_docstrings:
+            for method, documentation in public_methods_with_docstrings:
+                print(f"{method}: {documentation}")
+        else:
+            return [x[0] for x in public_methods_with_docstrings]

edsl/config.py

@@ -1,154 +1,171 @@
+"""This module provides a Config class that loads environment variables from a .env file and sets them as class attributes."""
+
 import os
-import sys
+import platformdirs
 from dotenv import load_dotenv, find_dotenv
-from getpass import getpass
-from typing import Any
-from edsl.exceptions import (
+from edsl.exceptions.configuration import (
     InvalidEnvironmentVariableError,
     MissingEnvironmentVariableError,
 )
 
+cache_dir = platformdirs.user_cache_dir("edsl")
+os.makedirs(cache_dir, exist_ok=True)
+
+# valid values for EDSL_RUN_MODE
+EDSL_RUN_MODES = [
+    "development",
+    "development-testrun",
+    "production",
+]
+
+# `default` is used to impute values only in "production" mode
+# `info` gives a brief description of the env var
 CONFIG_MAP = {
     "EDSL_RUN_MODE": {
         "default": "production",
-        "allowed": ["development", "production"],
-        "user_message": None,
+        "info": "This config var determines the run mode of the application.",
+    },
+    "EDSL_API_TIMEOUT": {
+        "default": "60",
+        "info": "This config var determines the maximum number of seconds to wait for an API call to return.",
     },
-    "EDSL_PASTEBIN_URL": {
-        "default": "http://127.0.0.1:5000",
-        "allowed": None,
-        "user_message": None,
+    "EDSL_BACKOFF_START_SEC": {
+        "default": "1",
+        "info": "This config var determines the number of seconds to wait before retrying a failed API call.",
+    },
+    "EDSL_BACKOFF_MAX_SEC": {
+        "default": "60",
+        "info": "This config var determines the maximum number of seconds to wait before retrying a failed API call.",
     },
     "EDSL_DATABASE_PATH": {
-        "default": f"sqlite:///{os.path.join(os.getcwd(), 'edsl_cache.db')}",
-        "allowed": None,
-        "user_message": None,
+        # "default": f"sqlite:///{os.path.join(os.getcwd(), '.edsl_cache/data.db')}",
+        "default": f"sqlite:///{os.path.join(platformdirs.user_cache_dir('edsl'), 'lm_model_calls.db')}",
+        "info": "This config var determines the path to the cache file.",
     },
-    "EDSL_LOGGING_PATH": {
-        "default": f"interview.log",
-        "allowed": None,
-        "user_message": None,
+    "EDSL_DEFAULT_MODEL": {
+        "default": "gpt-4o",
+        "info": "This config var holds the default model that will be used if a model is not explicitly passed.",
     },
-    "API_CALL_TIMEOUT_SEC": {
-        "default": "60",
-        "allowed": None,
-        "user_message": "What is the maximum number of seconds to wait for an API call to return?",
+    "EDSL_FETCH_TOKEN_PRICES": {
+        "default": "True",
+        "info": "This config var determines whether to fetch prices for tokens used in remote inference",
+    },
+    "EDSL_MAX_ATTEMPTS": {
+        "default": "5",
+        "info": "This config var determines the maximum number of times to retry a failed API call.",
     },
-    "EMERITUS_API_KEY": {
-        "default": "local",
-        "allowed": None,
-        "user_message": "Please provide your Emeritus API key (https://emeritus.org/).",
+    "EDSL_SERVICE_RPM_BASELINE": {
+        "default": "100",
+        "info": "This config var holds the maximum number of requests per minute. Model-specific values provided in env vars such as EDSL_SERVICE_RPM_OPENAI will override this. value for the corresponding model",
     },
-    "OPENAI_API_KEY": {
-        "default": None,
-        "allowed": None,
-        "user_message": "Please provide your OpenAI API key (https://platform.openai.com/api-keys).",
+    "EDSL_SERVICE_TPM_BASELINE": {
+        "default": "2000000",
+        "info": "This config var holds the maximum number of tokens per minute for all models. Model-specific values provided in env vars such as EDSL_SERVICE_TPM_OPENAI will override this value for the corresponding model.",
     },
-    "DEEP_INFRA_API_KEY": {
-        "default": None,
-        "allowed": None,
-        "user_message": "Please provide your DeepInfra API key (https://deepinfra.com/).",
+    "EXPECTED_PARROT_URL": {
+        "default": "https://www.expectedparrot.com",
+        "info": "This config var holds the URL of the Expected Parrot API.",
     },
-    "GOOGLE_API_KEY": {
-        "default": None,
-        "allowed": None,
-        "user_message": "Please provide your Google API key (https://console.cloud.google.com/apis/credentials).",
+    "EDSL_MAX_CONCURRENT_TASKS": {
+        "default": "500",
+        "info": "This config var determines the maximum number of concurrent tasks that can be run by the async job-runner",
+    },
+    "EDSL_OPEN_EXCEPTION_REPORT_URL": {
+        "default": "False",
+        "info": "This config var determines whether to open the exception report URL in the browser",
+    },
+    "EDSL_REMOTE_TOKEN_BUCKET_URL": {
+        "default": "None",
+        "info": "This config var holds the URL of the remote token bucket server.",
     },
 }
 
 
 class Config:
+    """A class that loads environment variables from a .env file and sets them as class attributes."""
+
     def __init__(self):
+        """Initialize the Config class."""
+        self._set_run_mode()
         self._load_dotenv()
         self._set_env_vars()
-        self._validate_attributes()
+
+    def show_path_to_dot_env(self):
+        print(find_dotenv(usecwd=True))
+
+    def _set_run_mode(self) -> None:
+        """
+        Sets EDSL_RUN_MODE as a class attribute.
+        """
+        run_mode = os.getenv("EDSL_RUN_MODE")
+        default = CONFIG_MAP.get("EDSL_RUN_MODE").get("default")
+        if run_mode is None:
+            run_mode = default
+        if run_mode not in EDSL_RUN_MODES:
+            raise InvalidEnvironmentVariableError(
+                f"Value `{run_mode}` is not allowed for EDSL_RUN_MODE."
+            )
+        self.EDSL_RUN_MODE = run_mode
 
     def _load_dotenv(self) -> None:
         """
-        Loads environment variables from the .env file.
-        Overrides existing env vars, unless the env var EDSL_TESTING="True".
+        Loads the .env
+        - The .env will override existing env vars **unless** EDSL_RUN_MODE=="development-testrun"
         """
-        override = True
-        if os.getenv("EDSL_TESTING") == "True":
+
+        if self.EDSL_RUN_MODE == "development-testrun":
             override = False
+        else:
+            override = True
         _ = load_dotenv(dotenv_path=find_dotenv(usecwd=True), override=override)
 
+    def __contains__(self, env_var: str) -> bool:
+        """
+        Checks if an env var is set as a class attribute.
+        """
+        return env_var in self.__dict__
+
     def _set_env_vars(self) -> None:
-        """Sets env vars as Config class attributes. If an env var is not set and has a default value in the CONFIG_MAP, sets it to the default value."""
+        """
+        Sets env vars as class attributes.
+        - EDSL_RUN_MODE is not set my this method, but by _set_run_mode
+        - If an env var is not set and has a default value in the CONFIG_MAP, sets it to the default value.
+        """
+        # for each env var in the CONFIG_MAP
         for env_var, config in CONFIG_MAP.items():
-            # if the env var is set, set it as a CONFIG attribute as well
-            if value := os.getenv(env_var):
+            # EDSL_RUN_MODE is already set by _set_run_mode
+            if env_var == "EDSL_RUN_MODE":
+                continue
+            value = os.getenv(env_var)
+            default_value = config.get("default")
+            # if an env var exists, set it as a class attribute
+            if value:
                 setattr(self, env_var, value)
-            # if the env var is not set and has a default value, set it as an CONFIG attribute and as an env var
-            elif default_value := config.get("default"):
+            # otherwise, if EDSL_RUN_MODE == "production" set it to its default value
+            elif self.EDSL_RUN_MODE == "production":
                 setattr(self, env_var, default_value)
-                os.environ[env_var] = default_value
-
-    def _set_env_var(self, env_var: str, config: dict[str, Any]) -> None:
-        """Attempts to set an environment variable."""
-        if self.EDSL_RUN_MODE == "development":
-            raise MissingEnvironmentVariableError(f"Missing env var {env_var}.")
-        else:
-            print("=" * 50)
-            print(config.get("user_message"))
-            print(f"If you would like to skip this step, press enter.")
-            print(f"If you would like to provide your key, do one of the following:")
-            print(f"1. Set it as a regular environment variable")
-            print(f"2. Create a .env file and add `{env_var}=...` to it")
-            print(f"3. Enter the value below and press enter: ")
-            # if the script is running in a terminal
-            if sys.stdout.isatty():
-                # try to use get_pass to mask the input
-                try:
-                    value = getpass()
-                # if you fail, use input instead
-                except Exception as e:
-                    value = input()
-            # otherwise use input
-            else:
-                value = input()
-            value = value.strip()
-            setattr(self, env_var, value)
-            os.environ[env_var] = value
-            if value:
-                if len(value) <= 4:
-                    masked_value = value
-                else:
-                    masked_value = value[:2] + "*" * (len(value) - 4) + value[-2:]
-                print(
-                    f"Environment variable {env_var} set successfully to {masked_value}."
-                )
-            else:
-                print(f"Skipping setting environment variable {env_var}.")
-            print("=" * 50)
-            print("\n")
-
-    def _validate_attributes(self):
-        """Validates that all attributes are allowed values."""
-        for attr, value in self.__dict__.items():
-            config = CONFIG_MAP.get(attr)
-            if config.get("allowed") and value not in config.get("allowed"):
-                raise InvalidEnvironmentVariableError(
-                    f"Variable {attr} has value {value}, which is not allowed.\n"
-                    f"Allowed values are: {config.get('allowed')}. "
-                )
 
     def get(self, env_var: str) -> str:
         """
         Returns the value of an environment variable.
-        - If the environment variable is valid but not set, attempts to set it.
         """
         if env_var not in CONFIG_MAP:
-            raise InvalidEnvironmentVariableError(
-                f"Variable {env_var} is not a valid environment variable. "
-                f"Valid environment variables are: {set(CONFIG_MAP.keys())}."
-            )
+            raise InvalidEnvironmentVariableError(f"{env_var} is not a valid env var. ")
         elif env_var not in self.__dict__:
-            self._set_env_var(env_var, CONFIG_MAP.get(env_var))
+            info = CONFIG_MAP[env_var].get("info")
+            raise MissingEnvironmentVariableError(f"{env_var} is not set. {info}")
         return self.__dict__.get(env_var)
 
+    def __iter__(self):
+        """Iterate over the environment variables."""
+        return iter(self.__dict__)
+
+    def items(self):
+        """Iterate over the environment variables and their values."""
+        return self.__dict__.items()
+
     def show(self) -> str:
-        """Prints the currently set environment vars."""
+        """Print the currently set environment vars."""
         max_env_var_length = max(len(env_var) for env_var in self.__dict__)
         print("Here are the current configuration settings:")
         for env_var, value in self.__dict__.items():