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

edsl/questions/__init__.py

@@ -1,28 +1,157 @@
-# Schemas
-from edsl.questions.settings import Settings
-from edsl.questions.register_questions_meta import RegisterQuestionsMeta
+"""
+EDSL Questions Module: The core system for creating and processing questions.
 
-# Base Class
-from edsl.questions.QuestionBase import QuestionBase
+The questions module provides a comprehensive framework for creating, validating,
+and processing various types of questions that can be asked to language models.
+It is one of the foundational components of EDSL and enables the creation of 
+surveys, interviews, and other question-based interactions.
+
+Key Features:
+-------------
+- A wide variety of question types including free text, multiple choice, checkbox, etc.
+- Consistent interface for asking questions to language models
+- Robust validation of responses
+- Support for question templates and parameterization with scenarios
+- Integration with the rest of the EDSL framework
+- Extensible architecture for creating custom question types
+
+Question Types:
+--------------
+Core Question Types:
+- QuestionFreeText: Free-form text responses without constraints
+- QuestionMultipleChoice: Selection from a predefined list of options
+- QuestionCheckBox: Selection of multiple options from a predefined list
+- QuestionNumerical: Numeric responses within an optional range
+- QuestionList: Responses in the form of lists or arrays
+- QuestionDict: Responses with key-value pairs
+- QuestionMatrix: Grid-based responses with rows and columns
+- QuestionBudget: Allocation of a budget across multiple options
+- QuestionRank: Ordering of items by preference or other criteria
+- QuestionExtract: Extraction of specific information from text or data
+
+Derived Question Types:
+- QuestionLikertFive: Standard 5-point Likert scale (agree/disagree)
+- QuestionLinearScale: Linear scale with customizable range and labels
+- QuestionYesNo: Simple binary yes/no response
+- QuestionTopK: Selection of top K items from a list of options
+
+Technical Architecture:
+---------------------
+1. Base Classes and Mixins:
+   - QuestionBase: Abstract base class for all question types
+   - SimpleAskMixin: Basic asking functionality to models and agents
+   - AnswerValidatorMixin: Validation of responses
+   - QuestionBasePromptsMixin: Template-based prompt generation
+   - QuestionBaseGenMixin: Integration with language models
+   
+2. Validation System:
+   - Response validators ensure answers conform to expected formats
+   - Pydantic models provide schema validation
+   - Repair functionality attempts to fix invalid responses
+   
+3. Template System:
+   - Jinja2 templates for consistent prompt generation
+   - Separate templates for answering instructions and question presentation
+   - Support for dynamic content through scenario variables
+
+4. Registry System:
+   - RegisterQuestionsMeta metaclass for automatic registration
+   - Question types are automatically available for serialization
+   - Registry enables runtime lookup of question types
+
+Example Usage:
+-------------
+    >>> from edsl import QuestionFreeText
+    >>> question = QuestionFreeText(
+    ...     question_name="greeting",
+    ...     question_text="Say hello to the user."
+    ... )
+    >>> from edsl.language_models import Model
+    >>> model = Model()
+    >>> # result = question.by(model).run()
+    
+    >>> from edsl import QuestionMultipleChoice
+    >>> choice_q = QuestionMultipleChoice(
+    ...     question_name="preference",
+    ...     question_text="Which color do you prefer?",
+    ...     question_options=["Red", "Blue", "Green", "Yellow"]
+    ... )
+    >>> # result = choice_q.by(model).run()
+
+Integration with Surveys:
+-----------------------
+Questions can be combined into surveys for more complex interactions:
+
+    # Note: Actual survey usage in code
+    # from edsl import Survey
+    # survey = Survey()
+    # survey.add_question(question)
+    # survey.add_question(choice_q)
+    # results = survey.by(model).run()
+
+Extension Points:
+---------------
+The questions module is designed to be extensible:
+- Create custom question types by subclassing QuestionBase
+- Implement custom validators for specialized validation
+- Define custom templates for unique presentation needs
+- Combine questions in surveys with custom flow logic
+"""
+
+# Schemas and metadata
+from .settings import Settings
+from .register_questions_meta import RegisterQuestionsMeta
+
+# Base Class and registry
+from .question_base import QuestionBase
+from .question_registry import Question
 
 # Core Questions
