edsl 0.1.27.dev2__py3-none-any.whl → 0.1.28__py3-none-any.whl

edsl/Base.py

@@ -4,7 +4,7 @@ from abc import ABC, abstractmethod, ABCMeta
 import gzip
 import io
 import json
-from typing import Union
+from typing import Any, Optional, Union
 from uuid import UUID
 from IPython.display import display
 from rich.console import Console
@@ -40,25 +40,30 @@ class RichPrintingMixin:
 class PersistenceMixin:
     """Mixin for saving and loading objects to and from files."""
 
-    def push(self, visibility="unlisted"):
+    def push(
+        self,
+        description: Optional[str] = None,
+        visibility: Optional[str] = "unlisted",
+    ):
         """Post the object to coop."""
         from edsl.coop import Coop
 
         c = Coop()
-        return c.create(self, visibility)
+        return c.create(self, description, visibility)
 
     @classmethod
-    def pull(cls, id_or_url: Union[str, UUID]):
+    def pull(cls, id_or_url: Union[str, UUID], exec_profile=None):
         """Pull the object from coop."""
         from edsl.coop import Coop
 
+        if id_or_url.startswith("http"):
+            uuid_value = id_or_url.split("/")[-1]
+        else:
+            uuid_value = id_or_url
+
         c = Coop()
-        return c._get_base(cls, id_or_url)
-        # if isinstance(id_or_url, str) and c.url in id_or_url:
-        #     return c.get(url=id_or_url)
-        # else:
-        #     _, object_type = c._resolve_edsl_object(cls)
-        #     return c.get(object_type, id_or_url)
+
+        return c._get_base(cls, uuid_value, exec_profile=exec_profile)
 
     @classmethod
     def delete(cls, id_or_url: Union[str, UUID]):
@@ -69,15 +74,23 @@ class PersistenceMixin:
         return c._delete_base(cls, id_or_url)
 
     @classmethod
-    def patch(cls, id_or_url: Union[str, UUID], visibility: str):
+    def patch(
+        cls,
+        id_or_url: Union[str, UUID],
+        description: Optional[str] = None,
+        value: Optional[Any] = None,
+        visibility: Optional[str] = None,
+    ):
         """
         Patch an uploaded objects attributes.
-        - Only supports changing visibility for now.
+        - `description` changes the description of the object on Coop
+        - `value` changes the value of the object on Coop. **has to be an EDSL object**
+        - `visibility` changes the visibility of the object on Coop
         """
         from edsl.coop import Coop
 
         c = Coop()
-        return c._patch_base(cls, id_or_url, visibility)
+        return c._patch_base(cls, id_or_url, description, value, visibility)
 
     @classmethod
     def search(cls, query):
@@ -87,14 +100,45 @@ class PersistenceMixin:
         c = Coop()
         return c.search(cls, query)
 
-    def save(self, filename):
+    def save(self, filename, compress=True):
         """Save the object to a file as zippped JSON.
 
         >>> obj.save("obj.json.gz")
 
         """
-        with gzip.open(filename, "wb") as f:
-            f.write(json.dumps(self.to_dict()).encode("utf-8"))
+        if filename.endswith("json.gz"):
+            import warnings
+
+            warnings.warn(
+                "Do not apply the file extensions. The filename should not end with 'json.gz'."
+            )
+            filename = filename[:-7]
+        if filename.endswith("json"):
+            filename = filename[:-4]
+            warnings.warn(
+                "Do not apply the file extensions. The filename should not end with 'json'."
+            )
+
+        if compress:
+            with gzip.open(filename + ".json.gz", "wb") as f:
+                f.write(json.dumps(self.to_dict()).encode("utf-8"))
+        else:
+            with open(filename + ".json", "w") as f:
+                f.write(json.dumps(self.to_dict()))
+
+    @staticmethod
+    def open_compressed_file(filename):
+        with gzip.open(filename, "rb") as f:
+            file_contents = f.read()
+            file_contents_decoded = file_contents.decode("utf-8")
+            d = json.loads(file_contents_decoded)
+        return d
+
+    @staticmethod
+    def open_regular_file(filename):
+        with open(filename, "r") as f:
+            d = json.loads(f.read())
+        return d
 
     @classmethod
     def load(cls, filename):
