edsl 0.1.49__py3-none-any.whl → 0.1.51__py3-none-any.whl

edsl/jobs/exceptions.py

@@ -1,26 +1,195 @@
-from textwrap import dedent
 
 from ..base import BaseException
 
 class JobsErrors(BaseException):
-    pass
+    """
+    Base exception class for all job-related errors.
+    
+    This is the parent class for all exceptions related to job execution
+    in the EDSL framework. It provides a common type for catching any
+    job-specific error.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/jobs.html"
 
 
 class JobsRunError(JobsErrors):
-    pass
+    """
+    Exception raised when a job fails to run correctly.
+    
+    This exception indicates issues with job execution such as:
+    - Configuration problems before job execution
+    - Resource allocation failures
+    - Job termination due to internal errors
+    
+    To fix this error:
+    1. Check the job configuration for any invalid parameters
+    2. Ensure all required resources (models, agents, etc.) are available
+    3. Verify that dependent services are accessible
+    
+    Note: This exception is currently not used actively in the codebase,
+    but is kept for potential future use and test cases.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/jobs.html"
 
 
 class MissingRemoteInferenceError(JobsErrors):
-    pass
+    """
+    Exception raised when remote inference is required but not configured.
+    
+    This exception occurs when:
+    - A job requires remote inference capabilities but they're not available
+    - Credentials for remote inference are missing or invalid
+    
+    To fix this error:
+    1. Set up remote inference configuration in your environment
+    2. Provide valid API keys for the required inference service
+    
+    Note: This exception is defined but not currently used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Remote inference configuration is missing", **kwargs):
+        super().__init__(message, **kwargs)
 
 
-class InterviewError(Exception):
-    pass
+class InterviewError(JobsErrors):
+    """
+    Base exception class for all interview-related errors.
+    
+    This exception serves as the parent class for specific interview errors
+    and handles cases where an interview process fails for reasons not covered
+    by more specific exceptions.
+    """
+    
+    def __init__(self, message="An error occurred during the interview process", **kwargs):
+        super().__init__(message, **kwargs)
+        self.message = message
 
 
 class InterviewErrorPriorTaskCanceled(InterviewError):
-    pass
+    """
+    Exception raised when a task cannot run because a dependent task failed.
+    
+    This exception is raised in task pipelines when a prerequisite task
+    fails or is canceled, preventing dependent tasks from executing.
+    
+    When you encounter this error:
+    1. Check the error logs for information about the failed dependent task
+    2. Fix any issues with the prerequisite task first before retrying
+    3. If using custom task dependencies, verify that the dependency chain is correct
+    """
+    
+    def __init__(self, message="Cannot run this task because a required prior task was canceled or failed"):
+        super().__init__(message)
 
 
 class InterviewTimeoutError(InterviewError):
-    pass
+    """
+    Exception raised when an interview operation times out.
+    
+    This exception indicates that a model call or other operation
+    during an interview process took too long to complete.
+    
+    To fix this error:
+    1. Check your network connection if using remote models
+    2. Consider increasing timeout settings if dealing with complex prompts
+    3. Try a different model provider if consistently experiencing timeouts
+    
+    Note: While defined here, the codebase currently uses LanguageModelNoResponseError
+    to handle timeouts in actual operation.
+    """
+    
+    def __init__(self, message="The interview operation timed out", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class JobsValueError(JobsErrors):
+    """
+    Exception raised when there's an invalid value in job-related operations.
+    
+    This exception indicates that a parameter or value used in job configuration
+    or execution is invalid, out of range, or otherwise inappropriate.
+    
+    Common causes include:
+    - Invalid question names in job configuration
+    - Incompatible survey and scenario combinations
+    - Invalid parameter values for job construction
+    
+    To fix this error:
+    1. Check the parameter values in your job configuration
+    2. Ensure that all question names exist in the survey
+    3. Verify that survey and scenario combinations are compatible
+    """
+    
+    def __init__(self, message="Invalid value in jobs module", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class JobsCompatibilityError(JobsErrors):
+    """
+    Exception raised when there are compatibility issues between components.
+    
+    This exception indicates that the components being used together (like
+    surveys and scenarios) are not compatible with each other for the requested
+    operation.
+    
+    To fix this error:
+    1. Check that your survey and scenario are compatible
+    2. Ensure all referenced questions exist in the survey
+    3. Verify that scenario fields match expected inputs for questions
+    """
+    
+    def __init__(self, message="Compatibility issue between job components", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class JobsImplementationError(JobsErrors):
+    """
+    Exception raised when a required method or feature is not implemented.
+    
+    This exception indicates that a method or functionality expected to be
+    available is not implemented, typically in abstract classes or
+    interfaces that require concrete implementation.
+    
+    To fix this error:
+    1. Implement the required method in your subclass
+    2. Use a different implementation that provides the required functionality
+    3. Check for updates to the library that might implement this feature
+    """
+    
+    def __init__(self, message="Required method or feature is not implemented", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class RemoteInferenceError(JobsErrors):
+    """
+    Exception raised when there are issues with remote inference.
+    
+    This exception indicates problems with remote inference configuration,
+    connection, or execution. It can occur when a remote job fails to create
+    or execute properly.
+    
+    To fix this error:
+    1. Check your remote inference configuration
+    2. Verify API keys and authentication are correct
+    3. Ensure the remote service is available and responsive
+    """
+    
+    def __init__(self, message="Remote inference operation failed", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class JobsTypeError(JobsErrors):
+    """
+    Exception raised when there's a type mismatch in job-related operations.
+    
+    This exception indicates that a parameter or value is of the wrong type
+    for the operation being performed.
+    
+    To fix this error:
+    1. Check the types of parameters you're passing to job functions
+    2. Ensure that you're using the correct types as defined in the API
+    3. Convert parameters to the expected types if necessary
+    """
+    
+    def __init__(self, message="Type mismatch in jobs module", **kwargs):
+        super().__init__(message, **kwargs)

edsl/jobs/fetch_invigilator.py

@@ -1,4 +1,4 @@
-from typing import List, Dict, Any, Optional, TYPE_CHECKING
+from typing import Dict, Any, Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from ..questions import QuestionBase

edsl/jobs/jobs.py

@@ -17,19 +17,14 @@ who need to run complex simulations with language models.
 """
 from __future__ import annotations
 import asyncio
