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

edsl/{jobs/tasks/TaskHistory.py → tasks/task_history.py}

@@ -1,11 +1,47 @@
-from typing import List, Optional
+"""
+This module provides the TaskHistory class for tracking and analyzing task execution history.
+
+The TaskHistory class maintains a record of all interviews conducted by EDSL, including
+their task execution histories, exceptions, and performance metrics. It supports rich
+visualization and reporting to help users understand task execution patterns and diagnose
+issues.
+"""
+
+from typing import List, Optional, Dict, Any, Union
 from io import BytesIO
 import base64
-from edsl.jobs.tasks.task_status_enum import TaskStatus
-from edsl.Base import RepresentationMixin
+import os
+import tempfile
+
+from .task_status_enum import TaskStatus
+from ..base import RepresentationMixin
 
 
 class TaskHistory(RepresentationMixin):
+    """
+    Records and analyzes the execution history of tasks across multiple interviews.
+    
+    The TaskHistory class serves as a central repository for tracking task execution
+    across multiple interviews. It provides methods for:
+    
+    1. Error Analysis - Collecting, categorizing, and reporting exceptions
+    2. Execution Visualization - Generating plots of task status over time
+    3. Performance Metrics - Calculating timing statistics for tasks
+    4. HTML Reports - Creating detailed interactive reports of execution
+    
+    This class is particularly useful for debugging complex interview workflows,
+    identifying performance bottlenecks, and understanding patterns in task execution.
+    It supports both interactive exploration in notebooks and standalone report
+    generation.
+    
+    Key features:
+    - Tracks exceptions with optional traceback storage
+    - Provides visualizations of task status transitions
+    - Generates interactive HTML reports with filtering and drill-down
+    - Computes statistics across interviews (by model, question type, etc.)
+    - Exports to various formats (HTML, notebook, etc.)
+    """
+    
     def __init__(
         self,
         interviews: List["Interview"] = None,
@@ -14,12 +50,16 @@ class TaskHistory(RepresentationMixin):
         interviews_with_exceptions_only: bool = False,
     ):
         """
-        The structure of a TaskHistory exception
-
-        [Interview.exceptions, Interview.exceptions, Interview.exceptions, ...]
-
-        >>> _ = TaskHistory.example()
-        ...
+        Initialize a TaskHistory to track execution across multiple interviews.
+        
+        Parameters:
+            interviews: List of Interview objects to track
+            include_traceback: Whether to include full exception tracebacks
+            max_interviews: Maximum number of interviews to display in reports
+            interviews_with_exceptions_only: If True, only track interviews with exceptions
+        
+        Example:
+            >>> _ = TaskHistory.example()  # Create a sample TaskHistory
         """
         self.interviews_with_exceptions_only = interviews_with_exceptions_only
         self._interviews = {}
@@ -34,10 +74,8 @@ class TaskHistory(RepresentationMixin):
         }
         self.max_interviews = max_interviews
 
-        # self.total_interviews = interviews
         self.include_traceback = include_traceback
 
-        # self._interviews = {index: i for index, i in enumerate(self.total_interviews)}
         self.max_interviews = max_interviews
 
     def add_interview(self, interview: "Interview"):
@@ -51,9 +89,8 @@ class TaskHistory(RepresentationMixin):
     @classmethod
     def example(cls):
         """ """
-        from edsl.jobs.interviews.Interview import Interview
-
-        from edsl.jobs.Jobs import Jobs
+        from ..interviews import Interview
+        from ..jobs import Jobs
 
         j = Jobs.example(throw_exception_probability=1, test_model=True)
 
@@ -120,7 +157,7 @@ class TaskHistory(RepresentationMixin):
         if data is None:
             return cls([], include_traceback=False)
 
-        from edsl.jobs.interviews.Interview import Interview
+        from ..interviews import Interview
 
         interviews = [Interview.from_dict(i) for i in data["interviews"]]
         return cls(interviews, include_traceback=data["include_traceback"])
@@ -273,15 +310,15 @@ class TaskHistory(RepresentationMixin):
                 for exception in exceptions:
                     key = (
                         exception.exception.__class__.__name__,  # Exception type
-                        interview.model._inference_service_,    # Service
-                        interview.model.model,                  # Model
-                        question_name                           # Question name
+                        interview.model._inference_service_,  # Service
+                        interview.model.model,  # Model
+                        question_name,  # Question name
                     )
                     if key not in exceptions_table:
                         exceptions_table[key] = 0
                     exceptions_table[key] += 1
         return exceptions_table
