edsl 0.1.59__py3-none-any.whl → 0.1.61__py3-none-any.whl

edsl/language_models/raw_response_handler.py

@@ -1,5 +1,5 @@
 import json
-from typing import Optional, Any
+from typing import Optional, Any, List
 from .exceptions import (
     LanguageModelBadResponseError,
     LanguageModelTypeError,
@@ -41,10 +41,13 @@ def _extract_item_from_raw_response(data, sequence):
             current_data = current_data[key]
         except Exception as e:
             path = " -> ".join(map(str, sequence[: i + 1]))
-            if "error" in data:
-                msg = data["error"]
+            
+            # Create a safe error message that won't be None
+            if "error" in data and data["error"] is not None:
+                msg = str(data["error"])
             else:
                 msg = f"Error accessing path: {path}. {str(e)}. Full response is: '{data}'"
+                
             raise LanguageModelBadResponseError(message=msg, response_json=data)
     if isinstance(current_data, str):
         return current_data.strip()
@@ -55,17 +58,127 @@ def _extract_item_from_raw_response(data, sequence):
 class RawResponseHandler:
     """Class to handle raw responses from language models."""
 
-    def __init__(self, key_sequence: list, usage_sequence: Optional[list] = None):
+    def __init__(self, key_sequence: list, usage_sequence: Optional[list] = None, reasoning_sequence: Optional[list] = None):
         self.key_sequence = key_sequence
         self.usage_sequence = usage_sequence
+        self.reasoning_sequence = reasoning_sequence
 
     def get_generated_token_string(self, raw_response):
-        return _extract_item_from_raw_response(raw_response, self.key_sequence)
+        try:
+            return _extract_item_from_raw_response(raw_response, self.key_sequence)
+        except (LanguageModelKeyError, LanguageModelIndexError, LanguageModelTypeError, LanguageModelBadResponseError) as e:
+            # For non-reasoning models or reasoning models with different response formats,
+            # try to extract text directly from common response formats
+            if isinstance(raw_response, dict):
+                # Responses API format for non-reasoning models
+                if 'output' in raw_response and isinstance(raw_response['output'], list):
+                    # Try to get first message content
+                    if len(raw_response['output']) > 0:
+                        item = raw_response['output'][0]
+                        if isinstance(item, dict) and 'content' in item:
+                            if isinstance(item['content'], list) and len(item['content']) > 0:
+                                first_content = item['content'][0]
+                                if isinstance(first_content, dict) and 'text' in first_content:
+                                    return first_content['text']
+                            elif isinstance(item['content'], str):
+                                return item['content']
+                
+                # OpenAI completions format
+                if 'choices' in raw_response and isinstance(raw_response['choices'], list) and len(raw_response['choices']) > 0:
+                    choice = raw_response['choices'][0]
+                    if isinstance(choice, dict):
+                        if 'text' in choice:
+                            return choice['text']
+                        elif 'message' in choice and isinstance(choice['message'], dict) and 'content' in choice['message']:
+                            return choice['message']['content']
+                
+                # Text directly in response
+                if 'text' in raw_response:
+                    return raw_response['text']
+                elif 'content' in raw_response:
+                    return raw_response['content']
+                
+                # Error message - try to return a coherent error for debugging
+                if 'message' in raw_response:
+                    return f"[ERROR: {raw_response['message']}]"
+            
+            # If we get a string directly, return it
+            if isinstance(raw_response, str):
+                return raw_response
+            
+            # As a last resort, convert the whole response to string
+            try:
+                return f"[ERROR: Could not extract text. Raw response: {str(raw_response)}]"
+            except:
+                return "[ERROR: Could not extract text from response]"
 
     def get_usage_dict(self, raw_response):
         if self.usage_sequence is None:
             return {}
-        return _extract_item_from_raw_response(raw_response, self.usage_sequence)
+        try:
+            return _extract_item_from_raw_response(raw_response, self.usage_sequence)
+        except (LanguageModelKeyError, LanguageModelIndexError, LanguageModelTypeError, LanguageModelBadResponseError):
+            # For non-reasoning models, try to extract usage from common response formats
+            if isinstance(raw_response, dict):
+                # Standard OpenAI usage format
+                if 'usage' in raw_response:
+                    return raw_response['usage']
+                
+                # Look for nested usage info
+                if 'choices' in raw_response and len(raw_response['choices']) > 0:
+                    choice = raw_response['choices'][0]
+                    if isinstance(choice, dict) and 'usage' in choice:
+                        return choice['usage']
+            
+            # If no usage info found, return empty dict
+            return {}
+
+    def get_reasoning_summary(self, raw_response):
+        """
+        Extract reasoning summary from the model response.
+        
+        Handles various response structures:
+        1. Standard path extraction using self.reasoning_sequence
+        2. Direct access to output[0]['summary'] for OpenAI responses
+        3. List responses where the first item contains the output structure
+        """
+        if self.reasoning_sequence is None:
+            return None
+            
+        try:
+            # First try the standard extraction path
+            summary_data = _extract_item_from_raw_response(raw_response, self.reasoning_sequence)
+            
+            # If summary_data is a list of dictionaries with 'text' and 'type' fields
+            # (as in OpenAI's response format), combine them into a single string
+            if isinstance(summary_data, list) and all(isinstance(item, dict) and 'text' in item for item in summary_data):
+                return '\n\n'.join(item['text'] for item in summary_data)
+            
+            return summary_data
+        except Exception:
+            # Fallback approaches for different response structures
+            try:
+                # Case 1: Direct dict with 'output' field (common OpenAI format)
+                if isinstance(raw_response, dict) and 'output' in raw_response:
+                    output = raw_response['output']
+                    if isinstance(output, list) and len(output) > 0 and 'summary' in output[0]:
+                        summary_data = output[0]['summary']
+                        if isinstance(summary_data, list) and all(isinstance(item, dict) and 'text' in item for item in summary_data):
+                            return '\n\n'.join(item['text'] for item in summary_data)
+                
+                # Case 2: List where the first item is a dict with 'output' field
+                if isinstance(raw_response, list) and len(raw_response) > 0:
+                    first_item = raw_response[0]
+                    if isinstance(first_item, dict) and 'output' in first_item:
+                        output = first_item['output']
+                        if isinstance(output, list) and len(output) > 0 and 'summary' in output[0]:
+                            summary_data = output[0]['summary']
+                            if isinstance(summary_data, list) and all(isinstance(item, dict) and 'text' in item for item in summary_data):
+                                return '\n\n'.join(item['text'] for item in summary_data)
+            except Exception:
+                pass
+            
+            return None
 
     def parse_response(self, raw_response: dict[str, Any]) -> Any:
         """Parses the API response and returns the response text."""
@@ -73,7 +186,11 @@ class RawResponseHandler:
         from edsl.data_transfer_models import EDSLOutput
 
         generated_token_string = self.get_generated_token_string(raw_response)
+        # Ensure generated_token_string is a string before using string methods
+        if not isinstance(generated_token_string, str):
+            generated_token_string = str(generated_token_string)
         last_newline = generated_token_string.rfind("\n")
+        reasoning_summary = self.get_reasoning_summary(raw_response)
 
         if last_newline == -1:
             # There is no comment
@@ -81,12 +198,14 @@ class RawResponseHandler:
                 "answer": self.convert_answer(generated_token_string),
                 "generated_tokens": generated_token_string,
                 "comment": None,
+                "reasoning_summary": reasoning_summary,
             }
         else:
             edsl_dict = {
                 "answer": self.convert_answer(generated_token_string[:last_newline]),
-                "comment": generated_token_string[last_newline + 1 :].strip(),
+                "comment": generated_token_string[last_newline + 1:].strip(),
                 "generated_tokens": generated_token_string,
+                "reasoning_summary": reasoning_summary,
             }
         return EDSLOutput(**edsl_dict)
 

