ibm-watsonx-orchestrate 1.12.2__tar.gz → 1.13.0b1__tar.gz

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ibm-watsonx-orchestrate
-Version: 1.12.2
+Version: 1.13.0b1
 Summary: IBM watsonx.orchestrate SDK
 Author-email: IBM <support@ibm.com>
 License: MIT License
@@ -11,7 +11,7 @@ Requires-Dist: click<8.2.0,>=8.0.0
 Requires-Dist: docstring-parser<1.0,>=0.16
 Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: ibm-cloud-sdk-core>=3.24.2
-Requires-Dist: ibm-watsonx-orchestrate-evaluation-framework==1.1.3
+Requires-Dist: ibm-watsonx-orchestrate-evaluation-framework==1.1.5
 Requires-Dist: jsonref==1.1.0
 Requires-Dist: langchain-core<=0.3.63
 Requires-Dist: langsmith<=0.3.45

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
     "urllib3>=2.2.3",
     "pytz>=2025.2",
     "redis>=6.0.0",
-    "ibm_watsonx_orchestrate_evaluation_framework==1.1.3"
+    "ibm_watsonx_orchestrate_evaluation_framework==1.1.5"
 ]
 
 [project.optional-dependencies]

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/__init__.py

@@ -5,8 +5,8 @@
 
 pkg_name = "ibm-watsonx-orchestrate"
 
+__version__ = "1.13.0b1"
 
-__version__ = "1.12.2"
 
 
 from ibm_watsonx_orchestrate.utils.logging.logger import setup_logging

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/connections/types.py

@@ -27,6 +27,9 @@ class ConnectionEnvironment(str, Enum):
 
     def __str__(self):
         return self.value
+    
+    def __repr__(self):
+        return repr(self.value)
 
 class ConnectionPreference(str, Enum):
     MEMBER = 'member'
@@ -188,9 +191,9 @@ class ConnectionCredentialsEntryLocation(str, Enum):
         return self.value
 
 class ConnectionCredentialsEntry(BaseModel):
-    key: str
-    value: str
-    location: ConnectionCredentialsEntryLocation
+    key: str = Field(description="The key of the custom credential entry.")
+    value: str = Field(description="The value of the custom credential entry.")
+    location: ConnectionCredentialsEntryLocation = Field(description="How the custom credential should be sent to the server")
 
     def __str__(self):
         return f"<ConnectionCredentialsEntry: {self.location}:{self.key}={self.value}>"
@@ -338,3 +341,31 @@ class IdentityProviderCredentials(BaseOAuthCredentials):
 class ExpectedCredentials(BaseModel):
     app_id: str
     type: ConnectionType | List[ConnectionType]
+
+class FetchConfigAuthTypes(str, Enum):
+    BASIC_AUTH = ConnectionType.BASIC_AUTH.value
+    BEARER_TOKEN = ConnectionType.BEARER_TOKEN.value
+    API_KEY_AUTH = ConnectionType.API_KEY_AUTH.value
+    OAUTH2_AUTH_CODE = ConnectionType.OAUTH2_AUTH_CODE.value
+    OAUTH2_IMPLICIT = 'oauth2_implicit'
+    OAUTH2_PASSWORD = ConnectionType.OAUTH2_PASSWORD.value
+    OAUTH2_CLIENT_CREDS = ConnectionType.OAUTH2_CLIENT_CREDS.value
+    OAUTH_ON_BEHALF_OF_FLOW = ConnectionType.OAUTH_ON_BEHALF_OF_FLOW.value
+    KEY_VALUE = ConnectionType.KEY_VALUE.value
+
+class ConnectionsListEntry(BaseModel):
+    app_id: str = Field(description="A unique identifier for the connection.")
+    auth_type: Optional[FetchConfigAuthTypes] = Field(default=None, description="The kind of auth used by the connections")
+    type: Optional[ConnectionPreference] = Field(default=None, description="The type of the connections. If set to 'team' the credentails will be shared by all users. If set to 'member' each user will have to provide their own credentials")
+    credentials_set: bool = Field(default=False, description="Are the credentials set for the current user. If using OAuth connection types this value will be False unless there isn a stored token from runtime usage")
+
+    def get_row_details(self):
+        auth_type = self.auth_type if self.auth_type else "n/a"
+        type = self.type if self.type else "n/a"
+        credentials_set = "✅" if self.credentials_set else "❌"
+        return [self.app_id, auth_type, type, credentials_set]
+
+class ConnectionsListResponse(BaseModel):
+    non_configured: Optional[List[dict] | str] = None
+    draft: Optional[List[dict] | str] = None
+    live: Optional[List[dict] | str] = None

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/knowledge_bases/types.py

