edsl 0.1.49__tar.gz → 0.1.51__tar.gz

{edsl-0.1.49 → edsl-0.1.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.49
+Version: 0.1.51
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT
@@ -36,6 +36,7 @@ Requires-Dist: openai (>=1.4.0,<2.0.0)
 Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
 Requires-Dist: pandas (>=2.1.4,<3.0.0)
 Requires-Dist: platformdirs (>=4.3.6,<5.0.0)
+Requires-Dist: pluggy (>=1.3.0,<2.0.0)
 Requires-Dist: pydot (>=2.0.0,<3.0.0)
 Requires-Dist: pygments (>=2.17.2,<3.0.0)
 Requires-Dist: pypdf2 (>=3.0.1,<4.0.0)
@@ -50,6 +51,7 @@ Requires-Dist: simpleeval (>=0.9.13,<0.10.0)
 Requires-Dist: sqlalchemy (>=2.0.23,<3.0.0)
 Requires-Dist: tabulate (>=0.9.0,<0.10.0)
 Requires-Dist: tenacity (>=8.2.3,<9.0.0)
+Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
 Requires-Dist: urllib3 (>=1.25.4,<1.27)
 Project-URL: Documentation, https://docs.expectedparrot.com
 Description-Content-Type: text/markdown
@@ -198,6 +200,27 @@ results.select("color", "flower")
 **Caching**: 
 API calls to LLMs are cached automatically, allowing you to retrieve responses to questions that have already been run and reproduce experiments at no cost. Learn more about how the <a href="https://docs.expectedparrot.com/en/latest/remote_caching.html" target="_blank" rel="noopener noreferrer">universal remote cache</a> works.
 
+**Logging**:
+EDSL includes a comprehensive logging system to help with debugging and monitoring. Control log levels and see important information about operations:
+
+```python
+from edsl import logger
+import logging
+
+# Set the logging level
+logger.set_level(logging.DEBUG)  # Show all log messages
+
+# Get a module-specific logger
+my_logger = logger.get_logger(__name__)
+my_logger.info("This is a module-specific log message")
+
+# Log messages at different levels
+logger.debug("Detailed debugging information")
+logger.info("General information about operation")
+logger.warning("Something unexpected but not critical")
+logger.error("Something went wrong")
+```
+
 **Flexibility**: 
 Choose whether to run surveys on your own computer or at the Expected Parrot server.
 
@@ -231,6 +254,13 @@ Analyze results as specified datasets from your account or workspace. Easily imp
 - API keys for language models. You can use your own keys or an Expected Parrot key that provides access to all available models.
 See instructions on <a href="https://docs.expectedparrot.com/en/latest/api_keys.html" target="_blank" rel="noopener noreferrer">managing keys</a> and <a href="https://www.expectedparrot.com/getting-started/coop-pricing" target="_blank" rel="noopener noreferrer">model pricing and performance</a> information.
 
+## Developer Notes
+
+### Running Tests
+- Unit tests: `python -m pytest tests/`  
+- Integration tests: `python -m pytest integration/`
+- Doctests: `python run_doctests.py` (use `-v` flag for verbose output)
+
 ## Coop
 An integrated platform for running experiments, sharing workflows and launching hybrid human/AI surveys.
 - <a href="https://www.expectedparrot.com/login" target="_blank" rel="noopener noreferrer">Login / Signup</a>
@@ -243,5 +273,5 @@ An integrated platform for running experiments, sharing workflows and launching
 - <a href="https://blog.expectedparrot.com" target="_blank" rel="noopener noreferrer">Blog</a>.
 
 ## Contact
-- <a href="mailto:info@expectedparrot.com" target="_blank" rel="noopener noreferrer">Email</a>
+- <a href="mailto:info@expectedparrot.com" target="_blank" rel="noopener noreferrer">Email</a>.
 

{edsl-0.1.49 → edsl-0.1.51}/README.md

@@ -142,6 +142,27 @@ results.select("color", "flower")
 **Caching**: 
 API calls to LLMs are cached automatically, allowing you to retrieve responses to questions that have already been run and reproduce experiments at no cost. Learn more about how the <a href="https://docs.expectedparrot.com/en/latest/remote_caching.html" target="_blank" rel="noopener noreferrer">universal remote cache</a> works.
 
+**Logging**:
+EDSL includes a comprehensive logging system to help with debugging and monitoring. Control log levels and see important information about operations:
+
+```python
+from edsl import logger
+import logging
+
+# Set the logging level
+logger.set_level(logging.DEBUG)  # Show all log messages
+
+# Get a module-specific logger
+my_logger = logger.get_logger(__name__)
+my_logger.info("This is a module-specific log message")
+
+# Log messages at different levels
+logger.debug("Detailed debugging information")
+logger.info("General information about operation")
+logger.warning("Something unexpected but not critical")
+logger.error("Something went wrong")
+```
+
 **Flexibility**: 
 Choose whether to run surveys on your own computer or at the Expected Parrot server.
 
@@ -175,6 +196,13 @@ Analyze results as specified datasets from your account or workspace. Easily imp
 - API keys for language models. You can use your own keys or an Expected Parrot key that provides access to all available models.
 See instructions on <a href="https://docs.expectedparrot.com/en/latest/api_keys.html" target="_blank" rel="noopener noreferrer">managing keys</a> and <a href="https://www.expectedparrot.com/getting-started/coop-pricing" target="_blank" rel="noopener noreferrer">model pricing and performance</a> information.
 
+## Developer Notes
+
+### Running Tests
+- Unit tests: `python -m pytest tests/`  
+- Integration tests: `python -m pytest integration/`
+- Doctests: `python run_doctests.py` (use `-v` flag for verbose output)
+
 ## Coop
 An integrated platform for running experiments, sharing workflows and launching hybrid human/AI surveys.
 - <a href="https://www.expectedparrot.com/login" target="_blank" rel="noopener noreferrer">Login / Signup</a>
@@ -187,4 +215,4 @@ An integrated platform for running experiments, sharing workflows and launching
 - <a href="https://blog.expectedparrot.com" target="_blank" rel="noopener noreferrer">Blog</a>.
 
 ## Contact
-- <a href="mailto:info@expectedparrot.com" target="_blank" rel="noopener noreferrer">Email</a>
+- <a href="mailto:info@expectedparrot.com" target="_blank" rel="noopener noreferrer">Email</a>.

edsl-0.1.51/edsl/__init__.py

@@ -0,0 +1,134 @@
+import os
+import time
+import importlib
+import pkgutil
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.dirname(BASE_DIR)
+
+from edsl.__version__ import __version__
+from edsl.config import Config, CONFIG
+
+# 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__")
+

edsl-0.1.51/edsl/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.51"

{edsl-0.1.49 → edsl-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-0.1.49 → edsl-0.1.51}/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-0.1.51/edsl/agents/exceptions.py

@@ -0,0 +1,159 @@
+
+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"
+    )
+    relevant_notebook = "https://docs.expectedparrot.com/en/latest/notebooks/example_agent_dynamic_traits.html"
+
+
+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 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-0.1.49 → edsl-0.1.51}/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__ = []