ibm-watsonx-orchestrate 1.0.0__tar.gz

ibm_watsonx_orchestrate-1.0.0/.gitignore

@@ -0,0 +1,77 @@
+# Byte-compiled Python files
+*.py[cod]
+__pycache__/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+.env/
+
+# Setuptools
+*.lock
+*.log
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+*.cover
+coverage.*
+.cache
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Editor / IDE-specific files
+.vscode/
+.idea/
+*.swp
+*~
+*.sublime-workspace
+
+# SDK specific
+sdk/python/ibm_watsonx_orchestrate/ibm_watsonx_orchestrate/__pycache__/
+sdk/python/ibm_watsonx_orchestrate/ibm_watsonx_orchestrate/messages/__pycache__/
+sdk/python/ibm_watsonx_orchestrate/ibm_watsonx_orchestrate/_wrappers/__pycache__/
+sdk/python/ibm_watsonx_orchestrate/ibm_watsonx_orchestrate/utils/__pycache__/
+
+# Build scripts
+.DS_Store
+*.bak
+*.tmp
+
+# Ignore local environment and configuration files
+.env
+.env.*
+.idea/
+.vscode/
+coverage/

ibm_watsonx_orchestrate-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2024, 2025 IBM Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ibm_watsonx_orchestrate-1.0.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: ibm-watsonx-orchestrate
+Version: 1.0.0
+Summary: IBM watsonx.orchestrate SDK
+Author-email: IBM <support@ibm.com>
+License: MIT License
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: certifi>=2024.8.30
+Requires-Dist: docstring-parser<1.0,>=0.16
+Requires-Dist: httpx<1.0.0,>=0.28.1
+Requires-Dist: ibm-cloud-sdk-core>=3.22.0
+Requires-Dist: jsonref==1.1.0
+Requires-Dist: jsonschema<5.0.0,>=4.23.0
+Requires-Dist: langchain-community<1.0.0,>=0.3.12
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: packaging>=24.2
+Requires-Dist: pydantic<3.0.0,>=2.10.3
+Requires-Dist: pyjwt<3.0.0,>=2.10.1
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich<14.0.0,>=13.9.4
+Requires-Dist: typer<1.0.0,>=0.15.1
+Requires-Dist: urllib3>=2.2.3
+Provides-Extra: dev
+Requires-Dist: black~=22.3.0; extra == 'dev'
+Requires-Dist: coverage[toml]>=6.5; extra == 'dev'
+Requires-Dist: pylint~=2.16.4; extra == 'dev'
+Requires-Dist: pytest-asyncio==0.25.1; extra == 'dev'
+Requires-Dist: pytest-cov==6.0.0; extra == 'dev'
+Requires-Dist: pytest-mock==3.14.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=8.3.4; extra == 'dev'
+Requires-Dist: snapshottest==1.0.0a1; extra == 'dev'

