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

edsl/instructions/instruction_handler.py

@@ -1,4 +1,3 @@
-from typing import TYPE_CHECKING
 from dataclasses import dataclass
 
 
@@ -46,12 +45,6 @@ class InstructionHandler:
         ['intro']
         >>> [i.name for i in s._relevant_instructions(q3)]
         []
-
-        >>> i_change = ChangeInstruction(keep = ["poop"], drop = [])
-        >>> s = Survey([q1, i, q2, i_change])
-        Traceback (most recent call last):
-        ...
-        ValueError: ChangeInstruction change_instruction_0 references instruction poop which does not exist.
         """
         from .instruction import Instruction
         from .change_instruction import ChangeInstruction
@@ -70,7 +63,8 @@ class InstructionHandler:
                     num_change_instructions += 1
                     for prior_instruction in entry.keep + entry.drop:
                         if prior_instruction not in instruction_names_to_instructions:
-                            raise ValueError(
+                            from edsl.instructions.exceptions import InstructionValueError
+                            raise InstructionValueError(
                                 f"ChangeInstruction {entry.name} references instruction {prior_instruction} which does not exist."
                             )
                 instructions_run_length += 1
@@ -83,7 +77,8 @@ class InstructionHandler:
                 instructions_run_length = 0
                 true_questions.append(entry)
             else:
-                raise ValueError(
+                from edsl.instructions.exceptions import InstructionValueError
+                raise InstructionValueError(
                     f"Entry {repr(entry)} is not a QuestionBase or an Instruction."
                 )
 

edsl/interviews/ReportErrors.py

@@ -1,7 +1,4 @@
-import json
-import requests
 import threading
-from ..coop import Coop
 
 
 class ReportErrors:

edsl/interviews/__init__.py

@@ -1,4 +1,11 @@
-from .interview_task_manager import InterviewTaskManager
+from .interview import Interview
 from .interview_status_dictionary import InterviewStatusDictionary
 from .interview_status_log import InterviewStatusLog
-from .interview import Interview
+from .interview_task_manager import InterviewTaskManager
+
+__all__ = [
+    "InterviewTaskManager",
+    "InterviewStatusDictionary",
+    "InterviewStatusLog",
+    "Interview"
+]

edsl/interviews/answering_function.py

@@ -1,21 +1,19 @@
-import copy
 import asyncio
-
-from typing import Union, Type, Callable, TYPE_CHECKING, Any
+import copy
+from typing import TYPE_CHECKING, Any, Callable, Union
 
 if TYPE_CHECKING:
+    from ..invigilators.invigilator_base import InvigilatorBase
+    from ..key_management import KeyLookup
     from ..questions import QuestionBase
     from .interview import Interview
-    from ..key_management import KeyLookup
-
-from ..surveys.base import EndOfSurvey
-from ..tasks import TaskStatus
 
+from ..data_transfer_models import EDSLResultObjectInput
 from ..jobs.fetch_invigilator import FetchInvigilator
 from ..language_models.exceptions import LanguageModelNoResponseError
 from ..questions.exceptions import QuestionAnswerValidationError
-from ..data_transfer_models import AgentResponseDict, EDSLResultObjectInput, Answers
-
+from ..surveys.base import EndOfSurvey
+from ..tasks import TaskStatus
 from .exception_tracking import InterviewExceptionEntry
 
 
@@ -46,7 +44,7 @@ class SkipHandler:
             | self.interview.agent["traits"]
         )
         return self.skip_function(current_question_index, combined_answers)
-    
+
     def _current_info_env(self) -> dict[str, Any]:
         """
         - The current answers are "generated_tokens" and "comment" 
@@ -112,7 +110,7 @@ class SkipHandler:
         if next_question_index > (current_question_index + 1):
             cancel_between(current_question_index + 1, next_question_index)
 
-        
+
 
 
 class AnswerQuestionFunctionConstructor:
