edsl 0.1.27.dev2__py3-none-any.whl → 0.1.29__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,28 +118,26 @@ class Coop:
     ################
     # Objects
     ################
-
-    # TODO: add URL to get and get_all methods
-
     def create(
         self,
         object: EDSLObject,
-        visibility: VisibilityType = "unlisted",
+        description: Optional[str] = None,
+        visibility: Optional[VisibilityType] = "unlisted",
     ) -> dict:
         """
         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={
-                "object_type": object_type,
+                "description": description,
                 "json_string": json.dumps(
                     object.to_dict(),
                     default=self._json_handle_none,
                 ),
+                "object_type": object_type,
                 "visibility": visibility,
                 "version": self._edsl_version,
             },
@@ -129,59 +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,
             "visibility": response_json.get("visibility"),
-            "url": f"{self.url}/explore/{object_page}/{response_json.get('uuid')}",
         }
 
     def get(
         self,
-        object_type: ObjectType = None,
         uuid: Union[str, UUID] = None,
         url: str = 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.
+        :param expected_object_type: the expected type of the object.
+
+        :return: the object instance.
         """
-        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)
+        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},
         )
         self._resolve_server_response(response)
         json_string = response.json().get("json_string")
-        return edsl_class.from_dict(json.loads(json_string))
-
-    def _get_base(
-        self,
-        cls: EDSLObject,
-        uuid: Union[str, UUID],
-    ) -> 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)
+        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",
@@ -193,67 +201,62 @@ class Coop:
                 "object": edsl_class.from_dict(json.loads(o.get("json_string"))),
                 "uuid": o.get("uuid"),
                 "version": o.get("version"),
+                "description": o.get("description"),
                 "visibility": o.get("visibility"),
-                "url": f"{self.url}/explore/{object_page}/{o.get('uuid')}",
+                "url": f"{self.url}/content/{o.get('uuid')}",
             }
             for o in response.json()
         ]
         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],
-        visibility: VisibilityType,
+        uuid: Union[str, UUID] = None,
+        url: str = None,
+        description: Optional[str] = None,
+        value: Optional[EDSLObject] = None,
+        visibility: Optional[VisibilityType] = None,
     ) -> dict:
         """
         Change the attributes of an uploaded object
         - Only supports visibility for now
         """
+        if description is None and visibility is None and value is None:
+            raise Exception("Nothing to patch.")
+        uuid = self._resolve_uuid(uuid, url)
         response = self._send_server_request(
             uri=f"api/v0/object",
             method="PATCH",
-            params={"type": object_type, "uuid": uuid},
-            payload={"visibility": visibility},
+            params={"uuid": uuid},
+            payload={
+                "description": description,
+                "json_string": (
+                    json.dumps(
+                        value.to_dict(),
+                        default=self._json_handle_none,
+                    )
+                    if value
+                    else None
+                ),
+                "visibility": visibility,
+            },
         )
         self._resolve_server_response(response)
         return response.json()
 
-    def _patch_base(
-        self,
-        cls: EDSLObject,
-        uuid: Union[str, UUID],
-        visibility: VisibilityType,
-    ) -> 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, visibility)
-
     ################
     # Remote Cache
     ################
@@ -261,9 +264,19 @@ class Coop:
         self,
         cache_entry: CacheEntry,
         visibility: VisibilityType = "private",
+        description: Optional[str] = None,
     ) -> dict:
         """
         Create a single remote cache entry.
+        If an entry with the same key already exists in the database, update it instead.
+
+        :param cache_entry: The cache entry to send to the server.
+        :param visibility: The visibility of the cache entry.
+        :param optional description: A description for this entry in the remote cache.
+
+        >>> entry = CacheEntry.example()
+        >>> coop.remote_cache_create(cache_entry=entry)
+        {'status': 'success', 'created_entry_count': 1, 'updated_entry_count': 0}
         """
         response = self._send_server_request(
             uri="api/v0/remote-cache",
@@ -272,24 +285,44 @@ class Coop:
                 "json_string": json.dumps(cache_entry.to_dict()),
                 "version": self._edsl_version,
                 "visibility": visibility,
+                "description": description,
             },
         )
         self._resolve_server_response(response)
+        response_json = response.json()
+        created_entry_count = response_json.get("created_entry_count", 0)
+        if created_entry_count > 0:
+            self.remote_cache_create_log(
+                response,
+                description="Upload new cache entries to server",
+                cache_entry_count=created_entry_count,
+            )
         return response.json()
 
     def remote_cache_create_many(
         self,
         cache_entries: list[CacheEntry],
         visibility: VisibilityType = "private",
+        description: Optional[str] = None,
     ) -> dict:
         """
         Create many remote cache entries.
+        If an entry with the same key already exists in the database, update it instead.
+
+        :param cache_entries: The list of cache entries to send to the server.
+        :param visibility: The visibility of the cache entries.
+        :param optional description: A description for these entries in the remote cache.
+
+        >>> entries = [CacheEntry.example(randomize=True) for _ in range(10)]
+        >>> coop.remote_cache_create_many(cache_entries=entries)
+        {'status': 'success', 'created_entry_count': 10, 'updated_entry_count': 0}
         """
         payload = [
             {
                 "json_string": json.dumps(c.to_dict()),
                 "version": self._edsl_version,
                 "visibility": visibility,
+                "description": description,
             }
             for c in cache_entries
         ]
