edsl 0.1.38.dev4__py3-none-any.whl → 0.1.39__py3-none-any.whl

edsl/jobs/Jobs.py

@@ -1,36 +1,106 @@
 # """The Jobs class is a collection of agents, scenarios and models and one survey."""
 from __future__ import annotations
-import warnings
-import requests
-from itertools import product
-from typing import Literal, Optional, Union, Sequence, Generator, TYPE_CHECKING
+import asyncio
+from inspect import signature
+from typing import (
+    Literal,
+    Optional,
+    Union,
+    Sequence,
+    Generator,
+    TYPE_CHECKING,
+    Callable,
+    Tuple,
+)
 
 from edsl.Base import Base
 
-from edsl.exceptions import MissingAPIKeyError
 from edsl.jobs.buckets.BucketCollection import BucketCollection
+from edsl.jobs.JobsPrompts import JobsPrompts
 from edsl.jobs.interviews.Interview import Interview
+from edsl.utilities.remove_edsl_version import remove_edsl_version
 from edsl.jobs.runners.JobsRunnerAsyncio import JobsRunnerAsyncio
-from edsl.utilities.decorators import remove_edsl_version
-
 from edsl.data.RemoteCacheSync import RemoteCacheSync
 from edsl.exceptions.coop import CoopServerResponseError
 
+from edsl.jobs.JobsChecks import JobsChecks
+from edsl.jobs.data_structures import RunEnvironment, RunParameters, RunConfig
+
 if TYPE_CHECKING:
     from edsl.agents.Agent import Agent
     from edsl.agents.AgentList import AgentList
     from edsl.language_models.LanguageModel import LanguageModel
     from edsl.scenarios.Scenario import Scenario
+    from edsl.scenarios.ScenarioList import ScenarioList
     from edsl.surveys.Survey import Survey
     from edsl.results.Results import Results
     from edsl.results.Dataset import Dataset
+    from edsl.language_models.ModelList import ModelList
+    from edsl.data.Cache import Cache
+    from edsl.language_models.key_management.KeyLookup import KeyLookup
+
+VisibilityType = Literal["private", "public", "unlisted"]
+
+from dataclasses import dataclass
+from typing import Optional, Union, TypeVar, Callable, cast
+from functools import wraps
+
+try:
+    from typing import ParamSpec
+except ImportError:
+    from typing_extensions import ParamSpec
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+from edsl.jobs.check_survey_scenario_compatibility import (
+    CheckSurveyScenarioCompatibility,
+)
+
+
+def with_config(f: Callable[P, T]) -> Callable[P, T]:
+    "This decorator make it so that the run function parameters match the RunConfig dataclass."
+    parameter_fields = {
+        name: field.default
+        for name, field in RunParameters.__dataclass_fields__.items()
+    }
+    environment_fields = {
+        name: field.default
+        for name, field in RunEnvironment.__dataclass_fields__.items()
+    }
+    combined = {**parameter_fields, **environment_fields}
+
+    @wraps(f)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        environment = RunEnvironment(
+            **{k: v for k, v in kwargs.items() if k in environment_fields}
+        )
+        parameters = RunParameters(
+            **{k: v for k, v in kwargs.items() if k in parameter_fields}
+        )
+        config = RunConfig(environment=environment, parameters=parameters)
+        return f(*args, config=config)
+
+    # Update the wrapper's signature to include all RunConfig parameters
+    # old_sig = signature(f)
+    # wrapper.__signature__ = old_sig.replace(
+    #     parameters=list(old_sig.parameters.values())[:-1]
+    #     + [
+    #         old_sig.parameters["config"].replace(
+    #             default=parameter_fields[name], name=name
+    #         )
+    #         for name in combined
+    #     ]
+    # )
+
+    return cast(Callable[P, T], wrapper)
 
 
 class Jobs(Base):
     """
-    A collection of agents, scenarios and models and one survey.
-    The actual running of a job is done by a `JobsRunner`, which is a subclass of `JobsRunner`.
-    The `JobsRunner` is chosen by the user, and is stored in the `jobs_runner_name` attribute.
+    A collection of agents, scenarios and models and one survey that creates 'interviews'
     """
 
     __documentation__ = "https://docs.expectedparrot.com/en/latest/jobs.html"
