edsl 0.1.29.dev3__tar.gz → 0.1.30__tar.gz

{edsl-0.1.29.dev3 → edsl-0.1.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.29.dev3
+Version: 0.1.30
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT
@@ -57,15 +57,6 @@ The Expected Parrot Domain-Specific Language (EDSL) package lets you conduct com
 - [LinkedIn](https://www.linkedin.com/company/expectedparrot/)
 - [Blog](https://blog.expectedparrot.com)
 
-## 💡 Contributions, feature requests & bugs
-Interested in contributing? Want us to add a new feature? Found a bug for us to squash? 
-Please send us an email at [info@expectedparrot.com](mailto:info@expectedparrot.com) or message us at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).
-
-## 💻 Requirements
-* EDSL is compatible with Python 3.9 - 3.12.
-* API keys for large language models that you want to use, stored in a `.env` file.
-See instructions on [storing API keys](https://docs.expectedparrot.com/en/latest/api_keys.html).
-
 ## 🌎 Hello, World!
 A quick example:
 
@@ -96,3 +87,13 @@ Output:
 │ Good              │
 └───────────────────┘
 ```
+
+## 💻 Requirements
+* EDSL is compatible with Python 3.9 - 3.12.
+* API keys for large language models that you want to use, stored in a `.env` file.
+See instructions on [storing API keys](https://docs.expectedparrot.com/en/latest/api_keys.html).
+
+## 💡 Contributions, feature requests & bugs
+Interested in contributing? Want us to add a new feature? Found a bug for us to squash? 
+Please send us an email at [info@expectedparrot.com](mailto:info@expectedparrot.com) or message us at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).
+

{edsl-0.1.29.dev3 → edsl-0.1.30}/README.md

@@ -14,15 +14,6 @@ The Expected Parrot Domain-Specific Language (EDSL) package lets you conduct com
 - [LinkedIn](https://www.linkedin.com/company/expectedparrot/)
 - [Blog](https://blog.expectedparrot.com)
 
-## 💡 Contributions, feature requests & bugs
-Interested in contributing? Want us to add a new feature? Found a bug for us to squash? 
-Please send us an email at [info@expectedparrot.com](mailto:info@expectedparrot.com) or message us at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).
-
-## 💻 Requirements
-* EDSL is compatible with Python 3.9 - 3.12.
-* API keys for large language models that you want to use, stored in a `.env` file.
-See instructions on [storing API keys](https://docs.expectedparrot.com/en/latest/api_keys.html).
-
 ## 🌎 Hello, World!
 A quick example:
 
@@ -52,4 +43,13 @@ Output:
 ┡━━━━━━━━━━━━━━━━━━━┩
 │ Good              │
 └───────────────────┘
-```
+```
+
+## 💻 Requirements
+* EDSL is compatible with Python 3.9 - 3.12.
+* API keys for large language models that you want to use, stored in a `.env` file.
+See instructions on [storing API keys](https://docs.expectedparrot.com/en/latest/api_keys.html).
+
+## 💡 Contributions, feature requests & bugs
+Interested in contributing? Want us to add a new feature? Found a bug for us to squash? 
+Please send us an email at [info@expectedparrot.com](mailto:info@expectedparrot.com) or message us at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).

edsl-0.1.30/edsl/Base.py

@@ -0,0 +1,288 @@
+"""Base class for all classes in the package. It provides rich printing and persistence of objects."""
+
+from abc import ABC, abstractmethod, ABCMeta
+import gzip
+import io
+import json
+from typing import Any, Optional, Union
+from uuid import UUID
+
+
+class RichPrintingMixin:
+    """Mixin for rich printing and persistence of objects."""
+
+    def _for_console(self):
+        """Return a string representation of the object for console printing."""
+        from rich.console import Console
+
+        with io.StringIO() as buf:
+            console = Console(file=buf, record=True)
+            table = self.rich_print()
+            console.print(table)
+            return console.export_text()
+
+    def __str__(self):
+        """Return a string representation of the object for console printing."""
+        return self._for_console()
+
+    def print(self):
+        """Print the object to the console."""
+        from edsl.utilities.utilities import is_notebook
+
+        if is_notebook():
+            from IPython.display import display
+
+            display(self.rich_print())
+        else:
+            from rich.console import Console
+
+            console = Console()
+            console.print(self.rich_print())
+
+
+class PersistenceMixin:
+    """Mixin for saving and loading objects to and from files."""
+
+    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, description, visibility)
+
+    @classmethod
+    def pull(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+        """Pull the object from coop."""
+        from edsl.coop import Coop
+        from edsl.coop.utils import ObjectRegistry
+
+        object_type = ObjectRegistry.get_object_type_by_edsl_class(cls)
+        coop = Coop()
+        return coop.get(uuid, url, object_type)
+
+    @classmethod
+    def delete(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+        """Delete the object from coop."""
+        from edsl.coop import Coop
+
+        coop = Coop()
+        return coop.delete(uuid, url)
+
+    @classmethod
+    def patch(
+        cls,
+        uuid: Optional[Union[str, UUID]] = None,
+        url: Optional[str] = None,
+        description: Optional[str] = None,
+        value: Optional[Any] = None,
+        visibility: Optional[str] = None,
+    ):
+        """
+        Patch an uploaded objects attributes.
+        - `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
+
+        coop = Coop()
+        return coop.patch(uuid, url, description, value, visibility)
+
+    @classmethod
+    def search(cls, query):
+        """Search for objects on coop."""
+        from edsl.coop import Coop
+
+        c = Coop()
+        return c.search(cls, query)
+
+    def save(self, filename, compress=True):
+        """Save the object to a file as zippped JSON.
+
+        >>> obj.save("obj.json.gz")
+
+        """
+        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):
+        """Load the object from a file.
+
+        >>> obj = cls.load("obj.json.gz")
+
+        """
+
+        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)
+
+
+class RegisterSubclassesMeta(ABCMeta):
+    """Metaclass for registering subclasses."""
+
+    _registry = {}
+
+    def __init__(cls, name, bases, nmspc):
+        """Register the class in the registry upon creation."""
+        super(RegisterSubclassesMeta, cls).__init__(name, bases, nmspc)
+        if cls.__name__ != "Base":
+            RegisterSubclassesMeta._registry[cls.__name__] = cls
+
+    @staticmethod
+    def get_registry():
+        """Return the registry of subclasses."""
+        return dict(RegisterSubclassesMeta._registry)
+
+
+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):
+    #     return getattr(self, key)
+
+    # @abstractmethod
+    # def _repr_html_(self) -> str:
+    #     raise NotImplementedError("This method is not implemented yet.")
+
+    # @abstractmethod
+    # def _repr_(self) -> str:
+    #     raise NotImplementedError("This method is not implemented yet.")
+
+    def keys(self):
+        """Return the keys of the object."""
+        _keys = list(self.to_dict().keys())
+        if "edsl_version" in _keys:
+            _keys.remove("edsl_version")
+        if "edsl_class_name" in _keys:
+            _keys.remove("edsl_class_name")
+        return _keys
+
+    def values(self):
+        """Return the values of the object."""
+        data = self.to_dict()
+        keys = self.keys()
+        return {data[key] for key in keys}
+
+    def _repr_html_(self):
+        from edsl.utilities.utilities import data_to_html
+
+        return data_to_html(self.to_dict())
+
+    # def html(self):
+    #     html_string = self._repr_html_()
+    #     import tempfile
+    #     import webbrowser
+
+    #     with tempfile.NamedTemporaryFile("w", delete=False, suffix=".html") as f:
+    #         # print("Writing HTML to", f.name)
+    #         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."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def rich_print():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def to_dict():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def from_dict():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    @abstractmethod
+    def code():
+        """This method should be implemented by subclasses."""
+        raise NotImplementedError("This method is not implemented yet.")
+
+    def show_methods(self, show_docstrings=True):
+        """Show the methods of the object."""
+        public_methods_with_docstrings = [
+            (method, getattr(self, method).__doc__)
+            for method in dir(self)
+            if callable(getattr(self, method)) and not method.startswith("_")
+        ]
+        if show_docstrings:
+            for method, documentation in public_methods_with_docstrings:
+                print(f"{method}: {documentation}")
+        else:
+            return [x[0] for x in public_methods_with_docstrings]

