iatoolkit 2.16.3__tar.gz → 2.17.1__tar.gz

{iatoolkit-2.16.3/src/iatoolkit.egg-info → iatoolkit-2.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.16.3
+Version: 2.17.1
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.16.3 → iatoolkit-2.17.1}/src/iatoolkit/__init__.py

@@ -3,7 +3,7 @@
 #
 # IAToolkit is open source software.
 
-__version__ = "2.16.3"
+__version__ = "2.17.1"
 
 # Expose main classes and functions at the top level of the package
 

iatoolkit-2.17.1/src/iatoolkit/infra/llm_gateway_resolver.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from injector import inject
+
+from iatoolkit.common.exceptions import IAToolkitException
+from iatoolkit.common.interfaces.secret_provider import SecretProvider
+from iatoolkit.common.secret_resolver import resolve_secret
+from iatoolkit.services.configuration_service import ConfigurationService
+
+
+class LLMGatewayResolver:
+    """Resolves optional outbound LLM gateway transport settings."""
+
+    PROVIDER_SLUGS = {
+        "openai": "openai",
+        "deepseek": "deepseek",
+        "anthropic": "anthropic",
+        "gemini": "google-ai-studio",
+    }
+    SUPPORTED_PROVIDERS = frozenset(PROVIDER_SLUGS)
+    CREDENTIAL_MODE_PROVIDER_KEY = "provider_key_in_request"
+    CREDENTIAL_MODE_CLOUDFLARE_MANAGED = "cloudflare_managed"
+
+    @inject
+    def __init__(self, configuration_service: ConfigurationService, secret_provider: SecretProvider):
+        self.configuration_service = configuration_service
+        self.secret_provider = secret_provider
+
+    def resolve(self, company_short_name: str, provider: str, provider_api_key: str | None) -> Dict[str, Any]:
+        normalized_provider = str(provider or "").strip().lower()
+        gateway_cfg = self.configuration_service.get_llm_gateway_config(company_short_name, normalized_provider) or {}
+        if not isinstance(gateway_cfg, dict) or gateway_cfg.get("enabled") is not True:
+            return {
+                "enabled": False,
+                "api_key": provider_api_key or "",
+                "base_url": "",
+                "default_headers": {},
+            }
+
+        vendor = str(gateway_cfg.get("vendor") or "").strip().lower()
+        if vendor != "cloudflare":
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.CONFIG_ERROR,
+                f"Unsupported llm.gateway vendor '{vendor}'.",
+            )
+
+        mode = str(gateway_cfg.get("mode") or "").strip().lower()
+        if mode != "provider_native":
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.CONFIG_ERROR,
+                f"Unsupported llm.gateway mode '{mode}'.",
+            )
+
+        provider_slug = self.PROVIDER_SLUGS.get(normalized_provider)
+        if not provider_slug:
+            return {
+                "enabled": False,
+                "api_key": provider_api_key or "",
+                "base_url": "",
+                "default_headers": {},
+            }
+
+        account_id = self._resolve_gateway_value(
+            company_short_name,
+            gateway_cfg,
+            direct_key="account_id",
+            secret_ref_key="account_id_secret_ref",
+            env_key="account_id_env",
+        )
+        gateway_id = str(gateway_cfg.get("gateway_id") or "").strip()
+        if not account_id or not gateway_id:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.CONFIG_ERROR,
+                "Cloudflare gateway requires resolved account_id and gateway_id.",
+            )
+
+        credential_mode = str(
+            gateway_cfg.get("credential_mode") or self.CREDENTIAL_MODE_PROVIDER_KEY
+        ).strip().lower()
+        authenticated_gateway = gateway_cfg.get("authenticated_gateway") is True
+        default_headers: dict[str, str] = {}
+
+        cloudflare_api_token = self._resolve_gateway_value(
+            company_short_name,
+            gateway_cfg,
+            direct_key="cloudflare_api_token",
+            secret_ref_key="cloudflare_api_token_secret_ref",
+            env_key="cloudflare_api_token_env",
+        )
+        if authenticated_gateway:
+            if not cloudflare_api_token:
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.CONFIG_ERROR,
+                    "Authenticated Cloudflare gateway requires a resolved cloudflare_api_token.",
+                )
+            default_headers["cf-aig-authorization"] = f"Bearer {cloudflare_api_token}"
+
+        if credential_mode == self.CREDENTIAL_MODE_PROVIDER_KEY:
+            if not provider_api_key:
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.API_KEY,
+                    (
+                        f"Cloudflare gateway for provider '{normalized_provider}' requires the provider API key "
+                        "when credential_mode is 'provider_key_in_request'."
+                    ),
+                )
+            resolved_api_key = provider_api_key
+        elif credential_mode == self.CREDENTIAL_MODE_CLOUDFLARE_MANAGED:
+            if not authenticated_gateway:
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.CONFIG_ERROR,
+                    (
+                        "credential_mode 'cloudflare_managed' requires "
+                        "'authenticated_gateway: true' so requests can be authorized with Cloudflare."
+                    ),
+                )
+            # Some SDKs insist on a non-null api_key even when upstream credentials are injected by Cloudflare.
+            resolved_api_key = "" if normalized_provider in {"openai", "deepseek", "gemini"} else None
+        else:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.CONFIG_ERROR,
+                f"Unsupported llm.gateway credential_mode '{credential_mode}'.",
+            )
+
+        byok_alias = str(gateway_cfg.get("byok_alias") or "").strip()
+        if byok_alias:
+            default_headers["cf-aig-byok-alias"] = byok_alias
+
+        return {
+            "enabled": True,
+            "api_key": resolved_api_key,
+            "base_url": f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider_slug}",
+            "default_headers": default_headers,
+            "vendor": vendor,
+            "mode": mode,
+            "credential_mode": credential_mode,
+            "authenticated_gateway": authenticated_gateway,
+        }
+
+    def _resolve_gateway_value(
+        self,
+        company_short_name: str,
+        gateway_cfg: Dict[str, Any],
+        *,
+        direct_key: str,
+        secret_ref_key: str,
+        env_key: str,
+    ) -> str:
+        direct_value = str(gateway_cfg.get(direct_key) or "").strip()
+        if direct_value:
+            return direct_value
+
+        secret_ref = str(gateway_cfg.get(secret_ref_key) or "").strip()
+        if secret_ref:
+            return str(
+                resolve_secret(self.secret_provider, company_short_name, secret_ref, default="") or ""
+            ).strip()
+
+        env_ref = str(gateway_cfg.get(env_key) or "").strip()
+        if env_ref:
+            return str(
+                resolve_secret(self.secret_provider, company_short_name, env_ref, default="") or ""
+            ).strip()
+
+        return ""

