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

edsl/__init__.py

@@ -15,39 +15,42 @@ from edsl import logger
 # Set up logger with configuration from environment/config
 # (We'll configure the logger after CONFIG is initialized below)
 
-__all__ = ['logger']
+__all__ = ["logger"]
 
 # Define modules to import
 modules_to_import = [
-    'dataset',
-    'agents',
-    'surveys',
-    'questions',
-    'scenarios',
-    'language_models',
-    'results',
-    'caching',
-    'notebooks',
-    'coop',
-    'instructions',
-    'jobs'
+    "dataset",
+    "agents",
+    "surveys",
+    "questions",
+    "scenarios",
+    "language_models",
+    "results",
+    "caching",
+    "notebooks",
+    "coop",
+    "instructions",
+    "jobs",
+    "conversation",
 ]
 
 # 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')
-        
+        module = importlib.import_module(f".{module_name}", package="edsl")
+
         # Get the module's __all__ attribute
-        module_all = getattr(module, '__all__', [])
-        
+        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__")
+            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")
@@ -61,39 +64,43 @@ for module_name in modules_to_import:
 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"""
+            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"
@@ -104,13 +111,17 @@ msg = (
 )
 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")
+            logger.info(
+                f"Added placeholder for {placeholder_name} with installation instructions"
+            )
 
 except ImportError as e:
     # Modules not available
@@ -127,8 +138,8 @@ 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/__version__.py

@@ -1 +1 @@
-__version__ = "0.1.50"
+__version__ = "0.1.52"

edsl/base/base_exception.py

@@ -146,7 +146,7 @@ class BaseException(Exception):
                     #         )
                     #     )
                     # except:
-                    print(f"❌ EDSL ERROR: {etype.__name__}: {evalue}", file=sys.stderr)
+                    print(f"❌ E[🦃] EDSL ERROR: {etype.__name__}: {evalue}", file=sys.stderr)
                 # Suppress IPython’s normal traceback
                 return
             # Otherwise, fall back to the usual traceback
@@ -178,7 +178,7 @@ class BaseException(Exception):
                     #     )
                     # except:
                     print(
-                        f"❌ EDSL ERROR: {exc_type.__name__}: {exc_value}",
+                        f"❌ E[🦃]EDSL ERROR: {exc_type.__name__}: {exc_value}",
                         exc_traceback,
                         file=sys.stderr,
                     )

edsl/buckets/bucket_collection.py

@@ -135,7 +135,7 @@ class BucketCollection(UserDict):
             >>> # The following would raise an exception:
             >>> # bucket_collection.get_tokens(m, 'tokens', 10)
         """
-        from edsl.buckets.exceptions import BucketError
+        from .exceptions import BucketError
         raise BucketError("This method is deprecated and should not be used")
         # The following code is kept for reference only
         # relevant_bucket = getattr(self[model], bucket_type)

edsl/buckets/exceptions.py

@@ -72,4 +72,36 @@ class BucketConfigurationError(BucketError):
         TokenBucket(name="test", capacity=-100, refill_rate=10)  # Would raise BucketConfigurationError
         ```
     """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class BucketNotFoundError(BucketError):
+    """
+    Exception raised when a requested bucket cannot be found.
+    
+    This exception occurs when attempting to access a bucket that doesn't exist
+    in the system or has been removed.
+    
+    Examples:
+        ```python
+        # Attempting to access a non-existent bucket:
+        bucket_collection.get_bucket("non_existent_bucket")  # Would raise BucketNotFoundError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+    
+    
+class InvalidBucketParameterError(BucketConfigurationError):
+    """
+    Exception raised when an invalid parameter is provided for bucket operations.
+    
+    This exception occurs when providing invalid parameters to bucket methods,
+    such as negative token amounts, invalid capacity values, etc.
+    
+    Examples:
+        ```python
+        # Attempting to use invalid parameters:
+        bucket.add_tokens(-100)  # Would raise InvalidBucketParameterError
+        ```
+    """
     relevant_doc = "https://docs.expectedparrot.com/"

edsl/buckets/token_bucket_api.py

@@ -1,9 +1,11 @@
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 from typing import Union, Dict
 from typing import Optional
 
 from .token_bucket import TokenBucket  # Original implementation
