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

edsl/questions/{QuestionMultipleChoice.py → question_multiple_choice.py}

@@ -4,12 +4,11 @@ from typing import Union, Literal, Optional, List, Any
 from jinja2 import Template
 from pydantic import BaseModel, Field
 
-from edsl.scenarios.Scenario import Scenario
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import QuestionOptionsDescriptor
-from edsl.questions.decorators import inject_exception
-from edsl.questions.response_validator_abc import ResponseValidatorABC
-
+from ..scenarios import Scenario
+from .question_base import QuestionBase
+from .descriptors import QuestionOptionsDescriptor
+from .decorators import inject_exception
+from .response_validator_abc import ResponseValidatorABC
 
 def create_response_model(choices: List[str], permissive: bool = False):
     """
@@ -112,10 +111,64 @@ class MultipleChoiceResponseValidator(ResponseValidatorABC):
 
 
 class QuestionMultipleChoice(QuestionBase):
-    """This question prompts the agent to select one option from a list of options.
-
-    https://docs.expectedparrot.com/en/latest/questions.html#questionmultiplechoice-class
-
+    """
+    A question that prompts the agent to select one option from a list of choices.
+    
+    QuestionMultipleChoice presents a set of predefined choices to the agent and asks
+    them to select exactly one option. This question type is ideal for scenarios where
+    the possible answers are known and limited, such as surveys, preference questions,
+    or classification tasks.
+    
+    Key Features:
+    - Presents a fixed set of options to choose from
+    - Enforces selection of exactly one option
+    - Can use numeric codes for options (use_code=True)
+    - Supports custom instructions and presentation
+    - Optional comment field for additional explanation
+    - Can be configured to be permissive (accept answers outside the options)
+    
+    Technical Details:
+    - Uses Pydantic models for validation with Literal types for strict checking
+    - Supports dynamic options from scenario variables
+    - HTML rendering for web interfaces
+    - Robust validation with repair capabilities
+    
+    Examples:
+        Basic usage:
+        
+        ```python
+        q = QuestionMultipleChoice(
+            question_name="preference",
+            question_text="Which color do you prefer?",
+            question_options=["Red", "Green", "Blue", "Yellow"]
+        )
+        ```
+        
+        With numeric codes:
+        
+        ```python
+        q = QuestionMultipleChoice(
+            question_name="rating",
+            question_text="Rate this product from 1 to 5",
+            question_options=["Very Poor", "Poor", "Average", "Good", "Excellent"],
+            use_code=True  # The answer will be 0-4 instead of the text
+        )
+        ```
+        
+        Dynamic options from scenario:
+        
+        ```python
+        q = QuestionMultipleChoice(
+            question_name="choice",
+            question_text="Select an option",
+            question_options=["{{option1}}", "{{option2}}", "{{option3}}"]
+        )
+        scenario = Scenario({"option1": "Choice A", "option2": "Choice B", "option3": "Choice C"})
+        result = q.by(model).with_scenario(scenario).run()
+        ```
+    
+    See also:
+        https://docs.expectedparrot.com/en/latest/questions.html#questionmultiplechoice-class
     """
 
     question_type = "multiple_choice"
@@ -137,17 +190,69 @@ class QuestionMultipleChoice(QuestionBase):
         question_presentation: Optional[str] = None,
         permissive: bool = False,
     ):
-        """Instantiate a new QuestionMultipleChoice.
-
-        :param question_name: The name of the question.
-        :param question_text: The text of the question.
-        :param question_options: The options the agent should select from.
-        :param include_comment: Whether to include a comment field.
-        :param use_code: Whether to use code for the options.
-        :param answering_instructions: Instructions for the question.
-        :param question_presentation: The presentation of the question.
-        :param permissive: Whether to force the answer to be one of the options.
-
+        """
+        Initialize a new multiple choice 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 actual text of the question to be asked. This is the prompt that will be presented
+            to the language model or agent.
+            
+        question_options : Union[list[str], list[list], list[float], list[int]]
+            The list of options the agent can select from. These can be:
+            - Strings: ["Option A", "Option B", "Option C"]
+            - Lists: Used for nested or complex options
+            - Numbers: [1, 2, 3, 4, 5] or [0.1, 0.2, 0.3]
+            - Template strings: ["{{var1}}", "{{var2}}"] which will be rendered with scenario variables
+            
+        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.
+            
+        use_code : bool, default=False
+            If True, the answer will be the index of the selected option (0-based) instead of
+            the option text itself. This is useful for numeric scoring or when option text is long.
+            
+        answering_instructions : Optional[str], default=None
+            Custom instructions for how the model should answer the question. If None,
+            default instructions for multiple choice 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 multiple choice questions will be used.
+            
+        permissive : bool, default=False
+            If True, the validator will accept answers that are not in the provided options list.
+            If False (default), only exact matches to the provided options are allowed.
+            
+        Examples
+        --------
+        >>> q = QuestionMultipleChoice(
+        ...     question_name="color_preference",
+        ...     question_text="What is your favorite color?",
+        ...     question_options=["Red", "Blue", "Green", "Yellow"],
+        ...     include_comment=True
+        ... )
+        
+        >>> q_numeric = QuestionMultipleChoice(
+        ...     question_name="rating",
+        ...     question_text="How would you rate this product?",
+        ...     question_options=["Very Poor", "Poor", "Average", "Good", "Excellent"],
+        ...     use_code=True,
+        ...     include_comment=True
+        ... )
+        
+        Notes
+        -----
+        - When `use_code=True`, the answer will be the index (0-based) of the selected option
+        - The `permissive` parameter is useful when you want to allow free-form responses
+          while still suggesting options
+        - Dynamic options can reference variables in a scenario using Jinja2 template syntax
         """
         self.question_name = question_name
         self.question_text = question_text

edsl/questions/{QuestionNumerical.py → question_numerical.py}

@@ -5,11 +5,11 @@ from typing import Any, Optional, Union, Literal
 
 from pydantic import BaseModel, Field, field_validator
 
-from edsl.exceptions.questions import QuestionAnswerValidationError
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import NumericalOrNoneDescriptor
-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 NumericalOrNoneDescriptor
+from .decorators import inject_exception
+from .response_validator_abc import ResponseValidatorABC
 
 
 def create_numeric_response(

edsl/questions/{QuestionRank.py → question_rank.py}

@@ -3,12 +3,13 @@ from typing import Optional, Any, List, Annotated, Literal
 
 from pydantic import BaseModel, Field
 
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import (
+from .question_base import QuestionBase
+from .descriptors import (
     QuestionOptionsDescriptor,
     NumSelectionsDescriptor,
 )
-from edsl.questions.response_validator_abc import ResponseValidatorABC
+from .response_validator_abc import ResponseValidatorABC
+from ..scenarios import Scenario
 
 
 def create_response_model(
@@ -190,9 +191,8 @@ class QuestionRank(QuestionBase):
         self, answer_codes, scenario: Scenario = None
     ) -> list[str]:
         """Translate the answer code to the actual answer."""
-        from edsl.scenarios.Scenario import Scenario
         from jinja2 import Template
-
+        
         scenario = scenario or Scenario()
         translated_options = [
             Template(option).render(scenario) for option in self.question_options
@@ -285,7 +285,7 @@ class QuestionRank(QuestionBase):
 
 def main():
     """Show example usage."""
-    from edsl.questions.QuestionRank import QuestionRank
+    from edsl.questions import QuestionRank
 
     q = QuestionRank.example(use_code=True)
     q.question_text

edsl/questions/question_registry.py

@@ -4,8 +4,7 @@ import textwrap
 from uuid import UUID
 from typing import Any, Optional, Union
 
-
-from edsl.questions.QuestionBase import RegisterQuestionsMeta
+from .question_base import RegisterQuestionsMeta
 
 
 class Meta(type):
@@ -60,26 +59,25 @@ class Question(metaclass=Meta):
         return q.example()
 
     @classmethod
-    def pull(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+    def pull(cls, url_or_uuid: Union[str, UUID]):
         """Pull the object from coop."""
         from edsl.coop import Coop
 
         coop = Coop()
-        return coop.get(uuid, url, "question")
+        return coop.get(url_or_uuid, "question")
 
     @classmethod
-    def delete(cls, uuid: Optional[Union[str, UUID]] = None, url: Optional[str] = None):
+    def delete(cls, url_or_uuid: Union[str, UUID]):
         """Delete the object from coop."""
         from edsl.coop import Coop
 
         coop = Coop()
-        return coop.delete(uuid, url)
+        return coop.delete(url_or_uuid)
 
     @classmethod
     def patch(
         cls,
-        uuid: Optional[Union[str, UUID]] = None,
-        url: Optional[str] = None,
+        url_or_uuid: Union[str, UUID],
         description: Optional[str] = None,
         value: Optional[Any] = None,
         visibility: Optional[str] = None,
@@ -88,7 +86,7 @@ class Question(metaclass=Meta):
         from edsl.coop import Coop
 
         coop = Coop()
-        return coop.patch(uuid, url, description, value, visibility)
+        return coop.patch(url_or_uuid, description, value, visibility)
 
     @classmethod
     def list_question_types(cls):
@@ -115,7 +113,7 @@ class Question(metaclass=Meta):
         Example usage:
 
         """