-    
+
     @property
     def exceptions_by_type(self) -> dict:
         """Return a dictionary of exceptions tallied by type."""
@@ -342,27 +379,6 @@ class TaskHistory(RepresentationMixin):
         }
         return sorted_exceptions_by_question_name
 
-    # @property
-    # def exceptions_by_model(self) -> dict:
-    #     """Return a dictionary of exceptions tallied by model and question name."""
-    #     exceptions_by_model = {}
-    #     for interview in self.total_interviews:
-    #         model = interview.model.model
-    #         service = interview.model._inference_service_
-    #         if (service, model) not in exceptions_by_model:
-    #             exceptions_by_model[(service, model)] = 0
-    #         if interview.exceptions != {}:
-    #             exceptions_by_model[(service, model)] += len(interview.exceptions)
-
-    #     # sort the exceptions by model
-    #     sorted_exceptions_by_model = {
-    #         k: v
-    #         for k, v in sorted(
-    #             exceptions_by_model.items(), key=lambda item: item[1], reverse=True
-    #         )
-    #     }
-    #     return sorted_exceptions_by_model
-
     @property
     def exceptions_by_model(self) -> dict:
         """Return a dictionary of exceptions tallied by model and question name."""
@@ -389,7 +405,7 @@ class TaskHistory(RepresentationMixin):
         models_used = set([i.model.model for index, i in self._interviews.items()])
 
         from jinja2 import Environment, FileSystemLoader
-        from edsl.TemplateLoader import TemplateLoader
+        from edsl.utilities import TemplateLoader
 
         env = Environment(loader=TemplateLoader("edsl", "templates/error_reporting"))
 
@@ -417,12 +433,35 @@ class TaskHistory(RepresentationMixin):
     def html(
         self,
         filename: Optional[str] = None,
-        return_link=False,
-        css=None,
-        cta="<br><span style='font-size: 18px; font-weight: medium-bold; text-decoration: underline;'>Click to open the report in a new tab</span><br><br>",
-        open_in_browser=False,
-    ):
-        """Return an HTML report."""
+        return_link: bool = False,
+        css: Optional[str] = None,
+        cta: str = "<br><span style='font-size: 18px; font-weight: medium-bold; text-decoration: underline;'>Click to open the report in a new tab</span><br><br>",
+        open_in_browser: bool = False,
+    ) -> Optional[str]:
+        """
+        Generate and display an interactive HTML report of task execution.
+        
+        This method creates a comprehensive HTML report showing task execution details,
+        exceptions, timing information, and statistics across all tracked interviews.
+        In notebook environments, it displays an embedded preview with a link to open
+        the full report in a new tab.
+        
+        Parameters:
+            filename: Path to save the HTML report (if None, a temporary file is created)
+            return_link: If True, return the path to the saved HTML file
+            css: Custom CSS to apply to the report (if None, uses default styling)
+            cta: HTML for the "Call to Action" link text
+            open_in_browser: If True, automatically open the report in the default browser
+            
+        Returns:
+            If return_link is True, returns the path to the saved HTML file; otherwise None
+            
+        Notes:
+            - In Jupyter notebooks, displays an embedded preview with a link
+            - In terminal environments, saves the file and prints its location
+            - The report includes interactive elements for filtering and drill-down
+            - Exception details, status transitions, and timing are all included
+        """
         from IPython.display import display, HTML
         import tempfile
         import os

edsl/{jobs/tasks → tasks}/task_status_enum.py

@@ -5,7 +5,27 @@ import time
 
 
 class TaskStatus(enum.Enum):
