edsl 0.1.49__py3-none-any.whl → 0.1.50__py3-none-any.whl

edsl/questions/question_list.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 import json
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, ForwardRef
 
 from pydantic import Field
 from json_repair import repair_json
-
 from .exceptions import QuestionAnswerValidationError
 from .question_base import QuestionBase
 from .descriptors import IntegerOrNoneDescriptor
 from .decorators import inject_exception
 from .response_validator_abc import ResponseValidatorABC
 
+# Forward reference for function return type annotation
+ListResponse = ForwardRef("ListResponse")
+
 def convert_string(s: str) -> Union[float, int, str, dict]:
     """Convert a string to a more appropriate type if possible.
 
@@ -54,10 +56,10 @@ def convert_string(s: str) -> Union[float, int, str, dict]:
     return s
 
 
-def create_model(max_list_items: int, permissive: bool) -> "ListResponse":
+def create_model(min_list_items: Optional[int], max_list_items: Optional[int], permissive: bool) -> "ListResponse":
     from pydantic import BaseModel
 
-    if permissive or max_list_items is None:
+    if permissive or (max_list_items is None and min_list_items is None):
 
         class ListResponse(BaseModel):
             answer: list[Any]
@@ -65,6 +67,14 @@ def create_model(max_list_items: int, permissive: bool) -> "ListResponse":
             generated_tokens: Optional[str] = None
 
     else:
+        # Determine field constraints
+        field_kwargs = {"...": None}
+        
+        if min_list_items is not None:
+            field_kwargs["min_items"] = min_list_items
+            
+        if max_list_items is not None:
+            field_kwargs["max_items"] = max_list_items
 
         class ListResponse(BaseModel):
             """
@@ -73,7 +83,7 @@ def create_model(max_list_items: int, permissive: bool) -> "ListResponse":
             {'answer': ['Apple', 'Cherry'], 'comment': None, 'generated_tokens': None}
             """
 
-            answer: list[Any] = Field(..., min_items=0, max_items=max_list_items)
+            answer: list[Any] = Field(**field_kwargs)
             comment: Optional[str] = None
             generated_tokens: Optional[str] = None
 
@@ -81,7 +91,7 @@ def create_model(max_list_items: int, permissive: bool) -> "ListResponse":
 
 
 class ListResponseValidator(ResponseValidatorABC):
-    required_params = ["max_list_items", "permissive"]
+    required_params = ["min_list_items", "max_list_items", "permissive"]
     valid_examples = [({"answer": ["hello", "world"]}, {"max_list_items": 5})]
 
     invalid_examples = [
@@ -90,6 +100,11 @@ class ListResponseValidator(ResponseValidatorABC):
             {"max_list_items": 5},
             "Too many items.",
         ),
+        (
+            {"answer": ["hello"]},
+            {"min_list_items": 2},
+            "Too few items.",
+        ),
     ]
 
     def _check_constraints(self, response) -> None:
@@ -98,6 +113,12 @@ class ListResponseValidator(ResponseValidatorABC):
             and len(response.answer) > self.max_list_items
         ):
             raise QuestionAnswerValidationError("Too many items.")
+            
+        if (
+            self.min_list_items is not None
+            and len(response.answer) < self.min_list_items
+        ):
+            raise QuestionAnswerValidationError("Too few items.")
 
     def fix(self, response, verbose=False):
         if verbose:
@@ -122,6 +143,7 @@ class QuestionList(QuestionBase):
 
     question_type = "list"
     max_list_items: int = IntegerOrNoneDescriptor()
+    min_list_items: int = IntegerOrNoneDescriptor()
     _response_model = None
     response_validator_class = ListResponseValidator
 
@@ -131,6 +153,7 @@ class QuestionList(QuestionBase):
         question_text: str,
         include_comment: bool = True,
         max_list_items: Optional[int] = None,
+        min_list_items: Optional[int] = None,
         answering_instructions: Optional[str] = None,
         question_presentation: Optional[str] = None,
         permissive: bool = False,
@@ -140,12 +163,14 @@ class QuestionList(QuestionBase):
         :param question_name: The name of the question.
         :param question_text: The text of the question.
         :param max_list_items: The maximum number of items that can be in the answer list.
+        :param min_list_items: The minimum number of items that must be in the answer list.
 
         >>> QuestionList.example().self_check()
         """
         self.question_name = question_name
         self.question_text = question_text
         self.max_list_items = max_list_items