@@ -38,9 +108,9 @@ class Jobs(Base):
     def __init__(
         self,
         survey: "Survey",
-        agents: Optional[list["Agent"]] = None,
-        models: Optional[list["LanguageModel"]] = None,
-        scenarios: Optional[list["Scenario"]] = None,
+        agents: Optional[Union[list[Agent], AgentList]] = None,
+        models: Optional[Union[ModelList, list[LanguageModel]]] = None,
+        scenarios: Optional[Union[ScenarioList, list[Scenario]]] = None,
     ):
         """Initialize a Jobs instance.
 
@@ -49,14 +119,62 @@ class Jobs(Base):
         :param models: a list of models
         :param scenarios: a list of scenarios
         """
+        self.run_config = RunConfig(
+            environment=RunEnvironment(), parameters=RunParameters()
+        )
+
         self.survey = survey
-        self.agents: "AgentList" = agents
-        self.scenarios: "ScenarioList" = scenarios
-        self.models = models
+        self.agents: AgentList = agents
+        self.scenarios: ScenarioList = scenarios
+        self.models: ModelList = models
+
+    def add_running_env(self, running_env: RunEnvironment):
+        self.run_config.add_environment(running_env)
+        return self
+
+    def using_cache(self, cache: "Cache") -> Jobs:
+        """
+        Add a Cache to the job.
+
+        :param cache: the cache to add
+        """
+        self.run_config.add_cache(cache)
+        return self
+
+    def using_bucket_collection(self, bucket_collection: BucketCollection) -> Jobs:
+        """
+        Add a BucketCollection to the job.
+
+        :param bucket_collection: the bucket collection to add
+        """
+        self.run_config.add_bucket_collection(bucket_collection)
+        return self
 
-        self.__bucket_collection = None
+    def using_key_lookup(self, key_lookup: KeyLookup) -> Jobs:
+        """
+        Add a KeyLookup to the job.
+
+        :param key_lookup: the key lookup to add
+        """
+        self.run_config.add_key_lookup(key_lookup)
+        return self
 
-    # these setters and getters are used to ensure that the agents, models, and scenarios are stored as AgentList, ModelList, and ScenarioList objects
+    def using(self, obj: Union[Cache, BucketCollection, KeyLookup]) -> Jobs:
+        """
+        Add a Cache, BucketCollection, or KeyLookup to the job.
+
+        :param obj: the object to add
+        """
+        from edsl.data.Cache import Cache
+        from edsl.language_models.key_management.KeyLookup import KeyLookup
+
+        if isinstance(obj, Cache):
+            self.using_cache(obj)
+        elif isinstance(obj, BucketCollection):
+            self.using_bucket_collection(obj)
+        elif isinstance(obj, KeyLookup):
+            self.using_key_lookup(obj)
+        return self
 
     @property
     def models(self):
@@ -64,7 +182,7 @@ class Jobs(Base):
 
     @models.setter
     def models(self, value):
-        from edsl import ModelList
+        from edsl.language_models.ModelList import ModelList
 
         if value:
             if not isinstance(value, ModelList):
@@ -74,13 +192,19 @@ class Jobs(Base):
         else:
             self._models = ModelList([])
 
+        # update the bucket collection if it exists
+        if self.run_config.environment.bucket_collection is None:
+            self.run_config.environment.bucket_collection = (
+                self.create_bucket_collection()
+            )
+
     @property
     def agents(self):
         return self._agents
 
     @agents.setter
     def agents(self, value):
-        from edsl import AgentList
+        from edsl.agents.AgentList import AgentList
 
         if value:
             if not isinstance(value, AgentList):
@@ -96,7 +220,7 @@ class Jobs(Base):
 
     @scenarios.setter
     def scenarios(self, value):
-        from edsl import ScenarioList
+        from edsl.scenarios.ScenarioList import ScenarioList
         from edsl.results.Dataset import Dataset
 
         if value:
@@ -115,28 +239,32 @@ class Jobs(Base):
     def by(
         self,
         *args: Union[
-            "Agent",
-            "Scenario",
-            "LanguageModel",
+            Agent,
+            Scenario,
+            LanguageModel,
             Sequence[Union["Agent", "Scenario", "LanguageModel"]],
         ],
     ) -> Jobs:
         """
-        Add Agents, Scenarios and LanguageModels to a job. 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.
+        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 import Survey
-        >>> from edsl import QuestionFreeText
+        >>> from edsl.surveys.Survey import Survey
+        >>> from edsl.questions.QuestionFreeText import QuestionFreeText
         >>> q = QuestionFreeText(question_name="name", question_text="What is your name?")
         >>> 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"})
+        >>> from edsl.agents.Agent import Agent; a = Agent(traits = {"status": "Sad"})
         >>> j.by(a).agents
         AgentList([Agent(traits = {'status': 'Sad'})])
 
-        :param args: objects or a sequence (list, tuple, ...) of objects of the same type
 
         Notes:
         - all objects must implement the 'get_value', 'set_value', and `__add__` methods
@@ -144,28 +272,9 @@ class Jobs(Base):
         - 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 user 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
+        from edsl.jobs.JobsComponentConstructor import JobsComponentConstructor
 
-        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, objects_key, new_objects)  # update the job
-        return self
+        return JobsComponentConstructor(self).by(*args)
 
     def prompts(self) -> "Dataset":
         """Return a Dataset of prompts that will be used.