@@ -3,7 +3,7 @@ from datetime import datetime
 from uuid import UUID
 from enum import Enum
 
-from pydantic import BaseModel, model_validator
+from pydantic import BaseModel, model_validator, Field
 
 
 class SpecVersion(str, Enum):
@@ -11,6 +11,7 @@ class SpecVersion(str, Enum):
 
 class KnowledgeBaseKind(str, Enum):
     KNOWLEDGE_BASE = "knowledge_base"
+
 class RetrievalConfidenceThreshold(str, Enum):
     Off = "Off"
     Lowest = "Lowest"
@@ -240,6 +241,7 @@ class AstraDBConnection(BaseModel):
 
 class IndexConnection(BaseModel):
     connection_id: Optional[str] = None
+    app_id: Optional[str] = None
     milvus: Optional[MilvusConnection] = None
     elastic_search: Optional[ElasticSearchConnection] = None
     custom_search: Optional[CustomSearchConnection] = None
@@ -295,4 +297,13 @@ class KnowledgeBaseSpec(BaseModel):
     created_on: Optional[datetime] = None 
     updated_at: Optional[datetime] = None
     # For import/update
-    documents: list[str] | list[FileUpload] = None
+    documents: list[str] | list[FileUpload] = None
+
+class KnowledgeBaseListEntry(BaseModel):
+    name: str = Field(description="Name of the knowledge base")
+    description: Optional[str] = Field(description="A description of the content contained in a knowledge base")
+    app_id: Optional[str] = Field(description="The app id for a connection that connects the knowledge base to an external knowledge store")
+    id: Optional[str] = Field(description="Unique identifier of the knowledge base")
+
+    def get_row_details(self):
+        return [self.name, self.description, self.app_id, self.id]

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/models/types.py

@@ -226,5 +226,21 @@ class ListVirtualModel(BaseModel):
     provider_config: Optional[ProviderConfig] = None
     tags: Optional[List[str]] = None
     model_type: Optional[str] = None
+    connection_id: Optional[str] = None
 
-ANTHROPIC_DEFAULT_MAX_TOKENS = 4096
+class ModelListEntry(BaseModel):
+    name: Optional[str] = Field(default=None, description="Name of the model")
+    description: Optional[str] = Field(default=None, description="A description of the model")
+    is_custom: bool = Field(default=False, description="Is the model a third party model imported into Orchestrate")
+    recommended: bool = Field(default=False, description="Is the model a reccomended model in watsonx. Non-custom models only")
+
+    def get_row_details(self):
+        description = self.description or 'No description provided.'
+        if self.is_custom:
+            return [f"✨️ {self.name}", description]
+        else:
+            name = self.name or "N/A"
+            marker = "★ " if self.recommended else ""
+            return [f"[yellow]{marker}[/yellow]watsonx/{name}", description]
+
+ANTHROPIC_DEFAULT_MAX_TOKENS = 4096

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/toolkits/types.py

@@ -1,6 +1,6 @@
 from typing import List, Dict, Optional, Union
 from enum import Enum
-from pydantic import BaseModel 
+from pydantic import BaseModel, Field
 
 class ToolkitKind(str, Enum):
     MCP = "mcp"
@@ -42,4 +42,16 @@ class ToolkitSpec(BaseModel):
     created_by: str
     created_by_username: str
     tools: List[str] | None
