edsl 0.1.37.dev4__tar.gz → 0.1.37.dev6__tar.gz

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/PKG-INFO

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

edsl-0.1.37.dev6/edsl/__version__.py

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

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/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")
@@ -622,8 +677,6 @@ class Agent(Base):
                 "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
@@ -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.37.dev4 → edsl-0.1.37.dev6}/edsl/agents/AgentList.py

@@ -151,6 +151,11 @@ class AgentList(UserList, Base):
         with open(file_path, "r") as f:
             reader = csv.DictReader(f)
             for row in reader:
+                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))

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/edsl/agents/InvigilatorBase.py

@@ -236,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
@@ -263,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]

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/edsl/agents/PromptConstructor.py

@@ -7,6 +7,23 @@ from edsl.prompts.Prompt import Prompt
 from edsl.agents.prompt_helpers import PromptPlan
 
 
+class PlaceholderAnswer:
+    """A placeholder answer for when a question is not yet answered."""
+
+    def __init__(self):
+        self.answer = "N/A"
+        self.comment = "Will be populated by prior answer"
+
+    def __getitem__(self, index):
+        return ""
+
+    def __str__(self):
+        return "<<PlaceholderAnswer>>"
+
+    def __repr__(self):
+        return "<<PlaceholderAnswer>>"
+
+
 def get_jinja2_variables(template_str: str) -> Set[str]:
     """
     Extracts all variable names from a Jinja2 template using Jinja2's built-in parsing.
@@ -88,15 +105,20 @@ class PromptConstructor:
         return self.agent.prompt()
 
     def prior_answers_dict(self) -> dict:
+        # this is all questions
         d = self.survey.question_names_to_questions()
         # This attaches the answer to the question
-        for question, answer in self.current_answers.items():
-            if question in d:
-                d[question].answer = answer
+        for question in d:
+            if question in self.current_answers:
+                d[question].answer = self.current_answers[question]
             else:
-                # adds a comment to the question
-                if (new_question := question.split("_comment")[0]) in d:
-                    d[new_question].comment = answer
+                d[question].answer = PlaceholderAnswer()
+
+                # if (new_question := question.split("_comment")[0]) in d:
+                #     d[new_question].comment = answer
+                # d[question].answer = PlaceholderAnswer()
+
+        # breakpoint()
         return d
 
     @property
@@ -109,6 +131,123 @@ class PromptConstructor:
                 question_file_keys.append(var)
         return question_file_keys
 
+    def build_replacement_dict(self, question_data: dict):
+        """
+        Builds a dictionary of replacement values by combining multiple data sources.
+        """
+        # File references dictionary
+        file_refs = {key: f"<see file {key}>" for key in self.scenario_file_keys}
+
+        # Scenario items excluding file keys
+        scenario_items = {
+            k: v for k, v in self.scenario.items() if k not in self.scenario_file_keys
+        }
+
+        # Question settings with defaults
+        question_settings = {
+            "use_code": getattr(self.question, "_use_code", True),
+            "include_comment": getattr(self.question, "_include_comment", False),
+        }
+
+        # Combine all dictionaries using dict.update() for clarity
+        replacement_dict = {}
+        for d in [
+            file_refs,
+            question_data,
+            scenario_items,
+            self.prior_answers_dict(),
+            {"agent": self.agent},
+            question_settings,
+        ]:
+            replacement_dict.update(d)
+
+        return replacement_dict
+
+    def _get_question_options(self, question_data):
+        question_options_entry = question_data.get("question_options", None)
+        question_options = question_options_entry
+
+        placeholder = ["<< Option 1 - Placholder >>", "<< Option 2 - Placholder >>"]
+
+        if isinstance(question_options_entry, str):
+            env = Environment()
+            parsed_content = env.parse(question_options_entry)
+            question_option_key = list(meta.find_undeclared_variables(parsed_content))[
+                0
+            ]
+            if isinstance(self.scenario.get(question_option_key), list):
+                question_options = self.scenario.get(question_option_key)
+
+            # might be getting it from the prior answers
+            if self.prior_answers_dict().get(question_option_key) is not None:
+                prior_question = self.prior_answers_dict().get(question_option_key)
+                if hasattr(prior_question, "answer"):
+                    if isinstance(prior_question.answer, list):
+                        question_options = prior_question.answer
+                    else:
+                        question_options = placeholder
+                else:
+                    question_options = placeholder
+
+        return question_options
+
+    def build_question_instructions_prompt(self):
+        """Buils the question instructions prompt."""
+
+        question_prompt = Prompt(self.question.get_instructions(model=self.model.model))
+
+        # Get the data for the question - this is a dictionary of the question data
+        # e.g., {'question_text': 'Do you like school?', 'question_name': 'q0', 'question_options': ['yes', 'no']}
+        question_data = self.question.data.copy()
+
+        if "question_options" in question_data:
+            question_options = self._get_question_options(question_data)
+            question_data["question_options"] = question_options
+
+        # check to see if the question_options is actually a string
+        # This is used when the user is using the question_options as a variable from a scenario
+        # if "question_options" in question_data:
+        replacement_dict = self.build_replacement_dict(question_data)
+        rendered_instructions = question_prompt.render(replacement_dict)
+
+        # is there anything left to render?
+        undefined_template_variables = (
+            rendered_instructions.undefined_template_variables({})
+        )
+
+        # Check if it's the name of a question in the survey
+        for question_name in self.survey.question_names:
+            if question_name in undefined_template_variables:
+                print(
+                    "Question name found in undefined_template_variables: ",
+                    question_name,
+                )
+
+        if undefined_template_variables:
+            msg = f"Question instructions still has variables: {undefined_template_variables}."
+            import warnings
+
+            warnings.warn(msg)
+            # raise QuestionScenarioRenderError(
+            #     f"Question instructions still has variables: {undefined_template_variables}."
+            # )
+
+        # Check if question has instructions - these are instructions in a Survey that can apply to multiple follow-on questions
+        relevant_instructions = self.survey.relevant_instructions(
+            self.question.question_name
+        )
+
+        if relevant_instructions != []:
+            # preamble_text = Prompt(
+            #    text="You were given the following instructions: "
+            # )
+            preamble_text = Prompt(text="")
+            for instruction in relevant_instructions:
+                preamble_text += instruction.text
+            rendered_instructions = preamble_text + rendered_instructions
+
+        return rendered_instructions
+
     @property
     def question_instructions_prompt(self) -> Prompt:
         """