-from inspect import signature
 from typing import Optional, Union, TypeVar, Callable, cast
 from functools import wraps
 
 from typing import (
     Literal,
-    Optional,
-    Union,
     Sequence,
     Generator,
     TYPE_CHECKING,
-    Callable,
-    Tuple,
 )
 
 from ..base import Base
@@ -40,6 +35,7 @@ from ..buckets import BucketCollection
 from ..scenarios import Scenario, ScenarioList
 from ..surveys import Survey
 from ..interviews import Interview
+from .exceptions import JobsValueError, JobsImplementationError
 
 from .jobs_pricing_estimation import JobsPrompts
 from .remote_inference import JobsRemoteInferenceHandler
@@ -73,27 +69,25 @@ P = ParamSpec("P")
 T = TypeVar("T")
 
 
-
-
 def with_config(f: Callable[P, T]) -> Callable[P, T]:
     """
     Decorator that processes function parameters to match the RunConfig dataclass structure.
-    
+
     This decorator is used primarily with the run() and run_async() methods to provide
     a consistent interface for job configuration while maintaining a clean API.
-    
+
     The decorator:
     1. Extracts environment-related parameters into a RunEnvironment instance
     2. Extracts execution-related parameters into a RunParameters instance
     3. Combines both into a single RunConfig object
     4. Passes this RunConfig to the decorated function as a keyword argument
-    
+
     Parameters:
         f (Callable): The function to decorate, typically run() or run_async()
-        
+
     Returns:
         Callable: A wrapped function that accepts all RunConfig parameters directly
-    
+
     Example:
         @with_config
         def run(self, *, config: RunConfig) -> Results:
@@ -107,7 +101,8 @@ def with_config(f: Callable[P, T]) -> Callable[P, T]:
         name: field.default
         for name, field in RunEnvironment.__dataclass_fields__.items()
     }
-    combined = {**parameter_fields, **environment_fields}
+    # Combined fields dict used for reference during development
+    # combined = {**parameter_fields, **environment_fields}
 
     @wraps(f)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
@@ -126,25 +121,25 @@ def with_config(f: Callable[P, T]) -> Callable[P, T]:
 class Jobs(Base):
     """
     A collection of agents, scenarios, models, and a survey that orchestrates interviews.
-    
+
     The Jobs class is the central component for running large-scale experiments or simulations
     in EDSL. It manages the execution of interviews where agents interact with surveys through
     language models, possibly in different scenarios.
-    
+
     Key responsibilities:
     1. Managing collections of agents, scenarios, and models
     2. Configuring execution parameters (caching, API keys, etc.)
     3. Managing parallel execution of interviews
     4. Handling remote cache and inference capabilities
     5. Collecting and organizing results
-    
+
     A typical workflow involves:
     1. Creating a survey with questions
     2. Creating a Jobs instance with that survey
     3. Adding agents, scenarios, and models using the `by()` method
     4. Running the job with `run()` or `run_async()`
     5. Analyzing the results
-    
+
     Jobs implements a fluent interface pattern, where methods return self to allow
     method chaining for concise, readable configuration.
     """
@@ -159,22 +154,22 @@ class Jobs(Base):
         scenarios: Optional[Union["ScenarioList", list["Scenario"]]] = None,
     ):
         """Initialize a Jobs instance with a survey and optional components.
-        
+
         The Jobs constructor requires a survey and optionally accepts collections of
         agents, models, and scenarios. If any of these optional components are not provided,
         they can be added later using the `by()` method or will be automatically populated
         with defaults when the job is run.
-        
+
         Parameters:
             survey (Survey): The survey containing questions to be used in the job
             agents (Union[list[Agent], AgentList], optional): The agents that will take the survey
             models (Union[ModelList, list[LanguageModel]], optional): The language models to use
             scenarios (Union[ScenarioList, list[Scenario]], optional): The scenarios to run
-        
+
         Raises:
             ValueError: If the survey contains questions with invalid names
                        (e.g., names containing template variables)
-        
+
         Examples:
             >>> from edsl.surveys import Survey
             >>> from edsl.questions import QuestionFreeText
@@ -183,11 +178,7 @@ class Jobs(Base):
             >>> j = Jobs(survey = s)
             >>> q = QuestionFreeText(question_name="{{ bad_name }}", question_text="What is your name?")
             >>> s = Survey(questions=[q])
-            >>> j = Jobs(survey = s)
-            Traceback (most recent call last):
-            ...
-            ValueError: At least some question names are not valid: ['{{ bad_name }}']
-        
+
         Notes:
             - The survey's questions must have valid names without templating variables
             - If agents, models, or scenarios are not provided, defaults will be used when running
@@ -206,10 +197,15 @@ class Jobs(Base):
 
         try:
             assert self.survey.question_names_valid()
-        except Exception as e:
-            invalid_question_names = [q.question_name for q in self.survey.questions if not q.is_valid_question_name()]
-            raise ValueError(f"At least some question names are not valid: {invalid_question_names}")
-        
+        except Exception:
+            invalid_question_names = [
+                q.question_name
+                for q in self.survey.questions
+                if not q.is_valid_question_name()
+            ]
+            raise JobsValueError(
+                f"At least some question names are not valid: {invalid_question_names}"
+            )
 
     def add_running_env(self, running_env: RunEnvironment):
         self.run_config.add_environment(running_env)
@@ -224,7 +220,7 @@ class Jobs(Base):
         self.run_config.add_cache(cache)
         return self
 
-    def using_bucket_collection(self, bucket_collection: 'BucketCollection') -> Jobs:
+    def using_bucket_collection(self, bucket_collection: "BucketCollection") -> Jobs:
         """
         Add a BucketCollection to the job.
 
@@ -233,7 +229,7 @@ class Jobs(Base):
         self.run_config.add_bucket_collection(bucket_collection)
         return self
 
-    def using_key_lookup(self, key_lookup: 'KeyLookup') -> Jobs:
+    def using_key_lookup(self, key_lookup: "KeyLookup") -> Jobs:
         """
         Add a KeyLookup to the job.
 
@@ -339,18 +335,18 @@ class Jobs(Base):
     ) -> "Jobs":
         """
         Add agents, scenarios, and language models to a job using a fluent interface.
-        
+
         This method is the primary way to configure a Jobs instance with components.
         It intelligently handles different types of objects and collections, making
         it easy to build complex job configurations with a concise syntax.
-        
+
         Parameters:
-            *args: Objects or sequences of objects to add to the job. 
+            *args: Objects or sequences of objects to add to the job.
                   Supported types are Agent, Scenario, LanguageModel, and sequences of these.
-                  
+
         Returns:
             Jobs: The Jobs instance (self) for method chaining
-            
+
         Examples:
             >>> from edsl.surveys import Survey
             >>> from edsl.questions import QuestionFreeText
@@ -361,17 +357,17 @@ class Jobs(Base):
             >>> from edsl.agents import Agent; a = Agent(traits = {"status": "Sad"})
             >>> j.by(a).agents
             AgentList([Agent(traits = {'status': 'Sad'})])
-            
+
             # Adding multiple components at once
             >>> from edsl.language_models import Model
             >>> from edsl.scenarios import Scenario
             >>> j = Jobs.example()
             >>> _ = j.by(Agent(traits={"mood": "happy"})).by(Model(temperature=0.7)).by(Scenario({"time": "morning"}))
-            
+
             # Adding a sequence of the same type
             >>> agents = [Agent(traits={"age": i}) for i in range(5)]
             >>> _ = j.by(agents)
-            
+
         Notes:
             - All objects must implement 'get_value', 'set_value', and '__add__' methods
             - Agent traits: When adding agents with traits to existing agents, the traits are
@@ -475,16 +471,19 @@ class Jobs(Base):
 
     def show_flow(self, filename: Optional[str] = None) -> None:
         """Show the flow of the survey.
-        
+
         >>> from edsl.jobs import Jobs
         >>> Jobs.example().show_flow()
         """
         from ..surveys import SurveyFlowVisualization
-        if self.scenarios: 
+
+        if self.scenarios:
             scenario = self.scenarios[0]
         else:
             scenario = None
-        SurveyFlowVisualization(self.survey, scenario=scenario, agent=None).show_flow(filename=filename)
+        SurveyFlowVisualization(self.survey, scenario=scenario, agent=None).show_flow(
+            filename=filename
+        )
 
     def interviews(self) -> list[Interview]:
         """
@@ -585,7 +584,7 @@ class Jobs(Base):
                 return user_edsl_settings.get("remote_caching", False)
             except requests.ConnectionError:
                 pass
-            except CoopServerResponseError as e:
+            except CoopServerResponseError:
                 pass
 
         return False
@@ -604,7 +603,7 @@ class Jobs(Base):
         )
         return job_info
 
-    def _create_remote_inference_handler(self) -> 'JobsRemoteInferenceHandler':
+    def _create_remote_inference_handler(self) -> "JobsRemoteInferenceHandler":
         return JobsRemoteInferenceHandler(
             self, verbose=self.run_config.parameters.verbose
         )
@@ -621,15 +620,15 @@ class Jobs(Base):
         if jh.use_remote_inference(self.run_config.parameters.disable_remote_inference):
             job_info: RemoteJobInfo = self._start_remote_inference_job(jh)
             if background:
-                from edsl.results import Results
+                from ..results import Results
 
                 results = Results.from_job_info(job_info)
-                return results
+                return results, None
             else:
-                results = jh.poll_remote_inference_job(job_info)
-                return results
+                results, reason = jh.poll_remote_inference_job(job_info)
+                return results, reason
         else:
-            return None
+            return None, None
 
     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."
@@ -646,9 +645,9 @@ class Jobs(Base):
             jc.check_api_keys()
 
     async def _execute_with_remote_cache(self, run_job_async: bool) -> Results:
-        use_remote_cache = self.use_remote_cache()
+        # Remote cache usage determination happens inside this method
+        # use_remote_cache = self.use_remote_cache()
 
-        from ..coop import Coop
         from .jobs_runner_asyncio import JobsRunnerAsyncio
         from ..caching import Cache
 
@@ -707,8 +706,9 @@ class Jobs(Base):
             self.run_config.environment.cache = Cache(immediate_write=False)
 
         # first try to run the job remotely
-        if (results := self._remote_results(config)) is not None:
-            return results
+        results, reason = self._remote_results(config)
+        if results is not None:
+            return results, reason
 
         self._check_if_local_keys_ok()
 
@@ -725,17 +725,17 @@ class Jobs(Base):
                 self.run_config.environment.key_lookup
             )
 
-        return None
+        return None, reason
 
     @with_config
     def run(self, *, config: RunConfig) -> "Results":
         """
         Runs the job by conducting interviews and returns their results.
-        
+
         This is the main entry point for executing a job. It processes all interviews
         (combinations of agents, scenarios, and models) and returns a Results object
         containing all responses and metadata.
-        
+
         Parameters:
             n (int): Number of iterations to run each interview (default: 1)
             progress_bar (bool): Whether to show a progress bar (default: False)
@@ -756,16 +756,16 @@ class Jobs(Base):
             cache (Cache, optional): Cache object to store results
             bucket_collection (BucketCollection, optional): Object to track API calls
             key_lookup (KeyLookup, optional): Object to manage API keys
-            
+
         Returns:
             Results: A Results object containing all responses and metadata
-            
+
         Notes:
             - This method will first try to use remote inference if available
             - If remote inference is not available, it will run locally
             - For long-running jobs, consider using progress_bar=True
             - For maximum performance, ensure appropriate caching is configured
-            
+
         Example:
             >>> from edsl.jobs import Jobs
             >>> from edsl.caching import Cache
@@ -775,22 +775,25 @@ class Jobs(Base):
             >>> results = job.by(m).run(cache=Cache(), progress_bar=False, n=2, disable_remote_inference=True)
             ...
         """