@@ -175,12 +284,9 @@ class Jobs(Base):
         >>> Jobs.example().prompts()
         Dataset(...)
         """
-        from edsl.jobs.JobsPrompts import JobsPrompts
-
-        j = JobsPrompts(self)
-        return j.prompts()
+        return JobsPrompts(self).prompts()
 
-    def show_prompts(self, all=False) -> None:
+    def show_prompts(self, all: bool = False) -> None:
         """Print the prompts."""
         if all:
             return self.prompts().to_scenario_list().table()
@@ -200,9 +306,12 @@ class Jobs(Base):
         """
         Estimate the cost of running the prompts.
         :param iterations: the number of iterations to run
+        :param system_prompt: the system prompt
+        :param user_prompt: the user prompt
+        :param price_lookup: the price lookup
+        :param inference_service: the inference service
+        :param model: the model name
         """
-        from edsl.jobs.JobsPrompts import JobsPrompts
-
         return JobsPrompts.estimate_prompt_cost(
             system_prompt, user_prompt, price_lookup, inference_service, model
         )
@@ -213,18 +322,14 @@ class Jobs(Base):
 
         :param iterations: the number of iterations to run
         """
-        from edsl.jobs.JobsPrompts import JobsPrompts
-
-        j = JobsPrompts(self)
-        return j.estimate_job_cost(iterations)
+        return JobsPrompts(self).estimate_job_cost(iterations)
 
     def estimate_job_cost_from_external_prices(
         self, price_lookup: dict, iterations: int = 1
     ) -> dict:
-        from edsl.jobs.JobsPrompts import JobsPrompts
-
-        j = JobsPrompts(self)
-        return j.estimate_job_cost_from_external_prices(price_lookup, iterations)
+        return JobsPrompts(self).estimate_job_cost_from_external_prices(
+            price_lookup, iterations
+        )
 
     @staticmethod
     def compute_job_cost(job_results: Results) -> float:
@@ -233,111 +338,30 @@ class Jobs(Base):
         """
         return job_results.compute_job_cost()
 
-    @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
-
-    @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:
-
-        >>> Jobs._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 = Jobs._get_container_class(args[0][0])
-            return container_class(args[0])
-        else:
-            container_class = Jobs._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]:
+    def replace_missing_objects(self) -> None:
         from edsl.agents.Agent import Agent
+        from edsl.language_models.model import Model
         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.
+        self.agents = self.agents or [Agent()]
+        self.models = self.models or [Model()]
+        self.scenarios = self.scenarios or [Scenario()]
 
-        >>> from edsl.jobs import Jobs
-        >>> j = Jobs.example()
-        >>> j._get_current_objects_of_this_type(j.agents[0])
-        (AgentList([Agent(traits = {'status': 'Joyful'}), Agent(traits = {'status': 'Sad'})]), 'agents')
+    def generate_interviews(self) -> Generator[Interview, None, None]:
         """
-        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, 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
+        Generate interviews.
 
-        return {"Agent": AgentList([]), "Scenario": ScenarioList([])}.get(
-            object.__class__.__name__, []
-        )
+        Note that this sets the agents, model and scenarios if they have not been set. This is a side effect of the method.
+        This is useful because a user can create a job without setting the agents, models, or scenarios, and the job will still run,
+        with us filling in defaults.
 