-    mcp: McpModel
+    mcp: McpModel
+
+class ToolkitListEntry(BaseModel):
+    name: str = Field(description="The name of the Toolkit")
+    description: Optional[str] = Field(description="The description of the Toolkit")
+    type: str = Field(default="MCP", description="The type of Toolkit.")
+    tools: Optional[List[str]] = Field(description = "A list of tool names for every tool in the Toolkit")
+    app_ids: Optional[List[str]] = Field(description = "A list of connection app_ids showing every connection bound to the Toolkit")
+
+    def get_row_details(self):
+        tools = ", ".join(self.tools) if self.tools else ""
+        app_ids = ", ".join(self.app_ids) if self.app_ids else ""
+        return [self.name, self.description, self.type, tools, app_ids]

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/tools/__init__.py

@@ -2,4 +2,4 @@ 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
+from .types import ToolPermission, JsonSchemaObject, ToolRequestBody, ToolResponseBody, OpenApiSecurityScheme, OpenApiToolBinding, PythonToolBinding, WxFlowsToolBinding, SkillToolBinding, ClientSideToolBinding, ToolBinding, ToolSpec, ToolListEntry

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/tools/types.py

@@ -1,10 +1,12 @@
 from enum import Enum
 from typing import List, Any, Dict, Literal, Optional, Union
+import logging
 
-from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices, ValidationError
+from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices, ValidationError, ValidationInfo
 from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 from ibm_watsonx_orchestrate.agent_builder.connections import KeyValueConnectionCredentials
 
+logger = logging.getLogger(__name__)
 
 class ToolPermission(str, Enum):
     READ_ONLY = 'read_only'
@@ -117,9 +119,14 @@ class OpenApiToolBinding(BaseModel):
     acknowledgement: Optional[AcknowledgementBinding] = None
 
     @model_validator(mode='after')
-    def validate_openapi_tool_binding(self):
+    def validate_openapi_tool_binding(self, info: ValidationInfo):
+        context = getattr(info, "context", None)
+
         if len(self.servers) != 1:
-            raise BadRequest("OpenAPI definition must include exactly one server")
+            if isinstance(context, str) and context == "list":
+                logger.warning("OpenAPI definition must include exactly one server")
+            else:
+                raise BadRequest("OpenAPI definition must include exactly one server")
         return self
 
 
@@ -259,3 +266,14 @@ class ToolSpec(BaseModel):
             return False
 
         return True
+
+class ToolListEntry(BaseModel):
+    name: str = Field(description="The name of the tool")
+    description: Optional[str] = Field(description="A description of the purpose of the tool")
+    type: Optional[str] = Field(description="The type of the tool"),
+    toolkit: Optional[str] = Field(description="The name of the Toolkit the tool belongs. Empty if the tool is not from a Toolkit"),
+    app_ids: Optional[List[str]] = Field(description="A list of app_ids that show what connections are bound to a tool")
+
+    def get_row_details(self):
+        app_ids = ", ".join(self.app_ids) if self.app_ids else ""
+        return [self.name, self.description, self.type, self.toolkit, app_ids]

ibm_watsonx_orchestrate-1.13.0b1/src/ibm_watsonx_orchestrate/agent_builder/voice_configurations/__init__.py

@@ -0,0 +1 @@
+from .types import VoiceConfiguration, VoiceConfigurationListEntry

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/agent_builder/voice_configurations/types.py

@@ -95,4 +95,15 @@ class VoiceConfiguration(BaseModel):
     dumped = self.model_dump(mode='json', exclude_none=True)
     return json.dumps(dumped, indent=2)
 
+class VoiceConfigurationListEntry(BaseModel):
+    name: str = Field(description="Name of the voice configuration.")
+    id: str = Field(default=None, description="A unique identifier for the voice configuration.")
+    speech_to_text_provider: Optional[str] = Field("The speech to text service provider.")
+    text_to_speech_provider: Optional[str] = Field("The text to speech service provider.")
+    attached_agents: Optional[List[str]] = Field("A list of agent names that use the voice configuration.")
+
+    def get_row_details(self):
+        attached_agents = ", ".join(self.attached_agents) if self.attached_agents else ""
+        return [self.name, self.id, self.speech_to_text_provider, self.text_to_speech_provider, attached_agents]
+
 

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/cli/commands/agents/agents_controller.py

