edsl 0.1.49__py3-none-any.whl → 0.1.51__py3-none-any.whl

edsl/config/config_class.py

@@ -3,10 +3,18 @@
 import os
 import platformdirs
 from dotenv import load_dotenv, find_dotenv
-from edsl.exceptions.configuration import (
-    InvalidEnvironmentVariableError,
-    MissingEnvironmentVariableError,
-)
+from ..base import BaseException
+import logging
+
+logger = logging.getLogger(__name__)
+
+class InvalidEnvironmentVariableError(BaseException):
+    """Raised when an environment variable is invalid."""
+    pass
+
+class MissingEnvironmentVariableError(BaseException):
+    """Raised when an expected environment variable is missing."""
+    pass
 
 cache_dir = platformdirs.user_cache_dir("edsl")
 os.makedirs(cache_dir, exist_ok=True)
@@ -50,6 +58,10 @@ CONFIG_MAP = {
         "default": "True",
         "info": "This config var determines whether to fetch prices for tokens used in remote inference",
     },
+    "EDSL_LOG_LEVEL": {
+        "default": "ERROR",
+        "info": "This config var determines the logging level for the EDSL package (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+    },
     "EDSL_MAX_ATTEMPTS": {
         "default": "5",
         "info": "This config var determines the maximum number of times to retry a failed API call.",
@@ -86,9 +98,11 @@ class Config:
 
     def __init__(self):
         """Initialize the Config class."""
+        logger.debug("Initializing Config class")
         self._set_run_mode()
         self._load_dotenv()
         self._set_env_vars()
+        logger.info(f"Config initialized with run mode: {self.EDSL_RUN_MODE}")
 
     def show_path_to_dot_env(self):
         print(find_dotenv(usecwd=True))
@@ -101,7 +115,12 @@ class Config:
         default = CONFIG_MAP.get("EDSL_RUN_MODE").get("default")
         if run_mode is None:
             run_mode = default
+            logger.debug(f"EDSL_RUN_MODE not set, using default: {default}")
+        else:
+            logger.debug(f"EDSL_RUN_MODE set to: {run_mode}")
+
         if run_mode not in EDSL_RUN_MODES:
+            logger.error(f"Invalid EDSL_RUN_MODE: {run_mode}")
             raise InvalidEnvironmentVariableError(
                 f"Value `{run_mode}` is not allowed for EDSL_RUN_MODE."
             )
@@ -149,12 +168,19 @@ class Config:
         """
         Returns the value of an environment variable.
         """
+        logger.debug(f"Getting config value for: {env_var}")
+
         if env_var not in CONFIG_MAP:
+            logger.error(f"Invalid environment variable requested: {env_var}")
             raise InvalidEnvironmentVariableError(f"{env_var} is not a valid env var. ")
         elif env_var not in self.__dict__:
             info = CONFIG_MAP[env_var].get("info")
+            logger.error(f"Missing environment variable: {env_var}")
             raise MissingEnvironmentVariableError(f"{env_var} is not set. {info}")
-        return self.__dict__.get(env_var)
+
+        value = self.__dict__.get(env_var)
+        logger.debug(f"Config value for {env_var}: {value}")
+        return value
 
     def __iter__(self):
         """Iterate over the environment variables."""
@@ -174,4 +200,4 @@ class Config:
 
 # Note: Python modules are singletons. As such, once this module is imported
 # the same instance of it is reused across the application.
-CONFIG = Config()
+CONFIG = Config()

edsl/conversation/Conversation.py

@@ -1,13 +1,16 @@
 from collections import UserList
 import asyncio
 import inspect
-from typing import Optional, Callable
-from .. import Agent, QuestionFreeText, Results, AgentList, ScenarioList, Scenario
+from typing import Optional, Callable, TYPE_CHECKING
+from .. import QuestionFreeText, Results, AgentList, ScenarioList, Scenario, Model
 from ..questions import QuestionBase
 from ..results.Result import Result
 from jinja2 import Template
 from ..caching import Cache
 
+if TYPE_CHECKING:
+    from ..language_models.model import Model
+
 from .next_speaker_utilities import (
     default_turn_taking_generator,
     speaker_closure,
@@ -71,7 +74,7 @@ class Conversation:
         conversation_index: Optional[int] = None,
         cache=None,
         disable_remote_inference=False,
-        default_model: Optional["LanguageModel"] = None,
+        default_model: Optional[Model] = None,
     ):
         self.disable_remote_inference = disable_remote_inference
         self.per_round_message_template = per_round_message_template
@@ -120,7 +123,8 @@ What do you say next?"""
                 per_round_message_template
                 and "{{ round_message }}" not in next_statement_question.question_text
             ):
-                raise ValueError(
+                from .exceptions import ConversationValueError
+                raise ConversationValueError(
                     "If you pass in a per_round_message_template, you must include {{ round_message }} in the question_text."
                 )
 

edsl/conversation/car_buying.py

@@ -1,5 +1,4 @@
-from .. import Agent, AgentList, QuestionFreeText
-from .. import Cache
+from .. import Agent, AgentList, QuestionFreeText, Cache, QuestionList
 from .Conversation import Conversation, ConversationList
 
 a1 = Agent(
@@ -46,7 +45,6 @@ q = QuestionFreeText(
     question_name="car_brand",
 )
 
-from .. import QuestionList
 
 q_actors = QuestionList(
     question_text="""This was a conversation about buying a car: {{ transcript }}. 

edsl/conversation/exceptions.py

@@ -0,0 +1,58 @@
+"""
+Exceptions for the conversation module.
+
+This module defines custom exceptions for the conversation module,
+including errors for invalid participant configurations, agent interaction
+failures, and conversation state errors.
+"""
+
+from ..base import BaseException
+
+
+class ConversationError(BaseException):
+    """
+    Base exception class for all conversation-related errors.
+    
+    This is the parent class for all exceptions related to conversation
+    operations, including agent communication, turn management, and
+    participant configuration.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class ConversationValueError(ConversationError):
+    """
+    Exception raised when an invalid value is provided to a conversation.
+    
+    This exception occurs when attempting to create or modify a conversation
+    with invalid values, such as:
+    - Invalid participant configurations
+    - Inappropriate agent parameters
+    - Incompatible conversation settings
+    
+    Examples:
+        ```python
+        # Attempting to add an invalid participant to a conversation
+        conversation.add_participant(None)  # Raises ConversationValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+    
+
+class ConversationStateError(ConversationError):
+    """
+    Exception raised when the conversation is in an invalid state.
+    
+    This exception occurs when attempting to perform an operation that
+    is incompatible with the current state of the conversation, such as:
+    - Ending a conversation that hasn't started
+    - Starting a conversation that's already in progress
+    - Accessing a participant that doesn't exist
+    
+    Examples:
+        ```python
+        # Attempting to get the next speaker when the conversation is empty
+        empty_conversation.next_speaker()  # Raises ConversationStateError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"

edsl/conversation/mug_negotiation.py

@@ -1,5 +1,5 @@
-from edsl import Agent, AgentList
-from edsl.conversation.Conversation import Conversation, ConversationList
+from .. import Agent, AgentList, QuestionYesNo, QuestionNumerical
+from .Conversation import Conversation, ConversationList
 
 
 def bargaining_pairs(alice_valuation, bob_valuation):
@@ -43,12 +43,6 @@ results.select("conversation_index", "index", "agent_name", "dialogue").print(
     format="rich"
 )
 
-from edsl import (
-    QuestionFreeText,
-    QuestionMultipleChoice,
-    QuestionYesNo,
-    QuestionNumerical,
-)
 
 q_deal = QuestionYesNo(
     question_text="""This was a negotiation: {{ transcript }}. 

edsl/coop/__init__.py

@@ -8,18 +8,40 @@ This module enables EDSL to interact with cloud-based resources for enhanced fun
 3. Caching of interview results for improved performance and cost savings
 4. API key management and authentication
 5. Price and model availability information
+6. Plugin registry and discovery
 
 The primary interface is the Coop class, which serves as a client for the
 Expected Parrot API. Most users will only need to interact with the Coop class directly.
 
-Example:
-    >>> from edsl.coop import Coop
-    >>> coop = Coop()  # Uses API key from environment or stored location
-    >>> survey = my_survey.push()  # Uploads survey to Expected Parrot
-    >>> job_info = coop.remote_inference_create(my_job)  # Creates remote job
+Examples:
+    
+    ```python
+    from edsl.coop import Coop
+    coop = Coop()  # Uses API key from environment or stored location
+    survey = my_survey.push()  # Uploads survey to Expected Parrot
+    job_info = coop.remote_inference_create(my_job)  # Creates remote job
+    
+    # Working with plugins
+    from edsl.coop import get_available_plugins
+    plugins = get_available_plugins()
+    plugin_names = [p.name for p in plugins]
+    ```
 """
 
 from .utils import EDSLObject, ObjectType, VisibilityType, ObjectRegistry
 from .coop import Coop
 from .exceptions import CoopServerResponseError
-__all__ = ["Coop"]
+
+__all__ = [
+    "Coop", 
+    "EDSLObject", 
+    "ObjectType", 
+    "VisibilityType", 
+    "ObjectRegistry", 
+    "CoopServerResponseError",
+    "AvailablePlugin", 
+    "get_available_plugins", 
+    "search_plugins", 
+    "get_plugin_details",
+    "PluginRegistryError"
+]

edsl/coop/coop.py

@@ -1,4 +1,5 @@
 import aiohttp
+import base64
 import json
 import requests
 
@@ -140,7 +141,7 @@ class Coop(CoopFunctionsMixin):
         if self.api_key:
             headers["Authorization"] = f"Bearer {self.api_key}"
         else:
-            headers["Authorization"] = f"Bearer None"
+            headers["Authorization"] = "Bearer None"
         return headers
 
     def _send_server_request(
@@ -149,7 +150,7 @@ class Coop(CoopFunctionsMixin):
         method: str,
         payload: Optional[dict[str, Any]] = None,
         params: Optional[dict[str, Any]] = None,
-        timeout: Optional[float] = 5,
+        timeout: Optional[float] = 10,
     ) -> requests.Response:
         """
         Send a request to the server and return the response.
@@ -159,7 +160,7 @@ class Coop(CoopFunctionsMixin):
         if payload is None:
             timeout = 40
         elif (
-            method.upper() == "POST"
+            (method.upper() == "POST" or method.upper() == "PATCH")
             and "json_string" in payload
             and payload.get("json_string") is not None
         ):
@@ -179,7 +180,9 @@ class Coop(CoopFunctionsMixin):
                     timeout=timeout,
                 )
             else:
-                raise Exception(f"Invalid {method=}.")
+                from .exceptions import CoopInvalidMethodError
+
+                raise CoopInvalidMethodError(f"Invalid {method=}.")
         except requests.ConnectionError:
             raise requests.ConnectionError(f"Could not connect to the server at {url}.")
 
@@ -226,7 +229,8 @@ class Coop(CoopFunctionsMixin):
         """
         # Get EDSL version from header
         # breakpoint()
-        server_edsl_version = response.headers.get("X-EDSL-Version")
+        # Commented out as currently unused
+        # server_edsl_version = response.headers.get("X-EDSL-Version")
 
         # if server_edsl_version:
         #     if self._user_version_is_outdated(
@@ -266,7 +270,7 @@ class Coop(CoopFunctionsMixin):
 
                 print("\n✨ API key retrieved.")
 
-                if stored_in_user_space := self.ep_key_handler.ask_to_store(api_key):
+                if self.ep_key_handler.ask_to_store(api_key):
                     pass
                 else:
                     path_to_env = write_api_key_to_env(api_key)
@@ -299,13 +303,19 @@ class Coop(CoopFunctionsMixin):
                 message = root.find("Message").text
                 details = root.find("Details").text
             except Exception:
-                raise Exception(
-                    f"Server returned status code {response.status_code}",
-                    "XML response could not be decoded.",
-                    "The server response was: " + response.text,
+                from .exceptions import CoopServerResponseError
+
+                raise CoopServerResponseError(
+                    f"Server returned status code {response.status_code}. "
+                    f"XML response could not be decoded. "
+                    f"The server response was: {response.text}"
                 )
 
-            raise Exception(f"An error occurred: {code} - {message} - {details}")
+            from .exceptions import CoopServerResponseError
+
+            raise CoopServerResponseError(
+                f"An error occurred: {code} - {message} - {details}"
+            )
 
     def _poll_for_api_key(
         self, edsl_auth_token: str, timeout: int = 120
@@ -432,6 +442,23 @@ class Coop(CoopFunctionsMixin):
         else:
             return None
 
+    def _scenario_is_file_store(self, scenario_dict: dict) -> bool:
+        """
+        Check if the scenario object is a valid FileStore.
+
+        Matches keys in the scenario dict against the expected keys for a FileStore.
+        """
+        file_store_keys = [
+            "path",
+            "base64_string",
+            "binary",
+            "suffix",
+            "mime_type",
+            "external_locations",
+            "extracted_text",
+        ]
+        return all(key in scenario_dict.keys() for key in file_store_keys)
+
     def create(
         self,
         object: EDSLObject,
@@ -471,21 +498,30 @@ class Coop(CoopFunctionsMixin):
             >>> print(result["url"])  # URL to access the survey
         """
         object_type = ObjectRegistry.get_object_type_by_edsl_class(object)
+        object_dict = object.to_dict()
+        if object_type == "scenario" and self._scenario_is_file_store(object_dict):
+            file_store_metadata = {
+                "suffix": object_dict["suffix"],
+                "mime_type": object_dict["mime_type"],
+            }
+        else:
+            file_store_metadata = None
         response = self._send_server_request(
-            uri=f"api/v0/object",
+            uri="api/v0/object",
             method="POST",
             payload={
                 "description": description,
                 "alias": alias,
                 "json_string": (
                     json.dumps(
-                        object.to_dict(),
+                        object_dict,
                         default=self._json_handle_none,
                     )
                     if object_type != "scenario"
                     else ""
                 ),
                 "object_type": object_type,
+                "file_store_metadata": file_store_metadata,
                 "visibility": visibility,
                 "version": self._edsl_version,
             },
@@ -495,19 +531,57 @@ class Coop(CoopFunctionsMixin):
 
         if object_type == "scenario":
             json_data = json.dumps(
-                object.to_dict(),
+                object_dict,
                 default=self._json_handle_none,
             )
             headers = {"Content-Type": "application/json"}
             if response_json.get("upload_signed_url"):
                 signed_url = response_json.get("upload_signed_url")
             else:
-                raise Exception("No signed url provided received")
+                from .exceptions import CoopResponseError
+
+                raise CoopResponseError("No signed url was provided received")
 
             response = requests.put(
                 signed_url, data=json_data.encode(), headers=headers
             )
             self._resolve_gcs_response(response)
+
+            file_store_upload_signed_url = response_json.get(
+                "file_store_upload_signed_url"
+            )
+            if file_store_metadata and not file_store_upload_signed_url:
+                from .exceptions import CoopResponseError
+
+                raise CoopResponseError("No file store signed url provided.")
+            elif file_store_metadata:
+                headers = {"Content-Type": file_store_metadata["mime_type"]}
+                # Lint json files prior to upload
+                if file_store_metadata["suffix"] == "json":
+                    file_store_bytes = base64.b64decode(object_dict["base64_string"])
+                    pretty_json_string = json.dumps(
+                        json.loads(file_store_bytes), indent=4
+                    )
+                    byte_data = pretty_json_string.encode("utf-8")
+                # Lint python files prior to upload
+                elif file_store_metadata["suffix"] == "py":
+                    import black
+
+                    file_store_bytes = base64.b64decode(object_dict["base64_string"])
+                    python_string = file_store_bytes.decode("utf-8")
+                    formatted_python_string = black.format_str(
+                        python_string, mode=black.Mode()
+                    )
+                    byte_data = formatted_python_string.encode("utf-8")
+                else:
+                    byte_data = base64.b64decode(object_dict["base64_string"])
+                response = requests.put(
+                    file_store_upload_signed_url,
+                    data=byte_data,
+                    headers=headers,
+                )
+                self._resolve_gcs_response(response)
+
         owner_username = response_json.get("owner_username")
         object_alias = response_json.get("alias")
 
@@ -519,7 +593,6 @@ class Coop(CoopFunctionsMixin):
             "uuid": response_json.get("uuid"),
             "version": self._edsl_version,
             "visibility": response_json.get("visibility"),
-            "upload_signed_url": response_json.get("upload_signed_url", None),
         }
 
     def get(
@@ -566,13 +639,13 @@ class Coop(CoopFunctionsMixin):
 
         if obj_uuid:
             response = self._send_server_request(
-                uri=f"api/v0/object",
+                uri="api/v0/object",
                 method="GET",
                 params={"uuid": obj_uuid},
             )
         else:
             response = self._send_server_request(
-                uri=f"api/v0/object/alias",
+                uri="api/v0/object/alias",
                 method="GET",
                 params={"owner_username": owner_username, "alias": alias},
             )
@@ -586,7 +659,11 @@ class Coop(CoopFunctionsMixin):
             json_string = object_data.text
         object_type = response.json().get("object_type")
         if expected_object_type and object_type != expected_object_type:
-            raise Exception(f"Expected {expected_object_type=} but got {object_type=}")
+            from .exceptions import CoopObjectTypeError
+
+            raise CoopObjectTypeError(
+                f"Expected {expected_object_type=} but got {object_type=}"
+            )
         edsl_class = ObjectRegistry.object_type_to_edsl_class.get(object_type)
         object = edsl_class.from_dict(json.loads(json_string))
         return object
@@ -597,7 +674,7 @@ class Coop(CoopFunctionsMixin):
         """
         edsl_class = ObjectRegistry.object_type_to_edsl_class.get(object_type)
         response = self._send_server_request(
-            uri=f"api/v0/objects",
+            uri="api/v0/objects",
             method="GET",
             params={"type": object_type},
         )
@@ -677,7 +754,9 @@ class Coop(CoopFunctionsMixin):
             and value is None
             and alias is None
         ):
-            raise Exception("Nothing to patch.")
+            from .exceptions import CoopPatchError
+
+            raise CoopPatchError("Nothing to patch.")
 
         obj_uuid, owner_username, obj_alias = self._resolve_uuid_or_alias(url_or_uuid)
 
@@ -808,7 +887,9 @@ class Coop(CoopFunctionsMixin):
         [CacheEntry(...), CacheEntry(...), ...]
         """
         if job_uuid is None:
-            raise ValueError("Must provide a job_uuid.")
+            from .exceptions import CoopValueError
+
+            raise CoopValueError("Must provide a job_uuid.")
         response = self._send_server_request(
             uri="api/v0/remote-cache/get-many-by-job",
             method="POST",
@@ -836,7 +917,9 @@ class Coop(CoopFunctionsMixin):
         [CacheEntry(...), CacheEntry(...), ...]
         """
         if select_keys is None or len(select_keys) == 0:
-            raise ValueError("Must provide a non-empty list of select_keys.")
+            from .exceptions import CoopValueError
+
+            raise CoopValueError("Must provide a non-empty list of select_keys.")
         response = self._send_server_request(
             uri="api/v0/remote-cache/get-many-by-key",
             method="POST",
@@ -1099,7 +1182,9 @@ class Coop(CoopFunctionsMixin):
             ...     print(f"Results available at: {job_status['results_url']}")
         """
         if job_uuid is None and results_uuid is None:
-            raise ValueError("Either job_uuid or results_uuid must be provided.")
+            from .exceptions import CoopValueError
+
+            raise CoopValueError("Either job_uuid or results_uuid must be provided.")
         elif job_uuid is not None:
             params = {"job_uuid": job_uuid}
         else:
@@ -1136,7 +1221,7 @@ class Coop(CoopFunctionsMixin):
                 "latest_error_report_uuid": latest_error_report_uuid,
                 "latest_error_report_url": latest_error_report_url,
                 "status": data.get("status"),
-                "reason": data.get("reason"),
+                "reason": data.get("latest_failure_reason"),
                 "credits_consumed": data.get("price"),
                 "version": data.get("version"),
             }
@@ -1173,7 +1258,9 @@ class Coop(CoopFunctionsMixin):
         elif isinstance(input, Survey):
             job = Jobs(survey=input)
         else:
-            raise TypeError("Input must be either a Job or a Survey.")
+            from .exceptions import CoopTypeError
+
+            raise CoopTypeError("Input must be either a Job or a Survey.")
 
         response = self._send_server_request(
             uri="api/v0/remote-inference/cost",
@@ -1215,7 +1302,7 @@ class Coop(CoopFunctionsMixin):
         )
         survey_uuid = survey_details.get("uuid")
         response = self._send_server_request(
-            uri=f"api/v0/projects/create-from-survey",
+            uri="api/v0/projects/create-from-survey",
             method="POST",
             payload={"project_name": project_name, "survey_uuid": str(survey_uuid)},
         )
@@ -1308,7 +1395,9 @@ class Coop(CoopFunctionsMixin):
         elif CONFIG.get("EDSL_FETCH_TOKEN_PRICES") == "False":
             return {}
         else:
-            raise ValueError(
+            from .exceptions import CoopValueError
+
+            raise CoopValueError(
                 "Invalid EDSL_FETCH_TOKEN_PRICES value---should be 'True' or 'False'."
             )
 
@@ -1464,7 +1553,9 @@ class Coop(CoopFunctionsMixin):
         api_key = self._poll_for_api_key(edsl_auth_token)
 
         if api_key is None:
-            raise Exception("Timed out waiting for login. Please try again.")
+            from .exceptions import CoopTimeoutError
+
+            raise CoopTimeoutError("Timed out waiting for login. Please try again.")
 
         path_to_env = write_api_key_to_env(api_key)
         print("\n✨ API key retrieved and written to .env file at the following path:")

edsl/coop/coop_functions.py

@@ -1,6 +1,6 @@
 class CoopFunctionsMixin:
     def better_names(self, existing_names):
-        from edsl import QuestionList, Scenario
+        from .. import QuestionList, Scenario
 
         s = Scenario({"existing_names": existing_names})
         q = QuestionList(

edsl/coop/ep_key_handling.py

@@ -70,7 +70,7 @@ class ExpectedParrotKeyHandler:
 
     def ok_to_ask_to_store(self):
         """Check if it's okay to ask the user to store the key."""
-        from edsl.config import CONFIG
+        from ..config import CONFIG
 
         if CONFIG.get("EDSL_RUN_MODE") != "production":
             return False