iatoolkit 2.22.0__tar.gz → 2.24.1__tar.gz

{iatoolkit-2.22.0/src/iatoolkit.egg-info → iatoolkit-2.24.1}/PKG-INFO

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

{iatoolkit-2.22.0 → iatoolkit-2.24.1}/src/iatoolkit/__init__.py

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

{iatoolkit-2.22.0 → iatoolkit-2.24.1}/src/iatoolkit/locales/en.yaml

@@ -1627,7 +1627,7 @@ ui:
     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."
     model_output_title: "Model Output"
-    model_output_hint: "Define the final JSON returned to the model after the HTTP response is received. Default mode is raw."
+    model_output_hint: "Define the final JSON returned to the model after the HTTP response is received. Default mode is raw. Use include/exclude and describe to keep responses compact and meaningful."
     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"
@@ -2613,9 +2613,16 @@ js_messages:
   tool_http_model_output_label: "model_output"
   tool_http_model_output_object: "model_output must be an object"
   tool_http_model_output_unknown_keys: "model_output has unsupported keys: {keys}"
+  tool_http_model_output_description_invalid: "model_output.description must be a string"
+  tool_http_model_output_list_invalid: "model_output.{field} must be a list"
+  tool_http_model_output_list_item_invalid: "model_output.{field}[{index}] must be a non-empty string"
+  tool_http_model_output_describe_object: "model_output.describe must be an object"
+  tool_http_model_output_describe_field_name_invalid: "model_output.describe must use non-empty field names"
+  tool_http_model_output_describe_field_invalid: "model_output.describe.{field} must be a string"
   tool_http_model_output_mode_invalid: "model_output.mode must be one of raw, extract, map"
   tool_http_model_output_path_required: "model_output.path is required when mode=extract"
   tool_http_model_output_root_invalid: "model_output.root must be a non-empty string"
+  tool_http_model_output_fields_object: "model_output.fields must be an object"
   tool_http_model_output_fields_required: "model_output.fields must be a non-empty object when mode=map"
   tool_http_model_output_field_name_invalid: "model_output.fields must use non-empty field names"
   tool_http_model_output_field_path_required: "model_output.fields.{field} must define a path"

{iatoolkit-2.22.0 → iatoolkit-2.24.1}/src/iatoolkit/locales/es.yaml

@@ -1631,7 +1631,7 @@ ui:
     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."
     model_output_title: "Model Output"
-    model_output_hint: "Define el JSON final que recibe el modelo después de ejecutar la tool HTTP. El modo por defecto es raw."
+    model_output_hint: "Define el JSON final que recibe el modelo después de ejecutar la tool HTTP. El modo por defecto es raw. Usa include/exclude y describe para mantener respuestas compactas y significativas."
     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"
@@ -2616,9 +2616,16 @@ js_messages:
   tool_http_model_output_label: "model_output"
   tool_http_model_output_object: "model_output debe ser un objeto"
   tool_http_model_output_unknown_keys: "model_output tiene claves no soportadas: {keys}"
+  tool_http_model_output_description_invalid: "model_output.description debe ser un string"
+  tool_http_model_output_list_invalid: "model_output.{field} debe ser una lista"
+  tool_http_model_output_list_item_invalid: "model_output.{field}[{index}] debe ser un string no vacío"
+  tool_http_model_output_describe_object: "model_output.describe debe ser un objeto"
+  tool_http_model_output_describe_field_name_invalid: "model_output.describe debe usar nombres de campo no vacíos"
+  tool_http_model_output_describe_field_invalid: "model_output.describe.{field} debe ser un string"
   tool_http_model_output_mode_invalid: "model_output.mode debe ser uno de raw, extract, map"
   tool_http_model_output_path_required: "model_output.path es obligatorio cuando mode=extract"
   tool_http_model_output_root_invalid: "model_output.root debe ser un string no vacío"
+  tool_http_model_output_fields_object: "model_output.fields debe ser un objeto"
   tool_http_model_output_fields_required: "model_output.fields debe ser un objeto no vacío cuando mode=map"
   tool_http_model_output_field_name_invalid: "model_output.fields debe usar nombres de campo no vacíos"
   tool_http_model_output_field_path_required: "model_output.fields.{field} debe definir un path"

{iatoolkit-2.22.0 → iatoolkit-2.24.1}/src/iatoolkit/services/http_tool_service.py

@@ -588,13 +588,15 @@ class HttpToolService:
         root_path = str(model_output.get("root") or "").strip()
         source = self._extract_path(value, root_path) if root_path else value
         fields = model_output.get("fields") or {}
-        if not isinstance(fields, dict) or not fields:
+        if not isinstance(fields, dict):
             raise IAToolkitException(
                 IAToolkitException.ErrorType.INVALID_PARAMETER,
-                "execution_config.response.model_output.fields must be a non-empty object when mode is 'map'"
+                "execution_config.response.model_output.fields must be an object"
             )
 
         exclude_nulls = model_output.get("exclude_nulls") is True
+        include_fields = self._normalize_model_output_field_names(model_output.get("include"))
+        exclude_fields = set(self._normalize_model_output_field_names(model_output.get("exclude")))
         max_items = model_output.get("max_items")
 
         if isinstance(source, list):
@@ -604,27 +606,81 @@ class HttpToolService:
                 else source
             )
             return [
-                self._map_model_output_item(item, fields, exclude_nulls)
+                self._map_model_output_item(
+                    item,
+                    fields=fields,
+                    include_fields=include_fields,
+                    exclude_fields=exclude_fields,
+                    exclude_nulls=exclude_nulls,
+                )
                 for item in items
             ]
         if isinstance(source, dict):
-            return self._map_model_output_item(source, fields, exclude_nulls)
+            return self._map_model_output_item(
+                source,
+                fields=fields,
+                include_fields=include_fields,
+                exclude_fields=exclude_fields,
+                exclude_nulls=exclude_nulls,
+            )
 
         raise IAToolkitException(
             IAToolkitException.ErrorType.INVALID_PARAMETER,
             f"Cannot map model_output over type '{type(source).__name__}'"
         )
 
-    def _map_model_output_item(self, source: dict, fields: dict, exclude_nulls: bool) -> dict:
-        mapped = {}
+    def _map_model_output_item(
+        self,
+        source,
+        *,
+        fields: dict,
+        include_fields: list[str],
+        exclude_fields: set[str],
+        exclude_nulls: bool,
+    ) -> dict:
+        if not isinstance(source, dict):
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                f"Cannot map model_output item over type '{type(source).__name__}'"
+            )
+
+        if include_fields:
+            mapped = {}
+            for field_name in include_fields:
+                field_value = source.get(field_name)
+                if field_value is None and exclude_nulls:
+                    continue
+                mapped[field_name] = field_value
+        else:
+            mapped = {
+                field_name: field_value
+                for field_name, field_value in source.items()
+                if not (field_value is None and exclude_nulls)
+            }
+
         for output_name, field_config in fields.items():
             path = self._resolve_model_output_field_path(output_name, field_config)
             found, field_value = self._try_extract_path(source, path)
             if (not found or field_value is None) and exclude_nulls:
                 continue
             mapped[output_name] = field_value if found else None
+
+        for field_name in exclude_fields:
+            mapped.pop(field_name, None)
+
         return mapped
 
+    @staticmethod
+    def _normalize_model_output_field_names(value) -> list[str]:
+        if not isinstance(value, list):
+            return []
+        names = []
+        for item in value:
+            text = str(item or "").strip()
+            if text:
+                names.append(text)
+        return names
+
     @staticmethod
     def _resolve_model_output_field_path(output_name: str, field_config) -> str:
         if isinstance(field_config, str):

{iatoolkit-2.22.0 → iatoolkit-2.24.1}/src/iatoolkit/services/tool_service.py

@@ -596,7 +596,18 @@ class ToolService:
                 "execution_config.response.model_output must be a JSON object"
             )
 
-        allowed_keys = {"mode", "path", "root", "fields", "exclude_nulls", "max_items"}
+        allowed_keys = {
+            "mode",
+            "path",
+            "root",
+            "fields",
+            "include",
+            "exclude",
+            "description",
+            "describe",
+            "exclude_nulls",
+            "max_items",
+        }
         unknown_keys = sorted(key for key in model_output.keys() if key not in allowed_keys)
         if unknown_keys:
             raise IAToolkitException(
@@ -604,6 +615,17 @@ class ToolService:
                 f"execution_config.response.model_output has unsupported keys: {unknown_keys}"
             )
 
+        description = model_output.get("description")
+        if description is not None and not isinstance(description, str):
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                "execution_config.response.model_output.description must be a string"
+            )
+
+        self._validate_http_model_output_string_list(model_output.get("include"), "include")
+        self._validate_http_model_output_string_list(model_output.get("exclude"), "exclude")
+        self._validate_http_model_output_descriptions(model_output.get("describe"))
+
         mode = str(model_output.get("mode", "raw")).strip().lower()
         if mode not in self.HTTP_ALLOWED_MODEL_OUTPUT_MODES:
             raise IAToolkitException(
@@ -628,42 +650,43 @@ class ToolService:
                 )
 
             fields = model_output.get("fields")
