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

edsl/__init__.py

@@ -1,5 +1,7 @@
 import os
 import time
+import importlib
+import pkgutil
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT_DIR = os.path.dirname(BASE_DIR)
@@ -7,57 +9,126 @@ ROOT_DIR = os.path.dirname(BASE_DIR)
 from edsl.__version__ import __version__
 from edsl.config import Config, CONFIG
 
-__all__ = []
+# Initialize and expose logger
+from edsl import logger
+
+# Set up logger with configuration from environment/config
+# (We'll configure the logger after CONFIG is initialized below)
+
+__all__ = ['logger']
+
+# Define modules to import
+modules_to_import = [
+    'dataset',
+    'agents',
+    'surveys',
+    'questions',
+    'scenarios',
+    'language_models',
+    'results',
+    'caching',
+    'notebooks',
+    'coop',
+    'instructions',
+    'jobs'
+]
+
+# Dynamically import modules and extend __all__
+for module_name in modules_to_import:
+    try:
+        # Import the module
+        module = importlib.import_module(f'.{module_name}', package='edsl')
+        
+        # Get the module's __all__ attribute
+        module_all = getattr(module, '__all__', [])
+        
+        # Import all names from the module
+        exec(f"from .{module_name} import *")
+        
+        # Extend __all__ with the module's __all__
+        if module_all:
+            logger.debug(f"Adding {len(module_all)} items from {module_name} to __all__")
+            __all__.extend(module_all)
+        else:
+            logger.warning(f"Module {module_name} does not have __all__ defined")
+    except ImportError as e:
+        logger.warning(f"Failed to import module {module_name}: {e}")
+    except Exception as e:
+        logger.warning(f"Error importing from module {module_name}: {e}")
+
+
+# Load plugins
+try:
+    from edsl.load_plugins import load_plugins
+    from edsl.plugins import get_plugin_manager, get_exports
+    
+    # Load all plugins
+    plugins = load_plugins()
+    logger.info(f"Loaded {len(plugins)} plugins")
+    
+    # Add plugins to globals and __all__
+    for plugin_name, plugin in plugins.items():
+        globals()[plugin_name] = plugin
+        __all__.append(plugin_name)
+        logger.info(f"Registered plugin {plugin_name} in global namespace")
+    
+    # Get exports from plugins and add them to globals
+    exports = get_exports()
+    logger.info(f"Found {len(exports)} exported objects from plugins")
+    
+    for name, obj in exports.items():
+        globals()[name] = obj
+        __all__.append(name)
+        logger.info(f"Added plugin export: {name}")
+    
+    # Add placeholders for expected exports that are missing
+    # This maintains backward compatibility for common plugins
+    PLUGIN_PLACEHOLDERS = {
+        # No placeholders - removed Conjure for cleaner namespace
+    }
+    
+    for placeholder_name, github_url in PLUGIN_PLACEHOLDERS.items():
+        if placeholder_name not in globals():
+            # Create a placeholder class
+            placeholder_class = type(placeholder_name, (), {
+                "__getattr__": lambda self, name: self._not_installed(name),
+                "_not_installed": lambda self, name: self._raise_import_error(),
+                "_raise_import_error": lambda self: exec(f"""
+msg = (
+    "The {placeholder_name} plugin is not installed. "
+    "To use {placeholder_name} with EDSL, install it using:\\n"
+    "  from edsl.plugins import install_from_github\\n"
+    "  install_from_github('{github_url}')\\n"
+    "\\nOr from the command line:\\n"
+    "  edsl plugins install {github_url}"
+)
+logger.warning(msg)
+raise ImportError(msg)
+""")
+            })
+            
+            # Register the placeholder
+            globals()[placeholder_name] = placeholder_class()
+            __all__.append(placeholder_name)
+            logger.info(f"Added placeholder for {placeholder_name} with installation instructions")
+
+except ImportError as e:
+    # Modules not available
+    logger.info("Plugin system not available, skipping plugin loading: %s", e)
+    logger.debug("Plugin system not available, skipping plugin loading: %s", e)
+except Exception as e:
+    # Error loading plugins
+    logger.error("Error loading plugins: %s", e)
+    logger.debug("Error loading plugins: %s", e)
+
+# Now that all modules are loaded, configure logging from the config
+logger.configure_from_config()
+
+
+# Installs a custom exception handling routine for edsl exceptions
+from .base.base_exception import BaseException
+BaseException.install_exception_hook()
+
+# Log the total number of items in __all__ for debugging
+logger.debug(f"EDSL initialization complete with {len(__all__)} items in __all__")
 
