edsl 0.1.39.dev3__py3-none-any.whl → 0.1.39.dev4__py3-none-any.whl

edsl/agents/QuestionInstructionPromptBuilder.py

@@ -0,0 +1,128 @@
+from typing import Dict, List, Set
+from warnings import warn
+from edsl.prompts.Prompt import Prompt
+
+from edsl.agents.QuestionTemplateReplacementsBuilder import (
+    QuestionTemplateReplacementsBuilder as QTRB,
+)
+
+
+class QuestionInstructionPromptBuilder:
+    """Handles the construction and rendering of question instructions."""
+
+    def __init__(self, prompt_constructor: "PromptConstructor"):
+        self.prompt_constructor = prompt_constructor
+
+        self.model = self.prompt_constructor.model
+        self.survey = self.prompt_constructor.survey
+        self.question = self.prompt_constructor.question
+
+    def build(self) -> Prompt:
+        """Builds the complete question instructions prompt with all necessary components.
+
+        Returns:
+            Prompt: The fully rendered question instructions
+        """
+        base_prompt = self._create_base_prompt()
+        enriched_prompt = self._enrich_with_question_options(base_prompt)
+        rendered_prompt = self._render_prompt(enriched_prompt)
+        self._validate_template_variables(rendered_prompt)
+
+        return self._append_survey_instructions(rendered_prompt)
+
+    def _create_base_prompt(self) -> Dict:
+        """Creates the initial prompt with basic question data.
+
+        Returns:
+            Dict: Base question data
+        """
+        return {
+            "prompt": Prompt(self.question.get_instructions(model=self.model.model)),
+            "data": self.question.data.copy(),
+        }
+
+    def _enrich_with_question_options(self, prompt_data: Dict) -> Dict:
+        """Enriches the prompt data with question options if they exist.
+
+        Args:
+            prompt_data: Dictionary containing prompt and question data
+
+        Returns:
+            Dict: Enriched prompt data
+        """
+        if "question_options" in prompt_data["data"]:
+            from edsl.agents.question_option_processor import QuestionOptionProcessor
+
+            question_options = QuestionOptionProcessor(
+                self.prompt_constructor
+            ).get_question_options(question_data=prompt_data["data"])
+
+            prompt_data["data"]["question_options"] = question_options
+        return prompt_data
+
+    def _render_prompt(self, prompt_data: Dict) -> Prompt:
+        """Renders the prompt using the replacement dictionary.
+
+        Args:
+            prompt_data: Dictionary containing prompt and question data
+
+        Returns:
+            Prompt: Rendered instructions
+        """
+
+        replacement_dict = QTRB(self.prompt_constructor).build_replacement_dict(
+            prompt_data["data"]
+        )
+        return prompt_data["prompt"].render(replacement_dict)
+
+    def _validate_template_variables(self, rendered_prompt: Prompt) -> None:
+        """Validates that all template variables have been properly replaced.
+
+        Args:
+            rendered_prompt: The rendered prompt to validate
+
+        Warns:
+            If any template variables remain undefined
+        """
+        undefined_vars = rendered_prompt.undefined_template_variables({})
+
+        # Check for question names in undefined variables
+        self._check_question_names_in_undefined_vars(undefined_vars)
+
+        # Warn about any remaining undefined variables
+        if undefined_vars:
+            warn(f"Question instructions still has variables: {undefined_vars}.")
+
+    def _check_question_names_in_undefined_vars(self, undefined_vars: Set[str]) -> None:
+        """Checks if any undefined variables match question names in the survey.
+
+        Args:
+            undefined_vars: Set of undefined template variables
+        """
+        for question_name in self.survey.question_names:
+            if question_name in undefined_vars:
+                print(
+                    f"Question name found in undefined_template_variables: {question_name}"
+                )
+
+    def _append_survey_instructions(self, rendered_prompt: Prompt) -> Prompt:
+        """Appends any relevant survey instructions to the rendered prompt.
+
+        Args:
+            rendered_prompt: The rendered prompt to append instructions to
+
+        Returns:
+            Prompt: Final prompt with survey instructions
+        """
+        relevant_instructions = self.survey._relevant_instructions(
+            self.question.question_name
+        )
+
+        if not relevant_instructions:
+            return rendered_prompt
+
+        preamble = Prompt(text="")
+        for instruction in relevant_instructions:
+            preamble += instruction.text
+
+        return preamble + rendered_prompt

edsl/agents/QuestionTemplateReplacementsBuilder.py

@@ -0,0 +1,137 @@
+from jinja2 import Environment, meta
+from typing import Any, Set, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.agents.PromptConstructor import PromptConstructor
+    from edsl.scenarios.Scenario import Scenario
+
+
+class QuestionTemplateReplacementsBuilder:
+    def __init__(self, prompt_constructor: "PromptConstructor"):
+        self.prompt_constructor = prompt_constructor
+
+    def question_file_keys(self):
+        question_text = self.prompt_constructor.question.question_text
+        file_keys = self._find_file_keys(self.prompt_constructor.scenario)
+        return self._extract_file_keys_from_question_text(question_text, file_keys)
+
+    def scenario_file_keys(self):
+        return self._find_file_keys(self.prompt_constructor.scenario)
+
+    def get_jinja2_variables(template_str: str) -> Set[str]:
+        """
+        Extracts all variable names from a Jinja2 template using Jinja2's built-in parsing.
+
+        Args:
+        template_str (str): The Jinja2 template string
+
+        Returns:
+        Set[str]: A set of variable names found in the template
+        """
+        env = Environment()
+        ast = env.parse(template_str)
+        return meta.find_undeclared_variables(ast)
+
+    @staticmethod
+    def _find_file_keys(scenario: "Scenario") -> list:
+        """We need to find all the keys in the scenario that refer to FileStore objects.
+        These will be used to append to the prompt a list of files that are part of the scenario.
+
+        >>> from edsl import Scenario
+        >>> from edsl.scenarios.FileStore import FileStore
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile() as f:
+        ...     _ = f.write(b"Hello, world!")
+        ...     _ = f.seek(0)
+        ...     fs = FileStore(f.name)
+        ...     scenario = Scenario({"fs_file": fs, 'a': 1})
+        ...     QuestionTemplateReplacementsBuilder._find_file_keys(scenario)
+        ['fs_file']
+        """
+        from edsl.scenarios.FileStore import FileStore
+
+        file_entries = []
+        for key, value in scenario.items():
+            if isinstance(value, FileStore):
+                file_entries.append(key)
+        return file_entries
+
+    @staticmethod
+    def _extract_file_keys_from_question_text(
+        question_text: str, scenario_file_keys: list
+    ) -> list:
+        """
+        Extracts the file keys from a question text.
+
+        >>> from edsl import Scenario
+        >>> from edsl.scenarios.FileStore import FileStore
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile() as f:
+        ...     _ = f.write(b"Hello, world!")
+        ...     _ = f.seek(0)
+        ...     fs = FileStore(f.name)
+        ...     scenario = Scenario({"fs_file": fs, 'a': 1})
+        ...     QuestionTemplateReplacementsBuilder._extract_file_keys_from_question_text("{{ fs_file }}", ['fs_file'])
+        ['fs_file']
+        """
+        variables = QuestionTemplateReplacementsBuilder.get_jinja2_variables(
+            question_text
+        )
+        question_file_keys = []
+        for var in variables:
+            if var in scenario_file_keys:
+                question_file_keys.append(var)
+        return question_file_keys
+
+    def _scenario_replacements(self) -> dict[str, Any]:
+        # File references dictionary
+        file_refs = {key: f"<see file {key}>" for key in self.scenario_file_keys()}
+
+        # Scenario items excluding file keys
+        scenario_items = {
+            k: v
+            for k, v in self.prompt_constructor.scenario.items()
+            if k not in self.scenario_file_keys()
+        }
+        return {**file_refs, **scenario_items}
+
+    @staticmethod
+    def _question_data_replacements(
+        question: dict, question_data: dict
+    ) -> dict[str, Any]:
+        """Builds a dictionary of replacement values for rendering a prompt by combining multiple data sources.
+
+        >>> from edsl import QuestionMultipleChoice
+        >>> q = QuestionMultipleChoice(question_text="Do you like school?", question_name = "q0", question_options = ["yes", "no"])
+        >>> QuestionTemplateReplacementsBuilder._question_data_replacements(q, q.data)
+        {'use_code': False, 'include_comment': True, 'question_name': 'q0', 'question_text': 'Do you like school?', 'question_options': ['yes', 'no']}
+
+        """
+        question_settings = {
+            "use_code": getattr(question, "_use_code", True),
+            "include_comment": getattr(question, "_include_comment", False),
+        }
+        return {**question_settings, **question_data}
+
+    def build_replacement_dict(self, question_data: dict) -> dict[str, Any]:
+        """Builds a dictionary of replacement values for rendering a prompt by combining multiple data sources."""
+        rpl = {}
+        rpl["scenario"] = self._scenario_replacements()
+        rpl["question"] = self._question_data_replacements(
+            self.prompt_constructor.question, question_data
+        )
+        rpl["prior_answers"] = self.prompt_constructor.prior_answers_dict()
+        rpl["agent"] = {"agent": self.prompt_constructor.agent}
+
+        # Combine all dictionaries using dict.update() for clarity
+        replacement_dict = {}
+        for r in rpl.values():
+            replacement_dict.update(r)
+
+        return replacement_dict
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/agents/__init__.py

@@ -1,3 +1,2 @@
-from edsl.agents.Agent import Agent
-from edsl.agents.AgentList import AgentList
-from edsl.agents.InvigilatorBase import InvigilatorBase
+from edsl.agents.Agent import Agent
+from edsl.agents.AgentList import AgentList

edsl/agents/descriptors.py

@@ -1,99 +1,99 @@
-"""This module contains the descriptors used to set the attributes of the Agent class."""
-
-from typing import Dict
-from edsl.exceptions.agents import AgentNameError, AgentTraitKeyError
-
-
-def convert_agent_name(x):
-    # potentially a numpy int64
-    import numpy as np
-
-    if isinstance(x, np.int64):
-        return int(x)
-    elif x is None:
-        return None
-    elif isinstance(x, int):
-        return x
-    else:
-        return str(x)
-
-
-class NameDescriptor:
-    """ABC for something."""
-
-    def __get__(self, instance, owner):
-        """Return the value of the attribute."""
-        return instance.__dict__[self.name]
-
-    def __set__(self, instance, name: str) -> None:
-        """Set the value of the attribute."""
-        instance.__dict__[self.name] = convert_agent_name(name)
-
-    def __set_name__(self, owner, name: str) -> None:
-        """Set the name of the attribute."""
-        self.name = "_" + name
-
-
-class TraitsDescriptor:
-    """Traits descriptor."""
-
-    def __get__(self, instance, owner):
-        """Return the value of the attribute."""
-        return instance.__dict__[self.name]
-
-    def __set__(self, instance, traits_dict: Dict[str, str]) -> None:
-        """Set the value of the attribute."""
-        from edsl.utilities.utilities import is_valid_variable_name
-
-        for key, value in traits_dict.items():
-            if key == "name":
-                raise AgentNameError(
-                    "Trait keys cannot be 'name'. Instead, use the 'name' attribute directly e.g.,\n"
-                    'Agent(name="my_agent", traits={"trait1": "value1", "trait2": "value2"})'
-                )
-
-            if not is_valid_variable_name(key):
-                raise AgentTraitKeyError(
-                    f"""Trait keys must be valid Python identifiers (must be alphanumeric, cannot start with a number and must use underscores instead of spaces).
-                    You passed: {key}
-                    """
-                )
-
-        instance.__dict__[self.name] = traits_dict
-
-    def __set_name__(self, owner, name: str) -> None:
-        """Set the name of the attribute."""
-        self.name = name
-
-
-class CodebookDescriptor:
-    """ABC for something."""
-
-    def __get__(self, instance, owner):
-        """Return the value of the attribute."""
-        return instance.__dict__[self.name]
-
-    def __set__(self, instance, codebook_dict: Dict[str, str]) -> None:
-        """Set the value of the attribute."""
-        instance.__dict__[self.name] = codebook_dict
-
-    def __set_name__(self, owner, name: str) -> None:
-        """Set the name of the attribute."""
-        self.name = "_" + name
-
-
-class InstructionDescriptor:
-    """ABC for something."""
-
-    def __get__(self, instance, owner):
-        """Return the value of the attribute."""
-        return instance.__dict__[self.name]
-
-    def __set__(self, instance, instruction) -> None:
-        """Set the value of the attribute."""
-        instance.__dict__[self.name] = instruction
-        instance.set_instructions = instruction != instance.default_instruction
-
-    def __set_name__(self, owner, name: str) -> None:
-        """Set the name of the attribute."""
-        self.name = "_" + name
+"""This module contains the descriptors used to set the attributes of the Agent class."""
+
+from typing import Dict
+from edsl.exceptions.agents import AgentNameError, AgentTraitKeyError
+
+
+def convert_agent_name(x):
+    # potentially a numpy int64
+    import numpy as np
+
+    if isinstance(x, np.int64):
+        return int(x)
+    elif x is None:
+        return None
+    elif isinstance(x, int):
+        return x
+    else:
+        return str(x)
+
+
+class NameDescriptor:
+    """ABC for something."""
+
+    def __get__(self, instance, owner):
+        """Return the value of the attribute."""
+        return instance.__dict__[self.name]
+
+    def __set__(self, instance, name: str) -> None:
+        """Set the value of the attribute."""
+        instance.__dict__[self.name] = convert_agent_name(name)
+
+    def __set_name__(self, owner, name: str) -> None:
+        """Set the name of the attribute."""
+        self.name = "_" + name
+
+
+class TraitsDescriptor:
+    """Traits descriptor."""
+
+    def __get__(self, instance, owner):
+        """Return the value of the attribute."""
+        return instance.__dict__[self.name]
+
+    def __set__(self, instance, traits_dict: Dict[str, str]) -> None:
+        """Set the value of the attribute."""
+        from edsl.utilities.utilities import is_valid_variable_name
+
+        for key, value in traits_dict.items():
+            if key == "name":
+                raise AgentNameError(
+                    "Trait keys cannot be 'name'. Instead, use the 'name' attribute directly e.g.,\n"
+                    'Agent(name="my_agent", traits={"trait1": "value1", "trait2": "value2"})'
+                )
+
+            if not is_valid_variable_name(key):
+                raise AgentTraitKeyError(
+                    f"""Trait keys must be valid Python identifiers (must be alphanumeric, cannot start with a number and must use underscores instead of spaces).
+                    You passed: {key}
+                    """
+                )
+
+        instance.__dict__[self.name] = traits_dict
+
+    def __set_name__(self, owner, name: str) -> None:
+        """Set the name of the attribute."""
+        self.name = name
+
+
+class CodebookDescriptor:
+    """ABC for something."""
+
+    def __get__(self, instance, owner):
+        """Return the value of the attribute."""
+        return instance.__dict__[self.name]
+
+    def __set__(self, instance, codebook_dict: Dict[str, str]) -> None:
+        """Set the value of the attribute."""
+        instance.__dict__[self.name] = codebook_dict
+
+    def __set_name__(self, owner, name: str) -> None:
+        """Set the name of the attribute."""
+        self.name = "_" + name
+
+
+class InstructionDescriptor:
+    """ABC for something."""
+
+    def __get__(self, instance, owner):
+        """Return the value of the attribute."""
+        return instance.__dict__[self.name]
+
+    def __set__(self, instance, instruction) -> None:
+        """Set the value of the attribute."""
+        instance.__dict__[self.name] = instruction
+        instance.set_instructions = instruction != instance.default_instruction
+
+    def __set_name__(self, owner, name: str) -> None:
+        """Set the name of the attribute."""
+        self.name = "_" + name