-    @staticmethod
-    def _merge_objects(passed_objects, current_objects) -> list:
         """
-        Combine all the existing objects with the new objects.
+        from edsl.jobs.InterviewsConstructor import InterviewsConstructor
 
-        For example, if the user passes in 3 agents,
-        and there are 2 existing agents, this will create 6 new agents
-
-        >>> Jobs(survey = [])._merge_objects([1,2,3], [4,5,6])
-        [5, 6, 7, 6, 7, 8, 7, 8, 9]
-        """
-        new_objects = Jobs._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
+        self.replace_missing_objects()
+        yield from InterviewsConstructor(
+            self, cache=self.run_config.environment.cache
+        ).create_interviews()
 
     def interviews(self) -> list[Interview]:
         """
@@ -353,13 +377,10 @@ class Jobs(Base):
         >>> j.interviews()[0]
         Interview(agent = Agent(traits = {'status': 'Joyful'}), survey = Survey(...), scenario = Scenario({'period': 'morning'}), model = Model(...))
         """
-        if hasattr(self, "_interviews"):
-            return self._interviews
-        else:
-            return list(self._create_interviews())
+        return list(self.generate_interviews())
 
     @classmethod
-    def from_interviews(cls, interview_list):
+    def from_interviews(cls, interview_list) -> "Jobs":
         """Return a Jobs instance from a list of interviews.
 
         This is useful when you have, say, a list of failed interviews and you want to create
@@ -373,34 +394,6 @@ class Jobs(Base):
         jobs._interviews = interview_list
         return jobs
 
-    def _create_interviews(self) -> Generator[Interview, None, None]:
-        """
-        Generate interviews.
-
-        Note that this sets the agents, model and scenarios if they have not been set. This is a side effect of the method.
-        This is useful because a user can create a job without setting the agents, models, or scenarios, and the job will still run,
-        with us filling in defaults.
-
-
-        """
-        # if no agents, models, or scenarios are set, set them to defaults
-        from edsl.agents.Agent import Agent
-        from edsl.language_models.registry import Model
-        from edsl.scenarios.Scenario import Scenario
-
-        self.agents = self.agents or [Agent()]
-        self.models = self.models or [Model()]
-        self.scenarios = self.scenarios or [Scenario()]
-        for agent, scenario, model in product(self.agents, self.scenarios, self.models):
-            yield Interview(
-                survey=self.survey,
-                agent=agent,
-                scenario=scenario,
-                model=model,
-                skip_retry=self.skip_retry,
-                raise_validation_errors=self.raise_validation_errors,
-            )
-
     def create_bucket_collection(self) -> BucketCollection:
         """
         Create a collection of buckets for each model.
