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

edsl/{jobs/interviews/InterviewStatusLog.py → interviews/interview_status_log.py}

@@ -1,7 +1,6 @@
 from collections import UserDict
 
-from edsl.jobs.tasks.task_status_enum import TaskStatus, status_colors
-
+from ..tasks.task_status_enum import TaskStatus, status_colors
 
 class InterviewStatusLog(UserDict):
     """A dictionary of TaskStatusLog objects.
@@ -10,14 +9,16 @@ class InterviewStatusLog(UserDict):
     """
 
     @property
-    def min_time(self):
+    def min_time(self) -> float:
+        """Return the minimum time of the status log."""
         return min([log.min_time for log in self.values()])
 
     @property
-    def max_time(self):
+    def max_time(self) -> float:
+        """Return the maximum time of the status log."""
         return max([log.max_time for log in self.values()])
 
-    def status_matrix(self, num_periods):
+    def status_matrix(self, num_periods: int) -> dict[str, list[TaskStatus]]:
         """Return a matrix of status values."""
         start_time = self.min_time
         end_time = self.max_time
@@ -28,7 +29,9 @@ class InterviewStatusLog(UserDict):
             status_matrix[task_name] = [log.status_at_time(t) for t in time_periods]
         return status_matrix
 
-    def numerical_matrix(self, num_periods):
+    def numerical_matrix(
+        self, num_periods: int
+    ) -> tuple[list[list[int]], dict[int, str]]:
         """Return a numerical matrix of status values."""
         status_dicts = self.status_matrix(num_periods)
 
@@ -44,7 +47,7 @@ class InterviewStatusLog(UserDict):
         index_to_names = {i: name for i, name in enumerate(status_dicts.keys())}
         return matrix, index_to_names
 
-    def visualize(self, num_periods=10):
+    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
@@ -90,3 +93,9 @@ class InterviewStatusLog(UserDict):
 
         # Show the plot
         plt.show()
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/{jobs/InterviewTaskManager.py → interviews/interview_task_manager.py}

@@ -3,18 +3,18 @@ import asyncio
 from typing import Any, Type, List, Generator, Optional, Union, TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from edsl.questions import QuestionBase
-    from edsl.jobs.tokens.InterviewTokenUsage import InterviewTokenUsage
-    from edsl.jobs.interviews.InterviewStatusDictionary import InterviewStatusDictionary
-    from edsl.jobs.interviews.InterviewStatusLog import InterviewStatusLog
+    from ..questions import QuestionBase
+    from ..tokens import InterviewTokenUsage
+    from . import InterviewStatusDictionary
+    from . import InterviewStatusLog
 
 
 class InterviewTaskManager:
     """Handles creation and management of interview tasks."""
 
     def __init__(self, survey, iteration=0):
-        from edsl.jobs.tasks.TaskCreators import TaskCreators
-        from edsl.jobs.interviews.InterviewStatusLog import InterviewStatusLog
+        from ..tasks import TaskCreators
+        from . import InterviewStatusLog
 
         self.survey = survey
         self.iteration = iteration
@@ -59,7 +59,7 @@ class InterviewTaskManager:
         model_buckets,
     ) -> asyncio.Task:
         """Create a single question task with its dependencies."""