-        from edsl.results.Dataset import Dataset
+        from ..dataset import Dataset
 
         exclude = ["budget"]
         if show_class_names:
@@ -169,9 +167,5 @@ question_purpose = {
 
 
 if __name__ == "__main__":
-    print(Question.available())
-
-    # q = Question("free_text", question_text="How are you doing?", question_name="test")
-    # results = q.run()
-
-    q = Question.pull(id=76)
+    import doctest
+    doctest.testmod()

edsl/questions/register_questions_meta.py

@@ -1,11 +1,9 @@
 from __future__ import annotations
 from abc import ABCMeta
-
-from edsl.enums import QuestionType
-from edsl.exceptions.questions import QuestionMissingTypeError, QuestionBadTypeError
-
 import inspect
 
+from ..enums import QuestionType
+from .exceptions import QuestionMissingTypeError, QuestionBadTypeError
 
 class RegisterQuestionsMeta(ABCMeta):
     """Metaclass to register output elements in a registry i.e., those that have a parent."""
@@ -69,3 +67,9 @@ class RegisterQuestionsMeta(ABCMeta):
                     f"Class {classname} does not have a question_type class attribute"
                 )
         return d
+
+
+
+if __name__ == "__main__":
+    import doctest 
+    doctest.testmod()

edsl/questions/response_validator_abc.py

@@ -1,15 +1,16 @@
 from abc import ABC, abstractmethod
-from typing import Optional, Any, List, TypedDict
+from typing import Optional, Any, List, TypedDict, TYPE_CHECKING
 
 from pydantic import BaseModel, Field, field_validator, ValidationError
 
-from edsl.exceptions.questions import QuestionAnswerValidationError
-from edsl.questions.ExceptionExplainer import ExceptionExplainer
+from .exceptions import QuestionAnswerValidationError
+from .ExceptionExplainer import ExceptionExplainer
 
-from edsl.questions.data_structures import (
-    RawEdslAnswerDict,
-    EdslAnswerDict,
-)
+if TYPE_CHECKING:
+    from edsl.questions.data_structures import (
+        RawEdslAnswerDict,
+        EdslAnswerDict,
+    )
 
 
 class ResponseValidatorABC(ABC):
@@ -53,7 +54,7 @@ class ResponseValidatorABC(ABC):
 
         self.fixes_tried = 0  # how many times we've tried to fix the answer
 
-    def _preprocess(self, data: RawEdslAnswerDict) -> RawEdslAnswerDict:
+    def _preprocess(self, data: 'RawEdslAnswerDict') -> 'RawEdslAnswerDict':
         """This is for testing purposes. A question can be given an exception to throw or an answer to always return.
 
         >>> rv = ResponseValidatorABC.example()
@@ -65,7 +66,7 @@ class ResponseValidatorABC(ABC):
             raise self.exception_to_throw
         return self.override_answer if self.override_answer else data
 
-    def _base_validate(self, data: RawEdslAnswerDict) -> BaseModel:
+    def _base_validate(self, data: 'RawEdslAnswerDict') -> BaseModel:
         """This is the main validation function. It takes the response_model and checks the data against it,
         returning the instantiated model.
 
@@ -85,11 +86,11 @@ class ResponseValidatorABC(ABC):
 
     def validate(
         self,
-        raw_edsl_answer_dict: RawEdslAnswerDict,
+        raw_edsl_answer_dict: 'RawEdslAnswerDict',
         fix=False,
         verbose=False,
         replacement_dict: dict = None,
-    ) -> EdslAnswerDict:
+    ) -> 'EdslAnswerDict':
         """This is the main validation function.
 
         >>> rv = ResponseValidatorABC.example("numerical")
@@ -100,7 +101,7 @@ class ResponseValidatorABC(ABC):
         >>> rv.validate({"answer": "120"})
         Traceback (most recent call last):
         ...
-        edsl.exceptions.questions.QuestionAnswerValidationError:...
+        edsl.questions.exceptions.QuestionAnswerValidationError:...
         >>> from edsl import QuestionNumerical
         >>> q = QuestionNumerical.example()
         >>> q.permissive = True
@@ -110,7 +111,7 @@ class ResponseValidatorABC(ABC):
         >>> rv.validate({"answer": "poo"})
         Traceback (most recent call last):
         ...
-        edsl.exceptions.questions.QuestionAnswerValidationError:...
+        edsl.questions.exceptions.QuestionAnswerValidationError:...
         """
         proposed_edsl_answer_dict = self._preprocess(raw_edsl_answer_dict)
         try:
@@ -126,7 +127,7 @@ class ResponseValidatorABC(ABC):
         explanation = ExceptionExplainer(e, model_response=e.data).explain()
         return explanation
 
-    def _handle_exception(self, e: Exception, raw_edsl_answer_dict) -> EdslAnswerDict:
+    def _handle_exception(self, e: Exception, raw_edsl_answer_dict) -> 'EdslAnswerDict':
         if self.fixes_tried == 0:
             self.original_exception = e
 
@@ -153,10 +154,10 @@ class ResponseValidatorABC(ABC):
     def _check_constraints(self, pydantic_edsl_answer: BaseModel) -> dict:
         pass
 
-    def _extract_answer(self, response: BaseModel) -> EdslAnswerDict:
+    def _extract_answer(self, response: BaseModel) -> 'EdslAnswerDict':
         return response.model_dump()
 
-    def _post_process(self, edsl_answer_dict: EdslAnswerDict) -> EdslAnswerDict:
+    def _post_process(self, edsl_answer_dict: 'EdslAnswerDict') -> 'EdslAnswerDict':
         return edsl_answer_dict
 
     @classmethod

edsl/results/__init__.py

@@ -1,2 +1,5 @@
 # from edsl.results.Result import Result
-from edsl.results.Results import Results
+from .results import Results
+from .result import Result
+
+__all__ = ["Results"]

edsl/{exceptions/results.py → results/exceptions.py}

@@ -1,5 +1,5 @@
-from edsl.exceptions.BaseException import BaseException
 
+from ..base import BaseException
 
 class ResultsError(BaseException):
     relevant_docs = "https://docs.expectedparrot.com/en/latest/results.html"

edsl/results/report.py

