edsl 0.1.29.dev2__py3-none-any.whl → 0.1.29.dev6__py3-none-any.whl

edsl/coop/coop.py

@@ -5,8 +5,14 @@ import requests
 from typing import Any, Optional, Union, Literal
 from uuid import UUID
 import edsl
-from edsl import CONFIG, CacheEntry
-from edsl.coop.utils import EDSLObject, ObjectRegistry, ObjectType, VisibilityType
+from edsl import CONFIG, CacheEntry, Jobs, Survey
+from edsl.coop.utils import (
+    EDSLObject,
+    ObjectRegistry,
+    ObjectType,
+    RemoteJobStatus,
+    VisibilityType,
+)
 
 
 class Coop:
@@ -88,6 +94,18 @@ class Coop:
         if value is None:
             return "null"
 
+    def _resolve_uuid(
+        self, uuid: Union[str, UUID] = None, url: str = None
+    ) -> Union[str, UUID]:
+        """
+        Resolve the uuid from a uuid or a url.
+        """
+        if not url and not uuid:
+            raise Exception("No uuid or url provided for the object.")
+        if not uuid and url:
+            uuid = url.split("/")[-1]
+        return uuid
+
     @property
     def edsl_settings(self) -> dict:
         """
@@ -100,9 +118,6 @@ class Coop:
     ################
     # Objects
     ################
-
-    # TODO: add URL to get and get_all methods
-
     def create(
         self,
         object: EDSLObject,
@@ -113,17 +128,16 @@ class Coop:
         Create an EDSL object in the Coop server.
         """
         object_type = ObjectRegistry.get_object_type_by_edsl_class(object)
-        object_page = ObjectRegistry.get_object_page_by_object_type(object_type)
         response = self._send_server_request(
             uri=f"api/v0/object",
             method="POST",
             payload={
                 "description": description,
-                "object_type": object_type,
                 "json_string": json.dumps(
                     object.to_dict(),
                     default=self._json_handle_none,
                 ),
+                "object_type": object_type,
                 "visibility": visibility,
                 "version": self._edsl_version,
             },
@@ -131,73 +145,51 @@ class Coop:
         self._resolve_server_response(response)
         response_json = response.json()
         return {
+            "description": response_json.get("description"),
+            "object_type": object_type,
+            "url": f"{self.url}/content/{response_json.get('uuid')}",
             "uuid": response_json.get("uuid"),
             "version": self._edsl_version,
-            "description": response_json.get("description"),
             "visibility": response_json.get("visibility"),
-            "url": f"{self.url}/content/{response_json.get('uuid')}",
         }
 
     def get(
         self,
-        object_type: ObjectType = None,
         uuid: Union[str, UUID] = None,
         url: str = None,
-        exec_profile=None,
+        expected_object_type: Optional[ObjectType] = None,
     ) -> EDSLObject:
         """
-        Retrieve an EDSL object either by object type & UUID, or by its url.
-        - The object has to belong to the user or not be private.
-        - Returns the initialized object class instance.
+        Retrieve an EDSL object by its uuid or its url.
+        - If the object's visibility is private, the user must be the owner.
+        - Optionally, check if the retrieved object is of a certain type.
 
-        :param object_type: the type of object to retrieve.
         :param uuid: the uuid of the object either in str or UUID format.
         :param url: the url of the object.
-        """
-        if url:
-            object_type = url.split("/")[-2]
-            uuid = url.split("/")[-1]
-        elif not object_type and not uuid:
-            raise Exception("Provide either object_type & UUID, or a url.")
-        edsl_class = ObjectRegistry.object_type_to_edsl_class.get(object_type)
-        import time
+        :param expected_object_type: the expected type of the object.
 
-        start = time.time()
+        :return: the object instance.
+        """
+        uuid = self._resolve_uuid(uuid, url)
         response = self._send_server_request(
             uri=f"api/v0/object",
             method="GET",
-            params={"type": object_type, "uuid": uuid},
+            params={"uuid": uuid},
         )
-        end = time.time()
-        if exec_profile:
-            print("Download exec time = ", end - start)
         self._resolve_server_response(response)
         json_string = response.json().get("json_string")
-        start = time.time()
-        res_object = edsl_class.from_dict(json.loads(json_string))
-        end = time.time()
-        if exec_profile:
-            print("Creating object exec time = ", end - start)
-        return res_object
-
-    def _get_base(
-        self,
-        cls: EDSLObject,
-        uuid: Union[str, UUID],
-        exec_profile=None,
-    ) -> EDSLObject:
-        """
-        Used by the Base class to offer a get functionality.
-        """
-        object_type = ObjectRegistry.get_object_type_by_edsl_class(cls)
-        return self.get(object_type, uuid, exec_profile=exec_profile)
+        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=}")
+        edsl_class = ObjectRegistry.object_type_to_edsl_class.get(object_type)
+        object = edsl_class.from_dict(json.loads(json_string))
+        return object
 
-    def get_all(self, object_type: ObjectType) -> list[EDSLObject]:
+    def get_all(self, object_type: ObjectType) -> list[dict[str, Any]]:
         """
         Retrieve all objects of a certain type associated with the user.
         """
         edsl_class = ObjectRegistry.object_type_to_edsl_class.get(object_type)
-        object_page = ObjectRegistry.get_object_page_by_object_type(object_type)
         response = self._send_server_request(
             uri=f"api/v0/objects",
             method="GET",
@@ -217,33 +209,23 @@ class Coop:
         ]
         return objects
 
-    def delete(self, object_type: ObjectType, uuid: Union[str, UUID]) -> dict:
+    def delete(self, uuid: Union[str, UUID] = None, url: str = None) -> dict:
         """
         Delete an object from the server.
         """
+        uuid = self._resolve_uuid(uuid, url)
         response = self._send_server_request(
             uri=f"api/v0/object",
             method="DELETE",
-            params={"type": object_type, "uuid": uuid},
+            params={"uuid": uuid},
         )
         self._resolve_server_response(response)
         return response.json()
 
-    def _delete_base(
-        self,
-        cls: EDSLObject,
-        uuid: Union[str, UUID],
-    ) -> dict:
-        """
-        Used by the Base class to offer a delete functionality.
-        """
-        object_type = ObjectRegistry.get_object_type_by_edsl_class(cls)
-        return self.delete(object_type, uuid)
-
     def patch(
         self,
-        object_type: ObjectType,
-        uuid: Union[str, UUID],
+        uuid: Union[str, UUID] = None,
+        url: str = None,
         description: Optional[str] = None,
         value: Optional[EDSLObject] = None,
         visibility: Optional[VisibilityType] = None,
@@ -254,14 +236,11 @@ class Coop:
         """
         if description is None and visibility is None and value is None:
             raise Exception("Nothing to patch.")
-        if value is not None:
-            value_type = ObjectRegistry.get_object_type_by_edsl_class(value)
-            if value_type != object_type:
-                raise Exception(f"Object type mismatch: {object_type=} {value_type=}")
+        uuid = self._resolve_uuid(uuid, url)
         response = self._send_server_request(
             uri=f"api/v0/object",
             method="PATCH",
-            params={"type": object_type, "uuid": uuid},
+            params={"uuid": uuid},
             payload={
                 "description": description,
                 "json_string": (
@@ -278,20 +257,6 @@ class Coop:
         self._resolve_server_response(response)
         return response.json()
 
-    def _patch_base(
-        self,
-        cls: EDSLObject,
-        uuid: Union[str, UUID],
-        description: Optional[str] = None,
-        value: Optional[EDSLObject] = None,
-        visibility: Optional[VisibilityType] = None,
-    ) -> dict:
-        """
-        Used by the Base class to offer a patch functionality.
-        """
-        object_type = ObjectRegistry.get_object_type_by_edsl_class(cls)
-        return self.patch(object_type, uuid, description, value, visibility)
-
     ################
     # Remote Cache
     ################
@@ -494,9 +459,57 @@ class Coop:
     ################
     # Remote Inference
     ################
+    def remote_inference_create(
+        self,
+        job: Jobs,
+        description: Optional[str] = None,
+        status: RemoteJobStatus = "queued",
+        visibility: Optional[VisibilityType] = "unlisted",
+    ) -> dict:
+        """
+        Send a remote inference job to the server.
+
+        :param job: The EDSL job to send to the server.
+        :param optional description: A description for this entry in the remote cache.
+        :param status: The status of the job. Should be 'queued', unless you are debugging.
+        :param visibility: The visibility of the cache entry.
+
+        >>> job = Jobs.example()
+        >>> coop.remote_inference_create(job=job, description="My job")
+        {'uuid': '9f8484ee-b407-40e4-9652-4133a7236c9c', 'description': 'My job', 'status': 'queued', 'visibility': 'unlisted', 'version': '0.1.29.dev4'}
+        """
+        response = self._send_server_request(
+            uri="api/v0/remote-inference",
+            method="POST",
+            payload={
+                "json_string": json.dumps(
+                    job.to_dict(),
+                    default=self._json_handle_none,
+                ),
+                "description": description,
+                "status": status,
+                "visibility": visibility,
+                "version": self._edsl_version,
+            },
+        )
+        self._resolve_server_response(response)
+        response_json = response.json()
+        return {
+            "uuid": response_json.get("jobs_uuid"),
+            "description": response_json.get("description"),
+            "status": response_json.get("status"),
+            "visibility": response_json.get("visibility"),
+            "version": self._edsl_version,
+        }
+
     def remote_inference_get(self, job_uuid: str) -> dict:
         """
-        Get the results of a remote inference job.
+        Get the details of a remote inference job.
+
+        :param job_uuid: The UUID of the EDSL job.
+
+        >>> coop.remote_inference_get("9f8484ee-b407-40e4-9652-4133a7236c9c")
+        {'jobs_uuid': '9f8484ee-b407-40e4-9652-4133a7236c9c', 'results_uuid': 'dd708234-31bf-4fe1-8747-6e232625e026', 'results_url': 'https://www.expectedparrot.com/content/dd708234-31bf-4fe1-8747-6e232625e026', 'status': 'completed', 'reason': None, 'price': 16, 'version': '0.1.29.dev4'}
         """
         response = self._send_server_request(
             uri="api/v0/remote-inference",
@@ -508,13 +521,44 @@ class Coop:
         return {
             "jobs_uuid": data.get("jobs_uuid"),
             "results_uuid": data.get("results_uuid"),
-            "results_url": "TO BE ADDED",
+            "results_url": f"{self.url}/content/{data.get('results_uuid')}",
             "status": data.get("status"),
             "reason": data.get("reason"),
             "price": data.get("price"),
             "version": data.get("version"),
         }
 
+    def remote_inference_cost(self, input: Union[Jobs, Survey]) -> int:
+        """
+        Get the cost of a remote inference job.
+
+        :param input: The EDSL job to send to the server.
+
+        >>> job = Jobs.example()
+        >>> coop.remote_inference_cost(input=job)
+        16
+        """
+        if isinstance(input, Jobs):
+            job = input
+        elif isinstance(input, Survey):
+            job = Jobs(survey=input)
+        else:
+            raise TypeError("Input must be either a Job or a Survey.")
+
+        response = self._send_server_request(
+            uri="api/v0/remote-inference/cost",
+            method="POST",
+            payload={
+                "json_string": json.dumps(
+                    job.to_dict(),
+                    default=self._json_handle_none,
+                ),
+            },
+        )
+        self._resolve_server_response(response)
+        response_json = response.json()
+        return response_json.get("cost")
+
     ################
     # Remote Errors
     ################
@@ -578,32 +622,65 @@ class Coop:
         return response_json
 
 
-if __name__ == "__main__":
-    from edsl.coop import Coop
-
-    # init
-    API_KEY = "b"
-    coop = Coop(api_key=API_KEY)
-    # basics
-    coop
-    coop.edsl_settings
-
-    ##############
-    # A. Objects
-    ##############
+def main():
+    """
+    A simple example for the coop client
+    """
     from uuid import uuid4
     from edsl import (
         Agent,
         AgentList,
         Cache,
         Notebook,
+        QuestionFreeText,
         QuestionMultipleChoice,
         Results,
         Scenario,
         ScenarioList,
         Survey,
     )
+    from edsl.coop import Coop
+    from edsl.data.CacheEntry import CacheEntry
+    from edsl.jobs import Jobs
+
+    # init & basics
+    API_KEY = "b"
+    coop = Coop(api_key=API_KEY)
+    coop
+    coop.edsl_settings
 
+    ##############
+    # A. A simple example
+    ##############
+    # .. create and manipulate an object through the Coop client
+    response = coop.create(QuestionMultipleChoice.example())
+    coop.get(uuid=response.get("uuid"))
+    coop.get(uuid=response.get("uuid"), expected_object_type="question")
+    coop.get(url=response.get("url"))
+    coop.create(QuestionMultipleChoice.example())
+    coop.get_all("question")
+    coop.patch(uuid=response.get("uuid"), visibility="private")
+    coop.patch(uuid=response.get("uuid"), description="hey")
+    coop.patch(uuid=response.get("uuid"), value=QuestionFreeText.example())
+    # coop.patch(uuid=response.get("uuid"), value=Survey.example()) - should throw error
+    coop.get(uuid=response.get("uuid"))
+    coop.delete(uuid=response.get("uuid"))
+
+    # .. create and manipulate an object through the class
+    response = QuestionMultipleChoice.example().push()
+    QuestionMultipleChoice.pull(uuid=response.get("uuid"))
+    QuestionMultipleChoice.pull(url=response.get("url"))
+    QuestionMultipleChoice.patch(uuid=response.get("uuid"), visibility="private")
+    QuestionMultipleChoice.patch(uuid=response.get("uuid"), description="hey")
+    QuestionMultipleChoice.patch(
+        uuid=response.get("uuid"), value=QuestionFreeText.example()
+    )
+    QuestionMultipleChoice.pull(response.get("uuid"))
+    QuestionMultipleChoice.delete(response.get("uuid"))
+
+    ##############
+    # B. Examples with all objects
+    ##############
     OBJECTS = [
         ("agent", Agent),
         ("agent_list", AgentList),
@@ -615,13 +692,12 @@ if __name__ == "__main__":
         ("scenario_list", ScenarioList),
         ("survey", Survey),
     ]
-
     for object_type, cls in OBJECTS:
         print(f"Testing {object_type} objects")
         # 1. Delete existing objects
         existing_objects = coop.get_all(object_type)
         for item in existing_objects:
-            coop.delete(object_type=object_type, uuid=item.get("uuid"))
+            coop.delete(uuid=item.get("uuid"))
         # 2. Create new objects
         example = cls.example()
         response_1 = coop.create(example)
@@ -635,51 +711,26 @@ if __name__ == "__main__":
         assert len(objects) == 4
         # 4. Try to retrieve an item that does not exist
         try:
-            coop.get(object_type=object_type, uuid=uuid4())
+            coop.get(uuid=uuid4())
         except Exception as e:
             print(e)
         # 5. Try to retrieve all test objects by their uuids
         for response in [response_1, response_2, response_3, response_4]:
-            coop.get(object_type=object_type, uuid=response.get("uuid"))
+            coop.get(uuid=response.get("uuid"))
         # 6. Change visibility of all objects
         for item in objects:
-            coop.patch(
-                object_type=object_type, uuid=item.get("uuid"), visibility="private"
-            )
+            coop.patch(uuid=item.get("uuid"), visibility="private")
         # 6. Change description of all objects
         for item in objects:
-            coop.patch(
-                object_type=object_type, uuid=item.get("uuid"), description="hey"
-            )
+            coop.patch(uuid=item.get("uuid"), description="hey")
         # 7. Delete all objects
         for item in objects:
-            coop.delete(object_type=object_type, uuid=item.get("uuid"))
+            coop.delete(uuid=item.get("uuid"))
         assert len(coop.get_all(object_type)) == 0
 
-    # a simple example
-    from edsl import Coop, QuestionMultipleChoice, QuestionFreeText
-
-    coop = Coop(api_key="b")
-    response = QuestionMultipleChoice.example().push()
-    QuestionMultipleChoice.pull(response.get("uuid"))
-    coop.patch(object_type="question", uuid=response.get("uuid"), visibility="public")
-    coop.patch(
-        object_type="question",
-        uuid=response.get("uuid"),
-        description="crazy new description",
-    )
-    coop.patch(
-        object_type="question",
-        uuid=response.get("uuid"),
-        value=QuestionFreeText.example(),
-    )
-    coop.delete(object_type="question", uuid=response.get("uuid"))
-
     ##############
-    # B. Remote Cache
+    # C. Remote Cache
     ##############
-    from edsl.data.CacheEntry import CacheEntry
-
     # clear
     coop.remote_cache_clear()
     assert coop.remote_cache_get() == []
@@ -701,30 +752,16 @@ if __name__ == "__main__":
     coop.remote_cache_get()
 
     ##############
-    # C. Remote Inference
+    # D. Remote Inference
     ##############
-    from edsl.jobs import Jobs
-
-    # check jobs on server (should be an empty list)
-    coop.get_all("job")
-    for job in coop.get_all("job"):
-        coop.delete(object_type="job", uuid=job.get("uuid"))
-    # post a job
-    response = coop.create(Jobs.example())
-    # get job and results
-    coop.remote_inference_get(response.get("uuid"))
-    coop.get(
-        object_type="results",
-        uuid=coop.remote_inference_get(response.get("uuid")).get("results_uuid"),
-    )
+    job = Jobs.example()
+    coop.remote_inference_cost(job)
+    results = coop.remote_inference_create(job)
+    coop.remote_inference_get(results.get("uuid"))
 
     ##############
-    # D. Errors
+    # E. Errors
     ##############
-    from edsl import Coop
-
-    coop = Coop()
-    coop.api_key = "a"
     coop.error_create({"something": "This is an error message"})
     coop.api_key = None
     coop.error_create({"something": "This is an error message"})

edsl/coop/utils.py

@@ -2,7 +2,6 @@ from edsl import (
     Agent,
     AgentList,
     Cache,
-    Jobs,
     Notebook,
     Results,
     Scenario,
@@ -17,7 +16,6 @@ EDSLObject = Union[
     Agent,
     AgentList,
     Cache,
-    Jobs,
     Notebook,
     Type[QuestionBase],
     Results,
@@ -31,9 +29,8 @@ ObjectType = Literal[
     "agent",
     "agent_list",
     "cache",
-    "job",
-    "question",
     "notebook",
+    "question",
     "results",
     "scenario",
     "scenario_list",
@@ -41,18 +38,12 @@ ObjectType = Literal[
     "study",
 ]
 
-ObjectPage = Literal[
-    "agents",
-    "agentlists",
-    "caches",
-    "jobs",
-    "notebooks",
-    "questions",
-    "results",
-    "scenarios",
-    "scenariolists",
-    "surveys",
-    "studies",
+
+RemoteJobStatus = Literal[
+    "queued",
+    "running",
+    "completed",
+    "failed",
 ]
 
 VisibilityType = Literal[
@@ -68,67 +59,21 @@ class ObjectRegistry:
     """
 
     objects = [
-        {
-            "object_type": "agent",
-            "edsl_class": Agent,
-            "object_page": "agents",
-        },
-        {
-            "object_type": "agent_list",
-            "edsl_class": AgentList,
-            "object_page": "agentlists",
-        },
-        {
-            "object_type": "cache",
-            "edsl_class": Cache,
-            "object_page": "caches",
-        },
-        {
-            "object_type": "job",
-            "edsl_class": Jobs,
-            "object_page": "jobs",
-        },
-        {
-            "object_type": "question",
-            "edsl_class": QuestionBase,
-            "object_page": "questions",
-        },
-        {
-            "object_type": "notebook",
-            "edsl_class": Notebook,
-            "object_page": "notebooks",
-        },
-        {
-            "object_type": "results",
-            "edsl_class": Results,
-            "object_page": "results",
-        },
-        {
-            "object_type": "scenario",
-            "edsl_class": Scenario,
-            "object_page": "scenarios",
-        },
-        {
-            "object_type": "scenario_list",
-            "edsl_class": ScenarioList,
-            "object_page": "scenariolists",
-        },
-        {
-            "object_type": "survey",
-            "edsl_class": Survey,
-            "object_page": "surveys",
-        },
-        {
-            "object_type": "study",
-            "edsl_class": Study,
-            "object_page": "studies",
-        },
+        {"object_type": "agent", "edsl_class": Agent},
+        {"object_type": "agent_list", "edsl_class": AgentList},
+        {"object_type": "cache", "edsl_class": Cache},
+        {"object_type": "question", "edsl_class": QuestionBase},
+        {"object_type": "notebook", "edsl_class": Notebook},
+        {"object_type": "results", "edsl_class": Results},
+        {"object_type": "scenario", "edsl_class": Scenario},
+        {"object_type": "scenario_list", "edsl_class": ScenarioList},
+        {"object_type": "survey", "edsl_class": Survey},
+        {"object_type": "study", "edsl_class": Study},
     ]
     object_type_to_edsl_class = {o["object_type"]: o["edsl_class"] for o in objects}
     edsl_class_to_object_type = {
         o["edsl_class"].__name__: o["object_type"] for o in objects
     }
-    object_type_to_object_page = {o["object_type"]: o["object_page"] for o in objects}
 
     @classmethod
     def get_object_type_by_edsl_class(cls, edsl_object: EDSLObject) -> ObjectType:
@@ -149,7 +94,3 @@ class ObjectRegistry:
         if EDSL_object is None:
             raise ValueError(f"EDSL class not found for {object_type=}")
         return EDSL_object
-
-    @classmethod
-    def get_object_page_by_object_type(cls, object_type: ObjectType) -> ObjectPage:
-        return cls.object_type_to_object_page.get(object_type)