edsl 0.1.39.dev1__py3-none-any.whl → 0.1.39.dev2__py3-none-any.whl

edsl/agents/QuestionInstructionPromptBuilder.py

@@ -0,0 +1,128 @@
+from typing import Dict, List, Set
+from warnings import warn
+from edsl.prompts.Prompt import Prompt
+
+from edsl.agents.QuestionTemplateReplacementsBuilder import (
+    QuestionTemplateReplacementsBuilder as QTRB,
+)
+
+
+class QuestionInstructionPromptBuilder:
+    """Handles the construction and rendering of question instructions."""
+
+    def __init__(self, prompt_constructor: "PromptConstructor"):
+        self.prompt_constructor = prompt_constructor
+
+        self.model = self.prompt_constructor.model
+        self.survey = self.prompt_constructor.survey
+        self.question = self.prompt_constructor.question
+
+    def build(self) -> Prompt:
+        """Builds the complete question instructions prompt with all necessary components.
+
+        Returns:
+            Prompt: The fully rendered question instructions
+        """
+        base_prompt = self._create_base_prompt()
+        enriched_prompt = self._enrich_with_question_options(base_prompt)
+        rendered_prompt = self._render_prompt(enriched_prompt)
+        self._validate_template_variables(rendered_prompt)
+
+        return self._append_survey_instructions(rendered_prompt)
+
+    def _create_base_prompt(self) -> Dict:
+        """Creates the initial prompt with basic question data.
+
+        Returns:
+            Dict: Base question data
+        """
+        return {
+            "prompt": Prompt(self.question.get_instructions(model=self.model.model)),
+            "data": self.question.data.copy(),
+        }
+
+    def _enrich_with_question_options(self, prompt_data: Dict) -> Dict:
+        """Enriches the prompt data with question options if they exist.
+
+        Args:
+            prompt_data: Dictionary containing prompt and question data
+
+        Returns:
+            Dict: Enriched prompt data
+        """
+        if "question_options" in prompt_data["data"]:
+            from edsl.agents.QuestionOptionProcessor import QuestionOptionProcessor
+
+            question_options = QuestionOptionProcessor(
+                self.prompt_constructor
+            ).get_question_options(question_data=prompt_data["data"])
+
+            prompt_data["data"]["question_options"] = question_options
+        return prompt_data
+
+    def _render_prompt(self, prompt_data: Dict) -> Prompt:
+        """Renders the prompt using the replacement dictionary.
+
+        Args:
+            prompt_data: Dictionary containing prompt and question data
+
+        Returns:
+            Prompt: Rendered instructions
+        """
+
+        replacement_dict = QTRB(self.prompt_constructor).build_replacement_dict(
+            prompt_data["data"]
+        )
+        return prompt_data["prompt"].render(replacement_dict)
+
+    def _validate_template_variables(self, rendered_prompt: Prompt) -> None:
+        """Validates that all template variables have been properly replaced.
+
+        Args:
+            rendered_prompt: The rendered prompt to validate
+
+        Warns:
+            If any template variables remain undefined
+        """
+        undefined_vars = rendered_prompt.undefined_template_variables({})
+
+        # Check for question names in undefined variables
+        self._check_question_names_in_undefined_vars(undefined_vars)
+
+        # Warn about any remaining undefined variables
+        if undefined_vars:
+            warn(f"Question instructions still has variables: {undefined_vars}.")
+
+    def _check_question_names_in_undefined_vars(self, undefined_vars: Set[str]) -> None:
+        """Checks if any undefined variables match question names in the survey.
+
+        Args:
+            undefined_vars: Set of undefined template variables
+        """
+        for question_name in self.survey.question_names:
+            if question_name in undefined_vars:
+                print(
+                    f"Question name found in undefined_template_variables: {question_name}"
+                )
+
+    def _append_survey_instructions(self, rendered_prompt: Prompt) -> Prompt:
+        """Appends any relevant survey instructions to the rendered prompt.
+
+        Args:
+            rendered_prompt: The rendered prompt to append instructions to
+
+        Returns:
+            Prompt: Final prompt with survey instructions
+        """
+        relevant_instructions = self.survey._relevant_instructions(
+            self.question.question_name
+        )
+
+        if not relevant_instructions:
+            return rendered_prompt
+
+        preamble = Prompt(text="")
+        for instruction in relevant_instructions:
+            preamble += instruction.text
+
+        return preamble + rendered_prompt

