levelapp 0.1.0__py3-none-any.whl

levelapp/aspects/sanitizer.py

@@ -0,0 +1,168 @@
+"""'levelapp/aspects/sanitizers.py'"""
+import re
+import json
+from typing import Dict, Any, Callable
+
+
+class JSONSanitizer:
+    def __init__(
+            self,
+            type_conversions: Dict[str, Callable[[str], Any]] = None,
+            default_values: Dict[str, Any] = None,
+            remove_nulls: bool = True,
+            raise_on_missing: bool = False,
+    ):
+        """
+        Initialize the sanitizer with optional transformation rules.
+
+        Args:
+            type_conversions: Map of field names to functions that convert their values.
+            default_values: Map of default values for missing or null fields.
+            remove_nulls: If True, null-valued fields will be dropped.
+            raise_on_missing: If True, an error is raised when a required field is missing.
+        """
+        self.type_conversions = type_conversions or {}
+        self.default_values = default_values or {}
+        self.remove_nulls = remove_nulls
+        self.raise_on_missing = raise_on_missing
+
+    def sanitize(self, data: Any) -> Any:
+        """
+        Entry point for sanitization logic.
+
+        Args:
+            data: Input data (expected to be a dict or list of dicts).
+
+        Returns:
+            Sanitized data with transformations and corrections applied.
+        """
+        if isinstance(data, dict):
+            return self._sanitize_dict(data)
+
+        elif isinstance(data, list):
+            return [self._sanitize_dict(item) for item in data]
+
+        else:
+            return self._sanitize_value(data)
+
+    def _sanitize_dict(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Sanitize a dictionary recursively.
+
+        Args:
+            data: Dictionary to be cleaned.
+
+        Returns:
+            A sanitized version of the dictionary.
+        """
+        sanitized_data = {}
+        for key, value in data.items():
+            if value is None:
+                if self.remove_nulls:
+                    continue
+
+                elif key in self.default_values:
+                    value = self.default_values[key]
+
+                elif self.raise_on_missing:
+                    raise ValueError(f'[_sanitize_dict] Missing value for key "{key}"')
+
+            if isinstance(value, (dict, list)):
+                sanitized_data[key] = self.sanitize(value)
+
+            else:
+                sanitized_data[key] = self._sanitize_field(key, value)
+
+        for key, default in self.default_values.items():
+            if key not in sanitized_data:
+                sanitized_data[key] = default
+
+        return sanitized_data
+
+    def _sanitize_field(self, key: str, value: Any) -> Any:
+        """
+        Apply type conversion to a single field if configured.
+
+        Args:
+            key: Field name.
+            value: Original value.
+
+        Returns:
+            Sanitized and type-converted value.
+        """
+        if key in self.type_conversions:
+            try:
+                value = self.type_conversions[key](value)
+
+            except Exception as e:
+                raise ValueError(f"[_sanitized_field] Failed to convert field {key} to type {type(value)}: {e}")
+
+        return self._sanitize_value(value)
+
+    def _sanitize_value(self, value: Any) -> Any:
+        """
+        Ensure a value is JSON-serializable and safely encoded.
+
+        Args:
+            value: Raw value from input.
+
+        Returns:
+            Cleaned value, suitable for JSON serialization.
+        """
+        if isinstance(value, str):
+            return self._escape_special_characters(value)
+
+        else:
+            try:
+                json.dumps(value)
+                return value
+
+            except (TypeError, ValueError):
+                return str(value)
+
+    @staticmethod
+    def _escape_special_characters(value: Any) -> str:
+        """
+        Escape non-UTF-8 or invalid characters in string data.
+
+        Args:
+            value: A string that may contain unsafe characters.
+
+        Returns:
+            UTF-8-safe, sanitized string.
+        """
+        try:
+            value.encode("utf-8").decode("utf-8")
+            return value
+
+        except UnicodeDecodeError:
+            return value.encode("utf-8", errors="replace").decode("utf-8")
+
+    @staticmethod
+    def strip_code_fences(text: str) -> str:
+        """
+        Remove triple backticks and language hints from code blocks.
+
+        Args:
+            text: Input string potentially containing code fences.
+
+        Returns:
+            String with code fences removed.
+        """
+        return re.sub(r"^(```[a-zA-Z]*\n?)$", "", text.strip(), flags=re.MULTILINE)
+
+    def safe_load_json(self, text: str) -> Dict[str, Any]:
+        """
+        Safely parse JSON from a string, even if surrounded by extra spaces/newlines.
+
+        Args:
+            text: Input string containing JSON.
+
+        Returns:
+            Parsed JSON as a dictionary, or empty dict on failure.
+        """
+        try:
+            return json.loads(text.strip())
+
+        except json.JSONDecodeError:
+            return self.sanitize(data=text)

levelapp/clients/__init__.py

@@ -0,0 +1,119 @@
+"""levelapp/clients/__init__.py"""
+import dotenv
+import threading
+
+from typing import Dict, Type
+
+from levelapp.clients.anthropic import AnthropicClient
+from levelapp.clients.ionos import IonosClient
+from levelapp.clients.mistral import MistralClient
+from levelapp.clients.openai import OpenAIClient
+from levelapp.core.base import BaseChatClient
+from levelapp.aspects import MonitoringAspect, logger
+
+dotenv.load_dotenv()
+
+
+class ClientRegistry:
+    """Thread-safe client registry with monitoring"""
+    _clients: Dict[str, Type[BaseChatClient]] = {}
+    _lock = threading.RLock()
+
+    @classmethod
+    def register(cls, provider: str, client_class: Type[BaseChatClient]) -> None:
+        """
+        Register a client class under a provider name.
+
+        Args:
+            provider (str): Unique identifier for the provider.
+            client_class (Type[BaseChatClient]): The client class to register.
+
+        Raises:
+            TypeError: If client_class is not a subclass of BaseChatClient.
+            KeyError: If a client for the provider is already registered.
+        """
+        if not isinstance(client_class, type) or not issubclass(client_class, BaseChatClient):
+            raise TypeError(f"Client '{provider}' must be a subclass of BaseChatClient")
+
+        if provider in cls._clients:
+            raise KeyError(f"[ClientRegistry] Client for provider '{provider}' is already registered")
+
+        with cls._lock:
+            if provider in cls._clients:
+                raise KeyError(f"[ClientRegistry] Client for provider '{provider}' is already registered")
+
+        cls._wrap_client_methods(client_class)
+        cls._clients[provider] = client_class
+        logger.info(f"[ClientRegistry] Registered client for provider: {provider}")
+
+    @classmethod
+    def _wrap_client_methods(cls, client_class: Type[BaseChatClient]) -> None:
+        """
+        Apply monitoring decorators to client methods.
+
+        Args:
+            client_class (Type[BaseChatClient]): The client class whose methods to wrap.
+
+        Raises:
+            TypeError: If the methods are not callable.
+        """
+        for method in ("call", "acall"):
+            if not hasattr(client_class, method):
+                raise TypeError(f"{client_class.__name__} missing required method: {method}")
+
+            original = getattr(client_class, method)
+
+            if getattr(original, "_is_monitored", False):
+                continue
+
+            monitored = MonitoringAspect.monitor(
+                name=f"{client_class.__name__}.{method}",
+                cached=False,
+                enable_timing=True
+            )(original)
+
+            setattr(monitored, "_is_monitored", True)
+            setattr(client_class, method, monitored)
+
+    @classmethod
+    def get(cls, provider: str, **kwargs) -> BaseChatClient:
+        """
+        Retrieve a registered chat client by provider name.
+
+        Args:
+            provider (str): The name of the provider to retrieve.
+            **kwargs: Additional keyword arguments to pass to the client constructor.
+
+        Returns:
+            BaseChatClient: An instance of the registered client class.
+        """
+        if provider not in cls._clients:
+            raise KeyError(f"Client for provider '{provider}' is not registered")
+
+        return cls._clients[provider](**kwargs)
+
+    @classmethod
+    def list_providers(cls) -> list[str]:
+        """List all registered provider names"""
+        return list(cls._clients.keys())
+
+    @classmethod
+    def unregister(cls, provider: str) -> None:
+        """Remove a provider from registry"""
+        with cls._lock:
+            cls._clients.pop(provider, None)
+
+
+clients = {
+    "openai": OpenAIClient,
+    "ionos": IonosClient,
+    "mistral": MistralClient,
+    "anthropic": AnthropicClient
+}
+
+for provider_, client_class_ in clients.items():
+    try:
+        ClientRegistry.register(provider=provider_, client_class=client_class_)
+
+    except (TypeError, KeyError) as e:
+        logger.error(f"Failed to register client for {provider_}: {e}")

levelapp/clients/anthropic.py

@@ -0,0 +1,112 @@
+"""levelapp/clients/anthropic.py"""
+import os
+
+from typing import Dict, Any
+
+from levelapp.core.base import BaseChatClient
+
+
+class AnthropicClient(BaseChatClient):
+    """
+    Client for interacting with Anthropic's Claude API.
+
+    This implementation adapts requests and responses to the Anthropic API
+    format, including authentication, versioning headers, and structured
+    response parsing.
+
+    Attributes:
+        model (str): Target model ID (default: "claude-sonnet-4-20250514").
+        version (str): API version header required by Anthropic (default: "2023-06-01").
+        base_url (str): Base endpoint for Anthropic API (default: https://api.anthropic.com/v1).
+        api_key (str): Authentication token for Anthropic API.
+        max_tokens (int): Maximum tokens allowed in the response.
+    """
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.model = kwargs.get('model') or "claude-sonnet-4-20250514"
+        self.version = kwargs.get('version') or "2023-06-01"
+        self.base_url = kwargs.get("base_url") or "https://api.anthropic.com/v1"
+        self.api_key = kwargs.get('api_key') or os.environ.get('ANTHROPIC_API_KEY')
+        self.max_tokens = kwargs.get('max_tokens') or 1024
+
+        if not self.api_key:
+            raise ValueError("Anthropic API key not set.")
+
+    @property
+    def endpoint_path(self) -> str:
+        """
+        API-specific endpoint path for message-based chat.
+
+        Returns:
+            str: "/messages"
+        """
+        return "/messages"
+
+    def _build_endpoint(self) -> str:
+        """
+        Construct the full API endpoint URL.
+
+        Returns:
+            str: Concatenation of base_url and endpoint_path.
+        """
+        return f"{self.base_url}/{self.endpoint_path.lstrip('/')}"
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Build HTTP headers for the Anthropic API request.
+
+        Required headers include:
+        - `x-api-key`: Authentication token.
+        - `anthropic-version`: API version string.
+        - `content-type`: Always "application/json".
+
+        Returns:
+            Dict[str, str]: Headers with authentication and API version.
+        """
+        return {
+            "x-api-key": self.api_key,
+            "anthropic-version": self.version,
+            "content-type": "application/json"
+        }
+
+    def _build_payload(self, message: str) -> Dict[str, Any]:
+        """
+        Construct the JSON payload for the Anthropic Messages API.
+
+        Args:
+            message (str): User input or prompt to evaluate.
+
+        Returns:
+            Dict[str, Any]: Payload containing model ID, messages, and token limit.
+        """
+        return {
+            "model": self.model,
+            "messages": [{"role": "user", "content": message}],
+            "max_tokens": self.max_tokens
+        }
+
+    def parse_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Parse and normalize the Anthropic API response.
+
+        - Extracts text output from `content[0].text`.
+        - Attempts to JSON-parse the output if it contains structured data.
+        - Collects token usage metadata from `usage`.
+
+        Args:
+            response (Dict[str, Any]): Raw JSON response from Anthropic.
+
+        Returns:
+            Dict[str, Any]: {
+                "output": Parsed model output (dict or str),
+                "metadata": {
+                    "input_tokens": int,
+                    "output_tokens": int
+                }
+            }
+        """
+        input_tokens = response.get("usage", {}).get("input_tokens", 0)
+        output_tokens = response.get("usage", {}).get("output_tokens", 0)
+        output = response.get("content", {})[0].get("text", "")
+        parsed = self.sanitizer.safe_load_json(text=output)
+        return {'output': parsed, 'metadata': {'input_tokens': input_tokens, 'output_tokens': output_tokens}}

levelapp/clients/ionos.py

@@ -0,0 +1,116 @@
+"""levelapp/clients/ionos.py"""
+import os
+import uuid
+
+from typing import Dict, Any
+from levelapp.core.base import BaseChatClient
+
+
+class IonosClient(BaseChatClient):
+    """
+    Client for interacting with the IONOS LLM API.
+
+    This implementation adapts requests and responses to the IONOS
+    API format, including payload structure, headers, and response parsing.
+
+    Attributes:
+        model_id (str): Model identifier to target (from IONOS dashboard or env).
+        base_url (str): Base endpoint for IONOS API, e.g. https://api.ionos.ai.
+        api_key (str): Authentication token for the IONOS API.
+        top_k (int): Sampling parameter; number of top tokens to consider.
+        top_p (float): Sampling parameter; nucleus probability cutoff.
+        temperature (float): Sampling randomness.
+        max_tokens (int): Maximum tokens allowed in completion.
+    """
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.model_id = kwargs.get('model_id') or os.getenv('IONOS_MODEL_ID')
+        self.base_url = kwargs.get('base_url') or os.getenv("IONOS_BASE_URL")
+        self.api_key = kwargs.get('api_key') or os.environ.get("IONOS_API_KEY")
+        self.top_k = kwargs.get('top_k') or 5
+        self.top_p = kwargs.get('top_p') or 0.5
+        self.temperature = kwargs.get('temperature') or 0.0
+        self.max_tokens = kwargs.get('max_tokens') or 150
+
+        if not self.api_key:
+            raise ValueError("IONOS API key not set.")
+
+    @property
+    def endpoint_path(self) -> str:
+        """
+        API-specific endpoint path for inference calls.
+
+        Example:
+            "models/{model_id}/predictions"
+        """
+        return f"models/{self.model_id}/predictions"
+
+    def _build_endpoint(self) -> str:
+        """
+        Construct the full API endpoint URL.
+
+        Returns:
+            str: Concatenation of base_url and endpoint_path.
+        """
+        return f"{self.base_url}/{self.endpoint_path.lstrip('/')}"
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Build HTTP headers for the IONOS API request.
+
+        Returns:
+            Dict[str, str]: Headers with authentication and content type.
+        """
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _build_payload(self, message: str) -> Dict[str, Any]:
+        """
+        Construct the JSON payload for the IONOS API.
+
+        Args:
+            message (str): User input or prompt to evaluate.
+
+        Returns:
+            Dict[str, Any]: Payload containing properties and sampling options.
+        """
+        return {
+            "properties": {"input": message},
+            "option": {
+                "top-k": self.top_k,
+                "top-p": self.top_p,
+                "temperature": self.temperature,
+                "max_tokens": self.max_tokens,
+                "seed": uuid.uuid4().int & ((1 << 16) - 1),
+            },
+        }
+
+    def parse_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Parse and normalize the IONOS API response.
+
+        - Extracts model output from `properties.output`.
+        - Strips any code fences or formatting noise.
+        - Attempts to JSON-parse the result (safe fallback if invalid).
+        - Collects token usage metadata.
+
+        Args:
+            response (Dict[str, Any]): Raw JSON response from IONOS.
+
+        Returns:
+            Dict[str, Any]: {
+                "output": Parsed model output (dict or str),
+                "metadata": {
+                    "input_tokens": int,
+                    "output_tokens": int
+                }
+            }
+        """
+        input_tokens = response.get("metadata", {}).get("inputTokens", -1)
+        output_tokens = response.get("metadata", {}).get("outputTokens", -1)
+        output = response.get("properties", {}).get("output", "")
+        cleaned = self.sanitizer.strip_code_fences(output)
+        parsed = self.sanitizer.safe_load_json(text=cleaned)
+        return {"output": parsed, "metadata": {"input_tokens": input_tokens, "output_tokens": output_tokens}}

levelapp/clients/mistral.py

@@ -0,0 +1,106 @@
+"""levelapp/clients/mistral.py"""
+import os
+
+from typing import Dict, Any
+from levelapp.core.base import BaseChatClient
+
+
+class MistralClient(BaseChatClient):
+    """
+    Client for interacting with the Mistral API.
+
+    This implementation adapts requests and responses to the Mistral API
+    format, handling authentication, request payload structure, and
+    response parsing into a normalized format.
+
+    Attributes:
+        model (str): Target model identifier (default: "mistral-large-latest").
+        base_url (str): Base endpoint for Mistral API (default: https://api.mistral.ai/v1).
+        api_key (str): Authentication token for Mistral API.
+    """
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.model = kwargs.get("model") or "mistral-large-latest"
+        self.base_url = kwargs.get('base_url') or "https://api.mistral.ai/v1"
+        self.api_key = kwargs.get('api_key') or os.environ.get('MISTRAL_API_KEY')
+
+        if not self.api_key:
+            raise ValueError("Missing API key not set.")
+
+    @property
+    def endpoint_path(self) -> str:
+        """
+        API-specific endpoint path for chat completions.
+
+        Returns:
+            str: "/chat/completions"
+        """
+        return "/chat/completions"
+
+    def _build_endpoint(self) -> str:
+        """
+        Construct the full API endpoint URL.
+
+        Returns:
+            str: Concatenation of base_url and endpoint_path.
+        """
+        return f"{self.base_url}/{self.endpoint_path.lstrip('/')}"
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Build HTTP headers for the Mistral API request.
+
+        Required headers include:
+        - `Authorization`: Bearer token for API access.
+        - `Content-Type`: Always "application/json".
+        - `Accept`: Expected response format ("application/json").
+
+        Returns:
+            Dict[str, str]: Headers including authentication and content type.
+        """
+        return {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.api_key}"
+        }
+
+    def _build_payload(self, message: str) -> Dict[str, Any]:
+        """
+        Construct the JSON payload for the Mistral chat completions API.
+
+        Args:
+            message (str): User input or prompt to evaluate.
+
+        Returns:
+            Dict[str, Any]: Payload containing model ID and user message.
+        """
+        return {
+            "model": self.model,
+            "messages": [{"role": "user", "content": message}],
+        }
+
+    def parse_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Parse and normalize the Mistral API response.
+
+        - Extracts text output from `choices[0].message.content`.
+        - Attempts to JSON-parse the output if structured data is detected.
+        - Collects token usage metadata from `usage`.
+
+        Args:
+            response (Dict[str, Any]): Raw JSON response from Mistral API.
+
+        Returns:
+            Dict[str, Any]: {
+                "output": Parsed model output (dict or str),
+                "metadata": {
+                    "input_tokens": int,
+                    "output_tokens": int
+                }
+            }
+        """
+        input_tokens = response.get("usage", {}).get("prompt_tokens", 0)
+        output_tokens = response.get("usage", {}).get("completion_tokens", 0)
+        output = response.get("choices", [{}])[0].get("message", {}).get("content", "")
+        parsed = self.sanitizer.safe_load_json(text=output)
+        return {'output': parsed, 'metadata': {'input': input_tokens, 'output': output_tokens}}