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

edsl/inference_services/exceptions.py

@@ -2,4 +2,135 @@ from ..base import BaseException
 
 
 class InferenceServiceError(BaseException):
-    relevant_doc = "https://docs.expectedparrot.com/"
+    """
+    Exception raised when an error occurs with an inference service.
+    
+    This exception is raised in the following scenarios:
+    - When a service connection fails or times out
+    - When the API returns an error response (e.g., rate limit exceeded)
+    - When model parameters are invalid for the specified service
+    - When the service doesn't support requested functionality
+    - When there's an issue with authentication or API keys
+    
+    To fix this error:
+    1. Check your API key is valid and has appropriate permissions
+    2. Verify your network connection is stable
+    3. Ensure the requested model is available on the service
+    4. Check if provided parameters are valid for the model
+    5. Verify you're not exceeding service rate limits
+    
+    If the issue persists, you may need to:
+    - Switch to a different service provider
+    - Use a different model with similar capabilities
+    - Implement retry logic with exponential backoff
+    
+    Examples:
+        ```python
+        # Authentication error
+        model = Model("gpt-4", api_key="invalid-key")  # Raises InferenceServiceError
+        
+        # Invalid model parameters
+        model = Model("claude-3-opus", temperature=2.5)  # Raises InferenceServiceError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_inference.html"
+
+
+class InferenceServiceValueError(InferenceServiceError):
+    """
+    Exception raised when invalid values are provided to inference services.
+    
+    This exception occurs when parameters, configurations, or inputs for an inference
+    service have invalid values, such as:
+    - Invalid model names or identifiers
+    - Out-of-range parameter values (e.g., temperature > 1.0)
+    - Incorrect service names
+    - Invalid regular expressions for pattern matching
+    
+    Examples:
+        ```python
+        # Invalid model name
+        model = Model("non-existent-model")  # Raises InferenceServiceValueError
+        
+        # Out-of-range temperature
+        model = Model("gpt-4", temperature=2.5)  # Raises InferenceServiceValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#model-parameters"
+
+
+class InferenceServiceIndexError(InferenceServiceError):
+    """
+    Exception raised when attempting to access an invalid index in a collection.
+    
+    This exception occurs when trying to access elements outside the valid range 
+    of an inference service's internal collections, such as:
+    - Accessing results that don't exist
+    - Using an invalid index in a list of models or services
+    
+    Examples:
+        ```python
+        service_models = get_available_models_for_service("openai")
+        model = service_models[999]  # Raises InferenceServiceIndexError if there aren't 1000 models
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#available-models"
+
+
+class InferenceServiceNotImplementedError(InferenceServiceError):
+    """
+    Exception raised when a requested feature or method is not implemented.
+    
+    This exception occurs when trying to use functionality that is defined in
+    the interface but not yet implemented in a particular service, such as:
+    - Using a feature only available in certain services
+    - Calling methods that are not implemented in the concrete service class
+    - Using functionality that is planned but not yet available
+    
+    Examples:
+        ```python
+        # Using a feature only available in certain services
+        model = Model("test-model")
+        model.streaming_generate()  # Raises InferenceServiceNotImplementedError if streaming is not supported
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/language_models.html#available-models"
+
+
+class InferenceServiceRuntimeError(InferenceServiceError):
+    """
+    Exception raised when a runtime error occurs during inference.
+    
+    This exception occurs when there is a problem during the execution
+    of an inference service operation, such as:
+    - Service availability changes during operation
+    - Network interruptions during API calls
+    - Resource limits reached during execution
+    
+    Examples:
+        ```python
+        # Service becomes unavailable during operation
+        model = Model("gpt-4")
+        model.generate()  # Might raise InferenceServiceRuntimeError if service goes down mid-request
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/remote_inference.html"
+
+
+class InferenceServiceEnvironmentError(InferenceServiceError):
+    """
+    Exception raised when there's an issue with the environment configuration.
+    
+    This exception occurs when the environment is not properly set up for
+    using a particular inference service, such as:
+    - Missing required environment variables (API keys, endpoints)
+    - Improperly formatted environment variables
+    - Insufficient permissions in the environment
+    
+    Examples:
+        ```python
+        # Missing required environment variables
+        model = Model("azure-gpt4")  # Raises InferenceServiceEnvironmentError if AZURE_API_KEY is not set
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/api_keys.html"

