levelapp 0.1.15__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,122 @@
+"""levelapp/clients/__init__.py"""
+import dotenv
+import threading
+
+from typing import Dict, Type
+
+from levelapp.clients.anthropic import AnthropicClient
+from levelapp.clients.gemini import GeminiClient
+from levelapp.clients.groq import GroqClient
+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
+
+    @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,
+    "groq": GroqClient,
+    "gemini": GeminiClient
+}
+
+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/gemini.py

@@ -0,0 +1,130 @@
+"""levelapp/clients/gemini.py"""
+import os
+from typing import Dict, Any
+
+from levelapp.core.base import BaseChatClient
+
+
+class GeminiClient(BaseChatClient):
+    """
+    Client for interacting with Google's Gemini API.
+
+    This implementation adapts requests and responses to the Gemini API
+    format, including content structure, headers, and token usage reporting.
+
+    Attributes:
+        model (str): Target model ID (default: "gemini-2.0-flash-exp").
+        base_url (str): Base endpoint for Gemini API (default: https://generativelanguage.googleapis.com/v1beta).
+        api_key (str): Authentication token for the Gemini API.
+        max_tokens (int): Maximum tokens allowed in the completion.
+    """
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.model = kwargs.get('model') or os.environ.get("GEMINI_MODEL")
+        self.base_url = kwargs.get('base_url') or "https://generativelanguage.googleapis.com/v1beta"
+        self.api_key = kwargs.get('api_key') or os.environ.get('GEMINI_API_KEY')
+        self.max_tokens = kwargs.get('max_tokens') or 1024
+
+        if not self.api_key:
+            raise ValueError("Gemini API key not set")
+
+    @property
+    def endpoint_path(self) -> str:
+        """
+        API-specific endpoint path for content generation.
+
+        Returns:
+            str: Formatted endpoint with model name.
+        """
+        return f"/models/{self.model}:generateContent"
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Build HTTP headers for the Gemini API request.
+
+        Gemini uses x-goog-api-key header instead of Authorization: Bearer.
+
+        Returns:
+            Dict[str, str]: Headers with API key and content type.
+        """
+        return {
+            "x-goog-api-key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+    def _build_payload(self, message: str) -> Dict[str, Any]:
+        """
+        Construct the JSON payload for the Gemini generateContent API.
+
+        Args:
+            message (str): User input or prompt to evaluate.
+
+        Returns:
+            Dict[str, Any]: Payload containing model ID, contents structure, and token limit.
+        """
+        return {
+            "contents": [
+                {
+                    "parts": [
+                        {
+                            "text": message
+                        }
+                    ]
+                }
+            ],
+            "generationConfig": {
+                "maxOutputTokens": self.max_tokens,
+            }
+        }
+
+    def parse_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Parse and normalize the Gemini API response.
+
+        - Extracts text output from `candidates[0].content.parts[0].text`.
+        - Attempts to JSON-parse the result if it contains structured content.
+        - Collects token usage metadata from `usageMetadata`.
+
+        Args:
+            response (Dict[str, Any]): Raw JSON response from Gemini.
+
+        Returns:
+            Dict[str, Any]: {
+                "output": Parsed model output (dict or str),
+                "metadata": {
+                    "input_tokens": int,
+                    "output_tokens": int,
+                    "total_tokens": int,
+                    "finish_reason": str
+                }
+            }
+        """
+        # Extract text from candidates
+        candidates = response.get("candidates", [{}])
+        candidate = candidates[0] if candidates else {}
+        content = candidate.get("content", {})
+        parts = content.get("parts", [{}])
+        part = parts[0] if parts else {}
+        output_text = part.get("text", "")
+
+        # Extract token usage
+        usage_metadata = response.get("usageMetadata", {})
+        input_tokens = usage_metadata.get("promptTokenCount", 0)
+        output_tokens = usage_metadata.get("candidatesTokenCount", 0)
+        total_tokens = usage_metadata.get("totalTokenCount", 0)
+
+        # Extract finish reason
+        finish_reason = candidate.get("finishReason", "UNKNOWN")
+
+        # Try to parse as JSON if it looks like structured data
+        parsed = self.sanitizer.safe_load_json(text=output_text)
+
+        return {
+            "output": parsed,
+            "metadata": {
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "total_tokens": total_tokens,
+                "finish_reason": finish_reason
+            }
+        }

levelapp/clients/groq.py

@@ -0,0 +1,101 @@
+"""levelapp/clients/groq.py"""
+import os
+from typing import Dict, Any
+from levelapp.core.base import BaseChatClient
+
+
+class GroqClient(BaseChatClient):
+    """
+    Client for interacting with Groq's Chat Completions API.
+
+    This implementation adapts requests and responses to the Groq API
+    format, which is OpenAI-compatible but with Groq-specific models and endpoints.
+
+    Attributes:
+        model (str): Target model ID (default: "llama-3.3-70b-versatile").
+        base_url (str): Base endpoint for Groq API (default: https://api.groq.com/openai/v1).
+        api_key (str): Authentication token for the Groq API.
+        max_tokens (int): Maximum tokens allowed in the completion.
+    """
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.model = kwargs.get('model') or os.environ.get('GROK_MODEL')
+        self.base_url = kwargs.get('base_url') or "https://api.groq.com/openai/v1"
+        self.api_key = kwargs.get('api_key') or os.environ.get('GROQ_API_KEY')
+        self.max_tokens = kwargs.get('max_tokens') or 1024
+
+        if not self.api_key:
+            raise ValueError("Groq 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 Groq 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 Groq Chat Completions 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 Groq API response.
+
+        - Extracts text output from `choices[0].message.content`.
+        - Attempts to JSON-parse the result if it contains structured content.
+        - Collects token usage metadata from `usage`.
+
+        Args:
+            response (Dict[str, Any]): Raw JSON response from Groq.
+
+        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_tokens": input_tokens, "output_tokens": output_tokens}}