@@ -299,6 +332,14 @@ class Coop:
             payload=payload,
         )
         self._resolve_server_response(response)
+        response_json = response.json()
+        created_entry_count = response_json.get("created_entry_count", 0)
+        if created_entry_count > 0:
+            self.remote_cache_create_log(
+                response,
+                description="Upload new cache entries to server",
+                cache_entry_count=created_entry_count,
+            )
         return response.json()
 
     def remote_cache_get(
@@ -307,7 +348,11 @@ class Coop:
     ) -> list[CacheEntry]:
         """
         Get all remote cache entries.
-        - optional exclude_keys: exclude CacheEntry objects with these keys.
+
+        :param optional exclude_keys: Exclude CacheEntry objects with these keys.
+
+        >>> coop.remote_cache_get()
+        [CacheEntry(...), CacheEntry(...), ...]
         """
         if exclude_keys is None:
             exclude_keys = []
@@ -322,23 +367,149 @@ class Coop:
             for v in response.json()
         ]
 
+    def remote_cache_get_diff(
+        self,
+        client_cacheentry_keys: list[str],
+    ) -> dict:
+        """
+        Get the difference between local and remote cache entries for a user.
+        """
+        response = self._send_server_request(
+            uri="api/v0/remote-cache/get-diff",
+            method="POST",
+            payload={"keys": client_cacheentry_keys},
+        )
+        self._resolve_server_response(response)
+        response_json = response.json()
+        response_dict = {
+            "client_missing_cacheentries": [
+                CacheEntry.from_dict(json.loads(c.get("json_string")))
+                for c in response_json.get("client_missing_cacheentries", [])
+            ],
+            "server_missing_cacheentry_keys": response_json.get(
+                "server_missing_cacheentry_keys", []
+            ),
+        }
+        downloaded_entry_count = len(response_dict["client_missing_cacheentries"])
+        if downloaded_entry_count > 0:
+            self.remote_cache_create_log(
+                response,
+                description="Download missing cache entries to client",
+                cache_entry_count=downloaded_entry_count,
+            )
+        return response_dict
+
     def remote_cache_clear(self) -> dict:
         """
         Clear all remote cache entries.
+
+        >>> entries = [CacheEntry.example(randomize=True) for _ in range(10)]
+        >>> coop.remote_cache_create_many(cache_entries=entries)
+        >>> coop.remote_cache_clear()
+        {'status': 'success', 'deleted_entry_count': 10}
         """
         response = self._send_server_request(
             uri="api/v0/remote-cache/delete-all",
             method="DELETE",
         )
         self._resolve_server_response(response)
+        response_json = response.json()
+        deleted_entry_count = response_json.get("deleted_entry_count", 0)
+        if deleted_entry_count > 0:
+            self.remote_cache_create_log(
+                response,
+                description="Clear cache entries",
+                cache_entry_count=deleted_entry_count,
+            )
+        return response.json()
+
+    def remote_cache_create_log(
+        self, response: requests.Response, description: str, cache_entry_count: int
+    ) -> Union[dict, None]:
+        """
+        If a remote cache action has been completed successfully,
+        log the action.
+        """
+        if 200 <= response.status_code < 300:
+            log_response = self._send_server_request(
+                uri="api/v0/remote-cache-log",
+                method="POST",
+                payload={
+                    "description": description,
+                    "cache_entry_count": cache_entry_count,
+                },
+            )
+            self._resolve_server_response(log_response)
+            return response.json()
+
+    def remote_cache_clear_log(self) -> dict:
+        """
+        Clear all remote cache log entries.
+
+        >>> coop.remote_cache_clear_log()
+        {'status': 'success'}
+        """
+        response = self._send_server_request(
+            uri="api/v0/remote-cache-log/delete-all",
+            method="DELETE",
+        )
+        self._resolve_server_response(response)
         return response.json()
 
     ################
     # 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",
@@ -350,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
     ################
@@ -420,87 +622,115 @@ 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,
-        Jobs,
+        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),
         ("cache", Cache),
-        ("job", Jobs),
+        ("notebook", Notebook),
         ("question", QuestionMultipleChoice),
         ("results", Results),
         ("scenario", Scenario),
         ("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)
         response_2 = coop.create(cls.example(), visibility="private")
         response_3 = coop.create(cls.example(), visibility="public")
-        response_4 = coop.create(cls.example(), visibility="unlisted")
+        response_4 = coop.create(
+            cls.example(), visibility="unlisted", description="hey"
+        )
         # 3. Retrieve all objects
         objects = coop.get_all(object_type)
         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(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
 
-    response = QuestionMultipleChoice.example().push()
-    QuestionMultipleChoice.pull(response.get("uuid"))
-    coop.patch(object_type="question", uuid=response.get("uuid"), visibility="public")
-    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() == []
@@ -522,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"})