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

edsl/jobs/JobsChecks.py

@@ -1,16 +1,21 @@
 import os
-from edsl.exceptions import MissingAPIKeyError
+from edsl.exceptions.general import MissingAPIKeyError
 
 
 class JobsChecks:
     def __init__(self, jobs):
-        """ """
+        """Checks a Jobs object for missing API keys and other requirements."""
         self.jobs = jobs
 
     def check_api_keys(self) -> None:
-        from edsl import Model
+        from edsl.language_models.registry import Model
 
-        for model in self.jobs.models + [Model()]:
+        if len(self.jobs.models) == 0:
+            models = [Model()]
+        else:
+            models = self.jobs.models
+
+        for model in models:  # + [Model()]:
             if not model.has_valid_api_key():
                 raise MissingAPIKeyError(
                     model_name=str(model.model),
@@ -23,7 +28,7 @@ class JobsChecks:
         """
         missing_api_keys = set()
 
-        from edsl import Model
+        from edsl.language_models.registry import Model
         from edsl.enums import service_to_api_keyname
 
         for model in self.jobs.models + [Model()]:
@@ -95,16 +100,33 @@ class JobsChecks:
             return True
 
     def needs_key_process(self):
+        """
+        A User needs the key process when:
+        1. They don't have all the model keys
+        2. They don't have the EP API
+        3. They need external LLMs to run the job
+        """
         return (
             not self.user_has_all_model_keys()
             and not self.user_has_ep_api_key()
             and self.needs_external_llms()
         )
 
+    def status(self) -> dict:
+        """
+        Returns a dictionary with the status of the job checks.
+        """
+        return {
+            "user_has_ep_api_key": self.user_has_ep_api_key(),
+            "user_has_all_model_keys": self.user_has_all_model_keys(),
+            "needs_external_llms": self.needs_external_llms(),
+            "needs_key_process": self.needs_key_process(),
+        }
+
     def key_process(self):
         import secrets
         from dotenv import load_dotenv
-        from edsl import CONFIG
+        from edsl.config import CONFIG
         from edsl.coop.coop import Coop
         from edsl.utilities.utilities import write_api_key_to_env
 
@@ -119,10 +141,12 @@ class JobsChecks:
             "\nYou can either add the missing keys to your .env file, or use remote inference."
         )
         print("Remote inference allows you to run jobs on our server.")
-        print("\n🚀 To use remote inference, sign up at the following link:")
 
         coop = Coop()
-        coop._display_login_url(edsl_auth_token=edsl_auth_token)
+        coop._display_login_url(
+            edsl_auth_token=edsl_auth_token,
+            link_description="\n🚀 To use remote inference, sign up at the following link:",
+        )
 
         print(
             "\nOnce you log in, we will automatically retrieve your Expected Parrot API key and continue your job remotely."
@@ -134,8 +158,9 @@ class JobsChecks:
             print("\nTimed out waiting for login. Please try again.")
             return
 
-        write_api_key_to_env(api_key)
-        print("✨ API key retrieved and written to .env file.\n")
+        path_to_env = write_api_key_to_env(api_key)
+        print("\n✨ API key retrieved and written to .env file at the following path:")
+        print(f"    {path_to_env}")
 
         # Retrieve API key so we can continue running the job
         load_dotenv()

edsl/jobs/JobsComponentConstructor.py

@@ -0,0 +1,189 @@
+from typing import Union, Sequence, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.agents.Agent import Agent
+    from edsl.language_models.LanguageModel import LanguageModel
+    from edsl.scenarios.Scenario import Scenario
+    from edsl.jobs.Jobs import Jobs
+
+
+class JobsComponentConstructor:
+    "Handles the creation of Agents, Scenarios, and LanguageModels in a job."
+
+    def __init__(self, jobs: "Jobs"):
+        self.jobs = jobs
+
+    def by(
+        self,
+        *args: Union[
+            "Agent",
+            "Scenario",
+            "LanguageModel",
+            Sequence[Union["Agent", "Scenario", "LanguageModel"]],
+        ],
+    ) -> "Jobs":
+        """
+        Add Agents, Scenarios and LanguageModels to a job.
+
+        :param args: objects or a sequence (list, tuple, ...) of objects of the same type
+
+        If no objects of this type exist in the Jobs instance, it stores the new objects as a list in the corresponding attribute.
+        Otherwise, it combines the new objects with existing objects using the object's `__add__` method.
+
+        This 'by' is intended to create a fluent interface.
+
+        >>> from edsl.surveys import Survey
+        >>> from edsl.questions import QuestionFreeText
+        >>> q = QuestionFreeText(question_name="name", question_text="What is your name?")
+        >>> from edsl.jobs import Jobs
+        >>> j = Jobs(survey = Survey(questions=[q]))
+        >>> j
+        Jobs(survey=Survey(...), agents=AgentList([]), models=ModelList([]), scenarios=ScenarioList([]))
+        >>> from edsl import Agent; a = Agent(traits = {"status": "Sad"})
+        >>> j.by(a).agents
+        AgentList([Agent(traits = {'status': 'Sad'})])
+
+
+        Notes:
+        - all objects must implement the 'get_value', 'set_value', and `__add__` methods
+        - agents: traits of new agents are combined with traits of existing agents. New and existing agents should not have overlapping traits, and do not increase the # agents in the instance
+        - scenarios: traits of new scenarios are combined with traits of old existing. New scenarios will overwrite overlapping traits, and do not increase the number of scenarios in the instance
+        - models: new models overwrite old models.
+        """
+        from edsl.results.Dataset import Dataset
+
+        if isinstance(
+            args[0], Dataset
+        ):  # let the user use a Dataset as if it were a ScenarioList
+            args = args[0].to_scenario_list()
+
+        passed_objects = self._turn_args_to_list(
+            args
+        )  # objects can also be passed comma-separated
+
+        current_objects, objects_key = self._get_current_objects_of_this_type(
+            passed_objects[0]
+        )
+
+        if not current_objects:
+            new_objects = passed_objects
+        else:
+            new_objects = self._merge_objects(passed_objects, current_objects)
+
+        setattr(self.jobs, objects_key, new_objects)  # update the job object
+        return self.jobs
+
+    @staticmethod
+    def _turn_args_to_list(args):
+        """Return a list of the first argument if it is a sequence, otherwise returns a list of all the arguments.
+
+        Example:
+
+        >>> JobsComponentConstructor._turn_args_to_list([1,2,3])
+        [1, 2, 3]
+
+        """
+
+        def did_user_pass_a_sequence(args):
+            """Return True if the user passed a sequence, False otherwise.
+
+            Example:
+
+            >>> did_user_pass_a_sequence([1,2,3])
+            True
+
+            >>> did_user_pass_a_sequence(1)
+            False
+            """
+            return len(args) == 1 and isinstance(args[0], Sequence)
+
+        if did_user_pass_a_sequence(args):
+            container_class = JobsComponentConstructor._get_container_class(args[0][0])
+            return container_class(args[0])
+        else:
+            container_class = JobsComponentConstructor._get_container_class(args[0])
+            return container_class(args)
+
+    def _get_current_objects_of_this_type(
+        self, object: Union["Agent", "Scenario", "LanguageModel"]
+    ) -> tuple[list, str]:
+        from edsl.agents.Agent import Agent
+        from edsl.scenarios.Scenario import Scenario
+        from edsl.language_models.LanguageModel import LanguageModel
+
+        """Return the current objects of the same type as the first argument.
+
+        >>> from edsl.jobs import Jobs
+        >>> j = JobsComponentConstructor(Jobs.example())
+        >>> j._get_current_objects_of_this_type(j.agents[0])
+        (AgentList([Agent(traits = {'status': 'Joyful'}), Agent(traits = {'status': 'Sad'})]), 'agents')
+        """
+        class_to_key = {
+            Agent: "agents",
+            Scenario: "scenarios",
+            LanguageModel: "models",
+        }
+        for class_type in class_to_key:
+            if isinstance(object, class_type) or issubclass(
+                object.__class__, class_type
+            ):
+                key = class_to_key[class_type]
+                break
+        else:
+            raise ValueError(
+                f"First argument must be an Agent, Scenario, or LanguageModel, not {object}"
+            )
+        current_objects = getattr(self.jobs, key, None)
+        return current_objects, key
+
+    @staticmethod
+    def _get_empty_container_object(object):
+        from edsl.agents.AgentList import AgentList
+        from edsl.scenarios.ScenarioList import ScenarioList
+
+        return {"Agent": AgentList([]), "Scenario": ScenarioList([])}.get(
+            object.__class__.__name__, []
+        )
+
+    @staticmethod
+    def _merge_objects(passed_objects, current_objects) -> list:
+        """
+        Combine all the existing objects with the new objects.
+
+        For example, if the user passes in 3 agents,
+        and there are 2 existing agents, this will create 6 new agents
+        >>> from edsl.jobs import Jobs
+        >>> JobsComponentConstructor(Jobs(survey = []))._merge_objects([1,2,3], [4,5,6])
+        [5, 6, 7, 6, 7, 8, 7, 8, 9]
+        """
+        new_objects = JobsComponentConstructor._get_empty_container_object(
+            passed_objects[0]
+        )
+        for current_object in current_objects:
+            for new_object in passed_objects:
+                new_objects.append(current_object + new_object)
+        return new_objects
+
+    @staticmethod
+    def _get_container_class(object):
+        from edsl.agents.AgentList import AgentList
+        from edsl.agents.Agent import Agent
+        from edsl.scenarios.Scenario import Scenario
+        from edsl.scenarios.ScenarioList import ScenarioList
+        from edsl.language_models.ModelList import ModelList
+
+        if isinstance(object, Agent):
+            return AgentList
+        elif isinstance(object, Scenario):
+            return ScenarioList
+        elif isinstance(object, ModelList):
+            return ModelList
+        else:
+            return list
+
+
+if __name__ == "__main__":
+    """Run the module's doctests."""
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/jobs/JobsPrompts.py

@@ -11,6 +11,8 @@ if TYPE_CHECKING:
     # from edsl.scenarios.ScenarioList import ScenarioList
     # from edsl.surveys.Survey import Survey
 
+from edsl.jobs.FetchInvigilator import FetchInvigilator
+
 
 class JobsPrompts:
     def __init__(self, jobs: "Jobs"):
@@ -23,7 +25,7 @@ class JobsPrompts:
     @property
     def price_lookup(self):
         if self._price_lookup is None:
-            from edsl import Coop
+            from edsl.coop.coop import Coop
 
             c = Coop()
             self._price_lookup = c.fetch_prices()
@@ -48,7 +50,7 @@ class JobsPrompts:
 
         for interview_index, interview in enumerate(interviews):
             invigilators = [
-                interview._get_invigilator(question)
+                FetchInvigilator(interview)(question)
                 for question in self.survey.questions
             ]
             for _, invigilator in enumerate(invigilators):
@@ -184,7 +186,7 @@ class JobsPrompts:
         data = []
         for interview in interviews:
             invigilators = [
-                interview._get_invigilator(question)
+                FetchInvigilator(interview)(question)
                 for question in self.survey.questions
             ]
             for invigilator in invigilators:

edsl/jobs/JobsRemoteInferenceHandler.py

@@ -1,47 +1,50 @@
-from typing import Optional, Union, Literal
-import requests
-import sys
+from typing import Optional, Union, Literal, TYPE_CHECKING, NewType
+
+
+Seconds = NewType("Seconds", float)
+JobUUID = NewType("JobUUID", str)
+
 from edsl.exceptions.coop import CoopServerResponseError
 
-# from edsl.enums import VisibilityType
-from edsl.results import Results
+if TYPE_CHECKING:
+    from edsl.results.Results import Results
+    from edsl.jobs.Jobs import Jobs
+    from edsl.coop.coop import RemoteInferenceResponse, RemoteInferenceCreationInfo
+    from edsl.jobs.JobsRemoteInferenceLogger import JobLogger
+
+from edsl.coop.coop import RemoteInferenceResponse, RemoteInferenceCreationInfo
+
+from edsl.jobs.jobs_status_enums import JobsStatus
+from edsl.coop.utils import VisibilityType
 
 
 class JobsRemoteInferenceHandler:
-    def __init__(self, jobs, verbose=False, poll_interval=3):
-        """
-        >>> from edsl.jobs import Jobs
-        >>> jh = JobsRemoteInferenceHandler(Jobs.example(), verbose=True)
-        >>> jh.use_remote_inference(True)
-        False
-        >>> jh._poll_remote_inference_job({'uuid':1234}, testing_simulated_response={"status": "failed"}) # doctest: +NORMALIZE_WHITESPACE
-        Job failed.
-        ...
-        >>> jh._poll_remote_inference_job({'uuid':1234}, testing_simulated_response={"status": "completed"}) # doctest: +NORMALIZE_WHITESPACE
-        Job completed and Results stored on Coop: None.
-        Results(...)
-        """
+    def __init__(self, jobs: "Jobs", verbose: bool = False, poll_interval: Seconds = 1):
+        """ """
         self.jobs = jobs
         self.verbose = verbose
         self.poll_interval = poll_interval
 
-        self._remote_job_creation_data = None
-        self._job_uuid = None
+        self._remote_job_creation_data: Union[None, RemoteInferenceCreationInfo] = None
+        self._job_uuid: Union[None, JobUUID] = None  # Will be set when job is created
+        self.logger: Union[None, JobLogger] = None  # Will be initialized when needed
 
     @property
-    def remote_job_creation_data(self):
+    def remote_job_creation_data(self) -> RemoteInferenceCreationInfo:
         return self._remote_job_creation_data
 
     @property
-    def job_uuid(self):
+    def job_uuid(self) -> JobUUID:
         return self._job_uuid
 
     def use_remote_inference(self, disable_remote_inference: bool) -> bool:
+        import requests
+
         if disable_remote_inference:
             return False
         if not disable_remote_inference:
             try:
-                from edsl import Coop
+                from edsl.coop.coop import Coop
 
                 user_edsl_settings = Coop().edsl_settings
                 return user_edsl_settings.get("remote_inference", False)
@@ -56,16 +59,27 @@ class JobsRemoteInferenceHandler:
         self,
         iterations: int = 1,
         remote_inference_description: Optional[str] = None,
-        remote_inference_results_visibility: Optional["VisibilityType"] = "unlisted",
-        verbose=False,
-    ):
-        """ """
+        remote_inference_results_visibility: Optional[VisibilityType] = "unlisted",
+    ) -> None:
         from edsl.config import CONFIG
         from edsl.coop.coop import Coop
