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

edsl/results/results_selector.py

@@ -106,7 +106,7 @@ class Selector:
             new_data = self._fetch_data(to_fetch)
         except ResultsColumnNotFoundError as e:
             # Check is_notebook with explicit import to ensure mock works
-            from edsl.utilities import is_notebook as is_notebook_check
+            from ..utilities import is_notebook as is_notebook_check
             if is_notebook_check():
                 print("Error:", e, file=sys.stderr)
                 return None
@@ -114,7 +114,7 @@ class Selector:
                 raise e
                 
         # Import Dataset here to avoid circular import issues
-        from edsl.dataset import Dataset
+        from ..dataset import Dataset
         return Dataset(new_data)
 
     def _normalize_columns(self, columns: Union[str, List[str]]) -> Tuple[str, ...]:

edsl/scenarios/construct_download_link.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import os
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Optional, List
 
 if TYPE_CHECKING:
     from ..display import HTML
@@ -104,8 +104,8 @@ class ConstructDownloadLink:
 
     def create_multiple_links(
         self,
-        files: list[FileStore],
-        custom_filenames: Optional[list[str | None]] = None,
+        files: List["FileStore"],
+        custom_filenames: Optional[List[Optional[str]]] = None,
         style: Optional[dict] = None,
     ) -> HTML:
         """Create multiple download links in a horizontal layout.

edsl/scenarios/scenario.py

@@ -96,8 +96,7 @@ class Scenario(Base, UserDict):
                 data = dict(data)
             except Exception as e:
                 raise ScenarioError(
-                    f"You must pass in a dictionary to initialize a Scenario. You passed in {data}",
-                    "Exception message:" + str(e),
+                    f"You must pass in a dictionary to initialize a Scenario. You passed in {data}" +   "Exception message:" + str(e),
                 )
 
         super().__init__()

edsl/scenarios/scenario_list.py

@@ -31,7 +31,6 @@ import warnings
 import csv
 import random
 import os
-import glob
 from io import StringIO
 import inspect
 from collections import UserList, defaultdict
@@ -488,7 +487,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         if isinstance(other, Scenario):
             other = ScenarioList([other])
         elif not isinstance(other, ScenarioList):
-            raise TypeError(f"Cannot multiply ScenarioList with {type(other)}")
+            from .exceptions import TypeScenarioError
+            raise TypeScenarioError(f"Cannot multiply ScenarioList with {type(other)}")
 
         new_sl = []
         for s1, s2 in list(product(self, other)):
@@ -599,7 +599,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                 # Convert to a set (removes duplicates)
                 new_scenario[field_name] = set(values)
             else:
-                raise ValueError(f"Invalid output_type: {output_type}. Must be 'string', 'list', or 'set'.")
+                from .exceptions import ValueScenarioError
+                raise ValueScenarioError(f"Invalid output_type: {output_type}. Must be 'string', 'list', or 'set'.")
                 
             new_scenarios.append(new_scenario)
 
@@ -895,11 +896,13 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         cls,
         path: Optional[str] = None,
         recursive: bool = False,
+        key_name: str = "content",
     ) -> "ScenarioList":
-        """Create a ScenarioList of FileStore objects from files in a directory.
+        """Create a ScenarioList of Scenario objects from files in a directory.
         
-        This method scans a directory and creates a FileStore object for each file found,
-        optionally filtering files based on a wildcard pattern. If no path is provided,
+        This method scans a directory and creates a Scenario object for each file found,
+        where each Scenario contains a FileStore object under the specified key.
+        Optionally filters files based on a wildcard pattern. If no path is provided,
         the current working directory is used.
         
         Args:
@@ -910,25 +913,27 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                  - "/path/to/directory/*.py" - scans only Python files in the directory
                  - "*.txt" - scans only text files in the current working directory
             recursive: Whether to scan subdirectories recursively. Defaults to False.
+            key_name: The key to use for the FileStore object in each Scenario. Defaults to "content".
             
         Returns:
-            A ScenarioList containing FileStore objects for all matching files.
+            A ScenarioList containing Scenario objects for all matching files, where each Scenario
+            has a FileStore object under the specified key.
             
         Raises:
             FileNotFoundError: If the specified directory does not exist.
             
         Examples:
-            # Get all files in the current directory
+            # Get all files in the current directory with default key "content"
             sl = ScenarioList.from_directory()
             
-            # Get all Python files in a specific directory
-            sl = ScenarioList.from_directory('*.py')
+            # Get all Python files in a specific directory with custom key "python_file"
+            sl = ScenarioList.from_directory('*.py', key_name="python_file")
             
             # Get all image files in the current directory
-            sl = ScenarioList.from_directory('*.png')
+            sl = ScenarioList.from_directory('*.png', key_name="image")
             
             # Get all files recursively including subdirectories
-            sl = ScenarioList.from_directory(recursive=True)
+            sl = ScenarioList.from_directory(recursive=True, key_name="document")
         """
         # Handle default case - use current directory
         if path is None:
