edsl 0.1.14__py3-none-any.whl → 0.1.40__py3-none-any.whl

edsl/questions/descriptors.py

@@ -1,14 +1,14 @@
+"""This module contains the descriptors used to validate the attributes of the question classes."""
+
 from abc import ABC, abstractmethod
 import re
-from typing import Any, Callable
-from edsl.exceptions import (
+from typing import Any, Callable, List, Optional
+from edsl.exceptions.questions import (
     QuestionCreationValidationError,
     QuestionAnswerValidationError,
 )
 from edsl.questions.settings import Settings
-from edsl.utilities.utilities import is_valid_variable_name
 
-from edsl.prompts import get_classes
 
 ################################
 # Helper functions
@@ -16,19 +16,19 @@ from edsl.prompts import get_classes
 
 
 def contains_single_braced_substring(s: str) -> bool:
-    """Checks if the string contains a substring in single braces."""
+    """Check if the string contains a substring in single braces."""
     pattern = r"(?<!\{)\{[^{}]+\}(?!\})"
     match = re.search(pattern, s)
     return bool(match)
 
 
 def is_number(value: Any) -> bool:
-    """Checks if an object is a number."""
+    """Check if an object is a number."""
     return isinstance(value, int) or isinstance(value, float)
 
 
 def is_number_or_none(value: Any) -> bool:
-    """Checks if an object is a number or None."""
+    """Check if an object is a number or None."""
     return value is None or is_number(value)
 
 
@@ -42,43 +42,26 @@ class BaseDescriptor(ABC):
 
     @abstractmethod
     def validate(self, value: Any) -> None:
-        """Validates the value. If it is invalid, raises an exception. If it is valid, does nothing."""
+        """Validate the value. If it is invalid, raises an exception. If it is valid, does nothing."""
         pass
 
     def __get__(self, instance, owner):
-        """"""
+        """Get the value of the attribute."""
         if self.name not in instance.__dict__:
             return {}
         return instance.__dict__[self.name]
 
     def __set__(self, instance, value: Any) -> None:
-        self.validate(value, instance)
-        instance.__dict__[self.name] = value
-        if self.name == "_instructions":
-            instructions = value
-            if value is not None:
-                instance.__dict__[self.name] = instructions
-                instance.set_instructions = True
-            else:
-                potential_prompt_classes = get_classes(
-                    question_type=instance.question_type
-                )
-                if len(potential_prompt_classes) > 0:
-                    instructions = potential_prompt_classes[0]().text
-                    instance.__dict__[self.name] = instructions
-                    instance.set_instructions = False
-                else:
-                    if not hasattr(instance, "default_instructions"):
-                        raise Exception(
-                            "No default instructions found and no matching prompts!"
-                        )
-                    instructions = instance.default_instructions
-                    instance.__dict__[self.name] = instructions
-                    instance.set_instructions = False
-
-            # instance.set_instructions = value != instance.default_instructions
+        """Set the value of the attribute."""
+        new_value = self.validate(value, instance)
+
+        if new_value is not None:
+            instance.__dict__[self.name] = new_value
+        else:
+            instance.__dict__[self.name] = value
 
     def __set_name__(self, owner, name: str) -> None:
+        """Set the name of the attribute."""
         self.name = "_" + name
 
 
@@ -88,8 +71,10 @@ class BaseDescriptor(ABC):
 
 
 class FunctionDescriptor(BaseDescriptor):
+    """Validate that a value is a function."""
+
     def validate(self, value: Any, instance) -> Callable:
-        """Validates the value is a function, and if so, returns it."""
+        """Validate the value is a function, and if so, returns it."""
         if not callable(value):
             raise QuestionCreationValidationError(
                 f"Expected a function (got {value}).)"
@@ -99,14 +84,17 @@ class FunctionDescriptor(BaseDescriptor):
 
 class IntegerDescriptor(BaseDescriptor):
     """
-    Validates that a value is an integer.
+    Validate that a value is an integer.
+
     - `none_allowed` is whether None is allowed as a value.
     """
 
     def __init__(self, none_allowed: bool = False):
+        """Initialize the descriptor."""
         self.none_allowed = none_allowed
 
     def validate(self, value, instance):
+        """Validate the value is an integer."""
         if self.none_allowed:
             if not (isinstance(value, int) or value is None):
                 raise QuestionAnswerValidationError(
@@ -120,7 +108,10 @@ class IntegerDescriptor(BaseDescriptor):
 
 
 class IntegerOrNoneDescriptor(BaseDescriptor):
+    """Validate that a value is an integer or None."""
+
     def validate(self, value, instance):
+        """Validate the value is an integer or None."""
         if not (isinstance(value, int) or value is None):
             raise QuestionCreationValidationError(
                 f"Expected an integer or None (got {value})."
@@ -128,7 +119,10 @@ class IntegerOrNoneDescriptor(BaseDescriptor):
 
 
 class NumericalOrNoneDescriptor(BaseDescriptor):
+    """Validate that a value is a number or None."""
+
     def validate(self, value, instance):
+        """Validate the value is a number or None."""
         if not is_number_or_none(value):
             raise QuestionAnswerValidationError(
                 f"Expected a number or None (got {value})."
@@ -140,20 +134,11 @@ class NumericalOrNoneDescriptor(BaseDescriptor):
 ################################
 
 
-class AllowNonresponseDescriptor(BaseDescriptor):
-    """Validates that the `allow_nonresponse` attribute is a boolean."""
-
-    def validate(self, value, instance):
-        if not isinstance(value, bool):
-            raise QuestionCreationValidationError(
-                f"`allow_nonresponse` must be a boolean (got {value})."
-            )
-
-
 class AnswerTemplateDescriptor(BaseDescriptor):
-    """Validates that the answer template is a dictionary with string keys and string values."""
+    """Validate that the answer template is a dictionary with string keys and string values."""
 
     def validate(self, value: Any, instance) -> None:
+        """Validate the answer template."""
         if not isinstance(value, dict):
             raise QuestionCreationValidationError(
                 f"`answer_template` must be a dictionary (got {value}).)"
@@ -165,9 +150,10 @@ class AnswerTemplateDescriptor(BaseDescriptor):
 
 
 class InstructionsDescriptor(BaseDescriptor):
-    """Validates that the `instructions` attribute is a string."""
+    """Validate that the `instructions` attribute is a string."""
 
     def validate(self, value, instance):
+        """Validate the value is a string."""
         # if not isinstance(value, str):
         #     raise QuestionCreationValidationError(
         #         f"Question `instructions` must be a string (got {value})."
@@ -176,9 +162,10 @@ class InstructionsDescriptor(BaseDescriptor):
 
 
 class NumSelectionsDescriptor(BaseDescriptor):
-    """Validates that `num_selections` is an integer, is less than the number of options, and is positive."""
+    """Validate that `num_selections` is an integer, is less than the number of options, and is positive."""
 
     def validate(self, value, instance):
+        """Validate the value is an integer, is less than the number of options, and is positive."""
         if not (isinstance(value, int)):
             raise QuestionCreationValidationError(
                 f"`num_selections` must be an integer (got {value})."
@@ -194,13 +181,32 @@ class NumSelectionsDescriptor(BaseDescriptor):
 
 
 class OptionLabelDescriptor(BaseDescriptor):
+    """Validate that the `option_label` attribute is a string.
+
+    >>> class TestQuestion:
+    ...     option_label = OptionLabelDescriptor()
+    ...     def __init__(self, option_label: str):
+    ...         self.option_label = option_label
+
+    >>> _ = TestQuestion("{{Option}}")
+
+    """
+
     def validate(self, value, instance):
-        if value is not None:
-            if min(value.keys()) != min(instance.question_options):
+        """Validate the value is a string."""
+        if isinstance(value, str):
+            if "{{" in value and "}}" in value:
+                # they're trying to use a dynamic question name - let's let this play out
+                return None
+
+        key_values = [int(v) for v in value.keys()]
+
+        if value and (key_values := [float(v) for v in value.keys()]) != []:
+            if min(key_values) != min(instance.question_options):
                 raise QuestionCreationValidationError(
                     f"First option needs a label (got {value})"
                 )
-            if max(value.keys()) != max(instance.question_options):
+            if max(key_values) != max(instance.question_options):
                 raise QuestionCreationValidationError(
                     f"Last option needs a label (got {value})"
                 )
@@ -208,17 +214,34 @@ class OptionLabelDescriptor(BaseDescriptor):
                 raise QuestionCreationValidationError(
                     "Option labels must be strings (got {value})."
                 )
-            for key in value.keys():
+            for key in key_values:
                 if key not in instance.question_options:
                     raise QuestionCreationValidationError(
                         f"Option label key ({key}) is not in question options ({instance.question_options})."
                     )
 
+            if len(value.values()) != len(set(value.values())):
+                raise QuestionCreationValidationError(
+                    f"Option labels must be unique (got {value})."
+                )
+
 
 class QuestionNameDescriptor(BaseDescriptor):
-    """Validates that the `question_name` attribute is a valid variable name."""
+    """Validate that the `question_name` attribute is a valid variable name."""
 
     def validate(self, value, instance):
+        """Validate the value is a valid variable name."""
+        from edsl.utilities.utilities import is_valid_variable_name
+
+        if "{{" in value and "}}" in value:
+            # they're trying to use a dynamic question name - let's let this play out
+            return None
+
+        if value.endswith("_comment") or value.endswith("_generated_tokens"):
+            raise QuestionCreationValidationError(
+                f"`question_name` cannot end with '_comment' or '_generated_tokens - (got {value})."
+            )
+
         if not is_valid_variable_name(value):
             raise QuestionCreationValidationError(
                 f"`question_name` is not a valid variable name (got {value})."
@@ -226,13 +249,55 @@ class QuestionNameDescriptor(BaseDescriptor):
 
 
 class QuestionOptionsDescriptor(BaseDescriptor):
-    """Validates that `question_options` is a list, does not exceed the min/max lengths, and has unique items."""
+    """Validate that `question_options` is a list, does not exceed the min/max lengths, and has unique items."""
+
+    @classmethod
+    def example(cls):
+        class TestQuestion:
+            question_options = QuestionOptionsDescriptor()
 
-    def __init__(self, num_choices: int = None, linear_scale: bool = False):
+            def __init__(self, question_options: List[str]):
+                self.question_options = question_options
+
+        return TestQuestion
+
+    def __init__(
+        self,
+        num_choices: int = None,
+        linear_scale: bool = False,
+        q_budget: bool = False,
+    ):
+        """Initialize the descriptor."""
         self.num_choices = num_choices
         self.linear_scale = linear_scale
+        self.q_budget = q_budget
 
     def validate(self, value: Any, instance) -> None:
+        """Validate the question options.
+
+        >>> q_class = QuestionOptionsDescriptor.example()
+        >>> _ = q_class(["a", "b", "c"])
+        >>> _ = q_class(["a", "b", "c", "d", "d"])
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.questions.QuestionCreationValidationError: Question options must be unique (got ['a', 'b', 'c', 'd', 'd']).
+
+        We allow dynamic question options, which are strings of the form '{{ question_options }}'.
+
+        >>> _ = q_class("{{dynamic_options}}")
+        >>> _ = q_class("dynamic_options")
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.questions.QuestionCreationValidationError: ...
+        """
+        if isinstance(value, str):
+            # Check if the string is a dynamic question option
+            if "{{" in value and "}}" in value:
+                return None
+            else:
+                raise QuestionCreationValidationError(
+                    f"Dynamic question options must have jinja2 braces - instead received: {value}."
+                )
         if not isinstance(value, list):
             raise QuestionCreationValidationError(
                 f"Question options must be a list (got {value})."
@@ -245,18 +310,32 @@ class QuestionOptionsDescriptor(BaseDescriptor):
             raise QuestionCreationValidationError(
                 f"Too few question options (got {value})."
             )
-        if len(value) != len(set(value)):
+        # handle the case when question_options is a list of lists (a list of list can be converted to set)
+        tmp_value = [str(x) for x in value]
+        if len(tmp_value) != len(set(tmp_value)):
             raise QuestionCreationValidationError(
                 f"Question options must be unique (got {value})."
             )
         if not self.linear_scale:
-            if not all(isinstance(x, str) for x in value):
-                raise QuestionCreationValidationError(
-                    "Question options must be strings (got {value}).)"
-                )
+            if not self.q_budget:
+                pass
+            #     if not (
+            #         value
+            #         and all(type(x) == type(value[0]) for x in value)
+            #         and isinstance(value[0], (str, list, int, float))
+            #     ):
+            #         raise QuestionCreationValidationError(
+            #             f"Question options must be all same type (got {value}).)"
+            #         )
+            else:
+                if not all(isinstance(x, (str)) for x in value):
+                    raise QuestionCreationValidationError(
+                        f"Question options must be strings (got {value}).)"
+                    )
             if not all(
                 [
-                    len(option) >= 1 and len(option) < Settings.MAX_OPTION_LENGTH
+                    type(option) != str
+                    or (len(option) >= 1 and len(option) < Settings.MAX_OPTION_LENGTH)
                     for option in value
                 ]
             ):
@@ -287,31 +366,106 @@ class QuestionOptionsDescriptor(BaseDescriptor):
 
 
 class QuestionTextDescriptor(BaseDescriptor):
+    """Validate that the `question_text` attribute is a string.
+
+
+    >>> class TestQuestion:
+    ...     question_text = QuestionTextDescriptor()
+    ...     def __init__(self, question_text: str):
+    ...         self.question_text = question_text
+
+    >>> _ = TestQuestion("What is the capital of France?")
+    >>> _ = TestQuestion("What is the capital of France? {{variable}}")
+    >>> _ = TestQuestion("What is the capital of France? {{variable name}}")
+    Traceback (most recent call last):
+    ...
+    edsl.exceptions.questions.QuestionCreationValidationError: Question text contains an invalid identifier: 'variable name'
+    """
+
     def validate(self, value, instance):
-        if len(value) > Settings.MAX_QUESTION_LENGTH:
-            raise Exception("Question is too long!")
+        """Validate the value is a string."""
+        # if len(value) > Settings.MAX_QUESTION_LENGTH:
+        #     raise Exception("Question is too long!")
         if len(value) < 1:
             raise Exception("Question is too short!")
         if not isinstance(value, str):
             raise Exception("Question must be a string!")
         if contains_single_braced_substring(value):
-            print(
-                f"WARNING: Question text contains a single-braced substring: {value}.\nYou probably mean to use a double-braced substring, e.g. {{variable}}."
+            import warnings
+
+            # # warnings.warn(
+            # #     f"WARNING: Question text contains a single-braced substring: If you intended to parameterize the question with a Scenario this should be changed to a double-braced substring, e.g. {{variable}}.\nSee details on constructing Scenarios in the docs: https://docs.expectedparrot.com/en/latest/scenarios.html",
+            # #     UserWarning,
+            # # )
+            warnings.warn(
+                "WARNING: Question text contains a single-braced substring. "
+                "If you intended to parameterize the question with a Scenario, this will "
+                "be changed to a double-braced substring, e.g. {{variable}}.\n"
+                "See details on constructing Scenarios in the docs: "
+                "https://docs.expectedparrot.com/en/latest/scenarios.html",
+                UserWarning,
             )
+            # Automatically replace single braces with double braces
+            # This is here because if the user is using an f-string, the double brace will get converted to a single brace.
+            # This undoes that.
+            value = re.sub(r"\{([^\{\}]+)\}", r"{{\1}}", value)
+            return value
+
+        # iterate through all doubles braces and check if they are valid python identifiers
+        for match in re.finditer(r"\{\{([^\{\}]+)\}\}", value):
+            if " " in match.group(1).strip():
+                raise QuestionCreationValidationError(
+                    f"Question text contains an invalid identifier: '{match.group(1)}'"
+                )
 
+        return None
 
-class ShortNamesDictDescriptor(BaseDescriptor):
+
+class ValueTypesDescriptor(BaseDescriptor):
     def validate(self, value, instance):
-        "Validates the short names dictionary"
-        if not isinstance(value, dict):
+        """Validate the value is a list of strings or None."""
+        if value is None:  # Allow None as a valid value
+            return None
+        if not isinstance(value, list):
             raise QuestionCreationValidationError(
-                f"Short names dictionary must be a dictionary (got {value})."
+                f"`value_types` must be a list or None (got {value})."
             )
-        if not all(isinstance(x, str) for x in value.keys()):
+        # Convert all items in the list to strings
+        return [str(item) for item in value]
+
+
+class ValueDescriptionsDescriptor(BaseDescriptor):
+    def validate(self, value, instance):
+        """Validate the value is a list of strings or None."""
+        if value is None:  # Allow None as a valid value
+            return None
+        if not isinstance(value, list):
             raise QuestionCreationValidationError(
-                f"Short names dictionary keys must be strings (got {value})."
+                f"`value_descriptions` must be a list or None (got {value})."
             )
-        if not all(isinstance(x, str) for x in value.values()):
+        if not all(isinstance(x, str) for x in value):
             raise QuestionCreationValidationError(
-                f"Short names dictionary values must be strings (got {value})."
+                f"`value_descriptions` must be a list of strings (got {value})."
             )
+        return value
+
+
+class AnswerKeysDescriptor(BaseDescriptor):
+    """Validate that the `answer_keys` attribute is a list of strings or integers."""
+
+    def validate(self, value, instance):
+        """Validate the value is a list of strings or integers."""
+        if not isinstance(value, list):
+            raise QuestionCreationValidationError(
+                f"`answer_keys` must be a list (got {value})."
+            )
+        if not all(isinstance(x, (str, int)) for x in value):
+            raise QuestionCreationValidationError(
+                f"`answer_keys` must be a list of strings or integers (got {value})."
+            )
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/loop_processor.py

@@ -0,0 +1,149 @@
+from typing import List, Any, Dict, Union
+from jinja2 import Environment
+from edsl.questions.QuestionBase import QuestionBase
+from edsl import ScenarioList
+
+
+class LoopProcessor:
+    def __init__(self, question: QuestionBase):
+        self.question = question
+        self.env = Environment()
+
+    def process_templates(self, scenario_list: ScenarioList) -> List[QuestionBase]:
+        """Process templates for each scenario and return list of modified questions.
+
+        Args:
+            scenario_list: List of scenarios to process templates against
+
+        Returns:
+            List of QuestionBase objects with rendered templates
+        """
+        questions = []
+        starting_name = self.question.question_name
+
+        for index, scenario in enumerate(scenario_list):
+            question_data = self.question.to_dict().copy()
+            processed_data = self._process_data(question_data, scenario)
+
+            if processed_data["question_name"] == starting_name:
+                processed_data["question_name"] += f"_{index}"
+
+            questions.append(QuestionBase.from_dict(processed_data))
+
+        return questions
+
+    def _process_data(
+        self, data: Dict[str, Any], scenario: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Process all data fields according to their type.
+
+        Args:
+            data: Dictionary of question data
+            scenario: Current scenario to render templates against
+
+        Returns:
+            Processed dictionary with rendered templates
+        """
+        processed = {}
+
+        for key, value in [(k, v) for k, v in data.items() if v is not None]:
+            processed[key] = self._process_value(key, value, scenario)
+
+        return processed
+
+    def _process_value(self, key: str, value: Any, scenario: Dict[str, Any]) -> Any:
+        """Process a single value according to its type.
+
+        Args:
+            key: Dictionary key
+            value: Value to process
+            scenario: Current scenario
+
+        Returns:
+            Processed value
+        """
+        if key == "question_options" and isinstance(value, str):
+            return value
+
+        if key == "option_labels":
+            import json
+
+            return (
+                eval(self._render_template(value, scenario))
+                if isinstance(value, str)
+                else value
+            )
+
+        if isinstance(value, str):
+            return self._render_template(value, scenario)
+
+        if isinstance(value, list):
+            return self._process_list(value, scenario)
+
+        if isinstance(value, dict):
+            return self._process_dict(value, scenario)
+
+        if isinstance(value, (int, float)):
+            return value
+
+        raise ValueError(f"Unexpected value type: {type(value)} for key '{key}'")
+
+    def _render_template(self, template: str, scenario: Dict[str, Any]) -> str:
+        """Render a single template string.
+
+        Args:
+            template: Template string to render
+            scenario: Current scenario
+
+        Returns:
+            Rendered template string
+        """
+        return self.env.from_string(template).render(scenario)
+
+    def _process_list(self, items: List[Any], scenario: Dict[str, Any]) -> List[Any]:
+        """Process all items in a list.
+
+        Args:
+            items: List of items to process
+            scenario: Current scenario
+
+        Returns:
+            List of processed items
+        """
+        return [
+            self._render_template(item, scenario) if isinstance(item, str) else item
+            for item in items
+        ]
+
+    def _process_dict(
+        self, data: Dict[str, Any], scenario: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Process all keys and values in a dictionary.
+
+        Args:
+            data: Dictionary to process
+            scenario: Current scenario
+
+        Returns:
+            Dictionary with processed keys and values
+        """
+        return {
+            (self._render_template(k, scenario) if isinstance(k, str) else k): (
+                self._render_template(v, scenario) if isinstance(v, str) else v
+            )
+            for k, v in data.items()
+        }
+
+
+# Usage example:
+"""
+from edsl import QuestionFreeText, ScenarioList
+
+question = QuestionFreeText(
+    question_text="What are your thoughts on: {{subject}}?",
+    question_name="base_{{subject}}"
+)
+processor = TemplateProcessor(question)
+scenarios = ScenarioList.from_list("subject", ["Math", "Economics", "Chemistry"])
+processed_questions = processor.process_templates(scenarios)
+"""

edsl/questions/prompt_templates/question_budget.jinja

@@ -0,0 +1,13 @@
+You are being asked the following question: {{question_text}}
+The options are:
+{% for option in question_options %}
+    {{ loop.index0 }}: {{option}}
+{% endfor %}                       
+Return a valid JSON formatted as follows, with a dictionary for your "answer" 
+where the keys are the option numbers and the values are the amounts you want 
+to allocate to the options, and the sum of the values is {{budget_sum}}:
+
+{"answer": {<put dict of option numbers and allocation amounts here>}, "comment": "<put explanation here>"}
+Example response for a budget of 100 and 4 options: 
+{"answer": {"0": 25, "1": 25, "2": 25, "3": 25}, "comment": "I allocated 25 to each option."}
+There must be an allocation listed for each item (including 0).

edsl/questions/prompt_templates/question_checkbox.jinja

@@ -0,0 +1,32 @@
+{# Question Presention #}
+{{question_text}}
+{% if use_code %}
+    {% for option in question_options %}
+        {{ loop.index0 }}: {{option}}
+    {% endfor %}
+{% else %}
+    {% for option in question_options %}
+        {{ option }}
+    {% endfor %}    
+{% endif %}
+
+{# Restrictions #}
+{% if min_selections != None and max_selections != None and min_selections == max_selections %}
+    You must select exactly {{min_selections}} options.
+{% elif min_selections != None and max_selections != None %}
+    Minimum number of options that must be selected: {{min_selections}}.
+    Maximum number of options that must be selected: {{max_selections}}.
+{% elif min_selections != None %}
+    Minimum number of options that must be selected: {{min_selections}}.
+{% elif max_selections != None %}
+    Maximum number of options that must be selected: {{max_selections}}.
+{% endif %}
+
+{# Answering Instructions #}
+Please respond with valid JSON, formatted like so:
+{% if include_comment %}
+    {"answer": [<put comma-separated list here>], "comment": "<put explanation here>"}
+{% else %}
+    {"answer": [<put comma-separated list here>]}
+{% endif %}
+