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

edsl/questions/prompt_templates/question_extract.jinja

@@ -0,0 +1,11 @@
+{{question_text}}
+
+Create an ANSWER should be formatted like this: 
+{{ answer_template }}
+
+It should have the same keys but values extracted from the input.
+If the value of a key is not present in the input, fill with "null".
+
+Return a valid JSON formatted like this:
+{"answer": <put your ANSWER here>}
+ONLY RETURN THE JSON, AND NOTHING ELSE.

edsl/questions/prompt_templates/question_free_text.jinja

@@ -0,0 +1,3 @@
+{{question_text}}
+Return a valid JSON formatted like this: 
+{"answer": "<put free text answer here>"}

edsl/questions/prompt_templates/question_linear_scale.jinja

@@ -0,0 +1,11 @@
+    {{question_text}}
+        {% for option in question_options %}
+            {{option}} : {{ option_labels.get(option, "") }}
+        {% endfor %}
+    Return a valid JSON formatted like this, selecting only the code of the option (codes start at 0):
+    {% if include_comment %}  
+        {"answer": <put answer code here>, "comment": <comment>} 
+    {% else %} 
+        {"answer": <put answer here>} 
+    {% endif %}
+    Only 1 option may be selected.

edsl/questions/prompt_templates/question_list.jinja

@@ -0,0 +1,17 @@
+{{question_text}}
+
+Your response should be only a valid JSON in the following format:
+{% if include_comment %}
+    {
+    "answer": [<comma-separated list of responsive words or phrases as independent strings>],
+    "comment": "<put comment here>"
+    }
+{% else %}
+    {
+    "answer": [<comma-separated list of responsive words or phrases as independent strings>],
+    }
+{% endif %}
+
+{% if max_list_items is not none %}
+The list must not contain more than {{ max_list_items }} items.
+{% endif %}

edsl/questions/prompt_templates/question_multiple_choice.jinja