-    "These are the possible states a task can be in."
+    """
+    Enumeration of possible states for a task in the EDSL task system.
+    
+    Each task moves through various states during its lifecycle, from creation 
+    to completion. This enum defines all possible states to track task progress 
+    and diagnose issues.
+    
+    States:
+        NOT_STARTED: Initial state - task has been created but not yet started
+        WAITING_FOR_DEPENDENCIES: Task is waiting for prerequisite tasks to complete
+        CANCELLED: Task was explicitly cancelled by the user or system
+        PARENT_FAILED: Task cannot run because a dependency task failed
+        WAITING_FOR_REQUEST_CAPACITY: Task is waiting due to API rate limits
+        WAITING_FOR_TOKEN_CAPACITY: Task is waiting due to token usage limits
+        API_CALL_IN_PROGRESS: Task is actively executing an API call
+        SUCCESS: Task completed successfully
+        FAILED: Task encountered an error and failed to complete
+    
+    These states are used throughout EDSL to track task progress, generate
+    visualizations, and provide detailed error reports.
+    """
     NOT_STARTED = enum.auto()
     WAITING_FOR_DEPENDENCIES = enum.auto()
     CANCELLED = enum.auto()
@@ -18,30 +38,80 @@ class TaskStatus(enum.Enum):
 
 
 class TaskStatusLogEntry(UserDict):
-    def __init__(self, log_time, value):
+    """
+    A timestamped record of a task's status change.
+    
+    This class records both the time when a task's status changed and the new status value.
+    It uses the UserDict interface for convenient dictionary-like access while maintaining
+    the structured nature of status log entries.
+    
+    Attributes:
+        log_time: The time (from time.monotonic()) when the status change occurred
+        value: The new TaskStatus value
+    """
+    def __init__(self, log_time: float, value: TaskStatus):
+        """
+        Create a new task status log entry.
+        
+        Parameters:
+            log_time: The time when this status change occurred (from time.monotonic())
+            value: The TaskStatus value that the task transitioned to
+        """
         self.data = {"log_time": log_time, "value": value}
         super().__init__(self.data)
 
 
 class TaskStatusDescriptor:
-    "The descriptor ensures that the task status is always an instance of the TaskStatus enum."
+    """
+    A descriptor that enforces TaskStatus type safety and logs status changes.
+    
+    This descriptor is used to create task_status properties in task-related classes.
+    It performs two key functions:
+    
+    1. Type Enforcement: Ensures that task_status is always set to a valid TaskStatus enum
+    2. Logging: Automatically adds entries to the task's status_log when status changes
+    
+    By using this descriptor, EDSL ensures consistent status tracking across all tasks
+    while providing a rich history of status changes for debugging and visualization.
+    """
 
     def __init__(self):
+        """Initialize the descriptor with a null status value."""
         self._task_status = None
 
     def __get__(self, instance, owner):
+        """Return the current task status."""
         return self._task_status
 
     def __set__(self, instance, value):
-        """Ensure that the value is an instance of TaskStatus."""
+        """
+        Set a new task status and record the change in the status log.
+        
+        This method enforces that the value is a valid TaskStatus enum and
+        automatically adds an entry to the instance's status_log (if it exists).
+        
+        Parameters:
+            instance: The object instance that owns this descriptor
+            value: The new TaskStatus value to set
+            
+        Raises:
+            ValueError: If value is not an instance of TaskStatus enum
+        """
         if not isinstance(value, TaskStatus):
             raise ValueError("Value must be an instance of TaskStatus enum")
+        
+        # Record the current time for the status change
         t = time.monotonic()
+        
+        # Add an entry to the status log if the instance has one
         if hasattr(instance, "status_log"):
             instance.status_log.append(TaskStatusLogEntry(t, value))
+            
+        # Update the actual status value
         self._task_status = value
 
     def __delete__(self, instance):
+        """Reset the task status to None when deleted."""
         self._task_status = None
 
 
@@ -69,9 +139,23 @@ def get_enum_from_string(str_key):
 
 
 class InterviewTaskLogDict(UserDict):
