edsl 0.1.36.dev5__tar.gz → 0.1.37__tar.gz

{edsl-0.1.36.dev5 → edsl-0.1.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.36.dev5
+Version: 0.1.37
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT

{edsl-0.1.36.dev5 → edsl-0.1.37}/edsl/__init__.py

@@ -27,6 +27,7 @@ from edsl.questions import QuestionTopK
 
 from edsl.scenarios import Scenario
 from edsl.scenarios import ScenarioList
+from edsl.scenarios.FileStore import FileStore
 
 # from edsl.utilities.interface import print_dict_with_rich
 from edsl.surveys.Survey import Survey

edsl-0.1.37/edsl/__version__.py

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

{edsl-0.1.36.dev5 → edsl-0.1.37}/edsl/agents/Agent.py

@@ -4,14 +4,23 @@ from __future__ import annotations
 import copy
 import inspect
 import types
-from typing import Callable, Optional, Union, Any
+from typing import Callable, Optional, Union, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl import Cache, Survey, Scenario
+    from edsl.language_models import LanguageModel
+    from edsl.surveys.MemoryPlan import MemoryPlan
+    from edsl.questions import QuestionBase
+    from edsl.agents.Invigilator import InvigilatorBase
+
 from uuid import uuid4
-from edsl.Base import Base
 
+from edsl.Base import Base
 from edsl.prompts import Prompt
 from edsl.exceptions import QuestionScenarioRenderError
 
 from edsl.exceptions.agents import (
+    AgentErrors,
     AgentCombinationError,
     AgentDirectAnswerFunctionError,
     AgentDynamicTraitsFunctionError,
@@ -33,7 +42,9 @@ from edsl.utilities.restricted_python import create_restricted_function
 
 
 class Agent(Base):
-    """An Agent that can answer questions."""
+    """An class representing an agent that can answer questions."""
+
+    __doc__ = "https://docs.expectedparrot.com/en/latest/agents.html"
 
     default_instruction = """You are answering questions as if you were a human. Do not break character."""
 
@@ -148,9 +159,10 @@ class Agent(Base):
         self.current_question = None
 
         if traits_presentation_template is not None:
+            self._traits_presentation_template = traits_presentation_template
             self.traits_presentation_template = traits_presentation_template
         else:
-            self.traits_presentation_template = """Your traits: {{ traits }}"""
+            self.traits_presentation_template = "Your traits: {{traits}}"
 
     @property
     def agent_persona(self) -> Prompt:
@@ -181,13 +193,23 @@ class Agent(Base):
         """Check whether dynamic trait function is valid.
 
         This checks whether the dynamic traits function is valid.
+
+        >>> def f(question): return {"age": 10, "hair": "brown", "height": 5.5}
+        >>> a = Agent(dynamic_traits_function = f)
+        >>> a._check_dynamic_traits_function()
+
+        >>> def g(question, poo): return {"age": 10, "hair": "brown", "height": 5.5}
+        >>> a = Agent(dynamic_traits_function = g)
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.agents.AgentDynamicTraitsFunctionError: ...
         """
         if self.has_dynamic_traits_function:
             sig = inspect.signature(self.dynamic_traits_function)
             if "question" in sig.parameters:
                 if len(sig.parameters) > 1:
                     raise AgentDynamicTraitsFunctionError(
-                        f"The dynamic traits function {self.dynamic_traits_function} has too many parameters. It should only have one parameter: 'question'."
+                        message=f"The dynamic traits function {self.dynamic_traits_function} has too many parameters. It should only have one parameter: 'question'."
                     )
             else:
                 if len(sig.parameters) > 0:
@@ -221,7 +243,38 @@ class Agent(Base):
         else:
             return self._traits
 
-    def rename(self, old_name: str, new_name: str) -> Agent:
+    def rename(
+        self, old_name_or_dict: Union[str, dict], new_name: Optional[str] = None
+    ) -> 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
+
+        >>> a.rename({'years': 'smage'})
+        Agent(traits = {'hair': 'brown', 'height': 5.5, 'smage': 10})
+
+        """
+        if isinstance(old_name_or_dict, dict) and new_name is None:
+            for old_name, new_name in old_name_or_dict.items():
+                self = self._rename(old_name, new_name)
+            return self
+
+        if isinstance(old_name_or_dict, dict) and new_name:
+            raise AgentErrors(
+                f"You passed a dict: {old_name_or_dict} and a new name: {new_name}. You should pass only a dict."
+            )
+
+        if isinstance(old_name_or_dict, str):
+            self._rename(old_name_or_dict, new_name)
+            return self
+
+        raise AgentErrors("Something is not right with Agent renaming")
+
+    def _rename(self, old_name: str, new_name: str) -> Agent:
         """Rename a trait.
 
         Example usage:
@@ -267,8 +320,11 @@ class Agent(Base):
         translate_response: bool = False,
     ) -> None:
         """Add a method to the agent that can answer a particular question type.
+        https://docs.expectedparrot.com/en/latest/agents.html#agent-direct-answering-methods
 
         :param method: A method that can answer a question directly.
+        :param validate_response: Whether to validate the response.
+        :param translate_response: Whether to translate the response.
 
         Example usage:
 
@@ -304,10 +360,10 @@ class Agent(Base):
         question: "QuestionBase",
         cache: "Cache",
         survey: Optional["Survey"] = None,
-        scenario: Optional[Scenario] = None,
-        model: Optional[LanguageModel] = None,
+        scenario: Optional["Scenario"] = 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 = 1,
         sidecar_model=None,
@@ -354,13 +410,13 @@ class Agent(Base):
     async def async_answer_question(
         self,
         *,
-        question: "QuestionBase",
-        cache: "Cache",
-        scenario: Optional["Scenario"] = None,
-        survey: Optional["Survey"] = 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:
@@ -404,13 +460,13 @@ class Agent(Base):
 
     def _create_invigilator(
         self,
-        question: "QuestionBase",
-        cache: Optional["Cache"] = None,
-        scenario: Optional["Scenario"] = None,
-        model: Optional["LanguageModel"] = None,
-        survey: Optional["Survey"] = 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,
@@ -493,9 +549,6 @@ class Agent(Base):
 
         return Agent(traits={trait: self.traits[trait] for trait in traits_to_select})
 
-    ################
-    # Dunder Methods
-    ################
     def __add__(self, other_agent: Optional[Agent] = None) -> Agent:
         """
         Combine two agents by joining their traits.
@@ -512,6 +565,7 @@ class Agent(Base):
         Traceback (most recent call last):
         ...
         edsl.exceptions.agents.AgentCombinationError: The agents have overlapping traits: {'age'}.
+        ...
         """
         if other_agent is None:
             return self
@@ -540,12 +594,12 @@ class Agent(Base):
 
     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}'"
         )
@@ -598,6 +652,7 @@ class Agent(Base):
             for k, v in self.__dict__.items()
             if k.startswith("_")
         }
+
         if hasattr(self, "set_instructions"):
             if not self.set_instructions:
                 raw_data.pop("instruction")
@@ -614,16 +669,14 @@ class Agent(Base):
             if dynamic_traits_func:
                 func = inspect.getsource(dynamic_traits_func)
                 raw_data["dynamic_traits_function_source_code"] = func
-                raw_data["dynamic_traits_function_name"] = (
-                    self.dynamic_traits_function_name
-                )
+                raw_data[
+                    "dynamic_traits_function_name"
+                ] = self.dynamic_traits_function_name
         if hasattr(self, "answer_question_directly"):
             raw_data.pop(
                 "answer_question_directly", None
             )  # in case answer_question_directly will appear with _ in self.__dict__
             answer_question_directly_func = self.answer_question_directly
-            # print(answer_question_directly_func)
-            # print(type(answer_question_directly_func), flush=True)
 
             if (
                 answer_question_directly_func
@@ -632,9 +685,9 @@ class Agent(Base):
                 raw_data["answer_question_directly_source_code"] = inspect.getsource(
                     answer_question_directly_func
                 )
-                raw_data["answer_question_directly_function_name"] = (
-                    self.answer_question_directly_function_name
-                )
+                raw_data[
+                    "answer_question_directly_function_name"
+                ] = self.answer_question_directly_function_name
 
         return raw_data
 
@@ -644,12 +697,12 @@ class Agent(Base):
         return dict_hash(self._to_dict())
 
     def _to_dict(self) -> dict[str, Union[dict, bool]]:
-        """Serialize to a dictionary."""
+        """Serialize to a dictionary without EDSL info"""
         return self.data
 
     @add_edsl_version
     def to_dict(self) -> dict[str, Union[dict, bool]]:
-        """Serialize to a dictionary.
+        """Serialize to a dictionary with EDSL info.
 
         Example usage:
 
@@ -672,10 +725,6 @@ class Agent(Base):
         """
         return cls(**agent_dict)
 
-    ################
-    # DISPLAY Methods
-    ################
-
     def _table(self) -> tuple[dict, list]:
         """Prepare generic table data."""
         table_data = []
@@ -691,14 +740,16 @@ class Agent(Base):
             return self
 
         if isinstance(trait_name_or_dict, dict) and value:
-            raise ValueError(f"You passed a dict: {trait_name_or_dict}")
+            raise AgentErrors(
+                f"You passed a dict: {trait_name_or_dict} and a value: {value}. You should pass only a dict."
+            )
 
         if isinstance(trait_name_or_dict, str):
             trait = trait_name_or_dict
             self.traits[trait] = value
             return self
 
-        raise Exception("Something is not right with adding")
+        raise AgentErrors("Something is not right with adding a trait to an Agent")
 
     def remove_trait(self, trait: str) -> Agent:
         """Remove a trait from the agent.

{edsl-0.1.36.dev5 → edsl-0.1.37}/edsl/agents/AgentList.py

@@ -125,7 +125,7 @@ class AgentList(UserList, Base):
         return list(d.keys())
 
     @classmethod
-    def from_csv(cls, file_path: str):
+    def from_csv(cls, file_path: str, name_field: Optional[str] = None):
         """Load AgentList from a CSV file.
 
         >>> import csv
@@ -137,9 +137,13 @@ class AgentList(UserList, Base):
         >>> al = AgentList.from_csv('/tmp/agents.csv')
         >>> al
         AgentList([Agent(traits = {'age': '22', 'hair': 'brown', 'height': '5.5'})])
+        >>> al = AgentList.from_csv('/tmp/agents.csv', name_field='hair')
+        >>> al
+        AgentList([Agent(name = \"""brown\""", traits = {'age': '22', 'height': '5.5'})])
         >>> os.remove('/tmp/agents.csv')
 
         :param file_path: The path to the CSV file.
+        :param name_field: The name of the field to use as the agent name.
         """
         from edsl.agents.Agent import Agent
 
@@ -147,7 +151,16 @@ class AgentList(UserList, Base):
         with open(file_path, "r") as f:
             reader = csv.DictReader(f)
             for row in reader:
-                agent_list.append(Agent(row))
+                if "name" in row:
+                    import warnings
+
+                    warnings.warn("Using 'name' field in the CSV for the Agent name")
+                    name_field = "name"
+                if name_field is not None:
+                    agent_name = row.pop(name_field)
+                    agent_list.append(Agent(traits=row, name=agent_name))
+                else:
+                    agent_list.append(Agent(traits=row))
         return cls(agent_list)
 
     def translate_traits(self, values_codebook: dict[str, str]):

{edsl-0.1.36.dev5 → edsl-0.1.37}/edsl/agents/InvigilatorBase.py

@@ -16,6 +16,8 @@ from edsl.language_models.LanguageModel import LanguageModel
 from edsl.data_transfer_models import EDSLResultObjectInput
 from edsl.agents.PromptConstructor import PromptConstructor
 
+from edsl.agents.prompt_helpers import PromptPlan
+
 
 class InvigilatorBase(ABC):
     """An invigiator (someone who administers an exam) is a class that is responsible for administering a question to an agent.
@@ -45,6 +47,7 @@ class InvigilatorBase(ABC):
         additional_prompt_data: Optional[dict] = None,
         sidecar_model: Optional[LanguageModel] = None,
         raise_validation_errors: Optional[bool] = True,
+        prompt_plan: Optional["PromptPlan"] = None,
     ):
         """Initialize a new Invigilator."""
         self.agent = agent
@@ -59,6 +62,10 @@ class InvigilatorBase(ABC):
         self.sidecar_model = sidecar_model
         self.survey = survey
         self.raise_validation_errors = raise_validation_errors
+        if prompt_plan is None:
+            self.prompt_plan = PromptPlan()
+        else:
+            self.prompt_plan = prompt_plan
 
         self.raw_model_response = (
             None  # placeholder for the raw response from the model
@@ -67,7 +74,7 @@ class InvigilatorBase(ABC):
     @property
     def prompt_constructor(self) -> PromptConstructor:
         """Return the prompt constructor."""
-        return PromptConstructor(self)
+        return PromptConstructor(self, prompt_plan=self.prompt_plan)
 
     def to_dict(self):
         attributes = [
@@ -115,7 +122,11 @@ class InvigilatorBase(ABC):
         iteration = data["iteration"]
         additional_prompt_data = data["additional_prompt_data"]
         cache = Cache.from_dict(data["cache"])
-        sidecar_model = LanguageModel.from_dict(data["sidecar_model"])
+
+        if data["sidecar_model"] is None:
+            sidecar_model = None
+        else:
+            sidecar_model = LanguageModel.from_dict(data["sidecar_model"])
 
         return cls(
             agent=agent,
@@ -225,24 +236,6 @@ class InvigilatorBase(ABC):
         from edsl import Model
 
         model = Model("test", canned_response="SPAM!")
-        # class TestLanguageModelGood(LanguageModel):
-        #     """A test language model."""
-
-        #     _model_ = "test"
-        #     _parameters_ = {"temperature": 0.5}
-        #     _inference_service_ = InferenceServiceType.TEST.value
-
-        #     async def async_execute_model_call(
-        #         self, user_prompt: str, system_prompt: str
-        #     ) -> dict[str, Any]:
-        #         await asyncio.sleep(0.1)
-        #         if hasattr(self, "throw_an_exception"):
-        #             raise Exception("Error!")
-        #         return {"message": """{"answer": "SPAM!"}"""}
-
-        #     def parse_response(self, raw_response: dict[str, Any]) -> str:
-        #         """Parse the response from the model."""
-        #         return raw_response["message"]
 
         if throw_an_exception:
             model.throw_an_exception = True
@@ -252,11 +245,8 @@ class InvigilatorBase(ABC):
 
         if not survey:
             survey = Survey.example()
-        # if question:
-        # need to have the focal question name in the list of names
-        # survey._questions[0].question_name = question.question_name
-        #    survey.add_question(question)
-        if question:
+
+        if question not in survey.questions and question is not None:
             survey.add_question(question)
 
         question = question or survey.questions[0]