-        from rich import print as rich_print
+
+        # Initialize logger
+        from edsl.utilities.is_notebook import is_notebook
+        from edsl.jobs.JobsRemoteInferenceLogger import JupyterJobLogger
+        from edsl.jobs.JobsRemoteInferenceLogger import StdOutJobLogger
+        from edsl.jobs.loggers.HTMLTableJobLogger import HTMLTableJobLogger
+
+        if is_notebook():
+            self.logger = HTMLTableJobLogger(verbose=self.verbose)
+        else:
+            self.logger = StdOutJobLogger(verbose=self.verbose)
 
         coop = Coop()
-        print("Remote inference activated. Sending job to server...")
+        self.logger.update(
+            "Remote inference activated. Sending job to server...",
+            status=JobsStatus.QUEUED,
+        )
         remote_job_creation_data = coop.remote_inference_create(
             self.jobs,
             description=remote_inference_description,
@@ -73,51 +87,65 @@ class JobsRemoteInferenceHandler:
             iterations=iterations,
             initial_results_visibility=remote_inference_results_visibility,
         )
+        self.logger.update(
+            "Your survey is running at the Expected Parrot server...",
+            status=JobsStatus.RUNNING,
+        )
+
         job_uuid = remote_job_creation_data.get("uuid")
-        print(f"Job sent to server. (Job uuid={job_uuid}).")
+        self.logger.update(
+            message=f"Job sent to server. (Job uuid={job_uuid}).",
+            status=JobsStatus.RUNNING,
+        )
+        self.logger.add_info("job_uuid", job_uuid)
 
         expected_parrot_url = CONFIG.get("EXPECTED_PARROT_URL")