+        self.min_list_items = min_list_items
         self.permissive = permissive
 
         self.include_comment = include_comment
@@ -153,7 +178,7 @@ class QuestionList(QuestionBase):
         self.question_presentations = question_presentation
 
     def create_response_model(self):
-        return create_model(self.max_list_items, self.permissive)
+        return create_model(self.min_list_items, self.max_list_items, self.permissive)
 
     @property
     def question_html_content(self) -> str:
@@ -183,7 +208,7 @@ class QuestionList(QuestionBase):
     @classmethod
     @inject_exception
     def example(
-        cls, include_comment=True, max_list_items=None, permissive=False
+        cls, include_comment=True, max_list_items=None, min_list_items=None, permissive=False
     ) -> QuestionList:
         """Return an example of a list question."""
         return cls(
@@ -191,6 +216,7 @@ class QuestionList(QuestionBase):
             question_text="What are your favorite foods?",
             include_comment=include_comment,
             max_list_items=max_list_items,
+            min_list_items=min_list_items,
             permissive=permissive,
         )
 
@@ -199,10 +225,11 @@ def main():
     """Create an example of a list question and demonstrate its functionality."""
     from edsl.questions import QuestionList
 
-    q = QuestionList.example(max_list_items=5)
+    q = QuestionList.example(max_list_items=5, min_list_items=2)
     q.question_text
     q.question_name
     q.max_list_items
+    q.min_list_items
     # validate an answer
     q._validate_answer({"answer": ["pasta", "garlic", "oil", "parmesan"]})
     # translate answer code

edsl/questions/question_matrix.py

@@ -1,9 +1,26 @@
+"""
+question_matrix.py
+
+Drop-in replacement for `QuestionMatrix` with a dynamic Pydantic approach
+that automatically raises ValidationError for invalid matrix answers.
+"""
+
 from __future__ import annotations
-from typing import Union, Optional, Dict, List, Any
+from typing import (
+    Union,
+    Optional,
+    Dict,
+    List,
+    Any,
+    Type,
+    get_args,
+    Literal
+)
+import random
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, create_model, ValidationError
 from jinja2 import Template
-import random
+
 from .question_base import QuestionBase
 from .descriptors import (
     QuestionOptionsDescriptor,
@@ -14,8 +31,8 @@ from .response_validator_abc import ResponseValidatorABC
 from .decorators import inject_exception
 
 from .exceptions import (
-    QuestionAnswerValidationError,
     QuestionCreationValidationError,
+    QuestionAnswerValidationError,  # If you still want to raise custom exceptions
 )
 
 
@@ -23,47 +40,56 @@ 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
+) -> Type[BaseModel]:
     """
+    Create a dynamic Pydantic model for matrix questions.
 
-    if permissive:
-
-        class MatrixResponse(BaseModel):
-            answer: Dict[str, Any]
-            comment: Optional[str] = None
-            generated_tokens: Optional[Any] = None
+    If `permissive=False`, each item is a required field with a `Literal[...]` type
+    so that only the given question_options are allowed.
+    If `permissive=True`, each item can have any value, and extra items are allowed.
+    """
 
+    # If non-permissive, build a Literal for each valid option
+    # e.g. Literal[1,2,3] or Literal["Yes","No"] or a mix
+    if not permissive:
+        # If question_options is empty (edge case), fall back to 'Any'
+        if question_options:
+            AllowedOptions = Literal[tuple(question_options)]  # type: ignore
+        else:
+            AllowedOptions = Any
     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
+        # Permissive => let each item be anything
+        AllowedOptions = Any
+
+    # Build field definitions for an "AnswerSubModel", where each
+    # question_item is a required field with type AllowedOptions
+    field_definitions = {}
+    for item in question_items:
+        field_definitions[item] = (AllowedOptions, Field(...))  # required
+
+    # Dynamically create the submodel
+    MatrixAnswerSubModel = create_model(
+        "MatrixAnswerSubModel",
+        __base__=BaseModel,
+        **field_definitions
+    )
+
+    # Build the top-level model with `answer` + optional `comment`
+    class MatrixResponse(BaseModel):
+        answer: MatrixAnswerSubModel
+        comment: Optional[str] = None
+        generated_tokens: Optional[Any] = None
+
+        class Config:
+            # If permissive=False, forbid extra items in `answer`.
+            # If permissive=True, allow them.
+            extra = "allow" if permissive else "forbid"
 
     return MatrixResponse
 
 
 class MatrixResponseValidator(ResponseValidatorABC):
+    """Optional placeholder validator, if still needed for example/fixing logic."""
     required_params = ["question_items", "question_options", "permissive"]
 
     valid_examples = [
@@ -96,6 +122,10 @@ class MatrixResponseValidator(ResponseValidatorABC):
     ]
 
     def fix(self, response, verbose=False):
+        """
+        Example fix() method to try and repair a partially invalid response.
+        (This logic is carried over from your original code.)
+        """
         if verbose:
             print(f"Fixing matrix response: {response}")
 
@@ -111,12 +141,10 @@ class MatrixResponseValidator(ResponseValidatorABC):
                     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
+                    if mapped_answer:
                         return {"answer": mapped_answer}
-            except:
-                pass
+            except (ValueError, KeyError, TypeError):
+                pass  # Just continue
 
         # If answer uses numeric keys, map them to question items
         if "answer" in response and isinstance(response["answer"], dict):
@@ -125,14 +153,21 @@ class MatrixResponseValidator(ResponseValidatorABC):
                 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
+                if mapped_answer:
                     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."""
+    """
+    A question that presents a matrix/grid where multiple items are rated
+    or selected from the same set of options.
+
+    This version dynamically builds a Pydantic model at runtime
+    (via `create_matrix_response`) and automatically raises ValidationError
+    if the user provides an invalid or incomplete answer.
+    """
 
     question_type = "matrix"
     question_text: str = QuestionTextDescriptor()
@@ -155,18 +190,19 @@ class QuestionMatrix(QuestionBase):
         question_presentation: Optional[str] = None,
         permissive: bool = False,
     ):
-        """Initialize a matrix question.
+        """
+        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
+            question_items: List of items to be rated or answered
+            question_options: Possible answer options (e.g., [1,2,3] or ["Yes","No"])
+            option_labels: Optional mapping of options to labels (e.g. {1: "Sad", 5: "Happy"})
             include_comment: Whether to include a comment field
-            answering_instructions: Optional custom instructions
-            question_presentation: Optional custom presentation
-            permissive: Whether to strictly validate responses
+            answering_instructions: Custom instructions
+            question_presentation: Custom presentation
+            permissive: Whether to allow any values & extra items instead of strictly checking
         """
         self.question_name = question_name
 
@@ -186,9 +222,14 @@ class QuestionMatrix(QuestionBase):
         self.question_presentation = question_presentation
         self.permissive = permissive
 
-    def create_response_model(self):
+    def create_response_model(self) -> Type[BaseModel]:
+        """
+        Returns the pydantic model that will parse/validate a user answer.
+        """
         return create_matrix_response(
-            self.question_items, self.question_options, self.permissive
+            self.question_items,
+            self.question_options,
+            self.permissive
         )
 
     @property