@@ -103,11 +147,19 @@ class PersistenceMixin:
         >>> obj = cls.load("obj.json.gz")
 
         """
-        with gzip.open(filename, "rb") as f:
-            file_contents = f.read()
-            file_contents_decoded = file_contents.decode("utf-8")
-            d = json.loads(file_contents_decoded)
-            # d = json.loads(f.read().decode("utf-8"))
+
+        if filename.endswith("json.gz"):
+            d = cls.open_compressed_file(filename)
+        elif filename.endswith("json"):
+            d = cls.open_regular_file(filename)
+        else:
+            try:
+                d = cls.open_compressed_file(filename)
+            except:
+                d = cls.open_regular_file(filename)
+            finally:
+                raise ValueError("File must be a json or json.gz file")
+
         return cls.from_dict(d)
 
 
@@ -128,7 +180,21 @@ class RegisterSubclassesMeta(ABCMeta):
         return dict(RegisterSubclassesMeta._registry)
 
 
-class Base(RichPrintingMixin, PersistenceMixin, ABC, metaclass=RegisterSubclassesMeta):
+class DiffMethodsMixin:
+    def __sub__(self, other):
+        """Return the difference between two objects."""
+        from edsl.BaseDiff import BaseDiff
+
+        return BaseDiff(self, other)
+
+
+class Base(
+    RichPrintingMixin,
+    PersistenceMixin,
+    DiffMethodsMixin,
+    ABC,
+    metaclass=RegisterSubclassesMeta,
+):
     """Base class for all classes in the package."""
 
     # def __getitem__(self, key):
@@ -172,6 +238,17 @@ class Base(RichPrintingMixin, PersistenceMixin, ABC, metaclass=RegisterSubclasse
     #         f.write(html_string)
     #         webbrowser.open(f.name)
 
+    def __eq__(self, other):
+        """Return whether two objects are equal."""
+        import inspect
+
+        if not isinstance(other, self.__class__):
+            return False
+        if "sort" in inspect.signature(self._to_dict).parameters:
+            return self._to_dict(sort=True) == other._to_dict(sort=True)
+        else:
+            return self._to_dict() == other._to_dict()
+
     @abstractmethod
     def example():
         """This method should be implemented by subclasses."""

edsl/BaseDiff.py

@@ -0,0 +1,260 @@
+import difflib
+import json
+from typing import Any, Dict, Tuple
+from collections import UserList
+import inspect
+
+
+class BaseDiffCollection(UserList):
+    def __init__(self, diffs=None):
+        if diffs is None:
+            diffs = []
+        super().__init__(diffs)
+
+    def apply(self, obj: Any):
+        for diff in self:
+            obj = diff.apply(obj)
+        return obj
+
+    def add_diff(self, diff) -> "BaseDiffCollection":
+        self.append(diff)
+        return self
+
+
+class DummyObject:
+    def __init__(self, object_dict):
+        self.object_dict = object_dict
+
+    def _to_dict(self):
+        return self.object_dict
+
+
+class BaseDiff:
+    def __init__(
+        self, obj1: Any, obj2: Any, added=None, removed=None, modified=None, level=0
+    ):
+        self.level = level
+
+        self.obj1 = obj1
+        self.obj2 = obj2
+
+        if "sort" in inspect.signature(obj1._to_dict).parameters:
+            self._dict1 = obj1._to_dict(sort=True)
+            self._dict2 = obj2._to_dict(sort=True)
+        else:
+            self._dict1 = obj1._to_dict()
+            self._dict2 = obj2._to_dict()
+        self._obj_class = type(obj1)
+
+        self.added = added
+        self.removed = removed
+        self.modified = modified
+
+    def __bool__(self):
+        return bool(self.added or self.removed or self.modified)
+
+    @property
+    def added(self):
+        if self._added is None:
+            self._added = self._find_added()
+        return self._added
+
+    def __add__(self, other):
+        return self.apply(other)
+
+    @added.setter
+    def added(self, value):
+        self._added = value if value is not None else self._find_added()
+
+    @property
+    def removed(self):
+        if self._removed is None:
+            self._removed = self._find_removed()
+        return self._removed
+
+    @removed.setter
+    def removed(self, value):
+        self._removed = value if value is not None else self._find_removed()
+
+    @property
+    def modified(self):
+        if self._modified is None:
+            self._modified = self._find_modified()
+        return self._modified
+
+    @modified.setter
+    def modified(self, value):
+        self._modified = value if value is not None else self._find_modified()
+
+    def _find_added(self) -> Dict[Any, Any]:
+        return {k: self._dict2[k] for k in self._dict2 if k not in self._dict1}
+
+    def _find_removed(self) -> Dict[Any, Any]:
+        return {k: self._dict1[k] for k in self._dict1 if k not in self._dict2}
+
+    def _find_modified(self) -> Dict[Any, Tuple[Any, Any, str]]:
+        modified = {}
+        for k in self._dict1:
+            if k in self._dict2 and self._dict1[k] != self._dict2[k]:
+                if isinstance(self._dict1[k], str) and isinstance(self._dict2[k], str):
+                    diff = self._diff_strings(self._dict1[k], self._dict2[k])
+                    modified[k] = (self._dict1[k], self._dict2[k], diff)
+                elif isinstance(self._dict1[k], dict) and isinstance(
+                    self._dict2[k], dict
+                ):
+                    diff = self._diff_dicts(self._dict1[k], self._dict2[k])
+                    modified[k] = (self._dict1[k], self._dict2[k], diff)
+                elif isinstance(self._dict1[k], list) and isinstance(
+                    self._dict2[k], list
+                ):
+                    d1 = dict(zip(range(len(self._dict1[k])), self._dict1[k]))
+                    d2 = dict(zip(range(len(self._dict2[k])), self._dict2[k]))
+                    diff = BaseDiff(
+                        DummyObject(d1), DummyObject(d2), level=self.level + 1
+                    )
+                    modified[k] = (self._dict1[k], self._dict2[k], diff)
+                else:
+                    modified[k] = (self._dict1[k], self._dict2[k], "")
+        return modified
+
+    @staticmethod
+    def is_json(string_that_could_be_json: str) -> bool:
+        try:
+            json.loads(string_that_could_be_json)
+            return True
+        except json.JSONDecodeError:
+            return False
+
+    def _diff_dicts(self, dict1: Dict[str, Any], dict2: Dict[str, Any]) -> str:
+        diff = BaseDiff(DummyObject(dict1), DummyObject(dict2), level=self.level + 1)
+        return diff
+
+    def _diff_strings(self, str1: str, str2: str) -> str:
+        if self.is_json(str1) and self.is_json(str2):
+            diff = self._diff_dicts(json.loads(str1), json.loads(str2))
+            return diff
+        diff = difflib.ndiff(str1.splitlines(), str2.splitlines())
+        return diff
+
+    def apply(self, obj: Any):
+        """Apply the diff to the object."""
+
+        new_obj_dict = obj._to_dict()
+        for k, v in self.added.items():
+            new_obj_dict[k] = v
+        for k in self.removed.keys():
+            del new_obj_dict[k]
+        for k, (v1, v2, diff) in self.modified.items():
+            new_obj_dict[k] = v2
+
+        return obj.from_dict(new_obj_dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "added": self.added,
+            "removed": self.removed,
+            "modified": self.modified,
+            "obj1": self._dict1,
+            "obj2": self._dict2,
+            "obj_class": self._obj_class.__name__,
+            "level": self.level,
+        }
+
+    @classmethod
+    def from_dict(cls, diff_dict: Dict[str, Any], obj1: Any, obj2: Any):
+        return cls(
+            obj1=obj1,
+            obj2=obj2,
+            added=diff_dict["added"],
+            removed=diff_dict["removed"],
+            modified=diff_dict["modified"],
+            level=diff_dict["level"],
+        )
+
+    class Results(UserList):
+        def __init__(self, prepend=" ", level=0):
+            super().__init__()
+            self.prepend = prepend
+            self.level = level
+
+        def append(self, item):
+            super().append(self.prepend * self.level + item)
+
+    def __str__(self):
+        prepend = " "
+        result = self.Results(level=self.level, prepend="\t")
+        if self.added:
+            result.append("Added keys and values:")
+            for k, v in self.added.items():
+                result.append(prepend + f"  {k}: {v}")
+        if self.removed:
+            result.append("Removed keys and values:")
+            for k, v in self.removed.items():
+                result.append(f"  {k}: {v}")
+        if self.modified:
+            result.append("Modified keys and values:")
+            for k, (v1, v2, diff) in self.modified.items():
+                result.append(f"Key: {k}:")
+                result.append(f"    Old value: {v1}")
+                result.append(f"    New value: {v2}")
+                if diff:
+                    result.append(f"    Diff:")
+                    try:
+                        for line in diff:
+                            result.append(f"      {line}")
+                    except:
+                        result.append(f"      {diff}")
+        return "\n".join(result)
+
+    def __repr__(self):
+        return (
+            f"BaseDiff(obj1={self.obj1!r}, obj2={self.obj2!r}, added={self.added!r}, "
+            f"removed={self.removed!r}, modified={self.modified!r})"
+        )
+
+    def add_diff(self, diff) -> "BaseDiffCollection":
+        return BaseDiffCollection([self, diff])
+
+
+if __name__ == "__main__":
+    from edsl import Question
+
+    q_ft = Question.example("free_text")
+    q_mc = Question.example("multiple_choice")
+
+    diff1 = q_ft - q_mc
+    assert q_ft == q_mc + diff1
+    assert q_ft == diff1.apply(q_mc)
+    # new_q_mc = diff1.apply(q_ft)
+    # assert new_q_mc == q_mc
+
+    # new_q_mc = q_ft + diff1
+    # assert new_q_mc == q_mc
+
+    # new_q_mc = diff1 + q_ft
+    # assert new_q_mc == q_mc
+
+    # ## Test chain of diffs
+    q0 = Question.example("free_text")
+    q1 = q0.copy()
+    q1.question_text = "Why is Buzzard's Bay so named?"
+    diff1 = q1 - q0
+    q2 = q1.copy()
+    q2.question_name = "buzzard_bay"
+    diff2 = q2 - q1
+
+    diff_chain = diff1.add_diff(diff2)
+
+    new_q2 = diff_chain.apply(q0)
+    assert new_q2 == q2
+
+    new_q2 = diff_chain + q0
+    assert new_q2 == q2
+
+    # new_diffs = diff1.add_diff(diff1).add_diff(diff1)
+    # assert len(new_diffs) == 3
+
+    # q0 = Question.example("free_text")
+    # q1 = Question.example("free_text")
+    # q1.question_text = "Why is Buzzard's Bay so named?"
+    # q2 = q1.copy()

edsl/__init__.py

@@ -35,4 +35,8 @@ from edsl.data.CacheEntry import CacheEntry
 from edsl.data.CacheHandler import set_session_cache, unset_session_cache
 from edsl.shared import shared_globals
 from edsl.jobs import Jobs
+from edsl.notebooks import Notebook
+from edsl.study.Study import Study
 from edsl.coop.coop import Coop
+from edsl.conjure.Conjure import Conjure
+from edsl.language_models.ModelList import ModelList

edsl/__version__.py

@@ -1 +1 @@
-__version__ = "0.1.27.dev2"
+__version__ = "0.1.28"

edsl/agents/Agent.py

@@ -98,7 +98,7 @@ class Agent(Base):
 
         >>> a = Agent(traits = {"age": 10}, traits_presentation_template = "I am a {{age}} year old.")
         >>> repr(a.agent_persona)
-        "Prompt(text='I am a {{age}} year old.')"
+        'Prompt(text=\"""I am a {{age}} year old.\""")'
 
         When this is rendered for presentation to the LLM, it will replace the `{{age}}` with the actual age.
         it is also possible to use the `codebook` to provide a more human-readable description of the trait.
@@ -109,7 +109,7 @@ class Agent(Base):
         >>> a = Agent(traits = traits, codebook = codebook, traits_presentation_template = "This agent is Dave. {{codebook['age']}} {{age}}")
         >>> d = a.traits | {'codebook': a.codebook}
         >>> a.agent_persona.render(d)
-        Prompt(text='This agent is Dave. Their age is 10')
+        Prompt(text=\"""This agent is Dave. Their age is 10\""")
 
         Instructions
         ------------
@@ -198,6 +198,18 @@ class Agent(Base):
         else:
             return self._traits
 
+    def rename(self, old_name: str, new_name: str) -> Agent:
+        """Rename a trait.
+
+        Example usage:
+
+        >>> a = Agent(traits = {"age": 10, "hair": "brown", "height": 5.5})
+        >>> a.rename("age", "years") == Agent(traits = {'years': 10, 'hair': 'brown', 'height': 5.5})
+        True
+        """
+        self.traits[new_name] = self.traits.pop(old_name)
+        return self
+
     def __getitem__(self, key):
         """Allow for accessing traits using the bracket notation.
 