@@ -414,17 +407,7 @@ class Jobs(Base):
         >>> bc
         BucketCollection(...)
         """
-        bucket_collection = BucketCollection()
-        for model in self.models:
-            bucket_collection.add_model(model)
-        return bucket_collection
-
-    @property
-    def bucket_collection(self) -> BucketCollection:
-        """Return the bucket collection. If it does not exist, create it."""
-        if self.__bucket_collection is None:
-            self.__bucket_collection = self.create_bucket_collection()
-        return self.__bucket_collection
+        return BucketCollection.from_models(self.models)
 
     def html(self):
         """Return the HTML representations for each scenario"""
@@ -451,89 +434,27 @@ class Jobs(Base):
 
     def _output(self, message) -> None:
         """Check if a Job is verbose. If so, print the message."""
-        if hasattr(self, "verbose") and self.verbose:
+        if self.run_config.parameters.verbose:
             print(message)
+        # if hasattr(self, "verbose") and self.verbose:
+        #    print(message)
 
-    def _check_parameters(self, strict=False, warn=False) -> None:
-        """Check if the parameters in the survey and scenarios are consistent.
-
-        >>> from edsl import QuestionFreeText
-        >>> from edsl import Survey
-        >>> from edsl import Scenario
-        >>> q = QuestionFreeText(question_text = "{{poo}}", question_name = "ugly_question")
-        >>> j = Jobs(survey = Survey(questions=[q]))
-        >>> with warnings.catch_warnings(record=True) as w:
-        ...     j._check_parameters(warn = True)
-        ...     assert len(w) == 1
-        ...     assert issubclass(w[-1].category, UserWarning)
-        ...     assert "The following parameters are in the survey but not in the scenarios" in str(w[-1].message)
-
-        >>> q = QuestionFreeText(question_text = "{{poo}}", question_name = "ugly_question")
-        >>> s = Scenario({'plop': "A", 'poo': "B"})
-        >>> j = Jobs(survey = Survey(questions=[q])).by(s)
-        >>> j._check_parameters(strict = True)
-        Traceback (most recent call last):
-        ...
-        ValueError: The following parameters are in the scenarios but not in the survey: {'plop'}
-
-        >>> q = QuestionFreeText(question_text = "Hello", question_name = "ugly_question")
-        >>> s = Scenario({'ugly_question': "B"})
-        >>> j = Jobs(survey = Survey(questions=[q])).by(s)
-        >>> j._check_parameters()
-        Traceback (most recent call last):
-        ...
-        ValueError: The following names are in both the survey question_names and the scenario keys: {'ugly_question'}. This will create issues.
-        """
-        survey_parameters: set = self.survey.parameters
-        scenario_parameters: set = self.scenarios.parameters
-
-        msg0, msg1, msg2 = None, None, None
-
-        # look for key issues
-        if intersection := set(self.scenarios.parameters) & set(
-            self.survey.question_names
-        ):
-            msg0 = f"The following names are in both the survey question_names and the scenario keys: {intersection}. This will create issues."
-
-            raise ValueError(msg0)
-
-        if in_survey_but_not_in_scenarios := survey_parameters - scenario_parameters:
-            msg1 = f"The following parameters are in the survey but not in the scenarios: {in_survey_but_not_in_scenarios}"
-        if in_scenarios_but_not_in_survey := scenario_parameters - survey_parameters:
-            msg2 = f"The following parameters are in the scenarios but not in the survey: {in_scenarios_but_not_in_survey}"
-
-        if msg1 or msg2:
-            message = "\n".join(filter(None, [msg1, msg2]))
-            if strict:
-                raise ValueError(message)
-            else:
-                if warn:
-                    warnings.warn(message)
-
-        if self.scenarios.has_jinja_braces:
-            warnings.warn(
-                "The scenarios have Jinja braces ({{ and }}). Converting to '<<' and '>>'. If you want a different conversion, use the convert_jinja_braces method first to modify the scenario."
-            )
-            self.scenarios = self.scenarios.convert_jinja_braces()
-
-    @property
-    def skip_retry(self):
-        if not hasattr(self, "_skip_retry"):
-            return False
-        return self._skip_retry
+    def all_question_parameters(self) -> set:
+        """Return all the fields in the questions in the survey.
+        >>> from edsl.jobs import Jobs
+        >>> Jobs.example().all_question_parameters()
+        {'period'}
+        """
+        return set.union(*[question.parameters for question in self.survey.questions])
 
-    @property
-    def raise_validation_errors(self):
-        if not hasattr(self, "_raise_validation_errors"):
-            return False
-        return self._raise_validation_errors
+    def use_remote_cache(self) -> bool:
+        import requests
 
-    def use_remote_cache(self, disable_remote_cache: bool) -> bool:
-        if disable_remote_cache:
+        if self.run_config.parameters.disable_remote_cache:
             return False
-        if not disable_remote_cache:
+        if not self.run_config.parameters.disable_remote_cache:
             try:
-                from edsl import Coop
+                from edsl.coop.coop import Coop
 
                 user_edsl_settings = Coop().edsl_settings
                 return user_edsl_settings.get("remote_caching", False)
@@ -544,152 +465,173 @@ class Jobs(Base):
 
         return False
 
-    def run(
+    def _remote_results(
         self,
-        n: int = 1,
-        progress_bar: bool = False,
-        stop_on_exception: bool = False,
-        cache: Union[Cache, bool] = None,
-        check_api_keys: bool = False,
-        sidecar_model: Optional[LanguageModel] = None,
-        verbose: bool = True,
-        print_exceptions=True,
-        remote_cache_description: Optional[str] = None,
-        remote_inference_description: Optional[str] = None,
-        remote_inference_results_visibility: Optional[
-            Literal["private", "public", "unlisted"]
-        ] = "unlisted",
-        skip_retry: bool = False,
-        raise_validation_errors: bool = False,
-        disable_remote_cache: bool = False,
-        disable_remote_inference: bool = False,
-    ) -> Results:
-        """
-        Runs the Job: conducts Interviews and returns their results.
-
-        :param n: How many times to run each interview
-        :param progress_bar: Whether to show a progress bar
-        :param stop_on_exception: Stops the job if an exception is raised
-        :param cache: A Cache object to store results
-        :param check_api_keys: Raises an error if API keys are invalid
-        :param verbose: Prints extra messages
-        :param remote_cache_description: Specifies a description for this group of entries in the remote cache
-        :param remote_inference_description: Specifies a description for the remote inference job
-        :param remote_inference_results_visibility: The initial visibility of the Results object on Coop. This will only be used for remote jobs!
-        :param disable_remote_cache: If True, the job will not use remote cache. This only works for local jobs!
-        :param disable_remote_inference: If True, the job will not use remote inference
-        """
-        from edsl.coop.coop import Coop
-
-        self._check_parameters()
-        self._skip_retry = skip_retry
-        self._raise_validation_errors = raise_validation_errors
+    ) -> Union["Results", None]:
+        from edsl.jobs.JobsRemoteInferenceHandler import JobsRemoteInferenceHandler
 
-        self.verbose = verbose
+        jh = JobsRemoteInferenceHandler(
+            self, verbose=self.run_config.parameters.verbose
+        )
+        if jh.use_remote_inference(self.run_config.parameters.disable_remote_inference):
+            job_info = jh.create_remote_inference_job(
+                iterations=self.run_config.parameters.n,
+                remote_inference_description=self.run_config.parameters.remote_inference_description,
+                remote_inference_results_visibility=self.run_config.parameters.remote_inference_results_visibility,
+            )
+            results = jh.poll_remote_inference_job(job_info)
+            return results
+        else:
+            return None
 
-        from edsl.jobs.JobsChecks import JobsChecks
+    def _prepare_to_run(self) -> None:
+        "This makes sure that the job is ready to run and that keys are in place for a remote job."
+        CheckSurveyScenarioCompatibility(self.survey, self.scenarios).check()
 
+    def _check_if_remote_keys_ok(self):
         jc = JobsChecks(self)
-
-        # check if the user has all the keys they need
         if jc.needs_key_process():
             jc.key_process()
 
-        from edsl.jobs.JobsRemoteInferenceHandler import JobsRemoteInferenceHandler
-
-        jh = JobsRemoteInferenceHandler(self, verbose=verbose)
-        if jh.use_remote_inference(disable_remote_inference):
-            jh.create_remote_inference_job(
-                iterations=n,
-                remote_inference_description=remote_inference_description,
-                remote_inference_results_visibility=remote_inference_results_visibility,
-            )
-            results = jh.poll_remote_inference_job()
-            return results
-
-        if check_api_keys:
+    def _check_if_local_keys_ok(self):
+        jc = JobsChecks(self)
+        if self.run_config.parameters.check_api_keys:
             jc.check_api_keys()
 
-        # handle cache
-        if cache is None or cache is True:
-            from edsl.data.CacheHandler import CacheHandler
+    async def _execute_with_remote_cache(self, run_job_async: bool) -> Results:
 
-            cache = CacheHandler().get_cache()
-        if cache is False:
-            from edsl.data.Cache import Cache
+        use_remote_cache = self.use_remote_cache()
+
+        from edsl.coop.coop import Coop
+        from edsl.jobs.runners.JobsRunnerAsyncio import JobsRunnerAsyncio
+        from edsl.data.Cache import Cache
 
-            cache = Cache()
+        assert isinstance(self.run_config.environment.cache, Cache)
 
-        remote_cache = self.use_remote_cache(disable_remote_cache)
         with RemoteCacheSync(
             coop=Coop(),
-            cache=cache,
+            cache=self.run_config.environment.cache,
             output_func=self._output,
-            remote_cache=remote_cache,
-            remote_cache_description=remote_cache_description,
-        ) as r:
-            results = self._run_local(
-                n=n,
-                progress_bar=progress_bar,
-                cache=cache,
-                stop_on_exception=stop_on_exception,
-                sidecar_model=sidecar_model,
-                print_exceptions=print_exceptions,
-                raise_validation_errors=raise_validation_errors,
-            )
-
-        # results.cache = cache.new_entries_cache()
+            remote_cache=use_remote_cache,
+            remote_cache_description=self.run_config.parameters.remote_cache_description,
+        ):
+            runner = JobsRunnerAsyncio(self, environment=self.run_config.environment)
+            if run_job_async:
+                results = await runner.run_async(self.run_config.parameters)
+            else:
+                results = runner.run(self.run_config.parameters)
         return results
 
-    async def run_async(
-        self,
-        cache=None,
-        n=1,
-        disable_remote_inference: bool = False,
-        remote_inference_description: Optional[str] = None,
-        remote_inference_results_visibility: Optional[
-            Literal["private", "public", "unlisted"]
-        ] = "unlisted",
-        **kwargs,
-    ):
-        """Run the job asynchronously, either locally or remotely.
+    def _setup_and_check(self) -> Tuple[RunConfig, Optional[Results]]:
 
-        :param cache: Cache object or boolean
-        :param n: Number of iterations
-        :param disable_remote_inference: If True, forces local execution
-        :param remote_inference_description: Description for remote jobs
-        :param remote_inference_results_visibility: Visibility setting for remote results
-        :param kwargs: Additional arguments passed to local execution
-        :return: Results object
-        """
-        # Check if we should use remote inference
-        from edsl.jobs.JobsRemoteInferenceHandler import JobsRemoteInferenceHandler
+        self._prepare_to_run()
+        self._check_if_remote_keys_ok()
+
+        # first try to run the job remotely
+        if results := self._remote_results():
+            return results
 
-        jh = JobsRemoteInferenceHandler(self, verbose=False)
-        if jh.use_remote_inference(disable_remote_inference):
-            results = await jh.create_and_poll_remote_job(
-                iterations=n,
-                remote_inference_description=remote_inference_description,
-                remote_inference_results_visibility=remote_inference_results_visibility,
+        self._check_if_local_keys_ok()
+        return None
+
+    @property
+    def num_interviews(self):
+        if self.run_config.parameters.n is None:
+            return len(self)
+        else:
+            len(self) * self.run_config.parameters.n
+
+    def _run(self, config: RunConfig):
+        "Shared code for run and run_async"
+        if config.environment.cache is not None:
+            self.run_config.environment.cache = config.environment.cache
+
+        if config.environment.bucket_collection is not None:
+            self.run_config.environment.bucket_collection = (
+                config.environment.bucket_collection
             )
+
+        if config.environment.key_lookup is not None:
+            self.run_config.environment.key_lookup = config.environment.key_lookup
+
+        # replace the parameters with the ones from the config
+        self.run_config.parameters = config.parameters
+
+        self.replace_missing_objects()
+
+        # try to run remotely first
+        self._prepare_to_run()
+        self._check_if_remote_keys_ok()
+
+        if (
+            self.run_config.environment.cache is None
+            or self.run_config.environment.cache is True
+        ):
+            from edsl.data.CacheHandler import CacheHandler
+
+            self.run_config.environment.cache = CacheHandler().get_cache()
+
+        if self.run_config.environment.cache is False:
+            from edsl.data.Cache import Cache
+
+            self.run_config.environment.cache = Cache(immediate_write=False)
+
+        # first try to run the job remotely
+        if results := self._remote_results():
             return results
 
-        # If not using remote inference, run locally with async
-        return await JobsRunnerAsyncio(self).run_async(cache=cache, n=n, **kwargs)
+        self._check_if_local_keys_ok()
 
-    def _run_local(self, *args, **kwargs):
-        """Run the job locally."""
+        if config.environment.bucket_collection is None:
+            self.run_config.environment.bucket_collection = (
+                self.create_bucket_collection()
+            )
 
-        results = JobsRunnerAsyncio(self).run(*args, **kwargs)
-        return results
+    @with_config
+    def run(self, *, config: RunConfig) -> "Results":
+        """
+        Runs the Job: conducts Interviews and returns their results.
 
-    def all_question_parameters(self):
-        """Return all the fields in the questions in the survey.
-        >>> from edsl.jobs import Jobs
-        >>> Jobs.example().all_question_parameters()
-        {'period'}
+        :param n: How many times to run each interview
+        :param progress_bar: Whether to show a progress bar
+        :param stop_on_exception: Stops the job if an exception is raised
+        :param check_api_keys: Raises an error if API keys are invalid
+        :param verbose: Prints extra messages
+        :param remote_cache_description: Specifies a description for this group of entries in the remote cache
+        :param remote_inference_description: Specifies a description for the remote inference job
+        :param remote_inference_results_visibility: The initial visibility of the Results object on Coop. This will only be used for remote jobs!
+        :param disable_remote_cache: If True, the job will not use remote cache. This only works for local jobs!
+        :param disable_remote_inference: If True, the job will not use remote inference
+        :param cache: A Cache object to store results
+        :param bucket_collection: A BucketCollection object to track API calls
+        :param key_lookup: A KeyLookup object to manage API keys
         """
-        return set.union(*[question.parameters for question in self.survey.questions])
+        self._run(config)
+
+        return asyncio.run(self._execute_with_remote_cache(run_job_async=False))
+
+    @with_config
+    async def run_async(self, *, config: RunConfig) -> "Results":
+        """
+        Runs the Job: conducts Interviews and returns their results.
+
+        :param n: How many times to run each interview
+        :param progress_bar: Whether to show a progress bar
+        :param stop_on_exception: Stops the job if an exception is raised
+        :param check_api_keys: Raises an error if API keys are invalid
+        :param verbose: Prints extra messages
+        :param remote_cache_description: Specifies a description for this group of entries in the remote cache
+        :param remote_inference_description: Specifies a description for the remote inference job
+        :param remote_inference_results_visibility: The initial visibility of the Results object on Coop. This will only be used for remote jobs!
+        :param disable_remote_cache: If True, the job will not use remote cache. This only works for local jobs!
+        :param disable_remote_inference: If True, the job will not use remote inference
+        :param cache: A Cache object to store results
+        :param bucket_collection: A BucketCollection object to track API calls
+        :param key_lookup: A KeyLookup object to manage API keys
+        """
+        self._run(config)
+
+        return await self._execute_with_remote_cache(run_job_async=True)
 
     def __repr__(self) -> str:
         """Return an eval-able string representation of the Jobs instance."""