-from .dataset import __all__ as dataset_all
-from .dataset import *
-__all__.extend(dataset_all)
-
-from .agents import __all__ as agents_all
-from .agents import *
-__all__.extend(agents_all)
-
-from .surveys import __all__ as surveys_all
-from .surveys import *
-__all__.extend(surveys_all)
-
-# Questions
-from .questions import __all__ as questions_all
-from .questions import *
-__all__.extend(questions_all)
-
-from .scenarios import __all__ as scenarios_all
-from .scenarios import *
-__all__.extend(scenarios_all)
-
-from .language_models import __all__ as language_models_all
-from .language_models import *
-__all__.extend(language_models_all)
-
-from .results import __all__ as results_all
-from .results import *
-__all__.extend(results_all)
-
-from .caching import __all__ as caching_all
-from .caching import *
-__all__.extend(caching_all)
-
-from .notebooks import __all__ as notebooks_all
-from .notebooks import *
-__all__.extend(notebooks_all)
-
-from .coop import __all__ as coop_all
-from .coop import *
-__all__.extend(coop_all)
-
-from .instructions import __all__ as instructions_all
-from .instructions import *
-__all__.extend(instructions_all)
-
-from .jobs import __all__ as jobs_all
-from .jobs import *
-__all__.extend(jobs_all)
-
-from .study import __all__ as study_all
-from .study import *
-__all__.extend(study_all)

edsl/__version__.py

@@ -1 +1 @@
-__version__ = "0.1.49"
+__version__ = "0.1.51"

edsl/agents/agent.py

@@ -47,7 +47,6 @@ import types
 import warnings
 from uuid import uuid4
 from contextlib import contextmanager
-
 from typing import (
     Callable,
     Optional,
@@ -57,11 +56,9 @@ from typing import (
     Protocol,
     runtime_checkable,
     TypeVar,
+    Type,
 )
 
-# Type variable for the Agent class
-A = TypeVar("A", bound="Agent")
-
 if TYPE_CHECKING:
     from ..caching import Cache
     from ..surveys import Survey
@@ -71,17 +68,8 @@ if TYPE_CHECKING:
     from ..questions import QuestionBase
     from ..invigilators import InvigilatorBase
     from ..prompts import Prompt
-    from ..questions import QuestionBase
     from ..key_management import KeyLookup
 
-
-@runtime_checkable
-class DirectAnswerMethod(Protocol):
-    """Protocol defining the required signature for direct answer methods."""
-
-    def __call__(self, self_: A, question: QuestionBase, scenario: Scenario) -> Any: ...
-
-
 from ..base import Base
 from ..scenarios import Scenario
 from ..questions import QuestionScenarioRenderError
@@ -93,7 +81,6 @@ from ..utilities import (
     remove_edsl_version,
 )
 
-
 from .exceptions import (
     AgentErrors,
     AgentCombinationError,
@@ -108,6 +95,16 @@ from .descriptors import (
     NameDescriptor,
 )
 
+# Type variable for the Agent class
+A = TypeVar("A", bound="Agent")
+
+
+@runtime_checkable
+class DirectAnswerMethod(Protocol):
+    """Protocol defining the required signature for direct answer methods."""
+
+    def __call__(self, self_: A, question: QuestionBase, scenario: Scenario) -> Any: ...
+
 
 class AgentTraits(Scenario):
     """A class representing the traits of an agent.
@@ -472,9 +469,10 @@ class Agent(Base):
         # Transfer direct answering method if present
         if hasattr(self, "answer_question_directly"):
             answer_question_directly = self.answer_question_directly
-            newf = lambda self, question, scenario: answer_question_directly(
-                question, scenario
-            )
+            def newf(self, question, scenario):
+                return answer_question_directly(
+                    question, scenario
+                )
             new_agent.add_direct_question_answering_method(newf)
             
         # Transfer dynamic traits function if present
@@ -940,7 +938,7 @@ class Agent(Base):
 
     answer_question = sync_wrapper(async_answer_question)
 
-    def _get_invigilator_class(self, question: QuestionBase) -> Type[InvigilatorBase]:
+    def _get_invigilator_class(self, question: "QuestionBase") -> Type["InvigilatorBase"]:
         """Get the invigilator class for a question.
 
         This method returns the invigilator class that should be used to answer a question.
@@ -1098,6 +1096,8 @@ class Agent(Base):
         if name in self._traits:
             return self._traits[name]
 
+        # Keep using AttributeError instead of our custom exception to maintain compatibility
+        # with Python's attribute access mechanism
         raise AttributeError(
             f"'{type(self).__name__}' object has no attribute '{name}'"
         )
@@ -1142,7 +1142,7 @@ class Agent(Base):
                 raw_data.pop("instruction")
         if self.codebook == {}:
             raw_data.pop("codebook")
-        if self.name == None:
+        if self.name is None:
             raw_data.pop("name")
 
         if hasattr(self, "dynamic_traits_function"):
@@ -1164,7 +1164,7 @@ class Agent(Base):
 
             if (
                 answer_question_directly_func
-                and raw_data.get("answer_question_directly_source_code", None) != None
+                and raw_data.get("answer_question_directly_source_code", None) is not None
             ):
                 raw_data["answer_question_directly_source_code"] = inspect.getsource(
                     answer_question_directly_func
@@ -1352,7 +1352,7 @@ def main():
         question_name="food_preference",
     )
     job = question.by(agent)
-    results = job.run()
+    job.run()  # results not used
 
 
 if __name__ == "__main__":

edsl/agents/agent_list.py

@@ -27,10 +27,7 @@ from .exceptions import AgentListError
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from ..scenarios import ScenarioList
     from ..agents import Agent
-    from pandas import DataFrame
-    from ..dataset import Dataset
 
 
 def is_iterable(obj):
@@ -212,7 +209,7 @@ class AgentList(UserList, Base, AgentListOperationsMixin):
             new_data = [
                 agent for agent in self.data if create_evaluator(agent).eval(expression)
             ]
-        except NameNotDefined as e:
+        except NameNotDefined:
             e = AgentListError(f"'{expression}' is not a valid expression.")
             if is_notebook():
                 print(e, file=sys.stderr)
@@ -451,7 +448,7 @@ class AgentList(UserList, Base, AgentListOperationsMixin):
         *fields,
         tablefmt: Optional[str] = None,
         pretty_labels: Optional[dict] = None,
-    ) -> "Table":
+    ) -> Any:
         if len(self) == 0:
             e = AgentListError("Cannot create a table from an empty AgentList.")
             if is_notebook():

