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

edsl/questions/QuestionMatrix.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+from typing import Union, Optional, Dict, List, Any
+
+from pydantic import BaseModel, Field, field_validator
+from jinja2 import Template
+import random
+from edsl.questions.QuestionBase import QuestionBase
+from edsl.questions.descriptors import (
+    QuestionOptionsDescriptor,
+    OptionLabelDescriptor,
+    QuestionTextDescriptor,
+)
+from edsl.questions.response_validator_abc import ResponseValidatorABC
+from edsl.questions.decorators import inject_exception
+from edsl.exceptions.questions import (
+    QuestionAnswerValidationError,
+    QuestionCreationValidationError,
+)
+
+
+def create_matrix_response(
+    question_items: List[str],
+    question_options: List[Union[int, str, float]],
+    permissive: bool = False,
+):
+    """Create a response model for matrix questions.
+
+    The response model validates that:
+    1. All question items are answered
+    2. Each answer is from the allowed options
+    """
+
+    if permissive:
+
+        class MatrixResponse(BaseModel):
+            answer: Dict[str, Any]
+            comment: Optional[str] = None
+            generated_tokens: Optional[Any] = None
+
+    else:
+
+        class MatrixResponse(BaseModel):
+            answer: Dict[str, Union[int, str, float]] = Field(
+                ..., description="Mapping of items to selected options"
+            )
+            comment: Optional[str] = None
+            generated_tokens: Optional[Any] = None
+
+            @field_validator("answer")
+            def validate_answer(cls, v, values, **kwargs):
+                # Check that all items have responses
+                if not all(item in v for item in question_items):
+                    missing = set(question_items) - set(v.keys())
+                    raise ValueError(f"Missing responses for items: {missing}")
+
+                # Check that all responses are valid options
+                if not all(answer in question_options for answer in v.values()):
+                    invalid = [ans for ans in v.values() if ans not in question_options]
+                    raise ValueError(f"Invalid options selected: {invalid}")
+                return v
+
+    return MatrixResponse
+
+
+class MatrixResponseValidator(ResponseValidatorABC):
+    required_params = ["question_items", "question_options", "permissive"]
+
+    valid_examples = [
+        (
+            {"answer": {"Item1": 1, "Item2": 2}},
+            {
+                "question_items": ["Item1", "Item2"],
+                "question_options": [1, 2, 3],
+            },
+        )
+    ]
+
+    invalid_examples = [
+        (
+            {"answer": {"Item1": 1}},
+            {
+                "question_items": ["Item1", "Item2"],
+                "question_options": [1, 2, 3],
+            },
+            "Missing responses for some items",
+        ),
+        (
+            {"answer": {"Item1": 4, "Item2": 5}},
+            {
+                "question_items": ["Item1", "Item2"],
+                "question_options": [1, 2, 3],
+            },
+            "Invalid options selected",
+        ),
+    ]
+
+    def fix(self, response, verbose=False):
+        if verbose:
+            print(f"Fixing matrix response: {response}")
+
+        # If we have generated tokens, try to parse them
+        if "generated_tokens" in response:
+            try:
+                import json
+
+                fixed = json.loads(response["generated_tokens"])
+                if isinstance(fixed, dict):
+                    # Map numeric keys to question items
+                    mapped_answer = {}
+                    for idx, item in enumerate(self.question_items):
+                        if str(idx) in fixed:
+                            mapped_answer[item] = fixed[str(idx)]
+                    if (
+                        mapped_answer
+                    ):  # Only return if we successfully mapped some answers
+                        return {"answer": mapped_answer}
+            except:
+                pass
+
+        # If answer uses numeric keys, map them to question items
+        if "answer" in response and isinstance(response["answer"], dict):
+            if all(str(key).isdigit() for key in response["answer"].keys()):
+                mapped_answer = {}
+                for idx, item in enumerate(self.question_items):
+                    if str(idx) in response["answer"]:
+                        mapped_answer[item] = response["answer"][str(idx)]
+                if mapped_answer:  # Only update if we successfully mapped some answers
+                    response["answer"] = mapped_answer
+
+        return response
+
+
+class QuestionMatrix(QuestionBase):
+    """A question that presents a matrix/grid where multiple items are rated using the same scale."""
+
+    question_type = "matrix"
+    question_text: str = QuestionTextDescriptor()
+    question_items: List[str] = QuestionOptionsDescriptor()
+    question_options: List[Union[int, str, float]] = QuestionOptionsDescriptor()
+    option_labels: Optional[Dict[Union[int, str, float], str]] = OptionLabelDescriptor()
+
+    _response_model = None
+    response_validator_class = MatrixResponseValidator
+
+    def __init__(
+        self,
+        question_name: str,
+        question_text: str,
+        question_items: List[str],
+        question_options: List[Union[int, str, float]],
+        option_labels: Optional[Dict[Union[int, str, float], str]] = None,
+        include_comment: bool = True,
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+        permissive: bool = False,
+    ):
+        """Initialize a matrix question.
+
+        Args:
+            question_name: The name of the question
+            question_text: The text of the question
+            question_items: List of items to be rated
+            question_options: List of rating options
+            option_labels: Optional mapping of options to their labels
+            include_comment: Whether to include a comment field
+            answering_instructions: Optional custom instructions
+            question_presentation: Optional custom presentation
+            permissive: Whether to strictly validate responses
+        """
+        self.question_name = question_name
+
+        try:
+            self.question_text = question_text
+        except Exception as e:
+            raise QuestionCreationValidationError(
+                "question_text cannot be empty or too short!"
+            ) from e
+
+        self.question_items = question_items
+        self.question_options = question_options
+        self.option_labels = option_labels or {}
+
+        self.include_comment = include_comment
+        self.answering_instructions = answering_instructions
+        self.question_presentation = question_presentation
+        self.permissive = permissive
+
+    def create_response_model(self):
+        return create_matrix_response(
+            self.question_items, self.question_options, self.permissive
+        )
+
+    @property
+    def question_html_content(self) -> str:
+        """Generate HTML representation of the matrix question."""
+        template = Template(
+            """
+        <table class="matrix-question">
+            <tr>
+                <th></th>
+                {% for option in question_options %}
+                <th>
+                    {{ option }}
+                    {% if option in option_labels %}
+                    <br>
+                    <small>{{ option_labels[option] }}</small>
+                    {% endif %}
+                </th>
+                {% endfor %}
+            </tr>
+            {% for item in question_items %}
+            <tr>
+                <td>{{ item }}</td>
+                {% for option in question_options %}
+                <td>
+                    <input type="radio" 
+                           name="{{ question_name }}_{{ item }}" 
+                           value="{{ option }}"
+                           id="{{ question_name }}_{{ item }}_{{ option }}">
+                </td>
+                {% endfor %}
+            </tr>
+            {% endfor %}
+        </table>
+        """
+        )
+
+        return template.render(
+            question_name=self.question_name,
+            question_items=self.question_items,
+            question_options=self.question_options,
+            option_labels=self.option_labels,
+        )
+
+    @classmethod
+    @inject_exception
+    def example(cls) -> QuestionMatrix:
+        """Return an example matrix question."""
+        return cls(
+            question_name="child_happiness",
+            question_text="How happy would you be with different numbers of children?",
+            question_items=[
+                "No children",
+                "1 child",
+                "2 children",
+                "3 or more children",
+            ],
+            question_options=[1, 2, 3, 4, 5],
+            option_labels={1: "Very sad", 3: "Neutral", 5: "Extremely happy"},
+        )
+
+    def _simulate_answer(self) -> dict:
+        """Simulate a random valid answer."""
+        return {
+            "answer": {
+                item: random.choice(self.question_options)
+                for item in self.question_items
+            }
+        }
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/QuestionMultipleChoice.py