@@ -0,0 +1,197 @@
+import jinja2
+import textwrap
+import warnings
+
+class Report:
+    """
+    A flexible report generator for creating formatted output from EDSL datasets.
+    
+    The Report class provides a powerful yet simple way to create customized reports
+    from your survey results. It uses Jinja2 templates to format the data with complete
+    control over the presentation. This is particularly useful for:
+    
+    - Creating human-readable summaries of your results
+    - Generating standardized reports for stakeholders
+    - Formatting results for inclusion in papers or presentations
+    - Creating custom visualizations of your data
+    
+    The Report class works with any object that supports the Dataset interface,
+    including Results objects after using the select() method.
+    
+    Key features:
+    
+    - Flexible templating with full Jinja2 syntax
+    - Support for filtering and sorting data
+    - Customizable field selection and labeling
+    - Simple integration with Results and Dataset objects
+    
+    Usage:
+      report = Report(
+          dataset=my_dataset,
+          fields=["answer.how_feeling", "answer.how_feeling_yesterday"],
+          template=textwrap.dedent(\"\"\"\
+              # Observation {{ i }}
+              How feeling: {{ row['answer.how_feeling'] }}
+              How feeling yesterday: {{ row['answer.how_feeling_yesterday'] }}
+
+              ---
+          \"\"\")
+      )
+      print(report.generate())
+    """
+    def __init__(
+        self,
+        dataset,
+        fields=None,
+        template=None,
+        top_n=None,
+        pretty_labels=None,
+        filter_func=None,
+        sort_by=None
+    ):
+        """
+        :param dataset: The Dataset instance (DatasetExportMixin-based) to report on.
+        :param fields:  List of fields (column names) to include in the report. If None, use all.
+        :param template: A Jinja2-compatible template string describing how each row should be rendered.
+                         Within the template, you have access to:
+                           - {{ i }}         (the 1-based index of the row)
+                           - {{ row }}       (dictionary of field values for that row)
+        :param top_n:   If provided, only report on the first N observations.
+        :param pretty_labels: Dict mapping original field names to "pretty" labels used inside the template,
+                              or you can manually handle that in the template yourself.
+        :param filter_func: Optional callable(row_dict) -> bool. If given, only rows for which
+                            filter_func(row_dict) is True will appear in the final report.
+        :param sort_by: Optional single field name or list of field names to sort by.
+        """
+        self.dataset = dataset
+        self.fields = fields
+        self.template = template
+        self.top_n = top_n
+        self.pretty_labels = pretty_labels or {}
+        self.filter_func = filter_func
+        self.sort_by = sort_by
+
+        # Provide a simple fallback template
+        if not self.template:
+            # A minimal default: print all fields line by line
+            # with a heading "Observation #1" etc.
+            self.template = textwrap.dedent("""\
+                # Observation {{ i }}
+                {% for key, value in row.items() %}
+                **{{ key }}**: {{ value }}
+                {% endfor %}
+                ---
+            """)
+
+    def _prepare_data(self):
+        """
+        Convert dataset into a list of dictionaries (one per row),
+        optionally filtering, sorting, and limiting to top_n rows.
+        """
+        # 1) Decide which fields to include
+        if not self.fields:
+            self.fields = self.dataset.relevant_columns()
+
+        # 2) Convert to list of dictionaries
+        #    removing prefix because we typically want "field" instead of "answer.field"
+        data_dicts = self.dataset.to_dicts(remove_prefix=False)
+
+        # 3) Filter out any rows if filter_func is given
+        if self.filter_func:
+            data_dicts = [row for row in data_dicts if self.filter_func(row)]
+
+        # 4) If sort_by was specified, we’ll do a simple sort
+        if self.sort_by:
+            if isinstance(self.sort_by, str):
+                sort_keys = [self.sort_by]
+            else:
+                sort_keys = self.sort_by
+
+            # Python's sort can't directly do multi-key with fields from a dict
+            # unless we do something like tuple(...) for each field
+            # For simplicity, do a stable sort in reverse order for multiple keys
+            # or do a single pass with a tuple:
+            data_dicts.sort(key=lambda row: tuple(row.get(k) for k in sort_keys))
+
+        # 5) If top_n is specified, slice
+        if self.top_n is not None:
+            data_dicts = data_dicts[: self.top_n]
+
+        # 6) Optionally rename fields if pretty_labels is given
+        #    (But typically you'd use it inside the template. This is just an example.)
+        if self.pretty_labels:
+            # We'll apply them in a copy so the original keys are still accessible
+            data_for_report = []
+            for row in data_dicts:
+                # copy of the row, but with replaced keys
+                new_row = {}
+                for k, v in row.items():
+                    display_key = self.pretty_labels.get(k, k)
+                    new_row[display_key] = v
+                data_for_report.append(new_row)
+            data_dicts = data_for_report
+
+        return data_dicts
+
+    def generate(self) -> str:
+        """
+        Render the final report as a string.
+        
+        This method applies the Jinja2 template to each row of data and
+        combines the results into a single string. The template has access
+        to the row index (i) and the row data (row) for each observation.
+        
+        Returns:
+            A formatted string containing the complete report.
+        
+        Examples:
+            >>> from edsl import Results
+            >>> ds = Results.example().select("how_feeling")
+            >>> report = Report(dataset=ds)
+            >>> lines = report.generate().split("\\n")
+            >>> lines[0]
+            '# Observation 1'
+            
+            >>> # Custom template
+            >>> template = "Row {{ i }}: {{ row['answer.how_feeling'] }}\\n"
+            >>> report = Report(dataset=ds, template=template)
+            >>> report.generate().split("\\n")[0]
+            'Row 1: OK'
+        """
+        # Prepare data
+        data_dicts = self._prepare_data()
+
+        # Build a single Jinja2 template
+        template_obj = jinja2.Template(self.template)
+
+        output = []
+        for i, row in enumerate(data_dicts, start=1):
+            rendered = template_obj.render(i=i, row=row)
+            output.append(rendered.strip())
+
+        return "\n\n".join(output)
+
+
+if __name__ == "__main__":
+    # Suppose you have an existing Dataset
+    from edsl import Results
+    ds = Results.example().select("how_feeling", "how_feeling_yesterday")
+
+    # Provide a custom template string
+    my_template = textwrap.dedent("""\
+        ## Row {{ i }}
+
+        Feeling: {{ row['answer.how_feeling'] }}
+        Yesterday: {{ row['answer.how_feeling_yesterday'] }}
+
+        --------------------
+    """)
+
+    report = Report(
+        dataset=ds,
+        fields=["answer.how_feeling", "answer.how_feeling_yesterday"],
+        template=my_template,
+        top_n=3,  # only the first 3 observations
+    )
+
+    print(report.generate())