-        progress_bar_url = f"{expected_parrot_url}/home/remote-job-progress/{job_uuid}"
+        remote_inference_url = f"{expected_parrot_url}/home/remote-inference"
 
-        rich_print(
-            f"View job progress here: [#38bdf8][link={progress_bar_url}]{progress_bar_url}[/link][/#38bdf8]"
+        self.logger.update(
+            f"Job details are available at your Coop account {remote_inference_url}{remote_inference_url}",
+            status=JobsStatus.RUNNING,
+        )
+        progress_bar_url = f"{expected_parrot_url}/home/remote-job-progress/{job_uuid}"
+        self.logger.add_info("progress_bar_url", progress_bar_url)
+        self.logger.update(
+            f"View job progress here: {progress_bar_url}", status=JobsStatus.RUNNING
         )
 
         self._remote_job_creation_data = remote_job_creation_data
         self._job_uuid = job_uuid
-        # return remote_job_creation_data
 
     @staticmethod
-    def check_status(job_uuid):
+    def check_status(
+        job_uuid: JobUUID,
+    ) -> RemoteInferenceResponse:
         from edsl.coop.coop import Coop
 
         coop = Coop()
         return coop.remote_inference_get(job_uuid)
 
-    def poll_remote_inference_job(self):
+    def poll_remote_inference_job(self) -> Union[None, "Results"]:
         return self._poll_remote_inference_job(
             self.remote_job_creation_data, verbose=self.verbose
         )
 
     def _poll_remote_inference_job(
         self,
-        remote_job_creation_data: dict,
-        verbose=False,
-        poll_interval: Optional[float] = None,
-        testing_simulated_response: Optional[dict] = None,
-    ) -> Union[Results, None]:
+        remote_job_creation_data: RemoteInferenceCreationInfo,
+        verbose: bool = False,
+        poll_interval: Optional[Seconds] = None,
+        testing_simulated_response=None,
+    ) -> Union[None, "Results"]:
         import time
         from datetime import datetime
         from edsl.config import CONFIG
-        from edsl.coop.coop import Coop
+        from edsl.results.Results import Results
 
         if poll_interval is None:
             poll_interval = self.poll_interval
 
-        expected_parrot_url = CONFIG.get("EXPECTED_PARROT_URL")
-
         job_uuid = remote_job_creation_data.get("uuid")
-        coop = Coop()
+        expected_parrot_url = CONFIG.get("EXPECTED_PARROT_URL")
 
         if testing_simulated_response is not None:
             remote_job_data_fetcher = lambda job_uuid: testing_simulated_response
@@ -125,66 +153,88 @@ class JobsRemoteInferenceHandler:
                 lambda results_uuid, expected_object_type: Results.example()
             )
         else:
+            from edsl.coop.coop import Coop
+
+            coop = Coop()
             remote_job_data_fetcher = coop.remote_inference_get
             object_fetcher = coop.get
 
         job_in_queue = True
         while job_in_queue:
-            remote_job_data = remote_job_data_fetcher(job_uuid)
+            remote_job_data: RemoteInferenceResponse = remote_job_data_fetcher(job_uuid)
             status = remote_job_data.get("status")
+
             if status == "cancelled":
-                print("\r" + " " * 80 + "\r", end="")
-                print("Job cancelled by the user.")
-                print(
-                    f"See {expected_parrot_url}/home/remote-inference for more details."
+                self.logger.update(
+                    messaged="Job cancelled by the user.", status=JobsStatus.CANCELLED
+                )
+                self.logger.update(
+                    f"See {expected_parrot_url}/home/remote-inference for more details.",
+                    status=JobsStatus.CANCELLED,
                 )
                 return None
+
             elif status == "failed":
-                print("\r" + " " * 80 + "\r", end="")
-                # write to stderr
                 latest_error_report_url = remote_job_data.get("latest_error_report_url")
                 if latest_error_report_url:
-                    print("Job failed.")
-                    print(
-                        f"Your job generated exceptions. Details on these exceptions can be found in the following report: {latest_error_report_url}"
+                    self.logger.update("Job failed.", status=JobsStatus.FAILED)
+                    self.logger.update(
+                        f"Error report: {latest_error_report_url}", "failed"
                     )
-                    print(
-                        f"Need support? Post a message at the Expected Parrot Discord channel (https://discord.com/invite/mxAYkjfy9m) or send an email to info@expectedparrot.com."
+                    self.logger.add_info("error_report_url", latest_error_report_url)
+                    self.logger.update(
+                        "Need support? Visit Discord: https://discord.com/invite/mxAYkjfy9m",
+                        status=JobsStatus.FAILED,
                     )
                 else:
-                    print("Job failed.")
-                    print(
-                        f"See {expected_parrot_url}/home/remote-inference for more details."
+                    self.logger.update("Job failed.", "failed")
+                    self.logger.update(
+                        f"See {expected_parrot_url}/home/remote-inference for details.",
+                        status=JobsStatus.FAILED,
                     )
-                return None
+
+                results_uuid = remote_job_data.get("results_uuid")
+                if results_uuid:
+                    self.logger.add_info("results_uuid", results_uuid)
+                    results = object_fetcher(
+                        results_uuid, expected_object_type="results"
+                    )
+                    results.job_uuid = job_uuid
+                    results.results_uuid = results_uuid
+                    return results
+                else:
+                    return None
+
             elif status == "completed":
                 results_uuid = remote_job_data.get("results_uuid")
+                self.logger.add_info("results_uuid", results_uuid)
                 results_url = remote_job_data.get("results_url")
+                self.logger.add_info("results_url", results_url)
                 results = object_fetcher(results_uuid, expected_object_type="results")
-                print("\r" + " " * 80 + "\r", end="")
-                print(f"Job completed and Results stored on Coop: {results_url}.")
+                self.logger.update(
+                    f"Job completed and Results stored on Coop: {results_url}",
+                    status=JobsStatus.COMPLETED,
+                )
+                results.job_uuid = job_uuid
+                results.results_uuid = results_uuid
                 return results
+
             else:
-                duration = poll_interval
                 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)]} Job status: {status} - last update: {time_checked}",
-                        end="",
-                        flush=True,
-                    )
-                    time.sleep(0.1)
-                    i += 1
+                self.logger.update(
+                    f"Job status: {status} - last update: {time_checked}",
+                    status=JobsStatus.RUNNING,
+                )
+                time.sleep(poll_interval)
 
     def use_remote_inference(self, disable_remote_inference: bool) -> bool:
+        import requests
+
         if disable_remote_inference:
             return False
         if not disable_remote_inference:
             try:
-                from edsl import Coop
+                from edsl.coop.coop import Coop
 
                 user_edsl_settings = Coop().edsl_settings
                 return user_edsl_settings.get("remote_inference", False)
@@ -199,10 +249,8 @@ class JobsRemoteInferenceHandler:
         self,
         iterations: int = 1,
         remote_inference_description: Optional[str] = None,
-        remote_inference_results_visibility: Optional[
-            Literal["private", "public", "unlisted"]
-        ] = "unlisted",
-    ) -> Union[Results, None]:
+        remote_inference_results_visibility: Optional[VisibilityType] = "unlisted",
+    ) -> Union["Results", None]:
         """
         Creates and polls a remote inference job asynchronously.
         Reuses existing synchronous methods but runs them in an async context.