@@ -1,106 +1,330 @@
 from __future__ import annotations
-import random
-import textwrap
+from typing import Union, Literal, Optional, List, Any
+
 from jinja2 import Template
-from typing import Optional, Union
-from edsl.utilities import random_string
+from pydantic import BaseModel, Field
+
+from edsl.scenarios.Scenario import Scenario
+from edsl.questions.QuestionBase import QuestionBase
 from edsl.questions.descriptors import QuestionOptionsDescriptor
-from edsl.questions.Question import Question
-from edsl.scenarios import Scenario
+from edsl.questions.decorators import inject_exception
+from edsl.questions.response_validator_abc import ResponseValidatorABC
 
 
-class QuestionMultipleChoice(Question):
+def create_response_model(choices: List[str], permissive: bool = False):
+    """
+    Create a ChoiceResponse model class with a predefined list of choices.
+
+    :param choices: A list of allowed values for the answer field.
+    :param permissive: If True, any value will be accepted as an answer.
+    :return: A new Pydantic model class.
     """
-    This question asks the user to select one option from a list of options.
+    choice_tuple = tuple(choices)
+
+    if not permissive:
+
+        class ChoiceResponse(BaseModel):
+            answer: Literal[choice_tuple] = Field(description="Selected choice")
+            comment: Optional[str] = Field(None, description="Optional comment field")
+            generated_tokens: Optional[Any] = Field(
+                None, description="Generated tokens"
+            )
+
+            class Config:
+                @staticmethod
+                def json_schema_extra(schema: dict, model: BaseModel) -> None:
+                    for prop in schema.get("properties", {}).values():
+                        if prop.get("title") == "answer":
+                            prop["enum"] = choices
+
+    else:
+
+        class ChoiceResponse(BaseModel):
+            answer: Any = Field(description="Selected choice (can be any value)")
+            comment: Optional[str] = Field(None, description="Optional comment field")
+            generated_tokens: Optional[Any] = Field(
+                None, description="Generated tokens"
+            )
+
+            class Config:
+                @staticmethod
+                def json_schema_extra(schema: dict, model: BaseModel) -> None:
+                    for prop in schema.get("properties", {}).values():
+                        if prop.get("title") == "answer":
+                            prop["description"] += f". Suggested choices are: {choices}"
+                    schema["title"] += " (Permissive)"
+
+    return ChoiceResponse
+
+
+class MultipleChoiceResponseValidator(ResponseValidatorABC):
+    required_params = ["question_options", "use_code"]
+
+    def fix(self, response, verbose=False):
+        response_text = str(response.get("answer"))
+        if response_text is None:
+            response_text = response.get("generated_tokens", "")
 
