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

edsl/buckets/token_bucket.py

@@ -4,6 +4,7 @@ import time
 from threading import RLock
 
 from ..jobs.decorators import synchronized_class
+from .exceptions import TokenLimitError
 
 
 @synchronized_class
@@ -350,6 +351,7 @@ class TokenBucket:
             - Usage statistics and token levels are logged for tracking purposes
             
         Example:
+            >>> from edsl.buckets.token_bucket import TokenBucket
             >>> bucket = TokenBucket(bucket_name="api", bucket_type="test", capacity=100, refill_rate=10)
             >>> bucket.tokens = 100
             >>> import asyncio
@@ -358,29 +360,32 @@ class TokenBucket:
             70
             
             >>> # Example with capacity cheating
+            >>> from edsl.buckets.token_bucket import TokenBucket
             >>> bucket = TokenBucket(bucket_name="api", bucket_type="test", capacity=10, refill_rate=1)
             >>> asyncio.run(bucket.get_tokens(15, cheat_bucket_capacity=True))
             >>> bucket.capacity > 15  # Capacity should have been increased
             True
             
-            >>> # Example raising ValueError
+            >>> # Example raising TokenLimitError
+            >>> from edsl.buckets.token_bucket import TokenBucket
+            >>> from edsl.buckets.exceptions import TokenLimitError
             >>> bucket = TokenBucket(bucket_name="api", bucket_type="test", capacity=10, refill_rate=1)
             >>> try:
             ...     asyncio.run(bucket.get_tokens(15, cheat_bucket_capacity=False))
-            ... except ValueError as e:
-            ...     print("ValueError raised")
-            ValueError raised
+            ... except TokenLimitError as e:
+            ...     print("TokenLimitError raised")
+            TokenLimitError raised
         """
         self.num_requests += amount
         if amount >= self.capacity:
             if not cheat_bucket_capacity:
                 msg = f"Requested amount exceeds bucket capacity. Bucket capacity: {self.capacity}, requested amount: {amount}. As the bucket never overflows, the requested amount will never be available."
-                raise ValueError(msg)
+                raise TokenLimitError(msg)
             else:
                 self.capacity = amount * 1.10
                 self._old_capacity = self.capacity
 
-        start_time = time.monotonic()
+        # Loop until we have enough tokens
         while True:
             self.refill()  # Refill based on elapsed time
             if self.tokens >= amount:

edsl/buckets/token_bucket_api.py

@@ -1,8 +1,7 @@
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
 from typing import Union, Dict
-from typing import Union, List, Any, Optional
-from threading import RLock
+from typing import Optional
 
 from .token_bucket import TokenBucket  # Original implementation
 

edsl/buckets/token_bucket_client.py

@@ -7,13 +7,15 @@ operations to a remote server, enabling distributed rate limiting across
 multiple processes or machines.
 """
 
-from typing import Union, Optional, Dict, List, Any, Tuple
+from typing import Union, Optional, Dict, Any
 import asyncio
 import time
 import aiohttp
 from matplotlib import pyplot as plt
 from matplotlib.figure import Figure
 
+from .exceptions import BucketError, TokenBucketClientError
+
 
 class TokenBucketClient:
     """
@@ -125,7 +127,7 @@ class TokenBucketClient:
                 json=payload,
             ) as response:
                 if response.status != 200:
-                    raise ValueError(f"Unexpected error: {await response.text()}")
+                    raise TokenBucketClientError(f"Unexpected error: {await response.text()}")
 
                 # Process server response
                 result = await response.json()
@@ -200,7 +202,7 @@ class TokenBucketClient:
                 params={"amount": amount},
             ) as response:
                 if response.status != 200:
-                    raise ValueError(f"Failed to add tokens: {await response.text()}")
+                    raise TokenBucketClientError(f"Failed to add tokens: {await response.text()}")
 
     async def _set_turbo_mode(self, state: bool) -> None:
         """