ibm_watsonx_orchestrate-1.0.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ibm-watsonx-orchestrate"
+dynamic = ["version"]
+
+description = "IBM watsonx.orchestrate SDK"
+authors = [
+    { name = "IBM", email = "support@ibm.com" }
+]
+#readme = { file = "README.md", content-type = 'text/markdown'}
+license = {text = "MIT License"}
+license-files = ["LICENSE"]
+requires-python = ">=3.11, <3.14"
+classifiers = []
+dependencies = [
+    "certifi>=2024.8.30",
+    "docstring-parser>=0.16,<1.0",
+    "httpx>=0.28.1,<1.0.0",
+    "ibm-cloud-sdk-core>=3.22.0",
+    "jsonref==1.1.0",
+    "jsonschema>=4.23.0,<5.0.0",
+    "langchain-community>=0.3.12,<1.0.0",
+    "numpy>=1.26.0",
+    "packaging>=24.2",
+    "pydantic>=2.10.3,<3.0.0",
+    "pyjwt>=2.10.1,<3.0.0",
+    "python-dotenv>=1.0.0",
+    "pyyaml>=6.0.2,<7.0.0",
+    "requests>=2.32.3",
+    "rich>=13.9.4,<14.0.0",
+    "typer>=0.15.1,<1.0.0",
+    "urllib3>=2.2.3"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.4,<9.0.0",
+    "pytest-cov==6.0.0",
+    "snapshottest==1.0.0a1",
+    "pytest-mock==3.14.0",
+    "pytest-asyncio==0.25.1",
+    "coverage[toml]>=6.5",
+    "black~=22.3.0",
+    "pylint~=2.16.4",
+]
+
+[tool.hatch.envs.default]
+dependencies = [
+    "pkg[dev]"
+]
+detached = true
+
+[tool.hatch.version]
+path = "src/ibm_watsonx_orchestrate/__init__.py"
+validate-bump=false
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ibm_watsonx_orchestrate"]
+
+[tool.hatch.build]
+include = [
+    "src/*"
+]
+
+[project.scripts]
+orchestrate = "ibm_watsonx_orchestrate.cli.main:app"
+
+[tool.hatch.envs.default.scripts]
+test = "pytest {args:tests}"
+test-cov = "coverage run -m pytest {args:tests}"
+cov-report = [
+  "- coverage combine",
+  "coverage report",
+]
+cov = [
+  "test-cov",
+  "cov-report",
+]
+
+[tool.coverage.run]
+omit = [
+  "*/__init__.py",
+  "tests/*"
+]
+
+[tool.hatch.envs.test]
+dependencies = [
+    "pkg[dev]"
+]
+
+[[tool.hatch.envs.test.matrix]]
+python = ["3.11", "3.12", "3.13"]
+
+[tool.coverage.report]
+show_missing=true
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/__init__.py

@@ -0,0 +1,28 @@
+#  -----------------------------------------------------------------------------------------
+#  (C) Copyright IBM Corp. 2023-2024.
+#  https://opensource.org/licenses/BSD-3-Clause
+#  -----------------------------------------------------------------------------------------
+
+pkg_name = "ibm-watsonx-orchestrate"
+
+__version__ = "1.0.0"
+
+
+
+try:
+    from importlib.metadata import version
+
+    ver = version(pkg_name)
+
+except (ModuleNotFoundError, AttributeError):
+    from importlib_metadata import version as imp_lib_ver
+
+    ver = imp_lib_ver(pkg_name)
+
+from ibm_watsonx_orchestrate.client.client import Client
+from ibm_watsonx_orchestrate.utils.logging.logger import setup_logging
+
+Client.version = ver
+__version__ = ver
+setup_logging()
+

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/agents/__init__.py

@@ -0,0 +1,5 @@
+from .agent import Agent, AgentSpec
+from .external_agent import ExternalAgent, ExternalAgentSpec
+from .assistant_agent import AssistantAgent, AssistantAgentSpec
+# from .types import AgentKind, AgentStyle, ExternalAgentConfig, AssistantAgentConfig, SpecVersion
+from .types import AgentKind, AgentStyle, SpecVersion, ExternalAgentAuthScheme, AgentProvider, AssistantAgentConfig

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/agents/agent.py

@@ -0,0 +1,27 @@
+import json
+from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
+from .types import AgentSpec
+
+
+class Agent(AgentSpec):
+
+    @staticmethod
+    def from_spec(file: str) -> 'Agent':
+        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")
+            agent = Agent.model_validate(content)
+
+        return agent
+    
+    def __repr__(self):
+        return f"Agent(name='{self.name}', description='{self.description}')"
+
+    def __str__(self):
+        return self.__repr__()

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/agents/assistant_agent.py

@@ -0,0 +1,28 @@
+import json
+from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
+from .types import AssistantAgentSpec
+
+
+class AssistantAgent(AssistantAgentSpec):
+
+    @staticmethod
+    def from_spec(file: str) -> 'AssistantAgent':
+        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")
+            agent = AssistantAgent.model_validate(content)
+
+        return agent
+    
+    def __repr__(self):
+        return f"AssistantAgent(name='{self.name}', description='{self.description}')"
+
+    def __str__(self):
+        return self.__repr__()

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/agents/external_agent.py