edsl/questions/loop_processor.py

@@ -1,7 +1,9 @@
-from typing import List, Any, Dict
+from typing import List, Any, Dict, Tuple
 from jinja2 import Environment, Undefined
 from .question_base import QuestionBase
-from ..scenarios import ScenarioList
+from ..scenarios import Scenario, ScenarioList
+from ..surveys import Survey
+
 
 class LoopProcessor:
     def __init__(self, question: QuestionBase):
@@ -88,7 +90,10 @@ class LoopProcessor:
             return value
 
         from .exceptions import QuestionValueError
-        raise QuestionValueError(f"Unexpected value type: {type(value)} for key '{key}'")
+
+        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.
@@ -124,21 +129,21 @@ class LoopProcessor:
             '{{ item.missing }}'
         """
         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*\}\})'
-        
+        pattern = r"(?P<open>\{\{\s*)(?P<var>[a-zA-Z0-9_.]+)(?P<close>\s*\}\})"
+
         def replace_var(match):
-            var_name = match.group('var')
+            var_name = match.group("var")
             # 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:
                 # Handle nested attributes (like item.price)
-                parts = var_name.split('.')
+                parts = var_name.split(".")
                 value = scenario
                 for part in parts:
                     if part in value:
@@ -151,7 +156,7 @@ class LoopProcessor:
             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
@@ -191,6 +196,280 @@ class LoopProcessor:
         }
 
 
+class LongSurveyLoopProcessor:
+    """
+    A modified LoopProcessor that creates a long survey where each question is rendered for each scenario.
+
+    Returns a tuple of (long_questions, long_scenario_list).
+    The long scenario list is essentially a flattened scenario list with one scenario that has many fields.
+
+    Usage:
+    >>> from edsl.questions import QuestionMultipleChoice
+    >>> from edsl.surveys import Survey
+    >>> from edsl.scenarios import Scenario, ScenarioList
+    >>> q = QuestionMultipleChoice(question_name = "enjoy", question_text = "How much do you enjoy {{ scenario.activity }}?", question_options = ["Not at all", "Somewhat", "Very much"])
+    >>> scenarios = ScenarioList([Scenario({"activity": activity}) for activity in ["tennis", "racecar driving", "cycling"]])
+    >>> survey = Survey([q])
+    >>> loop_processor = LongSurveyLoopProcessor(survey, scenarios)
+    >>> long_questions_list, long_scenario_list = loop_processor.process_templates_for_all_questions()
+    """
+
+    def __init__(self, survey: Survey, scenario_list: ScenarioList):
+        self.survey = survey
+        self.scenario_list = scenario_list
+        self.env = Environment(undefined=Undefined)
+        self.long_scenario_dict = {}
+
+    def process_templates_for_all_questions(
+        self,
+    ) -> Tuple[List[QuestionBase], ScenarioList]:
+        long_questions_list = []
+
+        self.long_scenario_dict = {}
+
+        for question in self.survey.questions:
+            updates_for_one_question = self.process_templates(
+                question, self.scenario_list
+            )
+            long_questions_list.extend(updates_for_one_question)
+
+        long_scenario_list = ScenarioList([Scenario(data=self.long_scenario_dict)])
+
+        return long_questions_list, long_scenario_list
+
+    def process_templates(
+        self, question: QuestionBase, scenario_list: ScenarioList
+    ) -> List[QuestionBase]:
+        """Process templates for each scenario and return list of modified questions.
+
+        Args:
+            scenario_list: List of scenarios to process templates against
+
+        Returns:
+            List of QuestionBase objects with rendered templates
+        """
+        import re
+
+        questions = []
+        starting_name = question.question_name
+
+        # Check for Jinja2 variables in the question text
+        pattern = self._jinja_variable_pattern()
+        variables_in_question_text = (
+            re.search(pattern, question.question_text) is not None
+        )
+        if variables_in_question_text:
+            for index, scenario in enumerate(scenario_list):
+                question_data = question.to_dict().copy()
+                processed_data = self._process_data(question_data, scenario, index)
+
+                if processed_data["question_name"] == starting_name:
+                    processed_data["question_name"] += f"_{index}"
+
+                questions.append(QuestionBase.from_dict(processed_data))
+        else:
+            questions.append(question)
+
+        return questions
+
+    def _process_data(
+        self, data: Dict[str, Any], scenario: Dict[str, Any], scenario_index: int
+    ) -> Dict[str, Any]:
+        """Process all data fields according to their type.
+
+        Args:
+            data: Dictionary of question data
+            scenario: Current scenario to render templates against
+
+        Returns:
+            Processed dictionary with rendered templates
+        """
+        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, extended_scenario, scenario_index
+            )
+
+        return processed
+
+    def _process_value(
+        self, key: str, value: Any, scenario: Dict[str, Any], scenario_index: int
+    ) -> Any:
+        """Process a single value according to its type.
+
+        Args:
+            key: Dictionary key
+            value: Value to process
+            scenario: Current scenario
+
+        Returns:
+            Processed value
+        """
+        if key == "question_options" and isinstance(value, str):
+            return value
+
+        if key == "option_labels":
+
+            return (
+                eval(self._render_template(value, scenario, scenario_index))
+                if isinstance(value, str)
+                else value
+            )
+
+        if isinstance(value, str):
+            return self._render_template(value, scenario, scenario_index)
+
+        if isinstance(value, list):
+            return self._process_list(value, scenario, scenario_index)
+
+        if isinstance(value, dict):
+            return self._process_dict(value, scenario, scenario_index)
+
+        if isinstance(value, (int, float)):
+            return value
+
+        from edsl.questions.exceptions import QuestionValueError
+
+        raise QuestionValueError(
+            f"Unexpected value type: {type(value)} for key '{key}'"
+        )
+
+    def _jinja_variable_pattern(self) -> str:
+
+        # Regular expression to find Jinja2 variables in the template
+        pattern = (
+            r"(?P<open>\{\{\s*)scenario\.(?P<var>[a-zA-Z0-9_.]+)(?P<close>\s*\}\})"
+        )
+        return pattern
+
+    def _render_template(
+        self, template: str, scenario: Dict[str, Any], scenario_index: int
+    ) -> str:
+        """Render a single template string.
+
+        Args:
+            template: Template string to render
+            scenario: Current scenario
+
+        Returns:
+            Rendered template string, preserving any unmatched template variables
+
+        Examples:
+            >>> from edsl.questions import QuestionBase
+            >>> from edsl.scenarios import Scenario, ScenarioList
+            >>> q = QuestionBase()
+            >>> q.question_text = "test"
+            >>> sl = ScenarioList([Scenario({"name": "World"}), Scenario({"name": "everyone"})])
+            >>> p = LongSurveyLoopProcessor(q, sl)
+            >>> p._render_template("Hello {{scenario.name}}!", {"name": "everyone"}, scenario_index=1)
+            'Hello {{ scenario.name_1 }}!'
+
+            >>> p._render_template("{{scenario.a}} and {{scenario.b}}", {"b": 6}, scenario_index=1)
+            '{{ a }} and {{ scenario.b_1 }}'
+
+            >>> p._render_template("{{scenario.x}} + {{scenario.y}} = {{scenario.z}}", {"x": 2, "y": 3}, scenario_index=5)
+            '{{ scenario.x_5 }} + {{ scenario.y_5 }} = {{ z }}'
+
+            >>> p._render_template("No variables here", {}, scenario_index=0)
+            'No variables here'
+
+            >>> p._render_template("{{scenario.item.price}}", {"item": {"price": 9.99}}, scenario_index=3)
+            '{{ scenario.item_3.price }}'
+
+            >>> p._render_template("{{scenario.item.missing}}", {"item": {"price": 9.99}}, scenario_index=3)
+            '{{ scenario.item_3.missing }}'
+        """
+        import re
+
+        # Regular expression to find Jinja2 variables in the template
+        pattern = self._jinja_variable_pattern()
+
+        def replace_var(match):
+            var_name = match.group("var")
+            # 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:
+                # Handle nested attributes (like item.price)
+                parts = var_name.split(".")
+
+                base_var = parts[0]
+
+                self.long_scenario_dict.update(
+                    {f"{base_var}_{scenario_index}": scenario[base_var]}
+                )
+
+                if len(parts) > 1:
+                    non_name_parts = ".".join(parts[1:])
+                    result = (
+                        f"{{ scenario.{base_var}_{scenario_index}.{non_name_parts} }}"
+                    )
+                else:
+                    result = f"{{ scenario.{base_var}_{scenario_index} }}"
+
+                result = result.replace("{", "{{").replace("}", "}}")
+                return result
+            except (KeyError, TypeError) as e:
+                # Return the original variable name with the expected spacing
+                result = f"{{ {var_name} }}".replace("{", "{{").replace("}", "}}")
+                return result
+
+        # 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], scenario_index: int
+    ) -> List[Any]:
+        """Process all items in a list.
+
+        Args:
+            items: List of items to process
+            scenario: Current scenario
+
+        Returns:
+            List of processed items
+        """
+        return [
+            (
+                self._render_template(item, scenario, scenario_index)
+                if isinstance(item, str)
+                else item
+            )
+            for item in items
+        ]
+
+    def _process_dict(
+        self, data: Dict[str, Any], scenario: Dict[str, Any], scenario_index: int
+    ) -> Dict[str, Any]:
+        """Process all keys and values in a dictionary.
+
+        Args:
+            data: Dictionary to process
+            scenario: Current scenario
+
+        Returns:
+            Dictionary with processed keys and values
+        """
+        return {
+            (
+                self._render_template(k, scenario, scenario_index)
+                if isinstance(k, str)
+                else k
+            ): (
+                self._render_template(v, scenario, scenario_index)
+                if isinstance(v, str)
+                else v
+            )
+            for k, v in data.items()
+        }
+
+
 if __name__ == "__main__":
     import doctest
 

edsl/questions/templates/dict/answering_instructions.jinja

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

edsl/results/result.py

@@ -95,6 +95,7 @@ class Result(Base, UserDict):
         question_to_attributes: Optional[dict[QuestionName, Any]] = None,
         generated_tokens: Optional[dict] = None,
         comments_dict: Optional[dict] = None,
+        reasoning_summaries_dict: Optional[dict] = None,
         cache_used_dict: Optional[dict[QuestionName, bool]] = None,
         indices: Optional[dict] = None,
         cache_keys: Optional[dict[QuestionName, str]] = None,
@@ -112,6 +113,7 @@ class Result(Base, UserDict):
         :param question_to_attributes: A dictionary of question attributes.
         :param generated_tokens: A dictionary of generated tokens.
         :param comments_dict: A dictionary of comments.
+        :param reasoning_summaries_dict: A dictionary of reasoning summaries.
         :param cache_used_dict: A dictionary of cache usage.
         :param indices: A dictionary of indices.
 
@@ -130,6 +132,7 @@ class Result(Base, UserDict):
             "question_to_attributes": self.question_to_attributes,
             "generated_tokens": generated_tokens or {},
             "comments_dict": comments_dict or {},
+            "reasoning_summaries_dict": reasoning_summaries_dict or {},
             "cache_used_dict": cache_used_dict or {},
             "cache_keys": cache_keys or {},
         }
@@ -236,6 +239,7 @@ class Result(Base, UserDict):
             "answer": self.data["answer"],
             "prompt": self.data["prompt"],
             "comment": self.data["comments_dict"],
+            "reasoning_summary": self.data["reasoning_summaries_dict"],
             "generated_tokens": self.data["generated_tokens"],
             "raw_model_response": self.data["raw_model_response"],
             "question_text": sub_dicts_needing_new_keys["question_text"],
@@ -497,6 +501,7 @@ class Result(Base, UserDict):
             question_to_attributes=json_dict.get("question_to_attributes", None),
             generated_tokens=json_dict.get("generated_tokens", {}),
             comments_dict=json_dict.get("comments_dict", {}),
+            reasoning_summaries_dict=json_dict.get("reasoning_summaries_dict", {}),
             cache_used_dict=json_dict.get("cache_used_dict", {}),
             cache_keys=json_dict.get("cache_keys", {}),
             indices=json_dict.get("indices", None),
@@ -631,6 +636,36 @@ class Result(Base, UserDict):
             }
             return comments_dict
 
+        def get_reasoning_summaries_dict(answer_key_names) -> dict[str, Any]:
+            reasoning_summaries_dict = {}
+            for k in answer_key_names:
+                reasoning_summary = question_results[k].reasoning_summary
+                
+                # If reasoning summary is None but we have a raw model response, try to extract it
+                if reasoning_summary is None and hasattr(question_results[k], 'raw_model_response'):
+                    try:
+                        # Get the model class to access the reasoning_sequence
+                        model_class = interview.model.__class__ if hasattr(interview, 'model') else None
+                        
+                        if model_class and hasattr(model_class, 'reasoning_sequence'):
+                            from ..language_models.raw_response_handler import RawResponseHandler
+                            
+                            # Create a handler with the model's reasoning sequence
+                            handler = RawResponseHandler(
+                                key_sequence=model_class.key_sequence if hasattr(model_class, 'key_sequence') else None,
+                                usage_sequence=model_class.usage_sequence if hasattr(model_class, 'usage_sequence') else None, 
+                                reasoning_sequence=model_class.reasoning_sequence
+                            )
+                            
+                            # Try to extract the reasoning summary
+                            reasoning_summary = handler.get_reasoning_summary(question_results[k].raw_model_response)
+                    except Exception:
+                        # If extraction fails, keep it as None
+                        pass
+                        
+                reasoning_summaries_dict[k + "_reasoning_summary"] = reasoning_summary
+            return reasoning_summaries_dict
+
         def get_question_name_to_prompts(
             model_response_objects,
         ) -> dict[str, dict[str, str]]:
@@ -705,6 +740,7 @@ class Result(Base, UserDict):
         answer_key_names = list(question_results.keys())
         generated_tokens_dict = get_generated_tokens_dict(answer_key_names) if answer_key_names else {}
         comments_dict = get_comments_dict(answer_key_names) if answer_key_names else {}
+        reasoning_summaries_dict = get_reasoning_summaries_dict(answer_key_names) if answer_key_names else {}
         
         # Get answers that are in the question results
         answer_dict = {}
@@ -735,6 +771,7 @@ class Result(Base, UserDict):
             survey=survey_copy,
             generated_tokens=generated_tokens_dict,
             comments_dict=comments_dict,
+            reasoning_summaries_dict=reasoning_summaries_dict,
             cache_used_dict=cache_used_dictionary,
             indices=indices_copy,
             cache_keys=cache_keys,

edsl/results/results.py

@@ -273,6 +273,7 @@ class Results(MutableSequence, ResultsOperationsMixin, Base):
         "generated_tokens",
         "cache_used",
         "cache_keys",
+        "reasoning_summary",
     ]
 
     @classmethod

edsl/scenarios/scenario_list.py

@@ -159,7 +159,15 @@ class ScenarioList(MutableSequence, Base, ScenarioListOperationsMixin):
 
     # Required MutableSequence abstract methods
     def __getitem__(self, index):
-        """Get item at index."""
+        """Get item at index.
+
+        Example:
+            >>> from edsl.scenarios import Scenario, ScenarioList
+            >>> sl = ScenarioList([Scenario({'a': 12})])
+            >>> sl[0]['b'] = 100  # modify in-place
+            >>> sl[0]['b']
+            100
+        """
         if isinstance(index, slice):
             return self.__class__(list(self.data[index]), self.codebook.copy())
         return self.data[index]
@@ -356,7 +364,29 @@ class ScenarioList(MutableSequence, Base, ScenarioListOperationsMixin):
                 new_scenarios.append(Scenario(new_scenario))
 
         return new_scenarios
+
+    @classmethod
+    def from_prompt(self, description: str, name:Optional[str] = "item", target_number:int = 10, verbose = False):
+        from ..questions.question_list import QuestionList
+        q = QuestionList(question_name = name, 
+                         question_text = description + f"\n Please try to return {target_number} examples.")
+        results = q.run(verbose = verbose)
+        return results.select(name).to_scenario_list().expand(name)
     
+
+    def __add__(self, other):
+        if isinstance(other, Scenario):
+            new_list = self.duplicate()
+            new_list.append(other)
+            return new_list
+        elif isinstance(other, ScenarioList):
+            new_list = self.duplicate()
+            for item in other:
+                new_list.append(item)
+        else:
+            raise ScenarioError("Don't know how to combine!")
+        return new_list
+
     @classmethod
     def from_search_terms(cls, search_terms: List[str]) -> ScenarioList:
         """Create a ScenarioList from a list of search terms, using Wikipedia.