@@ -220,7 +222,7 @@ class TokenBucketClient:
                 f"{self.api_base_url}/bucket/{self.bucket_id}/turbo_mode/{str(state).lower()}"
             ) as response:
                 if response.status != 200:
-                    raise ValueError(
+                    raise TokenBucketClientError(
                         f"Failed to set turbo mode: {await response.text()}"
                     )
 
@@ -259,7 +261,7 @@ class TokenBucketClient:
                 },
             ) as response:
                 if response.status != 200:
-                    raise ValueError(f"Failed to get tokens: {await response.text()}")
+                    raise TokenBucketClientError(f"Failed to get tokens: {await response.text()}")
 
     def get_throughput(self, time_window: Optional[float] = None) -> float:
         """
@@ -324,7 +326,7 @@ class TokenBucketClient:
                 f"{self.api_base_url}/bucket/{self.bucket_id}/status"
             ) as response:
                 if response.status != 200:
-                    raise ValueError(
+                    raise TokenBucketClientError(
                         f"Failed to get bucket status: {await response.text()}"
                     )
                 return await response.json()
@@ -408,7 +410,7 @@ class TokenBucketClient:
             # Calculate time needed to accumulate the required tokens
             return (requested_tokens - self.tokens) / self.refill_rate
         except Exception as e:
-            raise ValueError(f"Error calculating wait time: {e}")
+            raise BucketError(f"Error calculating wait time: {e}")
 
     # Note: The commented out method below is a reminder for future implementation
     # def wait_time(self, num_tokens: Union[int, float]) -> float:

edsl/caching/cache.py

@@ -32,10 +32,14 @@ import json
 import os
 import warnings
 from typing import Optional, Union, TYPE_CHECKING
-from ..base import Base
 
+from ..base import Base
 from ..utilities import remove_edsl_version, dict_hash
 from .exceptions import CacheError
+from .sql_dict import SQLiteDict
+
+if TYPE_CHECKING:
+    from .cache_entry import CacheEntry
 
 class Cache(Base):
     """Cache for storing and retrieving language model responses.
@@ -418,9 +422,10 @@ class Cache(Base):
         """
         # if a file doesn't exist at jsonfile, throw an error
         from .sql_dict import SQLiteDict
+        from .exceptions import CacheFileNotFoundError
 
         if not os.path.exists(jsonlfile):
-            raise FileNotFoundError(f"File {jsonlfile} not found")
+            raise CacheFileNotFoundError(f"File {jsonlfile} not found")
 
         if db_path is None:
             data = {}

edsl/caching/cache_entry.py

@@ -11,10 +11,11 @@ from __future__ import annotations
 import json
 import datetime
 import hashlib
-from typing import Optional, Dict, List, Any, Union
+from typing import Optional, Dict, List, Any
 from uuid import uuid4
 
 from ..base import RepresentationMixin
+from .exceptions import CacheError
 
 
 class CacheEntry(RepresentationMixin):
@@ -81,22 +82,22 @@ class CacheEntry(RepresentationMixin):
             TypeError: If any attribute has an incorrect type
         """
         if not isinstance(self.model, str):
-            raise TypeError("`model` should be a string.")
+            raise CacheError("`model` should be a string.")
         if not isinstance(self.parameters, dict):
-            raise TypeError("`parameters` should be a dictionary.")
+            raise CacheError("`parameters` should be a dictionary.")
         if not isinstance(self.system_prompt, str):
-            raise TypeError("`system_prompt` should be a string.")
+            raise CacheError("`system_prompt` should be a string.")
         if not isinstance(self.user_prompt, str):
-            raise TypeError("`user_prompt` should be a string")
+            raise CacheError("`user_prompt` should be a string")
         if not isinstance(self.output, str):
-            raise TypeError("`output` should be a string")
+            raise CacheError("`output` should be a string")
         if not isinstance(self.iteration, int):