-    Arguments:
-    - `question_name` is the name of the question (string)
-    - `question_options` are the options the user should select from (list of strings)
-    - `question_text` is the text of the question (string)
+        if verbose:
+            print(f"Invalid generated tokens was: {response_text}")
 
-    Optional arguments:
-    - `instructions` are the instructions for the question (string). If not provided, the default instructions are used. To view them, run `QuestionMultipleChoice.default_instructions`
-    - `short_names_dict` maps question_options to short names (dictionary mapping strings to strings)
+        matches = []
+        for idx, option in enumerate(self.question_options):
+            if verbose:
+                print("The options are: ", self.question_options)
+            if str(option) in response_text:
+                if verbose:
+                    print("Match found with option ", option)
+                if option not in matches:
+                    matches.append(option)
+
+        if verbose:
+            print("The matches are: ", matches)
+        if len(matches) == 1:
+            proposed_data = {
+                "answer": matches[0],
+                "generated_tokens": response.get("generated_tokens", None),
+            }
+            try:
+                self.response_model(**proposed_data)
+                return proposed_data
+            except Exception as e:
+                if verbose:
+                    print(f"Proposed solution {proposed_data} is invalid. Error: {e}")
+            return response
+
+    valid_examples = [
+        ({"answer": 1}, {"question_options": ["Good", "Great", "OK", "Bad"]})
+    ]
+
+    invalid_examples = [
+        (
+            {"answer": -1},
+            {"question_options": ["Good", "Great", "OK", "Bad"]},
+            "Answer code must be a non-negative integer",
+        ),
+        (
+            {"answer": None},
+            {"question_options": ["Good", "Great", "OK", "Bad"]},
+            "Answer code must not be missing.",
+        ),
+    ]
+
+
+class QuestionMultipleChoice(QuestionBase):
+    """This question prompts the agent to select one option from a list of options.
+
+    https://docs.expectedparrot.com/en/latest/questions.html#questionmultiplechoice-class
 
-    For an example, run `QuestionMultipleChoice.example()`
     """
 
     question_type = "multiple_choice"
     purpose = "When options are known and limited"