+from .exceptions import BucketNotFoundError, InvalidBucketParameterError
 
 def safe_float_for_json(value: float) -> Union[float, str]:
     """Convert float('inf') to 'infinity' for JSON serialization.
@@ -24,6 +26,20 @@ app = FastAPI()
 # In-memory storage for TokenBucket instances
 buckets: Dict[str, TokenBucket] = {}
 
+@app.exception_handler(BucketNotFoundError)
+async def bucket_not_found_handler(request, exc):
+    return JSONResponse(
+        status_code=404,
+        content={"detail": str(exc)},
+    )
+
+@app.exception_handler(InvalidBucketParameterError)
+async def invalid_parameter_handler(request, exc):
+    return JSONResponse(
+        status_code=400,
+        content={"detail": str(exc)},
+    )
+
 
 class TokenBucketCreate(BaseModel):
     bucket_name: str
@@ -83,13 +99,13 @@ async def list_buckets(
 async def add_tokens(bucket_id: str, amount: float):
     """Add tokens to an existing bucket."""
     if bucket_id not in buckets:
-        raise HTTPException(status_code=404, detail="Bucket not found")
+        raise BucketNotFoundError(f"Bucket with ID '{bucket_id}' not found")
 
     if not isinstance(amount, (int, float)) or amount != amount:  # Check for NaN
-        raise HTTPException(status_code=400, detail="Invalid amount specified")
+        raise InvalidBucketParameterError("Invalid amount specified")
 
     if amount == float("inf") or amount == float("-inf"):
-        raise HTTPException(status_code=400, detail="Amount cannot be infinite")
+        raise InvalidBucketParameterError("Amount cannot be infinite")
 
     bucket = buckets[bucket_id]
     bucket.add_tokens(amount)
@@ -124,14 +140,14 @@ async def create_bucket(bucket: TokenBucketCreate):
         not isinstance(bucket.capacity, (int, float))
         or bucket.capacity != bucket.capacity
     ):  # Check for NaN
-        raise HTTPException(status_code=400, detail="Invalid capacity value")
+        raise InvalidBucketParameterError("Invalid capacity value")
     if (
         not isinstance(bucket.refill_rate, (int, float))
         or bucket.refill_rate != bucket.refill_rate
     ):  # Check for NaN
-        raise HTTPException(status_code=400, detail="Invalid refill rate value")
+        raise InvalidBucketParameterError("Invalid refill rate value")
     if bucket.capacity == float("inf") or bucket.refill_rate == float("inf"):
-        raise HTTPException(status_code=400, detail="Values cannot be infinite")
+        raise InvalidBucketParameterError("Values cannot be infinite")
     bucket_id = f"{bucket.bucket_name}_{bucket.bucket_type}"
     if bucket_id in buckets:
         # Instead of error, return success with "existing" status
@@ -156,7 +172,7 @@ async def create_bucket(bucket: TokenBucketCreate):
 @app.post("/bucket/{bucket_id}/get_tokens")
 async def get_tokens(bucket_id: str, amount: float, cheat_bucket_capacity: bool = True):
     if bucket_id not in buckets:
-        raise HTTPException(status_code=404, detail="Bucket not found")
+        raise BucketNotFoundError(f"Bucket with ID '{bucket_id}' not found")
 
     bucket = buckets[bucket_id]
     await bucket.get_tokens(amount, cheat_bucket_capacity)
@@ -166,7 +182,7 @@ async def get_tokens(bucket_id: str, amount: float, cheat_bucket_capacity: bool
 @app.post("/bucket/{bucket_id}/turbo_mode/{state}")
 async def set_turbo_mode(bucket_id: str, state: bool):
     if bucket_id not in buckets:
-        raise HTTPException(status_code=404, detail="Bucket not found")
+        raise BucketNotFoundError(f"Bucket with ID '{bucket_id}' not found")
 
     bucket = buckets[bucket_id]
     if state:
@@ -179,7 +195,7 @@ async def set_turbo_mode(bucket_id: str, state: bool):
 @app.get("/bucket/{bucket_id}/status")
 async def get_bucket_status(bucket_id: str):
     if bucket_id not in buckets:
-        raise HTTPException(status_code=404, detail="Bucket not found")
+        raise BucketNotFoundError(f"Bucket with ID '{bucket_id}' not found")
 
     bucket = buckets[bucket_id]
     status = {

edsl/caching/cache.py

@@ -176,8 +176,11 @@ class Cache(Base):
             
         Examples:
             >>> from edsl import Cache
-            >>> Cache.example().values()
-            [CacheEntry(...)]
+            >>> entries = Cache.example().values()
+            >>> len(entries)
+            1
+            >>> entries[0]  # doctest: +ELLIPSIS
+            CacheEntry(model='gpt-3.5-turbo', parameters={'temperature': 0.5}, ...)
         """
         return list(self.data.values())
 

edsl/caching/remote_cache_sync.py

@@ -5,7 +5,7 @@ from collections import UserList
 
 if TYPE_CHECKING:
     from .cache import Cache
