edsl 0.1.49__py3-none-any.whl → 0.1.51__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,10 +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 Union, List, Any, Optional
-from threading import RLock
+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.
@@ -25,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
@@ -84,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)
@@ -125,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
@@ -157,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)
@@ -167,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:
@@ -180,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/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.
@@ -172,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())
 
@@ -418,9 +425,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,14 +1,13 @@
-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
 
 if TYPE_CHECKING:
     from .cache import Cache
-    from edsl.coop.coop import Coop
+    from ..coop.coop import Coop
     from .cache_entry import CacheEntry
 
-from logging import Logger
 
 
 class CacheKeyList(UserList):
@@ -35,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})
 
@@ -179,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

@@ -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')
 
@@ -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,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 .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 .exceptions import CacheError
+            raise CacheError(
                 f"""Database initialization error: {e}. The attempted DB path was {db_path}"""
             ) from e
 
@@ -99,7 +101,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 +124,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 .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 .orm import Data
 
             db.merge(Data(key=key, value=json.dumps(value.to_dict())))
             db.commit()
@@ -154,11 +156,12 @@ class SQLiteDict:
             True
         """
         with self.Session() as db:
-            from edsl.caching.orm import Base, Data
+            from .orm import Data
 
             value = db.query(Data).filter_by(key=key).first()
             if not value:
-                raise KeyError(f"Key '{key}' not found.")
+                from .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 +184,10 @@ class SQLiteDict:
             >>> d.get("foo", "bar")
             'bar'
         """
+        from .exceptions import CacheKeyError
         try:
             return self[key]
-        except KeyError:
+        except (KeyError, CacheKeyError):
             return default
 
     def __bool__(self) -> bool:
@@ -233,7 +237,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 .exceptions import CacheValueError
+            raise CacheValueError(
                 f"new_d must be a dict or SQLiteDict object (got {type(new_d)})"
             )
         current_batch = 0
@@ -301,7 +306,8 @@ class SQLiteDict:
                 db.delete(instance)
                 db.commit()
             else:
-                raise KeyError(f"Key '{key}' not found.")
+                from .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/__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"]