-    question_options: list[str] = QuestionOptionsDescriptor()
+    question_options: Union[list[str], list[list], list[float], list[int]] = (
+        QuestionOptionsDescriptor()
+    )
+    _response_model = None
+    response_validator_class = MultipleChoiceResponseValidator
 
     def __init__(
         self,
-        question_text: str,
-        question_options: list[str],
         question_name: str,
-        short_names_dict: Optional[dict[str, str]] = None,
+        question_text: str,
+        question_options: Union[list[str], list[list], list[float], list[int]],
+        include_comment: bool = True,
+        use_code: bool = False,
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+        permissive: bool = False,
     ):
+        """Instantiate a new QuestionMultipleChoice.
+
+        :param question_name: The name of the question.
+        :param question_text: The text of the question.
+        :param question_options: The options the agent should select from.
+        :param include_comment: Whether to include a comment field.
+        :param use_code: Whether to use code for the options.
+        :param answering_instructions: Instructions for the question.
+        :param question_presentation: The presentation of the question.
+        :param permissive: Whether to force the answer to be one of the options.
+
+        """
+        self.question_name = question_name
         self.question_text = question_text
         self.question_options = question_options
-        self.question_name = question_name
-        self.short_names_dict = short_names_dict or dict()
+
+        self._include_comment = include_comment
+        self.use_code = use_code
+        self.answering_instructions = answering_instructions
+        self.question_presentation = question_presentation
+        self.permissive = permissive
 
     ################
     # Answer methods
     ################
-    def validate_answer(
-        self, answer: dict[str, Union[str, int]]
-    ) -> dict[str, Union[str, int]]:
-        """Validates the answer"""
-        self.validate_answer_template_basic(answer)
-        self.validate_answer_multiple_choice(answer)
-        return answer
-
-    def translate_answer_code_to_answer(self, answer_code, scenario: Scenario = None):
-        """Translates the answer code to the actual answer."""
-        scenario = scenario or Scenario()
-        translated_options = [
-            Template(str(option)).render(scenario) for option in self.question_options
-        ]
-        return translated_options[int(answer_code)]
-
-    def simulate_answer(
-        self, human_readable: bool = True
-    ) -> dict[str, Union[int, str]]:
-        """Simulates a valid answer for debugging purposes"""
-        if human_readable:
-            answer = random.choice(self.question_options)
+
+    def create_response_model(self, replacement_dict: dict = None):
+        if replacement_dict is None:
+            replacement_dict = {}
+            # The replacement dict that could be from scenario, current answers, etc. to populate the response model
+
+        if self.use_code:
+            return create_response_model(
+                list(range(len(self.question_options))), self.permissive
+            )
+        else:
+            return create_response_model(self.question_options, self.permissive)
+
+    @staticmethod
+    def _translate_question_options(
+        question_options, substitution_dict: dict
+    ) -> list[str]:
+
+        if isinstance(question_options, str):
+            # If dynamic options are provided like {{ options }}, render them with the scenario
+            # We can check if it's in the Scenario.
+            from jinja2 import Environment, meta
+
+            env = Environment()
+            parsed_content = env.parse(question_options)
+            template_variables = list(meta.find_undeclared_variables(parsed_content))
+            # print("The template variables are: ", template_variables)
+            question_option_key = template_variables[0]
+            # We need to deal with possibility it's actually an answer to a question.
+            potential_replacement = substitution_dict.get(question_option_key, None)
+
+            if isinstance(potential_replacement, list):
+                # translated_options = potential_replacement
+                return potential_replacement
+
+            if isinstance(potential_replacement, QuestionBase):
+                if hasattr(potential_replacement, "answer") and isinstance(
+                    potential_replacement.answer, list
+                ):
+                    return potential_replacement.answer
+                    # translated_options = potential_replacement.answer
+
+            # if not isinstance(potential_replacement, list):
+            # translated_options = potential_replacement
+
+            if potential_replacement is None:
+                # Nope - maybe it's in the substition dict?
+                raise ValueError(
+                    f"Could not find the key '{question_option_key}' in the scenario."
+                    f"The substition dict was: '{substitution_dict}.'"
+                    f"The question options were: '{question_options}'."
+                )
+        else:
+            translated_options = [
+                Template(str(option)).render(substitution_dict)
+                for option in question_options
+            ]
+        return translated_options
+
+    def _translate_answer_code_to_answer(
+        self, answer_code: int, replacements_dict: Optional[dict] = None
+    ):
+        """Translate the answer code to the actual answer.
+
+        It is used to translate the answer code to the actual answer.
+        The question options might be templates, so they need to be rendered with the scenario.
+
+        >>> q = QuestionMultipleChoice.example()
+        >>> q._translate_answer_code_to_answer('Good', {})
+        'Good'
+
+        >>> q = QuestionMultipleChoice(question_name="how_feeling", question_text="How are you?", question_options=["{{emotion[0]}}", "emotion[1]"])
+        >>> q._translate_answer_code_to_answer('Happy', {"emotion": ["Happy", "Sad"]})
+        'Happy'
+
+        """
+        if replacements_dict is None:
+            replacements_dict = {}
+        translated_options = self._translate_question_options(
+            self.question_options, replacements_dict
+        )
+
+        if self._use_code:
+            try:
+                return translated_options[int(answer_code)]
+            except IndexError:
+                raise ValueError(
+                    f"Answer code is out of range. The answer code index was: {int(answer_code)}. The options were: {translated_options}."
+                )
+            except TypeError:
+                raise ValueError(
+                    f"The answer code was: '{answer_code}.'",
+                    f"The options were: '{translated_options}'.",
+                )
         else:
-            answer = random.choice(range(len(self.question_options)))
-        return {
-            "answer": answer,
-            "comment": random_string(),
-        }
+            # return translated_options[answer_code]
+            return answer_code
+
+    @property
+    def question_html_content(self) -> str:
+        """Return the HTML version of the question."""
+        if hasattr(self, "option_labels"):
+            option_labels = self.option_labels
+        else:
+            option_labels = {}
+        question_html_content = Template(
+            """
+        {% for option in question_options %} 
+        <div>
+        <input type="radio" id="{{ option }}" name="{{ question_name }}" value="{{ option }}">
+        <label for="{{ option }}">
+        {{ option }}
+        {% if option in option_labels %}
+        : {{ option_labels[option] }}
+        {% endif %}
+        </label>
+        </div>
+        {% endfor %}
+        """
+        ).render(
+            question_name=self.question_name,
+            question_options=self.question_options,
+            option_labels=option_labels,
+        )
+        return question_html_content
 
     ################
     # Example
     ################
     @classmethod
-    def example(cls) -> QuestionMultipleChoice:
+    @inject_exception
+    def example(cls, include_comment=False, use_code=False) -> QuestionMultipleChoice:
+        """Return an example instance."""
         return cls(
             question_text="How are you?",
             question_options=["Good", "Great", "OK", "Bad"],
             question_name="how_feeling",
-            short_names_dict={"Good": "g", "Great": "gr", "OK": "ok", "Bad": "b"},
+            include_comment=include_comment,
+            use_code=use_code,
         )
 
 
-def main():
-    from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
-
-    q = QuestionMultipleChoice.example()
-    q.question_text
-    q.question_options
-    q.question_name
-    q.short_names_dict
-    # validate an answer
-    q.validate_answer({"answer": 0, "comment": "I like custard"})
-    # translate answer code
-    q.translate_answer_code_to_answer(0, {})
-    # simulate answer
-    q.simulate_answer()
-    q.simulate_answer(human_readable=False)
-    # serialization (inherits from Question)
-    q.to_dict()
-    assert q.from_dict(q.to_dict()) == q
+# def main():
+#     """Create an example QuestionMultipleChoice and test its methods."""
+#     from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
+
+#     q = QuestionMultipleChoice.example()
+#     q.question_text
+#     q.question_options
+#     q.question_name
+#     # validate an answer
+#     q._validate_answer({"answer": 0, "comment": "I like custard"})
+#     # translate answer code
+#     q._translate_answer_code_to_answer(0, {})
+#     # simulate answer
+#     q._simulate_answer()
+#     q._simulate_answer(human_readable=False)
+#     # serialization (inherits from Question)
+#     q.to_dict()
+#     assert q.from_dict(q.to_dict()) == q
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)