iatoolkit 2.3.2__tar.gz → 2.4.0__tar.gz

{iatoolkit-2.3.2/src/iatoolkit.egg-info → iatoolkit-2.4.0}/PKG-INFO

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

{iatoolkit-2.3.2 → iatoolkit-2.4.0}/src/iatoolkit/__init__.py

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

{iatoolkit-2.3.2 → iatoolkit-2.4.0}/src/iatoolkit/config/llm_capabilities.yaml

@@ -58,6 +58,24 @@ openai_compatible:
   max_file_size_mb: 0
   max_files_per_request: 0
 
+openrouter:
+  supports_native_files: true
+  supports_native_images: true
+  supported_mime_types:
+    - application/pdf
+    - text/plain
+    - text/csv
+    - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
+    - application/vnd.openxmlformats-officedocument.presentationml.presentation
+    - application/json
+    - application/xml
+    - text/xml
+  preferred_native_mime_types:
+    - application/pdf
+  max_file_size_mb: 20
+  max_files_per_request: 10
+
 unknown:
   supports_native_files: false
   supports_native_images: false

{iatoolkit-2.3.2 → iatoolkit-2.4.0}/src/iatoolkit/config/system_prompts_pack.yaml

@@ -2,42 +2,47 @@ version: 2
 prompts:
   - key: core_identity
     filename: core_identity.prompt
+    section: identity
     include:
       execution_modes:
         - chat
         - agent
   - key: chat_user_profile
     filename: chat_user_profile.prompt
+    section: identity
     include:
       execution_modes:
         - chat
   - key: chat_state_rules
     filename: chat_state_rules.prompt
+    section: conversation_rules
     include:
       execution_modes:
         - chat
   - key: links_documents
     filename: links_documents.prompt
+    section: conversation_rules
     include:
       execution_modes:
         - chat
         - agent
   - key: memory_usage
     filename: memory_usage.prompt
+    section: conversation_rules
     include:
       execution_modes:
         - chat
-        - agent
       all_capabilities:
         - can_use_memory
   - key: multimodal_basics
     filename: multimodal_basics.prompt
+    section: conversation_rules
     include:
       execution_modes:
         - chat
-        - agent
   - key: output_basics
     filename: output_basics.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
@@ -46,6 +51,7 @@ prompts:
         - chat_compatible
   - key: presentation_formatting
     filename: presentation_formatting.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
@@ -53,6 +59,7 @@ prompts:
         - chat_compatible
   - key: html_structures
     filename: html_structures.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
@@ -60,12 +67,14 @@ prompts:
         - chat_compatible
   - key: tool_html_passthrough
     filename: tool_html_passthrough.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
         - agent
   - key: file_download_output
     filename: file_download_output.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
@@ -74,6 +83,7 @@ prompts:
         - can_generate_files
   - key: email_output
     filename: email_output.prompt
+    section: output_contract
     include:
       execution_modes:
         - chat
@@ -82,6 +92,7 @@ prompts:
         - can_send_email
   - key: sql_core
     filename: sql_core.prompt
+    section: data_access_rules
     include:
       execution_modes:
         - chat
@@ -90,6 +101,7 @@ prompts:
         - can_query_sql
   - key: sql_jsonb
     filename: sql_jsonb.prompt
+    section: data_access_rules
     include:
       execution_modes:
         - chat
@@ -98,6 +110,7 @@ prompts:
         - can_query_sql
   - key: sql_casting
     filename: sql_casting.prompt
+    section: data_access_rules
     include:
       execution_modes:
         - chat
@@ -106,6 +119,7 @@ prompts:
         - can_query_sql
   - key: sql_aggregation_scope
     filename: sql_aggregation_scope.prompt
+    section: data_access_rules
     include:
       execution_modes:
         - chat

{iatoolkit-2.3.2 → iatoolkit-2.4.0}/src/iatoolkit/infra/llm_providers/openai_compatible_chat_adapter.py