@@ -225,7 +266,6 @@ class QuestionMatrix(QuestionBase):
         </table>
         """
         )
-
         return template.render(
             question_name=self.question_name,
             question_items=self.question_items,
@@ -256,11 +296,5 @@ class QuestionMatrix(QuestionBase):
             "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/question_multiple_choice.py

@@ -4,7 +4,6 @@ from typing import Union, Literal, Optional, List, Any
 from jinja2 import Template
 from pydantic import BaseModel, Field
 
-from ..scenarios import Scenario
 from .question_base import QuestionBase
 from .descriptors import QuestionOptionsDescriptor
 from .decorators import inject_exception
@@ -314,7 +313,8 @@ class QuestionMultipleChoice(QuestionBase):
 
             if potential_replacement is None:
                 # Nope - maybe it's in the substition dict?
-                raise ValueError(
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(
                     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}'."
@@ -353,11 +353,13 @@ class QuestionMultipleChoice(QuestionBase):
             try:
                 return translated_options[int(answer_code)]
             except IndexError:
-                raise ValueError(
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(
                     f"Answer code is out of range. The answer code index was: {int(answer_code)}. The options were: {translated_options}."
                 )
             except TypeError:
-                raise ValueError(
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(
                     f"The answer code was: '{answer_code}.'",
                     f"The options were: '{translated_options}'.",
                 )

edsl/questions/question_numerical.py

@@ -1,11 +1,9 @@
 from __future__ import annotations
 
-from random import uniform
-from typing import Any, Optional, Union, Literal
+from typing import Any, Optional, Union
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field
 
-from .exceptions import QuestionAnswerValidationError
 from .question_base import QuestionBase
 from .descriptors import NumericalOrNoneDescriptor
 from .decorators import inject_exception

edsl/questions/question_registry.py

@@ -42,7 +42,8 @@ class Question(metaclass=Meta):
 
         subclass = get_question_classes.get(question_type, None)
         if subclass is None:
-            raise ValueError(
+            from .exceptions import QuestionValueError
+            raise QuestionValueError(
                 f"No question registered with question_type {question_type}"
             )
 
@@ -144,7 +145,8 @@ 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(
+        from .exceptions import QuestionValueError
+        raise QuestionValueError(
             f"The question type, {question_type}, is not recognized. Recognied types are: {q2c.keys()}"
         )
     return q2c.get(question_type)

edsl/questions/register_questions_meta.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 from abc import ABCMeta
 import inspect
 
-from ..enums import QuestionType
 from .exceptions import QuestionMissingTypeError, QuestionBadTypeError
 
 class RegisterQuestionsMeta(ABCMeta):

edsl/questions/response_validator_abc.py

@@ -1,7 +1,7 @@
-from abc import ABC, abstractmethod
-from typing import Optional, Any, List, TypedDict, TYPE_CHECKING
+from abc import ABC
+from typing import Optional, List, TYPE_CHECKING
 
-from pydantic import BaseModel, Field, field_validator, ValidationError
+from pydantic import BaseModel, ValidationError
 
 from .exceptions import QuestionAnswerValidationError
 from .ExceptionExplainer import ExceptionExplainer
@@ -22,7 +22,8 @@ class ResponseValidatorABC(ABC):
         required_class_vars = ["required_params", "valid_examples", "invalid_examples"]
         for var in required_class_vars:
             if not hasattr(cls, var):
-                raise ValueError(f"Class {cls.__name__} must have a '{var}' attribute.")
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(f"Class {cls.__name__} must have a '{var}' attribute.")
 
     def __init__(
         self,
@@ -41,7 +42,8 @@ class ResponseValidatorABC(ABC):
             param for param in self.required_params if param not in kwargs
         ]
         if missing_params:
-            raise ValueError(
+            from .exceptions import QuestionValueError
+            raise QuestionValueError(
                 f"Missing required parameters: {', '.join(missing_params)}"
             )
 
@@ -98,20 +100,12 @@ class ResponseValidatorABC(ABC):
         {'answer': 42, 'comment': None, 'generated_tokens': None}
         >>> rv.max_value
         86.7
-        >>> rv.validate({"answer": "120"})
-        Traceback (most recent call last):
-        ...
-        edsl.questions.exceptions.QuestionAnswerValidationError:...
         >>> from edsl import QuestionNumerical
         >>> q = QuestionNumerical.example()
         >>> q.permissive = True
         >>> rv = q.response_validator
         >>> rv.validate({"answer": "120"})
         {'answer': 120, 'comment': None, 'generated_tokens': None}
-        >>> rv.validate({"answer": "poo"})
-        Traceback (most recent call last):
-        ...
-        edsl.questions.exceptions.QuestionAnswerValidationError:...
         """
         proposed_edsl_answer_dict = self._preprocess(raw_edsl_answer_dict)
         try:

edsl/questions/templates/dict/answering_instructions.jinja

@@ -1,4 +1,5 @@
 Please respond with a dictionary using the following keys: {{ answer_keys | join(', ') }}.
+Do not include "python" for create a code block. Just return the dictionary.
 
 {% if value_descriptions %}
 Here are descriptions of the values to provide:

edsl/questions/templates/rank/question_presentation.jinja

@@ -11,5 +11,5 @@ The options are:
 {% endfor %}
 {% endif %}
 {% if num_selections %}
-You can inlcude up to {{num_selections}} options in your answer.
+You have to include {{num_selections}} options in your answer.
 {% endif %}

edsl/results/__init__.py

@@ -2,4 +2,4 @@
 from .results import Results
 from .result import Result
 
-__all__ = ["Results"]
+__all__ = ["Results", "Result"]