ibm-watsonx-orchestrate 1.11.1__py3-none-any.whl → 1.12.0__py3-none-any.whl

ibm_watsonx_orchestrate/__init__.py

@@ -6,7 +6,7 @@
 pkg_name = "ibm-watsonx-orchestrate"
 
 
-__version__ = "1.11.1"
+__version__ = "1.12.0"
 
 
 from ibm_watsonx_orchestrate.utils.logging.logger import setup_logging

ibm_watsonx_orchestrate/agent_builder/agents/types.py

@@ -1,5 +1,6 @@
 import json
 import yaml
+import logging
 from enum import Enum
 from typing import List, Optional, Dict
 from pydantic import BaseModel, model_validator, ConfigDict
@@ -9,6 +10,7 @@ from ibm_watsonx_orchestrate.agent_builder.knowledge_bases.knowledge_base import
 from ibm_watsonx_orchestrate.agent_builder.agents.webchat_customizations import StarterPrompts, WelcomeContent
 from pydantic import Field, AliasChoices
 from typing import Annotated
+from ibm_watsonx_orchestrate.cli.commands.partners.offering.types import CATALOG_ONLY_FIELDS
 from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 from ibm_watsonx_orchestrate.agent_builder.tools.types import JsonSchemaObject
@@ -16,6 +18,8 @@ from ibm_watsonx_orchestrate.agent_builder.tools.types import JsonSchemaObject
 # TO-DO: this is just a placeholder. Will update this later to align with backend
 DEFAULT_LLM = "watsonx/meta-llama/llama-3-2-90b-vision-instruct"
 
+logger = logging.getLogger(__name__)
+
 # Handles yaml formatting for multiline strings to improve readability
 def str_presenter(dumper, data):
     if len(data.splitlines()) > 1:  # check for multiline string
@@ -84,7 +88,7 @@ class BaseAgentSpec(BaseModel):
         dumped = self.model_dump(mode='json', exclude_unset=True, exclude_none=True)
         with open(file, 'w') as f:
             if file.endswith('.yaml') or file.endswith('.yml'):
-                yaml.dump(dumped, f, sort_keys=False)
+                yaml.dump(dumped, f, sort_keys=False, allow_unicode=True)
             elif file.endswith('.json'):
                 json.dump(dumped, f, indent=2)
             else:
@@ -93,6 +97,19 @@ class BaseAgentSpec(BaseModel):
     def dumps_spec(self) -> str:
         dumped = self.model_dump(mode='json', exclude_none=True)
         return json.dumps(dumped, indent=2)
+    
+    @model_validator(mode="before")
+    def validate_agent_fields(cls,values):
+        return drop_catalog_fields(values)
+
+
+def drop_catalog_fields(values: dict):
+    for field in CATALOG_ONLY_FIELDS:
+        if values.get(field):
+            logger.warning(f"Field '{field}' is only used when publishing to the catalog, dropping this field for import")
+            del values[field]
+    return values
+
 
 # ===============================
 #      NATIVE AGENT TYPES
@@ -202,8 +219,8 @@ def validate_agent_fields(values: dict) -> dict:
 # ===============================
 
 class ExternalAgentConfig(BaseModel):
-    hidden: bool = False
-    enable_cot: bool = False
+    hidden: Optional[bool] = False
+    enable_cot: Optional[bool] = False
 
 class ExternalAgentSpec(BaseAgentSpec):
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -226,8 +243,8 @@ class ExternalAgentSpec(BaseAgentSpec):
         # The get api responds with a flat object with no config
         if values.get("config") is None:
             values["config"] = {}
-            values["config"]["enable_cot"] = values.get("enable_cot", None)
-            values["config"]["hidden"] = values.get("hidden", None)
+            values["config"]["enable_cot"] = values.get("enable_cot", False)
+            values["config"]["hidden"] = values.get("hidden", False)
         return validate_external_agent_fields(values)
 
     @model_validator(mode="after")

ibm_watsonx_orchestrate/agent_builder/connections/connections.py

@@ -14,7 +14,7 @@ from ibm_watsonx_orchestrate.agent_builder.connections.types import (
     CONNECTION_TYPE_CREDENTIAL_MAPPING
 )
 