@@ -973,7 +978,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                 
         # Ensure directory exists
         if not os.path.isdir(directory_path):
-            raise FileNotFoundError(f"Directory not found: {directory_path}")
+            from .exceptions import FileNotFoundScenarioError
+            raise FileNotFoundScenarioError(f"Directory not found: {directory_path}")
         
         # Create a DirectoryScanner for the directory
         scanner = DirectoryScanner(directory_path)
@@ -1001,7 +1007,10 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
             example_suffix=example_suffix
         )
         
-        return cls(file_stores)
+        # Convert FileStore objects to Scenario objects with the specified key
+        scenarios = [Scenario({key_name: file_store}) for file_store in file_stores]
+        
+        return cls(scenarios)
                 
     @classmethod
     def from_list(
@@ -1262,7 +1271,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         import sqlite3
 
         if table is None and sql_query is None:
-            raise ValueError("Either table or sql_query must be provided")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError("Either table or sql_query must be provided")
 
         try:
             with sqlite3.connect(filepath) as conn:
@@ -1328,7 +1338,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         if "/edit" in url:
             doc_id = url.split("/d/")[1].split("/edit")[0]
         else:
-            raise ValueError("Invalid Google Doc URL format.")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError("Invalid Google Doc URL format.")
 
         export_url = f"https://docs.google.com/document/d/{doc_id}/export?format=docx"
 
@@ -1532,7 +1543,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                 print("The Excel file contains multiple sheets:")
                 for name in all_sheets.keys():
                     print(f"- {name}")
-                raise ValueError("Please provide a sheet name to load data from.")
+                from .exceptions import ValueScenarioError
+                raise ValueScenarioError("Please provide a sheet name to load data from.")
             else:
                 # If there is only one sheet, use it
                 sheet_name = list(all_sheets.keys())[0]
@@ -1587,7 +1599,8 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         if "/edit" in url:
             sheet_id = url.split("/d/")[1].split("/edit")[0]
         else:
-            raise ValueError("Invalid Google Sheet URL format.")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError("Invalid Google Sheet URL format.")
 
         export_url = (
             f"https://docs.google.com/spreadsheets/d/{sheet_id}/export?format=xlsx"
@@ -1673,14 +1686,16 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                             file_obj = None
                 
                 if file_obj is None:
-                    raise ValueError(f"Could not decode file {source} with any of the attempted encodings. Original error: {last_exception}")
+                    from .exceptions import ValueScenarioError
+                    raise ValueScenarioError(f"Could not decode file {source} with any of the attempted encodings. Original error: {last_exception}")
 
             reader = csv.reader(file_obj, delimiter=delimiter)
             try:
                 header = next(reader)
                 observations = [Scenario(dict(zip(header, row))) for row in reader]
             except StopIteration:
-                raise ValueError(f"File {source} appears to be empty or has an invalid format")
+                from .exceptions import ValueScenarioError
+                raise ValueScenarioError(f"File {source} appears to be empty or has an invalid format")
 
         finally:
             if file_obj:
@@ -1996,13 +2011,16 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         import string
         
         if num_options < 2:
-            raise ValueError("num_options must be at least 2")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError("num_options must be at least 2")
         
         if num_options > len(self):
-            raise ValueError(f"num_options ({num_options}) cannot exceed the number of scenarios ({len(self)})")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError(f"num_options ({num_options}) cannot exceed the number of scenarios ({len(self)})")
         
         if use_alphabet and num_options > 26:
-            raise ValueError("When using alphabet labels, num_options cannot exceed 26 (the number of letters in the English alphabet)")
+            from .exceptions import ValueScenarioError
+            raise ValueScenarioError("When using alphabet labels, num_options cannot exceed 26 (the number of letters in the English alphabet)")
         
         # Convert each scenario to a dictionary
         scenario_dicts = [scenario.to_dict(add_edsl_version=False) for scenario in self]

edsl/surveys/survey_css.py

@@ -1,5 +1,5 @@
 from typing import Optional
-from edsl.utilities.remove_edsl_version import remove_edsl_version
+from ..utilities.remove_edsl_version import remove_edsl_version
 
 
 class CSSRuleMeta(type):
@@ -73,7 +73,7 @@ class CSSRule(metaclass=CSSRuleMeta):
         d = {"selector": self.selector, "properties": self.properties}
 
         if add_esl_version:
-            from edsl import __version__
+            from .. import __version__
 
             d["edsl_version"] = __version__
             d["edsl_class_name"] = self.__class__.__name__
@@ -233,7 +233,7 @@ class SurveyCSS:
         """
         d = {"rules": [rule.to_dict() for rule in self.rules.values()]}
         if add_edsl_version:
-            from edsl import __version__
+            from .. import __version__
 
             d["edsl_version"] = __version__
             d["edsl_class_name"] = self.__class__.__name__

edsl/surveys/survey_simulator.py

@@ -58,7 +58,8 @@ class Simulator:
 
             if num_passes > 100:
                 print("Too many passes.")
-                raise Exception("Too many passes.")
+                from .exceptions import SurveyError
+                raise SurveyError("Too many passes.")
         return self.survey.answers
 
     def create_agent(self) -> "Agent":

edsl/tasks/__init__.py

@@ -26,9 +26,29 @@ For most users, this module works behind the scenes, but understanding it can
 be helpful when debugging or optimizing complex EDSL workflows.
 """
 
-__all__ = ['TaskHistory', 'QuestionTaskCreator', 'TaskCreators', 'TaskStatus', 'TaskStatusDescriptor']
+__all__ = [
+    'TaskHistory', 
+    'QuestionTaskCreator', 
+    'TaskCreators', 
+    'TaskStatus', 
+    'TaskStatusDescriptor',
+    'TaskError',
+    'TaskStatusError',
+    'TaskExecutionError',
+    'TaskDependencyError',
+    'TaskResourceError',
+    'TaskHistoryError'
+]
 
 from .task_history import TaskHistory
 from .question_task_creator import QuestionTaskCreator
 from .task_creators import TaskCreators
-from .task_status_enum import TaskStatus, TaskStatusDescriptor
+from .task_status_enum import TaskStatus, TaskStatusDescriptor
+from .exceptions import (
+    TaskError,
+    TaskStatusError,
+    TaskExecutionError,
+    TaskDependencyError,
+    TaskResourceError,
+    TaskHistoryError
+)

edsl/tasks/exceptions.py

@@ -0,0 +1,72 @@
+"""
+This module defines the exception hierarchy for the tasks module.
+
+All exceptions related to task creation, execution, and management are defined here.
+These exceptions provide detailed error information for debugging and error reporting.
+"""
+
+from ..base import BaseException
+
+
+class TaskError(BaseException):
+    """
+    Base exception for all tasks-related errors.
+    
+    This is the parent class for all exceptions raised within the tasks module.
+    It inherits from BaseException to ensure proper error tracking and reporting.
+    """
+    pass
+
+
+class TaskStatusError(TaskError):
+    """
+    Raised when a task encounters an invalid status transition.
+    
+    This exception is raised when a task attempts to transition to an invalid state
+    based on its current state, such as trying to set a completed task to running.
+    
+    Attributes:
+        current_status: The current status of the task
+        attempted_status: The status that could not be set
+    """
+    pass
+
+
+class TaskExecutionError(TaskError):
+    """
+    Raised when a task encounters an error during execution.
+    
+    This is a general exception for errors that occur while a task is running,
+    not specific to dependency resolution or resource allocation.
+    """
+    pass
+
+
+class TaskDependencyError(TaskError):
+    """
+    Raised when there is an issue with task dependencies.
+    
+    This exception is raised for dependency-related issues, such as circular
+    dependencies or errors in dependent tasks.
+    """
+    pass
+
+
+class TaskResourceError(TaskError):
+    """
+    Raised when a task cannot acquire necessary resources.
+    
+    This exception is used when a task cannot obtain required resources
+    such as tokens or request capacity, beyond normal waiting situations.
+    """
+    pass
+
+
+class TaskHistoryError(TaskError):
+    """
+    Raised for errors related to task history operations.
+    
+    This exception covers issues with recording, accessing, or analyzing
+    task execution history and logs.
+    """
+    pass

edsl/tasks/task_history.py

@@ -146,7 +146,7 @@ class TaskHistory(RepresentationMixin):
             "include_traceback": self.include_traceback,
         }
         if add_edsl_version:
-            from edsl import __version__
+            from .. import __version__
 
             d["edsl_version"] = __version__
             d["edsl_class_name"] = "TaskHistory"
@@ -406,7 +406,7 @@ class TaskHistory(RepresentationMixin):
         models_used = set([i.model.model for index, i in self._interviews.items()])
 
         from jinja2 import Environment
-        from edsl.utilities import TemplateLoader
+        from ..utilities import TemplateLoader
 
         env = Environment(loader=TemplateLoader("edsl", "templates/error_reporting"))
 
@@ -465,7 +465,7 @@ class TaskHistory(RepresentationMixin):
         """
         from IPython.display import display, HTML
         import os
-        from edsl.utilities.utilities import is_notebook
+        from ..utilities.utilities import is_notebook
 
         output = self.generate_html_report(css)
 

edsl/tokens/__init__.py

@@ -1,4 +1,30 @@
+"""
+The tokens module provides functionality for tracking and analyzing token usage in EDSL.
+
+This module implements classes for tracking and reporting token usage across various
+components of EDSL, particularly for language model calls. It supports aggregation,
+cost calculation, and reporting of token usage metrics.
+
+Key components:
+1. TokenUsage - Tracks prompt and completion tokens for a single operation
+2. InterviewTokenUsage - Aggregates token usage across an entire interview
+3. Exception classes for handling token-related errors
+
+The token tracking system helps with:
+- Cost estimation and billing
+- Resource utilization analysis
+- Cache effectiveness measurement
+- API quota management
+"""
+
 from .token_usage import TokenUsage
 from .interview_token_usage import InterviewTokenUsage
+from .exceptions import TokenError, TokenUsageError, TokenCostError
 
-__all__ = ["TokenUsage", "InterviewTokenUsage"]
+__all__ = [
+    "TokenUsage", 
+    "InterviewTokenUsage",
+    "TokenError",
+    "TokenUsageError", 
+    "TokenCostError"
+]

edsl/tokens/exceptions.py

@@ -0,0 +1,37 @@
+"""
+This module defines the exception hierarchy for the tokens module.
+
+All exceptions related to token usage tracking and cost calculations are defined here.
+"""
+
+from ..base import BaseException
+
+
+class TokenError(BaseException):
+    """
+    Base exception for all token-related errors.
+    
+    This is the parent class for all exceptions raised within the tokens module.
+    It inherits from BaseException to ensure proper error tracking and reporting.
+    """
+    pass
+
+
+class TokenUsageError(TokenError):
+    """
+    Raised when there is an error in token usage operations.
+    
+    This exception is raised for issues related to token usage tracking,
+    such as invalid token counts or incompatible token usage types.
+    """
+    pass
+
+
+class TokenCostError(TokenError):
+    """
+    Raised when there is an error in token cost calculations.
+    
+    This exception is used for issues with cost calculations, such as
+    missing or invalid pricing information.
+    """
+    pass

edsl/tokens/interview_token_usage.py

@@ -1,7 +1,8 @@
 from typing import Optional
 
 from .token_usage import TokenUsage
-from edsl.enums import TokenPricing
+from ..enums import TokenPricing
+from .exceptions import TokenUsageError
 
 class InterviewTokenUsage:
     """A class to represent the token usage of an interview."""
@@ -24,7 +25,7 @@ class InterviewTokenUsage:
         >>> usage3 = usage1 + usage2
         """
         if not isinstance(other, InterviewTokenUsage):
-            raise ValueError(f"Can't add {type(other)} to InterviewTokenSummary")
+            raise TokenUsageError(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,

edsl/tokens/token_usage.py

@@ -1,4 +1,5 @@
-from edsl.enums import TokenPricing
+from ..enums import TokenPricing
+from .exceptions import TokenUsageError, TokenCostError
 
 
 class TokenUsage:
@@ -15,9 +16,9 @@ class TokenUsage:
 
     def __add__(self, other):
         if not isinstance(other, TokenUsage):
-            raise ValueError(f"Can't add {type(other)} to InterviewTokenUsage")
+            raise TokenUsageError(f"Can't add {type(other)} to InterviewTokenUsage")
         if self.from_cache != other.from_cache:
-            raise ValueError("Can't add token usages from different sources")
+            raise TokenUsageError("Can't add token usages from different sources")
         return TokenUsage(
             from_cache=self.from_cache,
             prompt_tokens=self.prompt_tokens + other.prompt_tokens,

{edsl-0.1.50.dist-info → edsl-0.1.51.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.50
+Version: 0.1.51
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT