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

edsl/invigilators/exceptions.py

@@ -0,0 +1,79 @@
+"""
+Exceptions specific to the invigilators module.
+
+This module defines custom exception classes for all invigilator-related errors
+in the EDSL framework, ensuring consistent error handling and user feedback.
+"""
+
+from ..base import BaseException
+
+
+class InvigilatorError(BaseException):
+    """
+    Base exception class for all invigilator-related errors.
+    
+    This is the parent class for all exceptions related to invigilator creation,
+    execution, and management in the EDSL framework.
+    
+    Examples:
+        ```python
+        # Usually not raised directly, but through subclasses
+        # For example, when attempting to use an unimplemented feature
+        invigilator.encode_image(image_path)  # Would raise InvigilatorNotImplementedError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#invigilators"
+
+
+class InvigilatorTypeError(InvigilatorError):
+    """
+    Exception raised when there's a type mismatch in invigilator operations.
+    
+    This exception occurs when:
+    - Invalid input types are provided to invigilator methods
+    - Template variables have incompatible types
+    - Return value types don't match expected types
+    
+    Examples:
+        ```python
+        # Providing an invalid type to an invigilator method
+        invigilator.process_options(123)  # Raises InvigilatorTypeError if expected a dict
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#invigilators"
+
+
+class InvigilatorValueError(InvigilatorError):
+    """
+    Exception raised when invalid values are provided to invigilator operations.
+    
+    This exception occurs when:
+    - Template variables are missing or invalid
+    - Option values don't match expected patterns
+    - Configuration values are outside allowed ranges
+    
+    Examples:
+        ```python
+        # Template with invalid variables
+        invigilator.process_template("Hello {{ missing }}")  # Raises InvigilatorValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#invigilators"
+
+
+class InvigilatorNotImplementedError(InvigilatorError):
+    """
+    Exception raised when attempting to use an unimplemented feature.
+    
+    This exception occurs when:
+    - Calling methods that are not implemented in a specific invigilator
+    - Using features only available in certain invigilator types
+    - Using planned functionality that is not yet available
+    
+    Examples:
+        ```python
+        # Attempting to use image encoding when not implemented
+        invigilator.encode_image(image_path)  # Raises InvigilatorNotImplementedError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#invigilators"

edsl/invigilators/invigilator_base.py

@@ -3,7 +3,6 @@ import asyncio
 from typing import Coroutine, Dict, Any, Optional, TYPE_CHECKING
 
 from ..utilities.decorators import jupyter_nb_handler
-from ..data_transfer_models import AgentResponseDict
 
 if TYPE_CHECKING:
     from ..prompts import Prompt

edsl/invigilators/invigilators.py

@@ -2,14 +2,12 @@
 from abc import ABC, abstractmethod
 import asyncio
 from typing import Coroutine, Dict, Any, Optional, TYPE_CHECKING
-from typing import Dict, Any, Optional, TYPE_CHECKING, Literal
+from typing import Literal
 
 from ..utilities.decorators import sync_wrapper
 from ..questions.exceptions import QuestionAnswerValidationError
-from ..data_transfer_models import AgentResponseDict, EDSLResultObjectInput
+from ..base.data_transfer_models import AgentResponseDict, EDSLResultObjectInput
 from ..utilities.decorators import jupyter_nb_handler
-from ..data_transfer_models import AgentResponseDict
-from ..data_transfer_models import EDSLResultObjectInput
 
 from .prompt_constructor import PromptConstructor
 from .prompt_helpers import PromptPlan
@@ -18,13 +16,10 @@ if TYPE_CHECKING:
     from ..prompts import Prompt
     from ..scenarios import Scenario
     from ..surveys import Survey
-    from ..prompts import Prompt
     from ..caching import Cache
     from ..questions import QuestionBase
-    from ..scenarios import Scenario
     from ..surveys.memory import MemoryPlan
     from ..language_models import LanguageModel
-    from ..surveys import Survey
     from ..agents import Agent
     from ..key_management import KeyLookup
 
@@ -171,14 +166,14 @@ class InvigilatorBase(ABC):
         """
         data = {
             "answer": None,
-            "generated_tokens": None,
+            "generated_tokens": getattr(self, "generated_tokens", None),
             "comment": failure_reason,
             "question_name": self.question.question_name,
             "prompts": self.get_prompts(),
-            "cached_response": None,
-            "raw_model_response": None,
-            "cache_used": None,
-            "cache_key": None,
+            "cached_response": getattr(self, "cached_response", None),
+            "raw_model_response": getattr(self, "raw_model_response", None),
+            "cache_used": getattr(self, "cache_used", None),
+            "cache_key": getattr(self, "cache_key", None),
         }
         return EDSLResultObjectInput(**data)
 