edsl/agents/exceptions.py

@@ -1,18 +1,52 @@
-import sys
 
-from ..exceptions.BaseException import BaseException
-from ..utilities.is_notebook import is_notebook
+from ..base.base_exception import BaseException
 
 
 class AgentListError(BaseException):
+    """
+    Exception raised when an AgentList operation fails.
+    
+    This exception is raised in the following cases:
+    - When an invalid expression is provided in the filter() method
+    - When trying to add traits with mismatched lengths
+    - When attempting to create a table from an empty AgentList
+    
+    Examples:
+        ```python
+        agents.filter("invalid expression")  # Raises AgentListError
+        agents.add_trait(name="scores", values=[1, 2])  # Raises AgentListError if agents list has different length
+        ```
+    """
     relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-lists"
 
 
 class AgentErrors(BaseException):
+    """
+    Base exception class for all agent-related errors.
+    
+    This class is the parent of all agent-specific exceptions and may also be raised directly
+    when modifying agent traits or during operations like renaming or adding traits.
+    """
     relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html"
 
 
 class AgentDynamicTraitsFunctionError(AgentErrors):
+    """
+    Exception raised when there's an issue with the dynamic traits function.
+    
+    This exception occurs when:
+    - The dynamic traits function has too many parameters
+    - The dynamic traits function has parameters other than 'question'
+    
+    This error typically indicates that your dynamic traits function has an incorrect signature.
+    The function should accept only one parameter named 'question'.
+    
+    Examples:
+        ```python
+        def wrong_func(question, extra_param):  # Will raise AgentDynamicTraitsFunctionError
+            return {"trait": "value"}
+        ```
+    """
     relevant_doc = (
         "https://docs.expectedparrot.com/en/latest/agents.html#dynamic-traits-function"
     )
@@ -20,26 +54,106 @@ class AgentDynamicTraitsFunctionError(AgentErrors):
 
 
 class AgentDirectAnswerFunctionError(AgentErrors):
+    """
+    Exception raised when there's an issue with the direct answer method.
+    
+    This exception occurs when the direct answer method doesn't have the required parameters.
+    The method must include 'question', 'scenario', and/or 'self' parameters.
+    
+    Examples:
+        ```python
+        def wrong_answer_func(wrong_param):  # Will raise AgentDirectAnswerFunctionError
+            return "Answer"
+        ```
+    """
     relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-direct-answering-methods"
 
 
 class AgentCombinationError(AgentErrors):
