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

edsl/instructions/instruction.py

@@ -1,7 +1,10 @@
-from typing import Union, Optional, List, Generator, Dict
+from __future__ import annotations
 from ..utilities.remove_edsl_version import remove_edsl_version
 from ..base import RepresentationMixin
-#from ..surveys import Survey
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..surveys import Survey
 
 
 class Instruction(RepresentationMixin):
@@ -11,6 +14,7 @@ class Instruction(RepresentationMixin):
         self.name = name
         self.text = text
         self.preamble = preamble
+        self.pseudo_index = 0.0
 
     def __str__(self):
         return self.text

edsl/instructions/instruction_collection.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Dict, List, Generator, Union
+from typing import TYPE_CHECKING, Dict, List, Generator, Union, Tuple
 from collections import UserDict
 
 from .instruction import Instruction
@@ -40,12 +40,14 @@ class InstructionCollection(UserDict):
 
     def _entries_before(
         self, question_name
-    ) -> tuple[List[Instruction], List[ChangeInstruction]]:
+    ) -> Tuple[List[Instruction], List[ChangeInstruction]]:
         if question_name not in self.question_names:
-            raise ValueError(
+            from .exceptions import InstructionCollectionError
+            raise InstructionCollectionError(
                 f"Question name not found in the list of questions: got '{question_name}'; list is {self.question_names}"
             )
-        instructions, changes = [], []
+        instructions: List[Instruction] = []
+        changes: List[ChangeInstruction] = []
 
         index = self.question_index(question_name)
         for instruction in self.instruction_names_to_instruction.values():

edsl/instructions/instruction_handler.py

@@ -1,12 +1,13 @@
-from typing import TYPE_CHECKING
 from dataclasses import dataclass
 
 
+from typing import Dict, List, Any
+
 @dataclass
 class SeparatedComponents:
-    true_questions: list
-    instruction_names_to_instructions: dict
-    pseudo_indices: dict
+    true_questions: List[Any]
+    instruction_names_to_instructions: Dict[str, Any]
+    pseudo_indices: Dict[str, float]
 
 
 class InstructionHandler:
@@ -14,7 +15,7 @@ class InstructionHandler:
         self.survey = survey
 
     @staticmethod
-    def separate_questions_and_instructions(questions_and_instructions: list) -> tuple:
+    def separate_questions_and_instructions(questions_and_instructions: list) -> SeparatedComponents:
         """
         The 'pseudo_indices' attribute is a dictionary that maps question names to pseudo-indices
         that are used to order questions and instructions in the survey.
@@ -46,18 +47,12 @@ 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
-        from edsl.questions import QuestionBase
+        from ..questions import QuestionBase
 
-        true_questions = []
+        true_questions: List[QuestionBase] = []
         instruction_names_to_instructions = {}
 
         num_change_instructions = 0
@@ -70,7 +65,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 .exceptions import InstructionValueError
+                            raise InstructionValueError(
                                 f"ChangeInstruction {entry.name} references instruction {prior_instruction} which does not exist."
                             )
                 instructions_run_length += 1
@@ -83,7 +79,8 @@ class InstructionHandler:
                 instructions_run_length = 0
                 true_questions.append(entry)
             else:
-                raise ValueError(
+                from .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)
@@ -91,7 +92,7 @@ class InterviewExceptionEntry:
     def code(self, run=True):
         """Return the code to reproduce the exception."""
         lines = []
-        lines.append("from edsl import Question, Model, Scenario, Agent")
+        lines.append("from .. import Question, Model, Scenario, Agent")
 
         lines.append(f"q = {repr(self.invigilator.question)}")
         lines.append(f"scenario = {repr(self.invigilator.scenario)}")
@@ -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:
@@ -363,7 +365,7 @@ class Interview:
             bool: True if the interviews are equivalent, False otherwise
             
         Examples:
-            >>> from edsl.interviews import Interview
+            >>> from . import Interview
             >>> i = Interview.example()
             >>> d = i.to_dict()
             >>> i2 = Interview.from_dict(d)
@@ -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 .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:
@@ -29,7 +29,7 @@ class InterviewTaskManager:
         self, answer_func, token_estimator, model_buckets
     ) -> list[asyncio.Task]:
         """Create tasks for all questions with proper dependencies."""
-        tasks = []
+        tasks: list[asyncio.Task] = []
         for question in self.survey.questions:
             dependencies = self._get_task_dependencies(tasks, question)
             task = self._create_single_task(
@@ -40,7 +40,7 @@ class InterviewTaskManager:
                 model_buckets=model_buckets,
             )
             tasks.append(task)
-        return tuple(tasks)
+        return tasks
 
     def _get_task_dependencies(
         self, existing_tasks: list[asyncio.Task], question: "QuestionBase"

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,8 +26,10 @@ class RequestTokenEstimator:
                     if isinstance(file, FileStore):
                         file_tokens += file.size * 0.25
             else:
-                raise ValueError(f"Prompt is of type {type(prompt)}")
-        return len(combined_text) / 4.0 + file_tokens
+                from .exceptions import InterviewTokenError
+                raise InterviewTokenError(f"Prompt is of type {type(prompt)}")
+        result: float = len(combined_text) / 4.0 + file_tokens
+        return result
 
 
 

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, Union, Optional
 
 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
@@ -44,7 +43,7 @@ class InterviewStatistic(UserDict):
         value: float,
         digits: int = 0,
         units: str = "",
-        pretty_name: str = None,
+        pretty_name: Optional[str] = None,
     ):
         """Create a new InterviewStatistic object."""
         self.name = name

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'
+]