@@ -327,7 +339,7 @@ class Agent(Base):
         >>> from edsl import QuestionFreeText
         >>> q = QuestionFreeText.example()
         >>> a.answer_question(question = q, cache = False)
-        {'answer': 'I am a direct answer.', 'comment': 'This is a real survey response from a human.', 'question_name': 'how_are_you', 'prompts': {'user_prompt': Prompt(text='NA'), 'system_prompt': Prompt(text='NA')}, 'usage': {'prompt_tokens': 0, 'completion_tokens': 0}, 'cached_response': None, 'raw_model_response': None, 'simple_model_raw_response': None}
+        {'answer': 'I am a direct answer.', 'comment': 'This is a real survey response from a human.', ...}
 
         This is a function where an agent returns an answer to a particular question.
         However, there are several different ways an agent can answer a question, so the
@@ -547,6 +559,15 @@ class Agent(Base):
 
         return raw_data
 
+    def __hash__(self) -> int:
+        from edsl.utilities.utilities import dict_hash
+
+        return dict_hash(self._to_dict())
+
+    def _to_dict(self) -> dict[str, Union[dict, bool]]:
+        """Serialize to a dictionary."""
+        return self.data
+
     @add_edsl_version
     def to_dict(self) -> dict[str, Union[dict, bool]]:
         """Serialize to a dictionary.
@@ -557,7 +578,7 @@ class Agent(Base):
         >>> a.to_dict()
         {'name': 'Steve', 'traits': {'age': 10, 'hair': 'brown', 'height': 5.5}, 'edsl_version': '...', 'edsl_class_name': 'Agent'}
         """