-    """A dictionary of TaskStatusLog objects.
-
-    The key is the name of the task.
+    """
+    A collection of task status logs for all tasks in an interview.
+    
+    This dictionary-like object maps task names to their individual TaskStatusLog objects,
+    providing methods to analyze task execution across an entire interview. It supports
+    calculating timing metrics, generating status matrices for visualization, and 
+    rendering graphical representations of task execution flow.
+    
+    The InterviewTaskLogDict is a key component in EDSL's task monitoring system,
+    enabling both debugging of individual interviews and aggregate analysis of
+    execution patterns.
+    
+    Key features:
+    - Temporal analysis (min/max execution times)
+    - Status matrix generation for visualization
+    - Visual representation of task status changes over time
+    - Color-coded status visualization
     """
 
     @property

edsl/tasks/task_status_log.py

@@ -0,0 +1,85 @@
+"""
+This module provides the TaskStatusLog class for tracking the status history of tasks.
+
+The TaskStatusLog class maintains an ordered list of status changes for a specific task,
+with timestamps and status values. This history allows for detailed analysis of task
+execution, including timing, state transitions, and status at any point in time.
+"""
+
+from collections import UserList
+from typing import List, Optional, Union
+
+from .task_status_enum import TaskStatus, TaskStatusLogEntry
+
+
+class TaskStatusLog(UserList):
+    """
+    An ordered history of status changes for a single task.
+    
+    This class extends UserList to provide a chronological record of all status changes
+    that a task undergoes during its lifecycle. Each entry in the list is a 
+    TaskStatusLogEntry object containing a timestamp and status value.
+    
+    The TaskStatusLog provides methods to analyze the timing of task execution and 
+    determine task status at any point in time. This information is valuable for
+    debugging, performance analysis, and visualization of task execution flow.
+    
+    Key features:
+    - Records all status transitions with timestamps
+    - Provides min/max execution time calculations
+    - Supports interpolation to determine status at any given time
+    - Used by visualization tools to render task execution timelines
+    """
+
+    @property
+    def min_time(self) -> float:
+        """
+        Get the timestamp of the first status change.
+        
+        Returns:
+            The timestamp (from time.monotonic()) of the earliest status entry
+            
+        Note:
+            This is typically when the task was first created and set to NOT_STARTED
+        """
+        return self[0]["log_time"]
+
+    @property
+    def max_time(self) -> float:
+        """
+        Get the timestamp of the last status change.
+        
+        Returns:
+            The timestamp (from time.monotonic()) of the most recent status entry
+            
+        Note:
+            This is typically when the task reached its final state (SUCCESS, FAILED, etc.)
+        """
+        return self[-1]["log_time"]
+
+    def status_at_time(self, t: float) -> TaskStatus:
+        """
+        Determine what status the task had at a specific point in time.
+        
+        This method interpolates between status log entries to determine the task's
+        status at any arbitrary time point. It searches for the first status change
+        that occurred after time t and returns the status that was active at that time.
+        
+        Parameters:
+            t: The timestamp to query (from time.monotonic())
+            
+        Returns:
+            The TaskStatus that was active at time t
+            
+        Note:
+            If t is after the last recorded status change, the final status is returned.
+            If t is before the first recorded status change, this method may not behave
+            as expected since it assumes ordered traversal through the log.
+            
+        TODO: 
+            Could re-factor with bisect to make this faster for large logs.
+        """
+        for entry in self:
+            if entry["log_time"] > t:
+                return entry["value"]
+        return self[-1]["value"]

edsl/tokens/__init__.py

@@ -0,0 +1,2 @@
+from .token_usage import TokenUsage
+from .interview_token_usage import InterviewTokenUsage

edsl/tokens/interview_token_usage.py

@@ -0,0 +1,53 @@
+from typing import Optional
+
+from .token_usage import TokenUsage
+from edsl.enums import TokenPricing
+
+class InterviewTokenUsage:
+    """A class to represent the token usage of an interview."""
+
+    def __init__(
+        self, new_token_usage: Optional[TokenUsage] = None, cached_token_usage: Optional[TokenUsage] = None
+    ):
+        """Initialize the InterviewTokenUsage.
+
+        >>> usage = InterviewTokenUsage()
+        """
+        self.new_token_usage = new_token_usage or TokenUsage(from_cache=False)
+        self.cached_token_usage = cached_token_usage or TokenUsage(from_cache=True)
+
+    def __add__(self, other: "InterviewTokenUsage") -> "InterviewTokenUsage":
+        """Add two InterviewTokenUsage objects together.
+
+        >>> usage1 = InterviewTokenUsage()
+        >>> usage2 = InterviewTokenUsage()
+        >>> usage3 = usage1 + usage2
+        """
+        if not isinstance(other, InterviewTokenUsage):
+            raise ValueError(f"Can't add {type(other)} to InterviewTokenSummary")
+        return InterviewTokenUsage(
+            new_token_usage=self.new_token_usage + other.new_token_usage,
+            cached_token_usage=self.cached_token_usage + other.cached_token_usage,
+        )
+
+    def __repr__(self):
+        return f"InterviewTokenUsage(new_token_usage={self.new_token_usage}, cached_token_usage={self.cached_token_usage})"
+
+    def cost(self, prices: TokenPricing) -> float:
+        """Return the cost of the new and cached token usage.
+
+        >>> usage = InterviewTokenUsage()
+        >>> usage.cost(TokenPricing.example())
+        0.0
+        """
+        return self.new_token_usage.cost(prices)
+
+    def saved(self, prices: TokenPricing) -> float:
+        """Return the saved cost of the cached token usage.
+        """
+        return self.cached_token_usage.cost(prices)
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/utilities/PrettyList.py

@@ -1,5 +1,5 @@
 from collections import UserList
-from edsl.results.Dataset import Dataset
+from ..dataset import Dataset
 
 class Markkdown:
 

edsl/utilities/SystemInfo.py

@@ -1,28 +1,31 @@
 """Module to store system information."""
 
-from dataclasses import dataclass
-import getpass
-import platform
-import pkg_resources
+# This module is not currently used by any part of the codebase.
+# Keeping it commented out for potential future use.
 
+# from dataclasses import dataclass
+# import getpass
+# import platform
+# import pkg_resources
 
-@dataclass
-class SystemInfo:
-    """Dataclass to store system information."""
 
-    username: str
-    system_info: str
-    release_info: str
-    package_name: str
-    package_version: str
+# @dataclass
+# class SystemInfo:
+#     """Dataclass to store system information."""
 
-    def __init__(self, package_name: str):
-        """Initialize the dataclass with system."""
-        self.username = getpass.getuser()
-        self.system_info = platform.system()
-        self.release_info = platform.release()
-        self.package_name = package_name
-        try:
-            self.package_version = pkg_resources.get_distribution(package_name).version
-        except pkg_resources.DistributionNotFound:
-            self.package_version = "Not installed"
+#     username: str
+#     system_info: str
+#     release_info: str
+#     package_name: str
+#     package_version: str
+
+#     def __init__(self, package_name: str):
+#         """Initialize the dataclass with system."""
+#         self.username = getpass.getuser()
+#         self.system_info = platform.system()
+#         self.release_info = platform.release()
+#         self.package_name = package_name
+#         try:
+#             self.package_version = pkg_resources.get_distribution(package_name).version
+#         except pkg_resources.DistributionNotFound:
+#             self.package_version = "Not installed"

edsl/utilities/__init__.py

@@ -1,22 +1,30 @@
-# from edsl.utilities.interface import (
-#     print_dict_as_html_table,
-#     print_dict_with_rich,
-#     print_list_of_dicts_as_html_table,
-#     print_table_with_rich,
-#     print_public_methods_with_doc,
-#     print_list_of_dicts_as_markdown_table,
-# )
+# Core utilities - used across the codebase
+from .template_loader import TemplateLoader
+from .PrettyList import PrettyList
+from .restricted_python import create_restricted_function
+from .remove_edsl_version import remove_edsl_version
+from .ast_utilities import extract_variable_names
+
+# Functions from utilities.py
+from .utilities import (
+    clean_json,
+    dict_hash,
+    hash_value,
+    repair_json,
+    create_valid_var_name,
+    random_string,
+    shorten_string,
+    is_gzipped
+)
+
+# Decorator utilities
+from .decorators import sync_wrapper, jupyter_nb_handler
+
+# Standalone utilities
+from .is_notebook import is_notebook
+from .is_valid_variable_name import is_valid_variable_name
+from .naming_utilities import sanitize_string
+
+# Interface module - note: print_results_long is imported directly in results.py
+from .interface import print_results_long
 
-# from edsl.utilities.utilities import (
-#     create_valid_var_name,
-#     dict_to_html,
-#     hash_value,
-#     HTMLSnippet,
-#     is_notebook,
-#     is_gzipped,
-#     is_valid_variable_name,
-#     random_string,
-#     repair_json,
-#     shorten_string,
-#     time_all_functions,
-# )

edsl/utilities/gcp_bucket/__init__.py

@@ -0,0 +1,2 @@
+# GCP bucket utilities
+# This package is currently not being used