@@ -0,0 +1,33 @@
+{# 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 %}
+
+Only 1 option may be selected.
+
+{# Answering Instructions #}
+Return a valid JSON formatted like this:
+
+{% if use_code %}
+    {% if include_comment %}
+        {"answer": <put answer code here>, "comment": "<put explanation here>"}
+    {% else %}
+        {"answer": <put answer code here>}
+    {% endif %}
+{% else %}
+
+    {% if include_comment %}
+        {"answer": <text of option>, "comment": "<put explanation here>"}
+    {% else %}
+        {"answer": <put option here>}
+    {% endif %}
+
+{% endif %}

edsl/questions/prompt_templates/question_numerical.jinja

@@ -0,0 +1,37 @@
+You are being asked a question that requires a numerical response 
+in the form of an integer or decimal (e.g., -12, 0, 1, 2, 3.45, ...).
+        
+Your response must be in the following format:
+
+{% if include_comment %}
+    {"answer": "<your numerical answer here>", "comment": "<your explanation here>"}
+{% else %}
+    {"answer": "<your numerical answer here>"}
+{% endif %}
+
+You must only include an integer or decimal in the quoted "answer" part of your response.
+        
+Here is an example of a valid response:
+{% if include_comment %}
+    {"answer": "100", "comment": "This is my explanation..."}
+{% else %}
+    {"answer": "100"}
+{% endif %}
+        
+Here is an example of a response that is invalid because the "answer" includes words:
+{"answer": "I don't know.", ...}
+
+If your response is equivalent to zero, your formatted response should look like this:
+{% if include_comment %}
+    {"answer": "0", "comment": "This is my explanation..."}
+{% else %}
+    {"answer": "0"}
+{% endif %}
+
+You are being asked the following question: {{question_text}}
+{% if min_value is not none %}
+    Minimum answer value: {{min_value}}
+{% endif %}
+{% if max_value is not none %}
+    Maximum answer value: {{max_value}}
+{% endif %}

edsl/questions/question_base_gen_mixin.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+import copy
+import itertools
+from typing import Optional, List, Callable, Type, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.questions.QuestionBase import QuestionBase
+    from edsl.scenarios.ScenarioList import ScenarioList
+
+
+class QuestionBaseGenMixin:
+    """Mixin for QuestionBase."""
+
+    def copy(self) -> QuestionBase:
+        """Return a deep copy of the question.
+
+        >>> from edsl.questions import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite color?")
+        >>> q2 = q.copy()
+        >>> q2.question_name
+        'color'
+
+        """
+        return copy.deepcopy(self)
+
+    def option_permutations(self) -> list[QuestionBase]:
+        """Return a list of questions with all possible permutations of the options.
+
+        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice as Q
+        >>> len(Q.example().option_permutations())
+        24
+        """
+
+        if not hasattr(self, "question_options"):
+            return [self]
+
+        questions = []
+        for index, permutation in enumerate(
+            itertools.permutations(self.question_options)
+        ):
+            question = copy.deepcopy(self)
+            question.question_options = list(permutation)
+            question.question_name = f"{self.question_name}_{index}"
+            questions.append(question)
+        return questions
+
+    def draw(self) -> "QuestionBase":
+        """Return a new question with a randomly selected permutation of the options.
+
+        If the question has no options, returns a copy of the original question.
+
+        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice as Q
+        >>> q = Q.example()
+        >>> drawn = q.draw()
+        >>> len(drawn.question_options) == len(q.question_options)
+        True
+        >>> q is drawn
+        False
+        """
+
+        if not hasattr(self, "question_options"):
+            return copy.deepcopy(self)
+
+        import random
+
+        question = copy.deepcopy(self)
+        question.question_options = list(
+            random.sample(self.question_options, len(self.question_options))
+        )
+        return question
+
+    def loop(self, scenario_list: ScenarioList) -> List[QuestionBase]:
+        """Return a list of questions with the question name modified for each scenario.
+
+        :param scenario_list: The list of scenarios to loop through.
+
+        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
+        >>> from edsl.scenarios.ScenarioList import ScenarioList
+        >>> q = QuestionFreeText(question_text = "What are your thoughts on: {{ subject}}?", question_name = "base_{{subject}}")
+        >>> len(q.loop(ScenarioList.from_list("subject", ["Math", "Economics", "Chemistry"])))
+        3
+        """
+        from edsl.questions.loop_processor import LoopProcessor
+
+        lp = LoopProcessor(self)
+        return lp.process_templates(scenario_list)
+
+    def render(self, replacement_dict: dict) -> "QuestionBase":
+        """Render the question components as jinja2 templates with the replacement dictionary.
+
+        :param replacement_dict: The dictionary of values to replace in the question components.
+
+        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite {{ thing }}?")
+        >>> q.render({"thing": "color"})
+        Question('free_text', question_name = \"""color\""", question_text = \"""What is your favorite color?\""")
+
+        """
+        from jinja2 import Environment
+        from edsl.scenarios.Scenario import Scenario
+
+        strings_only_replacement_dict = {
+            k: v for k, v in replacement_dict.items() if not isinstance(v, Scenario)
+        }
+
+        def render_string(value: str) -> str:
+            if value is None or not isinstance(value, str):
+                return value
+            else:
+                try:
+                    return (
+                        Environment()
+                        .from_string(value)
+                        .render(strings_only_replacement_dict)
+                    )
+                except Exception as e:
+                    import warnings
+
+                    warnings.warn("Failed to render string: " + value)
+                    # breakpoint()
+                    return value
+
+        return self.apply_function(render_string)
+
+    def apply_function(
+        self, func: Callable, exclude_components: List[str] = None
+    ) -> QuestionBase:
+        """Apply a function to the question parts
+
+        :param func: The function to apply to the question parts.
+        :param exclude_components: The components to exclude from the function application.
+
+        >>> from edsl.questions import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite color?")
+        >>> shouting = lambda x: x.upper()
+        >>> q.apply_function(shouting)
+        Question('free_text', question_name = \"""color\""", question_text = \"""WHAT IS YOUR FAVORITE COLOR?\""")
+
+        >>> q.apply_function(shouting, exclude_components = ["question_type"])
+        Question('free_text', question_name = \"""COLOR\""", question_text = \"""WHAT IS YOUR FAVORITE COLOR?\""")
+
+        """
+        from edsl.questions.QuestionBase import QuestionBase
+
+        if exclude_components is None:
+            exclude_components = ["question_name", "question_type"]
+
+        d = copy.deepcopy(self.to_dict(add_edsl_version=False))
+        for key, value in d.items():
+            if key in exclude_components:
+                continue
+            if isinstance(value, dict):
+                for k, v in value.items():
+                    value[k] = func(v)
+                d[key] = value
+                continue
+            if isinstance(value, list):
+                value = [func(v) for v in value]
+                d[key] = value
+                continue
+            d[key] = func(value)
+        return QuestionBase.from_dict(d)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/questions/question_registry.py

@@ -1,27 +1,44 @@
+"""This module provides a factory class for creating question objects."""
+
 import textwrap
+from uuid import UUID
+from typing import Any, Optional, Union
 
-from edsl.exceptions import QuestionSerializationError
-from edsl.exceptions import QuestionCreationValidationError
-from edsl.questions.Question import RegisterQuestionsMeta
 
-# from edsl.questions.QuestionFreeText import QuestionFreeText
-# registry = RegisterQuestionsMeta.get_registered_classes()
-# q2c = RegisterQuestionsMeta.question_names_to_classes()
+from edsl.questions.QuestionBase import RegisterQuestionsMeta
 
 
 class Meta(type):
+    """Metaclass for QuestionBase that provides a __repr__ method that lists all available questions."""
+
     def __repr__(cls):
-        lines = "\n".join(cls.available())
-        return textwrap.dedent(
-            f"""\
-        Available questions: 
-        {lines}        
-        """
+        """Return a string that lists all available questions."""
+
+        s = textwrap.dedent(
+            """
+        You can use the Question class to create objects by name. 
+        For example, to create a multiple choice question, you can do:
+
+        >>> from edsl import Question
+        >>> q = Question('multiple_choice', question_text='What is your favorite color?', question_name='color')
+        
+        Question Types:\n"""
         )
+        for question_type, question_class in cls.available(
+            show_class_names=True
+        ).items():
+            line_info = (
+                f"{question_type} ({question_class.__name__}): {question_class.__doc__}"
+            )
+            s += line_info + "\n"
+        return s
 
 
-class QuestionBase(metaclass=Meta):
+class Question(metaclass=Meta):
+    """Factory class for creating question objects."""
+
     def __new__(cls, question_type, *args, **kwargs):
+        """Create a new question object."""
         get_question_classes = RegisterQuestionsMeta.question_types_to_classes()
 
         subclass = get_question_classes.get(question_type, None)
@@ -36,11 +53,97 @@ class QuestionBase(metaclass=Meta):
         return instance
 
     @classmethod
-    def available(cls):
-        return list(RegisterQuestionsMeta.question_types_to_classes().keys())
+    def example(cls, question_type: str):
+        """Return an example question of the given type."""
+        get_question_classes = RegisterQuestionsMeta.question_types_to_classes()
+        q = get_question_classes.get(question_type, None)
+        return q.example()
+
+    @classmethod
+    def pull(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+        """Pull the object from coop."""
+        from edsl.coop import Coop
+
+        coop = Coop()
+        return coop.get(uuid, url, "question")
+
+    @classmethod
+    def delete(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+        """Delete the object from coop."""
+        from edsl.coop import Coop
+
+        coop = Coop()
+        return coop.delete(uuid, url)
+
+    @classmethod
+    def patch(
+        cls,
+        uuid: Optional[Union[str, UUID]] = None,
+        url: Optional[str] = None,
+        description: Optional[str] = None,
+        value: Optional[Any] = None,
+        visibility: Optional[str] = None,
+    ):
+        """Patch the object on coop."""
+        from edsl.coop import Coop
+
+        coop = Coop()
+        return coop.patch(uuid, url, description, value, visibility)
+
+    @classmethod
+    def list_question_types(cls):
+        """Return a list of available question types.
+
+        >>> from edsl import Question
+        >>> Question.list_question_types()
+        ['checkbox', 'dict', 'extract', 'free_text', 'functional', 'likert_five', 'linear_scale', 'list', 'matrix', 'multiple_choice', 'numerical', 'rank', 'top_k', 'yes_no']
+        """
+        return [
+            q
+            for q in sorted(
+                list(RegisterQuestionsMeta.question_types_to_classes().keys())
+            )
+            if q not in ["budget"]
+        ]
+
+    @classmethod
+    def available(cls, show_class_names: bool = False) -> Union[list, dict]:
+        """Return a list of available question types.
+
+        :param show_class_names: If True, return a dictionary of question types to class names. If False, return a set of question types.
+
+        Example usage:
+
+        """
+        from edsl.results.Dataset import Dataset
+
+        exclude = ["budget"]
+        if show_class_names:
+            return RegisterQuestionsMeta.question_types_to_classes()
+        else:
+            question_list = [
+                q
+                for q in sorted(
+                    set(RegisterQuestionsMeta.question_types_to_classes().keys())
+                )
+                if q not in exclude
+            ]
+            d = RegisterQuestionsMeta.question_types_to_classes()
+            question_classes = [d[q] for q in question_list]
+            example_questions = [repr(q.example()) for q in question_classes]
+
+            return Dataset(
+                [
+                    {"question_type": [q for q in question_list]},
+                    {"question_class": [q.__name__ for q in question_classes]},
+                    {"example_question": example_questions},
+                ],
+                print_parameters={"containerHeight": "auto"},
+            )
 
 
 def get_question_class(question_type):
+    """Return the class for the given question type."""
     q2c = RegisterQuestionsMeta.question_types_to_classes()
     if question_type not in q2c:
         raise ValueError(
@@ -49,45 +152,26 @@ def get_question_class(question_type):
     return q2c.get(question_type)
 
 
-# all question types must be registered here
-# the key is the question type
-# the value is a tuple of the module name and the class name
-# CLASS_REGISTRY = {
-#     "budget": ("edsl.questions.QuestionBudget", "QuestionBudget"),
-#     "checkbox": ("edsl.questions.QuestionCheckBox", "QuestionCheckBox"),
-#     "extract": ("edsl.questions.QuestionExtract", "QuestionExtract"),
-#     "free_text": ("edsl.questions.QuestionFreeText", "QuestionFreeText"),
-#     "functional": ("edsl.questions.QuestionFunctional", "QuestionFunctional"),
-#     "likert_five": ("edsl.questions.derived.QuestionLikertFive", "QuestionLikertFive"),
-#     "linear_scale": (
-#         "edsl.questions.derived.QuestionLinearScale",
-#         "QuestionLinearScale",
-#     ),
-#     "list": ("edsl.questions.QuestionList", "QuestionList"),
-#     "multiple_choice": (
-#         "edsl.questions.QuestionMultipleChoice",
-#         "QuestionMultipleChoice",
-#     ),
-#     "numerical": ("edsl.questions.QuestionNumerical", "QuestionNumerical"),
-#     "rank": ("edsl.questions.QuestionRank", "QuestionRank"),
-#     "top_k": ("edsl.questions.derived.QuestionTopK", "QuestionTopK"),
-#     "yes_no": ("edsl.questions.derived.QuestionYesNo", "QuestionYesNo"),
-# }
-
 question_purpose = {
     "multiple_choice": "When options are known and limited",
     "free_text": "When options are unknown or unlimited",
     "checkbox": "When multiple options can be selected",
     "numerical": "When the answer is a single numerical value e.g., a float",
-    "linear_scale": "When options are text, but can be ordered e.g., daily, weekly, monthly, etc.",
+    "linear_scale": "When options are text, but can be ordered, e.g., daily, weekly, monthly, etc.",
     "yes_no": "When the question can be fully answered with either a yes or a no",
+    "list": "When the answer should be a list of items",
+    "rank": "When the answer should be a ranked list of items",
+    "budget": "When the answer should be an amount allocated among a set of options",
+    "top_k": "When the answer should be a list of the top k items",
+    "likert_five": "When the answer should be a value on the Likert scale from 1 to 5",
+    "extract": "When the answer should be information extracted or extrapolated from a text in a given format",
 }
 
 
 if __name__ == "__main__":
-    print(QuestionBase.available())
+    print(Question.available())
+
+    # q = Question("free_text", question_text="How are you doing?", question_name="test")
+    # results = q.run()
 
-    q = QuestionBase(
-        "free_text", question_text="How are you doing?", question_name="test"
-    )
-    results = q.run()
+    q = Question.pull(id=76)

edsl/questions/register_questions_meta.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from abc import ABCMeta
+
+from edsl.enums import QuestionType
+from edsl.exceptions.questions import QuestionMissingTypeError, QuestionBadTypeError
+
+import inspect
+
+
+class RegisterQuestionsMeta(ABCMeta):
+    """Metaclass to register output elements in a registry i.e., those that have a parent."""
+
+    _registry = {}  # Initialize the registry as a dictionary
+
+    def __init__(cls, name, bases, dct):
+        """Initialize the class and adds it to the registry if it's not the base class."""
+        super(RegisterQuestionsMeta, cls).__init__(name, bases, dct)
+        if (
+            name != "QuestionBase"
+            and name != "QuestionFunctional"
+            and name != "QuestionAddTwoNumbers"
+        ):
+            ## Enforce that all questions have a question_type class attribute
+            ## and it comes from our enum of valid question types.
+            required_attributes = [
+                "question_type",
+                "_response_model",
+                "response_validator_class",
+            ]
+            for attr in required_attributes:
+                if not hasattr(cls, attr):
+                    raise QuestionMissingTypeError(
+                        f"Question must have a {attr} class attribute"
+                    )
+
+            init_signature = inspect.signature(cls.__init__)
+            init_params = [p for p in init_signature.parameters if p != "self"]
+            required_params = [
+                "question_presentation",
+                "answering_instructions",
+                "question_name",
+                "question_text",
+            ]
+            for param in required_params:
+                if param not in init_params:
+                    raise QuestionBadTypeError(
+                        f"Question type {name} must have a question_presentation parameter in its __init__ method"
+                    )
+
+        if name != "QuestionBase":
+            RegisterQuestionsMeta._registry[name] = cls
+
+    @classmethod
+    def get_registered_classes(cls):
+        """Return the registry of registered classes."""
+        return cls._registry
+
+    @classmethod
+    def question_types_to_classes(
+        cls,
+    ):
+        """Return a dictionary of question types to classes."""
+        d = {}
+        for classname, cls in cls._registry.items():
+            if hasattr(cls, "question_type"):
+                d[cls.question_type] = cls
+            else:
+                raise Exception(
+                    f"Class {classname} does not have a question_type class attribute"
+                )
+        return d