edsl/inference_services/inference_service_abc.py

@@ -1,7 +1,6 @@
 from abc import abstractmethod, ABC
 import re
 from datetime import datetime, timedelta
-from ..config import CONFIG
 
 
 class InferenceServiceABC(ABC):
@@ -27,7 +26,8 @@ class InferenceServiceABC(ABC):
         ]
         for attr in must_have_attributes:
             if not hasattr(cls, attr):
-                raise NotImplementedError(
+                from edsl.inference_services.exceptions import InferenceServiceNotImplementedError
+                raise InferenceServiceNotImplementedError(
                     f"Class {cls.__name__} must have a '{attr}' attribute."
                 )
 

edsl/inference_services/inference_services_collection.py

@@ -1,8 +1,7 @@
-from functools import lru_cache
 from collections import defaultdict
-from typing import Optional, Protocol, Dict, List, Tuple, TYPE_CHECKING, Literal, Type, TypeVar, Union
-import os
+from typing import Optional, Protocol, Dict, List, Tuple, TYPE_CHECKING
 
+from edsl.enums import InferenceServiceLiteral
 from .inference_service_abc import InferenceServiceABC
 from .available_model_fetcher import AvailableModelFetcher
 from .exceptions import InferenceServiceError
@@ -17,9 +16,6 @@ class ModelCreator(Protocol):
         ...
 
 
-from edsl.enums import InferenceServiceLiteral
-
-
 class ModelResolver:
     def __init__(
         self,

edsl/inference_services/registry.py

@@ -1,8 +1,9 @@
 from .inference_services_collection import InferenceServicesCollection
 
-from .services import *
-from .services import __all__
+# Import services module
+from . import services
 
-services = [globals()[service_name] for service_name in __all__ if service_name in globals()]
+# Use __all__ from services to get service class names
+services = [getattr(services, service_name) for service_name in services.__all__]
 
 default = InferenceServicesCollection(services)

edsl/inference_services/service_availability.py

@@ -74,7 +74,8 @@ class ServiceAvailability:
                 continue
 
         # If we get here, all sources failed
-        raise RuntimeError(
+        from edsl.inference_services.exceptions import InferenceServiceRuntimeError
+        raise InferenceServiceRuntimeError(
             f"All sources failed to fetch models. Last error: {last_error}"
         )
 

edsl/inference_services/services/anthropic_service.py

@@ -1,10 +1,13 @@
 import os
-from typing import Any, Optional, List
+from typing import Any, Optional, List, TYPE_CHECKING
 from anthropic import AsyncAnthropic
 
 from ..inference_service_abc import InferenceServiceABC
 from ...language_models import LanguageModel
 
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore as Files
+
 
 class AnthropicService(InferenceServiceABC):
     """Anthropic service class."""

edsl/inference_services/services/aws_bedrock.py

@@ -1,12 +1,12 @@
 import os
-from typing import Any, List, Optional
-import re
+from typing import Any, List, Optional, TYPE_CHECKING
 import boto3
 from botocore.exceptions import ClientError
 from ..inference_service_abc import InferenceServiceABC
 from ...language_models import LanguageModel
-import json
-from edsl.utilities.utilities import fix_partial_correct_response
+
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore
 
 
 class AwsBedrockService(InferenceServiceABC):
@@ -78,9 +78,8 @@ class AwsBedrockService(InferenceServiceABC):
             ) -> dict[str, Any]:
                 """Calls the AWS Bedrock API and returns the API response."""
 
-                api_token = (
-                    self.api_token
-                )  # call to check the if env variables are set.
+                # Ensure credentials are available
+                _ = self.api_token  # call to check if env variables are set.
 
                 region = os.getenv("AWS_REGION", "us-east-1")
                 client = boto3.client("bedrock-runtime", region_name=region)
@@ -91,11 +90,13 @@ class AwsBedrockService(InferenceServiceABC):
                         "content": [{"text": user_prompt}],
                     }
                 ]
