edsl 0.1.33__py3-none-any.whl → 0.1.33.dev1__py3-none-any.whl

edsl/surveys/Survey.py

@@ -20,24 +20,6 @@ from edsl.surveys.SurveyExportMixin import SurveyExportMixin
 from edsl.surveys.SurveyFlowVisualizationMixin import SurveyFlowVisualizationMixin
 from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
 
-from edsl.agents.Agent import Agent
-
-
-class ValidatedString(str):
-    def __new__(cls, content):
-        if "<>" in content:
-            raise ValueError(
-                "The expression contains '<>', which is not allowed. You probably mean '!='."
-            )
-        return super().__new__(cls, content)
-
-
-# from edsl.surveys.Instruction import Instruction
-# from edsl.surveys.Instruction import ChangeInstruction
-from edsl.surveys.instructions.InstructionCollection import InstructionCollection
-from edsl.surveys.instructions.Instruction import Instruction
-from edsl.surveys.instructions.ChangeInstruction import ChangeInstruction
-
 
 class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     """A collection of questions that supports skip logic."""
@@ -60,13 +42,11 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
     def __init__(
         self,
-        questions: Optional[
-            list[Union[QuestionBase, Instruction, ChangeInstruction]]
-        ] = None,
+        questions: Optional[list[QuestionBase]] = None,
         memory_plan: Optional[MemoryPlan] = None,
         rule_collection: Optional[RuleCollection] = None,
         question_groups: Optional[dict[str, tuple[int, int]]] = None,
-        name: Optional[str] = None,
+        name: str = None,
     ):
         """Create a new survey.
 
@@ -76,33 +56,13 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         :param question_groups: The groups of questions in the survey.
         :param name: The name of the survey - DEPRECATED.
 
-
-        >>> from edsl import QuestionFreeText
-        >>> q1 = QuestionFreeText(question_text = "What is your name?", question_name = "name")
-        >>> q2 = QuestionFreeText(question_text = "What is your favorite color?", question_name = "color")
-        >>> q3 = QuestionFreeText(question_text = "Is a hot dog a sandwich", question_name = "food")
-        >>> s = Survey([q1, q2, q3], question_groups = {"demographics": (0, 1), "substantive":(3)})
-
-
         """
-
-        self.raw_passed_questions = questions
-
-        (
-            true_questions,
-            instruction_names_to_instructions,
-            self.pseudo_indices,
-        ) = self._separate_questions_and_instructions(questions or [])
-
         self.rule_collection = RuleCollection(
-            num_questions=len(true_questions) if true_questions else None
+            num_questions=len(questions) if questions else None
         )
         # the RuleCollection needs to be present while we add the questions; we might override this later
         # if a rule_collection is provided. This allows us to serialize the survey with the rule_collection.
-
-        self.questions = true_questions
-        self.instruction_names_to_instructions = instruction_names_to_instructions
-
+        self.questions = questions or []
         self.memory_plan = memory_plan or MemoryPlan(self)
         if question_groups is not None:
             self.question_groups = question_groups
@@ -118,177 +78,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
             warnings.warn("name parameter to a survey is deprecated.")
 