-            if not isinstance(fields, dict) or not fields:
-                raise IAToolkitException(
-                    IAToolkitException.ErrorType.INVALID_PARAMETER,
-                    "execution_config.response.model_output.fields must be a non-empty object when mode is 'map'"
-                )
-            for field_name, field_config in fields.items():
-                if not isinstance(field_name, str) or not field_name.strip():
+            if fields is not None:
+                if not isinstance(fields, dict):
                     raise IAToolkitException(
                         IAToolkitException.ErrorType.INVALID_PARAMETER,
-                        "execution_config.response.model_output.fields must use non-empty string field names"
+                        "execution_config.response.model_output.fields must be an object"
                     )
-                if isinstance(field_config, str):
-                    if not field_config.strip():
+                for field_name, field_config in fields.items():
+                    if not isinstance(field_name, str) or not field_name.strip():
                         raise IAToolkitException(
                             IAToolkitException.ErrorType.INVALID_PARAMETER,
-                            f"execution_config.response.model_output.fields.{field_name} must be a non-empty path"
+                            "execution_config.response.model_output.fields must use non-empty string field names"
                         )
-                    continue
-                if isinstance(field_config, dict):
-                    path = field_config.get("path")
-                    if not isinstance(path, str) or not path.strip():
-                        raise IAToolkitException(
-                            IAToolkitException.ErrorType.INVALID_PARAMETER,
-                            f"execution_config.response.model_output.fields.{field_name}.path must be a non-empty string"
-                        )
-                    description = field_config.get("description")
-                    if description is not None and not isinstance(description, str):
-                        raise IAToolkitException(
-                            IAToolkitException.ErrorType.INVALID_PARAMETER,
-                            f"execution_config.response.model_output.fields.{field_name}.description must be a string"
-                        )
-                    continue
-                raise IAToolkitException(
-                    IAToolkitException.ErrorType.INVALID_PARAMETER,
-                    f"execution_config.response.model_output.fields.{field_name} must be a path string or object"
-                )
+                    if isinstance(field_config, str):
+                        if not field_config.strip():
+                            raise IAToolkitException(
+                                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                                f"execution_config.response.model_output.fields.{field_name} must be a non-empty path"
+                            )
+                        continue
+                    if isinstance(field_config, dict):
+                        path = field_config.get("path")
+                        if not isinstance(path, str) or not path.strip():
+                            raise IAToolkitException(
+                                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                                f"execution_config.response.model_output.fields.{field_name}.path must be a non-empty string"
+                            )
+                        description = field_config.get("description")
+                        if description is not None and not isinstance(description, str):
+                            raise IAToolkitException(
+                                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                                f"execution_config.response.model_output.fields.{field_name}.description must be a string"
+                            )
+                        continue
+                    raise IAToolkitException(
+                        IAToolkitException.ErrorType.INVALID_PARAMETER,
+                        f"execution_config.response.model_output.fields.{field_name} must be a path string or object"
+                    )
 
             exclude_nulls = model_output.get("exclude_nulls")
             if exclude_nulls is not None and not isinstance(exclude_nulls, bool):
@@ -682,6 +705,43 @@ class ToolService:
                     "execution_config.response.model_output.max_items must be a positive integer"
                 )
 
+    @staticmethod
+    def _validate_http_model_output_string_list(value, field_name: str) -> None:
+        if value is None:
+            return
+        if not isinstance(value, list):
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                f"execution_config.response.model_output.{field_name} must be a list"
+            )
+        for index, item in enumerate(value):
+            if not isinstance(item, str) or not item.strip():
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.INVALID_PARAMETER,
+                    f"execution_config.response.model_output.{field_name}[{index}] must be a non-empty string"
+                )
+
+    @staticmethod
+    def _validate_http_model_output_descriptions(value) -> None:
+        if value is None:
+            return
+        if not isinstance(value, dict):
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                "execution_config.response.model_output.describe must be an object"
+            )
+        for field_name, description in value.items():
+            if not isinstance(field_name, str) or not field_name.strip():
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.INVALID_PARAMETER,
+                    "execution_config.response.model_output.describe must use non-empty string field names"
+                )
+            if not isinstance(description, str):
+                raise IAToolkitException(
+                    IAToolkitException.ErrorType.INVALID_PARAMETER,
+                    f"execution_config.response.model_output.describe.{field_name} must be a string"
+                )
+
     @staticmethod
     def _build_tool_snapshot(tool_obj) -> dict:
         if tool_obj is None:

{iatoolkit-2.22.0 → iatoolkit-2.24.1/src/iatoolkit.egg-info}/PKG-INFO

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