edsl 0.1.38.dev4__py3-none-any.whl → 0.1.39__py3-none-any.whl

edsl/study/ObjectEntry.py

@@ -1,7 +1,7 @@
 import time
 import webbrowser
 from typing import Any, Dict, Optional, Type
-from edsl import QuestionBase
+from edsl.questions.QuestionBase import QuestionBase
 from edsl.Base import RegisterSubclassesMeta
 
 

edsl/study/SnapShot.py

@@ -32,7 +32,7 @@ class SnapShot:
         {'Cache': <class 'edsl.data.Cache.Cache'>}
         """
         from edsl.Base import RegisterSubclassesMeta
-        from edsl import QuestionBase
+        from edsl.questions.QuestionBase import QuestionBase
 
         all_edsl_objects = RegisterSubclassesMeta.get_registry()
 

edsl/study/Study.py

@@ -7,7 +7,9 @@ import socket
 from datetime import datetime
 from typing import Dict, Optional, Union
 from uuid import UUID, uuid4
-from edsl import Cache, set_session_cache, unset_session_cache
+
+from edsl.data.Cache import Cache
+from edsl import set_session_cache, unset_session_cache
 from edsl.utilities.utilities import dict_hash
 from edsl.study.ObjectEntry import ObjectEntry
 from edsl.study.ProofOfWork import ProofOfWork
@@ -405,7 +407,7 @@ class Study:
 
         study_file = tempfile.NamedTemporaryFile()
         with cls(filename=study_file.name, verbose=verbose) as study:
-            from edsl import QuestionFreeText
+            from edsl.questions.QuestionFreeText import QuestionFreeText
 
             q = QuestionFreeText.example(randomize=randomize)
         return study
@@ -464,7 +466,7 @@ class Study:
     def push(self) -> dict:
         """Push the objects to coop."""
 
-        from edsl import Coop
+        from edsl.coop.coop import Coop
 
         coop = Coop()
         return coop.create(self, description=self.description)
@@ -517,12 +519,3 @@ if __name__ == "__main__":
     import doctest
 
     doctest.testmod(optionflags=doctest.ELLIPSIS)
-
-    # with Study(name = "cool_study") as study:
-    #      from edsl import QuestionFreeText
-    #      q = QuestionFreeText.example()
-
-    # assert len(study.objects) == 1
-
-    # print(study.versions())
-    # {'q': [ObjectEntry(variable_name='q', object=Question('free_text', question_name = """how_are_you""", question_text = """How are you?"""), description='Question name: how_are_you', coop_info=None, created_at=1720276402.561273, edsl_class_name='QuestionFreeText')]}

edsl/surveys/ConstructDAG.py

@@ -0,0 +1,92 @@
+from edsl.surveys.base import EndOfSurvey
+from edsl.surveys.DAG import DAG
+from edsl.exceptions.surveys import SurveyError
+
+
+class ConstructDAG:
+    def __init__(self, survey):
+        self.survey = survey
+        self.questions = survey.questions
+
+        self.parameters_by_question = self.survey.parameters_by_question
+        self.question_name_to_index = self.survey.question_name_to_index
+
+    def dag(self, textify: bool = False) -> DAG:
+        memory_dag = self.survey.memory_plan.dag
+        rule_dag = self.survey.rule_collection.dag
+        piping_dag = self.piping_dag
+        if textify:
+            memory_dag = DAG(self.textify(memory_dag))
+            rule_dag = DAG(self.textify(rule_dag))
+            piping_dag = DAG(self.textify(piping_dag))
+        return memory_dag + rule_dag + piping_dag
+
+    @property
+    def piping_dag(self) -> DAG:
+        """Figures out the DAG of piping dependencies.
+
+        >>> from edsl import Survey
+        >>> from edsl import QuestionFreeText
+        >>> q0 = QuestionFreeText(question_text="Here is a question", question_name="q0")
+        >>> q1 = QuestionFreeText(question_text="You previously answered {{ q0 }}---how do you feel now?", question_name="q1")
+        >>> s = Survey([q0, q1])
+        >>> ConstructDAG(s).piping_dag
+        {1: {0}}
+        """
+        d = {}
+        for question_name, depenencies in self.parameters_by_question.items():
+            if depenencies:
+                question_index = self.question_name_to_index[question_name]
+                for dependency in depenencies:
+                    if dependency not in self.question_name_to_index:
+                        pass
+                    else:
+                        dependency_index = self.question_name_to_index[dependency]
+                        if question_index not in d:
+                            d[question_index] = set()
+                        d[question_index].add(dependency_index)
+        return d
+
+    def textify(self, index_dag: DAG) -> DAG:
+        """Convert the DAG of question indices to a DAG of question names.
+
+        :param index_dag: The DAG of question indices.
+
+        Example:
+
+        >>> from edsl import Survey
+        >>> s = Survey.example()
+        >>> d = s.dag()
+        >>> d
+        {1: {0}, 2: {0}}
+        >>> ConstructDAG(s).textify(d)
+        {'q1': {'q0'}, 'q2': {'q0'}}
+        """
+
+        def get_name(index: int):
+            """Return the name of the question given the index."""
+            if index >= len(self.questions):
+                return EndOfSurvey
+            try:
+                return self.questions[index].question_name
+            except IndexError:
+                print(
+                    f"The index is {index} but the length of the questions is {len(self.questions)}"
+                )
+                raise SurveyError
+
+        try:
+            text_dag = {}
+            for child_index, parent_indices in index_dag.items():
+                parent_names = {get_name(index) for index in parent_indices}
+                child_name = get_name(child_index)
+                text_dag[child_name] = parent_names
+            return text_dag
+        except IndexError:
+            raise
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

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."""