-            raise TypeError("`iteration` should be an integer")
+            raise CacheError("`iteration` should be an integer")
         # Note: timestamp is stored as int for compatibility, but could be float in future
         if not isinstance(self.timestamp, int):
-            raise TypeError(f"`timestamp` should be an integer")
+            raise CacheError("`timestamp` should be an integer")
         if self.service is not None and not isinstance(self.service, str):
-            raise TypeError("`service` should be either a string or None")
+            raise CacheError("`service` should be either a string or None")
 
     @classmethod
     def gen_key(

edsl/caching/exceptions.py

@@ -1,5 +1,5 @@
 """
-Custom exceptions for the data module in the EDSL framework.
+Custom exceptions for the caching module in the EDSL framework.
 
 This module defines exceptions that are raised during cache operations,
 such as when entries cannot be stored, retrieved, or synchronized.
@@ -13,12 +13,118 @@ class CacheError(BaseException):
     Exception raised for errors related to cache operations.
     
     This exception is raised when cache operations fail, such as when:
-    - A cache key cannot be generated
-    - A cache entry cannot be stored or retrieved
-    - A cache synchronization operation fails
-    - Cache migration encounters an error
+    - A cache key cannot be generated due to invalid or non-serializable inputs
+    - A cache entry cannot be stored or retrieved due to database access issues
+    - A cache synchronization operation fails when syncing with remote cache
+    - Cache migration encounters an error when upgrading between versions
+    
+    To resolve this error:
+    1. Check that your inputs to cached functions are serializable
+    2. Ensure you have proper file system permissions for the SQLite cache file
+    3. For remote cache issues, verify your network connection and API credentials
+    4. For migration issues, you may need to clear the cache by calling cache.clear()
+    
+    Examples:
+        ```python
+        # Cache key generation failure
+        @cache
+        def my_function(non_serializable_object):  # Raises CacheError
+            return result
+        
+        # Storage failure
+        cache.set("key", "value")  # May raise CacheError if DB is locked
+        ```
     
     Attributes:
-        message (str): Explanation of the error
+        message (str): Detailed explanation of the error
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_caching.html"
+
+
+class CacheFileNotFoundError(CacheError):
+    """
+    Exception raised when a cache file cannot be found.
+    
+    This exception is raised when attempting to load or access a cache file
+    that does not exist on the filesystem.
+    
+    To resolve this error:
+    1. Check that the file path is correct
+    2. Verify that the file exists and has proper permissions
+    3. If you're loading a serialized cache, make sure it was previously saved
+    
+    Examples:
+        ```python
+        # Attempting to load a non-existent cache file
+        cache.load_from_file("non_existent_file.json")  # Raises CacheFileNotFoundError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_caching.html"
+
+
+class CacheValueError(CacheError):
+    """
+    Exception raised when an invalid value is provided to a cache operation.
+    
+    This exception is raised when:
+    - An incorrect type is provided for a cache entry
+    - A value cannot be serialized for storage
+    - A validation check fails during cache operations
+    
+    To resolve this error:
+    1. Ensure the value has the expected type and structure
+    2. Verify that values being stored are serializable
+    3. Check for any special requirements in the cache implementation
+    
+    Examples:
+        ```python
+        # Attempting to store an invalid value type
+        cache_dict["key"] = non_cache_entry_object  # Raises CacheValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_caching.html"
+
+
+class CacheKeyError(CacheError):
+    """
+    Exception raised when a key cannot be found in the cache.
+    
+    This exception is raised when attempting to access a cache entry that
+    does not exist in the cache.
+    
+    To resolve this error:
+    1. Check that the key exists before accessing it
+    2. Use cache.get() with a default value to handle missing keys gracefully
+    3. Consider initializing the key-value pair before accessing
+    
+    Examples:
+        ```python
+        # Attempting to access a non-existent key
+        value = cache["non_existent_key"]  # Raises CacheKeyError
+        
+        # Safer alternative
+        value = cache.get("non_existent_key", default=None)  # Returns None instead of raising
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_caching.html"
+
+
+class CacheNotImplementedError(CacheError):
+    """
+    Exception raised when a cache method is not implemented.
+    
+    This exception is raised when attempting to use a method that is
+    defined in the interface but not implemented in the concrete class.
+    
+    To resolve this error:
+    1. Check if the operation is supported by the specific cache implementation
+    2. Consider using an alternative approach that is supported
+    3. If you're implementing a custom cache, implement the required method
+    
+    Examples:
+        ```python
+        # Attempting to use an unimplemented method
+        cache.some_unimplemented_method()  # Raises CacheNotImplementedError
+        ```
     """
-    relevant_doc = "https://docs.expectedparrot.com/en/latest/data.html#cache"
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_caching.html"

edsl/caching/remote_cache_sync.py

@@ -1,4 +1,4 @@
-from typing import List, Dict, Any, Optional, TYPE_CHECKING, Callable
+from typing import List, TYPE_CHECKING, Callable
 from dataclasses import dataclass
 from contextlib import AbstractContextManager
 from collections import UserList
@@ -8,7 +8,6 @@ if TYPE_CHECKING:
     from edsl.coop.coop import Coop
     from .cache_entry import CacheEntry
 
-from logging import Logger
 
 
 class CacheKeyList(UserList):

edsl/caching/sql_dict.py

@@ -9,11 +9,11 @@ making it a drop-in replacement for regular dictionaries but with database persi
 
 from __future__ import annotations
 import json
-from typing import Any, Generator, Optional, Union, Dict, List, Tuple, TypeVar
+from typing import Any, Generator, Optional, Union, Dict, TypeVar
 
 from ..config import CONFIG
 from .cache_entry import CacheEntry
-from .orm import Base, Data
+from .orm import Data
 
 T = TypeVar('T')
 
@@ -76,13 +76,14 @@ class SQLiteDict:
         if not self.db_path.startswith("sqlite:///"):
             self.db_path = f"sqlite:///{self.db_path}"
         try:
-            from edsl.caching.orm import Base, Data
+            from edsl.caching.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:
-            raise Exception(
+            from edsl.caching.exceptions import CacheError
+            raise CacheError(
                 f"""Database initialization error: {e}. The attempted DB path was {db_path}"""
             ) from e
 
@@ -99,7 +100,6 @@ class SQLiteDict:
             Path to a temporary file location
         """
         import tempfile
-        import os
 
         _, temp_db_path = tempfile.mkstemp(suffix=".db")
         return temp_db_path
@@ -123,9 +123,10 @@ class SQLiteDict:
             >>> d["foo"] = CacheEntry.example()
         """
         if not isinstance(value, CacheEntry):
-            raise ValueError(f"Value must be a CacheEntry object (got {type(value)}).")
+            from edsl.caching.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 Base, Data
+            from edsl.caching.orm import Data
 
             db.merge(Data(key=key, value=json.dumps(value.to_dict())))
             db.commit()
@@ -154,11 +155,12 @@ class SQLiteDict:
             True
         """
         with self.Session() as db:
-            from edsl.caching.orm import Base, Data
+            from edsl.caching.orm import Data
 
             value = db.query(Data).filter_by(key=key).first()
             if not value:
-                raise KeyError(f"Key '{key}' not found.")
+                from edsl.caching.exceptions import CacheKeyError
+                raise CacheKeyError(f"Key '{key}' not found.")
             return CacheEntry.from_dict(json.loads(value.value))
 
     def get(self, key: str, default: Optional[Any] = None) -> Union[CacheEntry, Any]:
@@ -181,9 +183,10 @@ class SQLiteDict:
             >>> d.get("foo", "bar")
             'bar'
         """
+        from edsl.caching.exceptions import CacheKeyError
         try:
             return self[key]
-        except KeyError:
+        except (KeyError, CacheKeyError):
             return default
 
     def __bool__(self) -> bool:
@@ -233,7 +236,8 @@ class SQLiteDict:
             the database from being locked for too long.
         """
         if not (isinstance(new_d, dict) or isinstance(new_d, SQLiteDict)):
-            raise ValueError(
+            from edsl.caching.exceptions import CacheValueError
+            raise CacheValueError(
                 f"new_d must be a dict or SQLiteDict object (got {type(new_d)})"
             )
         current_batch = 0
@@ -301,7 +305,8 @@ class SQLiteDict:
                 db.delete(instance)
                 db.commit()
             else:
-                raise KeyError(f"Key '{key}' not found.")
+                from edsl.caching.exceptions import CacheKeyError
+                raise CacheKeyError(f"Key '{key}' not found.")
 
     def __contains__(self, key: str) -> bool:
         """

edsl/cli.py

@@ -0,0 +1,43 @@
+"""
+EDSL Command Line Interface.
+
+This module provides the main entry point for the EDSL command-line tool.
+"""
+
+import sys
+import typer
+from typing import Optional
+from rich.console import Console
+from importlib import metadata
+
+# Create the main Typer app
+app = typer.Typer(help="Expected Parrot EDSL Command Line Interface")
+console = Console()
+
+# Import the plugins app
+from .plugins.cli_typer import app as plugins_app
+
+# Add the plugins subcommand
+app.add_typer(plugins_app, name="plugins")
+
+@app.callback()
+def callback():
+    """
+    Expected Parrot EDSL Command Line Interface.
+    
+    A toolkit for creating, managing, and running surveys with language models.
+    """
+    pass
+
+@app.command()
+def version():
+    """Show the EDSL version."""
+    try:
+        version = metadata.version("edsl")
+        console.print(f"[bold cyan]EDSL version:[/bold cyan] {version}")
+    except metadata.PackageNotFoundError:
+        console.print("[yellow]EDSL package not installed or version not available.[/yellow]")
+
+def main():
+    """Main entry point for the EDSL CLI."""
+    app()

edsl/config/config_class.py

@@ -3,10 +3,16 @@
 import os
 import platformdirs
 from dotenv import load_dotenv, find_dotenv
-from edsl.exceptions.configuration import (
-    InvalidEnvironmentVariableError,
-    MissingEnvironmentVariableError,
-)
+from edsl.base import BaseException
+from edsl import logger
+
+class InvalidEnvironmentVariableError(BaseException):
+    """Raised when an environment variable is invalid."""
+    pass
+
+class MissingEnvironmentVariableError(BaseException):
+    """Raised when an expected environment variable is missing."""
+    pass
 
 cache_dir = platformdirs.user_cache_dir("edsl")
 os.makedirs(cache_dir, exist_ok=True)
@@ -50,6 +56,10 @@ CONFIG_MAP = {
         "default": "True",
         "info": "This config var determines whether to fetch prices for tokens used in remote inference",
     },
+    "EDSL_LOG_LEVEL": {
+        "default": "ERROR",
+        "info": "This config var determines the logging level for the EDSL package (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+    },
     "EDSL_MAX_ATTEMPTS": {
         "default": "5",
         "info": "This config var determines the maximum number of times to retry a failed API call.",
@@ -86,9 +96,11 @@ class Config:
 
     def __init__(self):
         """Initialize the Config class."""
+        logger.debug("Initializing Config class")
         self._set_run_mode()
         self._load_dotenv()
         self._set_env_vars()
+        logger.info(f"Config initialized with run mode: {self.EDSL_RUN_MODE}")
 
     def show_path_to_dot_env(self):
         print(find_dotenv(usecwd=True))
@@ -101,7 +113,12 @@ class Config:
         default = CONFIG_MAP.get("EDSL_RUN_MODE").get("default")
         if run_mode is None:
             run_mode = default
+            logger.debug(f"EDSL_RUN_MODE not set, using default: {default}")
+        else:
+            logger.debug(f"EDSL_RUN_MODE set to: {run_mode}")
+
         if run_mode not in EDSL_RUN_MODES:
+            logger.error(f"Invalid EDSL_RUN_MODE: {run_mode}")
             raise InvalidEnvironmentVariableError(
                 f"Value `{run_mode}` is not allowed for EDSL_RUN_MODE."
             )
@@ -149,12 +166,19 @@ class Config:
         """
         Returns the value of an environment variable.
         """
+        logger.debug(f"Getting config value for: {env_var}")
+
         if env_var not in CONFIG_MAP:
+            logger.error(f"Invalid environment variable requested: {env_var}")
             raise InvalidEnvironmentVariableError(f"{env_var} is not a valid env var. ")
         elif env_var not in self.__dict__:
             info = CONFIG_MAP[env_var].get("info")
+            logger.error(f"Missing environment variable: {env_var}")
             raise MissingEnvironmentVariableError(f"{env_var} is not set. {info}")
-        return self.__dict__.get(env_var)
+
+        value = self.__dict__.get(env_var)
+        logger.debug(f"Config value for {env_var}: {value}")
+        return value
 
     def __iter__(self):
         """Iterate over the environment variables."""
@@ -174,4 +198,4 @@ class Config:
 
 # Note: Python modules are singletons. As such, once this module is imported
 # the same instance of it is reused across the application.
-CONFIG = Config()
+CONFIG = Config()

edsl/conversation/Conversation.py

@@ -2,7 +2,7 @@ from collections import UserList
 import asyncio
 import inspect
 from typing import Optional, Callable
-from .. import Agent, QuestionFreeText, Results, AgentList, ScenarioList, Scenario
+from .. import QuestionFreeText, Results, AgentList, ScenarioList, Scenario
 from ..questions import QuestionBase
 from ..results.Result import Result
 from jinja2 import Template
@@ -120,7 +120,8 @@ What do you say next?"""
                 per_round_message_template
                 and "{{ round_message }}" not in next_statement_question.question_text
             ):
-                raise ValueError(
+                from edsl.conversation.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/exceptions.py

@@ -0,0 +1,58 @@
+"""
+Exceptions for the conversation module.
+
+This module defines custom exceptions for the conversation module,
+including errors for invalid participant configurations, agent interaction
+failures, and conversation state errors.
+"""
+
+from ..base import BaseException
+
+
+class ConversationError(BaseException):
+    """
+    Base exception class for all conversation-related errors.
+    
+    This is the parent class for all exceptions related to conversation
+    operations, including agent communication, turn management, and
+    participant configuration.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class ConversationValueError(ConversationError):
+    """
+    Exception raised when an invalid value is provided to a conversation.
+    
+    This exception occurs when attempting to create or modify a conversation
+    with invalid values, such as:
+    - Invalid participant configurations
+    - Inappropriate agent parameters
+    - Incompatible conversation settings
+    
+    Examples:
+        ```python
+        # Attempting to add an invalid participant to a conversation
+        conversation.add_participant(None)  # Raises ConversationValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+    
+
+class ConversationStateError(ConversationError):
+    """
+    Exception raised when the conversation is in an invalid state.
+    
+    This exception occurs when attempting to perform an operation that
+    is incompatible with the current state of the conversation, such as:
+    - Ending a conversation that hasn't started
+    - Starting a conversation that's already in progress
+    - Accessing a participant that doesn't exist
+    
+    Examples:
+        ```python
+        # Attempting to get the next speaker when the conversation is empty
+        empty_conversation.next_speaker()  # Raises ConversationStateError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"

edsl/conversation/mug_negotiation.py

@@ -44,8 +44,6 @@ results.select("conversation_index", "index", "agent_name", "dialogue").print(
 )
 
 from edsl import (
-    QuestionFreeText,
-    QuestionMultipleChoice,
     QuestionYesNo,
     QuestionNumerical,
 )