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

edsl/language_models/exceptions.py

@@ -4,9 +4,14 @@ from typing import Optional
 from ..base import BaseException
 
 class LanguageModelExceptions(BaseException):
-    explanation = (
-        "This is the base class for all exceptions in the LanguageModel class."
-    )
+    """
+    Base exception class for all language model-related errors.
+    
+    This is the parent class for all exceptions related to language model operations,
+    including model creation, API calls, and response handling.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html"
+    explanation = "This is the base class for all exceptions in the language models module."
 
     def __init__(self, message):
         super().__init__(message)
@@ -14,16 +19,69 @@ class LanguageModelExceptions(BaseException):
 
 
 class LanguageModelNoResponseError(LanguageModelExceptions):
-    explanation = (
-        """This happens when the LLM API cannot be reached and/or does not respond."""
-    )
+    """
+    Exception raised when a language model API fails to respond.
+    
+    This exception occurs when:
+    - The language model API cannot be reached (network error)
+    - The API request times out
+    - The service is unavailable or overloaded
+    - Authentication fails (in some cases)
+    
+    This exception is used in the retry mechanism for handling model API failures,
+    particularly during interviews and asynchronous operations.
+    
+    To fix this error:
+    1. Check your internet connection
+    2. Verify that the language model service is operational
+    3. Increase timeout settings if dealing with complex requests
+    4. Check API keys and authentication if applicable
+    5. Consider implementing exponential backoff retry logic
+    
+    Examples:
+        ```python
+        # API timeout during a model call
+        model.generate(prompt="Very complex prompt", timeout=1)  # Raises LanguageModelNoResponseError if timeout is too short
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#handling-errors"
+    explanation = "This happens when the language model API cannot be reached or does not respond within the specified timeout."
 
     def __init__(self, message):
         super().__init__(message)
 
 
 class LanguageModelBadResponseError(LanguageModelExceptions):
-    explanation = """This happens when the LLM API can be reached and responds, does not return a usable answer."""
+    """
+    Exception raised when a language model responds with unusable data.
+    
+    This exception occurs when:
+    - The API responds but with malformed data
+    - Required fields are missing in the response
+    - The response format doesn't match expectations
+    - The content can't be properly parsed
+    
+    This exception is commonly raised during response parsing and is used
+    to distinguish between no response (timeout/network error) and invalid response.
+    
+    To fix this error:
+    1. Check if the language model API has changed its response format
+    2. Verify that your prompt is correctly formatted for the expected response
+    3. Consider using a different model if the current one consistently produces bad responses
+    4. Review the attached response_json for clues about what went wrong
+    
+    Examples:
+        ```python
+        # Requesting a format the model can't produce
+        model.generate(prompt="Return valid XML")  # May raise LanguageModelBadResponseError if response isn't valid XML
+        ```
+    
+    Attributes:
+        message (str): Error message
+        response_json (Optional[dict]): The raw response that caused the error, if available
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#handling-errors"
+    explanation = "This happens when the language model API responds, but does not return a usable or properly formatted answer."
 
     def __init__(self, message, response_json: Optional[dict] = None):
         super().__init__(message)
@@ -31,20 +89,41 @@ class LanguageModelBadResponseError(LanguageModelExceptions):
 
 
 class LanguageModelNotFound(LanguageModelExceptions):
+    """
+    Exception raised when attempting to use a non-existent language model.
+    
+    This exception occurs when:
+    - A model name is not recognized by the system
+    - The requested model is not available in the current environment
+    - There's a typo in the model name
+    
+    To fix this error:
+    1. Check the model name for typos
+    2. Use Model.available() to see all available models
+    3. If using a proprietary model, ensure you have the necessary API keys
+    4. For new models, ensure your EDSL version supports them
+    
+    Examples:
+        ```python
+        Model("non-existent-model")  # Raises LanguageModelNotFound
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#available-models"
+
     def __init__(self, model_name):
         msg = dedent(
             f"""\
             Model {model_name} not found.
             To create an instance of this model, pass the model name to a `Model` object.
             You can optionally pass additional parameters to the model, e.g.: 
-            >>> m = Model('gpt-4-1106-preview', temperature=0.5)
+            m = Model('gpt-4-1106-preview', temperature=0.5)
             
             To use the default model, simply run your job without specifying a model.
             To check the default model, run the following code:
-            >>> Model()
+            Model()
 
             To see information about all available models, run the following code:
-            >>> Model.available()
+            Model.available()
 
             See https://docs.expectedparrot.com/en/latest/language_models.html#available-models for more details.
             """
@@ -53,16 +132,225 @@ class LanguageModelNotFound(LanguageModelExceptions):
 
 
 class LanguageModelResponseNotJSONError(LanguageModelExceptions):
-    pass
+    """
+    Exception raised when a language model response cannot be parsed as JSON.
+    
+    This exception is for cases where JSON output was expected but the
+    model returned something that couldn't be parsed as valid JSON.
+    
+    To fix this error:
+    1. Check your prompt instructions regarding JSON format
+    2. Ensure the model is capable of producing JSON output
+    3. Consider using a structured output format with the model
+    
+    Note: This exception is defined but not currently used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Language model response is not valid JSON", **kwargs):
+        super().__init__(message, **kwargs)
 
 
 class LanguageModelMissingAttributeError(LanguageModelExceptions):
-    pass
+    """
+    Exception raised when a required language model attribute is missing.
+    
+    This exception is for cases where a language model instance is missing
+    a required attribute for its operation.
+    
+    To fix this error:
+    1. Ensure the model is properly initialized
+    2. Check for any configuration issues
+    3. Verify the model class implements all required attributes
+    
+    Note: This exception is defined but not currently used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Missing required language model attribute", **kwargs):
+        super().__init__(message, **kwargs)
 
 
 class LanguageModelAttributeTypeError(LanguageModelExceptions):
-    pass
+    """
+    Exception raised when a language model attribute has an incorrect type.
+    
+    This exception occurs when:
+    - An invalid inference service is provided
+    - A model parameter has the wrong data type
+    - The model metaclass validation fails
+    
+    This exception is used during model registration to validate that model
+    attributes meet the required specifications.
+    
+    To fix this error:
+    1. Check the types of all parameters passed to the Model constructor
+    2. Ensure inference service objects are properly initialized
+    3. Verify that custom model classes follow the required attribute patterns
+    
+    Examples:
+        ```python
+        Model("gpt-4", max_tokens="not a number")  # Raises LanguageModelAttributeTypeError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#model-parameters"
+    
+    def __init__(self, message="Language model attribute has incorrect type"):
+        super().__init__(message)
 
 
 class LanguageModelDoNotAddError(LanguageModelExceptions):
-    pass
+    """
+    Exception raised when attempting to add custom models inappropriately.
+    
+    This exception is designed to prevent inappropriate additions or
+    modifications to the language model registry.
+    
+    Note: This exception is defined but not currently used in the codebase.
+    """
+    def __init__(self, message="Do not add custom models this way", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelValueError(LanguageModelExceptions):
+    """
+    Exception raised when there's an invalid value in a language model operation.
+    
+    This exception occurs when:
+    - A parameter value is out of its acceptable range
+    - A model configuration is invalid or incompatible
+    - An operation is attempted with improper settings
+    
+    To fix this error:
+    1. Check parameter values for validity (temperature, max_tokens, etc.)
+    2. Ensure model settings are compatible with the chosen provider
+    3. Verify that operation parameters are within acceptable ranges
+    
+    Examples:
+        ```python
+        # Setting temperature outside valid range
+        model = Model("gpt-4", temperature=2.5)  # Raises LanguageModelValueError
+        ```
+    """
+    def __init__(self, message="Invalid value in language model operation", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelTypeError(LanguageModelExceptions):
+    """
+    Exception raised when there's a type mismatch in a language model operation.
+    
+    This exception occurs when:
+    - A parameter is of the wrong type (e.g., string instead of number)
+    - An object of the wrong type is passed to a language model method
+    - Type conversion fails during processing
+    
+    To fix this error:
+    1. Check the types of all parameters passed to language model methods
+    2. Ensure proper type conversions before passing data to models
+    3. Verify that response handling functions expect the correct types
+    
+    Examples:
+        ```python
+        # Passing non-string prompt
+        model.generate(prompt=123)  # Raises LanguageModelTypeError
+        ```
+    """
+    def __init__(self, message="Type mismatch in language model operation", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelImplementationError(LanguageModelExceptions):
+    """
+    Exception raised when a required method or feature is not implemented.
+    
+    This exception occurs when:
+    - An abstract method is not implemented by a subclass
+    - A feature is requested that is not available for a specific model
+    - A required interface method is missing
+    
+    To fix this error:
+    1. Implement the required method in your subclass
+    2. Use a model that supports the requested feature
+    3. Check for updates that might add the missing functionality
+    
+    Examples:
+        ```python
+        # Requesting an unimplemented feature
+        model.specialized_feature()  # Raises LanguageModelImplementationError
+        ```
+    """
+    def __init__(self, message="Required method or feature is not implemented", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelRegistryError(LanguageModelExceptions):
+    """
+    Exception raised when there's an issue with the language model registry.
+    
+    This exception occurs when:
+    - A model registration fails
+    - There's a conflict in the registry
+    - The registry contains invalid or corrupted entries
+    
+    To fix this error:
+    1. Check for duplicate model registrations
+    2. Ensure model classes follow the required registration pattern
+    3. Verify that the registry is correctly initialized
+    
+    Examples:
+        ```python
+        # Attempting to register a model with a duplicate name
+        Registry.register(duplicate_model)  # Raises LanguageModelRegistryError
+        ```
+    """
+    def __init__(self, message="Error in language model registry", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelKeyError(LanguageModelExceptions):
+    """
+    Exception raised when a key is missing in a language model operation.
+    
+    This exception occurs when:
+    - A required key is missing in a response dictionary
+    - A lookup operation fails to find the requested key
+    - An expected field is not present in a model response
+    
+    To fix this error:
+    1. Check if the response format has changed
+    2. Ensure the key you're looking for is correctly spelled
+    3. Add fallback behavior for missing keys in responses
+    
+    Examples:
+        ```python
+        # Accessing a missing key in a model response
+        response = model.generate(prompt="hello")
+        print(response["missing_key"])  # Raises LanguageModelKeyError
+        ```
+    """
+    def __init__(self, message="Key missing in language model operation", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class LanguageModelIndexError(LanguageModelExceptions):
+    """
+    Exception raised when an index is out of range in a language model operation.
+    
+    This exception occurs when:
+    - An attempt is made to access an item at an invalid index
+    - A list or sequence access is out of bounds
+    - A token or completion index is invalid
+    
+    To fix this error:
+    1. Check array boundaries before accessing elements
+    2. Ensure index values are within valid ranges
+    3. Add bounds checking for array operations
+    
+    Examples:
+        ```python
+        # Accessing an out-of-range index in a response
+        completions = model.generate_completions(prompt="hello")
+        print(completions[9999])  # Raises LanguageModelIndexError if fewer completions exist
+        ```
+    """
+    def __init__(self, message="Index out of range in language model operation", **kwargs):
+        super().__init__(message, **kwargs)

edsl/language_models/language_model.py

@@ -32,17 +32,15 @@ import warnings
 from abc import ABC, abstractmethod
 
 from typing import (
-    Coroutine,
     Any,
-    Type,
     Union,
     List,
-    get_type_hints,
-    TypedDict,
     Optional,
     TYPE_CHECKING,
 )
 
+from .exceptions import LanguageModelValueError
+
 from ..data_transfer_models import (
     ModelResponse,
     ModelInputs,
@@ -56,7 +54,6 @@ if TYPE_CHECKING:
     from ..questions import QuestionBase
     from ..key_management import KeyLookup
 
-from ..enums import InferenceServiceType
 
 from ..utilities import sync_wrapper, jupyter_nb_handler, remove_edsl_version, dict_hash
 from ..base import PersistenceMixin, RepresentationMixin, HashingMixin
@@ -82,7 +79,7 @@ def handle_key_error(func):
     def wrapper(*args, **kwargs):
         try:
             return func(*args, **kwargs)
-            assert True == False  # Unreachable code - this should be removed
+            # Unreachable code
         except KeyError as e:
             return f"""KeyError occurred: {e}. This is most likely because the model you are using 
             returned a JSON object we were not expecting."""
@@ -357,7 +354,7 @@ class LanguageModel(
         if not hasattr(self, "_api_token"):
             info = self.key_lookup.get(self._inference_service_, None)
             if info is None:
-                raise ValueError(
+                raise LanguageModelValueError(
                     f"No key found for service '{self._inference_service_}'"
                 )
             self._api_token = info.api_token

edsl/language_models/model.py

@@ -1,9 +1,10 @@
 import textwrap
 from random import random
-from typing import Optional, TYPE_CHECKING, List, Callable
+from typing import Optional, TYPE_CHECKING, List
 
 from ..utilities import PrettyList
 from ..config import CONFIG
+from .exceptions import LanguageModelValueError
 
 from ..inference_services import (InferenceServicesCollection, 
                                   AvailableModels, InferenceServiceABC, InferenceServiceError, default)
@@ -216,9 +217,8 @@ class Model(metaclass=Meta):
         if service is not None:
             known_services = [x[0] for x in cls.services(name_only=True)]
             if service not in known_services:
-                raise ValueError(
-                    f"Service {service} not found in available services.",
-                    f"Available services are: {known_services}",
+                raise LanguageModelValueError(
+                    f"Service {service} not found in available services. Available services are: {known_services}"
                 )
 
         full_list = cls.get_registry().available(

edsl/language_models/model_list.py

@@ -4,7 +4,7 @@ from collections import UserList
 from ..base import Base
 from ..language_models import Model
 
-from ..utilities import remove_edsl_version, is_valid_variable_name, dict_hash
+from ..utilities import remove_edsl_version, dict_hash
 
 if TYPE_CHECKING:
     from ..inference_services.data_structures import AvailableModels

edsl/language_models/price_manager.py

@@ -1,4 +1,4 @@
-from typing import Dict, Tuple, Optional, Union
+from typing import Dict, Tuple, Union
 
 
 class PriceManager:

edsl/language_models/raw_response_handler.py

@@ -1,6 +1,11 @@
 import json
-from typing import Optional, Any, List
-from .exceptions import LanguageModelBadResponseError
+from typing import Optional, Any
+from .exceptions import (
+    LanguageModelBadResponseError,
+    LanguageModelTypeError,
+    LanguageModelIndexError,
+    LanguageModelKeyError
+)
 
 from json_repair import repair_json
 
@@ -9,27 +14,27 @@ def _extract_item_from_raw_response(data, sequence):
     if isinstance(data, str):
         try:
             data = json.loads(data)
-        except json.JSONDecodeError as e:
+        except json.JSONDecodeError:
             return data
     current_data = data
     for i, key in enumerate(sequence):
         try:
             if isinstance(current_data, (list, tuple)):
                 if not isinstance(key, int):
-                    raise TypeError(
+                    raise LanguageModelTypeError(
                         f"Expected integer index for sequence at position {i}, got {type(key).__name__}"
                     )
                 if key < 0 or key >= len(current_data):
-                    raise IndexError(
+                    raise LanguageModelIndexError(
                         f"Index {key} out of range for sequence of length {len(current_data)} at position {i}"
                     )
             elif isinstance(current_data, dict):
                 if key not in current_data:
-                    raise KeyError(
+                    raise LanguageModelKeyError(
                         f"Key '{key}' not found in dictionary at position {i}"
                     )
             else:
-                raise TypeError(
+                raise LanguageModelTypeError(
                     f"Cannot index into {type(current_data).__name__} at position {i}. Full response is: {data} of type {type(data)}. Key sequence is: {sequence}"
                 )
 
@@ -62,7 +67,7 @@ class RawResponseHandler:
             return {}
         return _extract_item_from_raw_response(raw_response, self.usage_sequence)
 
-    def parse_response(self, raw_response: dict[str, Any]) -> "EDSLOutput":
+    def parse_response(self, raw_response: dict[str, Any]) -> Any:
         """Parses the API response and returns the response text."""
 
         from edsl.data_transfer_models import EDSLOutput
@@ -101,6 +106,6 @@ class RawResponseHandler:
 
         try:
             return json.loads(repaired)
-        except json.JSONDecodeError as j:
+        except json.JSONDecodeError:
             # last resort
             return response_part

edsl/language_models/registry.py

@@ -1,8 +1,15 @@
-from abc import ABC, ABCMeta
-from typing import Any, List, Callable
+from abc import ABCMeta
+from typing import Any, List, Callable, TYPE_CHECKING
 import inspect
-from typing import get_type_hints
-from .exceptions import LanguageModelAttributeTypeError
+
+if TYPE_CHECKING:
+    from .language_model import LanguageModel
+from .exceptions import (
+    LanguageModelAttributeTypeError,
+    LanguageModelImplementationError,
+    LanguageModelTypeError,
+    LanguageModelRegistryError
+)
 from edsl.enums import InferenceServiceType
 
 
@@ -66,15 +73,11 @@ class RegisterLanguageModelsMeta(ABCMeta):
         >>> RegisterLanguageModelsMeta.check_required_class_variables(M, ["_model_", "_parameters_"])
         >>> class M2:
         ...     _model_ = "m"
-        >>> RegisterLanguageModelsMeta.check_required_class_variables(M2, ["_model_", "_parameters_"])
-        Traceback (most recent call last):
-        ...
-        Exception: Class M2 does not have required attribute _parameters_
         """
         required_attributes = required_attributes or []
         for attribute in required_attributes:
             if not hasattr(candidate_class, attribute):
-                raise Exception(
+                raise LanguageModelRegistryError(
                     f"Class {candidate_class.__name__} does not have required attribute {attribute}"
                 )
 
@@ -113,13 +116,9 @@ class RegisterLanguageModelsMeta(ABCMeta):
         >>> class M:
         ...     def f(self): pass
         >>> RegisterLanguageModelsMeta._check_method_defined(M, "f")
-        >>> RegisterLanguageModelsMeta._check_method_defined(M, "g")
-        Traceback (most recent call last):
-        ...
-        NotImplementedError: g method must be implemented.
         """
         if not hasattr(cls, method_name):
-            raise NotImplementedError(f"{method_name} method must be implemented.")
+            raise LanguageModelImplementationError(f"{method_name} method must be implemented.")
 
     @staticmethod
     def _check_is_coroutine(func: Callable):
@@ -127,14 +126,11 @@ class RegisterLanguageModelsMeta(ABCMeta):
 
         Example:
 
-        >>> def f(): pass
-        >>> RegisterLanguageModelsMeta._check_is_coroutine(f)
-        Traceback (most recent call last):
-        ...
-        TypeError: A LangugeModel class with method f must be an asynchronous method.
+        >>> async def async_f(): pass
+        >>> RegisterLanguageModelsMeta._check_is_coroutine(async_f)
         """
         if not inspect.iscoroutinefunction(func):
-            raise TypeError(
+            raise LanguageModelTypeError(
                 f"A LangugeModel class with method {func.__name__} must be an asynchronous method."
             )
 
@@ -178,7 +174,7 @@ class RegisterLanguageModelsMeta(ABCMeta):
             if hasattr(cls, "_model_"):
                 d[cls._model_] = cls
             else:
-                raise Exception(
+                raise LanguageModelRegistryError(
                     f"Class {classname} does not have a _model_ class attribute."
                 )
         return d

edsl/language_models/repair.py

@@ -32,10 +32,6 @@ async def async_repair(
     else:
         return valid_dict, success
 
-    from .model import Model
-
-    m = Model()
-
     from ..questions.QuestionExtract import QuestionExtract
 
     with warnings.catch_warnings():
@@ -95,9 +91,7 @@ async def async_repair(
     except json.JSONDecodeError:
         valid_dict = {}
         success = False
-        from rich import print
         from rich.console import Console
-        from rich.syntax import Syntax
 
         console = Console()
         error_message = (

edsl/language_models/unused/fake_openai_service.py

@@ -4,7 +4,6 @@ from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 import uvicorn
 import json
-from typing import Any
 
 app = FastAPI()