ibm-watsonx-orchestrate 1.7.0a0__py3-none-any.whl → 1.8.0b0__py3-none-any.whl

ibm_watsonx_orchestrate/__init__.py

@@ -5,7 +5,7 @@
 
 pkg_name = "ibm-watsonx-orchestrate"
 
-__version__ = "1.7.0a0"
+__version__ = "1.8.0b0"
 
 
 

ibm_watsonx_orchestrate/agent_builder/agents/agent.py

@@ -1,6 +1,7 @@
 import json
 from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
 from .types import AgentSpec
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 
 class Agent(AgentSpec):
@@ -13,10 +14,9 @@ class Agent(AgentSpec):
             elif file.endswith('.json'):
                 content = json.load(f)
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
-            
+                raise BadRequest('file must end in .json, .yaml, or .yml')
             if not content.get("spec_version"):
-                raise ValueError(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
+                raise BadRequest(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
             agent = Agent.model_validate(content)
 
         return agent

ibm_watsonx_orchestrate/agent_builder/agents/assistant_agent.py

@@ -1,6 +1,7 @@
 import json
 from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
 from .types import AssistantAgentSpec
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 
 class AssistantAgent(AssistantAgentSpec):
@@ -13,10 +14,10 @@ class AssistantAgent(AssistantAgentSpec):
             elif file.endswith('.json'):
                 content = json.load(f)
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
             
             if not content.get("spec_version"):
-                raise ValueError(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
+                raise BadRequest(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
             agent = AssistantAgent.model_validate(content)
 
         return agent

ibm_watsonx_orchestrate/agent_builder/agents/external_agent.py

@@ -1,6 +1,7 @@
 import json
 from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
 from .types import ExternalAgentSpec
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 
 class ExternalAgent(ExternalAgentSpec):
@@ -13,10 +14,10 @@ class ExternalAgent(ExternalAgentSpec):
             elif file.endswith('.json'):
                 content = json.load(f)
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
             
             if not content.get("spec_version"):
-                raise ValueError(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
+                raise BadRequest(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
             agent = ExternalAgent.model_validate(content)
 
         return agent

ibm_watsonx_orchestrate/agent_builder/agents/types.py

@@ -9,11 +9,22 @@ 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.utils.exceptions import BadRequest
 
 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-1-70b-instruct"
+DEFAULT_LLM = "watsonx/meta-llama/llama-3-2-90b-vision-instruct"
+
+# Handles yaml formatting for multiline strings to improve readability
+def str_presenter(dumper, data):
+    if len(data.splitlines()) > 1:  # check for multiline string
+        data = "\n".join([line.rstrip() for line in data.splitlines()])
+        return dumper.represent_scalar('tag:yaml.org,2002:str', data, style='|')
+    return dumper.represent_scalar('tag:yaml.org,2002:str', data)
+
+yaml.add_representer(str, str_presenter)
+yaml.representer.SafeRepresenter.add_representer(str, str_presenter) # to use with safe_dum
 
 class SpecVersion(str, Enum):
     V1 = "v1"
@@ -24,6 +35,12 @@ class AgentKind(str, Enum):
     EXTERNAL = "external"
     ASSISTANT = "assistant"
 
+    def __str__(self):
+        return self.value 
+
+    def __repr__(self):
+        return repr(self.value)
+
 class ExternalAgentAuthScheme(str, Enum):
     BEARER_TOKEN = 'BEARER_TOKEN'
     API_KEY = "API_KEY"
@@ -63,7 +80,7 @@ class BaseAgentSpec(BaseModel):
             elif file.endswith('.json'):
                 json.dump(dumped, f, indent=2)
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
 
     def dumps_spec(self) -> str:
         dumped = self.model_dump(mode='json', exclude_none=True)
@@ -136,7 +153,7 @@ class AgentSpec(BaseAgentSpec):
     @model_validator(mode="after")
     def validate_kind(self):
         if self.kind != AgentKind.NATIVE:
-            raise ValueError(f"The specified kind '{self.kind}' cannot be used to create a native agent.")
+            raise BadRequest(f"The specified kind '{self.kind}' cannot be used to create a native agent.")
         return self
 
 def validate_agent_fields(values: dict) -> dict:
@@ -144,13 +161,13 @@ def validate_agent_fields(values: dict) -> dict:
     for field in ["id", "name", "kind", "description", "collaborators", "tools", "knowledge_base"]:
         value = values.get(field)
         if value and not str(value).strip():
-            raise ValueError(f"{field} cannot be empty or just whitespace")
+            raise BadRequest(f"{field} cannot be empty or just whitespace")
     
     name = values.get("name")
     collaborators = values.get("collaborators", [])  if values.get("collaborators", []) else []
     for collaborator in collaborators:
         if collaborator == name:
-            raise ValueError(f"Circular reference detected. The agent '{name}' cannot contain itself as a collaborator")
+            raise BadRequest(f"Circular reference detected. The agent '{name}' cannot contain itself as a collaborator")
 
     if values.get("style") == AgentStyle.PLANNER:
         if values.get("custom_join_tool") and values.get("structured_output"):
@@ -197,7 +214,7 @@ class ExternalAgentSpec(BaseAgentSpec):
     @model_validator(mode="after")
     def validate_kind_for_external(self):
         if self.kind != AgentKind.EXTERNAL:
-            raise ValueError(f"The specified kind '{self.kind}' cannot be used to create an external agent.")
+            raise BadRequest(f"The specified kind '{self.kind}' cannot be used to create an external agent.")
         return self
 
 def validate_external_agent_fields(values: dict) -> dict:
@@ -205,7 +222,7 @@ def validate_external_agent_fields(values: dict) -> dict:
     for field in ["name", "kind", "description", "title", "tags", "api_url", "chat_params", "nickname", "app_id"]:
         value = values.get(field)
         if value and not str(value).strip():
-            raise ValueError(f"{field} cannot be empty or just whitespace")
+            raise BadRequest(f"{field} cannot be empty or just whitespace")
 
     context_variables = values.get("context_variables")
     if context_variables is not None:
@@ -250,7 +267,7 @@ class AssistantAgentSpec(BaseAgentSpec):
     @model_validator(mode="after")
     def validate_kind_for_external(self):
         if self.kind != AgentKind.ASSISTANT:
-            raise ValueError(f"The specified kind '{self.kind}' cannot be used to create an assistant agent.")
+            raise BadRequest(f"The specified kind '{self.kind}' cannot be used to create an assistant agent.")
         return self
 
 def validate_assistant_agent_fields(values: dict) -> dict:
@@ -258,7 +275,7 @@ def validate_assistant_agent_fields(values: dict) -> dict:
     for field in ["name", "kind", "description", "title", "tags", "nickname", "app_id"]:
         value = values.get(field)
         if value and not str(value).strip():
-            raise ValueError(f"{field} cannot be empty or just whitespace")
+            raise BadRequest(f"{field} cannot be empty or just whitespace")
 
     # Validate context_variables if provided
     context_variables = values.get("context_variables")

ibm_watsonx_orchestrate/agent_builder/agents/webchat_customizations/prompts.py

@@ -7,6 +7,7 @@ from pydantic import BaseModel, model_validator
 class PromptState(str,Enum):
     ACTIVE = "active"
     INACTIVE = "inactive"
+    MISSING = ""
 
 
 class AgentPrompt(BaseModel):

ibm_watsonx_orchestrate/agent_builder/connections/connections.py

@@ -8,11 +8,13 @@ from ibm_watsonx_orchestrate.agent_builder.connections.types import (
     OAuth2TokenCredentials,
     KeyValueConnectionCredentials,
     ConnectionType,
+    ConnectionSecurityScheme,
     CREDENTIALS,
     CONNECTION_TYPE_CREDENTIAL_MAPPING
 )
 
 from ibm_watsonx_orchestrate.utils.utils import sanatize_app_id
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 logger = logging.getLogger(__name__)
 
@@ -26,6 +28,18 @@ connection_type_requirements_mapping = {
     KeyValueConnectionCredentials: None
 }
 
+connection_type_security_schema_map = {
+    ConnectionType.API_KEY_AUTH: ConnectionSecurityScheme.API_KEY_AUTH,
+    ConnectionType.BASIC_AUTH: ConnectionSecurityScheme.BASIC_AUTH,
+    ConnectionType.BEARER_TOKEN: ConnectionSecurityScheme.BEARER_TOKEN,
+    ConnectionType.KEY_VALUE: ConnectionSecurityScheme.KEY_VALUE,
+    ConnectionType.OAUTH2_AUTH_CODE: ConnectionSecurityScheme.OAUTH2,
+    ConnectionType.OAUTH2_CLIENT_CREDS: ConnectionSecurityScheme.OAUTH2,
+    ConnectionType.OAUTH_ON_BEHALF_OF_FLOW: ConnectionSecurityScheme.OAUTH2,
+    # ConnectionType.OAUTH2_IMPLICIT: ConnectionSecurityScheme.OAUTH2,
+    # ConnectionType.OAUTH2_PASSWORD: ConnectionSecurityScheme.OAUTH2
+}
+
 def _clean_env_vars(vars: dict[str:str], requirements: List[str], app_id: str) -> dict[str,str]:
     base_prefix = _PREFIX_TEMPLATE.format(app_id=app_id)
 
@@ -48,7 +62,7 @@ def _clean_env_vars(vars: dict[str:str], requirements: List[str], app_id: str) -
         missing_requirements_str = ", ".join(missing_requirements)
         message = f"Missing requirement environment variables '{missing_requirements_str}' for connection '{app_id}'"
         logger.error(message)
-        raise ValueError(message)
+        raise BadRequest(message)
     
     return required_env_vars
 
@@ -75,10 +89,10 @@ def _build_credentials_model(credentials_type: type[CREDENTIALS], vars: dict[str
         )
 
 
-def _validate_schema_type(requested_type: ConnectionType, expected_type: ConnectionType) -> bool:
+def _validate_schema_type(requested_type: ConnectionSecurityScheme, expected_type: ConnectionSecurityScheme) -> bool:
         return expected_type == requested_type
 
-def _get_credentials_model(connection_type: ConnectionType, app_id: str) -> type[CREDENTIALS]:
+def _get_credentials_model(connection_type: ConnectionSecurityScheme, app_id: str) -> type[CREDENTIALS]:
     base_prefix = _PREFIX_TEMPLATE.format(app_id=app_id)
     variables = {}
     for key, value in os.environ.items():
@@ -93,7 +107,7 @@ def _get_credentials_model(connection_type: ConnectionType, app_id: str) -> type
 
     return _build_credentials_model(credentials_type=credentials_type, vars=variables, base_prefix=base_prefix)
 
-def get_connection_type(app_id: str) -> ConnectionType:
+def get_connection_type(app_id: str) -> ConnectionSecurityScheme:
     sanitized_app_id = sanatize_app_id(app_id=app_id)
     expected_schema_key = f"WXO_SECURITY_SCHEMA_{sanitized_app_id}"
     expected_schema = os.environ.get(expected_schema_key)
@@ -101,9 +115,9 @@ def get_connection_type(app_id: str) -> ConnectionType:
     if not expected_schema:
         message = f"No credentials found for connections '{app_id}'"
         logger.error(message)
-        raise ValueError(message)
+        raise BadRequest(message)
 
-    auth_types = {e.value for e in ConnectionType}
+    auth_types = {e.value for e in ConnectionSecurityScheme}
     if expected_schema not in auth_types:
         message = f"The expected type '{expected_schema}' cannot be resolved into a valid connection auth type ({', '.join(list(auth_types))})"
         logger.error(message)
@@ -114,10 +128,11 @@ def get_connection_type(app_id: str) -> ConnectionType:
 def get_application_connection_credentials(type: ConnectionType, app_id: str) -> CREDENTIALS:
     sanitized_app_id = sanatize_app_id(app_id=app_id)
     expected_schema = get_connection_type(app_id=app_id)
+    requested_schema = connection_type_security_schema_map.get(type)
 
-    if not _validate_schema_type(requested_type=type, expected_type=expected_schema):
-        message = f"The requested type '{type.__name__}' does not match the type '{expected_schema}' for the connection '{app_id}'"
+    if not _validate_schema_type(requested_type=requested_schema, expected_type=expected_schema):
+        message = f"The requested type '{requested_schema}' does not match the type '{expected_schema}' for the connection '{app_id}'"
         logger.error(message)
-        raise ValueError(message)
+        raise BadRequest(message)
 
-    return _get_credentials_model(connection_type=type, app_id=sanitized_app_id)
+    return _get_credentials_model(connection_type=requested_schema, app_id=sanitized_app_id)

ibm_watsonx_orchestrate/agent_builder/connections/types.py

@@ -244,15 +244,11 @@ CONNECTION_KIND_OAUTH_TYPE_MAPPING = {
 }
 
 CONNECTION_TYPE_CREDENTIAL_MAPPING = {
-    ConnectionType.BASIC_AUTH: BasicAuthCredentials,
-    ConnectionType.BEARER_TOKEN: BearerTokenAuthCredentials,
-    ConnectionType.API_KEY_AUTH: APIKeyAuthCredentials,
-    ConnectionType.OAUTH2_AUTH_CODE: OAuth2TokenCredentials,
-    # ConnectionType.OAUTH2_IMPLICIT: OAuth2TokenCredentials,
-    # ConnectionType.OAUTH2_PASSWORD: OAuth2TokenCredentials,
-    ConnectionType.OAUTH2_CLIENT_CREDS: OAuth2TokenCredentials,
-    ConnectionType.OAUTH_ON_BEHALF_OF_FLOW: OAuth2TokenCredentials,
-    ConnectionType.KEY_VALUE: KeyValueConnectionCredentials,
+    ConnectionSecurityScheme.BASIC_AUTH: BasicAuthCredentials,
+    ConnectionSecurityScheme.BEARER_TOKEN: BearerTokenAuthCredentials,
+    ConnectionSecurityScheme.API_KEY_AUTH: APIKeyAuthCredentials,
+    ConnectionSecurityScheme.OAUTH2: OAuth2TokenCredentials,
+    ConnectionSecurityScheme.KEY_VALUE: KeyValueConnectionCredentials,
 }
 
 class IdentityProviderCredentials(BaseModel):

ibm_watsonx_orchestrate/agent_builder/knowledge_bases/knowledge_base_requests.py

@@ -1,7 +1,6 @@
 import json
 from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
-from .types import KnowledgeBaseSpec, PatchKnowledgeBase, KnowledgeBaseKind
-
+from .types import KnowledgeBaseSpec
 
 class KnowledgeBaseCreateRequest(KnowledgeBaseSpec):
 
@@ -21,23 +20,3 @@ class KnowledgeBaseCreateRequest(KnowledgeBaseSpec):
             knowledge_base = KnowledgeBaseSpec.model_validate(content)
 
         return knowledge_base
-    
-
-class KnowledgeBaseUpdateRequest(PatchKnowledgeBase):
-
-    @staticmethod
-    def from_spec(file: str) -> 'PatchKnowledgeBase':
-        with open(file, 'r') as f:
-            if file.endswith('.yaml') or file.endswith('.yml'):
-                content = yaml_safe_load(f)
-            elif file.endswith('.json'):
-                content = json.load(f)
-            else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
-            
-            if not content.get("spec_version"):
-                raise ValueError(f"Field 'spec_version' not provided. Please ensure provided spec conforms to a valid spec format")
-            
-            patch = PatchKnowledgeBase.model_validate(content)
-
-        return patch

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
 
 class SpecVersion(str, Enum):
     V1 = "v1"
@@ -219,22 +219,6 @@ class KnowledgeBaseBuiltInVectorIndexConfig(BaseModel):
     chunk_overlap: Optional[int] = None
     limit: Optional[int] = None
     
-class PatchKnowledgeBase(BaseModel):
-    """request payload schema"""
-    description: Optional[str] = None
-    documents: list[str] = None
-    conversational_search_tool: Optional[ConversationalSearchConfig] = None  
-    prioritize_built_in_index: Optional[bool] = None
-    representation: Optional[KnowledgeBaseRepresentation] = None
-
-    @model_validator(mode="after")
-    def validate_fields(self):
-        if self.documents and self.conversational_search_tool and self.conversational_search_tool.index_config:
-            raise ValueError("Must not provide both \"documents\" or \"conversational_search_tool.index_config\"")
-        if self.conversational_search_tool and self.conversational_search_tool.index_config and len(self.conversational_search_tool.index_config) != 1:
-            raise ValueError(f"Must provide exactly one conversational_search_tool.index_config. Provided {len(self.conversational_search_tool.index_config)}.")
-        return self
-    
 class KnowledgeBaseSpec(BaseModel):
     """Schema for a complete knowledge-base."""
     spec_version: SpecVersion = None

ibm_watsonx_orchestrate/agent_builder/tools/base_tool.py

@@ -4,6 +4,7 @@ import yaml
 
 from .types import ToolSpec
 
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 class BaseTool:
     __tool_spec__: ToolSpec
@@ -22,7 +23,7 @@ class BaseTool:
             elif file.endswith('.json'):
                 json.dump(dumped, f, indent=2)
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
 
     def dumps_spec(self) -> str:
         dumped = self.__tool_spec__.model_dump(mode='json', exclude_unset=True, exclude_none=True, by_alias=True)

ibm_watsonx_orchestrate/agent_builder/tools/openapi_tool.py

@@ -3,6 +3,7 @@ import json
 import os.path
 import logging
 from typing import Dict, Any, List
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 import yaml
 import yaml.constructor
@@ -40,7 +41,7 @@ class OpenAPITool(BaseTool):
         BaseTool.__init__(self, spec=spec)
 
         if self.__tool_spec__.binding.openapi is None:
-            raise ValueError('Missing openapi binding')
+            raise BadRequest('Missing openapi binding')
 
     async def __call__(self, **kwargs):
         raise RuntimeError('OpenAPI Tools are only available when deployed onto watson orchestrate or the watson '
@@ -54,10 +55,10 @@ class OpenAPITool(BaseTool):
             elif file.endswith('.json'):
                 spec = ToolSpec.model_validate(json.load(f))
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
 
         if spec.binding.openapi is None or spec.binding.openapi is None:
-            raise ValueError('failed to load python tool as the tool had no openapi binding')
+            raise BadRequest('failed to load python tool as the tool had no openapi binding')
 
         return OpenAPITool(spec=spec)
 
@@ -108,11 +109,11 @@ def create_openapi_json_tool(
     paths = openapi_contents.get('paths', {})
     route = paths.get(http_path)
     if route is None:
-        raise ValueError(f"Path {http_path} not found in paths. Available endpoints are: {list(paths.keys())}")
+        raise BadRequest(f"Path {http_path} not found in paths. Available endpoints are: {list(paths.keys())}")
 
     route_spec = route.get(http_method.lower(), route.get(http_method.upper()))
     if route_spec is None:
-        raise ValueError(
+        raise BadRequest(
             f"Path {http_path} did not have an http_method {http_method}. Available methods are {list(route.keys())}")
 
     operation_id = re.sub( r'(\W|_)+', '_', route_spec.get('operationId') ) \
@@ -121,12 +122,12 @@ def create_openapi_json_tool(
     spec_name = name or operation_id
     spec_permission = permission or _action_to_perm(route_spec.get('x-ibm-operation', {}).get('action'))
     if spec_name is None:
-        raise ValueError(
-            f"No name provided for tool. {http_method}: {http_path} did not specify an operationId, and no name was provided")
+        raise BadRequest(
+            f"Failed to import tool from endpoint {http_method}: {http_path} as no operationId was provided. An operationId must be provided to generate the name of the tool.")
 
     spec_description = description or route_spec.get('description')
     if spec_description is None:
-        raise ValueError(
+        raise BadRequest(
             f"No description provided for tool. {http_method}: {http_path} did not specify a description field, and no description was provided")
 
     spec = ToolSpec(
@@ -199,7 +200,7 @@ def create_openapi_json_tool(
     for needed_security in route_spec.get('security', []) + openapi_spec.get('security', []):
         name = next(iter(needed_security.keys()), None)
         if name is None or name not in security_schemes_map:
-            raise ValueError(f"Invalid openapi spec, {HTTP_METHOD} {http_path} asks for a security scheme of {name}, "
+            raise BadRequest(f"Invalid openapi spec, {HTTP_METHOD} {http_path} asks for a security scheme of {name}, "
                              f"but no such security scheme was configured in the .security section of the spec")
 
         security.append(security_schemes_map[name])
@@ -260,23 +261,23 @@ async def _get_openapi_spec_from_uri(openapi_uri: str) -> Dict[str, Any]:
             elif openapi_uri.endswith('.yaml') or openapi_uri.endswith('.yml'):
                 openapi_contents = yaml_safe_load(fp)
             else:
-                raise ValueError(
+                raise BadRequest(
                     f"Unexpected file extension for file {openapi_uri}, expected one of [.json, .yaml, .yml]")
     elif openapi_uri.endswith('.json'):
         async with httpx.AsyncClient() as client:
             r = await client.get(openapi_uri)
             if r.status_code != 200:
-                raise ValueError(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
+                raise BadRequest(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
             openapi_contents = r.json()
     elif openapi_uri.endswith('.yaml'):
         async with httpx.AsyncClient() as client:
             r = await client.get(openapi_uri)
             if r.status_code != 200:
-                raise ValueError(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
+                raise BadRequest(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
             openapi_contents = yaml_safe_load(r.text)
 
     if openapi_contents is None:
-        raise ValueError(f"Unrecognized path or uri {openapi_uri}")
+        raise BadRequest(f"Unrecognized path or uri {openapi_uri}")
 
     return openapi_contents