edsl 0.1.47__py3-none-any.whl → 0.1.48__py3-none-any.whl

edsl/{language_models/key_management/KeyLookupBuilder.py → key_management/key_lookup_builder.py}

@@ -1,15 +1,12 @@
 from typing import Optional, List
-from collections import UserDict
 import os
 from functools import lru_cache
-from dataclasses import dataclass, asdict
 
-from edsl.enums import service_to_api_keyname
-from edsl.exceptions.general import MissingAPIKeyError
+from ..enums import service_to_api_keyname
+from ..exceptions.general import MissingAPIKeyError
 
-from edsl.language_models.key_management.KeyLookup import KeyLookup
-
-from edsl.language_models.key_management.models import (
+from .key_lookup import KeyLookup
+from .models import (
     APIKeyEntry,
     LimitEntry,
     APIIDEntry,
@@ -32,31 +29,61 @@ api_id_to_service = {"AWS_ACCESS_KEY_ID": "bedrock"}
 
 
 class KeyLookupBuilder:
-    """Builds KeyLookup options.
-
-    >>> builder = KeyLookupBuilder(fetch_order=("config", "env"))
-    >>> builder.DEFAULT_RPM
-    100
-    >>> builder.DEFAULT_TPM
-    2000000
-    >>> builder.fetch_order
-    ('config', 'env')
-
-    Test invalid fetch_order:
-    >>> try:
-    ...     KeyLookupBuilder(fetch_order=["config", "env"])  # Should be tuple
-    ... except ValueError as e:
-    ...     str(e)
-    'fetch_order must be a tuple'
-
-    Test service extraction:
-    >>> builder.extract_service("EDSL_SERVICE_RPM_OPENAI")
-    ('openai', 'rpm')
+    """Factory class for building KeyLookup objects by gathering credentials from multiple sources.
+    
+    KeyLookupBuilder is responsible for discovering, organizing, and consolidating API keys
+    and rate limits from various sources. It can pull credentials from:
+    
+    - Environment variables (env)
+    - Configuration files (config) 
+    - Remote services (coop)
+    
+    The builder handles the complexities of:
+    - Finding API keys with different naming conventions
+    - Merging rate limits from different sources
+    - Processing additional credentials like API IDs
+    - Prioritizing sources based on a configurable order
+    
+    Basic usage:
+        >>> builder = KeyLookupBuilder()
+        >>> keys = builder.build()
+        >>> # Now use keys to access service credentials
+        >>> keys['test'].api_token
+        'test'
+    
+    Customizing priorities:
+        >>> builder = KeyLookupBuilder(fetch_order=("config", "env"))
+        >>> builder.fetch_order
+        ('config', 'env')
+        >>> # 'env' has higher priority than 'config'
+    
+    Configuration parameters:
+        >>> builder = KeyLookupBuilder()
+        >>> builder.DEFAULT_RPM  # Default API calls per minute
+        100
+        >>> builder.DEFAULT_TPM  # Default tokens per minute
+        2000000
+    
+    Validation examples:
+        >>> try:
+        ...     KeyLookupBuilder(fetch_order=["config", "env"])  # Should be tuple
+        ... except ValueError as e:
+        ...     str(e)
+        'fetch_order must be a tuple'
+        
+        >>> builder = KeyLookupBuilder()
+        >>> builder.extract_service("EDSL_SERVICE_RPM_OPENAI")
+        ('openai', 'rpm')
+    
+    Technical Notes:
+        - The fetch_order parameter controls priority (later sources override earlier ones)
+        - Default rate limits are applied when not explicitly provided
+        - Maintains tracking of where each value came from for debugging
     """
 
     # DEFAULT_RPM = 10
     # DEFAULT_TPM = 2000000
-    from edsl.config import CONFIG
+    from ..config import CONFIG
 
     DEFAULT_RPM = int(CONFIG.get("EDSL_SERVICE_RPM_BASELINE"))
     DEFAULT_TPM = int(CONFIG.get("EDSL_SERVICE_TPM_BASELINE"))
@@ -66,7 +93,7 @@ class KeyLookupBuilder:
         fetch_order: Optional[tuple[str]] = None,
         coop: Optional["Coop"] = None,
     ):
-        from edsl.coop import Coop
+        from ..coop import Coop
 
         # Fetch order goes from lowest priority to highest priority
         if fetch_order is None:
@@ -99,34 +126,72 @@ class KeyLookupBuilder:
 
     @lru_cache
     def build(self) -> "KeyLookup":
-        """Build a KeyLookup instance.
-
-        >>> builder = KeyLookupBuilder()
-        >>> lookup = builder.build()
-        >>> isinstance(lookup, KeyLookup)
-        True
-        >>> lookup['test'].api_token  # Test service should always exist
-        'test'
+        """Build a KeyLookup instance with all discovered credentials.
+        
+        Processes all discovered API keys and rate limits from the configured sources
+        and builds a KeyLookup instance containing LanguageModelInput objects for
+        each valid service. This method is cached, so subsequent calls will return
+        the same instance unless the builder state changes.
+        
+        Returns:
+            KeyLookup: A populated KeyLookup instance with service credentials
+            
+        Examples:
+            >>> builder = KeyLookupBuilder()
+            >>> lookup = builder.build()
+            >>> isinstance(lookup, KeyLookup)
+            True
+            >>> lookup['test'].api_token  # Test service should always exist
+            'test'
+            
+        Technical Notes:
+            - Skips services with missing API keys
+            - Always includes a 'test' service for internal testing
+            - Uses lru_cache to avoid rebuilding unless necessary
+            - Each valid service gets a complete LanguageModelInput with
+              API token, rate limits, and optional API ID
         """
         d = {}
+        # Create entries for all discovered services
         for service in self.known_services:
             try:
                 d[service] = self.get_language_model_input(service)
             except MissingAPIKeyError:
-                pass
+                pass  # Skip services with missing API keys
 
+        # Always include a test service
         d.update({"test": LanguageModelInput(api_token="test", rpm=10, tpm=2000000)})
         return KeyLookup(d)
 
     def get_language_model_input(self, service: str) -> LanguageModelInput:
-        """Get the language model input for a given service.
-
-        >>> builder = KeyLookupBuilder()
-        >>> try:
-        ...     builder.get_language_model_input("nonexistent_service")
-        ... except MissingAPIKeyError as e:
-        ...     str(e)
-        "No key found for service 'nonexistent_service'"
+        """Construct a LanguageModelInput object for the specified service.
+        
+        Creates a complete LanguageModelInput object for the requested service by
+        combining the API key, rate limits, and optional API ID from the various 
+        data sources. This method assembles the disparate pieces of information
+        into a single configuration object.
+        
+        Args:
+            service: Name of the service to retrieve configuration for (e.g., 'openai')
+            
+        Returns:
+            LanguageModelInput: A configuration object with the service's credentials
+            
+        Raises:
+            MissingAPIKeyError: If the required API key for the service is not found
+            
+        Examples:
+            >>> builder = KeyLookupBuilder()
+            >>> try:
+            ...     builder.get_language_model_input("nonexistent_service")
+            ... except MissingAPIKeyError as e:
+            ...     str(e)
+            "No key found for service 'nonexistent_service'"
+            
+        Technical Notes:
+            - Uses default rate limits if none are specified
+            - Preserves information about where each value came from
+            - Supports services that require both API key and API ID
         """
         if (key_entries := self.key_data.get(service)) is None:
             raise MissingAPIKeyError(f"No key found for service '{service}'")
@@ -173,7 +238,7 @@ class KeyLookupBuilder:
         return dict(list(self.coop.fetch_rate_limit_config_vars().items()))
 
     def _config_key_value_pairs(self):
-        from edsl.config import CONFIG
+        from ..config import CONFIG
 
         return dict(list(CONFIG.items()))
 
@@ -302,3 +367,9 @@ class KeyLookupBuilder:
     def process_key_value_pairs(self) -> None:
         """Process all key-value pairs from the configured sources."""
         self.update_from_dict(self.get_key_value_pairs())
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/key_management/key_lookup_collection.py

@@ -0,0 +1,82 @@
+from collections import UserDict
+
+from .key_lookup_builder import KeyLookupBuilder
+from .key_lookup import KeyLookup
+
+class KeyLookupCollection(UserDict):
+    """Singleton collection for caching and reusing KeyLookup objects.
+    
+    KeyLookupCollection implements the singleton pattern to provide a global registry
+    of KeyLookup objects. It avoids rebuilding KeyLookup objects with the same 
+    fetch_order by storing and reusing previously created instances.
+    
+    This collection serves several purposes:
+    - Reduces overhead by avoiding redundant API key discovery
+    - Ensures consistency by reusing the same credentials throughout an application
+    - Provides a central access point for credential configuration
+    
+    The collection uses fetch_order tuples as keys and KeyLookup objects as values,
+    creating a new KeyLookup only when a new fetch_order is requested.
+    
+    Singleton behavior:
+        >>> collection = KeyLookupCollection()
+        >>> collection2 = KeyLookupCollection()
+        >>> collection is collection2  # Same instance
+        True
+        
+    Basic usage:
+        >>> collection = KeyLookupCollection()
+        >>> collection.add_key_lookup(("config", "env"))
+        >>> lookup = collection[("config", "env")]  # Get the stored KeyLookup
+        >>> isinstance(lookup, KeyLookup)
+        True
+        >>> ("config", "env") in collection
+        True
+        
+    Technical Notes:
+        - Uses __new__ to implement the singleton pattern
+        - Lazily creates KeyLookup objects only when requested
+        - Default fetch_order is ("config", "env") if not specified
+    """
+
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, *args, **kwargs):
+        if not hasattr(self, "_initialized"):
+            self.data = {}
+            self._initialized = True
+            super().__init__(*args, **kwargs)
+
+    def add_key_lookup(self, fetch_order=None):
+        """Add a KeyLookup to the collection with the specified fetch order.
+        
+        Creates a new KeyLookup using the KeyLookupBuilder with the given fetch_order,
+        or uses a default fetch_order of ("config", "env") if none is provided.
+        
+        The created KeyLookup is stored in the collection using the fetch_order as the key.
+        If a KeyLookup with the same fetch_order already exists, this method does nothing.
+        
+        Args:
+            fetch_order: Tuple specifying the order of sources to fetch credentials from.
+                        Later sources override earlier ones. If None, uses ("config", "env").
+                        
+        Examples:
+            >>> collection = KeyLookupCollection()
+            >>> collection.add_key_lookup(("config", "env", "coop"))
+            >>> ("config", "env", "coop") in collection
+            True
+            
+        Technical Notes:
+            - KeyLookup objects are created lazily only when needed
+            - Sources can include: "config", "env", "coop"
+            - The fetch_order determines credential priority
+        """
+        if fetch_order is None:
+            fetch_order = ("config", "env")
+        if fetch_order not in self.data:
+            self.data[fetch_order] = KeyLookupBuilder(fetch_order=fetch_order).build()

edsl/key_management/models.py

@@ -0,0 +1,218 @@
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+
+@dataclass
+class APIKeyEntry:
+    """Data structure for storing API key information with metadata.
+    
+    APIKeyEntry encapsulates an API key along with metadata about its service, 
+    environment variable name, and the source it was retrieved from. This structure
+    allows for tracking and debugging the origin of API keys.
+    
+    Attributes:
+        service: The service identifier (e.g., 'openai', 'anthropic')
+        name: The environment variable name (e.g., 'OPENAI_API_KEY')
+        value: The actual API key value
+        source: Where the key was obtained from (e.g., 'env', 'config')
+        
+    Examples:
+        >>> entry = APIKeyEntry.example()
+        >>> entry.service
+        'openai'
+        >>> entry.name
+        'OPENAI_API_KEY'
+        >>> entry.value
+        'sk-abcd1234'
+        >>> entry.source
+        'env'
+        
+    Technical Notes:
+        - Source values typically include: 'env', 'config', 'coop'
+        - Names follow the convention of the service's API documentation
+    """
+
+    service: str
+    name: str
+    value: str
+    source: Optional[str] = None
+
+    @classmethod
+    def example(cls):
+        return APIKeyEntry(
+            service="openai", name="OPENAI_API_KEY", value="sk-abcd1234", source="env"
+        )
+
+
+@dataclass
+class LimitEntry:
+    """Data structure for storing service rate limits with metadata.
+    
+    LimitEntry encapsulates rate limit information for a service, including
+    requests per minute (rpm) and tokens per minute (tpm) limits. It also 
+    tracks the source of each limit value to aid in debugging and understanding
+    configuration priority.
+    
+    Attributes:
+        service: The service identifier (e.g., 'openai', 'anthropic')
+        rpm: Requests per minute limit
+        tpm: Tokens per minute limit 
+        rpm_source: Where the rpm value was obtained from
+        tpm_source: Where the tpm value was obtained from
+        
+    Examples:
+        >>> limit = LimitEntry.example()
+        >>> limit.service
+        'openai'
+        >>> limit.rpm  # Requests per minute
+        60
+        >>> limit.tpm  # Tokens per minute
+        100000
+        >>> limit.rpm_source  # Source of the RPM value
+        'config'
+        >>> limit.tpm_source  # Source of the TPM value
+        'env'
+        
+    Technical Notes:
+        - Source values typically include: 'env', 'config', 'coop', 'default'
+        - rpm and tpm can come from different sources
+        - Default values are applied when specific limits aren't found
+    """
+
+    service: str
+    rpm: int
+    tpm: int
+    rpm_source: Optional[str] = None
+    tpm_source: Optional[str] = None
+
+    @classmethod
+    def example(cls):
+        return LimitEntry(
+            service="openai", rpm=60, tpm=100000, rpm_source="config", tpm_source="env"
+        )
+
+
+@dataclass
+class APIIDEntry:
+    """Data structure for storing API ID information with metadata.
+    
+    APIIDEntry encapsulates an API ID (like AWS Access Key ID) along with
+    metadata about its service, environment variable name, and source. Some
+    services like AWS Bedrock require both an API key and an API ID.
+    
+    Attributes:
+        service: The service identifier (e.g., 'bedrock' for AWS)
+        name: The environment variable name (e.g., 'AWS_ACCESS_KEY_ID')
+        value: The actual API ID value
+        source: Where the ID was obtained from (e.g., 'env', 'config')
+        
+    Examples:
+        >>> id_entry = APIIDEntry.example()
+        >>> id_entry.service
+        'bedrock'
+        >>> id_entry.name
+        'AWS_ACCESS_KEY_ID'
+        >>> id_entry.value
+        'AKIA1234'
+        >>> id_entry.source
+        'env'
+        
+    Technical Notes:
+        - Currently primarily used for AWS Bedrock integration
+        - Follows the same pattern as APIKeyEntry for consistency
+        - Source tracking helps with debugging configuration issues
+    """
+
+    service: str
+    name: str
+    value: str
+    source: Optional[str] = None
+
+    @classmethod
+    def example(cls):
+        return APIIDEntry(
+            service="bedrock", name="AWS_ACCESS_KEY_ID", value="AKIA1234", source="env"
+        )
+
+
+@dataclass
+class LanguageModelInput:
+    """Comprehensive configuration for a language model service.
+    
+    LanguageModelInput brings together all the configuration needed to interact with
+    a language model service, including authentication credentials and rate limits.
+    This is the primary data structure used by the language_models module to access
+    service credentials in a unified way.
+    
+    The class combines:
+    - API token for authentication
+    - Rate limits (rpm, tpm)
+    - Optional API ID for services that require it
+    - Source tracking for all values
+    
+    Attributes:
+        api_token: The API key/token for authentication
+        rpm: Requests per minute limit
+        tpm: Tokens per minute limit
+        api_id: Optional secondary ID (e.g., AWS Access Key ID)
+        token_source: Where the API token was obtained from
+        rpm_source: Where the rpm value was obtained from
+        tpm_source: Where the tpm value was obtained from
+        id_source: Where the api_id was obtained from
+        
+    Basic usage:
+        >>> lm_input = LanguageModelInput(api_token='sk-key123', rpm=60, tpm=100000)
+        >>> lm_input.api_token
+        'sk-key123'
+        
+    Example instance:
+        >>> lm_input = LanguageModelInput.example()
+        >>> lm_input.api_token
+        'sk-abcd123'
+        >>> lm_input.rpm
+        60
+        >>> lm_input.tpm
+        100000
+        >>> lm_input.api_id  # None for most services
+        
+    Serialization:
+        >>> d = lm_input.to_dict()
+        >>> isinstance(d, dict)
+        True
+        >>> LanguageModelInput.from_dict(d).api_token == lm_input.api_token
+        True
+        
+    Technical Notes:
+        - Used as values in the KeyLookup dictionary
+        - Centralizes all service configuration in one object
+        - Supports serialization for storage and transmission
+        - Preserves metadata about configuration sources
+    """
+
+    api_token: str
+    rpm: int
+    tpm: int
+    api_id: Optional[str] = None
+    token_source: Optional[str] = None
+    rpm_source: Optional[str] = None
+    tpm_source: Optional[str] = None
+    id_source: Optional[str] = None
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d)
+
+    @classmethod
+    def example(cls):
+        return LanguageModelInput(
+            api_token="sk-abcd123", tpm=100000, rpm=60, api_id=None
+        )
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

edsl/language_models/__init__.py

@@ -1,2 +1,7 @@
-from edsl.language_models.LanguageModel import LanguageModel
-from edsl.language_models.model import Model
+from .language_model import LanguageModel
+from .model import Model
+from .model_list import ModelList
+
+from .exceptions import LanguageModelBadResponseError
+
+__all__ = ["Model", "ModelList", "LanguageModelBadResponseError"]

edsl/language_models/{ComputeCost.py → compute_cost.py}

@@ -1,7 +1,16 @@
-from typing import Any, Union
+from typing import Any, Union, TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from .language_model import LanguageModel
 
 class ComputeCost:
+    """Computes the dollar cost of a raw response.
+    
+    # TODO: Add doctests
+    >>> True
+    True
+    
+    """
     def __init__(self, language_model: "LanguageModel"):
         self.language_model = language_model
         self._price_lookup = None
@@ -9,7 +18,7 @@ class ComputeCost:
     @property
     def price_lookup(self):
         if self._price_lookup is None:
-            from edsl.coop import Coop
+            from ..coop import Coop
 
             c = Coop()
             self._price_lookup = c.fetch_prices()
@@ -19,7 +28,7 @@ class ComputeCost:
         """Return the dollar cost of a raw response."""
 
         usage = self.get_usage_dict(raw_response)
-        from edsl.coop import Coop
+        from ..coop import Coop
 
         c = Coop()
         price_lookup = c.fetch_prices()
@@ -61,3 +70,9 @@ class ComputeCost:
                 return f"Could not compute output price - {e}"
 
         return input_cost + output_cost
+
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()

edsl/{exceptions/language_models.py → language_models/exceptions.py}

@@ -1,8 +1,9 @@
 from textwrap import dedent
 from typing import Optional
 
+from ..base import BaseException
 
-class LanguageModelExceptions(Exception):
+class LanguageModelExceptions(BaseException):
     explanation = (
         "This is the base class for all exceptions in the LanguageModel class."
     )