llmbridgekit 1.0.0__py3-none-any.whl

llmbridgekit/__init__.py

@@ -0,0 +1,77 @@
+"""
+LLMBridgeKit - Universal Python LLM Provider Abstraction Library
+
+A provider-agnostic library for calling multiple LLM providers through one consistent interface.
+"""
+
+try:
+    from importlib.metadata import version
+    __version__ = version("llmbridgekit")
+except Exception:
+    __version__ = "0.0.0"
+
+# Core imports
+from llmbridgekit.client import LLMClient
+from llmbridgekit.config import LLMConfig, RedactionConfig
+from llmbridgekit.models import (
+    LLMRequest,
+    LLMResponse,
+    MessageRole,
+    ResponseMode,
+    ToolCall,
+    Usage,
+)
+
+# Exceptions
+from llmbridgekit.exceptions import (
+    LLMGatewayError,
+    ProviderError,
+    ProviderNotFoundError,
+    InvalidConfigError,
+    InvalidRequestError,
+    RateLimitError,
+    TimeoutError,
+    AuthenticationError,
+    InvalidResponseError,
+    SchemaValidationError,
+    ToolCallError,
+)
+
+# Registry
+from llmbridgekit.registry import provider_registry
+
+# Provider base
+from llmbridgekit.providers.base import BaseProvider, ProviderFeatures
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "LLMClient",
+    "LLMConfig",
+    "RedactionConfig",
+    # Models
+    "LLMRequest",
+    "LLMResponse",
+    "MessageRole",
+    "ResponseMode",
+    "ToolCall",
+    "Usage",
+    # Exceptions
+    "LLMGatewayError",
+    "ProviderError",
+    "ProviderNotFoundError",
+    "InvalidConfigError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "TimeoutError",
+    "AuthenticationError",
+    "InvalidResponseError",
+    "SchemaValidationError",
+    "ToolCallError",
+    # Registry
+    "provider_registry",
+    # Provider base
+    "BaseProvider",
+    "ProviderFeatures",
+]

llmbridgekit/client.py

