edsl 0.1.27.dev2__py3-none-any.whl → 0.1.29__py3-none-any.whl

edsl/questions/QuestionBase.py

@@ -1,9 +1,10 @@
 """This module contains the Question class, which is the base class for all questions in EDSL."""
 
 from __future__ import annotations
+import time
 from abc import ABC, abstractmethod
-from rich.table import Table
-from typing import Any, Type, Optional
+from typing import Any, Type, Optional, List, Callable
+import copy
 
 from edsl.exceptions import (
     QuestionResponseValidationError,
@@ -11,10 +12,11 @@ from edsl.exceptions import (
 )
 from edsl.questions.descriptors import QuestionNameDescriptor, QuestionTextDescriptor
 
-from edsl.prompts.registry import get_classes as prompt_lookup
+
 from edsl.questions.AnswerValidatorMixin import AnswerValidatorMixin
 from edsl.questions.RegisterQuestionsMeta import RegisterQuestionsMeta
 from edsl.Base import PersistenceMixin, RichPrintingMixin
+from edsl.BaseDiff import BaseDiff, BaseDiffCollection
 
 from edsl.questions.SimpleAskMixin import SimpleAskMixin
 from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
@@ -37,6 +39,12 @@ class QuestionBase(
         """Get an attribute of the question."""
         return getattr(self, key)
 
+    def __hash__(self) -> int:
+        """Return a hash of the question."""
+        from edsl.utilities.utilities import dict_hash
+
+        return dict_hash(self._to_dict())
+
     def _repr_html_(self):
         from edsl.utilities.utilities import data_to_html
 
@@ -49,6 +57,35 @@ class QuestionBase(
 
         return data_to_html(data)
 
+    def apply_function(self, func: Callable, exclude_components=None) -> QuestionBase:
+        """Apply a function to the question parts
+
+        >>> from edsl.questions import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite color?")
+        >>> shouting = lambda x: x.upper()
+        >>> q.apply_function(shouting)
+        Question('free_text', question_name = \"""color\""", question_text = \"""WHAT IS YOUR FAVORITE COLOR?\""")
+
+        """
+        if exclude_components is None:
+            exclude_components = ["question_name", "question_type"]
+
+        d = copy.deepcopy(self._to_dict())
+        for key, value in d.items():
+            if key in exclude_components:
+                continue
+            if isinstance(value, dict):
+                for k, v in value.items():
+                    value[k] = func(v)
+                d[key] = value
+                continue
+            if isinstance(value, list):
+                value = [func(v) for v in value]
+                d[key] = value
+                continue
+            d[key] = func(value)
+        return QuestionBase.from_dict(d)
+
     @property
     def data(self) -> dict:
         """Return a dictionary of question attributes **except** for question_type."""
@@ -87,6 +124,8 @@ class QuestionBase(
         :param model: The language model to use. If None, assumes does not matter.
 
         """
+        from edsl.prompts.registry import get_classes as prompt_lookup
+
         applicable_prompts = prompt_lookup(
             component_type="question_instructions",
             question_type=cls.question_type,
@@ -101,6 +140,33 @@ class QuestionBase(
             self._model_instructions = {}
         return self._model_instructions
 
+    def _all_text(self) -> str:
+        """Return the question text."""
+        txt = ""
+        for key, value in self.data.items():
+            if isinstance(value, str):
+                txt += value
+            elif isinstance(value, list):
+                txt += "".join(str(value))
+        return txt
+
+    @property
+    def parameters(self) -> set[str]:
+        """Return the parameters of the question."""
+        from jinja2 import Environment, meta
+
+        env = Environment()
+        # Parse the template
+        txt = self._all_text()
+        # txt = self.question_text
+        # if hasattr(self, "question_options"):
+        #    txt += " ".join(self.question_options)
+        parsed_content = env.parse(txt)
+        # Extract undeclared variables
+        variables = meta.find_undeclared_variables(parsed_content)
+        # Return as a list
+        return set(variables)
+
     @model_instructions.setter
     def model_instructions(self, data: dict):
         """Set the model-specific instructions for the question."""
@@ -109,15 +175,16 @@ class QuestionBase(
     def add_model_instructions(
         self, *, instructions: str, model: Optional[str] = None
     ) -> None:
-        """Add model-specific instructions for the question.
+        """Add model-specific instructions for the question that override the default instructions.
 
         :param instructions: The instructions to add. This is typically a jinja2 template.
         :param model: The language model for this instruction.
 
         >>> from edsl.questions import QuestionFreeText
         >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite color?")
-        >>> q.add_model_instructions(instructions = "Answer in valid JSON like so {'answer': 'comment: <>}", model = "gpt3")
-
+        >>> q.add_model_instructions(instructions = "{{question_text}}. Answer in valid JSON like so {'answer': 'comment: <>}", model = "gpt3")
+        >>> q.get_instructions(model = "gpt3")
+        Prompt(text=\"""{{question_text}}. Answer in valid JSON like so {'answer': 'comment: <>}\""")
         """
         from edsl import Model
 
@@ -137,6 +204,13 @@ class QuestionBase(
         """Get the mathcing question-answering instructions for the question.
 
         :param model: The language model to use.
+
+        >>> from edsl import QuestionFreeText
+        >>> QuestionFreeText.example().get_instructions()
+        Prompt(text=\"""You are being asked the following question: {{question_text}}
+        Return a valid JSON formatted like this:
+        {"answer": "<put free text answer here>"}
+        \""")
         """
         from edsl.prompts.Prompt import Prompt
 
@@ -167,13 +241,17 @@ class QuestionBase(
     ############################
     # Serialization methods
     ############################
-    @add_edsl_version
-    def to_dict(self) -> dict[str, Any]:
+    def _to_dict(self):
         """Convert the question to a dictionary that includes the question type (used in deserialization)."""
         candidate_data = self.data.copy()
         candidate_data["question_type"] = self.question_type
         return candidate_data
 
+    @add_edsl_version
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the question to a dictionary that includes the question type (used in deserialization)."""
+        return self._to_dict()
+
     @classmethod
     @remove_edsl_version
     def from_dict(cls, data: dict) -> Type[QuestionBase]:
@@ -211,6 +289,10 @@ class QuestionBase(
 
         return question_class(**local_data)
 
+    def copy(self) -> Type[QuestionBase]:
+        """Return a deep copy of the question."""
+        return copy.deepcopy(self)
+
     ############################
     # Dunder methods
     ############################
@@ -220,6 +302,33 @@ class QuestionBase(
 
         print_json(json.dumps(self.to_dict()))
 
+    def __call__(self, just_answer=True, model=None, agent=None, **kwargs):
+        """Call the question.
+
+        >>> from edsl.language_models import LanguageModel
+        >>> m = LanguageModel.example(canned_response = "Yo, what's up?", test_model = True)
+        >>> from edsl import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "color", question_text = "What is your favorite color?")
+        >>> q(model = m)
+        "Yo, what's up?"
+
+        """
+        survey = self.to_survey()
+        results = survey(model=model, agent=agent, **kwargs)
+        if just_answer:
+            return results.select(f"answer.{self.question_name}").first()
+        else:
+            return results
+
+    async def run_async(self, just_answer=True, model=None, agent=None, **kwargs):
+        """Call the question."""
+        survey = self.to_survey()
+        results = await survey.run_async(model=model, agent=agent, **kwargs)
+        if just_answer:
+            return results.select(f"answer.{self.question_name}").first()
+        else:
+            return results
+
     def __repr__(self) -> str:
         """Return a string representation of the question. Should be able to be used to reconstruct the question."""
         class_name = self.__class__.__name__
@@ -237,21 +346,27 @@ class QuestionBase(
             return False
         return self.to_dict() == other.to_dict()
 
+    def __sub__(self, other) -> BaseDiff:
+        """Return the difference between two objects."""
+
+        return BaseDiff(other, self)
+
     # TODO: Throws an error that should be addressed at QuestionFunctional
-    def __add__(self, other_question):
+    def __add__(self, other_question_or_diff):
         """
         Compose two questions into a single question.
 
-        >>> from edsl.scenarios.Scenario import Scenario
-        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
-        >>> from edsl.questions.QuestionNumerical import QuestionNumerical
-        >>> q1 = QuestionFreeText(question_text = "What is the capital of {{country}}", question_name = "capital")
-        >>> q2 = QuestionNumerical(question_text = "What is the population of {{capital}}, in millions. Please round", question_name = "population")
-        >>> q3 = q1 + q2
+        TODO: Probably getting deprecated.
+
         """
+        if isinstance(other_question_or_diff, BaseDiff) or isinstance(
+            other_question_or_diff, BaseDiffCollection
+        ):
+            return other_question_or_diff.apply(self)
+
         from edsl.questions import compose_questions
 
-        return compose_questions(self, other_question)
+        return compose_questions(self, other_question_or_diff)
 
     @abstractmethod
     def _validate_answer(self, answer: dict[str, str]):
@@ -279,36 +394,41 @@ class QuestionBase(
     ############################
     # Forward methods
     ############################
-    def add_question(self, other: Question) -> "Survey":
+    def add_question(self, other: QuestionBase) -> "Survey":
         """Add a question to this question by turning them into a survey with two questions."""
         from edsl.surveys.Survey import Survey
 
         s = Survey([self, other])
         return s
 
-    def to_survey(self):
+    def to_survey(self) -> "Survey":
         """Turn a single question into a survey."""
         from edsl.surveys.Survey import Survey
 
         s = Survey([self])
         return s
 
-    def run(self, *args, **kwargs):
+    def run(self, *args, **kwargs) -> "Results":
         """Turn a single question into a survey and run it."""
         from edsl.surveys.Survey import Survey
 
         s = self.to_survey()
         return s.run(*args, **kwargs)
 
-    def by(self, *args):
-        """Turn a single question into a survey and run it."""
+    def by(self, *args) -> "Jobs":
+        """Turn a single question into a survey and then a Job."""
         from edsl.surveys.Survey import Survey
 
         s = Survey([self])
         return s.by(*args)
 
-    def human_readable(self):
-        """Print the question in a human readable format."""
+    def human_readable(self) -> str:
+        """Print the question in a human readable format.
+
+        >>> from edsl.questions import QuestionFreeText
+        >>> QuestionFreeText.example().human_readable()
+        'Question Type: free_text\\nQuestion: How are you?'
+        """
         lines = []
         lines.append(f"Question Type: {self.question_type}")
         lines.append(f"Question: {self.question_text}")
@@ -378,6 +498,8 @@ class QuestionBase(
 
     def rich_print(self):
         """Print the question in a rich format."""
+        from rich.table import Table
+
         table = Table(show_header=True, header_style="bold magenta")
         table.add_column("Question Name", style="dim")
         table.add_column("Question Type")

edsl/questions/QuestionBudget.py

@@ -1,11 +1,8 @@
 from __future__ import annotations
 import random
-import textwrap
 from typing import Any, Optional, Union
 from edsl.questions.QuestionBase import QuestionBase
 from edsl.questions.descriptors import IntegerDescriptor, QuestionOptionsDescriptor
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
 
 
 class QuestionBudget(QuestionBase):
@@ -46,7 +43,7 @@ class QuestionBudget(QuestionBase):
         return answer
 
     def _translate_answer_code_to_answer(
-        self, answer_codes: dict[str, int], scenario: Scenario = None
+        self, answer_codes: dict[str, int], scenario: "Scenario" = None
     ):
         """
         Translate the answer codes to the actual answers.
@@ -63,6 +60,8 @@ class QuestionBudget(QuestionBase):
 
     def _simulate_answer(self, human_readable=True):
         """Simulate a valid answer for debugging purposes (what the validator expects)."""
+        from edsl.utilities.utilities import random_string
+
         if human_readable:
             keys = self.question_options
         else:
@@ -163,8 +162,8 @@ def main():
 
 
 if __name__ == "__main__":
-    q = QuestionBudget.example()
-    results = q.run()
+    # q = QuestionBudget.example()
+    # results = q.run()
 
     import doctest
 

edsl/questions/QuestionCheckBox.py

@@ -9,8 +9,6 @@ from edsl.questions.descriptors import (
     IntegerDescriptor,
     QuestionOptionsDescriptor,
 )
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
 
 
 class QuestionCheckBox(QuestionBase):
@@ -55,13 +53,17 @@ class QuestionCheckBox(QuestionBase):
         self._validate_answer_checkbox(answer)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer_codes, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(
+        self, answer_codes, scenario: "Scenario" = None
+    ):
         """
         Translate the answer code to the actual answer.
 
         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(option).render(scenario) for option in self.question_options
@@ -73,6 +75,8 @@ class QuestionCheckBox(QuestionBase):
 
     def _simulate_answer(self, human_readable=True) -> dict[str, Union[int, str]]:
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         min_selections = self.min_selections or 1
         max_selections = self.max_selections or len(self.question_options)
         num_selections = random.randint(min_selections, max_selections)

edsl/questions/QuestionExtract.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 from typing import Any
 from edsl.questions.QuestionBase import QuestionBase
 from edsl.questions.descriptors import AnswerTemplateDescriptor
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
 
 
 class QuestionExtract(QuestionBase):
@@ -44,12 +42,14 @@ class QuestionExtract(QuestionBase):
         self._validate_answer_extract(answer)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(self, answer, scenario: "Scenario" = None):
         """Return the answer in a human-readable format."""
         return answer
 
     def _simulate_answer(self, human_readable: bool = True) -> dict[str, str]:
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         return {
             "answer": {key: random_string() for key in self.answer_template.keys()},
             "comment": random_string(),
@@ -106,6 +106,8 @@ def main():
     q.to_dict()
     assert q.from_dict(q.to_dict()) == q
 
+
+if __name__ == "__main__":
     import doctest
 
     doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/QuestionFreeText.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 import textwrap
 from typing import Any, Optional
 from edsl.questions.QuestionBase import QuestionBase
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
 
 
 class QuestionFreeText(QuestionBase):
@@ -43,12 +41,14 @@ class QuestionFreeText(QuestionBase):
         self._validate_answer_key_value(answer, "answer", str)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(self, answer, scenario: "Scenario" = None):
         """Do nothing, because the answer is already in a human-readable format."""
         return answer
 
     def _simulate_answer(self, human_readable: bool = True) -> dict[str, str]:
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         return {"answer": random_string()}
 
     @property

edsl/questions/QuestionFunctional.py

@@ -1,10 +1,7 @@
 from typing import Optional, Callable
-from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import FunctionDescriptor
 import inspect
 
 from edsl.questions.QuestionBase import QuestionBase
-from edsl.questions.descriptors import FunctionDescriptor
 
 from edsl.utilities.restricted_python import create_restricted_function
 

edsl/questions/QuestionList.py

@@ -5,9 +5,6 @@ from typing import Any, Optional, Union
 from edsl.questions.QuestionBase import QuestionBase
 from edsl.questions.descriptors import IntegerOrNoneDescriptor
 
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
-
 
 class QuestionList(QuestionBase):
     """This question prompts the agent to answer by providing a list of items as comma-separated strings."""
@@ -42,13 +39,15 @@ class QuestionList(QuestionBase):
         self._validate_answer_list(answer)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(self, answer, scenario: "Scenario" = None):
         """There is no answer code."""
         return answer
 
     def _simulate_answer(self, human_readable: bool = True):
         """Simulate a valid answer for debugging purposes (what the validator expects)."""
         num_items = random.randint(1, self.max_list_items or 2)
+        from edsl.utilities.utilities import random_string
+
         return {"answer": [random_string() for _ in range(num_items)]}
 
     @property

edsl/questions/QuestionMultipleChoice.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
-from typing import Optional, Union
+import time
+from typing import Union
 import random
 
 from jinja2 import Template
 
-from edsl.utilities import random_string
-from edsl.questions.descriptors import QuestionOptionsDescriptor
 from edsl.questions.QuestionBase import QuestionBase
-from edsl.scenarios import Scenario
+from edsl.questions.descriptors import QuestionOptionsDescriptor
 
 
 class QuestionMultipleChoice(QuestionBase):
@@ -15,9 +14,9 @@ class QuestionMultipleChoice(QuestionBase):
 
     question_type = "multiple_choice"
     purpose = "When options are known and limited"
-    question_options: Union[
-        list[str], list[list], list[float], list[int]
-    ] = QuestionOptionsDescriptor()
+    question_options: Union[list[str], list[list], list[float], list[int]] = (
+        QuestionOptionsDescriptor()
+    )
 
     def __init__(
         self,
@@ -47,8 +46,12 @@ class QuestionMultipleChoice(QuestionBase):
         self._validate_answer_multiple_choice(answer)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer_code, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(
+        self, answer_code, scenario: "Scenario" = None
+    ):
         """Translate the answer code to the actual answer."""
+        from edsl.scenarios.Scenario import Scenario
+
         scenario = scenario or Scenario()
         translated_options = [
             Template(str(option)).render(scenario) for option in self.question_options
@@ -59,6 +62,8 @@ class QuestionMultipleChoice(QuestionBase):
         self, human_readable: bool = True
     ) -> dict[str, Union[int, str]]:
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         if human_readable:
             answer = random.choice(self.question_options)
         else:
@@ -70,6 +75,7 @@ class QuestionMultipleChoice(QuestionBase):
 
     @property
     def question_html_content(self) -> str:
+
         if hasattr(self, "option_labels"):
             option_labels = self.option_labels
         else:
@@ -127,6 +133,8 @@ def main():
     q.to_dict()
     assert q.from_dict(q.to_dict()) == q
 
+
+if __name__ == "__main__":
     import doctest
 
     doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/QuestionNumerical.py

@@ -2,11 +2,10 @@ from __future__ import annotations
 import textwrap
 from random import uniform
 from typing import Any, Optional, Union
+
 from edsl.exceptions import QuestionAnswerValidationError
 from edsl.questions.QuestionBase import QuestionBase
 from edsl.questions.descriptors import NumericalOrNoneDescriptor
-from edsl.scenarios import Scenario
-from edsl.utilities import random_string
 
 
 class QuestionNumerical(QuestionBase):
@@ -48,12 +47,14 @@ class QuestionNumerical(QuestionBase):
         self._validate_answer_numerical(answer)
         return answer
 
-    def _translate_answer_code_to_answer(self, answer, scenario: Scenario = None):
+    def _translate_answer_code_to_answer(self, answer, scenario: "Scenario" = None):
         """There is no answer code."""
         return answer
 
     def _simulate_answer(self, human_readable: bool = True):
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         return {
             "answer": uniform(self.min_value, self.max_value),
             "comment": random_string(),

edsl/questions/QuestionRank.py

@@ -1,12 +1,10 @@
 from __future__ import annotations
 import random
-import textwrap
 from jinja2 import Template
 from typing import Any, Optional, Union
 from edsl.questions.QuestionBase import QuestionBase
 from edsl.exceptions import QuestionAnswerValidationError
-from edsl.scenarios import Scenario
-from edsl.utilities.utilities import random_string
+
 from edsl.questions.descriptors import (
     QuestionOptionsDescriptor,
     NumSelectionsDescriptor,
@@ -55,6 +53,8 @@ class QuestionRank(QuestionBase):
         self, answer_codes, scenario: Scenario = None
     ) -> list[str]:
         """Translate the answer code to the actual answer."""
+        from edsl.scenarios import Scenario
+
         scenario = scenario or Scenario()
         translated_options = [
             Template(option).render(scenario) for option in self.question_options
@@ -66,6 +66,8 @@ class QuestionRank(QuestionBase):
 
     def _simulate_answer(self, human_readable=True) -> dict[str, Union[int, str]]:
         """Simulate a valid answer for debugging purposes."""
+        from edsl.utilities.utilities import random_string
+
         if human_readable:
             selected = random.sample(self.question_options, self.num_selections)
         else:

edsl/questions/__init__.py

@@ -10,17 +10,18 @@ from edsl.questions.QuestionBudget import QuestionBudget
 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.QuestionMultipleChoice import QuestionMultipleChoice
 from edsl.questions.QuestionNumerical import QuestionNumerical
 from edsl.questions.QuestionRank import QuestionRank
 
-# Questions derived from core questions
+# # Questions derived from core questions
 from edsl.questions.derived.QuestionLikertFive import QuestionLikertFive
 from edsl.questions.derived.QuestionLinearScale import QuestionLinearScale
 from edsl.questions.derived.QuestionTopK import QuestionTopK
 from edsl.questions.derived.QuestionYesNo import QuestionYesNo
 
-# Compose Questions
-from edsl.questions.compose_questions import compose_questions
+# # Compose Questions
+# from edsl.questions.compose_questions import compose_questions

edsl/questions/descriptors.py

@@ -8,9 +8,7 @@ from edsl.exceptions import (
     QuestionAnswerValidationError,
 )
 from edsl.questions.settings import Settings
-from edsl.utilities.utilities import is_valid_variable_name
 
-from edsl.prompts import get_classes
 
 ################################
 # Helper functions
@@ -56,6 +54,8 @@ class BaseDescriptor(ABC):
     def __set__(self, instance, value: Any) -> None:
         """Set the value of the attribute."""
         self.validate(value, instance)
+        from edsl.prompts.registry import get_classes
+
         instance.__dict__[self.name] = value
         if self.name == "_instructions":
             instructions = value
@@ -231,6 +231,8 @@ class QuestionNameDescriptor(BaseDescriptor):
 
     def validate(self, value, instance):
         """Validate the value is a valid variable name."""
+        from edsl.utilities.utilities import is_valid_variable_name
+
         if not is_valid_variable_name(value):
             raise QuestionCreationValidationError(
                 f"`question_name` is not a valid variable name (got {value})."
@@ -331,6 +333,9 @@ class QuestionTextDescriptor(BaseDescriptor):
         if not isinstance(value, str):
             raise Exception("Question must be a string!")
         if contains_single_braced_substring(value):
-            print(
-                f"WARNING: Question text contains a single-braced substring: {value}.\nIf 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"
+            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,
             )