-    # region: Suvry instruction handling
-    @property
-    def relevant_instructions_dict(self) -> InstructionCollection:
-        """Return a dictionary with keys as question names and values as instructions that are relevant to the question.
-
-        >>> s = Survey.example(include_instructions=True)
-        >>> s.relevant_instructions_dict
-        {'q0': [Instruction(name="attention", text="Please pay attention!")], 'q1': [Instruction(name="attention", text="Please pay attention!")], 'q2': [Instruction(name="attention", text="Please pay attention!")]}
-
-        """
-        return InstructionCollection(
-            self.instruction_names_to_instructions, self.questions
-        )
-
-    @staticmethod
-    def _separate_questions_and_instructions(questions_and_instructions: list) -> tuple:
-        """
-        The 'pseudo_indices' attribute is a dictionary that maps question names to pseudo-indices
-        that are used to order questions and instructions in the survey.
-        Only questions get real indices; instructions get pseudo-indices.
-        However, the order of the pseudo-indices is the same as the order questions and instructions are added to the survey.
-
-        We don't have to know how many instructions there are to calculate the pseudo-indices because they are
-        calculated by the inverse of one minus the sum of 1/2^n for n in the number of instructions run so far.
-
-        >>> from edsl import Instruction
-        >>> i = Instruction(text = "Pay attention to the following questions.", name = "intro")
-        >>> i2 = Instruction(text = "How are you feeling today?", name = "followon_intro")
-        >>> from edsl import QuestionFreeText; q1 = QuestionFreeText.example()
-        >>> from edsl import QuestionMultipleChoice; q2 = QuestionMultipleChoice.example()
-        >>> s = Survey([q1, i, i2, q2])
-        >>> len(s.instruction_names_to_instructions)
-        2
-        >>> s.pseudo_indices
-        {'how_are_you': 0, 'intro': 0.5, 'followon_intro': 0.75, 'how_feeling': 1}
-
-        >>> from edsl import ChangeInstruction
-        >>> q3 = QuestionFreeText(question_text = "What is your favorite color?", question_name = "color")
-        >>> i_change = ChangeInstruction(drop = ["intro"])
-        >>> s = Survey([q1, i, q2, i_change, q3])
-        >>> [i.name for i in s.relevant_instructions(q1)]
-        []
-        >>> [i.name for i in s.relevant_instructions(q2)]
-        ['intro']
-        >>> [i.name for i in s.relevant_instructions(q3)]
-        []
-
-        >>> i_change = ChangeInstruction(keep = ["poop"], drop = [])
-        >>> s = Survey([q1, i, q2, i_change])
-        Traceback (most recent call last):
-        ...
-        ValueError: ChangeInstruction change_instruction_0 references instruction poop which does not exist.
-        """
-        from edsl.surveys.instructions.Instruction import Instruction
-        from edsl.surveys.instructions.ChangeInstruction import ChangeInstruction
-
-        true_questions = []
-        instruction_names_to_instructions = {}
-
-        num_change_instructions = 0
-        pseudo_indices = {}
-        instructions_run_length = 0
-        for entry in questions_and_instructions:
-            if isinstance(entry, Instruction) or isinstance(entry, ChangeInstruction):
-                if isinstance(entry, ChangeInstruction):
-                    entry.add_name(num_change_instructions)
-                    num_change_instructions += 1
-                    for prior_instruction in entry.keep + entry.drop:
-                        if prior_instruction not in instruction_names_to_instructions:
-                            raise ValueError(
-                                f"ChangeInstruction {entry.name} references instruction {prior_instruction} which does not exist."
-                            )
-                instructions_run_length += 1
-                delta = 1 - 1.0 / (2.0**instructions_run_length)
-                pseudo_index = (len(true_questions) - 1) + delta
-                entry.pseudo_index = pseudo_index
-                instruction_names_to_instructions[entry.name] = entry
-            elif isinstance(entry, QuestionBase):
-                pseudo_index = len(true_questions)
-                instructions_run_length = 0
-                true_questions.append(entry)
-            else:
-                raise ValueError(
-                    f"Entry {repr(entry)} is not a QuestionBase or an Instruction."
-                )
-
-            pseudo_indices[entry.name] = pseudo_index
-
-        return true_questions, instruction_names_to_instructions, pseudo_indices
-
-    def relevant_instructions(self, question) -> dict:
-        """This should be a dictionry with keys as question names and values as instructions that are relevant to the question.
-
-        :param question: The question to get the relevant instructions for.
-
-        # Did the instruction come before the question and was it not modified by a change instruction?
-
-        """
-        return self.relevant_instructions_dict[question]
-
-    @property
-    def max_pseudo_index(self) -> float:
-        """Return the maximum pseudo index in the survey.
-
-        Example:
-
-        >>> s = Survey.example()
-        >>> s.max_pseudo_index
-        2
-        """
-        if len(self.pseudo_indices) == 0:
-            return -1
-        return max(self.pseudo_indices.values())
-
-    @property
-    def last_item_was_instruction(self) -> bool:
-        """Return whether the last item added to the survey was an instruction.
-        This is used to determine the pseudo-index of the next item added to the survey.
-
-        Example:
-
-        >>> s = Survey.example()
-        >>> s.last_item_was_instruction
-        False
-        >>> from edsl.surveys.instructions.Instruction import Instruction
-        >>> s = s.add_instruction(Instruction(text="Pay attention to the following questions.", name="intro"))
-        >>> s.last_item_was_instruction
-        True
-        """
-        return isinstance(self.max_pseudo_index, float)
-
-    def add_instruction(
-        self, instruction: Union["Instruction", "ChangeInstruction"]
-    ) -> Survey:
-        """
-        Add an instruction to the survey.
-
-        :param instruction: The instruction to add to the survey.
-
-        >>> from edsl import Instruction
-        >>> i = Instruction(text="Pay attention to the following questions.", name="intro")
-        >>> s = Survey().add_instruction(i)
-        >>> s.instruction_names_to_instructions
-        {'intro': Instruction(name="intro", text="Pay attention to the following questions.")}
-        >>> s.pseudo_indices
-        {'intro': -0.5}
-        """
-        import math
-
-        if instruction.name in self.instruction_names_to_instructions:
-            raise SurveyCreationError(
-                f"""Instruction name '{instruction.name}' already exists in survey. Existing names are {self.instruction_names_to_instructions.keys()}."""
-            )
-        self.instruction_names_to_instructions[instruction.name] = instruction
-
-        # was the last thing added an instruction or a question?
-        if self.last_item_was_instruction:
-            pseudo_index = (
-                self.max_pseudo_index
-                + (math.ceil(self.max_pseudo_index) - self.max_pseudo_index) / 2
-            )
-        else:
-            pseudo_index = self.max_pseudo_index + 1.0 / 2.0
-        self.pseudo_indices[instruction.name] = pseudo_index
-
-        return self
-
-    # endregion
-
-    # region: Simulation methods
-
     def simulate(self) -> dict:
         """Simulate the survey and return the answers."""
         i = self.gen_path_through_survey()
