edsl 0.1.39.dev1__py3-none-any.whl → 0.1.39.dev2__py3-none-any.whl

edsl/surveys/EditSurvey.py

@@ -0,0 +1,221 @@
+from typing import Union, Optional, TYPE_CHECKING
+from edsl.exceptions.surveys import SurveyError
+
+if TYPE_CHECKING:
+    from edsl.questions.QuestionBase import QuestionBase
+
+from edsl.exceptions.surveys import SurveyError, SurveyCreationError
+from edsl.surveys.Rule import Rule
+from edsl.surveys.base import RulePriority, EndOfSurvey
+
+
+class EditSurvey:
+    def __init__(self, survey):
+        self.survey = survey
+
+    def move_question(self, identifier: Union[str, int], new_index: int) -> "Survey":
+        if isinstance(identifier, str):
+            if identifier not in self.survey.question_names:
+                raise SurveyError(
+                    f"Question name '{identifier}' does not exist in the survey."
+                )
+            index = self.survey.question_name_to_index[identifier]
+        elif isinstance(identifier, int):
+            if identifier < 0 or identifier >= len(self.survey.questions):
+                raise SurveyError(f"Index {identifier} is out of range.")
+            index = identifier
+        else:
+            raise SurveyError(
+                "Identifier must be either a string (question name) or an integer (question index)."
+            )
+
+        moving_question = self.survey._questions[index]
+
+        new_survey = self.survey.delete_question(index)
+        new_survey.add_question(moving_question, new_index)
+        return new_survey
+
+    def add_question(
+        self, question: "QuestionBase", index: Optional[int] = None
+    ) -> "Survey":
+        if question.question_name in self.survey.question_names:
+            raise SurveyCreationError(
+                f"""Question name '{question.question_name}' already exists in survey. Existing names are {self.survey.question_names}."""
+            )
+        if index is None:
+            index = len(self.survey.questions)
+
+        if index > len(self.survey.questions):
+            raise SurveyCreationError(
+                f"Index {index} is greater than the number of questions in the survey."
+            )
+        if index < 0:
+            raise SurveyCreationError(f"Index {index} is less than 0.")
+
+        interior_insertion = index != len(self.survey.questions)
+
+        # index = len(self.survey.questions)
+        # TODO: This is a bit ugly because the user
+        # doesn't "know" about _questions - it's generated by the
+        # descriptor.
+        self.survey._questions.insert(index, question)
+
+        if interior_insertion:
+            for question_name, old_index in self.survey._pseudo_indices.items():
+                if old_index >= index:
+                    self.survey._pseudo_indices[question_name] = old_index + 1
+
+        self.survey._pseudo_indices[question.question_name] = index
+
+        ## Re-do question_name to index - this is done automatically
+        # for question_name, old_index in self.survey.question_name_to_index.items():
+        #     if old_index >= index:
+        #         self.survey.question_name_to_index[question_name] = old_index + 1
+
+        ## Need to re-do the rule collection and the indices of the questions
+
+        ## If a rule is before the insertion index and next_q is also before the insertion index, no change needed.
+        ## If the rule is before the insertion index but next_q is after the insertion index, increment the next_q by 1
+        ## If the rule is after the insertion index, increment the current_q by 1 and the next_q by 1
+
+        # using index + 1 presumes there is a next question
+        if interior_insertion:
+            for rule in self.survey.rule_collection:
+                if rule.current_q >= index:
+                    rule.current_q += 1
+                if rule.next_q >= index:
+                    rule.next_q += 1
+
+        # add a new rule
+        self.survey.rule_collection.add_rule(
+            Rule(
+                current_q=index,
+                expression="True",
+                next_q=index + 1,
+                question_name_to_index=self.survey.question_name_to_index,
+                priority=RulePriority.DEFAULT.value,
+            )
+        )
+
+        # a question might be added before the memory plan is created
+        # it's ok because the memory plan will be updated when it is created
+        if hasattr(self.survey, "memory_plan"):
+            self.survey.memory_plan.add_question(question)
+
+        return self.survey
+
+    def delete_question(self, identifier: Union[str, int]) -> "Survey":
+        """
+        Delete a question from the survey.
+
+        :param identifier: The name or index of the question to delete.
+        :return: The updated Survey object.
+
+        >>> from edsl import QuestionMultipleChoice, Survey
+        >>> q1 = QuestionMultipleChoice(question_text="Q1", question_options=["A", "B"], question_name="q1")
+        >>> q2 = QuestionMultipleChoice(question_text="Q2", question_options=["C", "D"], question_name="q2")
+        >>> s = Survey().add_question(q1).add_question(q2)
+        >>> _ = s.delete_question("q1")
+        >>> len(s.questions)
+        1
+        >>> _ = s.delete_question(0)
+        >>> len(s.questions)
+        0
+        """
+        if isinstance(identifier, str):
+            if identifier not in self.survey.question_names:
+                raise SurveyError(
+                    f"Question name '{identifier}' does not exist in the survey."
+                )
+            index = self.survey.question_name_to_index[identifier]
+        elif isinstance(identifier, int):
+            if identifier < 0 or identifier >= len(self.survey.questions):
+                raise SurveyError(f"Index {identifier} is out of range.")
+            index = identifier
+        else:
+            raise SurveyError(
+                "Identifier must be either a string (question name) or an integer (question index)."
+            )
+
+        # Remove the question
+        deleted_question = self.survey._questions.pop(index)
+        del self.survey._pseudo_indices[deleted_question.question_name]
+
+        # Update indices
+        for question_name, old_index in self.survey._pseudo_indices.items():
+            if old_index > index:
+                self.survey._pseudo_indices[question_name] = old_index - 1
+
+        # Update rules
+        from .RuleCollection import RuleCollection
+
+        new_rule_collection = RuleCollection()
+        for rule in self.survey.rule_collection:
+            if rule.current_q == index:
+                continue  # Remove rules associated with the deleted question
+            if rule.current_q > index:
+                rule.current_q -= 1
+            if rule.next_q > index:
+                rule.next_q -= 1
+
+            if rule.next_q == index:
+                if index == len(self.survey.questions):
+                    rule.next_q = EndOfSurvey
+                else:
+                    rule.next_q = index
+
+            new_rule_collection.add_rule(rule)
+        self.survey.rule_collection = new_rule_collection
+
+        # Update memory plan if it exists
+        if hasattr(self.survey, "memory_plan"):
+            self.survey.memory_plan.remove_question(deleted_question.question_name)
+
+        return self.survey
+
+    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
+        >>> from edsl.surveys.Survey import Survey
+        >>> 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.survey._instruction_names_to_instructions:
+            raise SurveyCreationError(
+                f"""Instruction name '{instruction.name}' already exists in survey. Existing names are {self.survey._instruction_names_to_instructions.keys()}."""
+            )
+        self.survey._instruction_names_to_instructions[instruction.name] = instruction
+
+        # was the last thing added an instruction or a question?
+        if self.survey._pseudo_indices.last_item_was_instruction:
+            pseudo_index = (
+                self.survey._pseudo_indices.max_pseudo_index
+                + (
+                    math.ceil(self.survey._pseudo_indices.max_pseudo_index)
+                    - self.survey._pseudo_indices.max_pseudo_index
+                )
+                / 2
+            )
+        else:
+            pseudo_index = self.survey._pseudo_indices.max_pseudo_index + 1.0 / 2.0
+        self.survey._pseudo_indices[instruction.name] = pseudo_index
+
+        return self.survey
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/surveys/InstructionHandler.py