-    from edsl.coop.coop import Coop
+    from ..coop.coop import Coop
     from .cache_entry import CacheEntry
 
 
@@ -34,7 +34,7 @@ class CacheEntriesList(UserList):
         return f"CacheEntries({entries_repr})"
 
     def to_cache(self) -> "Cache":
-        from edsl.caching.cache import Cache
+        from .cache import Cache
 
         return Cache({entry.key: entry for entry in self.data})
 
@@ -178,9 +178,9 @@ if __name__ == "__main__":
 
     doctest.testmod()
 
-    from edsl.coop.coop import Coop
-    from edsl.data.Cache import Cache
-    from edsl.data.CacheEntry import CacheEntry
+    from ..coop.coop import Coop
+    from .cache import Cache
+    from .cache_entry import CacheEntry
 
     r = RemoteCacheSync(Coop(), Cache(), print)
     diff = r._get_cache_difference()

edsl/caching/sql_dict.py

@@ -64,8 +64,9 @@ class SQLiteDict:
             
         Example:
             >>> temp_db_path = SQLiteDict._get_temp_path()
-            >>> SQLiteDict(f"sqlite:///{temp_db_path}")  # Use the temp file for SQLite
-            SQLiteDict(db_path='...')
+            >>> db = SQLiteDict(f"sqlite:///{temp_db_path}")  # Use the temp file for SQLite
+            >>> isinstance(db, SQLiteDict)
+            True
             >>> import os; os.unlink(temp_db_path)  # Clean up the temp file after the test
         """
         from sqlalchemy.exc import SQLAlchemyError
@@ -76,13 +77,13 @@ class SQLiteDict:
         if not self.db_path.startswith("sqlite:///"):
             self.db_path = f"sqlite:///{self.db_path}"
         try:
-            from edsl.caching.orm import Base
+            from .orm import Base
 
             self.engine = create_engine(self.db_path, echo=False, future=True)
             Base.metadata.create_all(self.engine)
             self.Session = sessionmaker(bind=self.engine)
         except SQLAlchemyError as e:
-            from edsl.caching.exceptions import CacheError
+            from .exceptions import CacheError
             raise CacheError(
                 f"""Database initialization error: {e}. The attempted DB path was {db_path}"""
             ) from e
@@ -123,10 +124,10 @@ class SQLiteDict:
             >>> d["foo"] = CacheEntry.example()
         """
         if not isinstance(value, CacheEntry):
-            from edsl.caching.exceptions import CacheValueError
+            from .exceptions import CacheValueError
             raise CacheValueError(f"Value must be a CacheEntry object (got {type(value)}).")
         with self.Session() as db:
-            from edsl.caching.orm import Data
+            from .orm import Data
 
             db.merge(Data(key=key, value=json.dumps(value.to_dict())))
             db.commit()
@@ -155,11 +156,11 @@ class SQLiteDict:
             True
         """
         with self.Session() as db:
-            from edsl.caching.orm import Data
+            from .orm import Data
 
             value = db.query(Data).filter_by(key=key).first()
             if not value:
-                from edsl.caching.exceptions import CacheKeyError
+                from .exceptions import CacheKeyError
                 raise CacheKeyError(f"Key '{key}' not found.")
             return CacheEntry.from_dict(json.loads(value.value))
 
@@ -183,7 +184,7 @@ class SQLiteDict:
             >>> d.get("foo", "bar")
             'bar'
         """
-        from edsl.caching.exceptions import CacheKeyError
+        from .exceptions import CacheKeyError
         try:
             return self[key]
         except (KeyError, CacheKeyError):
@@ -236,7 +237,7 @@ class SQLiteDict:
             the database from being locked for too long.
         """
         if not (isinstance(new_d, dict) or isinstance(new_d, SQLiteDict)):
-            from edsl.caching.exceptions import CacheValueError
+            from .exceptions import CacheValueError
             raise CacheValueError(
                 f"new_d must be a dict or SQLiteDict object (got {type(new_d)})"
             )
@@ -305,7 +306,7 @@ class SQLiteDict:
                 db.delete(instance)
                 db.commit()
             else:
-                from edsl.caching.exceptions import CacheKeyError
+                from .exceptions import CacheKeyError
                 raise CacheKeyError(f"Key '{key}' not found.")
 
     def __contains__(self, key: str) -> bool:

edsl/config/__init__.py

@@ -3,6 +3,6 @@
 This module provides a Config class that loads environment variables from a .env file and sets them as class attributes.
 """
 
-from edsl.config.config_class import Config, CONFIG, CONFIG_MAP, EDSL_RUN_MODES, cache_dir
+from .config_class import Config, CONFIG, CONFIG_MAP, EDSL_RUN_MODES, cache_dir
 
 __all__ = ["Config", "CONFIG", "CONFIG_MAP", "EDSL_RUN_MODES", "cache_dir"]

