edsl 0.1.48__py3-none-any.whl → 0.1.50__py3-none-any.whl

edsl/coop/__init__.py

@@ -8,6 +8,7 @@ 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.
@@ -17,9 +18,27 @@ Example:
     >>> 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 edsl.coop.exceptions import CoopInvalidMethodError
+
+                raise CoopInvalidMethodError(f"Invalid {method=}.")
         except requests.ConnectionError:
             raise requests.ConnectionError(f"Could not connect to the server at {url}.")
 
@@ -226,16 +229,17 @@ class Coop(CoopFunctionsMixin):
         """
         # Get EDSL version from header
         # breakpoint()
-        server_edsl_version = response.headers.get("X-EDSL-Version")
-
-        if server_edsl_version:
-            if self._user_version_is_outdated(
-                user_version_str=self._edsl_version,
-                server_version_str=server_edsl_version,
-            ):
-                print(
-                    "Please upgrade your EDSL version to access our latest features. Open your terminal and run `pip install --upgrade edsl`"
-                )
+        # Commented out as currently unused
+        # server_edsl_version = response.headers.get("X-EDSL-Version")
+
+        # if server_edsl_version:
+        #     if self._user_version_is_outdated(
+        #         user_version_str=self._edsl_version,
+        #         server_version_str=server_edsl_version,
+        #     ):
+        #         print(
+        #             "Please upgrade your EDSL version to access our latest features. Open your terminal and run `pip install --upgrade edsl`"
+        #         )
 
         if response.status_code >= 400:
             try:
@@ -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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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 edsl.coop.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/exceptions.py

@@ -16,8 +16,11 @@ class CoopErrors(BaseException):
     This is the parent class for all exceptions raised by the Coop module.
     It inherits from EDSL's BaseException to maintain consistency with
     the library's exception hierarchy.
+    
+    When catching errors from Coop operations, you can catch this exception
+    to handle all Coop-related errors in a single exception handler.
     """
-    pass
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"
 
 
 class CoopInvalidURLError(CoopErrors):
@@ -27,12 +30,21 @@ class CoopInvalidURLError(CoopErrors):
     This exception is raised when a URL provided to the Coop client
     does not match the expected format for object or resource URLs.
     
+    To fix this error:
+    1. Ensure the URL follows the correct pattern:
+       - https://expectedparrot.com/content/{uuid}
+       - https://expectedparrot.com/content/{username}/{alias}
+    2. Check for typos in the domain name or path structure
+    3. Verify that you're using a complete URL rather than just a UUID or path
+    
     Example:
-        When a URL doesn't follow the pattern:
-        - https://expectedparrot.com/content/{uuid}
-        - https://expectedparrot.com/content/{username}/{alias}
+        ```python
+        coop = Coop()
+        coop.get("https://wrongdomain.com/content/123")  # Raises CoopInvalidURLError
+        coop.get("https://expectedparrot.com/wrong-path/123")  # Raises CoopInvalidURLError
+        ```
     """
-    pass
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html#accessing-content"
 
 
 class CoopNoUUIDError(CoopErrors):
@@ -42,10 +54,18 @@ class CoopNoUUIDError(CoopErrors):
     This exception is raised when an operation requires a UUID or other
     identifier, but none was provided.
     
+    To fix this error:
+    1. Ensure you're providing either a valid UUID or a complete URL to the operation
+    2. If using an alias instead of a UUID, make sure the alias exists and is formatted correctly
+    
     Example:
-        When calling get() without providing a UUID or URL
+        ```python
+        coop = Coop()
+        coop.get()  # Raises CoopNoUUIDError - missing required UUID or URL
+        coop.get("")  # Raises CoopNoUUIDError - empty string is not a valid UUID
+        ```
     """
-    pass
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html#accessing-content"
 
 
 class CoopServerResponseError(CoopErrors):
@@ -56,7 +76,166 @@ class CoopServerResponseError(CoopErrors):
     response, such as authentication failures, rate limits, or server errors.
     The exception message typically includes the error details from the server.
     