@@ -3,7 +3,9 @@
 #
 # IAToolkit is open source software.
 
+import base64
 import logging
+import mimetypes
 from typing import Any, Dict, List, Optional
 
 from iatoolkit.common.exceptions import IAToolkitException
@@ -12,12 +14,17 @@ from iatoolkit.infra.llm_response import LLMResponse, ToolCall, Usage
 
 class OpenAICompatibleChatAdapter:
     """
-    Adapter for OpenAI-compatible Chat Completions APIs.
+    Adapter for Chat Completions-style providers.
 
-    This adapter is used for providers that expose a `chat.completions` style
-    interface with `messages`, `tools`, and `tool_calls`.
+    This adapter targets providers that expose a `chat.completions` compatible
+    endpoint with `messages`, `tools`, `tool_calls`, and `response_format`.
     """
 
+    supports_multimodal = False
+    supports_reasoning = False
+    supports_metadata = False
+    supports_parallel_tool_calls = False
+
     def __init__(self, openai_compatible_client, provider_label: str = "OpenAI-compatible"):
         self.client = openai_compatible_client
         self.provider_label = provider_label
@@ -37,14 +44,10 @@ class OpenAICompatibleChatAdapter:
         tool_choice = kwargs.get("tool_choice", "auto")
         context_history = kwargs.get("context_history") or []
         images = kwargs.get("images") or []
+        attachments = kwargs.get("attachments") or []
         text = kwargs.get("text") or {}
-
-        if images:
-            logging.warning(
-                "[%sAdapter] Images provided but these models are not multimodal. Ignoring %s images.",
-                self.provider_label,
-                len(images),
-            )
+        reasoning = kwargs.get("reasoning")
+        metadata = kwargs.get("metadata")
 
         try:
             messages: List[Dict[str, Any]] = []
@@ -55,6 +58,18 @@ class OpenAICompatibleChatAdapter:
             current_messages = self._build_messages_from_input(input)
             messages.extend(current_messages)
 
+            if images or attachments:
+                if self.supports_multimodal:
+                    messages = self._prepare_multimodal_messages(messages, images, attachments)
+                else:
+                    logging.warning(
+                        "[%sAdapter] Multimodal content provided but this provider is configured as text-only. "
+                        "Ignoring %s images and %s attachments.",
+                        self.provider_label,
+                        len(images),
+                        len(attachments),
+                    )
+
             has_function_outputs = any(
                 item.get("type") == "function_call_output" for item in input
             )
@@ -77,10 +92,25 @@ class OpenAICompatibleChatAdapter:
             }
             if tools_payload:
                 call_kwargs["tools"] = tools_payload
-            if tool_choice:
-                call_kwargs["tool_choice"] = tool_choice
-            if isinstance(text, dict) and isinstance(text.get("response_format"), dict):
-                call_kwargs["response_format"] = text["response_format"]
+
+            tool_choice_payload = self._map_tool_choice(tool_choice, tools_payload or [])
+            if tool_choice_payload is not None:
+                call_kwargs["tool_choice"] = tool_choice_payload
+
+            response_format = self._extract_response_format(text)
+            if response_format:
+                call_kwargs["response_format"] = response_format
+
+            if self.supports_reasoning and reasoning:
+                call_kwargs["reasoning"] = reasoning
+
+            if self.supports_metadata and metadata:
+                call_kwargs["metadata"] = metadata
+
+            if self.supports_parallel_tool_calls and kwargs.get("parallel_tool_calls") is not None:
+                call_kwargs["parallel_tool_calls"] = bool(kwargs.get("parallel_tool_calls"))
+
+            self._extend_call_kwargs(call_kwargs, kwargs)
 
             logging.debug(
                 "[%sAdapter] Calling chat.completions API with %s messages.",
@@ -100,6 +130,10 @@ class OpenAICompatibleChatAdapter:
                 f"{self.provider_label} error: {ex}"
             ) from ex
 