@@ -16,8 +16,9 @@ from pydantic import BaseModel
 from ibm_watsonx_orchestrate.agent_builder.agents.types import AgentStyle
 from ibm_watsonx_orchestrate.agent_builder.tools.types import ToolSpec
 from ibm_watsonx_orchestrate.cli.commands.tools.tools_controller import import_python_tool, ToolsController
-from ibm_watsonx_orchestrate.cli.commands.knowledge_bases.knowledge_bases_controller import import_python_knowledge_base
+from ibm_watsonx_orchestrate.cli.commands.knowledge_bases.knowledge_bases_controller import import_python_knowledge_base, KnowledgeBaseController
 from ibm_watsonx_orchestrate.cli.commands.models.models_controller import import_python_model
+from ibm_watsonx_orchestrate.cli.common import ListFormats, rich_table_to_markdown
 
 from ibm_watsonx_orchestrate.agent_builder.agents import (
     Agent,
@@ -41,23 +42,11 @@ from ibm_watsonx_orchestrate.utils.utils import check_file_in_zip
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
-from enum import Enum
-
 logger = logging.getLogger(__name__)
 
 # Helper generic type for any agent
 AnyAgentT = TypeVar("AnyAgentT", bound=Agent | ExternalAgent | AssistantAgent)
 
-class AgentListFormats(str, Enum):
-    Table = "table"
-    JSON = "json"
-
-    def __str__(self):
-        return self.value 
-
-    def __repr__(self):
-        return repr(self.value)
-
 
 def import_python_agent(file: str) -> List[Agent | ExternalAgent | AssistantAgent]:
     # Import tools
@@ -858,7 +847,7 @@ class AgentsController:
 
     def _get_all_unique_agent_resources(self, agents: List[Agent], target_attr: str) -> List[str]:
         """
-            Given a list if agents get all the unique values of a certain field
+            Given a list of agents get all the unique values of a certain field
             Example: agent1.tools = [1 ,2 ,3] and agent2.tools = [2, 4, 5] then return [1, 2, 3, 4, 5]
             Example: agent1.id = "123" and agent2.id = "456" then return ["123", "456"]
 
@@ -959,18 +948,14 @@ class AgentsController:
             if tool_names:
                 agent.tools = tool_names
         return new_agents
-    
-    # TODO: Once bulk knowledge base is added create a generaic fucntion as opposed to 3 seperate ones
+
     def _bulk_resolve_agent_knowledge_bases(self, agents: List[Agent]) -> List[Agent]:
         new_agents = agents.copy()
         all_kb_ids = self._get_all_unique_agent_resources(new_agents, "knowledge_base")
+        if not all_kb_ids:
+            return new_agents
 
-        all_kbs = []
-        for id in all_kb_ids:
-            try:
-                all_kbs.append(self.get_knowledge_base_client().get_by_id(id))
-            except:
-                continue
+        all_kbs = self._batch_request_resource(self.get_knowledge_base_client().get_by_ids, all_kb_ids)
 
         kb_lut = self._construct_lut_agent_resource(all_kbs, "id", "name")
         
@@ -1016,24 +1001,7 @@ class AgentsController:
                 agent.app_id = app_id
         return new_agents
 
-    # TODO: Make a shared util
-    def _rich_table_to_markdown(self, table: rich.table.Table) -> str:
-        headers = [column.header for column in table.columns]
-        cols = [[cell for cell in col.cells] for col in table.columns]
-        rows = list(map(list, zip(*cols)))
-
-        # Header row
-        md = "| " + " | ".join(headers) + " |\n"
-        # Separator row
-        md += "| " + " | ".join(["---"] * len(headers)) + " |\n"
-        # # Data rows
-        for row in rows:
-            md += "| " + " | ".join(row) + " |\n"
-        return md
-
-
-
-    def list_agents(self, kind: AgentKind=None, verbose: bool=False, format: AgentListFormats | None = None) -> dict[str, dict] | None:
+    def list_agents(self, kind: AgentKind=None, verbose: bool=False, format: ListFormats | None = None) -> dict[str, dict] | dict[str, str] | None:
         """
         List agents in the active wxo environment
 
@@ -1068,7 +1036,7 @@ class AgentsController:
                 resolved_native_agents = self._bulk_resolve_agent_knowledge_bases(resolved_native_agents)
                 resolved_native_agents = self._bulk_resolve_agent_collaborators(resolved_native_agents)
 
-                if format and format == AgentListFormats.JSON:
+                if format and format == ListFormats.JSON:
                     agents_list = []
                     for agent in resolved_native_agents:
                         agents_list.append(json.loads(agent.dumps_spec()))
@@ -1096,8 +1064,9 @@ class AgentsController:
                         native_table.add_column(column, **column_args[column])
 
                     for agent in resolved_native_agents:
+                        agent_name = self._format_agent_display_name(agent)
                         native_table.add_row(
-                            agent.name,
+                            agent_name,
                             agent.description,
                             agent.llm,
                             agent.style,
@@ -1106,8 +1075,8 @@ class AgentsController:
                             ", ".join(agent.knowledge_base),
                             agent.id,
                         )
-                    if format == AgentListFormats.Table:
-                        output_dictionary["native"] = self._rich_table_to_markdown(native_table)
+                    if format == ListFormats.Table:
+                        output_dictionary["native"] = rich_table_to_markdown(native_table)
                     else:
                         rich.print(native_table)
       
@@ -1123,7 +1092,7 @@ class AgentsController:
             else:
                 resolved_external_agents = self._bulk_resolve_agent_app_ids(external_agents)
                 
-                if format and format == AgentListFormats.JSON:
+                if format and format == ListFormats.JSON:
                     external_agents_list = []
                     for agent in resolved_external_agents:
                         external_agents_list.append(json.loads(agent.dumps_spec()))
@@ -1157,8 +1126,9 @@ class AgentsController:
                         app_id = connections_client.get_draft_by_id(agent.connection_id)
                         resolved_native_agents = self._bulk_resolve_agent_app_ids(external_agents)
 
+                        agent_name = self._format_agent_display_name(agent)
                         external_table.add_row(
-                            agent.name,
+                            agent_name,
                             agent.title,
                             agent.description,
                             ", ".join(agent.tags or []),
@@ -1169,8 +1139,8 @@ class AgentsController:
                             app_id,
                             agent.id
                         )
-                    if format == AgentListFormats.Table:
-                        output_dictionary["external"] = self._rich_table_to_markdown(external_table)
+                    if format == ListFormats.Table:
+                        output_dictionary["external"] = rich_table_to_markdown(external_table)
                     else:
                         rich.print(external_table)
         
@@ -1186,7 +1156,7 @@ class AgentsController:
             else:
                 resolved_external_agents = self._bulk_resolve_agent_app_ids(assistant_agents)
                 
-                if format and format == AgentListFormats.JSON:
+                if format and format == ListFormats.JSON:
                     assistant_agents_list = []
                     for agent in resolved_external_agents:
                         assistant_agents_list.append(json.loads(agent.dumps_spec()))
@@ -1215,8 +1185,9 @@ class AgentsController:
                         assistants_table.add_column(column, **column_args[column])
                     
                     for agent in assistant_agents:
+                        agent_name = self._format_agent_display_name(agent)
                         assistants_table.add_row(
-                            agent.name,
+                            agent_name,
                             agent.title,
                             agent.description,
                             ", ".join(agent.tags or []),
@@ -1227,8 +1198,8 @@ class AgentsController:
                             agent.config.environment_id,
                             agent.id
                         )
-                    if format == AgentListFormats.Table:
-                        output_dictionary["assistant"] = self._rich_table_to_markdown(assistants_table)
+                    if format == ListFormats.Table:
+                        output_dictionary["assistant"] = rich_table_to_markdown(assistants_table)
                     else:
                         rich.print(assistants_table)
 
@@ -1391,8 +1362,10 @@ class AgentsController:
                         ToolSpec.model_validate(current_spec).model_dump_json(exclude_unset=True,indent=2)
                     )
         
+        knowledge_base_controller = KnowledgeBaseController()
         for kb_name in agent_spec_file_content.get("knowledge_base", []):
-            logger.warning(f"Skipping {kb_name}, knowledge_bases are currently unsupported by export")
+            knowledge_base_file_path = f"{output_file_name}/knowledge-bases/{kb_name}.yaml"
+            knowledge_base_controller.knowledge_base_export(name=kb_name, output_path=knowledge_base_file_path, zip_file_out=zip_file_out)
         
         if kind == AgentKind.NATIVE:
             for collaborator_id in agent.collaborators:
@@ -1523,4 +1496,9 @@ class AgentsController:
             logger.info(f"Successfully undeployed agent {name}")
         else:
             logger.error(f"Error undeploying agent {name}")
+    
+    @staticmethod
+    def _format_agent_display_name(agent: AnyAgentT) -> str:
+        return f"{agent.name} ({agent.display_name})" if agent.display_name and agent.name != agent.display_name else agent.name
+
 

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/cli/commands/connections/connections_command.py

@@ -1,6 +1,6 @@
 import typer
 from typing_extensions import Annotated, List
-from ibm_watsonx_orchestrate.agent_builder.connections.types import ConnectionEnvironment, ConnectionPreference, ConnectionKind, ConnectionCredentialsEntry
+from ibm_watsonx_orchestrate.agent_builder.connections.types import ConnectionEnvironment, ConnectionPreference, ConnectionKind, ConnectionCredentialsEntry, ConnectionSendVia
 from ibm_watsonx_orchestrate.cli.commands.connections.connections_controller import (
     add_connection,
     remove_connection,
@@ -222,7 +222,7 @@ def set_credentials_connection_command(
         )
     ] = None,
     send_via: Annotated[
-        str,
+        ConnectionSendVia,
         typer.Option(
             '--send-via',
             help='For oauth_auth_client_credentials_flow, how the token will be sent to the server. Defaults to using `header`'

{ibm_watsonx_orchestrate-1.12.2 → ibm_watsonx_orchestrate-1.13.0b1}/src/ibm_watsonx_orchestrate/cli/commands/connections/connections_controller.py

@@ -9,8 +9,9 @@ import yaml
 import sys
 import typer
 
-from typing import List
+from typing import List, Optional, Any
 from ibm_watsonx_orchestrate.agent_builder.agents.types import SpecVersion
+
 from ibm_watsonx_orchestrate.client.utils import is_local_dev
 from ibm_watsonx_orchestrate.agent_builder.connections.types import (
     ConnectionEnvironment,
@@ -34,11 +35,13 @@ from ibm_watsonx_orchestrate.agent_builder.connections.types import (
     OAUTH_CONNECTION_TYPES,
     ConnectionCredentialsEntryLocation,
     ConnectionCredentialsEntry,
-    ConnectionCredentialsCustomFields
-
+    ConnectionCredentialsCustomFields,
+    ConnectionsListEntry,
+    ConnectionsListResponse
 )
 
 from ibm_watsonx_orchestrate.client.connections import get_connections_client, get_connection_type
+from ibm_watsonx_orchestrate.cli.common import ListFormats, rich_table_to_markdown
 
 logger = logging.getLogger(__name__)
 
@@ -470,7 +473,11 @@ def remove_connection(app_id: str) -> None:
         logger.error(response_text)
         exit(1)
 
-def list_connections(environment: ConnectionEnvironment | None, verbose: bool = False) -> None:
+def list_connections(environment: ConnectionEnvironment | None = None, verbose: bool = False, format: Optional[ListFormats] = None) -> List[dict[str, Any]]| ConnectionsListResponse | None:
+    if verbose and format:
+            logger.error("For connections list, `--verbose` and `--format` are mutually exclusive options")
+            sys.exit(1)
+
     client = get_connections_client()
     connections = client.list()
     is_local = is_local_dev()
@@ -483,7 +490,12 @@ def list_connections(environment: ConnectionEnvironment | None, verbose: bool =
             connections_list.append(json.loads(conn.model_dump_json()))
 
         rich.print_json(json.dumps(connections_list, indent=4))
+        return connections_list
     else:
+        non_configured_connection_details = []
+        draft_connection_details = []
+        live_connection_details = []
+
         non_configured_table = rich.table.Table(show_header=True, header_style="bold white", show_lines=True, title="*Non-Configured")
         draft_table = rich.table.Table(show_header=True, header_style="bold white", show_lines=True, title="Draft")
         live_table = rich.table.Table(show_header=True, header_style="bold white", show_lines=True, title="Live")
@@ -501,41 +513,55 @@ def list_connections(environment: ConnectionEnvironment | None, verbose: bool =
         
         for conn in connections:
             if conn.environment is None:
-                non_configured_table.add_row(
-                    conn.app_id,
-                    "n/a",
-                    "n/a",
-                    "❌"
+                entry = ConnectionsListEntry(
+                    app_id=conn.app_id,
                 )
+
+                non_configured_table.add_row(*entry.get_row_details())
+                non_configured_connection_details.append(entry.model_dump())
                 continue
             
             try:
                 connection_type = get_connection_type(security_scheme=conn.security_scheme, auth_type=conn.auth_type)
             except:
                 connection_type = conn.auth_type
+            
+            entry = ConnectionsListEntry(
+                    app_id=conn.app_id,
+                    auth_type = connection_type,
+                    type=conn.preference,
+                    credentials_set=conn.credentials_entered
+                )
 
             if conn.environment == ConnectionEnvironment.DRAFT:
-                draft_table.add_row(
-                    conn.app_id,
-                    connection_type,
-                    conn.preference,
-                    "✅" if conn.credentials_entered else "❌"
-                )
+                draft_table.add_row(*entry.get_row_details())
+                draft_connection_details.append(entry.model_dump())
             elif conn.environment == ConnectionEnvironment.LIVE and not is_local:
-                live_table.add_row(
-                    conn.app_id,
-                    connection_type,
-                    conn.preference,
-                    "✅" if conn.credentials_entered else "❌"
+                live_table.add_row(*entry.get_row_details())
+                live_connection_details.append(entry.model_dump())
+        
+        match format:
+            case ListFormats.JSON:
+                return ConnectionsListResponse(
+                    non_configured=non_configured_connection_details,
+                    draft=draft_connection_details,
+                    live=live_connection_details
+                )
+            case ListFormats.Table:
+                return ConnectionsListResponse(
+                    non_configured=rich_table_to_markdown(non_configured_table),
+                    draft=rich_table_to_markdown(draft_table),
+                    live=rich_table_to_markdown(live_table)
                 )
-        if environment is None and len(non_configured_table.rows):
-            rich.print(non_configured_table)
-        if environment == ConnectionEnvironment.DRAFT or (environment == None and len(draft_table.rows)):
-            rich.print(draft_table)
-        if environment == ConnectionEnvironment.LIVE or (environment == None and len(live_table.rows)):
-            rich.print(live_table)
-        if environment == None and not len(draft_table.rows) and not len(live_table.rows) and not len(non_configured_table.rows):
-            logger.info("No connections found. You can create connections using `orchestrate connections add`")
+            case _:
+                if environment is None and len(non_configured_table.rows):
+                    rich.print(non_configured_table)
+                if environment == ConnectionEnvironment.DRAFT or (environment == None and len(draft_table.rows)):
+                    rich.print(draft_table)
+                if environment == ConnectionEnvironment.LIVE or (environment == None and len(live_table.rows)):
+                    rich.print(live_table)
+                if environment == None and not len(draft_table.rows) and not len(live_table.rows) and not len(non_configured_table.rows):
+                    logger.info("No connections found. You can create connections using `orchestrate connections add`")
 
 def import_connection(file: str) -> None:
     _parse_file(file=file)