-from edsl.questions.QuestionCheckBox import QuestionCheckBox
-from edsl.questions.QuestionExtract import QuestionExtract
-from edsl.questions.QuestionFreeText import QuestionFreeText
-from edsl.questions.QuestionFunctional import QuestionFunctional
-from edsl.questions.QuestionList import QuestionList
-from edsl.questions.QuestionMatrix import QuestionMatrix
-from edsl.questions.QuestionDict import QuestionDict
-from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
-from edsl.questions.QuestionNumerical import QuestionNumerical
-from edsl.questions.QuestionBudget import QuestionBudget
-from edsl.questions.QuestionRank import QuestionRank
-
-# # # Questions derived from core questions
-from edsl.questions.derived.QuestionLikertFive import QuestionLikertFive
-from edsl.questions.derived.QuestionLinearScale import QuestionLinearScale
-from edsl.questions.derived.QuestionYesNo import QuestionYesNo
-from edsl.questions.derived.QuestionTopK import QuestionTopK
-
-# # Compose Questions
-# from edsl.questions.compose_questions import compose_questions
+from .question_check_box import QuestionCheckBox
+from .question_extract import QuestionExtract
+from .question_free_text import QuestionFreeText
+from .question_functional import QuestionFunctional
+from .question_list import QuestionList
+from .question_matrix import QuestionMatrix
+from .question_dict import QuestionDict
+from .question_multiple_choice import QuestionMultipleChoice
+from .question_numerical import QuestionNumerical
+from .question_budget import QuestionBudget
+from .question_rank import QuestionRank
+
+# Questions derived from core questions
+from .derived.question_likert_five import QuestionLikertFive
+from .derived.question_linear_scale import QuestionLinearScale
+from .derived.question_yes_no import QuestionYesNo
+from .derived.question_top_k import QuestionTopK
+
+from .exceptions import QuestionScenarioRenderError
+
+__all__ = [
+    # Schema and metadata
+    "Settings",
+    "RegisterQuestionsMeta",
+    
+    # Base question class and registry
+    "QuestionBase",
+    "Question",
+    
+    # Core question types
+    "QuestionFreeText",
+    "QuestionMultipleChoice",
+    "QuestionCheckBox",
+    "QuestionDict",
+    "QuestionExtract",
+    "QuestionFunctional",
+    "QuestionList",
+    "QuestionMatrix",
+    "QuestionNumerical",
+    "QuestionBudget",
+    "QuestionRank",
+    
+    # Derived question types
+    "QuestionLinearScale",
+    "QuestionTopK",
+    "QuestionLikertFive",
+    "QuestionYesNo",
+]

edsl/questions/answer_validator_mixin.py

@@ -2,7 +2,7 @@
 
 import re
 from typing import Any, Type, Union