+    """
+    Exception raised when attempting to combine agents with overlapping traits.
+    
+    This exception occurs when you try to combine agents that have the same trait names,
+    which would result in ambiguous trait values in the combined agent.
+    
+    To fix this, ensure that the agents being combined have unique trait names,
+    or rename the conflicting traits before combination.
+    
+    Examples:
+        ```python
+        agent1 = Agent(name="A1", age=30)
+        agent2 = Agent(name="A2", age=40)
+        agent1 + agent2  # Raises AgentCombinationError due to duplicate 'age' trait
+        ```
+    """
     relevant_doc = (
         "https://docs.expectedparrot.com/en/latest/agents.html#combining-agents"
     )
 
 
 class AgentNameError(AgentErrors):
+    """
+    Exception raised when there's an issue with an agent's name.
+    
+    This exception occurs when a trait key conflicts with the 'name' parameter,
+    as 'name' is a special attribute for agents and cannot be used as a trait name.
+    
+    Examples:
+        ```python
+        Agent(name="John", name="John")  # Raises AgentNameError
+        agent.add_trait(name="name", value="NewName")  # Raises AgentNameError
+        ```
+    """
     relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-names"
 
 
 class AgentTraitKeyError(AgentErrors):
+    """
+    Exception raised when an invalid trait key is used.
+    
+    This exception occurs when a trait key is not a valid Python identifier.
+    Trait keys must follow Python variable naming rules (no spaces, no special characters 
+    except underscore, cannot start with a number).
+    
+    Examples:
+        ```python
+        Agent(name="John", "invalid-key"=30)  # Raises AgentTraitKeyError
+        agent.add_trait(name="2invalid", value="value")  # Raises AgentTraitKeyError
+        ```
+    """
     relevant_doc = (
         "https://docs.expectedparrot.com/en/latest/agents.html#constructing-an-agent"
     )
 
 
-class FailedTaskException(Exception):
-    def __init__(self, message, agent_response_dict):
+class AgentAttributeError(AgentErrors):
+    """
+    Exception raised when accessing a non-existent attribute of an agent.
+    
+    This exception occurs when trying to access a trait or attribute that
+    doesn't exist on the agent.
+    
+    Examples:
+        ```python
+        agent = Agent(name="John", age=30)
+        agent.height  # Raises AgentAttributeError as 'height' doesn't exist
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-traits"
+    
+    def __init__(self, message):
         super().__init__(message)
+        
+
+class FailedTaskException(BaseException):
+    """
+    Exception raised when an agent task execution fails.
+    
+    This exception is used to track agent execution failures and retain information
+    about the agent's response when the failure occurred.
+    
+    Note: This exception class is currently not used in the codebase.
+    """
+    def __init__(self, message, agent_response_dict):
+        super().__init__(f"Agent task failed: {message}")
         self.agent_response_dict = agent_response_dict

edsl/base/__init__.py

@@ -7,7 +7,6 @@ from edsl.base.base_class import (
     Base,
     BaseDiff,
     BaseDiffCollection,
-    BaseException,
     DiffMethodsMixin,
     DisplayJSON,
     DisplayYAML,
@@ -18,6 +17,15 @@ from edsl.base.base_class import (
     RepresentationMixin,
     is_iterable,
 )
+from edsl.base.base_exception import BaseException
+from edsl.base.exceptions import (
+    BaseValueError,
+    BaseNotImplementedError,
+    BaseKeyError,
+    BaseFileError, 
+    BaseTypeError
+)
+
 from edsl.base.enums import (
     EnumWithChecks,
     InferenceServiceLiteral,
@@ -39,37 +47,4 @@ from edsl.base.data_transfer_models import (
     ModelResponse,
 )
 
-__all__ = [
-    # From base_class
-    "Base",
-    "BaseDiff",
-    "BaseDiffCollection",
-    "BaseException",
-    "DiffMethodsMixin",
-    "DisplayJSON",
-    "DisplayYAML",
-    "DummyObject",
-    "HashingMixin",
-    "PersistenceMixin",
-    "RegisterSubclassesMeta",
-    "RepresentationMixin",
-    "is_iterable",
-    # From enums
-    "EnumWithChecks",
-    "InferenceServiceLiteral",
-    "InferenceServiceType",
-    "QuestionType",
-    "TokenPricing",
-    "available_models_urls",
-    "get_token_pricing",
-    "pricing",
-    "service_to_api_keyname",
-    # From data_transfer_models
-    "AgentResponseDict",
-    "Answers",
-    "EDSLOutput",
-    "EDSLResultObjectInput",
-    "ImageInfo",
-    "ModelInputs",
-    "ModelResponse",
-]
+__all__ = []