{iatoolkit-2.16.3 → iatoolkit-2.17.1}/src/iatoolkit/infra/llm_proxy.py

@@ -17,6 +17,7 @@ from iatoolkit.infra.llm_response import LLMResponse
 from iatoolkit.common.model_registry import ModelRegistry
 from iatoolkit.common.interfaces.secret_provider import SecretProvider
 from iatoolkit.common.secret_resolver import resolve_secret
+from iatoolkit.infra.llm_gateway_resolver import LLMGatewayResolver
 from iatoolkit.services.telemetry_service import NoopTelemetryService
 
 from openai import OpenAI, Timeout         # For OpenAI and xAI (OpenAI-compatible)
@@ -54,6 +55,7 @@ class LLMProxy:
         configuration_service: ConfigurationService,
         model_registry: ModelRegistry,
         secret_provider: SecretProvider,
+        gateway_resolver: LLMGatewayResolver | None = None,
         telemetry_service=None,
     ):
         """
@@ -64,6 +66,10 @@ class LLMProxy:
         self.configuration_service = configuration_service
         self.model_registry = model_registry
         self.secret_provider = secret_provider
+        self.gateway_resolver = gateway_resolver or LLMGatewayResolver(
+            configuration_service=configuration_service,
+            secret_provider=secret_provider,
+        )
         self._telemetry_service = telemetry_service
 
         # adapter cache by (provider, api_key, base_url)
@@ -356,7 +362,7 @@ class LLMProxy:
     def _get_or_create_client(
         self,
         provider: str,
-        api_key: str,
+        api_key: str | None,
         base_url: str = "",
         default_headers: Dict[str, str] | None = None,
         *,
@@ -409,7 +415,7 @@ class LLMProxy:
     def _create_client_for_provider(
         self,
         provider: str,
-        api_key: str,
+        api_key: str | None,
         base_url: str = "",
         default_headers: Dict[str, str] | None = None,
         *,
@@ -432,15 +438,22 @@ class LLMProxy:
 
         if provider == self.PROVIDER_OPENAI:
             # Standard OpenAI client for GPT models
-            return OpenAI(api_key=api_key, timeout=timeout, max_retries=max_retries)
+            return OpenAI(
+                api_key=api_key or "",
+                base_url=base_url or None,
+                timeout=timeout,
+                max_retries=max_retries,
+                default_headers=default_headers or None,
+            )
 
         if provider == self.PROVIDER_XAI:
             # xAI Grok is OpenAI-compatible; we can use the OpenAI client with a different base_url.
             return OpenAI(
-                api_key=api_key,
+                api_key=api_key or "",
                 base_url="https://api.x.ai/v1",
                 timeout=timeout,
                 max_retries=max_retries,
+                default_headers=default_headers or None,
             )
 
         if provider == self.PROVIDER_DEEPSEEK:
@@ -449,10 +462,11 @@ class LLMProxy:
 
             # We use OpenAI client with a DeepSeek base_url:
             return OpenAI(
-                api_key=api_key,
-                base_url="https://api.deepseek.com",
+                api_key=api_key or "",
+                base_url=base_url or "https://api.deepseek.com",
                 timeout=timeout,
                 max_retries=max_retries,
+                default_headers=default_headers or None,
             )
 
         if provider == self.PROVIDER_OPENAI_COMPATIBLE:
@@ -462,10 +476,11 @@ class LLMProxy:
                     "Provider 'openai_compatible' requires a configured base_url."
                 )
             return OpenAI(
-                api_key=api_key,
+                api_key=api_key or "",
                 base_url=base_url,
                 timeout=timeout,
                 max_retries=max_retries,
+                default_headers=default_headers or None,
             )
 
         if provider == self.PROVIDER_OPENROUTER:
@@ -488,7 +503,14 @@ class LLMProxy:
             #
             from google.genai import Client
 
-            return Client(api_key=api_key, http_options={'api_version': 'v1alpha'})
+            gemini_http_options = {"api_version": "v1alpha"}
+            if base_url:
+                gemini_http_options["base_url"] = base_url
+                gemini_http_options["api_version"] = "v1"
+            if default_headers:
+                gemini_http_options["headers"] = dict(default_headers)
+
+            return Client(api_key=api_key, http_options=gemini_http_options)
         if provider == self.PROVIDER_ANTHROPIC:
             try:
                 from anthropic import Anthropic
@@ -498,7 +520,13 @@ class LLMProxy:
                     "Anthropic SDK is not installed. Add 'anthropic' to requirements."
                 ) from ex
 
-            return Anthropic(api_key=api_key)
+            return Anthropic(
+                api_key=api_key,
+                base_url=base_url or None,
+                timeout=timeout,
+                max_retries=max_retries,
+                default_headers=default_headers or None,
+            )
 
         raise IAToolkitException(
             IAToolkitException.ErrorType.MODEL,
@@ -507,10 +535,31 @@ class LLMProxy:
 
     def _get_client_config(self, company_short_name: str, provider: str) -> dict:
         provider_config = self.configuration_service.get_llm_provider_config(company_short_name, provider) or {}
+        provider_api_key = self._get_api_key_from_config(
+            company_short_name,
+            provider,
+            required=False,
+        )
+        gateway_transport = self.gateway_resolver.resolve(
+            company_short_name=company_short_name,
+            provider=provider,
+            provider_api_key=provider_api_key,
+        )
+        if not gateway_transport.get("enabled"):
+            provider_api_key = provider_api_key or self._get_api_key_from_config(
+                company_short_name,
+                provider,
+                required=True,
+            )
+        configured_base_url = self._get_base_url_from_config(company_short_name, provider)
+        configured_headers = self._get_default_headers_from_config(company_short_name, provider)
+        effective_base_url = gateway_transport.get("base_url") or configured_base_url
+        effective_headers = dict(configured_headers)
+        effective_headers.update(gateway_transport.get("default_headers") or {})
         return {
-            "api_key": self._get_api_key_from_config(company_short_name, provider),
-            "base_url": self._get_base_url_from_config(company_short_name, provider),
-            "default_headers": self._get_default_headers_from_config(company_short_name, provider),
+            "api_key": gateway_transport.get("api_key", provider_api_key) if gateway_transport.get("enabled") else provider_api_key,
+            "base_url": effective_base_url,
+            "default_headers": effective_headers,
             "connect_timeout_seconds": self._resolve_provider_float(
                 provider_config,
                 ("connect_timeout_seconds",),
@@ -604,7 +653,7 @@ class LLMProxy:
     # -------------------------------------------------------------------------
     # Configuration helpers
     # -------------------------------------------------------------------------
-    def _get_api_key_from_config(self, company_short_name: str, provider: str) -> str:
+    def _get_api_key_from_config(self, company_short_name: str, provider: str, *, required: bool = True) -> str:
         """
         Read the LLM API key from company configuration and environment variables.
 
@@ -634,6 +683,8 @@ class LLMProxy:
             env_var_name = llm_config["api-key"]
 
         if not env_var_name:
+            if not required:
+                return ""
             raise IAToolkitException(
                 IAToolkitException.ErrorType.API_KEY,
                 f"Company '{company_short_name}' doesn't have an API key configured "
@@ -648,6 +699,8 @@ class LLMProxy:
         )
 
         if not api_key_value:
+            if not required:
+                return ""
             raise IAToolkitException(
                 IAToolkitException.ErrorType.API_KEY,
                 f"Environment variable '{env_var_name}' for company '{company_short_name}' "

{iatoolkit-2.16.3 → iatoolkit-2.17.1}/src/iatoolkit/services/configuration_service.py

@@ -98,6 +98,133 @@ class ConfigurationService:
                     "Must be one of: ['latency', 'price', 'throughput'], or a dictionary."
                 )
 
+    @staticmethod
+    def _validate_llm_gateway_entry(
+        add_error,
+        section: str,
+        gateway_cfg,
+        *,
+        allow_providers: bool,
+        require_complete_config: bool,
+    ) -> None:
+        if not isinstance(gateway_cfg, dict):
+            add_error(section, "Must be a dictionary.")
+            return
+
+        allowed_gateway_providers = {"openai", "deepseek", "anthropic", "gemini"}
+        allowed_gateway_modes = {"provider_native"}
+        allowed_gateway_vendors = {"cloudflare"}
+        allowed_credential_modes = {"provider_key_in_request", "cloudflare_managed"}
+        secret_ref_keys = (
+            "account_id",
+            "account_id_secret_ref",
+            "account_id_env",
+            "cloudflare_api_token_secret_ref",
+            "cloudflare_api_token_env",
+        )
+
+        enabled = gateway_cfg.get("enabled")
+        if enabled is not None and not isinstance(enabled, bool):
+            add_error(f"{section}.enabled", "Must be a boolean.")
+
+        vendor = gateway_cfg.get("vendor")
+        normalized_vendor = ""
+        if vendor is not None:
+            if not isinstance(vendor, str) or not vendor.strip():
+                add_error(f"{section}.vendor", "Must be a non-empty string.")
+            else:
+                normalized_vendor = vendor.strip().lower()
+                if normalized_vendor not in allowed_gateway_vendors:
+                    add_error(
+                        f"{section}.vendor",
+                        f"Unsupported vendor '{normalized_vendor}'. Must be one of: {sorted(allowed_gateway_vendors)}.",
+                    )
+
+        mode = gateway_cfg.get("mode")
+        normalized_mode = ""
+        if mode is not None:
+            if not isinstance(mode, str) or not mode.strip():
+                add_error(f"{section}.mode", "Must be a non-empty string.")
+            else:
+                normalized_mode = mode.strip().lower()
+                if normalized_mode not in allowed_gateway_modes:
+                    add_error(
+                        f"{section}.mode",
+                        f"Unsupported value '{normalized_mode}'. Must be one of: {sorted(allowed_gateway_modes)}.",
+                    )
+
+        gateway_id = gateway_cfg.get("gateway_id")
+        if gateway_id is not None and (not isinstance(gateway_id, str) or not gateway_id.strip()):
+            add_error(f"{section}.gateway_id", "Must be a non-empty string.")
+
+        byok_alias = gateway_cfg.get("byok_alias")
+        if byok_alias is not None and (not isinstance(byok_alias, str) or not byok_alias.strip()):
+            add_error(f"{section}.byok_alias", "Must be a non-empty string.")
+
+        authenticated_gateway = gateway_cfg.get("authenticated_gateway")
+        if authenticated_gateway is not None and not isinstance(authenticated_gateway, bool):
+            add_error(f"{section}.authenticated_gateway", "Must be a boolean.")
+
+        credential_mode = gateway_cfg.get("credential_mode")
+        if credential_mode is not None:
+            if not isinstance(credential_mode, str) or not credential_mode.strip():
+                add_error(f"{section}.credential_mode", "Must be a non-empty string.")
+            elif credential_mode.strip().lower() not in allowed_credential_modes:
+                add_error(
+                    f"{section}.credential_mode",
+                    "Unsupported value. Must be 'provider_key_in_request' or 'cloudflare_managed'.",
+                )
+
+        if allow_providers:
+            providers_cfg = gateway_cfg.get("providers")
+            if providers_cfg is not None and not isinstance(providers_cfg, dict):
+                add_error(f"{section}.providers", "Must be a dictionary.")
+            elif isinstance(providers_cfg, dict):
+                for provider_name, provider_gateway_cfg in providers_cfg.items():
+                    normalized_provider_name = str(provider_name or "").strip().lower()
+                    if normalized_provider_name not in allowed_gateway_providers:
+                        add_error(
+                            f"{section}.providers.{provider_name}",
+                            (
+                                f"Unsupported provider '{normalized_provider_name}'. "
+                                f"Must be one of: {sorted(allowed_gateway_providers)}."
+                            ),
+                        )
+                        continue
+                    ConfigurationService._validate_llm_gateway_entry(
+                        add_error,
+                        f"{section}.providers.{normalized_provider_name}",
+                        provider_gateway_cfg,
+                        allow_providers=False,
+                        require_complete_config=False,
+                    )
+        elif "providers" in gateway_cfg:
+            add_error(f"{section}.providers", "Nested provider overrides are not supported here.")
+
+        is_enabled = gateway_cfg.get("enabled") is True
+        if require_complete_config and is_enabled and not normalized_vendor:
+            add_error(f"{section}.vendor", "Missing required key: 'vendor'.")
+        if require_complete_config and is_enabled and not normalized_mode:
+            add_error(f"{section}.mode", "Missing required key: 'mode'.")
+        if require_complete_config and is_enabled and not str(gateway_cfg.get("gateway_id") or "").strip():
+            add_error(f"{section}.gateway_id", "Missing required key: 'gateway_id'.")
+        if require_complete_config and is_enabled and not any(
+            str(gateway_cfg.get(key) or "").strip() for key in secret_ref_keys[:3]
+        ):
+            add_error(
+                f"{section}.account_id",
+                "One of 'account_id', 'account_id_secret_ref', or 'account_id_env' is required when enabled.",
+            )
+        if is_enabled and gateway_cfg.get("authenticated_gateway") is True:
+            if not any(str(gateway_cfg.get(key) or "").strip() for key in secret_ref_keys[3:]):
+                add_error(
+                    f"{section}.cloudflare_api_token_secret_ref",
+                    (
+                        "One of 'cloudflare_api_token_secret_ref' or 'cloudflare_api_token_env' "
+                        "is required when 'authenticated_gateway' is true."
+                    ),
+                )
+
     def load_configuration(self, company_short_name: str):
         """
         Main entry point for configuring a company instance.
@@ -582,6 +709,16 @@ class ConfigurationService:
                                             "Must be an absolute HTTP or HTTPS URL.",
                                         )
 
+            gateway_cfg = config.get("llm", {}).get("gateway")
+            if gateway_cfg is not None:
+                self._validate_llm_gateway_entry(
+                    add_error,
+                    "llm.gateway",
+                    gateway_cfg,
+                    allow_providers=True,
+                    require_complete_config=True,
+                )
+
         # 3. Embedding Provider
         if isinstance(config.get("embedding_provider"), dict):
             if not config.get("embedding_provider", {}).get("provider"):
@@ -1219,6 +1356,35 @@ class ConfigurationService:
         provider_cfg = providers_cfg.get(candidate)
         return dict(provider_cfg) if isinstance(provider_cfg, dict) else {}
 
+    def get_llm_gateway_config(self, company_short_name: str, provider: str | None = None) -> dict:
+        self._ensure_config_loaded(company_short_name)
+        llm_config = self._loaded_configs[company_short_name].get("llm") or {}
+        gateway_cfg = llm_config.get("gateway")
+        if not isinstance(gateway_cfg, dict):
+            return {}
+
+        resolved_gateway_cfg = {
+            key: value
+            for key, value in gateway_cfg.items()
+            if key != "providers"
+        }
+
+        candidate = str(provider or "").strip().lower()
+        if not candidate:
+            return dict(resolved_gateway_cfg)
+
+        provider_overrides = gateway_cfg.get("providers")
+        if not isinstance(provider_overrides, dict):
+            return dict(resolved_gateway_cfg)
+
+        provider_gateway_cfg = provider_overrides.get(candidate)
+        if not isinstance(provider_gateway_cfg, dict):
+            return dict(resolved_gateway_cfg)
+
+        merged_gateway_cfg = dict(resolved_gateway_cfg)
+        merged_gateway_cfg.update(provider_gateway_cfg)
+        return merged_gateway_cfg
+
     def get_llm_telemetry_config(self, company_short_name: str) -> dict:
         self._ensure_config_loaded(company_short_name)
         llm_config = self._loaded_configs[company_short_name].get("llm") or {}

{iatoolkit-2.16.3 → iatoolkit-2.17.1/src/iatoolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.16.3
+Version: 2.17.1
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.16.3 → iatoolkit-2.17.1}/src/iatoolkit.egg-info/SOURCES.txt

@@ -66,6 +66,7 @@ src/iatoolkit/infra/google_chat_app.py
 src/iatoolkit/infra/inference_embeddings_client.py
 src/iatoolkit/infra/inference_handler.py
 src/iatoolkit/infra/jina_embeddings_client.py
+src/iatoolkit/infra/llm_gateway_resolver.py
 src/iatoolkit/infra/llm_proxy.py
 src/iatoolkit/infra/llm_response.py
 src/iatoolkit/infra/redis_session_manager.py