-                system = [
-                    {
-                        "text": system_prompt,
-                    }
-                ]
+                # We'll need to handle system prompt in the future
+                # Commented out to avoid unused variable warning
+                # system_content = [
+                #     {
+                #         "text": system_prompt,
+                #     }
+                # ]
                 try:
                     response = client.converse(
                         modelId=self._model_,

edsl/inference_services/services/azure_ai.py

@@ -1,16 +1,15 @@
 import os
-from typing import Any, Optional, List
-import re
+from typing import Any, Optional, List, TYPE_CHECKING
 from openai import AsyncAzureOpenAI
 from ..inference_service_abc import InferenceServiceABC
 from ...language_models import LanguageModel
 
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore
+
 from azure.ai.inference.aio import ChatCompletionsClient
 from azure.core.credentials import AzureKeyCredential
 from azure.ai.inference.models import SystemMessage, UserMessage
-import asyncio
-import json
-from edsl.utilities.utilities import fix_partial_correct_response
 
 
 def json_handle_none(value: Any) -> Any:
@@ -47,7 +46,8 @@ class AzureAIService(InferenceServiceABC):
         out = []
         azure_endpoints = os.getenv("AZURE_ENDPOINT_URL_AND_KEY", None)
         if not azure_endpoints:
-            raise EnvironmentError(f"AZURE_ENDPOINT_URL_AND_KEY is not defined")
+            from edsl.inference_services.exceptions import InferenceServiceEnvironmentError
+            raise InferenceServiceEnvironmentError("AZURE_ENDPOINT_URL_AND_KEY is not defined")
         azure_endpoints = azure_endpoints.split(",")
         for data in azure_endpoints:
             try:
@@ -131,21 +131,23 @@ class AzureAIService(InferenceServiceABC):
                     api_key = cls._model_id_to_endpoint_and_key[model_name][
                         "azure_endpoint_key"
                     ]
-                except:
+                except (KeyError, TypeError):
                     api_key = None
 
                 if not api_key:
-                    raise EnvironmentError(
+                    from edsl.inference_services.exceptions import InferenceServiceEnvironmentError
+                    raise InferenceServiceEnvironmentError(
                         f"AZURE_ENDPOINT_URL_AND_KEY doesn't have the endpoint:key pair for your model: {model_name}"
                     )
 
                 try:
                     endpoint = cls._model_id_to_endpoint_and_key[model_name]["endpoint"]
-                except:
+                except (KeyError, TypeError):
                     endpoint = None
 
                 if not endpoint:
-                    raise EnvironmentError(
+                    from edsl.inference_services.exceptions import InferenceServiceEnvironmentError
+                    raise InferenceServiceEnvironmentError(
                         f"AZURE_ENDPOINT_URL_AND_KEY doesn't have the endpoint:key pair for your model: {model_name}"
                     )
 

edsl/inference_services/services/deep_infra_service.py

@@ -1,7 +1,4 @@
-import aiohttp
-import json
-import requests
-from typing import Any, List
+from typing import List
 
 
 from .open_ai_service import OpenAIService

edsl/inference_services/services/deep_seek_service.py

@@ -1,9 +1,5 @@
-import aiohttp
-import json
-import requests
-from typing import Any, List
+from typing import List
 
-from ...language_models import LanguageModel
 from .open_ai_service import OpenAIService
 
 

edsl/inference_services/services/google_service.py

@@ -1,5 +1,5 @@
 # import os
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
 import google
 import google.generativeai as genai
 from google.generativeai.types import GenerationConfig
@@ -7,6 +7,10 @@ from google.api_core.exceptions import InvalidArgument
 
 # from edsl.exceptions.general import MissingAPIKeyError
 from ..inference_service_abc import InferenceServiceABC
+from ...language_models import LanguageModel
+
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore as Files
 #from ...coop import Coop
 
 safety_settings = [
@@ -115,7 +119,7 @@ class GoogleService(InferenceServiceABC):
                             safety_settings=safety_settings,
                             system_instruction=system_prompt,
                         )
-                    except InvalidArgument as e:
+                    except InvalidArgument:
                         print(
                             f"This model, {self._model_}, does not support system_instruction"
                         )

edsl/inference_services/services/groq_service.py

@@ -1,4 +1,4 @@
-from typing import Any, List
+from typing import List
 
 import groq
 

edsl/inference_services/services/mistral_ai_service.py

@@ -1,12 +1,14 @@
 import os
-from typing import Any, List, Optional
-import asyncio
+from typing import Any, List, Optional, TYPE_CHECKING
 from mistralai import Mistral
 
 
 from ..inference_service_abc import InferenceServiceABC
 from ...language_models import LanguageModel
 
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore
+
 
 class MistralAIService(InferenceServiceABC):
     """Mistral AI service class."""

edsl/inference_services/services/ollama_service.py

@@ -1,4 +1,4 @@
-from typing import Any, List
+from typing import List
 
 from .open_ai_service import OpenAIService
 

edsl/inference_services/services/open_ai_service.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import Any, List, Optional, Dict, NewType
+from typing import Any, List, Optional, Dict, NewType, TYPE_CHECKING
 import os
 
 import openai
@@ -7,9 +7,11 @@ import openai
 from ..inference_service_abc import InferenceServiceABC
 from ...language_models import LanguageModel
 from ..rate_limits_cache import rate_limits
-from ...utilities.utilities import fix_partial_correct_response
 
-from ...config import CONFIG
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore as Files
+    from ....invigilators.invigilator_base import InvigilatorBase as InvigilatorAI
+
 
 APIToken = NewType("APIToken", str)
 
@@ -103,7 +105,7 @@ class OpenAIService(InferenceServiceABC):
                     for m in cls.get_model_list(api_key=api_token)
                     if m.id not in cls.model_exclude_list
                 ]
-            except Exception as e:
+            except Exception:
                 raise
         return cls._models_list_cache
 
@@ -165,7 +167,7 @@ class OpenAIService(InferenceServiceABC):
                     else:
                         headers = self.get_headers()
 
-                except Exception as e:
+                except Exception:
                     return {
                         "rpm": 10_000,
                         "tpm": 2_000_000,

edsl/inference_services/services/perplexity_service.py

@@ -1,10 +1,14 @@
-from typing import Any, List, Optional
+from typing import Any, List, Optional, TYPE_CHECKING
 from ..rate_limits_cache import rate_limits
 
 from ...language_models import LanguageModel
 
 from .open_ai_service import OpenAIService
 
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore as Files
+    from ....invigilators.invigilator_base import InvigilatorBase as InvigilatorAI
+
 
 class PerplexityService(OpenAIService):
     """Perplexity service class."""
@@ -94,7 +98,7 @@ class PerplexityService(OpenAIService):
                     else:
                         headers = self.get_headers()
 
-                except Exception as e:
+                except Exception:
                     return {
                         "rpm": 10_000,
                         "tpm": 2_000_000,

edsl/inference_services/services/test_service.py

@@ -1,15 +1,15 @@
-from typing import Any, List, Optional
-import os
+from typing import Any, List, Optional, TYPE_CHECKING
 import asyncio
 import random
 
 from ..inference_service_abc import InferenceServiceABC
-from ..rate_limits_cache import rate_limits
 
 from ...language_models import LanguageModel
-from ...utilities.utilities import fix_partial_correct_response
 from ...enums import InferenceServiceType
 
+if TYPE_CHECKING:
+    from ....scenarios.file_store import FileStore as File
+
 
 class TestService(InferenceServiceABC):
     """OpenAI service class."""
@@ -37,7 +37,7 @@ class TestService(InferenceServiceABC):
 
     @classmethod
     def create_model(cls, model_name, model_class_name=None) -> LanguageModel:
-        throw_exception = False
+        # Removed unused variable
 
         class TestServiceLanguageModel(LanguageModel):
             _model_ = "test"
@@ -56,7 +56,7 @@ class TestService(InferenceServiceABC):
 
                     return self.canned_response
                 else:
-                    return "Hello, world"
+                    return "Hello, world X"
 
             async def async_execute_model_call(
                 self,
@@ -74,7 +74,8 @@ class TestService(InferenceServiceABC):
                         p = 1
 
                     if random.random() < p:
-                        raise Exception("This is a test error")
+                        from edsl.inference_services.exceptions import InferenceServiceError
+                        raise InferenceServiceError("This is a test error")
 
                 if hasattr(self, "func"):
                     return {

edsl/inference_services/services/together_ai_service.py

@@ -1,6 +1,5 @@
-from typing import Any, List, Optional
+from typing import List
 
-from ...language_models import LanguageModel
 from .open_ai_service import OpenAIService
 
 import openai
@@ -163,6 +162,6 @@ class TogetherAIService(OpenAIService):
                     for m in cls.get_model_list()
                     if m["id"] not in cls.model_exclude_list
                 ]
-            except Exception as e:
+            except Exception:
                 raise
         return cls._models_list_cache

edsl/inference_services/services/xai_service.py

@@ -1,4 +1,4 @@
-from typing import Any, List
+from typing import List
 
 from .open_ai_service import OpenAIService
 

edsl/instructions/__init__.py

@@ -3,4 +3,4 @@ from .instruction_collection import InstructionCollection
 from .change_instruction import ChangeInstruction
 from .instruction_handler import InstructionHandler
 
-__all__ = ["Instruction", "ChangeInstruction"]
+__all__ = ["Instruction", "ChangeInstruction", "InstructionCollection", "InstructionHandler"]

edsl/instructions/change_instruction.py

@@ -9,13 +9,14 @@ class ChangeInstruction:
         drop: Optional[List[str]] = None,
     ):
         if keep is None and drop is None:
-            raise ValueError("Keep and drop cannot both be None")
+            from edsl.instructions.exceptions import InstructionValueError
+            raise InstructionValueError("Keep and drop cannot both be None")
 
         self.keep = keep or []
         self.drop = drop or []
 
     def include_instruction(self, instruction_name) -> bool:
-        return (instruction_name in self.keep) or (not instruction_name in self.drop)
+        return (instruction_name in self.keep) or (instruction_name not in self.drop)
 
     def add_name(self, index) -> None:
         self.name = "change_instruction_{}".format(index)

edsl/instructions/exceptions.py

@@ -0,0 +1,61 @@
+"""
+Exceptions specific to the instructions module.
+
+This module defines custom exception classes for all instruction-related errors
+in the EDSL framework, ensuring consistent error handling and user feedback.
+"""
+
+from ..base import BaseException
+
+
+class InstructionError(BaseException):
+    """
+    Base exception class for all instruction-related errors.
+    
+    This is the parent class for all exceptions related to instruction creation,
+    modification, and application.
+    
+    Examples:
+        ```python
+        # Usually not raised directly, but through subclasses
+        # For example, when creating invalid instructions:
+        instruction = Instruction(keep=None, drop=None)  # Would raise InstructionValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/instructions.html"
+
+
+class InstructionValueError(InstructionError):
+    """
+    Exception raised when invalid values are provided to instruction methods.
+    
+    This exception occurs when:
+    - Both keep and drop parameters are None in an Instruction
+    - Invalid instruction options are provided
+    - The instruction content is improperly formatted
+    
+    Examples:
+        ```python
+        # Creating an instruction with invalid parameters
+        instruction = Instruction(keep=None, drop=None)  # Raises InstructionValueError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/instructions.html"
+
+
+class InstructionCollectionError(InstructionError):
+    """
+    Exception raised when there's an issue with an instruction collection.
+    
+    This exception occurs when:
+    - Instructions in a collection are invalid or incompatible
+    - There's an attempt to add a duplicate instruction
+    - The collection is used in an invalid context
+    
+    Examples:
+        ```python
+        # Adding an incompatible instruction to a collection
+        collection.add(invalid_instruction)  # Raises InstructionCollectionError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/instructions.html"

edsl/instructions/instruction.py

@@ -1,7 +1,10 @@
-from typing import Union, Optional, List, Generator, Dict
+from __future__ import annotations
 from ..utilities.remove_edsl_version import remove_edsl_version
 from ..base import RepresentationMixin
-#from ..surveys import Survey
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..surveys import Survey
 
 
 class Instruction(RepresentationMixin):

edsl/instructions/instruction_collection.py

@@ -42,7 +42,8 @@ class InstructionCollection(UserDict):
         self, question_name
     ) -> tuple[List[Instruction], List[ChangeInstruction]]:
         if question_name not in self.question_names:
-            raise ValueError(
+            from edsl.instructions.exceptions import InstructionCollectionError
+            raise InstructionCollectionError(
                 f"Question name not found in the list of questions: got '{question_name}'; list is {self.question_names}"
             )
         instructions, changes = [], []