edsl 0.1.48__py3-none-any.whl → 0.1.50__py3-none-any.whl

edsl/invigilators/prompt_constructor.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
-from typing import Dict, Any, Optional, Set, Union, TYPE_CHECKING, Literal
+from typing import Dict, Any, Optional, TYPE_CHECKING
 from functools import cached_property
-import time
 import logging
 
 from ..prompts import Prompt
@@ -20,7 +19,6 @@ if TYPE_CHECKING:
     from ..agents import Agent
     from ..language_models import LanguageModel
     from ..surveys.memory import MemoryPlan
-    from ..questions import QuestionBase
     from ..scenarios import Scenario
 
 logger = logging.getLogger(__name__)
@@ -438,8 +436,6 @@ class PromptConstructor:
 
     def get_prompts(self) -> Dict[str, Any]:
         """Get the prompts for the question."""
-        start = time.time()
-        
         # Build all the components
         agent_instructions = self.agent_instructions_prompt
         agent_persona = self.agent_persona_prompt

edsl/invigilators/prompt_helpers.py

@@ -76,19 +76,22 @@ class PromptPlan:
             system_prompt_order = (system_prompt_order,)
 
         if not isinstance(user_prompt_order, tuple):
-            raise TypeError(
+            from edsl.invigilators.exceptions import InvigilatorTypeError
+            raise InvigilatorTypeError(
                 f"Expected a tuple, but got {type(user_prompt_order).__name__}"
             )
 
         if not isinstance(system_prompt_order, tuple):
-            raise TypeError(
+            from edsl.invigilators.exceptions import InvigilatorTypeError
+            raise InvigilatorTypeError(
                 f"Expected a tuple, but got {type(system_prompt_order).__name__}"
             )
 
         self.user_prompt_order = self._convert_to_enum(user_prompt_order)
         self.system_prompt_order = self._convert_to_enum(system_prompt_order)
         if not self._is_valid_plan():
-            raise ValueError(
+            from edsl.invigilators.exceptions import InvigilatorValueError
+            raise InvigilatorValueError(
                 "Invalid plan: must contain each value of PromptComponent exactly once."
             )
 
@@ -109,7 +112,8 @@ class PromptPlan:
         # check is valid components passed
         component_strings = set([pc.value for pc in PromptComponent])
         if not set(kwargs.keys()) == component_strings:
-            raise ValueError(
+            from edsl.invigilators.exceptions import InvigilatorValueError
+            raise InvigilatorValueError(
                 f"Invalid components passed: {set(kwargs.keys())} but expected {PromptComponent}"
             )
 

edsl/invigilators/question_instructions_prompt_builder.py

@@ -1,4 +1,4 @@
-from typing import Dict, List, Set, Any, Union, TYPE_CHECKING
+from typing import Dict, Set, Any, Union, TYPE_CHECKING
 from warnings import warn
 import logging
 from ..prompts import Prompt

edsl/invigilators/question_option_processor.py

@@ -1,5 +1,7 @@
-from jinja2 import Environment, meta
-from typing import List, Optional, Union
+from jinja2 import Environment
+from typing import List, Union
+
+import edsl.scenarios.scenario  # noqa: F401
 
 
 def extract_template_variables(ast) -> List[Union[str, tuple]]:
@@ -61,7 +63,7 @@ class QuestionOptionProcessor:
 
         return cls(scenario, prior_answers_dict)
 
-    def __init__(self, scenario: 'Scenario', prior_answers_dict: dict):
+    def __init__(self, scenario: 'edsl.scenarios.scenario.Scenario', prior_answers_dict: dict):
         # This handles cases where the question has {{ scenario.key }} - eventually 
         # we might not allow 'naked' scenario keys w/o the scenario prefix
         #new_scenario = scenario.copy()
@@ -106,9 +108,11 @@ class QuestionOptionProcessor:
         undeclared_variables = extract_template_variables(parsed_content)
         
         if not undeclared_variables:
-            raise ValueError("No variables found in template string")
+            from edsl.invigilators.exceptions import InvigilatorValueError
+            raise InvigilatorValueError("No variables found in template string")
         if len(undeclared_variables) > 1:
-            raise ValueError("Multiple variables found in template string")
+            from edsl.invigilators.exceptions import InvigilatorValueError
+            raise InvigilatorValueError("Multiple variables found in template string")
         
         return undeclared_variables[0]
 

edsl/invigilators/question_template_replacements_builder.py

@@ -156,7 +156,8 @@ class QuestionTemplateReplacementsBuilder:
             if var == "scenario":
                 # If we find a scenario variable, we need to check for nested references
                 # Create a modified template with just {{ scenario.* }} expressions to isolate them
-                scenario_template = "".join([
+                # Using a template format for reference, not actually used
+                _ = "".join([
                     "{% for key, value in scenario.items() %}{{ key }}{% endfor %}"
                 ])
                 try:
@@ -168,7 +169,7 @@ class QuestionTemplateReplacementsBuilder:
                         for key in scenario_refs:
                             if key in scenario_file_keys:
                                 question_file_keys.append(key)
-                except:
+                except Exception:
                     # If there's any issue parsing, just continue with what we have
                     pass
                 

edsl/jobs/__init__.py

@@ -1,7 +1,7 @@
 from .jobs import Jobs
-from .jobs import RunConfig, RunParameters, RunEnvironment
-from .remote_inference import JobsRemoteInferenceHandler
-from .jobs_runner_status import JobsRunnerStatusBase
+from .jobs import RunConfig, RunParameters, RunEnvironment  # noqa: F401
+from .remote_inference import JobsRemoteInferenceHandler  # noqa: F401
+from .jobs_runner_status import JobsRunnerStatusBase  # noqa: F401
 
 
 __all__ = ["Jobs"]

edsl/jobs/async_interview_runner.py

@@ -14,22 +14,23 @@ from edsl.data_transfer_models import EDSLResultObjectInput
 from ..results import Result
 from ..interviews import Interview
 from ..config import Config
+from .data_structures import RunConfig
+
 config = Config()
 
 if TYPE_CHECKING:
     from ..jobs import Jobs
 
-from .data_structures import RunConfig
-
 @dataclass
 class InterviewResult:
     """Container for the result of an interview along with metadata.
-    
+
     Attributes:
         result: The Result object containing the interview answers
         interview: The Interview object used to conduct the interview
         order: The original position of this interview in the processing queue
     """
+
     result: Result
     interview: Interview
     order: int
@@ -38,10 +39,10 @@ class InterviewResult:
 class AsyncInterviewRunner:
     """
     Runs interviews asynchronously with controlled concurrency.
-    
+
     This class manages the parallel execution of multiple interviews while
     respecting concurrency limits and handling errors appropriately.
-    
+
     Examples:
         >>> from unittest.mock import MagicMock, AsyncMock
         >>> mock_jobs = MagicMock()
@@ -52,13 +53,13 @@ class AsyncInterviewRunner:
         >>> isinstance(runner._initialized, asyncio.Event)
         True
     """
-    
+
     MAX_CONCURRENT = int(config.EDSL_MAX_CONCURRENT_TASKS)
 
     def __init__(self, jobs: "Jobs", run_config: RunConfig):
         """
         Initialize the AsyncInterviewRunner.
-        
+
         Args:
             jobs: The Jobs object that generates interviews
             run_config: Configuration for running the interviews
@@ -70,13 +71,13 @@ class AsyncInterviewRunner:
     def _expand_interviews(self) -> Generator["Interview", None, None]:
         """
         Create multiple copies of each interview based on the run configuration.
-        
+
         This method expands interviews for repeated runs and ensures each has
         the proper cache configuration.
-        
+
         Yields:
             Interview objects ready to be conducted
-            
+
         Examples:
             >>> from unittest.mock import MagicMock
             >>> mock_jobs = MagicMock()
@@ -105,16 +106,16 @@ class AsyncInterviewRunner:
     ) -> Tuple["Result", "Interview"]:
         """
         Asynchronously conduct a single interview.
-        
+
         This method performs the interview and creates a Result object with
         the extracted answers and model responses.
-        
+
         Args:
             interview: The interview to conduct
-            
+
         Returns:
             Tuple containing the Result object and the Interview object
-            
+
         Notes:
             'extracted_answers' contains the processed and validated answers
             from the interview, which may differ from the raw model output.
@@ -137,14 +138,14 @@ class AsyncInterviewRunner:
     ) -> AsyncGenerator[tuple[Result, Interview], None]:
         """
         Run all interviews asynchronously and yield results as they complete.
-        
+
         This method processes interviews in chunks based on MAX_CONCURRENT,
         maintaining controlled concurrency while yielding results as soon as
         they become available.
-        
+
         Yields:
             Tuples of (Result, Interview) as interviews complete
-            
+
         Notes:
             - Uses structured concurrency patterns for proper resource management
             - Handles exceptions according to the run configuration
@@ -159,11 +160,11 @@ class AsyncInterviewRunner:
             try:
                 result, interview = await self._conduct_interview(interview)
                 self.run_config.environment.jobs_runner_status.add_completed_interview(
-                    result
+                    interview
                 )
                 result.order = idx
                 return InterviewResult(result, interview, idx)
-            except Exception as e:
+            except Exception:
                 if self.run_config.parameters.stop_on_exception:
                     raise
                 return None
@@ -187,7 +188,7 @@ class AsyncInterviewRunner:
                 for result in (r for r in results if r is not None):
                     yield result.result, result.interview
 
-            except Exception as e:
+            except Exception:
                 if self.run_config.parameters.stop_on_exception:
                     raise
                 continue
@@ -200,5 +201,6 @@ class AsyncInterviewRunner:
 
 
 if __name__ == "__main__":
-    import doctest 
-    doctest.testmod()
+    import doctest
+
+    doctest.testmod()

edsl/jobs/check_survey_scenario_compatibility.py

@@ -2,6 +2,7 @@ import warnings
 from typing import TYPE_CHECKING
 from edsl.scenarios import ScenarioList
 from edsl.surveys import Survey
+from edsl.jobs.exceptions import JobsCompatibilityError
 
 if TYPE_CHECKING:
     from edsl.surveys.Survey import Survey
@@ -34,19 +35,19 @@ class CheckSurveyScenarioCompatibility:
         >>> s = Scenario({'plop': "A", 'poo': "B"})
         >>> j = Jobs(survey = Survey(questions=[q])).by(s)
         >>> cs = CheckSurveyScenarioCompatibility(j.survey, j.scenarios)
-        >>> cs.check(strict = True)
+        >>> cs.check(strict = True)  # doctest: +ELLIPSIS
         Traceback (most recent call last):
         ...
-        ValueError: The following parameters are in the scenarios but not in the survey: {'plop'}
+        edsl.jobs.exceptions.JobsCompatibilityError: 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"})
         >>> from edsl.scenarios import ScenarioList
         >>> cs = CheckSurveyScenarioCompatibility(Survey(questions=[q]), ScenarioList([s]))
-        >>> cs.check()
+        >>> cs.check()  # doctest: +ELLIPSIS
         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.
+        edsl.jobs.exceptions.JobsCompatibilityError: 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
@@ -59,7 +60,7 @@ class CheckSurveyScenarioCompatibility:
         ):
             msg0 = f"The following names are in both the survey question_names and the scenario keys: {intersection}. This will create issues."
 
-            raise ValueError(msg0)
+            raise JobsCompatibilityError(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}"
@@ -69,7 +70,7 @@ class CheckSurveyScenarioCompatibility:
         if msg1 or msg2:
             message = "\n".join(filter(None, [msg1, msg2]))
             if strict:
-                raise ValueError(message)
+                raise JobsCompatibilityError(message)
             else:
                 if warn:
                     warnings.warn(message)

edsl/jobs/data_structures.py

@@ -1,5 +1,7 @@
-from typing import Optional, Literal
+from typing import Optional, Literal, TYPE_CHECKING
 from dataclasses import dataclass, asdict
+from collections import UserDict
+from edsl.data_transfer_models import EDSLResultObjectInput
 
 # from edsl.data_transfer_models import VisibilityType
 from ..caching import Cache
@@ -9,6 +11,10 @@ from ..base import Base
 
 from .jobs_runner_status import JobsRunnerStatus
 
+if TYPE_CHECKING:
+    from ..questions.question_base import QuestionBase
+    from ..surveys import Survey
+
 VisibilityType = Literal["private", "public", "unlisted"]
 
 @dataclass
@@ -157,9 +163,6 @@ class RunConfig:
 Additional data structures for working with job results and answers.
 """
 
-from collections import UserDict
-from edsl.data_transfer_models import EDSLResultObjectInput
-
 
 class Answers(UserDict):
     """

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