edsl/config/config_class.py

@@ -3,8 +3,10 @@
 import os
 import platformdirs
 from dotenv import load_dotenv, find_dotenv
-from edsl.base import BaseException
-from edsl import logger
+from ..base import BaseException
+import logging
+
+logger = logging.getLogger(__name__)
 
 class InvalidEnvironmentVariableError(BaseException):
     """Raised when an environment variable is invalid."""

edsl/conversation/Conversation.py

@@ -1,13 +1,16 @@
 from collections import UserList
 import asyncio
 import inspect
-from typing import Optional, Callable
-from .. import QuestionFreeText, Results, AgentList, ScenarioList, Scenario
+from typing import Optional, Callable, TYPE_CHECKING
+from .. import QuestionFreeText, Results, AgentList, ScenarioList, Scenario, Model
 from ..questions import QuestionBase
-from ..results.Result import Result
+from ..results.result import Result
 from jinja2 import Template
 from ..caching import Cache
 
+if TYPE_CHECKING:
+    from ..language_models.model import Model
+
 from .next_speaker_utilities import (
     default_turn_taking_generator,
     speaker_closure,
@@ -71,7 +74,7 @@ class Conversation:
         conversation_index: Optional[int] = None,
         cache=None,
         disable_remote_inference=False,
-        default_model: Optional["LanguageModel"] = None,
+        default_model: Optional[Model] = None,
     ):
         self.disable_remote_inference = disable_remote_inference
         self.per_round_message_template = per_round_message_template
@@ -120,7 +123,8 @@ What do you say next?"""
                 per_round_message_template
                 and "{{ round_message }}" not in next_statement_question.question_text
             ):
-                from edsl.conversation.exceptions import ConversationValueError
+                from .exceptions import ConversationValueError
+
                 raise ConversationValueError(
                     "If you pass in a per_round_message_template, you must include {{ round_message }} in the question_text."
                 )

edsl/conversation/car_buying.py

@@ -1,5 +1,4 @@
-from .. import Agent, AgentList, QuestionFreeText
-from .. import Cache
+from .. import Agent, AgentList, QuestionFreeText, Cache, QuestionList
 from .Conversation import Conversation, ConversationList
 
 a1 = Agent(
@@ -46,7 +45,6 @@ q = QuestionFreeText(
     question_name="car_brand",
 )
 
-from .. import QuestionList
 
 q_actors = QuestionList(
     question_text="""This was a conversation about buying a car: {{ transcript }}. 

edsl/conversation/mug_negotiation.py

@@ -1,5 +1,5 @@
-from edsl import Agent, AgentList
-from edsl.conversation.Conversation import Conversation, ConversationList
+from .. import Agent, AgentList, QuestionYesNo, QuestionNumerical
+from .Conversation import Conversation, ConversationList
 
 
 def bargaining_pairs(alice_valuation, bob_valuation):
@@ -43,10 +43,6 @@ results.select("conversation_index", "index", "agent_name", "dialogue").print(
     format="rich"
 )
 
-from edsl import (
-    QuestionYesNo,
-    QuestionNumerical,
-)
 
 q_deal = QuestionYesNo(
     question_text="""This was a negotiation: {{ transcript }}. 

edsl/coop/__init__.py

@@ -13,16 +13,19 @@ This module enables EDSL to interact with cloud-based resources for enhanced fun
 The primary interface is the Coop class, which serves as a client for the
 Expected Parrot API. Most users will only need to interact with the Coop class directly.
 
-Example:
-    >>> from edsl.coop import Coop
-    >>> coop = Coop()  # Uses API key from environment or stored location
-    >>> survey = my_survey.push()  # Uploads survey to Expected Parrot
-    >>> job_info = coop.remote_inference_create(my_job)  # Creates remote job
+Examples:
+    
+    ```python
+    from edsl.coop import Coop
+    coop = Coop()  # Uses API key from environment or stored location
+    survey = my_survey.push()  # Uploads survey to Expected Parrot
+    job_info = coop.remote_inference_create(my_job)  # Creates remote job
     
     # Working with plugins
-    >>> from edsl.coop import get_available_plugins
-    >>> plugins = get_available_plugins()
-    >>> plugin_names = [p.name for p in plugins]
+    from edsl.coop import get_available_plugins
+    plugins = get_available_plugins()
+    plugin_names = [p.name for p in plugins]
+    ```
 """
 
 from .utils import EDSLObject, ObjectType, VisibilityType, ObjectRegistry