edsl 0.1.37.dev4__py3-none-any.whl → 0.1.37.dev6__py3-none-any.whl

edsl/conjure/AgentConstructionMixin.py

@@ -99,6 +99,8 @@ class AgentConstructionMixin:
         sample_size: int = None,
         seed: str = "edsl",
         dryrun=False,
+        disable_remote_cache: bool = False,
+        disable_remote_inference: bool = False,
     ) -> Union[Results, None]:
         """Return the results of the survey.
 
@@ -109,7 +111,7 @@ class AgentConstructionMixin:
 
         >>> from edsl.conjure.InputData import InputDataABC
         >>> id = InputDataABC.example()
-        >>> r = id.to_results()
+        >>> r = id.to_results(disable_remote_cache = True, disable_remote_inference = True)
         >>> len(r) == id.num_observations
         True
         """
@@ -125,7 +127,10 @@ class AgentConstructionMixin:
             import time
 
             start = time.time()
-            _ = survey.by(agent_list.sample(DRYRUN_SAMPLE)).run()
+            _ = survey.by(agent_list.sample(DRYRUN_SAMPLE)).run(
+                disable_remote_cache=disable_remote_cache,
+                disable_remote_inference=disable_remote_inference,
+            )
             end = time.time()
             print(f"Time to run {DRYRUN_SAMPLE} agents (s): {round(end - start, 2)}")
             time_per_agent = (end - start) / DRYRUN_SAMPLE
@@ -143,7 +148,10 @@ class AgentConstructionMixin:
                     f"Full sample will take about {round(full_sample_time / 3600, 2)} hours."
                 )
             return None
-        return survey.by(agent_list).run()
+        return survey.by(agent_list).run(
+            disable_remote_cache=disable_remote_cache,
+            disable_remote_inference=disable_remote_inference,
+        )
 
 
 if __name__ == "__main__":

edsl/conversation/Conversation.py

@@ -5,7 +5,7 @@ from typing import Optional, Callable
 from edsl import Agent, QuestionFreeText, Results, AgentList, ScenarioList, Scenario
 from edsl.questions import QuestionBase
 from edsl.results.Result import Result
-
+from jinja2 import Template
 from edsl.data import Cache
 
 from edsl.conversation.next_speaker_utilities import (
@@ -54,6 +54,9 @@ class Conversation:
     """A conversation between a list of agents. The first agent in the list is the first speaker.
     After that, order is determined by the next_speaker function.
     The question asked to each agent is determined by the next_statement_question.
+
+    If the user has passed in a "per_round_message_template", this will be displayed at the beginning of each round.
+    {{ round_message }} must be in the question_text.
     """
 
     def __init__(
@@ -64,28 +67,62 @@ class Conversation:
         next_statement_question: Optional[QuestionBase] = None,
         next_speaker_generator: Optional[Callable] = None,
         verbose: bool = False,
+        per_round_message_template: Optional[str] = None,
         conversation_index: Optional[int] = None,
         cache=None,
+        disable_remote_inference=False,
+        default_model: Optional["LanguageModel"] = None,
     ):
+        self.disable_remote_inference = disable_remote_inference
+        self.per_round_message_template = per_round_message_template
+
         if cache is None:
             self.cache = Cache()
         else:
             self.cache = cache
 
         self.agent_list = agent_list
+
+        from edsl import Model
+
+        for agent in self.agent_list:
+            if not hasattr(agent, "model"):
+                if default_model is not None:
+                    agent.model = default_model
+                else:
+                    agent.model = Model()
+
         self.verbose = verbose
         self.agent_statements = []
         self._conversation_index = conversation_index
-
         self.agent_statements = AgentStatements()
 
         self.max_turns = max_turns
 
         if next_statement_question is None:
+            import textwrap
+
+            base_question = textwrap.dedent(
+                """\
+You are {{ agent_name }}. This is the conversation so far: {{ conversation }}
+{% if round_message is not none %}
+{{ round_message }}
+{% endif %}
+What do you say next?"""
+            )
             self.next_statement_question = QuestionFreeText(
-                question_text="You are {{ agent_name }}. This is the converstaion so far: {{ conversation }}. What do you say next?",
+                question_text=base_question,
                 question_name="dialogue",
             )
+        else:
+            self.next_statement_question = next_statement_question
+            if (
+                per_round_message_template
+                and "{{ round_message }}" not in next_statement_question.question_text
+            ):
+                raise ValueError(
+                    "If you pass in a per_round_message_template, you must include {{ round_message }} in the question_text."
+                )
 
         # Determine how the next speaker is chosen
         if next_speaker_generator is None:
@@ -93,6 +130,7 @@ class Conversation:
         else:
             func = next_speaker_generator
 
+        # Choose the next speaker
         self.next_speaker = speaker_closure(
             agent_list=self.agent_list, generator_function=func
         )
@@ -158,18 +196,32 @@ class Conversation:
         }
         return Scenario(d)
 