@@ -304,6 +93,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     def create_agent(self) -> "Agent":
         """Create an agent from the simulated answers."""
         answers_dict = self.simulate()
+        from edsl.agents.Agent import Agent
+
+        a = Agent(traits=answers_dict)
 
         def construct_answer_dict_function(traits: dict) -> Callable:
             def func(self, question: "QuestionBase", scenario=None):
@@ -311,48 +103,16 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
             return func
 
-        return Agent(traits=answers_dict).add_direct_question_answering_method(
+        a.add_direct_question_answering_method(
             construct_answer_dict_function(answers_dict)
         )
+        return a
 
     def simulate_results(self) -> "Results":
         """Simulate the survey and return the results."""
         a = self.create_agent()
         return self.by([a]).run()
 
-    # endregion
-
-    # region: Access methods
-    def _get_question_index(
-        self, q: Union[QuestionBase, str, EndOfSurvey.__class__]
-    ) -> Union[int, EndOfSurvey.__class__]:
-        """Return the index of the question or EndOfSurvey object.
-
-        :param q: The question or question name to get the index of.
-
-        It can handle it if the user passes in the question name, the question object, or the EndOfSurvey object.
-
-        >>> s = Survey.example()
-        >>> s._get_question_index("q0")
-        0
-
-        This doesnt' work with questions that don't exist:
-
-        >>> s._get_question_index("poop")
-        Traceback (most recent call last):
-        ...
-        ValueError: Question name poop not found in survey. The current question names are {'q0': 0, 'q1': 1, 'q2': 2}.
-        """
-        if q == EndOfSurvey:
-            return EndOfSurvey
-        else:
-            question_name = q if isinstance(q, str) else q.question_name
-            if question_name not in self.question_name_to_index:
-                raise ValueError(
-                    f"""Question name {question_name} not found in survey. The current question names are {self.question_name_to_index}."""
-                )
-            return self.question_name_to_index[question_name]
-
     def get(self, question_name: str) -> QuestionBase:
         """
         Return the question object given the question name.
@@ -368,184 +128,22 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         index = self.question_name_to_index[question_name]
         return self._questions[index]
 
+    def question_names_to_questions(self) -> dict:
+        """Return a dictionary mapping question names to question attributes."""
+        return {q.question_name: q for q in self.questions}
+
     def get_question(self, question_name: str) -> QuestionBase:
         """Return the question object given the question name."""
         # import warnings
         # warnings.warn("survey.get_question is deprecated. Use subscript operator instead.")
         return self.get(question_name)
 
-    def question_names_to_questions(self) -> dict:
-        """Return a dictionary mapping question names to question attributes."""
-        return {q.question_name: q for q in self.questions}
-
-    @property
-    def question_names(self) -> list[str]:
-        """Return a list of question names in the survey.
-
-        Example:
-
-        >>> s = Survey.example()
-        >>> s.question_names
-        ['q0', 'q1', 'q2']
-        """
-        # return list(self.question_name_to_index.keys())
-        return [q.question_name for q in self.questions]
-
-    @property
-    def question_name_to_index(self) -> dict[str, int]:
-        """Return a dictionary mapping question names to question indices.
-
-        Example:
-
-        >>> s = Survey.example()
-        >>> s.question_name_to_index
-        {'q0': 0, 'q1': 1, 'q2': 2}
-        """
-        return {q.question_name: i for i, q in enumerate(self.questions)}
-
-    # endregion
-
-    # region: serialization methods
     def __hash__(self) -> int:
         """Return a hash of the question."""
         from edsl.utilities.utilities import dict_hash
 
         return dict_hash(self._to_dict())
 
-    def _to_dict(self) -> dict[str, Any]:
-        """Serialize the Survey object to a dictionary.
-
-        >>> s = Survey.example()
-        >>> s._to_dict().keys()
-        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups'])
-        """
-        return {
-            "questions": [
-                q._to_dict() for q in self.recombined_questions_and_instructions()
-            ],
-            "memory_plan": self.memory_plan.to_dict(),
-            "rule_collection": self.rule_collection.to_dict(),
-            "question_groups": self.question_groups,
-        }
-
-    @add_edsl_version
-    def to_dict(self) -> dict[str, Any]:
-        """Serialize the Survey object to a dictionary.
-
-        >>> s = Survey.example()
-        >>> s.to_dict().keys()
-        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
-
-        """
-        return self._to_dict()
-
-    @classmethod
-    @remove_edsl_version
-    def from_dict(cls, data: dict) -> Survey:
-        """Deserialize the dictionary back to a Survey object.
-
-        :param data: The dictionary to deserialize.
-
-        >>> d = Survey.example().to_dict()
-        >>> s = Survey.from_dict(d)
-        >>> s == Survey.example()
-        True
-
-        >>> s = Survey.example(include_instructions = True)
-        >>> d = s.to_dict()
-        >>> news = Survey.from_dict(d)
-        >>> news == s
-        True
-
-        """
-
-        def get_class(pass_dict):
-            if (class_name := pass_dict.get("edsl_class_name")) == "QuestionBase":
-                return QuestionBase
-            elif class_name == "Instruction":
-                from edsl.surveys.instructions.Instruction import Instruction
-
-                return Instruction
-            elif class_name == "ChangeInstruction":
-                from edsl.surveys.instructions.ChangeInstruction import (
-                    ChangeInstruction,
-                )
-
-                return ChangeInstruction
-            else:
-                # some data might not have the edsl_class_name
-                return QuestionBase
-                # raise ValueError(f"Class {pass_dict['edsl_class_name']} not found")
-
-        questions = [
-            get_class(q_dict).from_dict(q_dict) for q_dict in data["questions"]
-        ]
-        memory_plan = MemoryPlan.from_dict(data["memory_plan"])
-        survey = cls(
-            questions=questions,
-            memory_plan=memory_plan,
-            rule_collection=RuleCollection.from_dict(data["rule_collection"]),
-            question_groups=data["question_groups"],
-        )
-        return survey
-
-    # endregion
-
-    # region: Survey template parameters
-    @property
-    def scenario_attributes(self) -> list[str]:
-        """Return a list of attributes that admissible Scenarios should have.
-
-        Here we have a survey with a question that uses a jinja2 style {{ }} template:
-
-        >>> from edsl import QuestionFreeText
-        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your name?", question_name="name"))
-        >>> s.scenario_attributes
-        ['greeting']
-
-        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your {{ attribute }}?", question_name="name"))
-        >>> s.scenario_attributes
-        ['greeting', 'attribute']
-
-
-        """
-        temp = []
-        for question in self.questions:
-            question_text = question.question_text
-            # extract the contents of all {{ }} in the question text using regex
-            matches = re.findall(r"\{\{(.+?)\}\}", question_text)
-            # remove whitespace
-            matches = [match.strip() for match in matches]
-            # add them to the temp list
-            temp.extend(matches)
-        return temp
-
-    @property
-    def parameters(self):
-        """Return a set of parameters in the survey.
-
-        >>> s = Survey.example()
-        >>> s.parameters
-        set()
-        """
-        return set.union(*[q.parameters for q in self.questions])
-
-    @property
-    def parameters_by_question(self):
-        """Return a dictionary of parameters by question in the survey.
-        >>> from edsl import QuestionFreeText
-        >>> q = QuestionFreeText(question_name = "example", question_text = "What is the capital of {{ country}}?")
-        >>> s = Survey([q])
-        >>> s.parameters_by_question
-        {'example': {'country'}}
-        """
-        return {q.question_name: q.parameters for q in self.questions}
-
-    # endregion
-
-    # region: Survey construction
-
-    # region: Adding questions and combining surveys
     def __add__(self, other: Survey) -> Survey:
         """Combine two surveys.
 
@@ -573,6 +171,51 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return Survey(questions=self.questions + other.questions)
 
+    def clear_non_default_rules(self) -> Survey:
+        s = Survey()
+        for question in self.questions:
+            s.add_question(question)
+        return s
+
+    @property
+    def parameters(self):
+        """Return a set of parameters in the survey.
+
+        >>> s = Survey.example()
+        >>> s.parameters
+        set()
+        """
+        return set.union(*[q.parameters for q in self.questions])
+
+    @property
+    def parameters_by_question(self):
+        return {q.question_name: q.parameters for q in self.questions}
+
+    @property
+    def question_names(self) -> list[str]:
+        """Return a list of question names in the survey.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.question_names
+        ['q0', 'q1', 'q2']
+        """
+        # return list(self.question_name_to_index.keys())
+        return [q.question_name for q in self.questions]
+
+    @property
+    def question_name_to_index(self) -> dict[str, int]:
+        """Return a dictionary mapping question names to question indices.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.question_name_to_index
+        {'q0': 0, 'q1': 1, 'q2': 2}
+        """
+        return {q.question_name: i for i, q in enumerate(self.questions)}
+
     def add_question(self, question: QuestionBase) -> Survey:
         """
         Add a question to survey.
@@ -590,11 +233,11 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         >>> s = Survey().add_question(q).add_question(q)
         Traceback (most recent call last):
         ...
-        edsl.exceptions.surveys.SurveyCreationError: Question name 'q0' already exists in survey. Existing names are ['q0'].
+        edsl.exceptions.surveys.SurveyCreationError: Question name already exists in survey. ...
         """
         if question.question_name in self.question_names:
             raise SurveyCreationError(
-                f"""Question name '{question.question_name}' already exists in survey. Existing names are {self.question_names}."""
+                f"""Question name already exists in survey. Please use a different name for the offensing question. The problemetic question name is {question.question_name}."""
             )
         index = len(self.questions)
         # TODO: This is a bit ugly because the user
@@ -602,8 +245,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         # descriptor.
         self._questions.append(question)
 
-        self.pseudo_indices[question.question_name] = index
-
         # using index + 1 presumes there is a next question
         self.rule_collection.add_rule(
             Rule(
@@ -622,20 +263,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self
 
-    def recombined_questions_and_instructions(
-        self,
-    ) -> list[Union[QuestionBase, "Instruction"]]:
-        """Return a list of questions and instructions sorted by pseudo index."""
-        questions_and_instructions = self._questions + list(
-            self.instruction_names_to_instructions.values()
-        )
-        return sorted(
-            questions_and_instructions, key=lambda x: self.pseudo_indices[x.name]
-        )
-
-    # endregion
-
-    # region: Memory plan methods
     def set_full_memory_mode(self) -> Survey:
         """Add instructions to a survey that the agent should remember all of the answers to the questions in the survey.
 
@@ -668,75 +295,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
                 prior_questions=prior_questions_func(i),
             )
 
-    def add_targeted_memory(
-        self,
-        focal_question: Union[QuestionBase, str],
-        prior_question: Union[QuestionBase, str],
-    ) -> Survey:
-        """Add instructions to a survey than when answering focal_question.
-
-        :param focal_question: The question that the agent is answering.
-        :param prior_question: The question that the agent should remember when answering the focal question.
-
-        Here we add instructions to a survey than when answering q2 they should remember q1:
-
-        >>> s = Survey.example().add_targeted_memory("q2", "q0")
-        >>> s.memory_plan
-        {'q2': Memory(prior_questions=['q0'])}
-
-        The agent should also remember the answers to prior_questions listed in prior_questions.
-        """
-        focal_question_name = self.question_names[
-            self._get_question_index(focal_question)
-        ]
-        prior_question_name = self.question_names[
-            self._get_question_index(prior_question)
-        ]
-
-        self.memory_plan.add_single_memory(
-            focal_question=focal_question_name,
-            prior_question=prior_question_name,
-        )
-
-        return self
-
-    def add_memory_collection(
-        self,
-        focal_question: Union[QuestionBase, str],
-        prior_questions: List[Union[QuestionBase, str]],
-    ) -> Survey:
-        """Add prior questions and responses so the agent has them when answering.
-
-        This adds instructions to a survey than when answering focal_question, the agent should also remember the answers to prior_questions listed in prior_questions.
-
-        :param focal_question: The question that the agent is answering.
-        :param prior_questions: The questions that the agent should remember when answering the focal question.
-
-        Here we have it so that when answering q2, the agent should remember answers to q0 and q1:
-
-        >>> s = Survey.example().add_memory_collection("q2", ["q0", "q1"])
-        >>> s.memory_plan
-        {'q2': Memory(prior_questions=['q0', 'q1'])}
-        """
-        focal_question_name = self.question_names[
-            self._get_question_index(focal_question)
-        ]
-
-        prior_question_names = [
-            self.question_names[self._get_question_index(prior_question)]
-            for prior_question in prior_questions
-        ]
-
-        self.memory_plan.add_memory_collection(
-            focal_question=focal_question_name, prior_questions=prior_question_names
-        )
-        return self
-
-    # endregion
-    # endregion
-    # endregion
-
-    # region: Question groups
     def add_question_group(
         self,
         start_question: Union[QuestionBase, str],
@@ -814,24 +372,69 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         self.question_groups[group_name] = (start_index, end_index)
         return self
 
-    # endregion
+    def add_targeted_memory(
+        self,
+        focal_question: Union[QuestionBase, str],
+        prior_question: Union[QuestionBase, str],
+    ) -> Survey:
+        """Add instructions to a survey than when answering focal_question.
+
+        :param focal_question: The question that the agent is answering.
+        :param prior_question: The question that the agent should remember when answering the focal question.
+
+        Here we add instructions to a survey than when answering q2 they should remember q1:
+
+        >>> s = Survey.example().add_targeted_memory("q2", "q0")
+        >>> s.memory_plan
+        {'q2': Memory(prior_questions=['q0'])}
+
+        The agent should also remember the answers to prior_questions listed in prior_questions.
+        """
+        focal_question_name = self.question_names[
+            self._get_question_index(focal_question)
+        ]
+        prior_question_name = self.question_names[
+            self._get_question_index(prior_question)
+        ]
+
+        self.memory_plan.add_single_memory(
+            focal_question=focal_question_name,
+            prior_question=prior_question_name,
+        )
+
+        return self
+
+    def add_memory_collection(
+        self,
+        focal_question: Union[QuestionBase, str],
+        prior_questions: List[Union[QuestionBase, str]],
+    ) -> Survey:
+        """Add prior questions and responses so the agent has them when answering.
 
-    # region: Survey rules
-    def show_rules(self) -> None:
-        """Print out the rules in the survey.
+        This adds instructions to a survey than when answering focal_question, the agent should also remember the answers to prior_questions listed in prior_questions.
 
-        >>> s = Survey.example()
-        >>> s.show_rules()
-        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
-        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-        │ 0         │ True        │ 1      │ -1       │ False       │
-        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
-        │ 1         │ True        │ 2      │ -1       │ False       │
-        │ 2         │ True        │ 3      │ -1       │ False       │
-        └───────────┴─────────────┴────────┴──────────┴─────────────┘
+        :param focal_question: The question that the agent is answering.
+        :param prior_questions: The questions that the agent should remember when answering the focal question.
+
+        Here we have it so that when answering q2, the agent should remember answers to q0 and q1:
+
+        >>> s = Survey.example().add_memory_collection("q2", ["q0", "q1"])
+        >>> s.memory_plan
+        {'q2': Memory(prior_questions=['q0', 'q1'])}
         """
-        self.rule_collection.show_rules()
+        focal_question_name = self.question_names[
+            self._get_question_index(focal_question)
+        ]
+
+        prior_question_names = [
+            self.question_names[self._get_question_index(prior_question)]
+            for prior_question in prior_questions
+        ]
+
+        self.memory_plan.add_memory_collection(
+            focal_question=focal_question_name, prior_questions=prior_question_names
+        )
+        return self
 
     def add_stop_rule(
         self, question: Union[QuestionBase, str], expression: str
@@ -841,7 +444,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         :param question: The question to add the stop rule to.
         :param expression: The expression to evaluate.
 
-        If this rule is true, the survey ends.
         The rule is evaluated *after* the question is answered. If the rule is true, the survey ends.
 
         Here, answering "yes" to q0 ends the survey:
@@ -854,42 +456,10 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> s.next_question("q0", {"q0": "no"}).question_name
         'q1'
-
-        >>> s.add_stop_rule("q0", "q1 <> 'yes'")
-        Traceback (most recent call last):
-        ...
-        ValueError: The expression contains '<>', which is not allowed. You probably mean '!='.
         """
-        expression = ValidatedString(expression)
         self.add_rule(question, expression, EndOfSurvey)
         return self
 
-    def clear_non_default_rules(self) -> Survey:
-        """Remove all non-default rules from the survey.
-
-        >>> Survey.example().show_rules()
-        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
-        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-        │ 0         │ True        │ 1      │ -1       │ False       │
-        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
-        │ 1         │ True        │ 2      │ -1       │ False       │
-        │ 2         │ True        │ 3      │ -1       │ False       │
-        └───────────┴─────────────┴────────┴──────────┴─────────────┘
-        >>> Survey.example().clear_non_default_rules().show_rules()
-        ┏━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-        ┃ current_q ┃ expression ┃ next_q ┃ priority ┃ before_rule ┃
-        ┡━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-        │ 0         │ True       │ 1      │ -1       │ False       │
-        │ 1         │ True       │ 2      │ -1       │ False       │
-        │ 2         │ True       │ 3      │ -1       │ False       │
-        └───────────┴────────────┴────────┴──────────┴─────────────┘
-        """
-        s = Survey()
-        for question in self.questions:
-            s.add_question(question)
-        return s
-
     def add_skip_rule(
         self, question: Union[QuestionBase, str], expression: str
     ) -> Survey:
@@ -917,6 +487,36 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         self._add_rule(question, expression, question_index + 1, before_rule=True)
         return self
 
+    def _get_question_index(
+        self, q: Union[QuestionBase, str, EndOfSurvey.__class__]
+    ) -> Union[int, EndOfSurvey.__class__]:
+        """Return the index of the question or EndOfSurvey object.
+
+        :param q: The question or question name to get the index of.
+
+        It can handle it if the user passes in the question name, the question object, or the EndOfSurvey object.
+
+        >>> s = Survey.example()
+        >>> s._get_question_index("q0")
+        0
+
+        This doesnt' work with questions that don't exist:
+
+        >>> s._get_question_index("poop")
+        Traceback (most recent call last):
+        ...
+        ValueError: Question name poop not found in survey. The current question names are {'q0': 0, 'q1': 1, 'q2': 2}.
+        """
+        if q == EndOfSurvey:
+            return EndOfSurvey
+        else:
+            question_name = q if isinstance(q, str) else q.question_name
+            if question_name not in self.question_name_to_index:
+                raise ValueError(
+                    f"""Question name {question_name} not found in survey. The current question names are {self.question_name_to_index}."""
+                )
+            return self.question_name_to_index[question_name]
+
     def _get_new_rule_priority(
         self, question_index: int, before_rule: bool = False
     ) -> int:
@@ -1015,9 +615,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self
 
-    # endregion
-
-    # region: Forward methods
+    ###################
+    # FORWARD METHODS
+    ###################
     def by(self, *args: Union["Agent", "Scenario", "LanguageModel"]) -> "Jobs":
         """Add Agents, Scenarios, and LanguageModels to a survey and returns a runnable Jobs object.
 
@@ -1040,63 +640,34 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return Jobs(survey=self)
 
-    # endregion
-
-    # region: Running the survey
-
-    def __call__(self, model=None, agent=None, cache=None, **kwargs):
-        """Run the survey with default model, taking the required survey as arguments.
-
-        >>> from edsl.questions import QuestionFunctional
-        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
-        >>> q = QuestionFunctional(question_name = "q0", func = f)
-        >>> s = Survey([q])
-        >>> s(period = "morning", cache = False).select("answer.q0").first()
-        'yes'
-        >>> s(period = "evening", cache = False).select("answer.q0").first()
-        'no'
-        """
-        job = self.get_job(model, agent, **kwargs)
-        return job.run(cache=cache)
-
-    async def run_async(self, model=None, agent=None, cache=None, **kwargs):
-        """Run the survey with default model, taking the required survey as arguments.
-
-        >>> from edsl.questions import QuestionFunctional
-        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
-        >>> q = QuestionFunctional(question_name = "q0", func = f)
-        >>> s = Survey([q])
-        >>> s(period = "morning").select("answer.q0").first()
-        'yes'
-        >>> s(period = "evening").select("answer.q0").first()
-        'no'
-        """
-        # TODO: temp fix by creating a cache
-        if cache is None:
-            from edsl.data import Cache
-
-            c = Cache()
-        else:
-            c = cache
-        jobs: "Jobs" = self.get_job(model, agent, **kwargs)
-        return await jobs.run_async(cache=c)
-
     def run(self, *args, **kwargs) -> "Results":
         """Turn the survey into a Job and runs it.
 
+        Here we run a survey but with debug mode on (so LLM calls are not made)
+
         >>> from edsl import QuestionFreeText
         >>> s = Survey([QuestionFreeText.example()])
-        >>> from edsl.language_models import LanguageModel
-        >>> m = LanguageModel.example(test_model = True, canned_response = "Great!")
-        >>> results = s.by(m).run(cache = False)
-        >>> results.select('answer.*')
-        Dataset([{'answer.how_are_you': ['Great!']}])
+        >>> results = s.run(debug = True, cache = False)
+        >>> results.select('answer.*').print(format = "rich")
+        ┏━━━━━━━━━━━━━━┓
+        ┃ answer       ┃
+        ┃ .how_are_you ┃
+        ┡━━━━━━━━━━━━━━┩
+        ...
+        └──────────────┘
         """
         from edsl.jobs.Jobs import Jobs
 
         return Jobs(survey=self).run(*args, **kwargs)
 
-    # region: Survey flow
+    ########################
+    ## Survey-Taking Methods
+    ########################
+
+    def _first_question(self) -> QuestionBase:
+        """Return the first question in the survey."""
+        return self.questions[0]
+
     def next_question(
         self, current_question: Union[str, QuestionBase], answers: dict
     ) -> Union[QuestionBase, EndOfSurvey.__class__]:
@@ -1174,15 +745,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
         >>> i2.send({"q0": "no"})
         Question('multiple_choice', question_name = \"""q1\""", question_text = \"""Why not?\""", question_options = ['killer bees in cafeteria', 'other'])
-
-
         """
         self.answers = {}
-        question = self._questions[0]
-        # should the first question be skipped?
-        if self.rule_collection.skip_question_before_running(0, self.answers):
-            question = self.next_question(question, self.answers)
-
+        question = self._first_question()
         while not question == EndOfSurvey:
             # breakpoint()
             answer = yield question
@@ -1191,9 +756,34 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             ## TODO: This should also include survey and agent attributes
             question = self.next_question(question, self.answers)
 
-    # endregion
+    @property
+    def scenario_attributes(self) -> list[str]:
+        """Return a list of attributes that admissible Scenarios should have.
+
+        Here we have a survey with a question that uses a jinja2 style {{ }} template:
+
+        >>> from edsl import QuestionFreeText
+        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your name?", question_name="name"))
+        >>> s.scenario_attributes
+        ['greeting']
+
+        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your {{ attribute }}?", question_name="name"))
+        >>> s.scenario_attributes
+        ['greeting', 'attribute']
+
+
+        """
+        temp = []
+        for question in self.questions:
+            question_text = question.question_text
+            # extract the contents of all {{ }} in the question text using regex
+            matches = re.findall(r"\{\{(.+?)\}\}", question_text)
+            # remove whitespace
+            matches = [match.strip() for match in matches]
+            # add them to the temp list
+            temp.extend(matches)
+        return temp
 
-    # regions: DAG construction
     def textify(self, index_dag: DAG) -> DAG:
         """Convert the DAG of question indices to a DAG of question names.
 
@@ -1333,6 +923,59 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             return False
         return self.to_dict() == other.to_dict()
 
+    ###################
+    # SERIALIZATION METHODS
+    ###################
+
+    def _to_dict(self) -> dict[str, Any]:
+        """Serialize the Survey object to a dictionary.
+
+        >>> s = Survey.example()
+        >>> s._to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups'])
+
+        """
+        return {
+            "questions": [q._to_dict() for q in self._questions],
+            "memory_plan": self.memory_plan.to_dict(),
+            "rule_collection": self.rule_collection.to_dict(),
+            "question_groups": self.question_groups,
+        }
+
+    @add_edsl_version
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the Survey object to a dictionary.
+
+        >>> s = Survey.example()
+        >>> s.to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
+
+        """
+        return self._to_dict()
+
+    @classmethod
+    @remove_edsl_version
+    def from_dict(cls, data: dict) -> Survey:
+        """Deserialize the dictionary back to a Survey object.
+
+        :param data: The dictionary to deserialize.
+
+        >>> d = Survey.example().to_dict()
+        >>> s = Survey.from_dict(d)
+        >>> s == Survey.example()
+        True
+
+        """
+        questions = [QuestionBase.from_dict(q_dict) for q_dict in data["questions"]]
+        memory_plan = MemoryPlan.from_dict(data["memory_plan"])
+        survey = cls(
+            questions=questions,
+            memory_plan=memory_plan,
+            rule_collection=RuleCollection.from_dict(data["rule_collection"]),
+            question_groups=data["question_groups"],
+        )
+        return survey
+
     @classmethod
     def from_qsf(
         cls, qsf_file: Optional[str] = None, url: Optional[str] = None
@@ -1359,7 +1002,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         so = SurveyQualtricsImport(qsf_file)
         return so.create_survey()
 
-    # region: Display methods
+    ###################
+    # DISPLAY METHODS
+    ###################
     def print(self):
         """Print the survey in a rich format.
 
@@ -1378,8 +1023,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     def __repr__(self) -> str:
         """Return a string representation of the survey."""
 
-        # questions_string = ", ".join([repr(q) for q in self._questions])
-        questions_string = ", ".join([repr(q) for q in self.raw_passed_questions or []])
+        questions_string = ", ".join([repr(q) for q in self._questions])
         # question_names_string = ", ".join([repr(name) for name in self.question_names])
         return f"Survey(questions=[{questions_string}], memory_plan={self.memory_plan}, rule_collection={self.rule_collection}, question_groups={self.question_groups})"
 
@@ -1388,6 +1032,22 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return data_to_html(self.to_dict())
 
+    def show_rules(self) -> None:
+        """Print out the rules in the survey.
+
+        >>> s = Survey.example()
+        >>> s.show_rules()
+        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
+        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
+        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
+        │ 0         │ True        │ 1      │ -1       │ False       │
+        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
+        │ 1         │ True        │ 2      │ -1       │ False       │
+        │ 2         │ True        │ 3      │ -1       │ False       │
+        └───────────┴─────────────┴────────┴──────────┴─────────────┘
+        """
+        self.rule_collection.show_rules()
+
     def rich_print(self) -> Table:
         """Print the survey in a rich format.
 
@@ -1423,8 +1083,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return table
 
-    # endregion
-
     def codebook(self) -> dict[str, str]:
         """Create a codebook for the survey, mapping question names to question text.
 
@@ -1437,7 +1095,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             codebook[question.question_name] = question.question_text
         return codebook
 
-    # region: Export methods
     def to_csv(self, filename: str = None):
         """Export the survey to a CSV file.
 
@@ -1480,16 +1137,8 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         res = c.web(self.to_dict(), platform, email)
         return res
 
-    # endregion
-
     @classmethod
-    def example(
-        cls,
-        params: bool = False,
-        randomize: bool = False,
-        include_instructions=False,
-        custom_instructions: Optional[str] = None,
-    ) -> Survey:
+    def example(cls, params: bool = False, randomize: bool = False) -> Survey:
         """Return an example survey.
 
         >>> s = Survey.example()
@@ -1522,18 +1171,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             )
             s = cls(questions=[q0, q1, q2, q3])
             return s
-
-        if include_instructions:
-            from edsl import Instruction
-
-            custom_instructions = (
-                custom_instructions if custom_instructions else "Please pay attention!"
-            )
-
-            i = Instruction(text=custom_instructions, name="attention")
-            s = cls(questions=[i, q0, q1, q2])
-            return s
-
         s = cls(questions=[q0, q1, q2])
         s = s.add_rule(q0, "q0 == 'yes'", q2)
         return s
@@ -1555,6 +1192,43 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self.by(s).by(agent).by(model)
 
+    def __call__(self, model=None, agent=None, cache=None, **kwargs):
+        """Run the survey with default model, taking the required survey as arguments.
+
+        >>> from edsl.questions import QuestionFunctional
+        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
+        >>> q = QuestionFunctional(question_name = "q0", func = f)
+        >>> s = Survey([q])
+        >>> s(period = "morning", cache = False).select("answer.q0").first()
+        'yes'
+        >>> s(period = "evening", cache = False).select("answer.q0").first()
+        'no'
+        """
+        job = self.get_job(model, agent, **kwargs)
+        return job.run(cache=cache)
+
+    async def run_async(self, model=None, agent=None, cache=None, **kwargs):
+        """Run the survey with default model, taking the required survey as arguments.
+
+        >>> from edsl.questions import QuestionFunctional
+        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
+        >>> q = QuestionFunctional(question_name = "q0", func = f)
+        >>> s = Survey([q])
+        >>> s(period = "morning").select("answer.q0").first()
+        'yes'
+        >>> s(period = "evening").select("answer.q0").first()
+        'no'
+        """
+        # TODO: temp fix by creating a cache
+        if cache is None:
+            from edsl.data import Cache
+
+            c = Cache()
+        else:
+            c = cache
+        jobs: "Jobs" = self.get_job(model, agent, **kwargs)
+        return await jobs.run_async(cache=c)
+
 
 def main():
     """Run the example survey."""