-        return self.data
+        return self._to_dict()
 
     @classmethod
     @remove_edsl_version
@@ -567,7 +588,7 @@ class Agent(Base):
         Example usage:
 
         >>> Agent.from_dict({'name': "Steve", 'traits': {'age': 10, 'hair': 'brown', 'height': 5.5}})
-        Agent(name = 'Steve', traits = {'age': 10, 'hair': 'brown', 'height': 5.5})
+        Agent(name = \"""Steve\""", traits = {'age': 10, 'hair': 'brown', 'height': 5.5})
 
         """
         return cls(**agent_dict)

edsl/agents/AgentList.py

@@ -18,6 +18,7 @@ from rich.table import Table
 import json
 import csv
 
+
 from simpleeval import EvalWithCompoundTypes
 
 from edsl.Base import Base
@@ -41,6 +42,38 @@ class AgentList(UserList, Base):
         else:
             super().__init__()
 
+    def shuffle(self, seed: Optional[str] = "edsl") -> AgentList:
+        """Shuffle the AgentList.
+
+        :param seed: The seed for the random number generator.
+        """
+        import random
+
+        random.seed(seed)
+        random.shuffle(self.data)
+        return self
+
+    def sample(self, n: int, seed="edsl") -> AgentList:
+        """Return a random sample of agents.
+
+        :param n: The number of agents to sample.
+        :param seed: The seed for the random number generator.
+        """
+        import random
+
+        random.seed(seed)
+        return AgentList(random.sample(self.data, n))
+
+    def rename(self, old_name, new_name):
+        """Rename a trait in the AgentList.
+
+        :param old_name: The old name of the trait.
+        :param new_name: The new name of the trait.
+        """
+        for agent in self.data:
+            agent.rename(old_name, new_name)
+        return self
+
     def select(self, *traits) -> AgentList:
         """Selects agents with only the references traits.
 
@@ -139,21 +172,36 @@ class AgentList(UserList, Base):
             reader = csv.DictReader(f)
             return {field: None for field in reader.fieldnames}
 
+    def __hash__(self) -> int:
+        from edsl.utilities.utilities import dict_hash
+
+        data = self.to_dict()
+        # data['agent_list'] = sorted(data['agent_list'], key=lambda x: dict_hash(x)
+        return dict_hash(self._to_dict(sorted=True))
+
+    def _to_dict(self, sorted=False):
+        if sorted:
+            data = self.data[:]
+            data.sort(key=lambda x: hash(x))
+        else:
+            data = self.data
+
+        return {"agent_list": [agent.to_dict() for agent in data]}
+
+    def __eq__(self, other: AgentList) -> bool:
+        return self._to_dict(sorted=True) == other._to_dict(sorted=True)
+
     @add_edsl_version
     def to_dict(self):
-        """Return dictionary of AgentList to serialization.
-
-        >>> AgentList.example().to_dict()
-        {'agent_list': [{'traits': {'age': 22, 'hair': 'brown', 'height': 5.5}, 'edsl_version': '...', 'edsl_class_name': 'Agent'}, {'traits': {'age': 22, 'hair': 'brown', 'height': 5.5}, 'edsl_version': '...', 'edsl_class_name': 'Agent'}], 'edsl_version': '...', 'edsl_class_name': 'AgentList'}
-        """
-        return {"agent_list": [agent.to_dict() for agent in self.data]}
+        """Return dictionary of AgentList to serialization."""
+        return self._to_dict()
 
     def __repr__(self):
         return f"AgentList({self.data})"
 
     def print(self, format: Optional[str] = None):
         """Print the AgentList."""
-        print_json(json.dumps(self.to_dict()))
+        print_json(json.dumps(self._to_dict()))
 
     def _repr_html_(self):
         """Return an HTML representation of the AgentList."""
@@ -161,6 +209,13 @@ class AgentList(UserList, Base):
 
         return data_to_html(self.to_dict()["agent_list"])
 
+    def to_scenario_list(self) -> "ScenarioList":
+        """Return a list of scenarios."""
+        from edsl.scenarios.ScenarioList import ScenarioList
+        from edsl.scenarios.Scenario import Scenario
+
+        return ScenarioList([Scenario(agent.traits) for agent in self.data])
+
     @classmethod
     @remove_edsl_version
     def from_dict(cls, data: dict) -> "AgentList":

edsl/agents/Invigilator.py

@@ -63,14 +63,9 @@ class InvigilatorAI(PromptConstructorMixin, InvigilatorBase):
 
     def _remove_from_cache(self, raw_response) -> None:
         """Remove an entry from the cache."""
-        if (
-            "raw_model_response" in raw_response
-            and "cache_key" in raw_response["raw_model_response"]
-        ):
-            cache_key = raw_response["raw_model_response"]["cache_key"]
-        else:
-            cache_key = None
-        del self.cache.data[cache_key]
+        cache_key = raw_response.get("cache_key", None)
+        if cache_key:
+            del self.cache.data[cache_key]
 
     def _format_raw_response(
         self, *, agent, question, scenario, raw_response, raw_model_response
@@ -95,7 +90,7 @@ class InvigilatorAI(PromptConstructorMixin, InvigilatorBase):
             ),  # not all question have comment fields,
             "question_name": question.question_name,
             "prompts": self.get_prompts(),
-            "cached_response": raw_response["cached_response"],
+            "cached_response": raw_response.get("cached_response", None),
             "usage": raw_response.get("usage", {}),
             "raw_model_response": raw_model_response,
         }