-        from edsl.jobs.tasks.QuestionTaskCreator import QuestionTaskCreator
+        from ..tasks import QuestionTaskCreator
 
         task_creator = QuestionTaskCreator(
             question=question,
@@ -96,3 +96,8 @@ class InterviewTaskManager:
     def interview_status(self) -> "InterviewStatusDictionary":
         """Return a dictionary mapping task status codes to counts."""
         return self.task_creators.interview_status
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()

edsl/{jobs/RequestTokenEstimator.py → interviews/request_token_estimator.py}

@@ -1,5 +1,5 @@
-from edsl.jobs.FetchInvigilator import FetchInvigilator
-
+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."""
@@ -9,7 +9,6 @@ class RequestTokenEstimator:
 
     def __call__(self, question) -> float:
         """Estimate the number of tokens that will be required to run the focal task."""
-        from edsl.scenarios.FileStore import FileStore
 
         invigilator = FetchInvigilator(self.interview)(question=question)
 
@@ -28,3 +27,9 @@ class RequestTokenEstimator:
             else:
                 raise ValueError(f"Prompt is of type {type(prompt)}")
         return len(combined_text) / 4.0 + file_tokens
+
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/{jobs/interviews/InterviewStatistic.py → interviews/statistics.py}

@@ -1,19 +1,16 @@
-import asyncio
-from enum import Enum
+from collections import UserDict
 from typing import Literal, List, Type, DefaultDict
-from collections import UserDict, defaultdict
+from collections import UserDict
 
-from edsl.jobs.interviews.InterviewStatusDictionary import InterviewStatusDictionary
-from edsl.jobs.tokens.InterviewTokenUsage import InterviewTokenUsage
-from edsl.enums import pricing, TokenPricing
-from edsl.jobs.tasks.task_status_enum import TaskStatus
+from ..tokens import InterviewTokenUsage
 
 InterviewTokenUsageMapping = DefaultDict[str, InterviewTokenUsage]
 
-
 class InterviewStatistic(UserDict):
+    """A statistic for an interview."""
+
     @staticmethod
-    def _format_number(number, digits=0, units=""):
+    def _format_number(number, digits: int = 0, units: str = "") -> str:
         """Format a number.
 
         :param number: the number to format
@@ -31,7 +28,7 @@ class InterviewStatistic(UserDict):
             return f"{number:,.{digits}f}" + " " + units
 
     @property
-    def _pretty_name(self):
+    def _pretty_name(self) -> str:
         """Return a pretty name for the statistic.
 
         Example usage:
@@ -61,3 +58,32 @@ class InterviewStatistic(UserDict):
         )
 
         self.raw: dict = {self.name: self.value}
+
+
+class InterviewStatisticsCollection(UserDict):
+    """A collection of interview statistics."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.raw: dict = {}
+
+    def add_stat(self, statistic: InterviewStatistic) -> None:
+        """Add a statistic to the collection.
+
+        Each statistic is a dictionary with a single key-value pair.
+
+        Example usage:
+
+        >>> isc = InterviewStatisticsCollection()
+        >>> isc.add_stat(InterviewStatistic("elapsed_time", value=100, digits=1, units="sec."))
+        >>> isc.raw
+        {'elapsed_time': 100}
+        """
+        self.update(statistic)
+        self.raw.update(statistic.raw)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/invigilators/__init__.py

@@ -0,0 +1,38 @@
+"""
+The invigilators module handles the administration of questions to agents.
+
+An invigilator (from the Latin "to watch over") is responsible for administering
+questions to agents, managing the interaction between questions, language models,
+and agents, and validating responses. This module is a core part of EDSL's architecture
+for ensuring that questions are properly presented to agents and responses are
+appropriately processed.
+
+Technical architecture:
+- InvigilatorBase: Abstract base class defining the core interface for invigilators
+- PromptConstructor: Transforms questions, scenarios, and agent memory into prompts
+- QuestionTemplateReplacementsBuilder: Handles template variable substitution
+- PromptHelpers: Utilities for prompt construction and manipulation
+
+Invigilator implementations:
+- InvigilatorAI: Administers questions to AI agents via language models
+- InvigilatorHuman: Handles questions to be answered by human users
+- InvigilatorFunctional: Uses custom functions to generate responses
+
+This module is primarily intended for EDSL developers or advanced users who need
+to customize the question administration process. Most users interact with invigilators
+indirectly through the Survey, Question, and Jobs interfaces.
+
+Design considerations:
+- Separation of prompt construction from response handling
+- Support for different agents and response types
+- Asynchronous execution for efficient processing
+- Extensibility through the abstract base class
+"""
+
+from .invigilators import InvigilatorAI
+from .invigilators import InvigilatorHuman
+from .invigilator_base import InvigilatorBase
+from .invigilators import InvigilatorFunctional
+from .prompt_constructor import PromptConstructor
+
+__all_ = []