edsl/agents/QuestionOptionProcessor.py

@@ -0,0 +1,172 @@
+from jinja2 import Environment, meta
+from typing import List, Optional, Union
+
+
+class QuestionOptionProcessor:
+    """
+    Class that manages the processing of question options.
+    These can be provided directly, as a template string, or fetched from prior answers or the scenario.
+    """
+
+    def __init__(self, prompt_constructor):
+        self.prompt_constructor = prompt_constructor
+
+    @staticmethod
+    def _get_default_options() -> list:
+        """Return default placeholder options."""
+        return [f"<< Option {i} - Placeholder >>" for i in range(1, 4)]
+
+    @staticmethod
+    def _parse_template_variable(template_str: str) -> str:
+        """
+        Extract the variable name from a template string.
+
+        Args:
+            template_str (str): Jinja template string
+
+        Returns:
+            str: Name of the first undefined variable in the template
+
+        >>> QuestionOptionProcessor._parse_template_variable("Here are some {{ options }}")
+        'options'
+        >>> QuestionOptionProcessor._parse_template_variable("Here are some {{ options }} and {{ other }}")
+        Traceback (most recent call last):
+        ...
+        ValueError: Multiple variables found in template string
+        >>> QuestionOptionProcessor._parse_template_variable("Here are some")
+        Traceback (most recent call last):
+        ...
+        ValueError: No variables found in template string
+        """
+        env = Environment()
+        parsed_content = env.parse(template_str)
+        undeclared_variables = list(meta.find_undeclared_variables(parsed_content))
+        if not undeclared_variables:
+            raise ValueError("No variables found in template string")
+        if len(undeclared_variables) > 1:
+            raise ValueError("Multiple variables found in template string")
+        return undeclared_variables[0]
+
+    @staticmethod
+    def _get_options_from_scenario(
+        scenario: dict, option_key: str
+    ) -> Union[list, None]:
+        """
+        Try to get options from scenario data.
+
+        >>> from edsl import Scenario
+        >>> scenario = Scenario({"options": ["Option 1", "Option 2"]})
+        >>> QuestionOptionProcessor._get_options_from_scenario(scenario, "options")
+        ['Option 1', 'Option 2']
+
+
+        Returns:
+            list | None: List of options if found in scenario, None otherwise
+        """
+        scenario_options = scenario.get(option_key)
+        return scenario_options if isinstance(scenario_options, list) else None
+
+    @staticmethod
+    def _get_options_from_prior_answers(
+        prior_answers: dict, option_key: str
+    ) -> Union[list, None]:
+        """
+        Try to get options from prior answers.
+
+        prior_answers (dict): Dictionary of prior answers
+        option_key (str): Key to look up in prior answers
+
+        >>> from edsl import QuestionList as Q
+        >>> q = Q.example()
+        >>> q.answer = ["Option 1", "Option 2"]
+        >>> prior_answers = {"options": q}
+        >>> QuestionOptionProcessor._get_options_from_prior_answers(prior_answers, "options")
+        ['Option 1', 'Option 2']
+        >>> QuestionOptionProcessor._get_options_from_prior_answers(prior_answers, "wrong_key") is None
+        True
+
+        Returns:
+            list | None: List of options if found in prior answers, None otherwise
+        """
+        prior_answer = prior_answers.get(option_key)
+        if prior_answer and hasattr(prior_answer, "answer"):
+            if isinstance(prior_answer.answer, list):
+                return prior_answer.answer
+        return None
+
+    def get_question_options(self, question_data: dict) -> list:
+        """
+        Extract and process question options from question data.
+
+        Args:
+            question_data (dict): Dictionary containing question configuration
+
+        Returns:
+            list: List of question options. Returns default placeholders if no valid options found.
+
+        >>> class MockPromptConstructor:
+        ...     pass
+        >>> mpc = MockPromptConstructor()
+        >>> from edsl import Scenario
+        >>> mpc.scenario = Scenario({"options": ["Option 1", "Option 2"]})
+        >>> processor = QuestionOptionProcessor(mpc)
+
+        The basic case where options are directly provided:
+
+        >>> question_data = {"question_options": ["Option 1", "Option 2"]}
+        >>> processor.get_question_options(question_data)
+        ['Option 1', 'Option 2']
+
+        The case where options are provided as a template string:
+
+        >>> question_data = {"question_options": "{{ options }}"}
+        >>> processor.get_question_options(question_data)
+        ['Option 1', 'Option 2']
+
+        The case where there is a templace string but it's in the prior answers:
+
+        >>> class MockQuestion:
+        ...     pass
+        >>> q0 = MockQuestion()
+        >>> q0.answer = ["Option 1", "Option 2"]
+        >>> mpc.prior_answers_dict = lambda: {'q0': q0}
+        >>> processor = QuestionOptionProcessor(mpc)
+        >>> question_data = {"question_options": "{{ q0 }}"}
+        >>> processor.get_question_options(question_data)
+        ['Option 1', 'Option 2']
+
+        The case we're no options are found:
+        >>> processor.get_question_options({"question_options": "{{ poop }}"})
+        ['<< Option 1 - Placeholder >>', '<< Option 2 - Placeholder >>', '<< Option 3 - Placeholder >>']
+
+        """
+        options_entry = question_data.get("question_options")
+
+        # If not a template string, return as is or default
+        if not isinstance(options_entry, str):
+            return options_entry if options_entry else self._get_default_options()
+
+        # Parse template to get variable name
+        option_key = self._parse_template_variable(options_entry)
+
+        # Try getting options from scenario
+        scenario_options = self._get_options_from_scenario(
+            self.prompt_constructor.scenario, option_key
+        )
+        if scenario_options:
+            return scenario_options
+
+        # Try getting options from prior answers
+        prior_answer_options = self._get_options_from_prior_answers(
+            self.prompt_constructor.prior_answers_dict(), option_key
+        )
+        if prior_answer_options:
+            return prior_answer_options
+
+        return self._get_default_options()
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/agents/QuestionTemplateReplacementsBuilder.py