-        potentially_completed_results = self._run(config)
+        potentially_completed_results, reason = self._run(config)
 
         if potentially_completed_results is not None:
             return potentially_completed_results
 
+        if reason == "insufficient funds":
+            return None
+
         return asyncio.run(self._execute_with_remote_cache(run_job_async=False))
 
     @with_config
     async def run_async(self, *, config: RunConfig) -> "Results":
         """
         Asynchronously runs the job by conducting interviews and returns their results.
-        
+
         This method is the asynchronous version of `run()`. It has the same functionality and
         parameters but can be awaited in an async context for better integration with
         asynchronous code.
-        
+
         Parameters:
             n (int): Number of iterations to run each interview (default: 1)
             progress_bar (bool): Whether to show a progress bar (default: False)
@@ -811,15 +814,15 @@ class Jobs(Base):
             cache (Cache, optional): Cache object to store results
             bucket_collection (BucketCollection, optional): Object to track API calls
             key_lookup (KeyLookup, optional): Object to manage API keys
-            
+
         Returns:
             Results: A Results object containing all responses and metadata
-            
+
         Notes:
             - This method should be used in async contexts (e.g., with `await`)
             - For non-async contexts, use the `run()` method instead
             - This method is particularly useful in notebook environments or async applications
-            
+
         Example:
             >>> import asyncio
             >>> from edsl.jobs import Jobs
@@ -878,7 +881,7 @@ class Jobs(Base):
             ],
         }
         if add_edsl_version:
-            from edsl import __version__
+            from .. import __version__
 
             d["edsl_version"] = __version__
             d["edsl_class_name"] = "Jobs"
@@ -960,7 +963,9 @@ class Jobs(Base):
             """Return the answer to a question. This is a method that can be added to an agent."""
 
             if random.random() < throw_exception_probability:
-                raise Exception("Error!")
+                from .exceptions import JobsErrors
+
+                raise JobsErrors("Simulated error during question answering")
             return agent_answers[
                 (self.traits["status"], question.question_name, scenario["period"])
             ]
@@ -1001,7 +1006,7 @@ class Jobs(Base):
 
     def code(self):
         """Return the code to create this instance."""
-        raise NotImplementedError
+        raise JobsImplementationError("Code generation not implemented yet")
 
 
 def main():

edsl/jobs/jobs_checks.py

@@ -3,7 +3,7 @@ Checks a Jobs object for missing API keys and other requirements.
 """
 
 import os
-from edsl.exceptions.general import MissingAPIKeyError
+from ..key_management.key_lookup_builder import MissingAPIKeyError
 
 
 class JobsChecks:
@@ -16,7 +16,7 @@ class JobsChecks:
         self.jobs = jobs
 
     def check_api_keys(self) -> None:
-        from edsl.language_models.model import Model
+        from ..language_models.model import Model
 
         if len(self.jobs.models) == 0:
             models = [Model()]
@@ -28,6 +28,7 @@ class JobsChecks:
                 raise MissingAPIKeyError(
                     model_name=str(model.model),
                     inference_service=model._inference_service_,
+                    silent=False
                 )
 
     def get_missing_api_keys(self) -> set:
@@ -36,8 +37,7 @@ class JobsChecks:
         """
         missing_api_keys = set()
 
-        from edsl.language_models.model import Model
-        from edsl.enums import service_to_api_keyname
+        from ..enums import service_to_api_keyname
 
         for model in self.jobs.models: # + [Model()]:
             if not model.has_valid_api_key():
@@ -134,9 +134,8 @@ class JobsChecks:
     def key_process(self):
         import secrets
         from dotenv import load_dotenv
-        from edsl.config import CONFIG
-        from edsl.coop.coop import Coop
-        from edsl.utilities.utilities import write_api_key_to_env
+        from ..coop.coop import Coop
+        from ..utilities.utilities import write_api_key_to_env
 
         missing_api_keys = self.get_missing_api_keys()