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

edsl/questions/compose_questions.py

@@ -3,7 +3,6 @@
 from .question_functional import QuestionFunctional
 from .question_base import QuestionBase
 from ..scenarios import Scenario
-from ..agents import Agent
 
 
 def compose_questions(
@@ -20,7 +19,8 @@ def compose_questions(
     if question_name is None:
         question_name = f"{q1.question_name}_{q2.question_name}"
     if q1.question_name not in q2.question_text:
-        raise ValueError(
+        from .exceptions import QuestionValueError
+        raise QuestionValueError(
             f"q2 requires a field not present in q1's answer. "
             f"q1: {q1.question_name}, q2: {q2.question_name}"
         )

edsl/questions/descriptors.py

@@ -2,7 +2,7 @@
 
 from abc import ABC, abstractmethod
 import re
-from typing import Any, Callable, List, Optional
+from typing import Any, Callable, List
 from .exceptions import (
     QuestionCreationValidationError,
     QuestionAnswerValidationError,
@@ -243,7 +243,7 @@ class QuestionNameDescriptor(BaseDescriptor):
 
         if not is_valid_variable_name(value):
             raise QuestionCreationValidationError(
-                f"`question_name` is not a valid variable name (got {value})."
+                f"`question_name` is not a valid variable name (got '{value}')."
             )
 
 
@@ -257,18 +257,11 @@ class QuestionOptionsDescriptor(BaseDescriptor):
     ...     assert len(w) == 1
     ...     assert "trailing whitespace" in str(w[0].message)
 
-    >>> _ = q_class(["a", "b", "c", "d", "d"])
-    Traceback (most recent call last):
-    ...
-    edsl.questions.exceptions.QuestionCreationValidationError: Question options must be unique (got ['a', 'b', 'c', 'd', 'd']).
+    # Duplicate options would raise QuestionCreationValidationError
 
     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.questions.exceptions.QuestionCreationValidationError: ...
     """
 
     @classmethod
@@ -306,10 +299,6 @@ class QuestionOptionsDescriptor(BaseDescriptor):
             raise QuestionCreationValidationError(
                 f"Question options must be a list (got {value})."
             )
-        # if len(value) > Settings.MAX_NUM_OPTIONS:
-        #     raise QuestionCreationValidationError(
-        #         f"Too many question options (got {value})."
-        #     )
         if len(value) < Settings.MIN_NUM_OPTIONS:
             raise QuestionCreationValidationError(
                 f"Too few question options (got {value})."
@@ -338,7 +327,7 @@ class QuestionOptionsDescriptor(BaseDescriptor):
                     )
             if not all(
                 [
-                    type(option) != str
+                    not isinstance(option, str)
                     or (len(option) >= 1 and len(option) < Settings.MAX_OPTION_LENGTH)
                     for option in value
                 ]
@@ -356,12 +345,12 @@ class QuestionOptionsDescriptor(BaseDescriptor):
                     UserWarning,
                 )
 
-        if hasattr(instance, "min_selections") and instance.min_selections != None:
+        if hasattr(instance, "min_selections") and instance.min_selections is not None:
             if instance.min_selections > len(value):
                 raise QuestionCreationValidationError(
                     f"You asked for at least {instance.min_selections} selections, but provided fewer options (got {value})."
                 )
-        if hasattr(instance, "max_selections") and instance.max_selections != None:
+        if hasattr(instance, "max_selections") and instance.max_selections is not None:
             if instance.max_selections > len(value):
                 raise QuestionCreationValidationError(
                     f"You asked for at most {instance.max_selections} selections, but provided fewer options (got {value})."
@@ -396,40 +385,12 @@ class QuestionTextDescriptor(BaseDescriptor):
         # if len(value) > Settings.MAX_QUESTION_LENGTH:
         #     raise Exception("Question is too long!")
         if len(value) < 1:
-            raise Exception("Question is too short!")
+
+            raise QuestionCreationValidationError("Question is too short!")
         if not isinstance(value, str):
-            raise Exception("Question must be a string!")
+            raise QuestionCreationValidationError("Question must be a string!")
         
-        #value = textwrap.dedent(value).strip()
-
-        # if contains_single_braced_substring(value):
-        #     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
 
 

edsl/questions/exceptions.py

@@ -1,11 +1,19 @@
-from typing import Any, SupportsIndex
 import json
+from typing import Any
 from pydantic import ValidationError
 
+from ..base import BaseException
 
-class QuestionErrors(Exception):
+class QuestionErrors(BaseException):
     """
     Base exception class for question-related errors.
+    
+    This is the parent class for all exceptions related to question creation,
+    validation, processing, and answer handling. It provides a consistent
+    interface for error handling across the questions module.
+    
+    Attributes:
+        message (str): A human-readable error message explaining the issue
     """
 
     def __init__(self, message="An error occurred with the question"):
@@ -14,19 +22,50 @@ class QuestionErrors(Exception):
 
 
 class QuestionAnswerValidationError(QuestionErrors):
-    documentation = "https://docs.expectedparrot.com/en/latest/exceptions.html"
+    """
+    Exception raised when an answer fails validation.
+    
+    This exception occurs when the response from a language model does not
+    conform to the expected format or constraints for a specific question type.
+    
+    Common reasons for this exception:
+    - Multiple choice: Answer not one of the provided options
+    - Numerical: Answer not a valid number or outside allowed range
+    - Checkbox: Answer not a valid list of selected options
+    - Ranking: Answer does not include all items or has duplicates
+    
+    To fix this error:
+    1. Check the model's response format against the question's requirements
+    2. Verify that the question's instructions are clear for the language model
+    3. Consider using a more capable model if consistent validation failures occur
+    4. Examine the full error details which include the invalid response and validation rules
+    
+    Attributes:
+        message (str): The error message
+        pydantic_error (ValidationError): Underlying pydantic validation error
+        data (dict): The data that failed validation
+        model: The pydantic model used for validation
+    """
+    documentation = "https://docs.expectedparrot.com/en/latest/questions.html#validation"
 
     explanation = """
-    This can occur when the answer coming from the Language Model does not conform to the expectations for the question type.
-    For example, if the question is a multiple choice question, the answer should be drawn from the list of options provided.
+    This error occurs when the answer from the Language Model doesn't match the expected format
+    or constraints for the question type. For example:
+    
+    • Multiple choice questions require answers from the provided options
+    • Numerical questions need valid numbers within any specified range
+    • Checkbox questions require a subset of valid options
+    • Matrix questions need responses for each row following column constraints
+    
+    The error details show both what the model returned and the validation rules that were violated.
     """
 
     def __init__(
         self,
-        message="Invalid answer.",
-        pydantic_error: ValidationError = None,
-        data: dict = None,
-        model=None,
+        message: str,
+        data: dict,
+        model: Any, # for now
+        pydantic_error: ValidationError,
     ):
         self.message = message
         self.pydantic_error = pydantic_error
@@ -45,13 +84,17 @@ class QuestionAnswerValidationError(QuestionErrors):
                 return str(error_list[0].get("msg", "Unknown error"))
         return str(self.message)
 
-    # def __str__(self):
-    #     return f"""{repr(self)}
-    #     Data being validated: {self.data}
-    #     Pydnantic Model: {self.model}.
-    #     Reported error: {self.message}."""
-
     def to_html_dict(self):
+        """
+        Convert the exception to an HTML-friendly dictionary for rendering.
+        
+        This method is used for creating detailed error reports in HTML format,
+        particularly in notebook environments.
+        
+        Returns:
+            dict: HTML-formatted error information
+        """
+        #breakpoint()
         return {
             "Exception type": ("p", "/p", self.__class__.__name__),
             "Explanation": ("p", "/p", self.explanation),
@@ -79,28 +122,241 @@ class QuestionAnswerValidationError(QuestionErrors):
 
 
 class QuestionCreationValidationError(QuestionErrors):
-    pass
+    """
+    Exception raised when question creation parameters are invalid.
+    
+    This exception occurs when attempting to create a question with invalid
+    parameters, such as:
+    - Missing required attributes
+    - Invalid option formats
+    - Incompatible parameter combinations
+    
+    To fix this error:
+    1. Check the documentation for the specific question type
+    2. Verify all required parameters are provided
+    3. Ensure parameter formats match the question type's expectations
+    4. Confirm that parameter combinations are compatible
+    
+    Examples:
+        ```python
+        # Missing required options for multiple choice
+        MultipleChoice(question_text="Choose one:", options=[])  # Raises QuestionCreationValidationError
+        
+        # Invalid parameter combination
+        Numerical(question_text="Enter a value:", min_value=10, max_value=5)  # Raises QuestionCreationValidationError
+        ```
+    """
+    
+    def __init__(self, message="Invalid parameters for question creation"):
+        super().__init__(message)
 
 
 class QuestionResponseValidationError(QuestionErrors):
-    pass
+    """
+    Exception raised when a response fails structural validation.
+    
+    This exception is similar to QuestionAnswerValidationError but focuses on
+    structural validation before content validation. It catches errors in the
+    response structure itself.
+    
+    To fix this error:
+    1. Check if the model's response format is correctly structured
+    2. Verify that the response contains all required fields
+    3. Ensure the response data types match expectations
+    
+    Note: This exception is primarily used in tests and internal validation.
+    In most cases, QuestionAnswerValidationError provides more detailed information.
+    """
+    
+    def __init__(self, message="The response structure is invalid"):
+        super().__init__(message)
 
 
 class QuestionAttributeMissing(QuestionErrors):
-    pass
+    """
+    Exception raised when a required question attribute is missing.
+    
+    This exception occurs when attempting to use a question that is missing
+    essential attributes needed for its operation.
+    
+    To fix this error:
+    1. Check that the question has been properly initialized
+    2. Verify all required attributes are set
+    3. Ensure any parent class initialization is called correctly
+    
+    Note: While defined in the codebase, this exception is not actively raised
+    and may be used for future validation enhancements.
+    """
+    
+    def __init__(self, message="A required question attribute is missing"):
+        super().__init__(message)
 
 
 class QuestionSerializationError(QuestionErrors):
-    pass
+    """
+    Exception raised when question serialization or deserialization fails.
+    
+    This exception occurs when:
+    - A question cannot be properly converted to JSON format
+    - A serialized question cannot be reconstructed from its JSON representation
+    - Required fields are missing in the serialized data
+    
+    To fix this error:
+    1. Ensure the question and all its attributes are serializable
+    2. When deserializing, verify the data format matches what's expected
+    3. Check for version compatibility if deserializing from an older version
+    
+    Examples:
+        ```python
+        question.to_dict()  # Raises QuestionSerializationError if contains unserializable attributes
+        ```
+    """
+    
+    def __init__(self, message="Failed to serialize or deserialize question"):
+        super().__init__(message)
 
 
 class QuestionScenarioRenderError(QuestionErrors):
-    pass
+    """
+    Exception raised when a scenario cannot be rendered for a question.
+    
+    This exception occurs when:
+    - The scenario template has syntax errors
+    - Required variables for the template are missing
+    - The rendered scenario exceeds size limits
+    
+    To fix this error:
+    1. Check the scenario template syntax
+    2. Ensure all required variables are provided to the template
+    3. Verify that the scenario size is within acceptable limits
+    
+    Examples:
+        ```python
+        question.with_scenario(scenario_with_invalid_template)  # Raises QuestionScenarioRenderError
+        ```
+    """
+    
+    def __init__(self, message="Failed to render scenario for question"):
+        super().__init__(message)
 
 
 class QuestionMissingTypeError(QuestionErrors):
-    pass
+    """
+    Exception raised when a question class is missing a required type attribute.
+    
+    This exception occurs during question registration when a question class
+    doesn't define the required question_type attribute. All question classes
+    must have this attribute for proper registration and identification.
+    
+    To fix this error:
+    1. Add the question_type class attribute to the question class
+    2. Ensure the question_type is a unique identifier for the question type
+    
+    Examples:
+        ```python
+        class MyQuestion(Question):  # Missing question_type attribute
+            pass
+        # Registration would raise QuestionMissingTypeError
+        ```
+    """
+    
+    def __init__(self, message="Question class is missing required type attribute"):
+        super().__init__(message)
 
 
 class QuestionBadTypeError(QuestionErrors):
-    pass
+    """
+    Exception raised when a question class has an invalid __init__ method signature.
+    
+    This exception occurs during question registration when a question class
+    doesn't have the required parameters in its __init__ method. All question
+    classes must follow a standard parameter pattern for consistency.
+    
+    To fix this error:
+    1. Ensure the question class __init__ method includes the necessary parameters
+    2. Match the parameter pattern required by the question registry
+    
+    Examples:
+        ```python
+        class MyQuestion(Question):
+            question_type = "my_question"
+            def __init__(self, missing_required_params):  # Invalid signature
+                pass
+        # Registration would raise QuestionBadTypeError
+        ```
+    """
+    
+    def __init__(self, message="Question class has invalid __init__ method signature"):
+        super().__init__(message)
+
+
+class QuestionTypeError(QuestionErrors):
+    """
+    Exception raised when a TypeError occurs in the questions module.
+    
+    This exception wraps standard Python TypeErrors to provide a consistent
+    exception handling approach within the EDSL framework. It's used when
+    a type-related error occurs during question operations.
+    
+    Examples:
+        - Attempting to access or operate on a question attribute with the wrong type
+        - Passing incorrect types to question methods
+        - Type conversion failures during question processing
+    """
+    
+    def __init__(self, message="A type error occurred while processing the question"):
+        super().__init__(message)
+
+
+class QuestionValueError(QuestionErrors):
+    """
+    Exception raised when a ValueError occurs in the questions module.
+    
+    This exception wraps standard Python ValueErrors to provide a consistent
+    exception handling approach within the EDSL framework. It's used when
+    a value-related error occurs during question operations.
+    
+    Examples:
+        - Invalid values for question parameters
+        - Out-of-range values for numerical questions
+        - Invalid option selections for multiple choice questions
+    """
+    
+    def __init__(self, message="An invalid value was provided for the question"):
+        super().__init__(message)
+
+
+class QuestionKeyError(QuestionErrors):
+    """
+    Exception raised when a KeyError occurs in the questions module.
+    
+    This exception wraps standard Python KeyErrors to provide a consistent
+    exception handling approach within the EDSL framework. It's used when
+    a key-related error occurs during question operations.
+    
+    Examples:
+        - Attempting to access a non-existent attribute via dictionary-style access
+        - Missing keys in question option dictionaries
+        - Key errors during question serialization or deserialization
+    """
+    
+    def __init__(self, message="A key error occurred while processing the question"):
+        super().__init__(message)
+
+
+class QuestionNotImplementedError(QuestionErrors):
+    """
+    Exception raised when a method that should be implemented is not.
+    
+    This exception wraps standard Python NotImplementedError to provide a consistent
+    exception handling approach within the EDSL framework. It's used when
+    a required method is called but not implemented.
+    
+    Examples:
+        - Abstract methods that must be overridden in subclasses
+        - Placeholder methods that should be implemented in concrete classes
+        - Methods that are required by an interface but not yet implemented
+    """
+    
+    def __init__(self, message="This method must be implemented in a subclass"):
+        super().__init__(message)

edsl/questions/loop_processor.py

@@ -1,4 +1,4 @@
-from typing import List, Any, Dict, Union
+from typing import List, Any, Dict
 from jinja2 import Environment, Undefined
 from .question_base import QuestionBase
 from ..scenarios import ScenarioList
@@ -68,7 +68,6 @@ class LoopProcessor:
             return value
 
         if key == "option_labels":
-            import json
 
             return (
                 eval(self._render_template(value, scenario))
@@ -88,7 +87,8 @@ class LoopProcessor:
         if isinstance(value, (int, float)):
             return value
 
-        raise ValueError(f"Unexpected value type: {type(value)} for key '{key}'")
+        from .exceptions import QuestionValueError
+        raise QuestionValueError(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.
@@ -130,8 +130,10 @@ class LoopProcessor:
         
         def replace_var(match):
             var_name = match.group('var')
-            open_brace = match.group('open')
-            close_brace = match.group('close')
+            # We're keeping the original formatting with braces
+            # but not using these variables directly
+            # open_brace = match.group('open')
+            # close_brace = match.group('close')
             
             # Try to evaluate the variable in the context
             try:

edsl/questions/prompt_templates/question_list.jinja

@@ -12,6 +12,9 @@ Your response should be only a valid JSON in the following format:
     }
 {% endif %}
 
+{% if min_list_items is not none %}
+The list must contain at least {{ min_list_items }} items.
+{% endif %}
 {% if max_list_items is not none %}
 The list must not contain more than {{ max_list_items }} items.
 {% endif %}

edsl/questions/question_base.py

@@ -48,25 +48,27 @@ Technical Details:
 
 from __future__ import annotations
 from abc import ABC
-from typing import Any, Type, Optional, List, Callable, Union, TypedDict, TYPE_CHECKING
+from typing import Any, Type, Optional, Union, TypedDict, TYPE_CHECKING, Literal
 
+from .descriptors import QuestionNameDescriptor, QuestionTextDescriptor
+from .answer_validator_mixin import AnswerValidatorMixin
+from .register_questions_meta import RegisterQuestionsMeta
+from .simple_ask_mixin import SimpleAskMixin
+from .question_base_prompts_mixin import QuestionBasePromptsMixin
+from .question_base_gen_mixin import QuestionBaseGenMixin
 from .exceptions import QuestionSerializationError
 
 from ..base import PersistenceMixin, RepresentationMixin, BaseDiff, BaseDiffCollection
 from ..utilities import remove_edsl_version, is_valid_variable_name
 
+# Define VisibilityType for type annotations
+VisibilityType = Literal["private", "public", "unlisted"]
+
 if TYPE_CHECKING:
     from ..agents import Agent
     from ..scenarios import Scenario
     from ..surveys import Survey
 
-from .descriptors import QuestionNameDescriptor, QuestionTextDescriptor
-from .answer_validator_mixin import AnswerValidatorMixin
-from .register_questions_meta import RegisterQuestionsMeta
-from .simple_ask_mixin import SimpleAskMixin
-from .question_base_prompts_mixin import QuestionBasePromptsMixin
-from .question_base_gen_mixin import QuestionBaseGenMixin
-
 if TYPE_CHECKING:
     from .response_validator_abc import ResponseValidatorABC
     from ..language_models import LanguageModel
@@ -202,11 +204,6 @@ class QuestionBase(
             >>> q = QuestionFreeText(question_name="valid_name", question_text="Text")
             >>> q.is_valid_question_name()
             True
-            
-            >>> q = QuestionFreeText(question_name="123invalid", question_text="Text")
-            Traceback (most recent call last):
-            ...
-            edsl.questions.exceptions.QuestionCreationValidationError: `question_name` is not a valid variable name (got 123invalid).
         """
         return is_valid_variable_name(self.question_name)
 
@@ -509,9 +506,9 @@ class QuestionBase(
                         int(key): value for key, value in options_labels.items()
                     }
                     local_data["option_labels"] = options_labels
-        except:
+        except Exception as e:
             raise QuestionSerializationError(
-                f"Data does not have a 'question_type' field (got {data})."
+                f"Error in deserialization: {str(e)}. Data does not have a 'question_type' field (got {data})."
             )
         from .question_registry import get_question_class
 
@@ -697,7 +694,8 @@ class QuestionBase(
         try:
             return getattr(self, key)
         except TypeError:
-            raise KeyError(f"Question has no attribute {key} of type {type(key)}")
+            from .exceptions import QuestionKeyError
+            raise QuestionKeyError(f"Question has no attribute {key} of type {type(key)}")
 
     def __repr__(self) -> str:
         """Return a string representation of the question. Should be able to be used to reconstruct the question.

edsl/questions/question_base_gen_mixin.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 import copy
 import itertools
-from typing import Optional, List, Callable, Type, TYPE_CHECKING, Union
+from typing import Optional, List, Callable, TYPE_CHECKING, Union
 
 if TYPE_CHECKING:
     from .question_base import QuestionBase
@@ -174,7 +174,7 @@ class QuestionBaseGenMixin:
                 return result
             except self.MaxTemplateNestingExceeded:
                 raise
-            except Exception as e:
+            except Exception:
                 import warnings
                 warnings.warn("Failed to render string: " + value)
                 return value

edsl/questions/question_base_prompts_mixin.py

@@ -1,9 +1,14 @@
 from importlib import resources
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
 from functools import lru_cache
 
 from .exceptions import QuestionAnswerValidationError
 
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+    from ..prompts import Prompt
+    from ..prompts.prompt import PromptBase
+
 class TemplateManager:
     _instance = None
 
@@ -85,7 +90,7 @@ class QuestionBasePromptsMixin:
 
     @classmethod
     def path_to_folder(cls) -> str:
-        return resources.files(f"edsl.questions.templates", cls.question_type)
+        return resources.files("edsl.questions.templates", cls.question_type)
 
     @property
     def response_model(self) -> type["BaseModel"]:
@@ -179,7 +184,8 @@ class QuestionBasePromptsMixin:
             except QuestionAnswerValidationError:
                 pass
             else:
-                raise ValueError(f"Example {answer} should have failed for {reason}.")
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(f"Example {answer} should have failed for {reason}.")
 
     @property
     def new_default_instructions(self) -> "Prompt":