@@ -118,109 +257,11 @@ class PromptConstructor:
         Prompt(text=\"""...
         ...
         """
-        # The user might have passed a custom prompt, which would be stored in _question_instructions_prompt
         if not hasattr(self, "_question_instructions_prompt"):
-            # Gets the instructions for the question - this is how the question should be answered
-            question_prompt = Prompt(
-                self.question.get_instructions(model=self.model.model)
+            self._question_instructions_prompt = (
+                self.build_question_instructions_prompt()
             )
 
-            # Get the data for the question - this is a dictionary of the question data
-            # e.g., {'question_text': 'Do you like school?', 'question_name': 'q0', 'question_options': ['yes', 'no']}
-            question_data = self.question.data.copy()
-
-            # check to see if the question_options is actually a string
-            # This is used when the user is using the question_options as a variable from a scenario
-            # if "question_options" in question_data:
-            if isinstance(self.question.data.get("question_options", None), str):
-                env = Environment()
-                parsed_content = env.parse(self.question.data["question_options"])
-                question_option_key = list(
-                    meta.find_undeclared_variables(parsed_content)
-                )[0]
-
-                # look to see if the question_option_key is in the scenario
-                if isinstance(
-                    question_options := self.scenario.get(question_option_key), list
-                ):
-                    question_data["question_options"] = question_options
-                    self.question.question_options = question_options
-
-                # might be getting it from the prior answers
-                if self.prior_answers_dict().get(question_option_key) is not None:
-                    prior_question = self.prior_answers_dict().get(question_option_key)
-                    if hasattr(prior_question, "answer"):
-                        if isinstance(prior_question.answer, list):
-                            question_data["question_options"] = prior_question.answer
-                            self.question.question_options = prior_question.answer
-                    else:
-                        placeholder_options = [
-                            "N/A",
-                            "Will be populated by prior answer",
-                            "These are placeholder options",
-                        ]
-                        question_data["question_options"] = placeholder_options
-                        self.question.question_options = placeholder_options
-
-            replacement_dict = (
-                {key: f"<see file {key}>" for key in self.scenario_file_keys}
-                | question_data
-                | {
-                    k: v
-                    for k, v in self.scenario.items()
-                    if k not in self.scenario_file_keys
-                }  # don't include images in the replacement dict
-                | self.prior_answers_dict()
-                | {"agent": self.agent}
-                | {
-                    "use_code": getattr(self.question, "_use_code", True),
-                    "include_comment": getattr(
-                        self.question, "_include_comment", False
-                    ),
-                }
-            )
-
-            rendered_instructions = question_prompt.render(replacement_dict)
-
-            # is there anything left to render?
-            undefined_template_variables = (
-                rendered_instructions.undefined_template_variables({})
-            )
-
-            # Check if it's the name of a question in the survey
-            for question_name in self.survey.question_names:
-                if question_name in undefined_template_variables:
-                    print(
-                        "Question name found in undefined_template_variables: ",
-                        question_name,
-                    )
-
-            if undefined_template_variables:
-                msg = f"Question instructions still has variables: {undefined_template_variables}."
-                import warnings
-
-                warnings.warn(msg)
-                # raise QuestionScenarioRenderError(
-                #     f"Question instructions still has variables: {undefined_template_variables}."
-                # )
-
-            ####################################
-            # Check if question has instructions - these are instructions in a Survey that can apply to multiple follow-on questions
-            ####################################
-            relevant_instructions = self.survey.relevant_instructions(
-                self.question.question_name
-            )
-
-            if relevant_instructions != []:
-                # preamble_text = Prompt(
-                #    text="You were given the following instructions: "
-                # )
-                preamble_text = Prompt(text="")
-                for instruction in relevant_instructions:
-                    preamble_text += instruction.text
-                rendered_instructions = preamble_text + rendered_instructions
-
-            self._question_instructions_prompt = rendered_instructions
         return self._question_instructions_prompt
 
     @property

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/edsl/agents/descriptors.py

@@ -4,6 +4,20 @@ from typing import Dict
 from edsl.exceptions.agents import AgentNameError, AgentTraitKeyError
 
 
+def convert_agent_name(x):
+    # potentially a numpy int64
+    import numpy as np
+
+    if isinstance(x, np.int64):
+        return int(x)
+    elif x is None:
+        return None
+    elif isinstance(x, int):
+        return x
+    else:
+        return str(x)
+
+
 class NameDescriptor:
     """ABC for something."""
 
@@ -13,7 +27,7 @@ class NameDescriptor:
 
     def __set__(self, instance, name: str) -> None:
         """Set the value of the attribute."""
-        instance.__dict__[self.name] = name
+        instance.__dict__[self.name] = convert_agent_name(name)
 
     def __set_name__(self, owner, name: str) -> None:
         """Set the name of the attribute."""
@@ -34,9 +48,8 @@ class TraitsDescriptor:
         for key, value in traits_dict.items():
             if key == "name":
                 raise AgentNameError(
-                    """Trait keys cannot be 'name'. Instead, use the 'name' attribute directly e.g., 
-                    Agent(name="my_agent", traits={"trait1": "value1", "trait2": "value2"})
-                    """
+                    "Trait keys cannot be 'name'. Instead, use the 'name' attribute directly e.g.,\n"
+                    'Agent(name="my_agent", traits={"trait1": "value1", "trait2": "value2"})'
                 )
 
             if not is_valid_variable_name(key):

{edsl-0.1.37.dev4 → edsl-0.1.37.dev6}/edsl/config.py

@@ -58,7 +58,7 @@ CONFIG_MAP = {
         "info": "This config var holds the maximum number of tokens per minute for all models. Model-specific values provided in env vars such as EDSL_SERVICE_TPM_OPENAI will override this value for the corresponding model.",
     },
     "EXPECTED_PARROT_URL": {
-        "default": "https://www.expectedparrot.com",
+        "default": "https://api.expectedparrot.com",
         "info": "This config var holds the URL of the Expected Parrot API.",
     },
 }