+    def _extend_call_kwargs(self, call_kwargs: Dict[str, Any], kwargs: Dict[str, Any]) -> None:
+        _ = call_kwargs
+        _ = kwargs
+
     def _build_messages_from_input(self, input_items: List[Dict]) -> List[Dict]:
         messages: List[Dict[str, Any]] = []
 
@@ -114,29 +148,145 @@ class OpenAICompatibleChatAdapter:
                     )
                     continue
 
-                messages.append(
-                    {
-                        "role": "user",
-                        "content": f"Tool result:\n{output}",
-                    }
-                )
+                tool_message: Dict[str, Any] = {
+                    "role": "tool",
+                    "content": output,
+                }
+                call_id = str(item.get("call_id") or "").strip()
+                if call_id:
+                    tool_message["tool_call_id"] = call_id
+                messages.append(tool_message)
                 continue
 
-            role = item.get("role")
+            role = str(item.get("role") or "").strip().lower()
             content = item.get("content")
 
-            if role == "tool":
-                logging.warning("[%sAdapter] Skipping tool-role message: %s", self.provider_label, item)
-                continue
-
             if not role:
                 logging.warning("[%sAdapter] Skipping message without role: %s", self.provider_label, item)
                 continue
 
-            messages.append({"role": role, "content": content})
+            if role == "model":
+                role = "assistant"
+
+            message: Dict[str, Any] = {"role": role, "content": content}
+            tool_call_id = str(item.get("tool_call_id") or "").strip()
+            if role == "tool" and tool_call_id:
+                message["tool_call_id"] = tool_call_id
+
+            annotations = item.get("annotations")
+            if annotations is not None:
+                message["annotations"] = annotations
+
+            messages.append(message)
 
         return messages
 
+    def _prepare_multimodal_messages(
+        self,
+        messages: List[Dict[str, Any]],
+        images: List[Dict],
+        attachments: List[Dict],
+    ) -> List[Dict[str, Any]]:
+        target_index = None
+        for index in range(len(messages) - 1, -1, -1):
+            if messages[index].get("role") == "user":
+                target_index = index
+                break
+
+        if target_index is None:
+            return messages
+
+        target_message = dict(messages[target_index])
+        content_parts = self._coerce_content_to_parts(target_message.get("content"))
+
+        for img in images:
+            image_part = self._build_image_part(img)
+            if image_part is not None:
+                content_parts.append(image_part)
+
+        for attachment in attachments:
+            file_part = self._build_file_part(attachment)
+            if file_part is not None:
+                content_parts.append(file_part)
+
+        target_message["content"] = content_parts
+        updated_messages = list(messages)
+        updated_messages[target_index] = target_message
+        return updated_messages
+
+    @staticmethod
+    def _coerce_content_to_parts(content: Any) -> List[Dict[str, Any]]:
+        if isinstance(content, list):
+            return list(content)
+        if content in (None, ""):
+            return []
+        return [{"type": "text", "text": str(content)}]
+
+    def _build_image_part(self, image: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        if not isinstance(image, dict):
+            return None
+
+        filename = str(image.get("name") or image.get("filename") or "").strip()
+        mime_type = str(image.get("mime_type") or image.get("type") or "").strip().lower()
+        if not mime_type:
+            mime_type = mimetypes.guess_type(filename)[0] or "image/jpeg"
+
+        raw_url = str(image.get("url") or image.get("image_url") or "").strip()
+        if raw_url:
+            data_url = raw_url
+        else:
+            base64_data = str(image.get("base64") or image.get("content") or "").strip()
+            if not base64_data:
+                return None
+            data_url = self._to_data_url(base64_data, mime_type)
+
+        return {
+            "type": "image_url",
+            "image_url": {
+                "url": data_url,
+            },
+        }
+
+    def _build_file_part(self, attachment: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        if not isinstance(attachment, dict):
+            return None
+
+        filename = str(attachment.get("name") or attachment.get("filename") or "attachment").strip()
+        mime_type = str(
+            attachment.get("mime_type")
+            or attachment.get("type")
+            or mimetypes.guess_type(filename)[0]
+            or "application/octet-stream"
+        ).strip().lower()
+
+        raw_file_data = str(attachment.get("file_data") or attachment.get("url") or "").strip()
+        if raw_file_data:
+            file_data = raw_file_data
+        else:
+            base64_data = str(attachment.get("base64") or attachment.get("content") or "").strip()
+            if not base64_data:
+                return None
+            file_data = self._to_data_url(base64_data, mime_type)
+
+        return {
+            "type": "file",
+            "file": {
+                "filename": filename,
+                "file_data": file_data,
+            },
+        }
+
+    @staticmethod
+    def _to_data_url(base64_data: str, mime_type: str) -> str:
+        payload = str(base64_data or "").strip()
+        if payload.lower().startswith("data:") and "," in payload:
+            return payload
+        try:
+            base64.b64decode(payload, validate=True)
+            return f"data:{mime_type};base64,{payload}"
+        except Exception:
+            return payload
+
     def _build_tools_payload(self, tools: List[Dict]) -> Optional[List[Dict]]:
         if not tools:
             return None
@@ -145,7 +295,7 @@ class OpenAICompatibleChatAdapter:
 
         for tool in tools:
             if "function" in tool:
-                func_def = tool["function"]
+                func_def = dict(tool["function"] or {})
             else:
                 func_def = {
                     "name": tool.get("name"),
@@ -172,6 +322,41 @@ class OpenAICompatibleChatAdapter:
 
         return tools_payload or None
 
+    @staticmethod
+    def _map_tool_choice(
+        tool_choice: Any,
+        tools_payload: List[Dict[str, Any]],
+    ) -> Optional[Dict[str, Any] | str]:
+        if tool_choice in ("", None, "auto"):
+            return None
+
+        if isinstance(tool_choice, dict):
+            return tool_choice
+
+        if tool_choice in {"none", "required"}:
+            return tool_choice
+
+        tool_names = {
+            str((tool.get("function") or {}).get("name") or "").strip()
+            for tool in (tools_payload or [])
+            if isinstance(tool, dict)
+        }
+        if str(tool_choice).strip() in tool_names:
+            return {
+                "type": "function",
+                "function": {
+                    "name": str(tool_choice).strip(),
+                },
+            }
+
+        return str(tool_choice)
+
+    @staticmethod
+    def _extract_response_format(text: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        if isinstance(text, dict) and isinstance(text.get("response_format"), dict):
+            return dict(text["response_format"])
+        return None
+
     def _map_chat_completion_response(self, response: Any) -> LLMResponse:
         if not response.choices:
             raise IAToolkitException(

iatoolkit-2.4.0/src/iatoolkit/infra/llm_providers/openrouter_adapter.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from typing import Any, Dict
+
+from iatoolkit.infra.llm_providers.openai_compatible_chat_adapter import OpenAICompatibleChatAdapter
+
+
+class OpenRouterAdapter(OpenAICompatibleChatAdapter):
+    """OpenRouter-specific adapter built on top of the shared chat.completions core."""
+
+    supports_multimodal = True
+    supports_reasoning = False
+    supports_metadata = True
+    supports_parallel_tool_calls = True
+
+    def __init__(self, openrouter_client):
+        super().__init__(openai_compatible_client=openrouter_client, provider_label="OpenRouter")
+
+    def _extend_call_kwargs(self, call_kwargs: Dict[str, Any], kwargs: Dict[str, Any]) -> None:
+        text = kwargs.get("text") or {}
+        verbosity = text.get("verbosity") if isinstance(text, dict) else None
+        if verbosity:
+            call_kwargs["verbosity"] = verbosity
+
+        passthrough_keys = (
+            "service_tier",
+            "temperature",
+            "top_p",
+            "max_tokens",
+            "max_completion_tokens",
+            "seed",
+            "stop",
+            "stream",
+            "stream_options",
+            "modalities",
+            "user",
+        )
+        for key in passthrough_keys:
+            if kwargs.get(key) is not None:
+                call_kwargs[key] = kwargs.get(key)
+
+        extra_body = dict(call_kwargs.get("extra_body") or {})
+
+        reasoning = kwargs.get("reasoning")
+        if isinstance(reasoning, dict) and reasoning:
+            extra_body["reasoning"] = dict(reasoning)
+
+        vendor_specific_keys = (
+            "models",
+            "provider",
+            "plugins",
+            "session_id",
+        )
+        for key in vendor_specific_keys:
+            if kwargs.get(key) is not None:
+                extra_body[key] = kwargs.get(key)
+
+        if extra_body:
+            call_kwargs["extra_body"] = extra_body

{iatoolkit-2.3.2 → iatoolkit-2.4.0}/src/iatoolkit/infra/llm_proxy.py

@@ -7,7 +7,9 @@
 from iatoolkit.services.configuration_service import ConfigurationService
 from iatoolkit.infra.llm_providers.openai_adapter import OpenAIAdapter
 from iatoolkit.infra.llm_providers.gemini_adapter import GeminiAdapter
+from iatoolkit.infra.llm_providers.deepseek_adapter import DeepseekAdapter
 from iatoolkit.infra.llm_providers.openai_compatible_chat_adapter import OpenAICompatibleChatAdapter
+from iatoolkit.infra.llm_providers.openrouter_adapter import OpenRouterAdapter
 from iatoolkit.infra.llm_providers.anthropic_adapter import AnthropicAdapter
 from iatoolkit.common.exceptions import IAToolkitException
 from iatoolkit.common.util import Utility
@@ -39,6 +41,7 @@ class LLMProxy:
     PROVIDER_XAI = "xai"
     PROVIDER_ANTHROPIC = "anthropic"
     PROVIDER_OPENAI_COMPATIBLE = "openai_compatible"
+    PROVIDER_OPENROUTER = "openrouter"
     DEFAULT_CONNECT_TIMEOUT_SECONDS = 10.0
     DEFAULT_READ_TIMEOUT_SECONDS = 300.0
     DEFAULT_MAX_RETRIES = 0
@@ -145,6 +148,7 @@ class LLMProxy:
         client_config = self._get_client_config(company_short_name, provider)
         api_key = client_config["api_key"]
         base_url = client_config.get("base_url") or ""
+        default_headers = client_config.get("default_headers") or {}
         connect_timeout_seconds = client_config["connect_timeout_seconds"]
         read_timeout_seconds = client_config["read_timeout_seconds"]
         max_retries = client_config["max_retries"]
@@ -152,6 +156,7 @@ class LLMProxy:
             provider,
             api_key or "",
             base_url,
+            tuple(sorted(default_headers.items())),
             connect_timeout_seconds,
             read_timeout_seconds,
             max_retries,
@@ -166,6 +171,7 @@ class LLMProxy:
             provider,
             api_key,
             base_url=base_url,
+            default_headers=default_headers,
             connect_timeout_seconds=connect_timeout_seconds,
             read_timeout_seconds=read_timeout_seconds,
             max_retries=max_retries,
@@ -177,9 +183,11 @@ class LLMProxy:
         elif provider == self.PROVIDER_GEMINI:
             adapter = GeminiAdapter(client)
         elif provider == self.PROVIDER_DEEPSEEK:
-            adapter = OpenAICompatibleChatAdapter(client, provider_label="DeepSeek")
+            adapter = DeepseekAdapter(client)
         elif provider == self.PROVIDER_OPENAI_COMPATIBLE:
             adapter = OpenAICompatibleChatAdapter(client, provider_label="OpenAI-compatible")
+        elif provider == self.PROVIDER_OPENROUTER:
+            adapter = OpenRouterAdapter(client)
         elif provider == self.PROVIDER_ANTHROPIC:
             adapter = AnthropicAdapter(client)
         else:
@@ -199,7 +207,7 @@ class LLMProxy:
     ) -> Dict[str, Any]:
         effective_kwargs = dict(request_kwargs or {})
 
-        if provider != self.PROVIDER_OPENAI_COMPATIBLE:
+        if provider not in {self.PROVIDER_OPENAI_COMPATIBLE, self.PROVIDER_OPENROUTER}:
             return effective_kwargs
 
         if provider_config.get("disable_tools") is True:
@@ -219,6 +227,7 @@ class LLMProxy:
         provider: str,
         api_key: str,
         base_url: str = "",
+        default_headers: Dict[str, str] | None = None,
         *,
         connect_timeout_seconds: float | None = None,
         read_timeout_seconds: float | None = None,
@@ -244,6 +253,7 @@ class LLMProxy:
             provider,
             api_key or "",
             base_url or "",
+            tuple(sorted((default_headers or {}).items())),
             connect_timeout_seconds,
             read_timeout_seconds,
             max_retries,
@@ -257,6 +267,7 @@ class LLMProxy:
                 provider,
                 api_key,
                 base_url=base_url,
+                default_headers=default_headers,
                 connect_timeout_seconds=connect_timeout_seconds,
                 read_timeout_seconds=read_timeout_seconds,
                 max_retries=max_retries,
@@ -269,6 +280,7 @@ class LLMProxy:
         provider: str,
         api_key: str,
         base_url: str = "",
+        default_headers: Dict[str, str] | None = None,
         *,
         connect_timeout_seconds: float | None = None,
         read_timeout_seconds: float | None = None,
@@ -325,6 +337,20 @@ class LLMProxy:
                 max_retries=max_retries,
             )
 
+        if provider == self.PROVIDER_OPENROUTER:
+            if not base_url:
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.CONFIG_ERROR,
+                    "Provider 'openrouter' requires a configured base_url."
+                )
+            return OpenAI(
+                api_key=api_key,
+                base_url=base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                default_headers=default_headers or None,
+            )
+
         if provider == self.PROVIDER_GEMINI:
             # Example placeholder: you may already have a Gemini client factory elsewhere.
             # Here you could create and configure the Gemini client (e.g. google.generativeai).
@@ -353,6 +379,7 @@ class LLMProxy:
         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),
             "connect_timeout_seconds": self._resolve_provider_float(
                 provider_config,
                 ("connect_timeout_seconds",),
@@ -499,7 +526,7 @@ class LLMProxy:
         return api_key_value
 
     def _get_base_url_from_config(self, company_short_name: str, provider: str) -> str:
-        if provider != self.PROVIDER_OPENAI_COMPATIBLE:
+        if provider not in {self.PROVIDER_OPENAI_COMPATIBLE, self.PROVIDER_OPENROUTER}:
             return ""
 
         provider_config = self.configuration_service.get_llm_provider_config(company_short_name, provider) or {}
@@ -528,6 +555,27 @@ class LLMProxy:
 
         return base_url
 
+    def _get_default_headers_from_config(self, company_short_name: str, provider: str) -> dict:
+        if provider != self.PROVIDER_OPENROUTER:
+            return {}
+
+        provider_config = self.configuration_service.get_llm_provider_config(company_short_name, provider) or {}
+        if not isinstance(provider_config, dict):
+            provider_config = {}
+
+        headers: dict[str, str] = {}
+
+        http_referer = str(provider_config.get("http_referer") or "").strip()
+        if http_referer:
+            headers["HTTP-Referer"] = http_referer
+
+        x_title = str(provider_config.get("x_title") or "").strip()
+        if x_title:
+            headers["X-Title"] = x_title
+            headers["X-OpenRouter-Title"] = x_title
+
+        return headers
+
     @classmethod
     def clear_low_level_clients_cache(cls):
         with cls._clients_cache_lock: