iatoolkit 2.20.0__tar.gz → 2.20.1__tar.gz

{iatoolkit-2.20.0/src/iatoolkit.egg-info → iatoolkit-2.20.1}/PKG-INFO

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

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/__init__.py

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

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/config/system_tools_pack.yaml

@@ -5,6 +5,12 @@ pack:
 tools:
   - function_name: iat_generate_excel
     description: Generador de Excel.Genera un archivo Excel (.xlsx) a partir de una lista de diccionarios. Cada diccionario representa una fila del archivo. el archivo se guarda en storage.retorna diccionario con filename y attachment_token (para recuperar el archivo)content_type y download_link
+    output_contract:
+      kind: file
+      mime_type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+      transport: signed_url
+      url_field: download_link
+      filename_field: filename
     routing_profile:
       tags:
         - excel
@@ -54,6 +60,12 @@ tools:
         - data
   - function_name: iat_generate_pdf
     description: Generador de PDF. Convierte contenido HTML o Markdown en un archivo PDF descargable. El archivo se guarda en storage y retorna filename, attachment_token, content_type y download_link.
+    output_contract:
+      kind: file
+      mime_type: application/pdf
+      transport: signed_url
+      url_field: download_link
+      filename_field: filename
     routing_profile:
       tags:
         - pdf

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/locales/en.yaml

@@ -1581,12 +1581,29 @@ ui:
     visual_editor: "Visual Editor"
     yaml_badge: "YAML"
     yaml_json_badge: "YAML / JSON"
+    tab_general: "General"
+    tab_input: "Input"
+    tab_execution: "Execution"
+    tab_output: "Output"
+    tab_routing: "Routing"
+    tab_raw: "Raw"
+    general_hint: "Define the tool identity first, then move through input, execution, output, and routing as needed."
+    execution_hint: "Define how this tool executes and what runtime contract it depends on."
+    execution_hint_http: "HTTP tools define request/auth/response behavior in execution_config."
+    execution_hint_inference: "Inference tools usually rely on external runtime model settings; use Output to describe the returned artifact."
+    execution_hint_native: "Native tools execute through toolkit runtime code, so there is no editable execution_config here."
+    inference_execution_hint: "This tool type does not expose an editable execution_config in the GUI. Use the Output tab to document what the runtime returns."
+    native_execution_hint: "This tool type executes through internal runtime code. There is no editable execution_config in this editor."
+    raw_hint: "Edit the full tool definition as YAML. This advanced mode includes parameters, execution_config, output_contract, and routing_profile."
+    raw_footer_hint: "Saving from Raw uses this document as the source of truth for the tool definition."
 
     # Modal
     modal_title: "Create New Tool"
     modal_name_label: "Tool Name (LLM Function)"
     modal_name_help: "Use snake_case. Must be unique."
     modal_type_label: "Type"
+    modal_output_preset_label: "Output preset"
+    modal_output_preset_none: "No preset"
     modal_desc_label: "Short Description"
     modal_desc_placeholder: "Briefly explain what this tool does..."
     modal_cancel: "Cancel"
@@ -1607,6 +1624,10 @@ ui:
     http_config_help_description: "Use version: 1 and define request/auth/response. Keep URLs as absolute HTTPS."
     http_config_help_get_example: "GET example"
     http_config_help_post_example: "POST example (Bearer from secrets_manager)"
+    output_contract_title: "Output Contract"
+    output_contract_hint: "Optional. Use YAML/JSON to describe the returned artifact, for example kind/image/file/audio/video plus transport and field names such as image_url or download_link."
+    modal_output_contract_label: "Initial output_contract"
+    modal_output_contract_placeholder: "kind: image\nmime_type: image/png\ntransport: signed_url\nurl_field: image_url"
     routing_profile_title: "Routing Profile"
     routing_profile_hint: "Used by enterprise tool routing to rank and select candidate tools."
 
@@ -2568,6 +2589,7 @@ js_messages:
   tool_pack_read_only: "PACK tools are read-only. Use Clone to USER."
   tool_invalid_yaml_format: "Invalid YAML format: {message}"
   tool_http_execution_config_label: "HTTP execution_config"
