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

edsl/__version__.py

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

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 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,7 @@ 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

edsl/coop/coop.py

@@ -180,7 +180,7 @@ class Coop(CoopFunctionsMixin):
                     timeout=timeout,
                 )
             else:
-                from edsl.coop.exceptions import CoopInvalidMethodError
+                from .exceptions import CoopInvalidMethodError
 
                 raise CoopInvalidMethodError(f"Invalid {method=}.")
         except requests.ConnectionError:
@@ -303,7 +303,7 @@ class Coop(CoopFunctionsMixin):
                 message = root.find("Message").text
                 details = root.find("Details").text
             except Exception:
-                from edsl.coop.exceptions import CoopServerResponseError
+                from .exceptions import CoopServerResponseError
 
                 raise CoopServerResponseError(
                     f"Server returned status code {response.status_code}. "
@@ -311,7 +311,7 @@ class Coop(CoopFunctionsMixin):
                     f"The server response was: {response.text}"
                 )
 
-            from edsl.coop.exceptions import CoopServerResponseError
+            from .exceptions import CoopServerResponseError
 
             raise CoopServerResponseError(
                 f"An error occurred: {code} - {message} - {details}"
@@ -538,7 +538,7 @@ class Coop(CoopFunctionsMixin):
             if response_json.get("upload_signed_url"):
                 signed_url = response_json.get("upload_signed_url")
             else:
-                from edsl.coop.exceptions import CoopResponseError
+                from .exceptions import CoopResponseError
 
                 raise CoopResponseError("No signed url was provided received")
 
@@ -551,7 +551,7 @@ class Coop(CoopFunctionsMixin):
                 "file_store_upload_signed_url"
             )
             if file_store_metadata and not file_store_upload_signed_url:
-                from edsl.coop.exceptions import CoopResponseError
+                from .exceptions import CoopResponseError
 
                 raise CoopResponseError("No file store signed url provided.")
             elif file_store_metadata:
@@ -659,7 +659,7 @@ class Coop(CoopFunctionsMixin):
             json_string = object_data.text
         object_type = response.json().get("object_type")
         if expected_object_type and object_type != expected_object_type:
-            from edsl.coop.exceptions import CoopObjectTypeError
+            from .exceptions import CoopObjectTypeError
 
             raise CoopObjectTypeError(
                 f"Expected {expected_object_type=} but got {object_type=}"
@@ -754,7 +754,7 @@ class Coop(CoopFunctionsMixin):
             and value is None
             and alias is None
         ):
-            from edsl.coop.exceptions import CoopPatchError
+            from .exceptions import CoopPatchError
 
             raise CoopPatchError("Nothing to patch.")
 
@@ -887,7 +887,7 @@ class Coop(CoopFunctionsMixin):
         [CacheEntry(...), CacheEntry(...), ...]
         """
         if job_uuid is None:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
 
             raise CoopValueError("Must provide a job_uuid.")
         response = self._send_server_request(
@@ -917,7 +917,7 @@ class Coop(CoopFunctionsMixin):
         [CacheEntry(...), CacheEntry(...), ...]
         """
         if select_keys is None or len(select_keys) == 0:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
 
             raise CoopValueError("Must provide a non-empty list of select_keys.")
         response = self._send_server_request(
@@ -1182,7 +1182,7 @@ class Coop(CoopFunctionsMixin):
             ...     print(f"Results available at: {job_status['results_url']}")
         """
         if job_uuid is None and results_uuid is None:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
 
             raise CoopValueError("Either job_uuid or results_uuid must be provided.")
         elif job_uuid is not None:
@@ -1258,7 +1258,7 @@ class Coop(CoopFunctionsMixin):
         elif isinstance(input, Survey):
             job = Jobs(survey=input)
         else:
-            from edsl.coop.exceptions import CoopTypeError
+            from .exceptions import CoopTypeError
 
             raise CoopTypeError("Input must be either a Job or a Survey.")
 
@@ -1395,7 +1395,7 @@ class Coop(CoopFunctionsMixin):
         elif CONFIG.get("EDSL_FETCH_TOKEN_PRICES") == "False":
             return {}
         else:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
 
             raise CoopValueError(
                 "Invalid EDSL_FETCH_TOKEN_PRICES value---should be 'True' or 'False'."
@@ -1553,7 +1553,7 @@ class Coop(CoopFunctionsMixin):
         api_key = self._poll_for_api_key(edsl_auth_token)
 
         if api_key is None:
-            from edsl.coop.exceptions import CoopTimeoutError
+            from .exceptions import CoopTimeoutError
 
             raise CoopTimeoutError("Timed out waiting for login. Please try again.")
 

edsl/coop/coop_functions.py

@@ -1,6 +1,6 @@
 class CoopFunctionsMixin:
     def better_names(self, existing_names):
-        from edsl import QuestionList, Scenario
+        from .. import QuestionList, Scenario
 
         s = Scenario({"existing_names": existing_names})
         q = QuestionList(

edsl/coop/ep_key_handling.py

@@ -70,7 +70,7 @@ class ExpectedParrotKeyHandler:
 
     def ok_to_ask_to_store(self):
         """Check if it's okay to ask the user to store the key."""
-        from edsl.config import CONFIG
+        from ..config import CONFIG
 
         if CONFIG.get("EDSL_RUN_MODE") != "production":
             return False

edsl/coop/price_fetcher.py

@@ -7,6 +7,7 @@ that price information is only fetched once and then cached for efficiency.
 """
 
 import requests
+import os
 from typing import Dict, Tuple, Any
 
 
@@ -82,7 +83,6 @@ class PriceFetcher:
         if self._cached_prices is not None:
             return self._cached_prices
 
-        import os
         from ..config import CONFIG
 
         try:
@@ -120,4 +120,4 @@ class PriceFetcher:
         except requests.RequestException:
             # Silently handle errors and return empty dict
             # print(f"An error occurred: {e}")
-            return {}
+            return {}

edsl/coop/utils.py

@@ -129,7 +129,7 @@ class ObjectRegistry:
         # Look up the object type
         object_type = cls.edsl_class_to_object_type.get(edsl_class_name)
         if object_type is None:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
             raise CoopValueError(f"Object type not found for {edsl_object=}")
         return object_type
 
@@ -152,7 +152,7 @@ class ObjectRegistry:
         """
         EDSL_class = cls.object_type_to_edsl_class.get(object_type)
         if EDSL_class is None:
-            from edsl.coop.exceptions import CoopValueError
+            from .exceptions import CoopValueError
             raise CoopValueError(f"EDSL class not found for {object_type=}")
         return EDSL_class