@@ -697,17 +639,12 @@ class Jobs(Base):
 
     def _summary(self):
         return {
-            "EDSL Class": "Jobs",
-            "Number of questions": len(self.survey),
-            "Number of agents": len(self.agents),
-            "Number of models": len(self.models),
-            "Number of scenarios": len(self.scenarios),
+            "questions": len(self.survey),
+            "agents": len(self.agents or [1]),
+            "models": len(self.models or [1]),
+            "scenarios": len(self.scenarios or [1]),
         }
 
-    def _repr_html_(self) -> str:
-        footer = f"<a href={self.__documentation__}>(docs)</a>"
-        return str(self.summary(format="html")) + footer
-
     def __len__(self) -> int:
         """Return the maximum number of questions that will be asked while running this job.
         Note that this is the maximum number of questions, not the actual number of questions that will be asked, as some questions may be skipped.
@@ -724,10 +661,6 @@ class Jobs(Base):
         )
         return number_of_questions
 
-    #######################
-    # Serialization methods
-    #######################
-
     def to_dict(self, add_edsl_version=True):
         d = {
             "survey": self.survey.to_dict(add_edsl_version=add_edsl_version),
@@ -752,11 +685,14 @@ class Jobs(Base):
 
         return d
 
+    def table(self):
+        return self.prompts().to_scenario_list().table()
+
     @classmethod
     @remove_edsl_version
     def from_dict(cls, data: dict) -> Jobs:
         """Creates a Jobs instance from a dictionary."""
-        from edsl import Survey
+        from edsl.surveys.Survey import Survey
         from edsl.agents.Agent import Agent
         from edsl.language_models.LanguageModel import LanguageModel
         from edsl.scenarios.Scenario import Scenario
@@ -778,9 +714,6 @@ class Jobs(Base):
         """
         return hash(self) == hash(other)
 
-    #######################
-    # Example methods
-    #######################
     @classmethod
     def example(
         cls,
@@ -800,14 +733,14 @@ class Jobs(Base):
         """
         import random
         from uuid import uuid4
-        from edsl.questions import QuestionMultipleChoice
+        from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
         from edsl.agents.Agent import Agent
         from edsl.scenarios.Scenario import Scenario
 
         addition = "" if not randomize else str(uuid4())
 
         if test_model:
-            from edsl.language_models import LanguageModel
+            from edsl.language_models.LanguageModel import LanguageModel
 
             m = LanguageModel.example(test_model=True)
 
@@ -848,7 +781,8 @@ class Jobs(Base):
             question_options=["Good", "Great", "OK", "Terrible"],
             question_name="how_feeling_yesterday",
         )
-        from edsl import Survey, ScenarioList
+        from edsl.surveys.Survey import Survey
+        from edsl.scenarios.ScenarioList import ScenarioList
 
         base_survey = Survey(questions=[q1, q2])
 
@@ -865,15 +799,6 @@ class Jobs(Base):
 
         return job
 
-    def rich_print(self):
-        """Print a rich representation of the Jobs instance."""
-        from rich.table import Table
-
-        table = Table(title="Jobs")
-        table.add_column("Jobs")
-        table.add_row(self.survey.rich_print())
-        return table
-
     def code(self):
         """Return the code to create this instance."""
         raise NotImplementedError
@@ -881,7 +806,7 @@ class Jobs(Base):
 
 def main():
     """Run the module's doctests."""
-    from edsl.jobs import Jobs
+    from edsl.jobs.Jobs import Jobs
     from edsl.data.Cache import Cache
 
     job = Jobs.example()