-from ibm_watsonx_orchestrate.utils.utils import sanatize_app_id
+from ibm_watsonx_orchestrate.utils.utils import sanitize_app_id
 from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 logger = logging.getLogger(__name__)
@@ -111,7 +111,7 @@ def _get_credentials_model(connection_type: ConnectionSecurityScheme, app_id: st
     return _build_credentials_model(credentials_type=credentials_type, vars=variables, base_prefix=base_prefix)
 
 def get_connection_type(app_id: str) -> ConnectionSecurityScheme:
-    sanitized_app_id = sanatize_app_id(app_id=app_id)
+    sanitized_app_id = sanitize_app_id(app_id=app_id)
     expected_schema_key = f"WXO_SECURITY_SCHEMA_{sanitized_app_id}"
     expected_schema = os.environ.get(expected_schema_key)
 
@@ -129,7 +129,7 @@ def get_connection_type(app_id: str) -> ConnectionSecurityScheme:
     return expected_schema
 
 def get_application_connection_credentials(type: ConnectionType, app_id: str) -> CREDENTIALS:
-    sanitized_app_id = sanatize_app_id(app_id=app_id)
+    sanitized_app_id = sanitize_app_id(app_id=app_id)
     expected_schema = get_connection_type(app_id=app_id)
     requested_schema = connection_type_security_schema_map.get(type)
 

ibm_watsonx_orchestrate/agent_builder/connections/types.py

@@ -1,7 +1,11 @@
+import logging
 from pydantic import BaseModel, Field, AliasChoices, model_validator
 from typing import Optional, Union, TypeVar, List
 from enum import Enum
 
+
+logger = logging.getLogger(__name__)
+
 class ConnectionKind(str, Enum):
     basic = 'basic'
     bearer = 'bearer'
@@ -145,6 +149,16 @@ class ConnectionConfiguration(BaseModel):
         
         super().__init__(*args, **kwargs)
 
+    @model_validator(mode="before")
+    def validate_auth_scheme(self):
+        if self.get('auth_type'):
+            try:
+                self['auth_type'] = ConnectionAuthType(self.get('auth_type'))
+            except:
+                logger.warning(f"Unsupported auth type '{self.get('auth_type')}', this will be removed from the configuration data")
+                self['auth_type'] = None
+        return self
+
     @model_validator(mode="after")
     def validate_config(self):
         conn_type = None

ibm_watsonx_orchestrate/agent_builder/models/types.py

@@ -23,6 +23,7 @@ class  ModelProvider(str, Enum):
     STABILITY_AI = 'stability-ai'
     TOGETHER_AI = 'together-ai'
     WATSONX = 'watsonx'
+    X_AI='x-ai'
 
     def __str__(self):
         return self.value

ibm_watsonx_orchestrate/agent_builder/toolkits/base_toolkit.py

@@ -18,7 +18,7 @@ class BaseToolkit:
         dumped = self.__toolkit_spec__.model_dump(mode='json', exclude_unset=True, exclude_none=True, by_alias=True)
         with open(file, 'w') as f:
             if file.endswith('.yaml') or file.endswith('.yml'):
-                yaml.dump(dumped, f)
+                yaml.dump(dumped, f, allow_unicode=True)
             elif file.endswith('.json'):
                 json.dump(dumped, f, indent=2)
             else:

ibm_watsonx_orchestrate/agent_builder/tools/__init__.py

@@ -1,4 +1,5 @@
 from .base_tool import BaseTool
 from .python_tool import tool, PythonTool, get_all_python_tools
 from .openapi_tool import create_openapi_json_tool, create_openapi_json_tool_from_uri, create_openapi_json_tools_from_uri, OpenAPITool, HTTPException
+from .langflow_tool import LangflowTool
 from .types import ToolPermission, JsonSchemaObject, ToolRequestBody, ToolResponseBody, OpenApiSecurityScheme, OpenApiToolBinding, PythonToolBinding, WxFlowsToolBinding, SkillToolBinding, ClientSideToolBinding, ToolBinding, ToolSpec

ibm_watsonx_orchestrate/agent_builder/tools/base_tool.py

@@ -19,7 +19,7 @@ class BaseTool:
         dumped = self.__tool_spec__.model_dump(mode='json', exclude_unset=True, exclude_none=True, by_alias=True)
         with open(file, 'w') as f:
             if file.endswith('.yaml') or file.endswith('.yml'):
-                yaml.dump(dumped, f)
+                yaml.dump(dumped, f, allow_unicode=True)
             elif file.endswith('.json'):
                 json.dump(dumped, f, indent=2)
             else:

ibm_watsonx_orchestrate/agent_builder/tools/langflow_tool.py

@@ -0,0 +1,184 @@
+import json
+import re
+
+from pydantic import BaseModel
+import rich
+
+from ibm_watsonx_orchestrate.agent_builder.connections.types import ConnectionSecurityScheme
+from ibm_watsonx_orchestrate.langflow.langflow_utils import parse_langflow_model
+from .base_tool import BaseTool
+from .types import LangflowToolBinding, ToolBinding, ToolPermission, ToolRequestBody, ToolResponseBody, ToolSpec
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
+
+MIN_LANGFLOW_VERSION = [1,5,0]
+LANGFLOW_CHAT_INPUT_LABEL = "ChatInput"
+LANGFLOW_CHAT_OUTPUT_LABEL = "ChatOutput"
+VALID_NAME_PATTERN = re.compile("^[a-zA-Z](\\w|_)+$")
+
+class LangflowTool(BaseTool):
+  # additional python module requirements for langflow based tools
+  requirements: list[str] = []
+
+  def __init__(self,spec: ToolSpec):
+    BaseTool.__init__(self,spec=spec)
+
+    if self.__tool_spec__.binding.langflow is None:
+      raise BadRequest('Missing langflow binding')
+    
+  
+  def __repr__(self):
+    return f"LangflowTool(name='{self.__tool_spec__.name}', description='{self.__tool_spec__.description}')"
+
+  
+  def __str__(self):
+    return self.__repr__()
+  
+def validate_langflow_version(version_string: str) -> bool:
+  version_nums = map(int, re.findall(r"\d+",version_string))
+  for i,n in enumerate(version_nums):
+    if i >= len(MIN_LANGFLOW_VERSION) or MIN_LANGFLOW_VERSION[i] < n:
+      break
+    if MIN_LANGFLOW_VERSION[i] > n:
+      return False
+  return True
+
+
+def extract_langflow_nodes(tool_definition: dict, node_type: str) -> dict:
+  return [n for n in tool_definition.get('data',{}).get('nodes',{}) if n.get('data',{}).get('type') == node_type]
+
+def langflow_input_schema(tool_definition: dict = None) -> ToolRequestBody:
+  
+  chat_input_nodes = extract_langflow_nodes(tool_definition=tool_definition,node_type=LANGFLOW_CHAT_INPUT_LABEL)
+
+  if len(chat_input_nodes) < 1:
+    raise ValueError(f"No '{LANGFLOW_CHAT_INPUT_LABEL}' node found in langflow tool")
+  if len(chat_input_nodes) > 1:
+    raise ValueError(f"Too many '{LANGFLOW_CHAT_INPUT_LABEL}' nodes found in langlow tool")
+
+  input_description = chat_input_nodes[0].get("data",{}).get("node",{}).get("description","")
+
+  return ToolRequestBody(
+    type= "object",
+    properties= {
+      "input": {
+        "description": input_description,
+        "type": "string"
+      }
+    },
+    required= ["input"]
+  )
+
+def langflow_output_schema(tool_definition: dict = None):
+
+  chat_output_nodes = extract_langflow_nodes(tool_definition=tool_definition,node_type=LANGFLOW_CHAT_OUTPUT_LABEL)
+
+  if len(chat_output_nodes) < 1:
+    raise ValueError(f"No '{LANGFLOW_CHAT_OUTPUT_LABEL}' node found in langflow tool")
+  if len(chat_output_nodes) > 1:
+    output_description = ""
+  else:
+    output_description = chat_output_nodes[0].get("data",{}).get("node",{}).get("description","")
+
+  return ToolResponseBody(
+    description=output_description,
+    type= "string"
+  )
+  
+def create_langflow_tool(
+    tool_definition: dict,
+    connections: dict = None,
+    ) -> LangflowTool:
+
+  name = tool_definition.get('name')
+  if not name:
+    raise ValueError('Provided tool definition does not have a name')
+  
+  if VALID_NAME_PATTERN.match(name) is None:
+    raise ValueError(f"Langflow tool name contains unsupported characters. Only alphanumeric characters and underscores are allowed, and must not start with a number or underscore.")
+  
+  description = tool_definition.get('description')
+  if not description:
+    raise ValueError('Provided tool definition does not have a description')
+  
+  langflow_id = tool_definition.get('id')
+
+  langflow_version = tool_definition.get('last_tested_version')
+  if not langflow_version:
+    raise ValueError('No langflow version detected in tool definition')
+  if not validate_langflow_version(langflow_version):
+    raise ValueError(f"Langflow version is below minimum requirements, found '{langflow_version}', miniumum required version '{'.'.join(map(str,MIN_LANGFLOW_VERSION))}'")
+  
+  # find all the component in Langflow and display its credential
+  langflow_spec = parse_langflow_model(tool_definition)
+  if langflow_spec:
+    rich.print(f"[bold white]Langflow version used: {langflow_version}[/bold white]")
+    rich.print("Please ensure this flow is compatible with the Langflow version bundled in ADK.")
+    rich.print("\nLangflow components:")
+
+    table = rich.table.Table(show_header=True, header_style="bold white", show_lines=True)
+    column_args = {
+      "ID": {},
+      "Name": {},
+      "Credentials": {},
+      "Requirements": {}
+    }
+    for column in column_args:
+        table.add_column(column,**column_args[column])
+
+    requirements = set()
+    api_key_not_set = False
+    for component in langflow_spec.components:
+      if component.credentials and len(component.credentials) > 0:
+        # create a command separated list with newline
+        component_creds = None
+        for k, v in component.credentials.items():
+          if v is None or v == "":
+            v = 'NOT SET'
+            api_key_not_set = True
+          if component_creds is None:
+            component_creds = f"{k} {v}"
+          else:
+            component_creds += "\n" + f"{k} {v}"
+      else:
+        component_creds = "N/A"
+
+      if component.requirements and len(component.requirements) > 0:
+        # create a command separated list with newline
+        component_req = "\n".join([f"{k}" for k in component.requirements])
+        for r in component.requirements:
+          requirements.add(r)
+      else:
+        component_req = "N/A"
+      table.add_row(component.id,component.name,component_creds,component_req)
+    rich.print(table)
+
+    rich.print("[bold yellow]Tip:[/bold yellow] Langflow tool might require additional python modules.  Identified requirements will be added.")
+    rich.print("[bold yellow]Tip:[/bold yellow] Avoid hardcoding sensitive values. Use Orchestrate connections to manage secrets securely.")
+    if api_key_not_set:
+      rich.print("[bold yellow]Warning:[/bold yellow] Some required api key(s) were not set in the flow. Please adjust the flow to include them.")
+    rich.print("Ensure each credential follows the <app-id>_<variable> naming convention within the Langflow model.")
+
+    for connection in connections:
+        rich.print(f"* Connection: {connection} → Suggested naming: {connection}_<variable>")
+
+  spec = ToolSpec(
+    name=name,
+    description=description,
+    permission=ToolPermission('read_only')
+  )
+
+  spec.input_schema = langflow_input_schema(tool_definition=tool_definition)
+
+  spec.output_schema = langflow_output_schema(tool_definition=tool_definition)
+
+  spec.binding = ToolBinding(
+    langflow=LangflowToolBinding(
+      langflow_id=langflow_id,
+      langflow_version=langflow_version,
+      connections=connections
+    )
+  )
+
+  tool = LangflowTool(spec=spec)
+  tool.requirements = requirements
+  return tool

ibm_watsonx_orchestrate/agent_builder/tools/openapi_tool.py

@@ -56,9 +56,9 @@ class OpenAPITool(BaseTool):
                 spec = ToolSpec.model_validate(json.load(f))
             else:
                 raise BadRequest('file must end in .json, .yaml, or .yml')
-
-        if spec.binding.openapi is None or spec.binding.openapi is None:
-            raise BadRequest('failed to load python tool as the tool had no openapi binding')
+            
+        if spec is None or spec.binding is None or spec.binding.openapi is None:
+            raise BadRequest('failed to load openapi tool as the tool had no openapi binding')
 
         return OpenAPITool(spec=spec)
 
@@ -80,6 +80,7 @@ def create_openapi_json_tool(
         http_success_response_code: int = 200,
         http_response_content_type='application/json',
         name: str = None,
+        display_name: str = None,
         description: str = None,
         permission: ToolPermission = None,
         input_schema: ToolRequestBody = None,
@@ -130,8 +131,10 @@ def create_openapi_json_tool(
         raise BadRequest(
             f"No description provided for tool. {http_method}: {http_path} did not specify a description field, and no description was provided")
 
+    spec_display_name = display_name if display_name else route_spec.get('summary')
     spec = ToolSpec(
         name=spec_name,
+        display_name=spec_display_name,
         description=spec_description,
         permission=spec_permission
     )
@@ -348,6 +351,7 @@ async def create_openapi_json_tool_from_uri(
         http_response_content_type='application/json',
         permission: ToolPermission = ToolPermission.READ_ONLY,
         name: str = None,
+        display_name: str = None,
         description: str = None,
         input_schema: ToolRequestBody = None,
         output_schema: ToolResponseBody = None,
@@ -362,6 +366,7 @@ async def create_openapi_json_tool_from_uri(
     :param http_success_response_code: Which http status code should be considered a successful call (defaults to 200)
     :param http_response_content_type: Which http response type should be considered successful (default to application/json)
     :param name: The name of the resulting tool (used to invoke the tool by the agent)
+    :param display_name: The name of the resulting tool to be displayed
     :param description: The description of the resulting tool (used as the semantic layer to help the agent with tool selection)
     :param permission: Which orchestrate permission level does a user need to have to invoke this tool
     :param input_schema: The JSONSchema of the inputs to the http request
@@ -379,6 +384,7 @@ async def create_openapi_json_tool_from_uri(
         http_response_content_type=http_response_content_type,
         permission=permission,
         name=name,
+        display_name=display_name,
         description=description,
         input_schema=input_schema,
         output_schema=output_schema,

ibm_watsonx_orchestrate/agent_builder/tools/types.py

@@ -1,8 +1,9 @@
 from enum import Enum
 from typing import List, Any, Dict, Literal, Optional, Union
 
-from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices
+from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices, ValidationError
 from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
+from ibm_watsonx_orchestrate.agent_builder.connections import KeyValueConnectionCredentials
 
 
 class ToolPermission(str, Enum):
@@ -159,6 +160,21 @@ class FlowToolBinding(BaseModel):
     flow_id: str
     model: Optional[dict] = None
 
+class LangflowToolBinding(BaseModel):
+    langflow_id: Optional[str] = None
+    project_id: Optional[str] = None
+    langflow_version: str
+    connections: Optional[dict] = None
+
+    @model_validator(mode='after')
+    def validate_connection_type(self) -> 'LangflowToolBinding':
+        if self.connections:
+            for k,v in self.connections.items():
+                if not v:
+                    raise ValidationError(f"No connection provided for '{k}'")
+        return self
+
+
 class ToolBinding(BaseModel):
     openapi: OpenApiToolBinding = None
     python: PythonToolBinding = None
@@ -167,6 +183,7 @@ class ToolBinding(BaseModel):
     client_side: ClientSideToolBinding = None
     mcp: McpToolBinding = None
     flow: FlowToolBinding = None
+    langflow: LangflowToolBinding = None
 
     @model_validator(mode='after')
     def validate_binding_type(self) -> 'ToolBinding':
@@ -177,7 +194,8 @@ class ToolBinding(BaseModel):
             self.skill is not None,
             self.client_side is not None,
             self.mcp is not None,
-            self.flow is not None
+            self.flow is not None,
+            self.langflow is not None
         ]
         if sum(bindings) == 0:
             raise BadRequest("One binding must be set")

ibm_watsonx_orchestrate/cli/commands/agents/agents_controller.py

@@ -1309,7 +1309,7 @@ class AgentsController:
             return AssistantAgent.model_validate(assistant_result)
         
 
-    def export_agent(self, name: str, kind: AgentKind, output_path: str, agent_only_flag: bool=False, zip_file_out: zipfile.ZipFile | None = None) -> None:
+    def export_agent(self, name: str, kind: AgentKind, output_path: str, agent_only_flag: bool=False, zip_file_out: zipfile.ZipFile | None = None, with_tool_spec_file: bool = False) -> None:
         output_file = Path(output_path)
         output_file_extension = output_file.suffix
         output_file_name = output_file.stem
@@ -1330,7 +1330,7 @@ class AgentsController:
         if agent_only_flag:
             logger.info(f"Exported agent definition for '{name}' to '{output_path}'")
             with open(output_path, 'w') as outfile:
-                yaml.dump(agent_spec_file_content, outfile, sort_keys=False, default_flow_style=False)
+                yaml.dump(agent_spec_file_content, outfile, sort_keys=False, default_flow_style=False, allow_unicode=True)
             return
         
         close_file_flag = False
@@ -1340,7 +1340,7 @@ class AgentsController:
 
         logger.info(f"Exporting agent definition for '{name}'")
         
-        agent_spec_yaml = yaml.dump(agent_spec_file_content, sort_keys=False, default_flow_style=False)
+        agent_spec_yaml = yaml.dump(agent_spec_file_content, sort_keys=False, default_flow_style=False, allow_unicode=True)
         agent_spec_yaml_bytes = agent_spec_yaml.encode("utf-8")
         agent_spec_yaml_file = io.BytesIO(agent_spec_yaml_bytes)
 
@@ -1357,15 +1357,22 @@ class AgentsController:
             agent_spec_yaml_file.getvalue()
         )
 
-        tools_contoller = ToolsController()
-        for tool_name in agent_spec_file_content.get("tools", []):
+        agent_tools = agent_spec_file_content.get("tools", [])
+
+        tools_controller = ToolsController()
+        tools_client = tools_controller.get_client() 
+        tool_specs = None
+        if with_tool_spec_file:
+            tool_specs = {t.get('name'):t for t in tools_client.get_drafts_by_names(agent_tools) if t.get('name')}
+
+        for tool_name in agent_tools:
 
             base_tool_file_path = f"{output_file_name}/tools/{tool_name}/"
             if check_file_in_zip(file_path=base_tool_file_path, zip_file=zip_file_out):
                 continue
             
             logger.info(f"Exporting tool '{tool_name}'")
-            tool_artifact_bytes = tools_contoller.download_tool(tool_name)
+            tool_artifact_bytes = tools_controller.download_tool(tool_name)
             if not tool_artifact_bytes:
                 continue
             
@@ -1377,6 +1384,12 @@ class AgentsController:
                             f"{base_tool_file_path}{item.filename}",
                             buffer
                         )
+                if with_tool_spec_file and tool_specs:
+                    current_spec = tool_specs[tool_name]
+                    zip_file_out.writestr(
+                        f"{base_tool_file_path}config.json",
+                        ToolSpec.model_validate(current_spec).model_dump_json(exclude_unset=True,indent=2)
+                    )
         
         for kb_name in agent_spec_file_content.get("knowledge_base", []):
             logger.warning(f"Skipping {kb_name}, knowledge_bases are currently unsupported by export")

ibm_watsonx_orchestrate/cli/commands/connections/connections_command.py

@@ -6,6 +6,7 @@ from ibm_watsonx_orchestrate.cli.commands.connections.connections_controller imp
     remove_connection,
     list_connections,
     import_connection,
+    export_connection,
     configure_connection,
     set_credentials_connection,
     set_identity_provider_connection,
@@ -65,6 +66,23 @@ def import_connection_command(
 ):
     import_connection(file=file)
 
+@connections_app.command(name="export")
+def export_connection_command(
+    app_id: Annotated[
+        str, typer.Option(
+            '--app-id', '-a',
+            help='The app id of the connection you wish to export.'
+        )
+    ],
+    output_file: Annotated[
+        str, typer.Option(
+            '--output', '-o',
+            help='Path to where the exported connection should be saved.'
+        )
+    ] = None
+):
+    export_connection(app_id=app_id,output_file=output_file)
+
 @connections_app.command(name="configure")
 def configure_connection_command(
     app_id: Annotated[