@@ -285,7 +280,8 @@ class InvigilatorAI(InvigilatorBase):
         }
         if "encoded_image" in prompts:
             params["encoded_image"] = prompts["encoded_image"]
-            raise NotImplementedError("encoded_image not implemented")
+            from .exceptions import InvigilatorNotImplementedError
+            raise InvigilatorNotImplementedError("encoded_image not implemented")
 
         if "files_list" in prompts:
             params["files_list"] = prompts["files_list"]

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,44 @@
-from .jobs import Jobs
-from .jobs import RunConfig, RunParameters, RunEnvironment
-from .remote_inference import JobsRemoteInferenceHandler
-from .jobs_runner_status import JobsRunnerStatusBase
+"""
+The jobs module provides tools for running and managing EDSL jobs.
+
+It includes classes for job configuration, execution, pricing estimation,
+and management of concurrent language model API calls.
+"""
 
+from .jobs import Jobs
+from .jobs import RunConfig, RunParameters, RunEnvironment  # noqa: F401
+from .remote_inference import JobsRemoteInferenceHandler  # noqa: F401
+from .jobs_runner_status import JobsRunnerStatusBase  # noqa: F401
+from .exceptions import (
+    JobsErrors,
+    JobsRunError,
+    MissingRemoteInferenceError,
+    InterviewError,
+    InterviewErrorPriorTaskCanceled,
+    InterviewTimeoutError,
+    JobsValueError,
+    JobsCompatibilityError,
+    JobsImplementationError,
+    RemoteInferenceError,
+    JobsTypeError
+)
 
-__all__ = ["Jobs"]
+__all__ = [
+    "Jobs",
+    "JobsErrors",
+    "JobsRunError",
+    "MissingRemoteInferenceError",
+    "InterviewError",
+    "InterviewErrorPriorTaskCanceled",
+    "InterviewTimeoutError",
+    "JobsValueError",
+    "JobsCompatibilityError",
+    "JobsImplementationError",
+    "RemoteInferenceError",
+    "JobsTypeError",
+    "JobsRemoteInferenceHandler",
+    "JobsRunnerStatusBase",
+    "RunConfig",
+    "RunParameters",
+    "RunEnvironment"
+]

edsl/jobs/async_interview_runner.py

@@ -9,27 +9,28 @@ from collections.abc import AsyncGenerator
 from typing import List, Generator, Tuple, TYPE_CHECKING
 from dataclasses import dataclass
 import asyncio
-from edsl.data_transfer_models import EDSLResultObjectInput
+from ..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

@@ -1,11 +1,12 @@
 import warnings
 from typing import TYPE_CHECKING
-from edsl.scenarios import ScenarioList
-from edsl.surveys import Survey
+from ..scenarios import ScenarioList
+from ..surveys import Survey
+from .exceptions import JobsCompatibilityError
 
 if TYPE_CHECKING:
-    from edsl.surveys.Survey import Survey
-    from edsl.scenarios.ScenarioList import ScenarioList
+    from ..surveys.survey import Survey
+    from ..scenarios.scenario_list import ScenarioList
 
 
 class CheckSurveyScenarioCompatibility:
@@ -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 ..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
@@ -80,7 +86,7 @@ class RunParameters(Base):
     def to_dict(self, add_edsl_version=False) -> dict:
         d = asdict(self)
         if add_edsl_version:
-            from edsl import __version__
+            from .. import __version__
 
             d["edsl_version"] = __version__
             d["edsl_class_name"] = "RunConfig"
@@ -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):
     """