@@ -0,0 +1,137 @@
+from jinja2 import Environment, meta
+from typing import Any, Set, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.agents.PromptConstructor import PromptConstructor
+    from edsl.scenarios.Scenario import Scenario
+
+
+class QuestionTemplateReplacementsBuilder:
+    def __init__(self, prompt_constructor: "PromptConstructor"):
+        self.prompt_constructor = prompt_constructor
+
+    def question_file_keys(self):
+        question_text = self.prompt_constructor.question.question_text
+        file_keys = self._find_file_keys(self.prompt_constructor.scenario)
+        return self._extract_file_keys_from_question_text(question_text, file_keys)
+
+    def scenario_file_keys(self):
+        return self._find_file_keys(self.prompt_constructor.scenario)
+
+    def get_jinja2_variables(template_str: str) -> Set[str]:
+        """
+        Extracts all variable names from a Jinja2 template using Jinja2's built-in parsing.
+
+        Args:
+        template_str (str): The Jinja2 template string
+
+        Returns:
+        Set[str]: A set of variable names found in the template
+        """
+        env = Environment()
+        ast = env.parse(template_str)
+        return meta.find_undeclared_variables(ast)
+
+    @staticmethod
+    def _find_file_keys(scenario: "Scenario") -> list:
+        """We need to find all the keys in the scenario that refer to FileStore objects.
+        These will be used to append to the prompt a list of files that are part of the scenario.
+
+        >>> from edsl import Scenario
+        >>> from edsl.scenarios.FileStore import FileStore
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile() as f:
+        ...     _ = f.write(b"Hello, world!")
+        ...     _ = f.seek(0)
+        ...     fs = FileStore(f.name)
+        ...     scenario = Scenario({"fs_file": fs, 'a': 1})
+        ...     QuestionTemplateReplacementsBuilder._find_file_keys(scenario)
+        ['fs_file']
+        """
+        from edsl.scenarios.FileStore import FileStore
+
+        file_entries = []
+        for key, value in scenario.items():
+            if isinstance(value, FileStore):
+                file_entries.append(key)
+        return file_entries
+
+    @staticmethod
+    def _extract_file_keys_from_question_text(
+        question_text: str, scenario_file_keys: list
+    ) -> list:
+        """
+        Extracts the file keys from a question text.
+
+        >>> from edsl import Scenario
+        >>> from edsl.scenarios.FileStore import FileStore
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile() as f:
+        ...     _ = f.write(b"Hello, world!")
+        ...     _ = f.seek(0)
+        ...     fs = FileStore(f.name)
+        ...     scenario = Scenario({"fs_file": fs, 'a': 1})
+        ...     QuestionTemplateReplacementsBuilder._extract_file_keys_from_question_text("{{ fs_file }}", ['fs_file'])
+        ['fs_file']
+        """
+        variables = QuestionTemplateReplacementsBuilder.get_jinja2_variables(
+            question_text
+        )
+        question_file_keys = []
+        for var in variables:
+            if var in scenario_file_keys:
+                question_file_keys.append(var)
+        return question_file_keys
+
+    def _scenario_replacements(self) -> dict[str, Any]:
+        # File references dictionary
+        file_refs = {key: f"<see file {key}>" for key in self.scenario_file_keys()}
+
+        # Scenario items excluding file keys
+        scenario_items = {
+            k: v
+            for k, v in self.prompt_constructor.scenario.items()
+            if k not in self.scenario_file_keys()
+        }
+        return {**file_refs, **scenario_items}
+
+    @staticmethod
+    def _question_data_replacements(
+        question: dict, question_data: dict
+    ) -> dict[str, Any]:
+        """Builds a dictionary of replacement values for rendering a prompt by combining multiple data sources.
+
+        >>> from edsl import QuestionMultipleChoice
+        >>> q = QuestionMultipleChoice(question_text="Do you like school?", question_name = "q0", question_options = ["yes", "no"])
+        >>> QuestionTemplateReplacementsBuilder._question_data_replacements(q, q.data)
+        {'use_code': False, 'include_comment': True, 'question_name': 'q0', 'question_text': 'Do you like school?', 'question_options': ['yes', 'no']}
+
+        """
+        question_settings = {
+            "use_code": getattr(question, "_use_code", True),
+            "include_comment": getattr(question, "_include_comment", False),
+        }
+        return {**question_settings, **question_data}
+
+    def build_replacement_dict(self, question_data: dict) -> dict[str, Any]:
+        """Builds a dictionary of replacement values for rendering a prompt by combining multiple data sources."""
+        rpl = {}
+        rpl["scenario"] = self._scenario_replacements()
+        rpl["question"] = self._question_data_replacements(
+            self.prompt_constructor.question, question_data
+        )
+        rpl["prior_answers"] = self.prompt_constructor.prior_answers_dict()
+        rpl["agent"] = {"agent": self.prompt_constructor.agent}
+
+        # Combine all dictionaries using dict.update() for clarity
+        replacement_dict = {}
+        for r in rpl.values():
+            replacement_dict.update(r)
+
+        return replacement_dict
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/agents/__init__.py

@@ -1,3 +1,2 @@
 from edsl.agents.Agent import Agent
 from edsl.agents.AgentList import AgentList
-from edsl.agents.InvigilatorBase import InvigilatorBase

edsl/agents/prompt_helpers.py

@@ -1,7 +1,7 @@
 import enum
 from typing import Dict, Optional
 from collections import UserList
-from edsl.prompts import Prompt
+from edsl.prompts.Prompt import Prompt
 
 
 class PromptComponent(enum.Enum):
@@ -12,14 +12,14 @@ class PromptComponent(enum.Enum):
 
 
 class PromptList(UserList):
-    separator = Prompt(" ")
+    separator = Prompt("")
 
     def reduce(self):
         """Reduce the list of prompts to a single prompt.
 
         >>> p = PromptList([Prompt("You are a happy-go lucky agent."), Prompt("You are an agent with the following persona: {'age': 22, 'hair': 'brown', 'height': 5.5}")])
         >>> p.reduce()
-        Prompt(text=\"""You are a happy-go lucky agent. You are an agent with the following persona: {'age': 22, 'hair': 'brown', 'height': 5.5}\""")
+        Prompt(text=\"""You are a happy-go lucky agent.You are an agent with the following persona: {'age': 22, 'hair': 'brown', 'height': 5.5}\""")
 
         """
         p = self[0]