@@ -175,11 +173,11 @@ class AnswerQuestionFunctionConstructor:
     ) -> "EDSLResultObjectInput":
 
         from tenacity import (
+            RetryError,
             retry,
+            retry_if_exception_type,
             stop_after_attempt,
             wait_exponential,
-            retry_if_exception_type,
-            RetryError,
         )
 
         @retry(

edsl/interviews/exception_tracking.py

@@ -1,10 +1,11 @@
-from collections import UserDict
-import traceback
 import datetime
 import json
+import traceback
+from collections import UserDict
 
 from ..invigilators import InvigilatorBase
 
+
 class InterviewExceptionEntry:
     """Class to record an exception that occurred during the interview."""
 
@@ -69,8 +70,8 @@ class InterviewExceptionEntry:
 
         >>> entry = InterviewExceptionEntry.example()
         """
-        from ..questions import QuestionFreeText
         from ..language_models import LanguageModel
+        from ..questions import QuestionFreeText
 
         m = LanguageModel.example(test_model=True)
         q = QuestionFreeText.example(exception_to_throw=ValueError)
@@ -128,12 +129,11 @@ class InterviewExceptionEntry:
 
     @property
     def html_traceback(self) -> str:
+        from io import StringIO
+
         from rich.console import Console
-        from rich.table import Table
         from rich.traceback import Traceback
 
-        from io import StringIO
-
         html_output = StringIO()
 
         console = Console(file=html_output, record=True)
@@ -218,7 +218,6 @@ class InterviewExceptionEntry:
         return cls(exception=exception, invigilator=invigilator)
 
 
-
 class InterviewExceptionCollection(UserDict):
     """A collection of exceptions that occurred during the interview."""
 
@@ -231,6 +230,14 @@ class InterviewExceptionCollection(UserDict):
         """Return a list of unfixed exceptions."""
         return {k: v for k, v in self.data.items() if k not in self.fixed}
 
+    def num_exceptions(self) -> int:
+        """Return the total number of exceptions."""
+        return sum(len(v) for v in self.data.values())
+
+    def num_unfixed_exceptions(self) -> int:
+        """Return the number of unfixed exceptions."""
+        return sum(len(v) for v in self.unfixed_exceptions().values())
+
     def num_unfixed(self) -> int:
         """Return a list of unfixed questions."""
         return len([k for k in self.data.keys() if k not in self.fixed])

edsl/interviews/exceptions.py

@@ -0,0 +1,79 @@
+"""
+Exceptions specific to the interviews module.
+
+This module defines custom exception classes for all interview-related errors
+in the EDSL framework, ensuring consistent error handling and user feedback.
+"""
+
+from ..base import BaseException
+
+
+class InterviewError(BaseException):
+    """
+    Base exception class for all interview-related errors.
+    
+    This is the parent class for all exceptions related to interview creation,
+    execution, and management in the EDSL framework.
+    
+    Examples:
+        ```python
+        # Usually not raised directly, but through subclasses
+        # For example, when accessing incomplete tasks
+        interview.get_completed_task("incomplete_task")  # Would raise InterviewTaskError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/interviews.html"
+
+
+class InterviewTaskError(InterviewError):
+    """
+    Exception raised when there's an issue with interview tasks.
+    
+    This exception occurs when:
+    - Attempting to access tasks that are not complete
+    - Task execution fails due to errors in the model response
+    - Task dependencies are not satisfied
+    
+    Examples:
+        ```python
+        # Attempting to access an incomplete task
+        interview.get_completed_task("incomplete_task")  # Raises InterviewTaskError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/interviews.html"
+
+
+class InterviewStatusError(InterviewError):
+    """
+    Exception raised when there's an issue with interview status management.
+    
+    This exception occurs when:
+    - Invalid operations are performed on interview status objects
+    - Incompatible status objects are combined
+    - Status tracking encounters inconsistent states
+    
+    Examples:
+        ```python
+        # Attempting to add incompatible status objects
+        status_dict + incompatible_object  # Raises InterviewStatusError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/interviews.html"
+
+
+class InterviewTokenError(InterviewError):
+    """
+    Exception raised when there's an issue with token estimation or usage.
+    
+    This exception occurs when:
+    - Invalid inputs are provided to token estimators
+    - Token calculation fails due to unsupported prompt types
+    - Token limits are exceeded during an interview
+    
+    Examples:
+        ```python
+        # Providing an invalid prompt type to token estimator
+        estimator.estimate_tokens(invalid_prompt)  # Raises InterviewTokenError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/token_usage.html"

edsl/interviews/interview.py

@@ -14,36 +14,38 @@ the individual API calls to language models, with support for caching and distri
 """
 
 from __future__ import annotations
+
 import asyncio
 import copy
 from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generator, List, Optional, Type
 
-from typing import Any, Type, List, Generator, Optional, TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..jobs.data_structures import RunConfig
+    from .interview_status_log import InterviewStatusLog
 
-# from jobs module 
-from ..jobs.data_structures import Answers
+# from jobs module
 from ..buckets import ModelBuckets
+from ..jobs.data_structures import Answers
 from ..jobs.fetch_invigilator import FetchInvigilator
-from ..utilities.utilities import dict_hash
 from ..surveys import Survey
+from ..utilities.utilities import dict_hash
 
-# from interviews module 
+# from interviews module
 from .answering_function import AnswerQuestionFunctionConstructor
+from .exception_tracking import InterviewExceptionCollection, InterviewExceptionEntry
+from .interview_status_dictionary import InterviewStatusDictionary
 from .interview_task_manager import InterviewTaskManager
 from .request_token_estimator import RequestTokenEstimator
-from .interview_status_dictionary import InterviewStatusDictionary
-from .exception_tracking import InterviewExceptionCollection, InterviewExceptionEntry
-
 
 if TYPE_CHECKING:
     from ..agents import Agent
-    from ..surveys import Survey
-    from ..scenarios import Scenario
     from ..caching import Cache
+    from ..invigilators import InvigilatorBase
     from ..language_models import LanguageModel
+    from ..scenarios import Scenario
+    from ..surveys import Survey
     from ..tokens import InterviewTokenUsage
-    from ..invigilators import InvigilatorBase
-    from ..key_management import KeyLookup
 
 
 @dataclass
@@ -277,15 +279,15 @@ class Interview:
             "iteration": self.iteration,
             "exceptions": {},
         }
-        
+
         # Optionally include exceptions
         if include_exceptions:
             d["exceptions"] = self.exceptions.to_dict()
-            
+
         # Include custom indices if present
         if hasattr(self, "indices"):
             d["indices"] = self.indices
-            
+
         return d
 
     @classmethod
@@ -304,9 +306,9 @@ class Interview:
         """
         # Import necessary classes
         from ..agents import Agent
-        from ..surveys import Survey
-        from ..scenarios import Scenario
         from ..language_models import LanguageModel
+        from ..scenarios import Scenario
+        from ..surveys import Survey
 
         # Deserialize each component
         agent = Agent.from_dict(d["agent"])
@@ -314,7 +316,7 @@ class Interview:
         scenario = Scenario.from_dict(d["scenario"])
         model = LanguageModel.from_dict(d["model"])
         iteration = d["iteration"]
-        
+
         # Prepare constructor parameters
         params = {
             "agent": agent,
@@ -323,19 +325,19 @@ class Interview:
             "model": model,
             "iteration": iteration,
         }
-        
+
         # Add optional indices if present
         if "indices" in d:
             params["indices"] = d["indices"]
-            
+
         # Create the interview instance
         interview = cls(**params)
-        
+
         # Restore exceptions if present
         if "exceptions" in d:
             exceptions = InterviewExceptionCollection.from_dict(d["exceptions"])
             interview.exceptions = exceptions
-            
+
         return interview
 
     def __hash__(self) -> int:
@@ -416,7 +418,7 @@ class Interview:
             >>> run_config.parameters.stop_on_exception = True
             >>> result, _ = asyncio.run(i.async_conduct_interview(run_config))
         """
-        from ..jobs import RunConfig, RunParameters, RunEnvironment
+        from ..jobs import RunConfig, RunEnvironment, RunParameters
 
         if run_config is None:
             run_config = RunConfig(
@@ -503,7 +505,7 @@ class Interview:
                     result = invigilator.get_failed_task_result(
                         failure_reason="Task was skipped."
                     )
-            except asyncio.CancelledError as e:  # task was cancelled
+            except asyncio.CancelledError:  # task was cancelled
                 result = invigilator.get_failed_task_result(
                     failure_reason="Task was cancelled."
                 )
@@ -520,7 +522,8 @@ class Interview:
 
         for task, invigilator in zip(tasks, invigilators):
             if not task.done():
-                raise ValueError(f"Task {task.get_name()} is not done.")
+                from edsl.interviews.exceptions import InterviewTaskError
+                raise InterviewTaskError(f"Task {task.get_name()} is not done.")
 
             yield handle_task(task, invigilator)
 
@@ -608,9 +611,9 @@ class Interview:
             True
         """
         from ..agents import Agent
-        from ..surveys import Survey
-        from ..scenarios import Scenario
         from ..language_models import LanguageModel
+        from ..scenarios import Scenario
+        from ..surveys import Survey
 
         # Define a simple direct answering method that always returns "yes"
         def f(self, question, scenario):
@@ -622,12 +625,12 @@ class Interview:
         survey = Survey.example()
         scenario = Scenario.example()
         model = LanguageModel.example()
-        
+
         # If we want an interview that throws exceptions, configure it accordingly
         if throw_exception:
             model = LanguageModel.example(test_model=True, throw_exception=True)
             agent = Agent.example()  # Without direct answering method
-            
+
         # Create and return the interview
         return Interview(agent=agent, survey=survey, scenario=scenario, model=model)
 

edsl/interviews/interview_status_dictionary.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
+
 from collections import UserDict
-from typing import Union, Dict
+from typing import Dict, Union
 
 from ..tasks.task_status_enum import TaskStatus, get_enum_from_string
 
@@ -26,7 +27,8 @@ class InterviewStatusDictionary(UserDict):
     ) -> "InterviewStatusDictionary":
         """Adds two InterviewStatusDictionaries together."""
         if not isinstance(other, InterviewStatusDictionary):
-            raise ValueError(f"Can't add {type(other)} to InterviewStatusDictionary")
+            from edsl.interviews.exceptions import InterviewStatusError
+            raise InterviewStatusError(f"Can't add {type(other)} to InterviewStatusDictionary")
         new_dict = {}
         for key in self.keys():
             new_dict[key] = self[key] + other[key]

edsl/interviews/interview_status_log.py

@@ -2,6 +2,7 @@ from collections import UserDict
 
 from ..tasks.task_status_enum import TaskStatus, status_colors
 
+
 class InterviewStatusLog(UserDict):
     """A dictionary of TaskStatusLog objects.
 
@@ -50,8 +51,8 @@ class InterviewStatusLog(UserDict):
     def visualize(self, num_periods: int = 10) -> None:
         """Visualize the status matrix with outlined squares."""
         import matplotlib.pyplot as plt
-        from matplotlib.colors import ListedColormap
         import numpy as np
+        from matplotlib.colors import ListedColormap
         from matplotlib.patches import Rectangle
 
         # Define your custom colormap

edsl/interviews/interview_task_manager.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
+
 import asyncio
-from typing import Any, Type, List, Generator, Optional, Union, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from ..questions import QuestionBase
     from ..tokens import InterviewTokenUsage
-    from . import InterviewStatusDictionary
-    from . import InterviewStatusLog
+    from . import InterviewStatusDictionary, InterviewStatusLog
 
 
 class InterviewTaskManager:

edsl/interviews/request_token_estimator.py

@@ -1,6 +1,7 @@
 from ..jobs.fetch_invigilator import FetchInvigilator
 from ..scenarios import FileStore
 
+
 class RequestTokenEstimator:
     """Estimate the number of tokens that will be required to run the focal task."""
 
@@ -25,7 +26,8 @@ class RequestTokenEstimator:
                     if isinstance(file, FileStore):
                         file_tokens += file.size * 0.25
             else:
-                raise ValueError(f"Prompt is of type {type(prompt)}")
+                from edsl.interviews.exceptions import InterviewTokenError
+                raise InterviewTokenError(f"Prompt is of type {type(prompt)}")
         return len(combined_text) / 4.0 + file_tokens
 
 

edsl/interviews/statistics.py

@@ -1,6 +1,5 @@
 from collections import UserDict
-from typing import Literal, List, Type, DefaultDict
-from collections import UserDict
+from typing import DefaultDict
 
 from ..tokens import InterviewTokenUsage
 
@@ -22,7 +21,7 @@ class InterviewStatistic(UserDict):
         >>> InterviewStatistic._format_number(1000, 1, "sec.")
         '1,000.0 sec.'
         """
-        if type(number) == str:
+        if isinstance(number, str):
             return number
         else:
             return f"{number:,.{digits}f}" + " " + units

edsl/invigilators/__init__.py

@@ -35,4 +35,10 @@ from .invigilator_base import InvigilatorBase
 from .invigilators import InvigilatorFunctional
 from .prompt_constructor import PromptConstructor
 
-__all_ = []
+__all__ = [
+    'InvigilatorAI',
+    'InvigilatorHuman',
+    'InvigilatorBase',
+    'InvigilatorFunctional',
+    'PromptConstructor'
+]

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 ..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 edsl.invigilators.exceptions import InvigilatorNotImplementedError
+            raise InvigilatorNotImplementedError("encoded_image not implemented")
 
         if "files_list" in prompts:
             params["files_list"] = prompts["files_list"]