@@ -0,0 +1,28 @@
+import json
+from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
+from .types import ExternalAgentSpec
+
+
+class ExternalAgent(ExternalAgentSpec):
+
+    @staticmethod
+    def from_spec(file: str) -> 'ExternalAgent':
+        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")
+            agent = ExternalAgent.model_validate(content)
+
+        return agent
+    
+    def __repr__(self):
+        return f"ExternalAgent(name='{self.name}', description='{self.description}')"
+
+    def __str__(self):
+        return self.__repr__()

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/agents/types.py

@@ -0,0 +1,204 @@
+import json
+import yaml
+from enum import Enum
+from typing import List, Optional, Dict
+from pydantic import BaseModel, model_validator, ConfigDict
+from ibm_watsonx_orchestrate.agent_builder.tools import BaseTool
+from ibm_watsonx_orchestrate.agent_builder.knowledge_bases.types import KnowledgeBaseSpec
+from pydantic import Field, AliasChoices
+from typing import Annotated
+
+# 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"
+
+class SpecVersion(str, Enum):
+    V1 = "v1"
+
+
+class AgentKind(str, Enum):
+    NATIVE = "native"
+    EXTERNAL = "external"
+    ASSISTANT = "assistant"
+
+class ExternalAgentAuthScheme(str, Enum):
+    BEARER_TOKEN = 'BEARER_TOKEN'
+    API_KEY = "API_KEY"
+    NONE = 'NONE'
+
+class AgentProvider(str, Enum):
+    WXAI = "wx.ai"
+    EXT_CHAT = "external_chat"
+    SALESFORCE = "salesforce"
+    WATSONX = "watsonx" #provider type returned from an assistant agent
+
+
+class AssistantAgentAuthType(str, Enum):
+    ICP_IAM = "ICP_IAM"
+    IBM_CLOUD_IAM = "IBM_CLOUD_IAM"
+    MCSP = "MCSP"
+    BEARER_TOKEN = "BEARER_TOKEN"
+    HIDDEN = "<hidden>"
+
+
+class BaseAgentSpec(BaseModel):
+    spec_version: SpecVersion = None
+    kind: AgentKind
+    id: Optional[Annotated[str, Field(json_schema_extra={"min_length_str": 1})]] = None
+    name: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+    description: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+
+    def dump_spec(self, file: str) -> None:
+        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)
+            elif file.endswith('.json'):
+                json.dump(dumped, f, indent=2)
+            else:
+                raise ValueError('file must end in .json, .yaml, or .yml')
+
+    def dumps_spec(self) -> str:
+        dumped = self.model_dump(mode='json', exclude_none=True)
+        return json.dumps(dumped, indent=2)
+
+# ===============================
+#      NATIVE AGENT TYPES
+# ===============================
+
+class AgentStyle(str, Enum):
+    DEFAULT = "default"
+    REACT = "react"
+
+class AgentSpec(BaseAgentSpec):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    kind: AgentKind = AgentKind.NATIVE
+    llm: str = DEFAULT_LLM
+    style: AgentStyle = AgentStyle.DEFAULT
+    instructions: Annotated[Optional[str], Field(json_schema_extra={"min_length_str":1})] = None
+    collaborators: Optional[List[str]] | Optional[List['BaseAgentSpec']] = []
+    tools: Optional[List[str]] | Optional[List['BaseTool']] = []
+    hidden: bool = False
+    knowledge_base: Optional[List[str]] | Optional[List['KnowledgeBaseSpec']] = []
+
+
+    def __init__(self, *args, **kwargs):
+        if "tools" in kwargs and kwargs["tools"]:
+            kwargs["tools"] = [x.__tool_spec__.name if isinstance(x, BaseTool) else x for x in kwargs["tools"]]
+        if "collaborators" in kwargs and kwargs["collaborators"]:
+            kwargs["collaborators"] = [x.name if isinstance(x, BaseAgentSpec) else x for x in kwargs["collaborators"]]
+        super().__init__(*args, **kwargs)
+
+    @model_validator(mode="before")
+    def validate_fields(cls, values):
+        return validate_agent_fields(values)
+    
+    @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.")
+        return self
+
+def validate_agent_fields(values: dict) -> dict:
+    # Check for empty strings or whitespace
+    for field in ["id", "name", "kind", "description", "collaborators", "tools"]:
+        value = values.get(field)
+        if value and not str(value).strip():
+            raise ValueError(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")
+
+
+    return values
+
+# ===============================
+#      EXTERNAL AGENT TYPES
+# ===============================
+
+class ExternalAgentConfig(BaseModel):
+    hidden: bool = False
+    enable_cot: bool = False
+
+class ExternalAgentSpec(BaseAgentSpec):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    kind: AgentKind = AgentKind.EXTERNAL
+    title: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+    tags: Optional[List[str]] = None
+    api_url: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+    auth_scheme: ExternalAgentAuthScheme = ExternalAgentAuthScheme.NONE
+    auth_config: dict = {}
+    provider: AgentProvider = AgentProvider.EXT_CHAT
+    chat_params: dict = None
+    config: ExternalAgentConfig = ExternalAgentConfig()
+    nickname: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    app_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    connection_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+
+    @model_validator(mode="before")
+    def validate_fields_for_external(cls, values):
+        return validate_external_agent_fields(values)
+
+    @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.")
+        return self
+
+def validate_external_agent_fields(values: dict) -> dict:
+    # Check for empty strings or whitespace
+    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")
+
+    return values
+
+# # ===============================
+# #      ASSISTANT AGENT TYPES
+# # ===============================
+
+class AssistantAgentConfig(BaseModel):
+    api_version: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    assistant_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    crn: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    service_instance_url: Annotated[str | None, Field(validation_alias=AliasChoices('instance_url', 'service_instance_url'), serialization_alias='service_instance_url')] = None
+    environment_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    auth_type: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    connection_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    api_key: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    authorization_url: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    auth_type: AssistantAgentAuthType = AssistantAgentAuthType.MCSP
+
+class AssistantAgentSpec(BaseAgentSpec):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    kind: AgentKind = AgentKind.ASSISTANT
+    title: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+    tags: Optional[List[str]] = None
+    config: AssistantAgentConfig = AssistantAgentConfig()
+    nickname: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+    connection_id: Annotated[str | None, Field(json_schema_extra={"min_length_str":1})] = None
+
+    @model_validator(mode="before")
+    def validate_fields_for_external(cls, values):
+        return validate_assistant_agent_fields(values)
+
+    @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.")
+        return self
+
+def validate_assistant_agent_fields(values: dict) -> dict:
+    # Check for empty strings or whitespace
+    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")
+
+    return values

ibm_watsonx_orchestrate-1.0.0/src/ibm_watsonx_orchestrate/agent_builder/connections/__init__.py

@@ -0,0 +1,27 @@
+from .connections import (
+    get_application_connection_credentials,
+    get_connection_type
+)
+from .types import (
+    ConnectionType,
+    ConnectionKind,
+    ConnectionAuthType,
+    ConnectionConfiguration,
+    ConnectionEnvironment,
+    ConnectionPreference,
+    ConnectionSecurityScheme,
+    CREDENTIALS,
+    BasicAuthCredentials,
+    BearerTokenAuthCredentials,
+    APIKeyAuthCredentials,
+    OAuth2TokenCredentials,
+    # OAuth2AuthCodeCredentials,
+    # OAuth2ClientCredentials,
+    # OAuth2ImplicitCredentials,
+    # OAuth2PasswordCredentials,
+    OAuthOnBehalfOfCredentials,
+    KeyValueConnectionCredentials,
+    CONNECTION_KIND_SCHEME_MAPPING,
+    CONNECTION_TYPE_CREDENTIAL_MAPPING,
+    ExpectedCredentials
+)