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

edsl/questions/question_base_gen_mixin.py

@@ -4,9 +4,8 @@ import itertools
 from typing import Optional, List, Callable, Type, TYPE_CHECKING, Union
 
 if TYPE_CHECKING:
-    from edsl.questions.QuestionBase import QuestionBase
-    from edsl.scenarios.ScenarioList import ScenarioList
-
+    from .question_base import QuestionBase
+    from ..scenarios import ScenarioList
 
 class QuestionBaseGenMixin:
     """Mixin for QuestionBase.
@@ -30,7 +29,7 @@ class QuestionBaseGenMixin:
     def option_permutations(self) -> list[QuestionBase]:
         """Return a list of questions with all possible permutations of the options.
 
-        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice as Q
+        >>> from edsl.questions import QuestionMultipleChoice as Q
         >>> len(Q.example().option_permutations())
         24
         """
@@ -53,7 +52,7 @@ class QuestionBaseGenMixin:
 
         If the question has no options, returns a copy of the original question.
 
-        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice as Q
+        >>> from edsl.questions import QuestionMultipleChoice as Q
         >>> q = Q.example()
         >>> drawn = q.draw()
         >>> len(drawn.question_options) == len(q.question_options)
@@ -78,8 +77,8 @@ class QuestionBaseGenMixin:
 
         :param scenario_list: The list of scenarios to loop through.
 
-        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
-        >>> from edsl.scenarios.ScenarioList import ScenarioList
+        >>> from edsl.questions import QuestionFreeText
+        >>> from edsl.scenarios import ScenarioList
         >>> q = QuestionFreeText(question_text = "What are your thoughts on: {{ subject}}?", question_name = "base_{{subject}}")
         >>> len(q.loop(ScenarioList.from_list("subject", ["Math", "Economics", "Chemistry"])))
         3
@@ -100,31 +99,31 @@ class QuestionBaseGenMixin:
         Raises:
             MaxTemplateNestingExceeded: If template nesting exceeds MAX_NESTING levels
         
-        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
+        >>> from edsl.questions import QuestionFreeText
         >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite {{ thing }}?")
         >>> q.render({"thing": "color"})
         Question('free_text', question_name = \"""color\""", question_text = \"""What is your favorite color?\""")
 
-        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
+        >>> from edsl.questions import QuestionMultipleChoice
         >>> q = QuestionMultipleChoice(question_name = "color", question_text = "What is your favorite {{ thing }}?", question_options = ["red", "blue", "green"])
-        >>> from edsl.scenarios.Scenario import Scenario
+        >>> from edsl.scenarios import Scenario
         >>> q.render(Scenario({"thing": "color"})).data
         {'question_name': 'color', 'question_text': 'What is your favorite color?', 'question_options': ['red', 'blue', 'green']}
 
-        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
+        >>> from edsl.questions import QuestionMultipleChoice
         >>> q = QuestionMultipleChoice(question_name = "color", question_text = "What is your favorite {{ thing }}?", question_options = ["red", "blue", "green"])
         >>> q.render({"thing": 1}).data
         {'question_name': 'color', 'question_text': 'What is your favorite 1?', 'question_options': ['red', 'blue', 'green']}
 
 
-        >>> from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
-        >>> from edsl.scenarios.Scenario import Scenario
+        >>> from edsl.questions import QuestionMultipleChoice
+        >>> from edsl.scenarios import Scenario
         >>> q = QuestionMultipleChoice(question_name = "color", question_text = "What is your favorite {{ thing }}?", question_options = ["red", "blue", "green"])
         >>> q.render(Scenario({"thing": "color of {{ object }}", "object":"water"})).data
         {'question_name': 'color', 'question_text': 'What is your favorite color of water?', 'question_options': ['red', 'blue', 'green']}
 
         
-        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
+        >>> from edsl.questions import QuestionFreeText
         >>> q = QuestionFreeText(question_name = "infinite", question_text = "This has {{ a }}")
         >>> q.render({"a": "{{ b }}", "b": "{{ a }}"}) # doctest: +IGNORE_EXCEPTION_DETAIL
         Traceback (most recent call last):
@@ -132,7 +131,7 @@ class QuestionBaseGenMixin:
         edsl.questions.question_base_gen_mixin.QuestionBaseGenMixin.MaxTemplateNestingExceeded:...
         """
         from jinja2 import Environment, meta
-        from edsl.scenarios.Scenario import Scenario
+        from edsl.scenarios import Scenario
 
         MAX_NESTING = 10  # Maximum allowed nesting levels
         
@@ -187,7 +186,7 @@ class QuestionBaseGenMixin:
     def apply_function(
         self, func: Callable, exclude_components: Optional[List[str]] = None
     ) -> QuestionBase:
-        from edsl.questions.QuestionBase import QuestionBase
+        from .question_base import QuestionBase
         d = self._apply_function_dict(func, exclude_components)
         return QuestionBase.from_dict(d)
 

edsl/questions/{QuestionBasePromptsMixin.py → question_base_prompts_mixin.py}

@@ -1,8 +1,8 @@
 from importlib import resources
 from typing import Optional
-from edsl.exceptions.questions import QuestionAnswerValidationError
 from functools import lru_cache
 
+from .exceptions import QuestionAnswerValidationError
 
 class TemplateManager:
     _instance = None
@@ -277,7 +277,7 @@ class QuestionBasePromptsMixin:
 
         :param model: The language model to use.
         """
-        from edsl.prompts.Prompt import Prompt
+        from ..prompts import Prompt
 
         if model in self.model_instructions:
             return Prompt(text=self.model_instructions[model])

edsl/questions/{QuestionBudget.py → question_budget.py}

@@ -3,10 +3,9 @@ from typing import Any, Optional, Union, List
 
 from pydantic import Field, BaseModel, validator
 
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import IntegerDescriptor, QuestionOptionsDescriptor
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-
+from .question_base import QuestionBase
+from .descriptors import IntegerDescriptor, QuestionOptionsDescriptor
+from .response_validator_abc import ResponseValidatorABC
 
 class BudgetResponseValidator(ResponseValidatorABC):
     valid_examples = []

edsl/questions/{QuestionCheckBox.py → question_check_box.py}

@@ -1,25 +1,27 @@
 from __future__ import annotations
 import random
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, TYPE_CHECKING
 
 from jinja2 import Template
+from pydantic import field_validator
+from pydantic import BaseModel, Field, conlist
+from typing import List, Literal, Optional, Annotated
 
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import (
+from .exceptions import QuestionAnswerValidationError
+from ..scenarios import Scenario
+
+from .question_base import QuestionBase
+from .descriptors import (
     IntegerDescriptor,
     QuestionOptionsDescriptor,
 )
+from .decorators import inject_exception
+from .response_validator_abc import ResponseValidatorABC
 
-from edsl.questions.decorators import inject_exception
-
-from pydantic import field_validator
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-from edsl.questions.data_structures import BaseResponse
-
-from edsl.exceptions.questions import QuestionAnswerValidationError
-
-from pydantic import BaseModel, Field, conlist
-from typing import List, Literal, Optional, Annotated
+if TYPE_CHECKING:
+    from .data_structures import (
+        BaseResponse,
+    )
 
 
 def create_checkbox_response_model(
@@ -164,7 +166,7 @@ class CheckBoxResponseValidator(ResponseValidatorABC):
                 print(f"Proposed solution {proposed_data} is invalid. Error: {e}")
             return response
 
-    def custom_validate(self, response) -> BaseResponse:
+    def custom_validate(self, response) -> 'BaseResponse':
         if response.answer is None:
             raise QuestionAnswerValidationError("Answer is missing.")
         return response.dict()
@@ -241,8 +243,6 @@ class QuestionCheckBox(QuestionBase):
         For example, for question options ["a", "b", "c"],the answer codes are 0, 1, and 2.
         The LLM will respond with [0,1] and this code will translate it to ["a","b"].
         """
-        from edsl.scenarios.Scenario import Scenario
-
         scenario = scenario or Scenario()
         translated_options = [
             Template(str(option)).render(scenario) for option in self.question_options

edsl/questions/{QuestionDict.py → question_dict.py}

@@ -4,16 +4,16 @@ from pydantic import BaseModel, Field, field_validator
 from jinja2 import Environment, FileSystemLoader, TemplateNotFound
 from pathlib import Path
 
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import (
+from .question_base import QuestionBase
+from .descriptors import (
     AnswerKeysDescriptor,
     ValueTypesDescriptor,
     ValueDescriptionsDescriptor,
     QuestionTextDescriptor,
 )
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-from edsl.exceptions.questions import QuestionCreationValidationError
-from edsl.questions.decorators import inject_exception
+from .response_validator_abc import ResponseValidatorABC
+from .exceptions import QuestionCreationValidationError
+from .decorators import inject_exception
 
 
 class DictResponseValidator(ResponseValidatorABC):
@@ -49,6 +49,40 @@ class DictResponseValidator(ResponseValidatorABC):
 
 
 class QuestionDict(QuestionBase):
+    """ A QuestionDict allows you to create questions that expect dictionary responses with specific keys and value types.
+
+    Documenation: https://docs.expectedparrot.com/en/latest/questions.html#questiondict
+    
+    Parameters
+    ----------
+    question_name : str
+        Unique identifier for the question
+    question_text : str
+        The actual question text presented to users
+    answer_keys : List[str]
+        Keys that must be provided in the answer dictionary
+    value_types : Optional[List[Union[str, type]]]
+        Expected data types for each answer key
+    value_descriptions : Optional[List[str]]
+        Human-readable descriptions for each answer key
+    include_comment : bool
+        Whether to allow additional comments with the answer
+    question_presentation : Optional[str]
+        Alternative way to present the question
+    answering_instructions : Optional[str]
+        Additional instructions for answering
+    permissive : bool
+        If True, allows additional keys not specified in answer_keys
+
+    Examples
+    --------
+    >>> q = QuestionDict(
+    ...     question_name="tweet",
+    ...     question_text="Draft a tweet.",
+    ...     answer_keys=["text", "characters"],
+    ...     value_descriptions=["The text of the tweet", "The number of characters in the tweet"]
+    ... )
+    """
     question_type = "dict"
     question_text: str = QuestionTextDescriptor()
     answer_keys: List[str] = AnswerKeysDescriptor()

edsl/questions/{QuestionExtract.py → question_extract.py}

@@ -1,18 +1,18 @@
 from __future__ import annotations
 import json
 import re
-
+from typing import Dict, Any
 from typing import Any, Optional, Dict
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import AnswerTemplateDescriptor
-
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-from edsl.questions.data_structures import BaseResponse
-from edsl.questions.decorators import inject_exception
 
-from typing import Dict, Any
 from pydantic import create_model, Field
 
+from .question_base import QuestionBase
+from .descriptors import AnswerTemplateDescriptor
+
+from .response_validator_abc import ResponseValidatorABC
+from .data_structures import BaseResponse
+from .decorators import inject_exception
+
 
 def extract_json(text, expected_keys, verbose=False):
     # Escape special regex characters in keys
@@ -156,7 +156,7 @@ class QuestionExtract(QuestionBase):
 
 def main():
     """Administer a question and validate the answer."""
-    from edsl.questions.QuestionExtract import QuestionExtract
+    from edsl.questions import QuestionExtract
 
     q = QuestionExtract.example()
     q.question_text

edsl/questions/question_free_text.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+from typing import Any, Optional
+from typing import Optional, Any, List
+
+from uuid import uuid4
+
+from pydantic import field_validator, model_validator, BaseModel
+
+from ..prompts import Prompt
+
+from .exceptions import QuestionAnswerValidationError
+from .question_base import QuestionBase
+from .response_validator_abc import ResponseValidatorABC
+from .decorators import inject_exception
+
+
+class FreeTextResponse(BaseModel):
+    """
+    Pydantic model for validating free text responses.
+    
+    This model defines the structure and validation rules for responses to
+    free text questions. It ensures that responses contain a valid text string
+    and that the answer and generated_tokens fields match when both are present.
+    
+    Attributes:
+        answer: The text response string.
+        generated_tokens: Optional raw LLM output for token tracking.
+    """
+
+    answer: str
+    generated_tokens: Optional[str] = None
+
+    @model_validator(mode='after')
+    def validate_tokens_match_answer(self):
+        """
+        Validate that the answer matches the generated tokens if provided.
+        
+        This validator ensures consistency between the answer and generated_tokens
+        fields when both are present. They must match exactly (after stripping
+        whitespace) to ensure token tracking accuracy.
+        
+        Returns:
+            The validated model instance.
+            
+        Raises:
+            ValueError: If the answer and generated_tokens don't match exactly.
+        """
+        if self.generated_tokens is not None:  # If generated_tokens exists
+            # Ensure exact string equality
+            if self.answer.strip() != self.generated_tokens.strip():  # They MUST match exactly
+                raise ValueError(
+                    f"answer '{self.answer}' must exactly match generated_tokens '{self.generated_tokens}'. "
+                    f"Type of answer: {type(self.answer)}, Type of tokens: {type(self.generated_tokens)}"
+                )
+        return self
+
+
+class FreeTextResponseValidator(ResponseValidatorABC):
+    """
+    Validator for free text question responses.
+    
+    This class implements the validation and fixing logic for free text responses.
+    It ensures that responses contain a valid text string and provides methods
+    to fix common issues in responses.
+    
+    Attributes:
+        required_params: List of required parameters for validation.
+        valid_examples: Examples of valid responses for testing.
+        invalid_examples: Examples of invalid responses for testing.
+    """
+    required_params = []
+    valid_examples = [({"answer": "This is great"}, {})]
+    invalid_examples = [
+        (
+            {"answer": None},
+            {},
+            "Answer code must not be missing.",
+        ),
+    ]
+
+    def fix(self, response: dict, verbose: bool = False) -> dict:
+        """
+        Fix common issues in free text responses.
+        
+        This method attempts to fix invalid responses by ensuring the answer
+        field contains a valid string and is consistent with the generated_tokens
+        field if present.
+        
+        Args:
+            response: The response dictionary to fix.
+            verbose: If True, print information about the fixing process.
+            
+        Returns:
+            A fixed version of the response dictionary.
+            
+        Notes:
+            - For free text responses, the answer is always synchronized with generated_tokens
+            - Both fields are converted to strings to ensure type consistency
+        """
+        if response.get("generated_tokens") != response.get("answer"):
+            return {
+                "answer": str(response.get("generated_tokens")),
+                "generated_tokens": str(response.get("generated_tokens")),
+            }
+        else:
+            return {
+                "answer": str(response.get("generated_tokens")),
+                "generated_tokens": str(response.get("generated_tokens")),
+            }
+
+
+class QuestionFreeText(QuestionBase):
+    """
+    A question that allows an agent to respond with free-form text.
+    
+    QuestionFreeText is one of the simplest and most commonly used question types
+    in EDSL. It prompts an agent or language model to provide a textual response
+    without any specific structure or constraints on the format. The response can
+    be of any length and content, making it suitable for open-ended questions,
+    explanations, storytelling, and other scenarios requiring unrestricted text.
+    
+    Attributes:
+        question_type (str): Identifier for this question type, set to "free_text".
+        _response_model: Pydantic model for validating responses.
+        response_validator_class: Class used to validate and fix responses.
+        
+    Examples:
+        >>> q = QuestionFreeText(
+        ...     question_name="opinion", 
+        ...     question_text="What do you think about AI?"
+        ... )
+        >>> q.question_type
+        'free_text'
+        
+        >>> from edsl.language_models import Model
+        >>> model = Model("test", canned_response="I think AI is fascinating.")
+        >>> result = q.by(model).run(disable_remote_inference=True)
+        >>> answer = result.select("answer.*").to_list()[0]
+        >>> "fascinating" in answer
+        True
+    """
+
+    question_type = "free_text"
+    _response_model = FreeTextResponse
+    response_validator_class = FreeTextResponseValidator
+
+    def __init__(
+        self,
+        question_name: str,
+        question_text: str,
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+    ):
+        """
+        Initialize a new free text question.
+        
+        Args:
+            question_name: Identifier for the question, used in results and templates.
+                          Must be a valid Python variable name.
+            question_text: The actual text of the question to be asked.
+            answering_instructions: Optional additional instructions for answering
+                                    the question, overrides default instructions.
+            question_presentation: Optional custom presentation template for the
+                                  question, overrides default presentation.
+                                  
+        Examples:
+            >>> q = QuestionFreeText(
+            ...     question_name="feedback",
+            ...     question_text="Please provide your thoughts on this product."
+            ... )
+            >>> q.question_name
+            'feedback'
+            
+            >>> q = QuestionFreeText(
+            ...     question_name="explanation",
+            ...     question_text="Explain how photosynthesis works.",
+            ...     answering_instructions="Provide a detailed scientific explanation."
+            ... )
+        """
+        self.question_name = question_name
+        self.question_text = question_text
+        self.answering_instructions = answering_instructions
+        self.question_presentation = question_presentation
+
+    @property
+    def question_html_content(self) -> str:
+        """
+        Generate HTML content for rendering the question in web interfaces.
+        
+        This property generates HTML markup for the question when it needs to be
+        displayed in web interfaces or HTML contexts. For a free text question,
+        this is typically a textarea element.
+        
+        Returns:
+            str: HTML markup for rendering the question.
+            
+        Notes:
+            - Uses Jinja2 templating to generate the HTML
+            - Creates a textarea input element with the question_name as the ID and name
+            - Can be used for displaying the question in web UIs or HTML exports
+        """
+        from jinja2 import Template
+
+        question_html_content = Template(
+            """
+        <div>
+        <textarea id="{{ question_name }}" name="{{ question_name }}"></textarea>
+        </div>
+        """
+        ).render(question_name=self.question_name)
+        return question_html_content
+
+    @classmethod
+    @inject_exception
+    def example(cls, randomize: bool = False) -> "QuestionFreeText":
+        """
+        Create an example instance of a free text question.
+        
+        This class method creates a predefined example of a free text question
+        for demonstration, testing, and documentation purposes.
+        
+        Args:
+            randomize: If True, appends a random UUID to the question text to
+                     ensure uniqueness in tests and examples.
+                     
+        Returns:
+            QuestionFreeText: An example free text question.
+            
+        Examples:
+            >>> q = QuestionFreeText.example()
+            >>> q.question_name
+            'how_are_you'
+            >>> q.question_text
+            'How are you?'
+            
+            >>> q1 = QuestionFreeText.example(randomize=True)
+            >>> q2 = QuestionFreeText.example(randomize=True)
+            >>> q1.question_text != q2.question_text
+            True
+        """
+        addition = "" if not randomize else str(uuid4())
+        return cls(question_name="how_are_you", question_text=f"How are you?{addition}")
+
+
+def main():
+    """
+    Demonstrate the functionality of the QuestionFreeText class.
+    
+    This function creates an example free text question and demonstrates its
+    key features including validation, serialization, and answer simulation.
+    It's primarily intended for testing and development purposes.
+    
+    Note:
+        This function will be executed when the module is run directly,
+        but not when imported.
+    """
+    from .question_free_text import QuestionFreeText
+
+    # Create an example question
+    q = QuestionFreeText.example()
+    print(f"Question text: {q.question_text}")
+    print(f"Question name: {q.question_name}")
+    
+    # Validate an answer
+    valid_answer = {"answer": "I like custard", "generated_tokens": "I like custard"}
+    validated = q._validate_answer(valid_answer)
+    print(f"Validated answer: {validated}")
+    
+    # Simulate an answer
+    simulated = q._simulate_answer()
+    print(f"Simulated answer: {simulated}")
+    
+    # Serialization demonstration
+    serialized = q.to_dict()
+    print(f"Serialized: {serialized}")
+    deserialized = QuestionBase.from_dict(serialized)
+    print(f"Deserialization successful: {deserialized.question_text == q.question_text}")
+    
+    # Run doctests
+    import doctest
+    doctest.testmod(optionflags=doctest.ELLIPSIS)
+    print("Doctests completed")

edsl/questions/{QuestionFunctional.py → question_functional.py}

@@ -1,10 +1,11 @@
+from __future__ import annotations
 from typing import Optional, Callable
 import inspect
 
-from edsl.questions.QuestionBase import QuestionBase
+from .question_base import QuestionBase
 
-from edsl.utilities.restricted_python import create_restricted_function
-from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
+from ..utilities.restricted_python import create_restricted_function
+from ..utilities.decorators import add_edsl_version, remove_edsl_version
 
 
 class QuestionFunctional(QuestionBase):
@@ -25,7 +26,7 @@ class QuestionFunctional(QuestionBase):
 
     # Serialize the question to a dictionary
 
-    >>> from edsl.questions.QuestionBase import QuestionBase
+    >>> from .question_base import QuestionBase
     >>> new_question = QuestionBase.from_dict(question.to_dict())
     >>> results = new_question.by(scenario).by(agent).run(disable_remote_cache = True, disable_remote_inference = True)
     >>> results.select("answer.*").to_list()[0] == 150
@@ -146,7 +147,7 @@ def calculate_sum_and_multiply(scenario, agent_traits):
 
 def main():
     from edsl import Scenario, Agent
-    from edsl.questions.QuestionFunctional import QuestionFunctional
+    from .question_functional import QuestionFunctional
 
     # Create an instance of QuestionFunctional with the new function
     question = QuestionFunctional.example()

edsl/questions/{QuestionList.py → question_list.py}

@@ -5,12 +5,11 @@ from typing import Any, Optional, Union
 from pydantic import Field
 from json_repair import repair_json
 
-from edsl.exceptions.questions import QuestionAnswerValidationError
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import IntegerOrNoneDescriptor
-from edsl.questions.decorators import inject_exception
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-
+from .exceptions import QuestionAnswerValidationError
+from .question_base import QuestionBase
+from .descriptors import IntegerOrNoneDescriptor
+from .decorators import inject_exception
+from .response_validator_abc import ResponseValidatorABC
 
 def convert_string(s: str) -> Union[float, int, str, dict]:
     """Convert a string to a more appropriate type if possible.
@@ -198,7 +197,7 @@ class QuestionList(QuestionBase):
 
 def main():
     """Create an example of a list question and demonstrate its functionality."""
-    from edsl.questions.QuestionList import QuestionList
+    from edsl.questions import QuestionList
 
     q = QuestionList.example(max_list_items=5)
     q.question_text

edsl/questions/{QuestionMatrix.py → question_matrix.py}

@@ -4,15 +4,16 @@ 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 (
+from .question_base import QuestionBase
+from .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 (
+from .response_validator_abc import ResponseValidatorABC
+from .decorators import inject_exception
+
+from .exceptions import (
     QuestionAnswerValidationError,
     QuestionCreationValidationError,
 )