edsl/config.py

@@ -1,12 +1,16 @@
 """This module provides a Config class that loads environment variables from a .env file and sets them as class attributes."""
 
 import os
+import platformdirs
 from dotenv import load_dotenv, find_dotenv
-from edsl.exceptions import (
+from edsl.exceptions.configuration import (
     InvalidEnvironmentVariableError,
     MissingEnvironmentVariableError,
 )
 
+cache_dir = platformdirs.user_cache_dir("edsl")
+os.makedirs(cache_dir, exist_ok=True)
+
 # valid values for EDSL_RUN_MODE
 EDSL_RUN_MODES = [
     "development",
@@ -34,7 +38,8 @@ CONFIG_MAP = {
         "info": "This config var determines the maximum number of seconds to wait before retrying a failed API call.",
     },
     "EDSL_DATABASE_PATH": {
-        "default": f"sqlite:///{os.path.join(os.getcwd(), '.edsl_cache/data.db')}",
+        # "default": f"sqlite:///{os.path.join(os.getcwd(), '.edsl_cache/data.db')}",
+        "default": f"sqlite:///{os.path.join(platformdirs.user_cache_dir('edsl'), 'lm_model_calls.db')}",
         "info": "This config var determines the path to the cache file.",
     },
     "EDSL_DEFAULT_MODEL": {
@@ -69,6 +74,10 @@ CONFIG_MAP = {
         "default": "False",
         "info": "This config var determines whether to open the exception report URL in the browser",
     },
+    "EDSL_REMOTE_TOKEN_BUCKET_URL": {
+        "default": "None",
+        "info": "This config var holds the URL of the remote token bucket server.",
+    },
 }
 
 
@@ -81,6 +90,9 @@ class Config:
         self._load_dotenv()
         self._set_env_vars()
 
+    def show_path_to_dot_env(self):
+        print(find_dotenv(usecwd=True))
+
     def _set_run_mode(self) -> None:
         """
         Sets EDSL_RUN_MODE as a class attribute.
@@ -144,6 +156,14 @@ class Config:
             raise MissingEnvironmentVariableError(f"{env_var} is not set. {info}")
         return self.__dict__.get(env_var)
 
+    def __iter__(self):
+        """Iterate over the environment variables."""
+        return iter(self.__dict__)
+
+    def items(self):
+        """Iterate over the environment variables and their values."""
+        return self.__dict__.items()
+
     def show(self) -> str:
         """Print the currently set environment vars."""
         max_env_var_length = max(len(env_var) for env_var in self.__dict__)

edsl/conversation/car_buying.py

@@ -29,7 +29,8 @@ a3 = Agent(
 c1 = Conversation(agent_list=AgentList([a1, a3, a2]), max_turns=5, verbose=True)
 c2 = Conversation(agent_list=AgentList([a1, a2]), max_turns=5, verbose=True)
 
-c = Cache.load("car_talk.json.gz")
+# c = Cache.load("car_talk.json.gz")
+c = Cache()
 # breakpoint()
 combo = ConversationList([c1, c2], cache=c)
 combo.run()

edsl/coop/CoopFunctionsMixin.py

@@ -0,0 +1,15 @@
+class CoopFunctionsMixin:
+    def better_names(self, existing_names):
+        from edsl import QuestionList, Scenario
+
+        s = Scenario({"existing_names": existing_names})
+        q = QuestionList(
+            question_text="""The following colum names are already in use: {{ existing_names }} 
+                         Please provide new names for the columns.
+                         They should be short, one or two words, and unique. They should be valid Python idenifiers. 
+                         No spaces - use underscores instead. 
+                         """,
+            question_name="better_names",
+        )
+        results = q.by(s).run(verbose=False)
+        return results.select("answer.better_names").first()

edsl/coop/ExpectedParrotKeyHandler.py

@@ -0,0 +1,125 @@
+from pathlib import Path
+import os
+import platformdirs
+
+
+import sys
+import select
+
+
+def get_input_with_timeout(prompt, timeout=5, default="y"):
+    print(prompt, end="", flush=True)
+    ready, _, _ = select.select([sys.stdin], [], [], timeout)
+    if ready:
+        return sys.stdin.readline().strip()
+    print(f"\nNo input received within {timeout} seconds. Using default: {default}")
+    return default
+
+
+class ExpectedParrotKeyHandler:
+    asked_to_store_file_name = "asked_to_store.txt"
+    ep_key_file_name = "ep_api_key.txt"
+    application_name = "edsl"
+
+    @property
+    def config_dir(self):
+        return platformdirs.user_config_dir(self.application_name)
+
+    def _ep_key_file_exists(self) -> bool:
+        """Check if the Expected Parrot key file exists."""
+        return Path(self.config_dir).joinpath(self.ep_key_file_name).exists()
+
+    def ok_to_ask_to_store(self):
+        """Check if it's okay to ask the user to store the key."""
+        from edsl.config import CONFIG
+
+        if CONFIG.get("EDSL_RUN_MODE") != "production":
+            return False
+
+        return (
+            not Path(self.config_dir).joinpath(self.asked_to_store_file_name).exists()
+        )
+
+    def reset_asked_to_store(self):
+        """Reset the flag that indicates whether the user has been asked to store the key."""
+        asked_to_store_path = Path(self.config_dir).joinpath(
+            self.asked_to_store_file_name
+        )
+        if asked_to_store_path.exists():
+            os.remove(asked_to_store_path)
+            print(
+                "Deleted the file that indicates whether the user has been asked to store the key."
+            )
+
+    def ask_to_store(self, api_key) -> bool:
+        """Ask the user if they want to store the Expected Parrot key. If they say "yes", store it."""
+        if self.ok_to_ask_to_store():
+            # can_we_store = get_input_with_timeout(
+            #     "Would you like to store your Expected Parrot key for future use? (y/n): ",
+            #     timeout=5,
+            #     default="y",
+            # )
+            can_we_store = "y"
+            if can_we_store.lower() == "y":
+                Path(self.config_dir).mkdir(parents=True, exist_ok=True)
+                self.store_ep_api_key(api_key)
+                # print("Stored Expected Parrot API key at ", self.config_dir)
+                return True
+            else:
+                Path(self.config_dir).mkdir(parents=True, exist_ok=True)
+                with open(
+                    Path(self.config_dir).joinpath(self.asked_to_store_file_name), "w"
+                ) as f:
+                    f.write("Yes")
+        return False
+
+    def get_ep_api_key(self):
+        # check if the key is stored in the config_dir
+        api_key = None
+        api_key_from_cache = None
+        api_key_from_os = None
+
+        if self._ep_key_file_exists():
+            with open(Path(self.config_dir).joinpath(self.ep_key_file_name), "r") as f:
+                api_key_from_cache = f.read().strip()
+
+        api_key_from_os = os.getenv("EXPECTED_PARROT_API_KEY")
+
+        if api_key_from_os and api_key_from_cache:
+            if api_key_from_os != api_key_from_cache:
+                import warnings
+
+                warnings.warn(
+                    "WARNING: The Expected Parrot API key from the environment variable "
+                    "differs from the one stored in the config directory. Using the one "
+                    "from the environment variable."
+                )
+            api_key = api_key_from_os
+
+        if api_key_from_os and not api_key_from_cache:
+            api_key = api_key_from_os
+
+        if not api_key_from_os and api_key_from_cache:
+            api_key = api_key_from_cache
+
+        if api_key is not None:
+            _ = self.ask_to_store(api_key)
+        return api_key
+
+    def delete_ep_api_key(self):
+        key_path = Path(self.config_dir) / self.ep_key_file_name
+        if key_path.exists():
+            os.remove(key_path)
+            print("Deleted Expected Parrot API key at ", key_path)
+
+    def store_ep_api_key(self, api_key):
+        # Create the directory if it doesn't exist
+        os.makedirs(self.config_dir, exist_ok=True)
+
+        # Create the path for the key file
+        key_path = Path(self.config_dir) / self.ep_key_file_name
+
+        # Save the key
+        with open(key_path, "w") as f:
+            f.write(api_key)
+        # print("Stored Expected Parrot API key at ", key_path)