+    To fix this error:
+    1. Check the exception message for specific error details from the server
+    2. For authentication errors (401), verify your API key is correct and not expired
+    3. For rate limit errors (429), reduce the frequency of your requests
+    4. For server errors (500+), the issue may be temporary - wait and try again
+    5. Check your network connection if you're getting connection timeout errors
+    
+    Example:
+        ```python
+        coop = Coop(api_key="invalid-key")
+        coop.get("valid-uuid")  # Raises CoopServerResponseError with 401 Unauthorized
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/api_keys.html"
+
+
+class CoopInvalidMethodError(CoopErrors):
+    """
+    Exception raised when an invalid method is requested.
+    
+    This exception is raised when attempting to use an HTTP method that is not
+    supported by the Coop API client or by a specific endpoint.
+    
+    To fix this error:
+    1. Check that you're using a valid HTTP method (GET, POST, PUT, DELETE, PATCH)
+    2. Verify that the endpoint you're accessing supports the method you're using
+    3. Consider using a higher-level method in the Coop class rather than direct HTTP methods
+    
+    Example:
+        ```python
+        coop = Coop()
+        coop._request("INVALID_METHOD", "/endpoint")  # Raises CoopInvalidMethodError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"
+
+
+class CoopResponseError(CoopErrors):
+    """
+    Exception raised when there's an issue with the server response.
+    
+    This exception is raised when the server response cannot be processed or
+    is missing expected data, even though the HTTP status code might be successful.
+    
+    To fix this error:
+    1. Check the exception message for details about what data was missing
+    2. Verify that your request contains all required parameters
+    3. Ensure you're using the correct endpoint for your intended operation
+    
+    Example:
+        ```python
+        coop = Coop()
+        # Assuming an endpoint that returns incomplete data
+        coop.get("some-resource")  # Might raise CoopResponseError if response is malformed
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"
+
+
+class CoopObjectTypeError(CoopErrors):
+    """
+    Exception raised when an object has an unexpected type.
+    
+    This exception is raised when an object retrieved from the server has a type
+    that doesn't match what was expected, particularly when using typed methods.
+    
+    To fix this error:
+    1. Make sure you're using the correct method for the object type you want
+    2. Verify that the UUID or URL points to the expected object type
+    3. Use the generic get() method if you're uncertain about the object type
+    
+    Example:
+        ```python
+        coop = Coop()
+        # Trying to get a Survey object but the UUID points to a Job
+        coop.get_survey("job-uuid")  # Raises CoopObjectTypeError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html#accessing-content"
+
+
+class CoopPatchError(CoopErrors):
+    """
+    Exception raised when a patch operation cannot be performed.
+    
+    This exception is raised when attempting to update an object but not
+    providing any fields to update, or if the patch operation fails.
+    
+    To fix this error:
+    1. Ensure you're providing at least one field to update
+    2. Verify that you have permission to update the object
+    3. Check that the object still exists and hasn't been deleted
+    
+    Example:
+        ```python
+        coop = Coop()
+        coop.patch("object-uuid")  # Raises CoopPatchError if no update fields provided
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html#updating-content"
+
+
+class CoopValueError(CoopErrors):
+    """
+    Exception raised when invalid parameters are provided to a Coop operation.
+    
+    This exception is raised when required parameters are missing or when
+    parameters have invalid values.
+    
+    To fix this error:
+    1. Check that all required parameters are provided
+    2. Verify that parameter values meet the expected format or constraints
+    3. Consult the API documentation for the correct parameter usage
+    
+    Example:
+        ```python
+        coop = Coop()
+        coop.get_job_results()  # Raises CoopValueError if job_uuid is not provided
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"
+
+
+class CoopTypeError(CoopErrors):
+    """
+    Exception raised when a parameter has an incorrect type.
+    
+    This exception is raised when a parameter provided to a Coop method
+    has a type that doesn't match what's expected.
+    
+    To fix this error:
+    1. Check the expected types of method parameters
+    2. Convert parameters to the correct type before passing them
+    3. Ensure you're using EDSL objects where required
+    
+    Example:
+        ```python
+        coop = Coop()
+        coop.create("not_an_edsl_object")  # Raises CoopTypeError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"
+
+
+class CoopTimeoutError(CoopErrors):
+    """
+    Exception raised when a Coop operation times out.
+    
+    This exception is raised when an operation takes longer than the
+    specified timeout period to complete.
+    
+    To fix this error:
+    1. Increase the timeout value for long-running operations
+    2. Check your network connection if timeouts occur frequently
+    3. For login operations, try again or use API key authentication instead
+    
     Example:
-        When the server returns a 401 Unauthorized response due to an invalid API key
+        ```python
+        coop = Coop()
+        coop.login(timeout=1)  # Raises CoopTimeoutError if login takes longer than 1 second
+        ```
     """
-    pass
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/using_coop.html"

edsl/coop/price_fetcher.py

@@ -7,9 +7,7 @@ that price information is only fetched once and then cached for efficiency.
 """
 
 import requests
-import csv
-from io import StringIO
-from typing import Dict, Tuple, Optional, Any
+from typing import Dict, Tuple, Any
 
 
 class PriceFetcher:
@@ -85,7 +83,6 @@ class PriceFetcher:
             return self._cached_prices
 
         import os
-        import requests
         from ..config import CONFIG
 
         try:
@@ -96,7 +93,7 @@ class PriceFetcher:
             if api_key:
                 headers["Authorization"] = f"Bearer {api_key}"
             else:
-                headers["Authorization"] = f"Bearer None"
+                headers["Authorization"] = "Bearer None"
 
             response = requests.get(url, headers=headers, timeout=20)
             response.raise_for_status()  # Raise an exception for bad responses
@@ -120,7 +117,7 @@ class PriceFetcher:
             self._cached_prices = price_lookup
             return self._cached_prices
 
-        except requests.RequestException as e:
+        except requests.RequestException:
             # Silently handle errors and return empty dict
             # print(f"An error occurred: {e}")
             return {}