edsl-0.1.30/edsl/__init__.py

@@ -0,0 +1,42 @@
+import os
+import time
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.dirname(BASE_DIR)
+
+from edsl.__version__ import __version__
+from edsl.config import Config, CONFIG
+from edsl.agents.Agent import Agent
+from edsl.agents.AgentList import AgentList
+from edsl.questions import QuestionBase
+from edsl.questions import QuestionMultipleChoice
+from edsl.questions import QuestionBudget
+from edsl.questions import QuestionCheckBox
+from edsl.questions import QuestionExtract
+from edsl.questions import QuestionFreeText
+from edsl.questions import QuestionFunctional
+from edsl.questions import QuestionLikertFive
+from edsl.questions import QuestionList
+from edsl.questions import QuestionLinearScale
+from edsl.questions import QuestionNumerical
+from edsl.questions import QuestionRank
+from edsl.questions import QuestionTopK
+from edsl.questions import QuestionYesNo
+from edsl.questions.question_registry import Question
+from edsl.scenarios import Scenario
+from edsl.scenarios import ScenarioList
+
+# from edsl.utilities.interface import print_dict_with_rich
+from edsl.surveys.Survey import Survey
+from edsl.language_models.registry import Model
+from edsl.language_models.ModelList import ModelList
+from edsl.results.Results import Results
+from edsl.data.Cache import Cache
+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.Jobs import Jobs
+from edsl.notebooks.Notebook import Notebook
+from edsl.study.Study import Study
+from edsl.conjure.Conjure import Conjure
+from edsl.coop.coop import Coop