-    async def get_next_statement(self, *, index, speaker, conversation):
+    async def get_next_statement(self, *, index, speaker, conversation) -> "Result":
+        """Get the next statement from the speaker."""
         q = self.next_statement_question
-        assert q.parameters == {"agent_name", "conversation"}, q.parameters
-        results = await q.run_async(
-            index=index,
-            conversation=conversation,
-            conversation_index=self.conversation_index,
-            agent_name=speaker.name,
-            agent=speaker,
-            just_answer=False,
-            cache=self.cache,
-            model=speaker.model,
+        # assert q.parameters == {"agent_name", "conversation"}, q.parameters
+        from edsl import Scenario
+
+        if self.per_round_message_template is None:
+            round_message = None
+        else:
+            round_message = Template(self.per_round_message_template).render(
+                {"max_turns": self.max_turns, "current_turn": index}
+            )
+
+        s = Scenario(
+            {
+                "agent_name": speaker.name,
+                "conversation": conversation,
+                "conversation_index": self.conversation_index,
+                "index": index,
+                "round_message": round_message,
+            }
+        )
+        jobs = q.by(s).by(speaker).by(speaker.model)
+        jobs.show_prompts()
+        results = await jobs.run_async(
+            cache=self.cache, disable_remote_inference=self.disable_remote_inference
         )
         return results[0]
 

edsl/conversation/chips.py

@@ -0,0 +1,95 @@
+from typing import Optional
+
+from edsl import Agent, AgentList, QuestionFreeText
+from edsl import Cache
+from edsl import QuestionList
+from edsl import Model
+
+from edsl.conversation.Conversation import Conversation, ConversationList
+
+m = Model("gemini-1.5-flash")
+
+
+class ChipLover(Agent):
+    def __init__(self, name, chip_values, initial_chips, model: Optional[Model] = None):
+        self.chip_values = chip_values
+        self.initial_chips = initial_chips
+        self.current_chips = initial_chips
+        self.model = model or Model()
+        super().__init__(
+            name=name,
+            traits={
+                "motivation": f"""
+            You are {name}. You are negotiating the trading of colored 'chips' with other players. You want to maximize your score.
+            When you want to accept a deal, say "DEAL!" 
+            Note that different players can have different values for the chips.
+            """,
+                "chip_values": chip_values,
+                "initial_chips": initial_chips,
+            },
+        )
+
+    def trade(self, chips_given_dict, chips_received_dict):
+        for color, amount in chips_given_dict.items():
+            self.current_chips[color] -= amount
+        for color, amount in chips_received_dict.items():
+            self.current_chips[color] += amount
+
+    def get_score(self):
+        return sum(
+            self.chip_values[color] * self.current_chips[color]
+            for color in self.chip_values
+        )
+
+
+a1 = ChipLover(
+    name="Alice",
+    chip_values={"Green": 7, "Blue": 1, "Red": 0},
+    model=Model("gemini-1.5-flash"),
+    initial_chips={"Green": 1, "Blue": 2, "Red": 3},
+)
+a2 = ChipLover(
+    name="Bob",
+    chip_values={"Green": 7, "Blue": 1, "Red": 0},
+    initial_chips={"Green": 1, "Blue": 2, "Red": 3},
+)
+
+c1 = Conversation(agent_list=AgentList([a1, a2]), max_turns=10, verbose=True)
+c2 = Conversation(agent_list=AgentList([a1, a2]), max_turns=10, verbose=True)
+
+with Cache() as c:
+    combo = ConversationList([c1, c2], cache=c)
+    combo.run()
+    results = combo.to_results()
+    results.select("conversation_index", "index", "agent_name", "dialogue").print(
+        format="rich"
+    )
+
+    q = QuestionFreeText(
+        question_text="""This was a conversation/negotiation: {{ transcript }}. 
+                        What trades occurred in the conversation?
+                        """,
+        question_name="trades",
+    )
+
+    q_actors = QuestionList(
+        question_text="""Here is a transcript: {{ transcript }}. 
+                        Who were the actors in the conversation?
+                        """,
+        question_name="actors",
+    )
+
+    from edsl import QuestionList
+
+    q_transfers = QuestionList(
+        question_text="""This was a conversation/negotiation: {{ transcript }}. 
+                        Extract all offers and their outcomes.
+                        Use this format: {'proposing_agent':"Alice": 'receiving_agent': "Bob", 'gives':{"Green": 1, "Blue": 2}, 'receives':{"Green": 2, "Blue": 1}, 'accepted':True}
+                        """,
+        question_name="transfers",
+    )
+
+    transcript_analysis = (
+        q.add_question(q_actors).add_question(q_transfers).by(combo.summarize()).run()
+    )
+    transcript_analysis.select("trades", "actors", "transfers").print(format="rich")

edsl/coop/coop.py

@@ -90,18 +90,83 @@ class Coop:
 
         return response
 
-    def _resolve_server_response(self, response: requests.Response) -> None:
+    def _resolve_server_response(
+        self, response: requests.Response, check_api_key: bool = True
+    ) -> None:
         """
         Check the response from the server and raise errors as appropriate.
         """
         if response.status_code >= 400:
             message = response.json().get("detail")
             # print(response.text)
-            if "Authorization" in message:
+            if "The API key you provided is invalid" in message and check_api_key:
+                import secrets
+                from edsl.utilities.utilities import write_api_key_to_env
+
+                edsl_auth_token = secrets.token_urlsafe(16)
+
+                print("Your Expected Parrot API key is invalid.")
+                print(
+                    "\nUse the link below to log in to Expected Parrot so we can automatically update your API key."
+                )
+                self._display_login_url(edsl_auth_token=edsl_auth_token)
+                api_key = self._poll_for_api_key(edsl_auth_token)
+
+                if api_key is None:
+                    print("\nTimed out waiting for login. Please try again.")
+                    return
+
+                write_api_key_to_env(api_key)
+                print("\n✨ API key retrieved and written to .env file.")
+                print("Rerun your code to try again with a valid API key.")
+                return
+
+            elif "Authorization" in message:
                 print(message)
                 message = "Please provide an Expected Parrot API key."
+
             raise CoopServerResponseError(message)
 
+    def _poll_for_api_key(
+        self, edsl_auth_token: str, timeout: int = 120
+    ) -> Union[str, None]:
+        """
+        Allows the user to retrieve their Expected Parrot API key by logging in with an EDSL auth token.
+
+        :param edsl_auth_token: The EDSL auth token to use for login
+        :param timeout: Maximum time to wait for login, in seconds (default: 120)
+        """
+        import time
+        from datetime import datetime
+
+        start_poll_time = time.time()
+        waiting_for_login = True
+        while waiting_for_login:
+            elapsed_time = time.time() - start_poll_time
+            if elapsed_time > timeout:
+                # Timed out waiting for the user to log in
+                print("\r" + " " * 80 + "\r", end="")
+                return None
+
+            api_key = self._get_api_key(edsl_auth_token)
+            if api_key is not None:
+                print("\r" + " " * 80 + "\r", end="")
+                return api_key
+            else:
+                duration = 5
+                time_checked = datetime.now().strftime("%Y-%m-%d %I:%M:%S %p")
+                frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+                start_time = time.time()
+                i = 0
+                while time.time() - start_time < duration:
+                    print(
+                        f"\r{frames[i % len(frames)]} Waiting for login. Last checked: {time_checked}",
+                        end="",
+                        flush=True,
+                    )
+                    time.sleep(0.1)
+                    i += 1
+
     def _json_handle_none(self, value: Any) -> Any:
         """
         Handle None values during JSON serialization.
@@ -134,7 +199,7 @@ class Coop:
             response = self._send_server_request(
                 uri="api/v0/edsl-settings", method="GET", timeout=5
             )
-            self._resolve_server_response(response)
+            self._resolve_server_response(response, check_api_key=False)
             return response.json()
         except Timeout:
             return {}
@@ -489,6 +554,7 @@ class Coop:
         description: Optional[str] = None,
         status: RemoteJobStatus = "queued",
         visibility: Optional[VisibilityType] = "unlisted",
+        initial_results_visibility: Optional[VisibilityType] = "unlisted",
         iterations: Optional[int] = 1,
     ) -> dict:
         """
@@ -517,6 +583,7 @@ class Coop:
                 "iterations": iterations,
                 "visibility": visibility,
                 "version": self._edsl_version,
+                "initial_results_visibility": initial_results_visibility,
             },
         )
         self._resolve_server_response(response)