+  tool_output_contract_label: "output_contract"
   tool_invalid_http_execution_config: "Invalid HTTP execution_config"
   tool_error_saving: "Error saving tool"
   tool_saved_ok: "Tool saved successfully"
@@ -2577,6 +2599,7 @@ js_messages:
   tool_error_cloning_pack: "Error cloning PACK tool"
   tool_pack_cloned_ok: "PACK tool cloned as USER tool"
   tool_name_required: "Name is required"
+  tool_description_required: "Description is required"
   tool_error_creating: "Error creating tool"
   tool_created_ok: "Tool created"
   tool_status_active: "Active"
@@ -2590,6 +2613,7 @@ js_messages:
   tool_routing_profile_cost_object: "routing_profile.cost must be an object"
   tool_routing_profile_penalty_non_negative: "routing_profile.cost.penalty must be a non-negative number"
   tool_routing_profile_label: "routing_profile"
+  tool_output_contract_object: "output_contract must be an object"
   tool_invalid_routing_profile: "Invalid routing_profile"
   tool_error_loading_routing_profile: "Error loading routing profile"
   tool_error_saving_routing_profile: "Error saving routing profile"

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/locales/es.yaml

@@ -1585,12 +1585,29 @@ ui:
     visual_editor: "Editor Visual"
     yaml_badge: "YAML"
     yaml_json_badge: "YAML / JSON"
+    tab_general: "General"
+    tab_input: "Input"
+    tab_execution: "Execution"
+    tab_output: "Output"
+    tab_routing: "Routing"
+    tab_raw: "Raw"
+    general_hint: "Define primero la identidad de la tool y luego avanza por input, execution, output y routing según lo necesites."
+    execution_hint: "Define cómo se ejecuta esta tool y de qué contrato de runtime depende."
+    execution_hint_http: "Las tools HTTP definen request/auth/response en execution_config."
+    execution_hint_inference: "Las tools de inference suelen depender de settings externos del runtime; usa Output para describir el artefacto devuelto."
+    execution_hint_native: "Las tools nativas se ejecutan en código interno del runtime, por eso aquí no existe un execution_config editable."
+    inference_execution_hint: "Este tipo de tool no expone un execution_config editable en la GUI. Usa el tab Output para documentar qué devuelve el runtime."
+    native_execution_hint: "Este tipo de tool se ejecuta mediante código interno del runtime. No hay un execution_config editable en este editor."
+    raw_hint: "Edita la definición completa de la tool como YAML. Este modo avanzado incluye parameters, execution_config, output_contract y routing_profile."
+    raw_footer_hint: "Guardar desde Raw usa este documento como source of truth de la definición de la tool."
 
     # Modal
     modal_title: "Crear Nueva Herramienta"
     modal_name_label: "Nombre (Función LLM)"
     modal_name_help: "Usar snake_case. Debe ser único."
     modal_type_label: "Tipo"
+    modal_output_preset_label: "Preset de output"
+    modal_output_preset_none: "Sin preset"
     modal_desc_label: "Descripción Corta"
     modal_desc_placeholder: "Explica brevemente qué hace esta herramienta..."
     modal_cancel: "Cancelar"
@@ -1611,6 +1628,10 @@ ui:
     http_config_help_description: "Usa version: 1 y define request/auth/response. Mantén URLs HTTPS absolutas."
     http_config_help_get_example: "Ejemplo GET"
     http_config_help_post_example: "Ejemplo POST (Bearer desde secrets_manager)"
+    output_contract_title: "Output Contract"
+    output_contract_hint: "Opcional. Usa YAML/JSON para describir el artefacto devuelto, por ejemplo kind/image/file/audio/video más transport y nombres de campos como image_url o download_link."
+    modal_output_contract_label: "output_contract inicial"
+    modal_output_contract_placeholder: "kind: image\nmime_type: image/png\ntransport: signed_url\nurl_field: image_url"
     routing_profile_title: "Routing Profile"
     routing_profile_hint: "Usado por el router enterprise para rankear y seleccionar herramientas candidatas."
 
@@ -2571,6 +2592,7 @@ js_messages:
   tool_pack_read_only: "Las herramientas PACK son de solo lectura. Usa Clonar a USER."
   tool_invalid_yaml_format: "Formato YAML inválido: {message}"
   tool_http_execution_config_label: "execution_config HTTP"
+  tool_output_contract_label: "output_contract"
   tool_invalid_http_execution_config: "execution_config HTTP inválido"
   tool_error_saving: "Error guardando herramienta"
   tool_saved_ok: "Herramienta guardada correctamente"
@@ -2580,6 +2602,7 @@ js_messages:
   tool_error_cloning_pack: "Error al clonar herramienta PACK"
   tool_pack_cloned_ok: "Herramienta PACK clonada como herramienta USER"
   tool_name_required: "El nombre es obligatorio"
+  tool_description_required: "La descripción es obligatoria"
   tool_error_creating: "Error creando herramienta"
   tool_created_ok: "Herramienta creada"
   tool_status_active: "Activo"
@@ -2593,6 +2616,7 @@ js_messages:
   tool_routing_profile_cost_object: "routing_profile.cost debe ser un objeto"
   tool_routing_profile_penalty_non_negative: "routing_profile.cost.penalty debe ser un número no negativo"
   tool_routing_profile_label: "routing_profile"
+  tool_output_contract_object: "output_contract debe ser un objeto"
   tool_invalid_routing_profile: "routing_profile inválido"
   tool_error_loading_routing_profile: "Error cargando routing profile"
   tool_error_saving_routing_profile: "Error guardando routing profile"

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/repositories/llm_query_repo.py

@@ -120,6 +120,7 @@ class LLMQueryRepo:
             tool.description = new_tool.description
             tool.parameters = new_tool.parameters
             tool.execution_config = new_tool.execution_config
+            tool.output_contract = new_tool.output_contract
             tool.tool_type = new_tool.tool_type
             tool.source = new_tool.source
             if new_tool.is_active is not None:

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/repositories/models.py

@@ -254,6 +254,7 @@ class Tool(Base):
     description = Column(Text, nullable=False)
     parameters = Column(JSON, nullable=False)
     execution_config = Column(JSON_NATIVE, nullable=True)
+    output_contract = Column(JSON_NATIVE, nullable=True)
     is_active = Column(Boolean, default=True)
     created_at = Column(DateTime, default=datetime.now)
 

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/services/inference_service.py

@@ -101,7 +101,7 @@ class InferenceService:
             payload["parameters"] = parameters
 
         # 4. Execute Call
-        logging.debug(f"Called inference tool {tool_name} with model {model_id}.")
+        logging.info("Calling inference tool %s with model %s.", tool_name, model_id)
         response_data = self._call_endpoint(
             endpoint_url,
             api_key,

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/services/system_tools.py

@@ -6,6 +6,8 @@ from typing import Any
 
 import yaml
 
+from iatoolkit.services.tool_output_contract import clone_output_contract, normalize_output_contract
+
 
 SYSTEM_TOOLS_CONFIG_PACKAGE = "iatoolkit.config"
 SYSTEM_TOOLS_CONFIG_FILENAME = "system_tools_pack.yaml"
@@ -59,6 +61,8 @@ def _validate_system_tool_entry(entry: dict, index: int) -> dict:
         "description": description,
         "parameters": copy.deepcopy(parameters),
     }
+    if entry.get("output_contract") is not None:
+        normalized["output_contract"] = clone_output_contract(normalize_output_contract(entry.get("output_contract")))
     if normalized_routing is not None:
         normalized["routing"] = normalized_routing
     if normalized_routing_profile is not None:

iatoolkit-2.20.1/src/iatoolkit/services/tool_output_contract.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from iatoolkit.common.exceptions import IAToolkitException
+
+
+ALLOWED_OUTPUT_KINDS = {"json", "html", "image", "file", "audio", "video"}
+ALLOWED_OUTPUT_TRANSPORTS = {"inline_base64", "signed_url", "attachment"}
+ALLOWED_OUTPUT_CONTRACT_KEYS = {
+    "kind",
+    "mime_type",
+    "transport",
+    "url_field",
+    "base64_field",
+    "filename_field",
+}
+
+
+def normalize_output_contract(output_contract: Any) -> dict | None:
+    if output_contract in (None, "", {}):
+        return None
+    if not isinstance(output_contract, dict):
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            "output_contract must be a JSON object",
+        )
+
+    unknown_keys = sorted(key for key in output_contract.keys() if key not in ALLOWED_OUTPUT_CONTRACT_KEYS)
+    if unknown_keys:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            f"output_contract has unsupported keys: {unknown_keys}",
+        )
+
+    kind = str(output_contract.get("kind") or "").strip().lower()
+    if kind not in ALLOWED_OUTPUT_KINDS:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            f"output_contract.kind must be one of {sorted(ALLOWED_OUTPUT_KINDS)}",
+        )
+
+    normalized = {"kind": kind}
+    mime_type = _normalize_optional_string(output_contract.get("mime_type"))
+    transport = _normalize_optional_string(output_contract.get("transport"))
+    url_field = _normalize_optional_string(output_contract.get("url_field"))
+    base64_field = _normalize_optional_string(output_contract.get("base64_field"))
+    filename_field = _normalize_optional_string(output_contract.get("filename_field"))
+
+    if mime_type:
+        normalized["mime_type"] = mime_type
+    if transport:
+        transport = transport.lower()
+        if transport not in ALLOWED_OUTPUT_TRANSPORTS:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                f"output_contract.transport must be one of {sorted(ALLOWED_OUTPUT_TRANSPORTS)}",
+            )
+        normalized["transport"] = transport
+    if url_field:
+        normalized["url_field"] = url_field
+    if base64_field:
+        normalized["base64_field"] = base64_field
+    if filename_field:
+        normalized["filename_field"] = filename_field
+
+    if kind in {"json", "html"}:
+        if transport or url_field or base64_field or filename_field:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                "output_contract transport fields are not allowed for json/html outputs",
+            )
+        return normalized
+
+    if not transport:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            f"output_contract.transport is required for output kind '{kind}'",
+        )
+    if transport == "signed_url" and not url_field:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            "output_contract.url_field is required when transport is 'signed_url'",
+        )
+    if transport == "inline_base64" and not base64_field:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            "output_contract.base64_field is required when transport is 'inline_base64'",
+        )
+    if transport == "attachment" and not filename_field:
+        raise IAToolkitException(
+            IAToolkitException.ErrorType.INVALID_PARAMETER,
+            "output_contract.filename_field is required when transport is 'attachment'",
+        )
+
+    return normalized
+
+
+def clone_output_contract(output_contract: Any) -> dict | None:
+    if isinstance(output_contract, dict):
+        return copy.deepcopy(output_contract)
+    return None
+
+
+def _normalize_optional_string(value: Any) -> str | None:
+    text = str(value or "").strip()
+    return text or None

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit/services/tool_service.py

@@ -26,6 +26,7 @@ from iatoolkit.services.system_tools import (
     get_system_tools_catalog_source,
     get_system_tool_force_include_capabilities,
 )
+from iatoolkit.services.tool_output_contract import clone_output_contract, normalize_output_contract
 from iatoolkit import current_iatoolkit
 
 
@@ -382,7 +383,8 @@ class ToolService:
             return text
         return f"[{text}]({url})"
 
-    def _validate_tool_contract(self, tool_type: str, execution_config):
+    def _validate_tool_contract(self, tool_type: str, execution_config, output_contract=None):
+        normalize_output_contract(output_contract)
         if tool_type != Tool.TYPE_HTTP:
             return
 
@@ -587,6 +589,7 @@ class ToolService:
             "description",
             "parameters",
             "execution_config",
+            "output_contract",
             "tool_type",
             "source",
             "is_active",
@@ -640,6 +643,7 @@ class ToolService:
                     name=function['function_name'],
                     description=function['description'],
                     parameters=function['parameters'],
+                    output_contract=clone_output_contract(function.get("output_contract")),
                     tool_type=Tool.TYPE_SYSTEM,
                     source=Tool.SOURCE_SYSTEM,
                     is_active=True,
@@ -680,6 +684,7 @@ class ToolService:
             and bool(tool.is_active)
             and tool.description == definition.get("description")
             and (tool.parameters or {}) == (definition.get("parameters") or {})
+            and (tool.output_contract or {}) == (definition.get("output_contract") or {})
         )
 
     def _system_tools_catalog_has_drift(
@@ -738,6 +743,7 @@ class ToolService:
                     name=function_name,
                     description=function.get("description"),
                     parameters=function.get("parameters") or {},
+                    output_contract=clone_output_contract(function.get("output_contract")),
                     tool_type=Tool.TYPE_SYSTEM,
                     source=Tool.SOURCE_SYSTEM,
                     is_active=True,
@@ -831,6 +837,7 @@ class ToolService:
                     name=name,
                     description=tool_data['description'],
                     parameters=tool_data['params'],
+                    output_contract=clone_output_contract(tool_data.get('output_contract')),
 
                     tool_type=Tool.TYPE_NATIVE,
                     source=Tool.SOURCE_YAML,
@@ -887,7 +894,8 @@ class ToolService:
 
         tool_type = tool_data.get('tool_type', Tool.TYPE_NATIVE)
         execution_config = tool_data.get('execution_config')
-        self._validate_tool_contract(tool_type, execution_config)
+        output_contract = normalize_output_contract(tool_data.get('output_contract'))
+        self._validate_tool_contract(tool_type, execution_config, output_contract)
 
         new_tool = Tool(
             company_id=company.id,
@@ -895,6 +903,7 @@ class ToolService:
             description=tool_data['description'],
             parameters=tool_data.get('parameters', {"type": "object", "properties": {}}),
             execution_config=execution_config,
+            output_contract=output_contract,
             tool_type=tool_type,
             source=Tool.SOURCE_USER,
             is_active=tool_data.get('is_active', True)
@@ -939,7 +948,9 @@ class ToolService:
 
         effective_tool_type = tool_data.get('tool_type', tool.tool_type)
         effective_execution_config = tool_data.get('execution_config', tool.execution_config)
-        self._validate_tool_contract(effective_tool_type, effective_execution_config)
+        existing_output_contract = clone_output_contract(tool.output_contract) if isinstance(tool.output_contract, dict) else None
+        effective_output_contract = normalize_output_contract(tool_data.get('output_contract', existing_output_contract))
+        self._validate_tool_contract(effective_tool_type, effective_execution_config, effective_output_contract)
 
         # Update fields
         if 'name' in tool_data:
@@ -950,6 +961,8 @@ class ToolService:
             tool.parameters = tool_data['parameters']
         if 'execution_config' in tool_data:
             tool.execution_config = tool_data['execution_config']
+        if 'output_contract' in tool_data:
+            tool.output_contract = effective_output_contract
         if 'tool_type' in tool_data:
             tool.tool_type = tool_data['tool_type']
         if 'is_active' in tool_data:

{iatoolkit-2.20.0 → iatoolkit-2.20.1/src/iatoolkit.egg-info}/PKG-INFO

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

{iatoolkit-2.20.0 → iatoolkit-2.20.1}/src/iatoolkit.egg-info/SOURCES.txt

@@ -147,6 +147,7 @@ src/iatoolkit/services/structured_output_service.py
 src/iatoolkit/services/system_prompt_catalog.py
 src/iatoolkit/services/system_tools.py
 src/iatoolkit/services/telemetry_service.py
+src/iatoolkit/services/tool_output_contract.py
 src/iatoolkit/services/tool_service.py
 src/iatoolkit/services/user_feedback_service.py
 src/iatoolkit/services/user_session_context_service.py