-from edsl.exceptions.questions import (
+from .exceptions import (
     QuestionAnswerValidationError,
 )
 

edsl/questions/compose_questions.py

@@ -1,8 +1,9 @@
 """Compose two questions where the answer to q1 is used as an input to q2."""
 
-from edsl.questions import QuestionFunctional
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.scenarios.Scenario import Scenario
+from .question_functional import QuestionFunctional
+from .question_base import QuestionBase
+from ..scenarios import Scenario
+from ..agents import Agent
 
 
 def compose_questions(

edsl/questions/derived/question_likert_five.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+from typing import Optional
+from ..question_multiple_choice import QuestionMultipleChoice
+from ..decorators import inject_exception
+
+
+class QuestionLikertFive(QuestionMultipleChoice):
+    """
+    A specialized question that prompts the agent to respond on a 5-point Likert scale.
+    
+    QuestionLikertFive is a subclass of QuestionMultipleChoice that presents a standard
+    5-point Likert scale ranging from "Strongly disagree" to "Strongly agree". This
+    question type is ideal for measuring attitudes, opinions, and perceptions on a
+    symmetric agree-disagree scale.
+    
+    Key Features:
+    - Pre-configured with standard Likert scale options
+    - Simplifies creating consistent Likert scale questions
+    - Inherits all functionality from QuestionMultipleChoice
+    - Can be customized with different options if needed
+    
+    Technical Details:
+    - Uses the standard Likert options: ["Strongly disagree", "Disagree", "Neutral", "Agree", "Strongly agree"]
+    - Implements `use_code=False` by default, so responses contain the text labels
+    - Can be connected to language models and agents like any other question
+    
+    Examples:
+        Basic usage:
+        
+        ```python
+        q = QuestionLikertFive(
+            question_name="climate_concern",
+            question_text="I am concerned about climate change."
+        )
+        ```
+        
+        With custom options:
+        
+        ```python
+        q = QuestionLikertFive(
+            question_name="satisfaction",
+            question_text="I am satisfied with the product.",
+            question_options=["Strongly Disagree", "Somewhat Disagree", 
+                              "Neither Agree nor Disagree", 
+                              "Somewhat Agree", "Strongly Agree"]
+        )
+        ```
+        
+    Notes:
+        - Likert scales are particularly useful for surveys and opinion research
+        - The default options follow the most common 5-point Likert scale format
+        - For different scales (e.g., 7-point), you can pass custom options
+    """
+
+    question_type = "likert_five"
+    likert_options: list[str] = [
+        "Strongly disagree",
+        "Disagree",
+        "Neutral",
+        "Agree",
+        "Strongly agree",
+    ]
+
+    def __init__(
+        self,
+        question_name: str,
+        question_text: str,
+        question_options: Optional[list[str]] = None,
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+        include_comment: bool = True,
+    ):
+        """
+        Initialize a new 5-point Likert scale question.
+        
+        Parameters
+        ----------
+        question_name : str
+            The name of the question, used as an identifier. Must be a valid Python variable name.
+            This name will be used in results, templates, and when referencing the question in surveys.
+            
+        question_text : str
+            The statement to which the agent will respond on the Likert scale. This is typically
+            phrased as a statement rather than a question, e.g., "I enjoy using this product."
+            
+        question_options : Optional[list[str]], default=None
+            Optional custom Likert scale options. If None, the default 5-point Likert scale options
+            are used: ["Strongly disagree", "Disagree", "Neutral", "Agree", "Strongly agree"].
+            Custom options should follow the same format (typically 5 or 7 points from negative to positive).
+            
+        answering_instructions : Optional[str], default=None
+            Custom instructions for how the model should answer the question. If None,
+            default instructions for Likert scale questions will be used.
+            
+        question_presentation : Optional[str], default=None
+            Custom template for how the question is presented to the model. If None,
+            the default presentation for Likert scale questions will be used.
+            
+        include_comment : bool, default=True
+            Whether to include a comment field in the response, allowing the model to provide
+            additional explanation beyond just selecting an option on the scale.
+            
+        Examples
+        --------
+        >>> q = QuestionLikertFive(
+        ...     question_name="product_satisfaction",
+        ...     question_text="I am satisfied with the product."
+        ... )
+        
+        >>> q_custom = QuestionLikertFive(
+        ...     question_name="service_quality",
+        ...     question_text="The service quality was excellent.",
+        ...     question_options=["Completely Disagree", "Somewhat Disagree", 
+        ...                      "Neutral", "Somewhat Agree", "Completely Agree"]
+        ... )
+        
+        Notes
+        -----
+        - The default Likert options can be accessed via QuestionLikertFive.likert_options
+        - Likert scale questions inherently use text labels rather than numeric codes
+        - The statement should be phrased such that agreeing or disagreeing makes sense
+        """
+        # Use default Likert options if none are provided
+        if question_options is None:
+            question_options = self.likert_options
+        super().__init__(
+            question_name=question_name,
+            question_text=question_text,
+            question_options=question_options,
+            use_code=False,
+            include_comment=include_comment,
+            answering_instructions=answering_instructions,
+            question_presentation=question_presentation,
+        )
+
+    @classmethod
+    @inject_exception
+    def example(cls) -> QuestionLikertFive:
+        """Return an example question."""
+        return cls(
+            question_name="happy_raining",
+            question_text="I'm only happy when it rains.",
+        )
+
+
+def main():
+    """Test QuestionLikertFive."""
+    # Use the class directly since we're already in the module
+    q = QuestionLikertFive.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, {})
+    q._simulate_answer()
+    q._simulate_answer(human_readable=False)
+    q._validate_answer(q._simulate_answer(human_readable=False))
+    # serialization (inherits from Question)
+    q.to_dict()
+    assert q.from_dict(q.to_dict()) == q
+
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/derived/{QuestionLinearScale.py → question_linear_scale.py}

@@ -1,10 +1,10 @@
 from __future__ import annotations
 from typing import Optional
 
-from edsl.questions.descriptors import QuestionOptionsDescriptor, OptionLabelDescriptor
-from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
+from ..descriptors import QuestionOptionsDescriptor, OptionLabelDescriptor
+from ..question_multiple_choice import QuestionMultipleChoice
 
-from edsl.questions.decorators import inject_exception
+from ..decorators import inject_exception
 
 
 class QuestionLinearScale(QuestionMultipleChoice):
@@ -67,7 +67,7 @@ class QuestionLinearScale(QuestionMultipleChoice):
 
 def main():
     """Create an example of a linear scale question and demonstrate its functionality."""
-    from edsl.questions.derived.QuestionLinearScale import QuestionLinearScale
+    from edsl.questions import QuestionLinearScale
 
     q = QuestionLinearScale.example()
     q.question_text

edsl/questions/derived/{QuestionTopK.py → question_top_k.py}

@@ -1,9 +1,9 @@
 from __future__ import annotations
 from typing import Optional
 
-from edsl.exceptions.questions import QuestionCreationValidationError
-from edsl.questions.QuestionCheckBox import QuestionCheckBox
-from edsl.questions.decorators import inject_exception
+from ..exceptions import QuestionCreationValidationError
+from ..question_check_box import QuestionCheckBox
+from ..decorators import inject_exception
 
 
 class QuestionTopK(QuestionCheckBox):
@@ -70,7 +70,7 @@ class QuestionTopK(QuestionCheckBox):
 
 def main():
     """Test QuestionTopK."""
-    from edsl.questions.derived.QuestionTopK import QuestionTopK
+    from edsl.questions import QuestionTopK
 
     q = QuestionTopK.example()
     q.question_text

edsl/questions/derived/{QuestionYesNo.py → question_yes_no.py}

@@ -1,9 +1,9 @@
 from __future__ import annotations
 from typing import Optional
-from edsl.questions.descriptors import QuestionOptionsDescriptor
-from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
+from ..descriptors import QuestionOptionsDescriptor
+from ..question_multiple_choice import QuestionMultipleChoice
 
-from edsl.questions.decorators import inject_exception
+from ..decorators import inject_exception
 
 
 class QuestionYesNo(QuestionMultipleChoice):
@@ -54,8 +54,7 @@ class QuestionYesNo(QuestionMultipleChoice):
 
 def main():
     """Create an example of a yes/no question and demonstrate its functionality."""
-    from edsl.questions.derived.QuestionYesNo import QuestionYesNo
-
+    # Use the class directly since we're already in the module
     q = QuestionYesNo.example()
     q.question_text
     q.question_options

edsl/questions/descriptors.py

@@ -2,14 +2,12 @@
 
 from abc import ABC, abstractmethod
 import re
-import textwrap
 from typing import Any, Callable, List, Optional
-from edsl.exceptions.questions import (
+from .exceptions import (
     QuestionCreationValidationError,
     QuestionAnswerValidationError,
 )
-from edsl.questions.settings import Settings
-
+from .settings import Settings
 
 ################################
 # Helper functions
@@ -262,7 +260,7 @@ class QuestionOptionsDescriptor(BaseDescriptor):
     >>> _ = q_class(["a", "b", "c", "d", "d"])
     Traceback (most recent call last):
     ...
-    edsl.exceptions.questions.QuestionCreationValidationError: Question options must be unique (got ['a', 'b', 'c', 'd', 'd']).
+    edsl.questions.exceptions.QuestionCreationValidationError: Question options must be unique (got ['a', 'b', 'c', 'd', 'd']).
 
     We allow dynamic question options, which are strings of the form '{{ question_options }}'.
 
@@ -270,7 +268,7 @@ class QuestionOptionsDescriptor(BaseDescriptor):
     >>> _ = q_class("dynamic_options")
     Traceback (most recent call last):
     ...
-    edsl.exceptions.questions.QuestionCreationValidationError: ...
+    edsl.questions.exceptions.QuestionCreationValidationError: ...
     """
 
     @classmethod
@@ -391,10 +389,6 @@ class QuestionTextDescriptor(BaseDescriptor):
 
     >>> _ = TestQuestion("What is the capital of France?")
     >>> _ = TestQuestion("What is the capital of France? {{variable}}")
-    >>> _ = TestQuestion("What is the capital of France? {{variable name}}")
-    Traceback (most recent call last):
-    ...
-    edsl.exceptions.questions.QuestionCreationValidationError: Question text contains an invalid identifier: 'variable name'
     """
 
     def validate(self, value, instance):
@@ -408,21 +402,21 @@ class QuestionTextDescriptor(BaseDescriptor):
         
         #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,
-            )
+        # 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.
@@ -430,11 +424,11 @@ class QuestionTextDescriptor(BaseDescriptor):
             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)}'"
-                )
+        # 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/loop_processor.py

@@ -1,13 +1,12 @@
 from typing import List, Any, Dict, Union
-from jinja2 import Environment
-from edsl.questions.QuestionBase import QuestionBase
-from edsl import ScenarioList
-
+from jinja2 import Environment, Undefined
+from .question_base import QuestionBase
+from ..scenarios import ScenarioList
 
 class LoopProcessor:
     def __init__(self, question: QuestionBase):
         self.question = question
-        self.env = Environment()
+        self.env = Environment(undefined=Undefined)
 
     def process_templates(self, scenario_list: ScenarioList) -> List[QuestionBase]:
         """Process templates for each scenario and return list of modified questions.
@@ -46,8 +45,11 @@ class LoopProcessor:
         """
         processed = {}
 
+        extended_scenario = scenario.copy()
+        extended_scenario.update({"scenario": scenario})
+
         for key, value in [(k, v) for k, v in data.items() if v is not None]:
-            processed[key] = self._process_value(key, value, scenario)
+            processed[key] = self._process_value(key, value, extended_scenario)
 
         return processed
 
@@ -96,9 +98,61 @@ class LoopProcessor:
             scenario: Current scenario
 
         Returns:
-            Rendered template string
+            Rendered template string, preserving any unmatched template variables
+
+        Examples:
+            >>> from edsl.questions import QuestionBase
+            >>> q = QuestionBase()
+            >>> q.question_text = "test"
+            >>> p = LoopProcessor(q)
+            >>> p._render_template("Hello {{name}}!", {"name": "World"})
+            'Hello World!'
+
+            >>> p._render_template("{{a}} and {{b}}", {"b": 6})
+            '{{ a }} and 6'
+
+            >>> p._render_template("{{x}} + {{y}} = {{z}}", {"x": 2, "y": 3})
+            '2 + 3 = {{ z }}'
+
+            >>> p._render_template("No variables here", {})
+            'No variables here'
+
+            >>> p._render_template("{{item.price}}", {"item": {"price": 9.99}})
+            '9.99'
+
+            >>> p._render_template("{{item.missing}}", {"item": {"price": 9.99}})
+            '{{ item.missing }}'
         """
-        return self.env.from_string(template).render(scenario)
+        import re
+        
+        # Regular expression to find Jinja2 variables in the template
+        pattern = r'(?P<open>\{\{\s*)(?P<var>[a-zA-Z0-9_.]+)(?P<close>\s*\}\})'
+        
+        def replace_var(match):
+            var_name = match.group('var')
+            open_brace = match.group('open')
+            close_brace = match.group('close')
+            
+            # Try to evaluate the variable in the context
+            try:
+                # Handle nested attributes (like item.price)
+                parts = var_name.split('.')
+                value = scenario
+                for part in parts:
+                    if part in value:
+                        value = value[part]
+                    else:
+                        # If any part doesn't exist, return the original with spacing
+                        return f"{{ {var_name} }}".replace("{", "{{").replace("}", "}}")
+                # Return the rendered value if successful
+                return str(value)
+            except (KeyError, TypeError):
+                # Return the original variable name with the expected spacing
+                return f"{{ {var_name} }}".replace("{", "{{").replace("}", "}}")
+                
+        # Replace all variables in the template
+        result = re.sub(pattern, replace_var, template)
+        return result
 
     def _process_list(self, items: List[Any], scenario: Dict[str, Any]) -> List[Any]:
         """Process all items in a list.
@@ -135,15 +189,7 @@ class LoopProcessor:
         }
 
 
-# Usage example:
-"""
-from edsl import QuestionFreeText, ScenarioList
+if __name__ == "__main__":
+    import doctest
 
-question = QuestionFreeText(
-    question_text="What are your thoughts on: {{subject}}?",
-    question_name="base_{{subject}}"
-)
-processor = TemplateProcessor(question)
-scenarios = ScenarioList.from_list("subject", ["Math", "Economics", "Chemistry"])
-processed_questions = processor.process_templates(scenarios)
-"""
+    doctest.testmod()