edsl-0.1.30/edsl/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.30"

{edsl-0.1.29.dev3 → edsl-0.1.30}/edsl/agents/Agent.py

@@ -4,28 +4,16 @@ from __future__ import annotations
 import copy
 import inspect
 import types
-from typing import Any, Callable, Optional, Union, Dict, Sequence
-
-from rich.table import Table
-
+from typing import Callable, Optional, Union
+from uuid import uuid4
 from edsl.Base import Base
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.language_models import LanguageModel
-from edsl.surveys.MemoryPlan import MemoryPlan
+
 from edsl.exceptions.agents import (
     AgentCombinationError,
     AgentDirectAnswerFunctionError,
     AgentDynamicTraitsFunctionError,
 )
-from edsl.agents.Invigilator import (
-    InvigilatorDebug,
-    InvigilatorHuman,
-    InvigilatorFunctional,
-    InvigilatorAI,
-    InvigilatorBase,
-)
-from edsl.language_models.registry import Model
-from edsl.scenarios import Scenario
+
 from edsl.agents.descriptors import (
     TraitsDescriptor,
     CodebookDescriptor,
@@ -38,10 +26,6 @@ from edsl.utilities.decorators import (
     remove_edsl_version,
 )
 from edsl.data_transfer_models import AgentResponseDict
-from edsl.prompts.library.agent_persona import AgentPersona
-from edsl.data.Cache import Cache
-
-
 from edsl.utilities.restricted_python import create_restricted_function
 
 
@@ -56,6 +40,7 @@ class Agent(Base):
     name = NameDescriptor()
     dynamic_traits_function_name = ""
     answer_question_directly_function_name = ""
+    has_dynamic_traits_function = False
 
     def __init__(
         self,
@@ -129,12 +114,16 @@ class Agent(Base):
 
         if self.dynamic_traits_function:
             self.dynamic_traits_function_name = self.dynamic_traits_function.__name__
+            self.has_dynamic_traits_function = True
+        else:
+            self.has_dynamic_traits_function = False
 
         if dynamic_traits_function_source_code:
             self.dynamic_traits_function_name = dynamic_traits_function_name
             self.dynamic_traits_function = create_restricted_function(
                 dynamic_traits_function_name, dynamic_traits_function
             )
+
         if answer_question_directly_source_code:
             self.answer_question_directly_function_name = (
                 answer_question_directly_function_name
@@ -151,6 +140,8 @@ class Agent(Base):
         self.current_question = None
 
         if traits_presentation_template is not None:
+            from edsl.prompts.library.agent_persona import AgentPersona
+
             self.traits_presentation_template = traits_presentation_template
             self.agent_persona = AgentPersona(text=self.traits_presentation_template)
 
@@ -159,7 +150,7 @@ class Agent(Base):
 
         This checks whether the dynamic traits function is valid.
         """
-        if self.dynamic_traits_function is not None:
+        if self.has_dynamic_traits_function:
             sig = inspect.signature(self.dynamic_traits_function)
             if "question" in sig.parameters:
                 if len(sig.parameters) > 1:
@@ -189,7 +180,7 @@ class Agent(Base):
         {'age': 10, 'hair': 'brown', 'height': 5.5}
 
         """
-        if self.dynamic_traits_function is not None:
+        if self.has_dynamic_traits_function:
             sig = inspect.signature(self.dynamic_traits_function)
             if "question" in sig.parameters:
                 return self.dynamic_traits_function(question=self.current_question)
@@ -271,8 +262,9 @@ class Agent(Base):
     def create_invigilator(
         self,
         *,
-        question: QuestionBase,
-        cache,
+        question: "QuestionBase",
+        cache: "Cache",
+        survey: Optional["Survey"] = None,
         scenario: Optional[Scenario] = None,
         model: Optional[LanguageModel] = None,
         debug: bool = False,
@@ -280,7 +272,7 @@ class Agent(Base):
         current_answers: Optional[dict] = None,
         iteration: int = 1,
         sidecar_model=None,
-    ) -> InvigilatorBase:
+    ) -> "InvigilatorBase":
         """Create an Invigilator.
 
         An invigilator is an object that is responsible for administering a question to an agent.
@@ -294,6 +286,8 @@ class Agent(Base):
         An invigator is an object that is responsible for administering a question to an agent and
         recording the responses.
         """
+        from edsl import Model, Scenario
+
         cache = cache
         self.current_question = question
         model = model or Model()
@@ -301,6 +295,7 @@ class Agent(Base):
         invigilator = self._create_invigilator(
             question=question,
             scenario=scenario,
+            survey=survey,
             model=model,
             debug=debug,
             memory_plan=memory_plan,
@@ -314,12 +309,13 @@ class Agent(Base):
     async def async_answer_question(
         self,
         *,
-        question: QuestionBase,
-        cache: Cache,
-        scenario: Optional[Scenario] = None,
-        model: Optional[LanguageModel] = None,
+        question: "QuestionBase",
+        cache: "Cache",
+        scenario: Optional["Scenario"] = None,
+        survey: Optional["Survey"] = None,
+        model: Optional["LanguageModel"] = None,
         debug: bool = False,
-        memory_plan: Optional[MemoryPlan] = None,
+        memory_plan: Optional["MemoryPlan"] = None,
         current_answers: Optional[dict] = None,
         iteration: int = 0,
     ) -> AgentResponseDict:
@@ -349,6 +345,7 @@ class Agent(Base):
             question=question,
             cache=cache,
             scenario=scenario,
+            survey=survey,
             model=model,
             debug=debug,
             memory_plan=memory_plan,
@@ -362,21 +359,35 @@ class Agent(Base):
 
     def _create_invigilator(
         self,
-        question: QuestionBase,
-        cache: Optional[Cache] = None,
-        scenario: Optional[Scenario] = None,
-        model: Optional[LanguageModel] = None,
+        question: "QuestionBase",
+        cache: Optional["Cache"] = None,
+        scenario: Optional["Scenario"] = None,
+        model: Optional["LanguageModel"] = None,
+        survey: Optional["Survey"] = None,
         debug: bool = False,
-        memory_plan: Optional[MemoryPlan] = None,
+        memory_plan: Optional["MemoryPlan"] = None,
         current_answers: Optional[dict] = None,
         iteration: int = 0,
         sidecar_model=None,
-    ) -> InvigilatorBase:
+    ) -> "InvigilatorBase":
         """Create an Invigilator."""
+        from edsl import Model
+        from edsl import Scenario
+
         model = model or Model()
         scenario = scenario or Scenario()
 
+        from edsl.agents.Invigilator import (
+            InvigilatorDebug,
+            InvigilatorHuman,
+            InvigilatorFunctional,
+            InvigilatorAI,
+            InvigilatorBase,
+        )
+
         if cache is None:
+            from edsl.data.Cache import Cache
+
             cache = Cache()
 
         if debug:
@@ -404,6 +415,7 @@ class Agent(Base):
             self,
             question=question,
             scenario=scenario,
+            survey=survey,
             model=model,
             memory_plan=memory_plan,
             current_answers=current_answers,
@@ -479,6 +491,29 @@ class Agent(Base):
         """
         return self.data == other.data
 
+    def __getattr__(self, name):
+        # This will be called only if 'name' is not found in the usual places
+        # breakpoint()
+        if name == "has_dynamic_traits_function":
+            return self.has_dynamic_traits_function
+
+        if name in self.traits:
+            return self.traits[name]
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        # Include any additional state that needs to be serialized
+        return state
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+        # Ensure _traits is initialized if it's missing
+        if "_traits" not in self.__dict__:
+            self._traits = {}
+
     def print(self) -> None:
         from rich import print_json
         import json
@@ -640,6 +675,8 @@ class Agent(Base):
         >>> a.rich_print()
         <rich.table.Table object at ...>
         """
+        from rich.table import Table
+
         table_data, column_names = self._table()
         table = Table(title=f"{self.__class__.__name__} Attributes")
         for column in column_names:
@@ -652,13 +689,14 @@ class Agent(Base):
         return table
 
     @classmethod
-    def example(cls) -> Agent:
-        """Return an example agent.
+    def example(cls, randomize: bool = False) -> Agent:
+        """
+        Returns an example Agent instance.
 
-        >>> Agent.example()
-        Agent(traits = {'age': 22, 'hair': 'brown', 'height': 5.5})
+        :param randomize: If True, adds a random string to the value of an example key.
         """
-        return cls(traits={"age": 22, "hair": "brown", "height": 5.5})
+        addition = "" if not randomize else str(uuid4())
+        return cls(traits={"age": 22, "hair": f"brown{addition}", "height": 5.5})
 
     def code(self) -> str:
         """Return the code for the agent.