@@ -0,0 +1,100 @@
+from typing import TYPE_CHECKING
+from dataclasses import dataclass
+
+
+@dataclass
+class SeparatedComponents:
+    true_questions: list
+    instruction_names_to_instructions: dict
+    pseudo_indices: dict
+
+
+class InstructionHandler:
+    def __init__(self, survey):
+        self.survey = survey
+
+    @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 Survey
+        >>> 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
+        from edsl.questions.QuestionBase import QuestionBase
+
+        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 SeparatedComponents(
+            true_questions, instruction_names_to_instructions, pseudo_indices
+        )
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/surveys/MemoryManagement.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+from typing import Callable, Union, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.questions.QuestionBase import QuestionBase
+
+
+class MemoryManagement:
+    def __init__(self, survey):
+        self.survey = survey
+
+    def _set_memory_plan(self, prior_questions_func: Callable) -> None:
+        """Set memory plan based on a provided function determining prior questions.
+        :param prior_questions_func: A function that takes an index and returns a list of prior questions.
+        """
+        for i, question_name in enumerate(self.survey.question_names):
+            self.survey.memory_plan.add_memory_collection(
+                focal_question=question_name,
+                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:
+        """
+        focal_question_name = self.survey.question_names[
+            self.survey._get_question_index(focal_question)
+        ]
+        prior_question_name = self.survey.question_names[
+            self.survey._get_question_index(prior_question)
+        ]
+
+        self.survey.memory_plan.add_single_memory(
+            focal_question=focal_question_name,
+            prior_question=prior_question_name,
+        )
+
+        return self.survey
+
+    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.
+        """
+        focal_question_name = self.survey.question_names[
+            self.survey._get_question_index(focal_question)
+        ]
+
+        prior_question_names = [
+            self.survey.question_names[self.survey._get_question_index(prior_question)]
+            for prior_question in prior_questions
+        ]
+
+        self.survey.memory_plan.add_memory_collection(
+            focal_question=focal_question_name, prior_questions=prior_question_names
+        )
+        return self.survey

edsl/surveys/Rule.py

@@ -21,13 +21,13 @@ import ast
 import random
 from typing import Any, Union, List
 
-from jinja2 import Template
-from rich import print
+
+# from rich import print
 from simpleeval import EvalWithCompoundTypes
 
 from edsl.exceptions.surveys import SurveyError
 
-from edsl.exceptions import (
+from edsl.exceptions.surveys import (
     SurveyRuleCannotEvaluateError,
     SurveyRuleCollectionHasNoRulesAtNodeError,
     SurveyRuleRefersToFutureStateError,
@@ -37,7 +37,7 @@ from edsl.exceptions import (
 )
 from edsl.surveys.base import EndOfSurvey
 from edsl.utilities.ast_utilities import extract_variable_names
-from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
+from edsl.utilities.remove_edsl_version import remove_edsl_version
 
 
 class QuestionIndex:
@@ -253,6 +253,7 @@ class Rule:
         ...
         edsl.exceptions.surveys.SurveyRuleCannotEvaluateError...
         """
+        from jinja2 import Template
 
         def substitute_in_answers(expression, current_info_env):
             """Take the dictionary of answers and substitute them into the expression."""

edsl/surveys/RuleCollection.py

@@ -1,20 +1,17 @@
 """A collection of rules for a survey."""
 
 from typing import List, Union, Any, Optional
-from collections import defaultdict, UserList
+from collections import defaultdict, UserList, namedtuple
 
-from edsl.exceptions import (
+from edsl.exceptions.surveys import (
     SurveyRuleCannotEvaluateError,
     SurveyRuleCollectionHasNoRulesAtNodeError,
 )
-from edsl.utilities.interface import print_table_with_rich
+
 from edsl.surveys.Rule import Rule
 from edsl.surveys.base import EndOfSurvey
 from edsl.surveys.DAG import DAG
 
-# from graphlib import TopologicalSorter
-
-from collections import namedtuple
 
 NextQuestion = namedtuple(
     "NextQuestion", "next_q, num_rules_found, expressions_evaluating_to_true, priority"
@@ -46,6 +43,24 @@ class RuleCollection(UserList):
         """
         return f"RuleCollection(rules={self.data}, num_questions={self.num_questions})"
 
+    def to_dataset(self):
+        """Return a Dataset object representation of the RuleCollection object."""
+        from edsl.results.Dataset import Dataset
+
+        keys = ["current_q", "expression", "next_q", "priority", "before_rule"]
+        rule_list = {}
+        for rule in sorted(self, key=lambda r: r.current_q):
+            for k in keys:
+                rule_list.setdefault(k, []).append(getattr(rule, k))
+
+        return Dataset([{k: v} for k, v in rule_list.items()])
+
+    def _repr_html_(self):
+        """Return an HTML representation of the RuleCollection object."""
+        from edsl.results.Dataset import Dataset
+
+        return self.to_dataset()._repr_html_()
+
     def to_dict(self, add_edsl_version=True):
         """Create a dictionary representation of the RuleCollection object."""
         return {
@@ -106,12 +121,7 @@ class RuleCollection(UserList):
         │ 1         │ q1 == 'no'  │ 2      │ 1        │ False       │
         └───────────┴─────────────┴────────┴──────────┴─────────────┘
         """
-        keys = ["current_q", "expression", "next_q", "priority", "before_rule"]
-        rule_list = []
-        for rule in sorted(self, key=lambda r: r.current_q):
-            rule_list.append({k: getattr(rule, k) for k in keys})
-
-        print_table_with_rich(rule_list)
+        return self.to_dataset()
 
     def skip_question_before_running(self, q_now: int, answers: dict[str, Any]) -> bool:
         """Determine if a question should be skipped before running the question.
@@ -183,17 +193,6 @@ class RuleCollection(UserList):
         NextQuestion(next_q=3, num_rules_found=2, expressions_evaluating_to_true=1, priority=1)
 
         """
-        # # is this the first question? If it is, we need to check if it should be skipped.
-        # if q_now == 0:
-        #     if self.skip_question_before_running(q_now, answers):
-        #         return NextQuestion(
-        #             next_q=q_now + 1,
-        #             num_rules_found=0,
-        #             expressions_evaluating_to_true=0,
-        #             priority=-1,
-        #         )
-
-        # breakpoint()
         expressions_evaluating_to_true = 0
         next_q = None
         highest_priority = -2  # start with -2 to 'pick up' the default rule added
@@ -215,7 +214,6 @@ class RuleCollection(UserList):
                 f"No rules found for question {q_now}"
             )
 
-        # breakpoint()
         ## Now we need to check if the *next question* has any 'before; rules that we should follow
         for rule in self.applicable_rules(next_q, before_rule=True):
             if rule.evaluate(answers):  # rule evaluates to True
@@ -260,8 +258,7 @@ class RuleCollection(UserList):
             [2, 3]
 
         """
-        # If it's the end of the survey, all questions between the start_q and the end of the survey
-        # now depend on the start_q
+        # If it's the end of the survey, all questions between the start_q and the end of the survey now depend on the start_q
         if end_q == EndOfSurvey:
             if self.num_questions is None:
                 raise ValueError(
@@ -381,7 +378,8 @@ class RuleCollection(UserList):
 
 
 if __name__ == "__main__":
-    # pass
     import doctest
 
     doctest.testmod(optionflags=doctest.ELLIPSIS)
+
+    print(RuleCollection.example()._repr_html_())