@@ -664,6 +731,17 @@ class Coop:
         else:
             return {}
 
+    def fetch_models(self) -> dict:
+        """
+        Fetch a dict of available models from Coop.
+
+        Each key in the dict is an inference service, and each value is a list of models from that service.
+        """
+        response = self._send_server_request(uri="api/v0/models", method="GET")
+        self._resolve_server_response(response)
+        data = response.json()
+        return data
+
     def fetch_rate_limit_config_vars(self) -> dict:
         """
         Fetch a dict of rate limit config vars from Coop.
@@ -678,6 +756,59 @@ class Coop:
         data = response.json()
         return data
 
+    def _display_login_url(self, edsl_auth_token: str):
+        """
+        Uses rich.print to display a login URL.
+
+        - We need this function because URL detection with print() does not work alongside animations in VSCode.
+        """
+        from rich import print as rich_print
+
+        url = f"{CONFIG.EXPECTED_PARROT_URL}/login?edsl_auth_token={edsl_auth_token}"
+
+        rich_print(f"[#38bdf8][link={url}]{url}[/link][/#38bdf8]")
+
+    def _get_api_key(self, edsl_auth_token: str):
+        """
+        Given an EDSL auth token, find the corresponding user's API key.
+        """
+
+        response = self._send_server_request(
+            uri="api/v0/get-api-key",
+            method="POST",
+            payload={
+                "edsl_auth_token": edsl_auth_token,
+            },
+        )
+        data = response.json()
+        api_key = data.get("api_key")
+        return api_key
+
+    def login(self):
+        """
+        Starts the EDSL auth token login flow.
+        """
+        import secrets
+        from dotenv import load_dotenv
+        from edsl.utilities.utilities import write_api_key_to_env
+
+        edsl_auth_token = secrets.token_urlsafe(16)
+
+        print(
+            "\nUse the link below to log in to Expected Parrot so we can automatically update your API key."
+        )
+        self._display_login_url(edsl_auth_token=edsl_auth_token)
+        api_key = self._poll_for_api_key(edsl_auth_token)
+
+        if api_key is None:
+            raise Exception("Timed out waiting for login. Please try again.")
+
+        write_api_key_to_env(api_key)
+        print("\n✨ API key retrieved and written to .env file.")
+
+        # Add API key to environment
+        load_dotenv()
+
 
 if __name__ == "__main__":
     sheet_data = fetch_sheet_data()

edsl/data/Cache.py

@@ -194,7 +194,7 @@ class Cache(Base):
         >>> c = Cache()
         >>> len(c)
         0
-        >>> results = Question.example("free_text").by(m).run(cache = c)
+        >>> results = Question.example("free_text").by(m).run(cache = c, disable_remote_cache = True, disable_remote_inference = True)
         >>> len(c)
         1
         """

edsl/exceptions/BaseException.py

@@ -0,0 +1,21 @@
+class BaseException(Exception):
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+    def __init__(self, message, *, show_docs=True):
+        # Format main error message
+        formatted_message = [message.strip()]
+
+        # Add documentation links if requested
+        if show_docs:
+            if hasattr(self, "relevant_doc"):
+                formatted_message.append(
+                    f"\nFor more information, see:\n{self.relevant_doc}"
+                )
+            if hasattr(self, "relevant_notebook"):
+                formatted_message.append(
+                    f"\nFor a usage example, see:\n{self.relevant_notebook}"
+                )
+
+        # Join with double newlines for clear separation
+        final_message = "\n\n".join(formatted_message)
+        super().__init__(final_message)

edsl/exceptions/__init__.py

@@ -1,8 +1,8 @@
 from .agents import (
-    AgentAttributeLookupCallbackError,
+    #    AgentAttributeLookupCallbackError,
     AgentCombinationError,
-    AgentLacksLLMError,
-    AgentRespondedWithBadJSONError,
+    #    AgentLacksLLMError,
+    #    AgentRespondedWithBadJSONError,
 )
 from .configuration import (
     InvalidEnvironmentVariableError,
@@ -14,6 +14,10 @@ from .data import (
     DatabaseIntegrityError,
 )
 
+from .scenarios import (
+    ScenarioError,
+)
+
 from .general import MissingAPIKeyError
 
 from .jobs import JobsRunError, InterviewErrorPriorTaskCanceled, InterviewTimeoutError

edsl/exceptions/agents.py

@@ -1,37 +1,35 @@
-class AgentErrors(Exception):
-    pass
+from edsl.exceptions.BaseException import BaseException
 
 
-class AgentDynamicTraitsFunctionError(AgentErrors):
-    pass
+class AgentErrors(BaseException):
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html"
 
 
-class AgentDirectAnswerFunctionError(AgentErrors):
-    pass
+class AgentDynamicTraitsFunctionError(AgentErrors):
+    relevant_doc = (
+        "https://docs.expectedparrot.com/en/latest/agents.html#dynamic-traits-function"
+    )
+    relevant_notebook = "https://docs.expectedparrot.com/en/latest/notebooks/example_agent_dynamic_traits.html"
 
 
-class AgentAttributeLookupCallbackError(AgentErrors):
-    pass
+class AgentDirectAnswerFunctionError(AgentErrors):
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-direct-answering-methods"
 
 
 class AgentCombinationError(AgentErrors):
-    pass
-
-
-class AgentLacksLLMError(AgentErrors):
-    pass
-
-
-class AgentRespondedWithBadJSONError(AgentErrors):
-    pass
+    relevant_doc = (
+        "https://docs.expectedparrot.com/en/latest/agents.html#combining-agents"
+    )
 
 
 class AgentNameError(AgentErrors):
-    pass
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-names"
 
 
 class AgentTraitKeyError(AgentErrors):
-    pass
+    relevant_doc = (
+        "https://docs.expectedparrot.com/en/latest/agents.html#constructing-an-agent"
+    )
 
 
 class FailedTaskException(Exception):

edsl/exceptions/results.py

@@ -1,26 +1,29 @@
-class ResultsErrors(Exception):
-    pass
+from edsl.exceptions.BaseException import BaseException
+
+
+class ResultsError(BaseException):
+    relevant_docs = "https://docs.expectedparrot.com/en/latest/results.html"
 
 
-class ResultsDeserializationError(ResultsErrors):
+class ResultsDeserializationError(ResultsError):
     pass
 
 
-class ResultsBadMutationstringError(ResultsErrors):
+class ResultsBadMutationstringError(ResultsError):
     pass
 
 
-class ResultsColumnNotFoundError(ResultsErrors):
+class ResultsColumnNotFoundError(ResultsError):
     pass
 
 
-class ResultsInvalidNameError(ResultsErrors):
+class ResultsInvalidNameError(ResultsError):
     pass
 
 
-class ResultsMutateError(ResultsErrors):
+class ResultsMutateError(ResultsError):
     pass
 
 
-class ResultsFilterError(ResultsErrors):
+class ResultsFilterError(ResultsError):
     pass

edsl/exceptions/scenarios.py

@@ -0,0 +1,22 @@
+import re
+import textwrap
+
+
+class ScenarioError(Exception):
+    documentation = "https://docs.expectedparrot.com/en/latest/scenarios.html#module-edsl.scenarios.Scenario"
+
+    def __init__(self, message: str):
+        self.message = message + "\n" + "Documentation: " + self.documentation
+        super().__init__(self.message)
+
+    def __str__(self):
+        return self.make_urls_clickable(self.message)
+
+    @staticmethod
+    def make_urls_clickable(text):
+        url_pattern = r"https?://[^\s]+"
+        urls = re.findall(url_pattern, text)
+        for url in urls:
+            clickable_url = f"\033]8;;{url}\007{url}\033]8;;\007"
+            text = text.replace(url, clickable_url)
+        return text

edsl/exceptions/surveys.py

@@ -1,34 +1,37 @@
-class SurveyErrors(Exception):
-    pass
+from edsl.exceptions.BaseException import BaseException
+
+
+class SurveyError(BaseException):
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html"
 
 
-class SurveyCreationError(SurveyErrors):
+class SurveyCreationError(SurveyError):
     pass
 
 
-class SurveyHasNoRulesError(SurveyErrors):
+class SurveyHasNoRulesError(SurveyError):
     pass
 
 
-class SurveyRuleSendsYouBackwardsError(SurveyErrors):
+class SurveyRuleSendsYouBackwardsError(SurveyError):
     pass
 
 
-class SurveyRuleSkipLogicSyntaxError(SurveyErrors):
+class SurveyRuleSkipLogicSyntaxError(SurveyError):
     pass
 
 
-class SurveyRuleReferenceInRuleToUnknownQuestionError(SurveyErrors):
+class SurveyRuleReferenceInRuleToUnknownQuestionError(SurveyError):
     pass
 
 
-class SurveyRuleRefersToFutureStateError(SurveyErrors):
+class SurveyRuleRefersToFutureStateError(SurveyError):
     pass
 
 
-class SurveyRuleCollectionHasNoRulesAtNodeError(SurveyErrors):
+class SurveyRuleCollectionHasNoRulesAtNodeError(SurveyError):
     pass
 
 
-class SurveyRuleCannotEvaluateError(SurveyErrors):
+class SurveyRuleCannotEvaluateError(SurveyError):
     pass