@@ -0,0 +1,609 @@
+"""
+LLMBridgeKit Client
+
+Main client for interacting with LLM providers.
+"""
+
+import logging
+import time
+from typing import Any, Generator
+
+from llmbridgekit.config import (
+    GatewayConfig,
+    LLMConfig,
+    RedactionConfig,
+    RetryConfig,
+    ValidationConfig,
+)
+from llmbridgekit.exceptions import (
+    InvalidRequestError,
+    ProviderNotFoundError,
+)
+from llmbridgekit.fallback import create_fallback_chain
+from llmbridgekit.models import LLMResponse, Message, StreamChunk, Usage
+from llmbridgekit.pricing import estimate_cost
+from llmbridgekit.redaction import redact_messages, redact_text
+from llmbridgekit.registry import provider_registry
+from llmbridgekit.retry import RetryConfig as RC, retry_with_backoff
+from llmbridgekit.usage import record_usage
+from llmbridgekit.validation import validate_config, validate_request
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """
+    Main LLM Gateway client.
+
+    Provides unified interface for calling multiple LLM providers.
+
+    Example:
+        >>> client = LLMClient(provider="gemini")
+        >>> response = client.generate("Explain quantum computing")
+        >>> print(response.text)
+    """
+
+    def __init__(
+        self,
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        gateway_config: GatewayConfig | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize LLM client.
+
+        Args:
+            provider: Default provider name
+            model: Default model name
+            config: Default LLM configuration
+            gateway_config: Gateway-level configuration
+            **kwargs: Additional config parameters
+        """
+        # Set up configurations
+        self.gateway_config = gateway_config or GatewayConfig()
+
+        if config:
+            self.default_config = config
+        else:
+            self.default_config = LLMConfig(
+                provider=provider or self.gateway_config.default_provider,
+                model=model or self.gateway_config.default_model,
+                **kwargs,
+            )
+
+        # Initialize components
+        self.redaction_config = self.gateway_config.redaction
+        self.validation_config = self.gateway_config.validation
+        self.retry_config = self.gateway_config.retry
+
+    def generate(
+        self,
+        prompt: str,
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        fallback_chain: list[dict[str, Any]] | str | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """
+        Generate text from prompt.
+
+        Args:
+            prompt: Input prompt
+            provider: Provider name (overrides default)
+            model: Model name (overrides default)
+            config: Generation configuration (overrides default)
+            fallback_chain: Fallback providers
+            **kwargs: Additional config parameters
+
+        Returns:
+            LLM response
+
+        Example:
+            >>> response = client.generate(
+            ...     "Explain machine learning",
+            ...     provider="gemini",
+            ...     temperature=0.7
+            ... )
+        """
+        # Merge configurations
+        merged_config = self._merge_config(provider, model, config, **kwargs)
+
+        # Validate
+        validate_request(prompt, None, merged_config, self.validation_config)
+        validate_config(merged_config)
+
+        # Redact PII
+        if self.redaction_config.enabled:
+            prompt = redact_text(prompt, self.redaction_config)
+
+        # Try fallback chain if configured
+        if fallback_chain:
+            chain = create_fallback_chain(
+                fallback_chain, self.gateway_config.fallback_chains
+            )
+            if chain:
+                return chain.execute(
+                    self._execute_generate,
+                    prompt=prompt,
+                    base_config=merged_config,
+                )
+
+        # Execute single provider
+        return self._execute_generate(
+            merged_config.provider,
+            merged_config.model,
+            merged_config,
+            prompt=prompt,
+        )
+
+    def chat(
+        self,
+        messages: list[dict[str, Any] | Message],
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        fallback_chain: list[dict[str, Any]] | str | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """
+        Chat with messages.
+
+        Args:
+            messages: Chat messages
+            provider: Provider name
+            model: Model name
+            config: Generation configuration
+            fallback_chain: Fallback providers
+            **kwargs: Additional config parameters
+
+        Returns:
+            LLM response
+
+        Example:
+            >>> response = client.chat([
+            ...     {"role": "system", "content": "You are a helpful assistant."},
+            ...     {"role": "user", "content": "What is Python?"}
+            ... ])
+        """
+        # Merge configurations
+        merged_config = self._merge_config(provider, model, config, **kwargs)
+
+        # Convert Message objects to dicts
+        messages_dicts = [
+            msg if isinstance(msg, dict) else {"role": msg.role, "content": msg.content}
+            for msg in messages
+        ]
+
+        # Validate
+        validate_request(None, messages_dicts, merged_config, self.validation_config)
+        validate_config(merged_config)
+
+        # Redact PII
+        if self.redaction_config.enabled:
+            messages_dicts = redact_messages(messages_dicts, self.redaction_config)
+
+        # Try fallback chain if configured
+        if fallback_chain:
+            chain = create_fallback_chain(
+                fallback_chain, self.gateway_config.fallback_chains
+            )
+            if chain:
+                return chain.execute(
+                    self._execute_chat,
+                    messages=messages_dicts,
+                    base_config=merged_config,
+                )
+
+        # Execute single provider
+        return self._execute_chat(
+            merged_config.provider,
+            merged_config.model,
+            merged_config,
+            messages=messages_dicts,
+        )
+
+    def generate_json(
+        self,
+        prompt: str,
+        schema: dict[str, Any],
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        fallback_chain: list[dict[str, Any]] | str | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """
+        Generate structured JSON output.
+
+        Args:
+            prompt: Input prompt
+            schema: JSON Schema
+            provider: Provider name
+            model: Model name
+            config: Generation configuration
+            fallback_chain: Fallback providers
+            **kwargs: Additional config parameters
+
+        Returns:
+            LLM response with json_data populated
+
+        Example:
+            >>> schema = {
+            ...     "type": "object",
+            ...     "properties": {
+            ...         "category": {"type": "string"},
+            ...         "confidence": {"type": "number"}
+            ...     }
+            ... }
+            >>> response = client.generate_json(
+            ...     "Categorize: Python tutorial",
+            ...     schema=schema
+            ... )
+        """
+        # Merge configurations
+        merged_config = self._merge_config(provider, model, config, **kwargs)
+        merged_config.json_schema = schema
+        merged_config.response_mode = "json_schema"
+
+        # Validate
+        validate_request(prompt, None, merged_config, self.validation_config)
+        validate_config(merged_config)
+
+        # Redact PII
+        if self.redaction_config.enabled:
+            prompt = redact_text(prompt, self.redaction_config)
+
+        # Try fallback chain if configured
+        if fallback_chain:
+            chain = create_fallback_chain(
+                fallback_chain, self.gateway_config.fallback_chains
+            )
+            if chain:
+                return chain.execute(
+                    self._execute_generate_json,
+                    prompt=prompt,
+                    base_config=merged_config,
+                )
+
+        # Execute single provider
+        return self._execute_generate_json(
+            merged_config.provider,
+            merged_config.model,
+            merged_config,
+            prompt=prompt,
+            schema=schema,
+        )
+
+    def stream(
+        self,
+        prompt: str,
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        **kwargs: Any,
+    ) -> Generator[StreamChunk, None, None]:
+        """
+        Stream generation.
+
+        Args:
+            prompt: Input prompt
+            provider: Provider name
+            model: Model name
+            config: Generation configuration
+            **kwargs: Additional config parameters
+
+        Yields:
+            Stream chunks
+
+        Example:
+            >>> for chunk in client.stream("Write a story"):
+            ...     print(chunk.text, end="", flush=True)
+        """
+        # Merge configurations
+        merged_config = self._merge_config(provider, model, config, **kwargs)
+        merged_config.stream = True
+
+        # Validate
+        validate_request(prompt, None, merged_config, self.validation_config)
+        validate_config(merged_config)
+
+        # Redact PII
+        if self.redaction_config.enabled:
+            prompt = redact_text(prompt, self.redaction_config)
+
+        # Get provider
+        provider_instance = provider_registry.get(merged_config.provider, merged_config)
+
+        # Stream
+        yield from provider_instance.stream(prompt, merged_config)
+
+    def generate_with_tools(
+        self,
+        prompt: str,
+        tools: list[dict[str, Any]],
+        provider: str | None = None,
+        model: str | None = None,
+        config: LLMConfig | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """
+        Generate with tool/function calling.
+
+        Args:
+            prompt: Input prompt
+            tools: Tool definitions
+            provider: Provider name
+            model: Model name
+            config: Generation configuration
+            **kwargs: Additional config parameters
+
+        Returns:
+            LLM response with tool_calls populated
+
+        Example:
+            >>> tools = [{
+            ...     "name": "get_weather",
+            ...     "description": "Get weather",
+            ...     "parameters": {
+            ...         "type": "object",
+            ...         "properties": {"location": {"type": "string"}}
+            ...     }
+            ... }]
+            >>> response = client.generate_with_tools(
+            ...     "What's the weather in NYC?",
+            ...     tools=tools
+            ... )
+        """
+        # Merge configurations
+        merged_config = self._merge_config(provider, model, config, **kwargs)
+        merged_config.tools = tools
+
+        # Validate
+        validate_request(prompt, None, merged_config, self.validation_config)
+        validate_config(merged_config)
+
+        # Redact PII
+        if self.redaction_config.enabled:
+            prompt = redact_text(prompt, self.redaction_config)
+
+        # Get provider
+        provider_instance = provider_registry.get(merged_config.provider, merged_config)
+
+        # Execute with retry
+        start_time = time.time()
+
+        def _call():
+            return provider_instance.generate_with_tools(prompt, tools, merged_config)
+
+        response = retry_with_backoff(_call, self.retry_config)
+
+        # Post-process
+        response.latency_ms = int((time.time() - start_time) * 1000)
+        self._post_process_response(response, merged_config)
+
+        return response
+
+    def run_task(
+        self,
+        task: str,
+        prompt: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """
+        Run predefined task.
+
+        Args:
+            task: Task name
+            prompt: Optional prompt
+            messages: Optional messages
+            **kwargs: Additional config parameters
+
+        Returns:
+            LLM response
+
+        Example:
+            >>> response = client.run_task(
+            ...     "text_to_sql",
+            ...     prompt="Show revenue by category"
+            ... )
+        """
+        if task not in self.gateway_config.tasks:
+            raise InvalidRequestError(f"Task '{task}' not found in configuration")
+
+        task_config = self.gateway_config.tasks[task]
+
+        # Build config from task
+        config = LLMConfig(
+            provider=task_config.get("provider", self.default_config.provider),
+            model=task_config.get("model"),
+            **task_config.get("config", {}),
+        )
+
+        # Execute
+        if prompt:
+            return self.generate(prompt, config=config, **kwargs)
+        elif messages:
+            return self.chat(messages, config=config, **kwargs)
+        else:
+            raise InvalidRequestError("Either prompt or messages required")
+
+    # Async methods
+    async def agenerate(self, *args, **kwargs) -> LLMResponse:
+        """Async generate (future implementation)."""
+        return self.generate(*args, **kwargs)
+
+    async def achat(self, *args, **kwargs) -> LLMResponse:
+        """Async chat (future implementation)."""
+        return self.chat(*args, **kwargs)
+
+    # Private methods
+    def _merge_config(
+        self,
+        provider: str | None,
+        model: str | None,
+        config: LLMConfig | None,
+        **kwargs: Any,
+    ) -> LLMConfig:
+        """Merge configurations with precedence."""
+        merged = LLMConfig()
+
+        # Start with default
+        merged = self.default_config
+
+        # Apply config parameter
+        if config:
+            merged = merged.merge(config)
+
+        # Apply provider/model overrides
+        if provider:
+            merged.provider = provider
+        if model:
+            merged.model = model
+
+        # Apply kwargs
+        for key, value in kwargs.items():
+            if hasattr(merged, key):
+                setattr(merged, key, value)
+
+        return merged
+
+    def _execute_generate(
+        self,
+        provider: str,
+        model: str | None,
+        config: LLMConfig,
+        prompt: str,
+    ) -> LLMResponse:
+        """Execute generate with provider."""
+        # Get provider
+        provider_instance = provider_registry.get(provider, config)
+
+        # Execute with retry
+        start_time = time.time()
+
+        def _call():
+            return provider_instance.generate(prompt, config)
+
+        response = retry_with_backoff(_call, self.retry_config)
+
+        # Post-process
+        response.latency_ms = int((time.time() - start_time) * 1000)
+        self._post_process_response(response, config)
+
+        return response
+
+    def _execute_chat(
+        self,
+        provider: str,
+        model: str | None,
+        config: LLMConfig,
+        messages: list[dict[str, Any]],
+    ) -> LLMResponse:
+        """Execute chat with provider."""
+        # Get provider
+        provider_instance = provider_registry.get(provider, config)
+
+        # Execute with retry
+        start_time = time.time()
+
+        def _call():
+            return provider_instance.chat(messages, config)
+
+        response = retry_with_backoff(_call, self.retry_config)
+
+        # Post-process
+        response.latency_ms = int((time.time() - start_time) * 1000)
+        self._post_process_response(response, config)
+
+        return response
+
+    def _execute_generate_json(
+        self,
+        provider: str,
+        model: str | None,
+        config: LLMConfig,
+        prompt: str,
+        schema: dict[str, Any],
+    ) -> LLMResponse:
+        """Execute generate_json with provider."""
+        # Get provider
+        provider_instance = provider_registry.get(provider, config)
+
+        # Execute with retry
+        start_time = time.time()
+
+        def _call():
+            return provider_instance.generate_json(prompt, schema, config)
+
+        response = retry_with_backoff(_call, self.retry_config)
+
+        # Post-process
+        response.latency_ms = int((time.time() - start_time) * 1000)
+        self._post_process_response(response, config)
+
+        return response
+
+    def _post_process_response(
+        self,
+        response: LLMResponse,
+        config: LLMConfig,
+    ) -> None:
+        """Post-process response (cost, usage tracking, etc.)."""
+        # Estimate cost
+        if self.gateway_config.cost.enabled and response.usage.total_tokens > 0:
+            response.cost = estimate_cost(
+                response.usage,
+                response.model or config.model or "",
+                self.gateway_config.cost.custom_pricing,
+            )
+
+        # Record usage
+        if response.usage.total_tokens > 0:
+            record_usage(
+                response.usage,
+                response.provider,
+                response.model or "",
+                task=config.metadata.get("task"),
+            )
+
+    @classmethod
+    def from_yaml(cls, config_path: str) -> "LLMClient":
+        """
+        Create client from YAML configuration file.
+
+        Args:
+            config_path: Path to YAML config file
+
+        Returns:
+            Configured LLM client
+
+        Example:
+            >>> client = LLMClient.from_yaml("config.yaml")
+        """
+        try:
+            import yaml
+        except ImportError:
+            raise ImportError("PyYAML required for YAML config. Install with: pip install pyyaml")
+
+        with open(config_path, "r") as f:
+            config_dict = yaml.safe_load(f)
+
+        # Parse gateway config
+        gateway_config = GatewayConfig(
+            default_provider=config_dict.get("default_provider", "openai"),
+            default_model=config_dict.get("default_model"),
+            default_timeout=config_dict.get("default_timeout", 60.0),
+            default_retries=config_dict.get("default_retries", 2),
+            providers=config_dict.get("providers", {}),
+            fallback_chains=config_dict.get("fallback_chains", {}),
+            tasks=config_dict.get("tasks", {}),
+        )
+
+        return cls(gateway_config=gateway_config)
+
+    def __repr__(self) -> str:
+        return f"<LLMClient provider='{self.default_config.provider}' model='{self.default_config.model}'>"