ibm-watsonx-orchestrate 1.10.2__py3-none-any.whl → 1.11.0b1__py3-none-any.whl

ibm_watsonx_orchestrate/client/base_api_client.py

@@ -1,9 +1,22 @@
 import json
-
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 import requests
 from abc import ABC, abstractmethod
 from ibm_cloud_sdk_core.authenticators import MCSPAuthenticator
 from typing_extensions import List
+from contextlib import contextmanager
+
+@contextmanager
+def ssl_handler():
+    try:
+        yield
+    except requests.exceptions.SSLError as e:
+        error_message = str(e)
+        if "self-signed certificate in certificate chain" in error_message:
+            reason = "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain"
+        else:
+            reason = error_message
+        raise BadRequest(f"SSL handshake failed for request '{e.request.path_url}'. Reason: '{reason}'")
 
 
 class ClientAPIException(requests.HTTPError):
@@ -50,7 +63,8 @@ class BaseAPIClient:
 
     def _get(self, path: str, params: dict = None, data=None, return_raw=False) -> dict:
         url = f"{self.base_url}{path}"
-        response = requests.get(url, headers=self._get_headers(), params=params, data=data, verify=self.verify)
+        with ssl_handler():
+            response = requests.get(url, headers=self._get_headers(), params=params, data=data, verify=self.verify)
         self._check_response(response)
         if not return_raw:
             return response.json()
@@ -59,13 +73,15 @@ class BaseAPIClient:
 
     def _post(self, path: str, data: dict = None, files: dict = None) -> dict:
         url = f"{self.base_url}{path}"
-        response = requests.post(url, headers=self._get_headers(), json=data, files=files, verify=self.verify)
+        with ssl_handler():
+            response = requests.post(url, headers=self._get_headers(), json=data, files=files, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
     
     def _post_nd_json(self, path: str, data: dict = None, files: dict = None) -> List[dict]:
         url = f"{self.base_url}{path}"
-        response = requests.post(url, headers=self._get_headers(), json=data, files=files)
+        with ssl_handler():
+            response = requests.post(url, headers=self._get_headers(), json=data, files=files)
         self._check_response(response)
 
         res = []
@@ -76,33 +92,38 @@ class BaseAPIClient:
     
     def _post_form_data(self, path: str, data: dict = None, files: dict = None) -> dict:
         url = f"{self.base_url}{path}"
-        # Use data argument instead of json so data is encoded as application/x-www-form-urlencoded
-        response = requests.post(url, headers=self._get_headers(), data=data, files=files, verify=self.verify)
+        with ssl_handler():
+            # Use data argument instead of json so data is encoded as application/x-www-form-urlencoded
+            response = requests.post(url, headers=self._get_headers(), data=data, files=files, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
 
     def _put(self, path: str, data: dict = None) -> dict:
 
         url = f"{self.base_url}{path}"
-        response = requests.put(url, headers=self._get_headers(), json=data, verify=self.verify)
+        with ssl_handler():
+            response = requests.put(url, headers=self._get_headers(), json=data, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
 
     def _patch(self, path: str, data: dict = None) -> dict:
         url = f"{self.base_url}{path}"
-        response = requests.patch(url, headers=self._get_headers(), json=data, verify=self.verify)
+        with ssl_handler():
+            response = requests.patch(url, headers=self._get_headers(), json=data, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
     
     def _patch_form_data(self, path: str, data: dict = None, files = None) -> dict:
         url = f"{self.base_url}{path}"
-        response = requests.patch(url, headers=self._get_headers(), data=data, files=files, verify=self.verify)
+        with ssl_handler():
+            response = requests.patch(url, headers=self._get_headers(), data=data, files=files, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
 
     def _delete(self, path: str, data=None) -> dict:
         url = f"{self.base_url}{path}"
-        response = requests.delete(url, headers=self._get_headers(), json=data, verify=self.verify)
+        with ssl_handler():
+            response = requests.delete(url, headers=self._get_headers(), json=data, verify=self.verify)
         self._check_response(response)
         return response.json() if response.text else {}
 

ibm_watsonx_orchestrate/client/connections/connections_client.py

@@ -177,3 +177,17 @@ class ConnectionsClient(BaseAPIClient):
                 logger.warning(f"Connections not found. Returning connection ID: {conn_id}")
                 return conn_id
             raise e
+
+    def get_drafts_by_ids(self, conn_ids) -> List[ListConfigsResponse]:
+        try:
+            res = self._get(f"/connections/applications?connectionIds={','.join(conn_ids)}")
+            import json
+            json.dumps(res)
+            return [ListConfigsResponse.model_validate(conn) for conn in res.get("applications", [])]
+        except ValidationError as e:
+            logger.error("Recieved unexpected response from server")
+            raise e
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                return []
+            raise e

ibm_watsonx_orchestrate/client/service_instance.py

@@ -10,7 +10,7 @@ from ibm_cloud_sdk_core.authenticators import MCSPV2Authenticator
 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
 from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator
 
-from ibm_watsonx_orchestrate.client.utils import check_token_validity, is_cpd_env
+from ibm_watsonx_orchestrate.client.utils import check_token_validity, is_cpd_env, is_ibm_cloud_platform
 from ibm_watsonx_orchestrate.client.base_service_instance import BaseServiceInstance
 from ibm_watsonx_orchestrate.cli.commands.environment.types import EnvironmentAuthType
 
@@ -21,14 +21,6 @@ from ibm_watsonx_orchestrate.client.client_errors import (
 import logging
 logger = logging.getLogger(__name__)
 
-from ibm_watsonx_orchestrate.cli.config import (
-    Config,
-    CONTEXT_SECTION_HEADER,
-    CONTEXT_ACTIVE_ENV_OPT,
-    ENVIRONMENTS_SECTION_HEADER,
-    ENV_WXO_URL_OPT
-)
-
 class ServiceInstance(BaseServiceInstance):
     """Connect, get details, and check usage of a Watson Machine Learning service instance."""
 
@@ -50,29 +42,28 @@ class ServiceInstance(BaseServiceInstance):
         return self._client.token
     
     def _create_token(self) -> str:
-        if not self._credentials.auth_type:
-            if ".cloud.ibm.com" in self._credentials.url:
-                logger.warning("Using IBM IAM Auth Type. If this is incorrect please use the '--type' flag to explicitly choose one of 'mcsp', 'mcsp_v1', 'mcsp_v2' or 'cpd' ")
-                return self._authenticate(EnvironmentAuthType.IBM_CLOUD_IAM)
-            elif is_cpd_env(self._credentials.url):
-                logger.warning("Using CPD Auth Type. If this is incorrect please use the '--type' flag to explicitly choose one of 'ibm_iam', 'mcsp', 'mcsp_v1' or 'mcsp_v2' ")
-                return self._authenticate(EnvironmentAuthType.CPD)
-            else:
-                logger.warning("Using MCSP Auth Type. If this is incorrect please use the '--type' flag to explicitly choose one of 'ibm_iam', 'mcsp_v1', 'mcsp_v2' or 'cpd' ")
-                try:
-                    return self._authenticate(EnvironmentAuthType.MCSP_V1)
-                except:
-                    return self._authenticate(EnvironmentAuthType.MCSP_V2)
-        auth_type = self._credentials.auth_type.lower()
+        inferred_auth_type = None
+        if is_ibm_cloud_platform(self._credentials.url):
+            inferred_auth_type = EnvironmentAuthType.IBM_CLOUD_IAM
+        elif is_cpd_env(self._credentials.url):
+            inferred_auth_type = EnvironmentAuthType.CPD
+        else:
+            inferred_auth_type = EnvironmentAuthType.MCSP
+        
+        if self._credentials.auth_type:
+            if self._credentials.auth_type != inferred_auth_type:
+                logger.warning(f"Overriding the default authentication type '{inferred_auth_type}' for url '{self._credentials.url}' with '{self._credentials.auth_type.lower()}'")
+            auth_type = self._credentials.auth_type.lower()
+        else:
+            inferred_type_options = [t for t in EnvironmentAuthType if t != inferred_auth_type]
+            logger.warning(f"Using '{inferred_auth_type}' Auth Type. If this is incorrect please use the '--type' flag to explicitly choose one of {', '.join(inferred_type_options[:-1])} or {inferred_type_options[-1]}")
+            auth_type = inferred_auth_type
+        
         if auth_type == "mcsp":
             try:
                 return self._authenticate(EnvironmentAuthType.MCSP_V1)
             except:
                 return self._authenticate(EnvironmentAuthType.MCSP_V2)
-        elif auth_type == "mcsp_v1":
-            return self._authenticate(EnvironmentAuthType.MCSP_V1)
-        elif auth_type == "mcsp_v2":
-            return self._authenticate(EnvironmentAuthType.MCSP_V2)
         else:
             return self._authenticate(auth_type)
 
@@ -100,13 +91,7 @@ class ServiceInstance(BaseServiceInstance):
                     if self._credentials.iam_url is not None: 
                         url = self._credentials.iam_url
                     else: 
-                        cfg = Config()
-                        env_cfg = cfg.get(ENVIRONMENTS_SECTION_HEADER)
-                        matching_wxo_url = next(
-                            (env_config['wxo_url'] for env_config in env_cfg.values() if 'bypass_ssl' in env_config and 'verify' in env_config),
-                            None
-                        )
-                        base_url = matching_wxo_url.split("/orchestrate")[0]
+                        base_url = self._credentials.url.split("/orchestrate")[0]
                         url = f"{base_url}/icp4d-api"
 
                     password = self._credentials.password if self._credentials.password is not None else None

ibm_watsonx_orchestrate/client/utils.py

@@ -66,7 +66,7 @@ def is_ibm_cloud_platform(url:str | None = None) -> bool:
     if url is None:
         url = get_current_env_url()
 
-    if url.__contains__("cloud.ibm.com"):
+    if ".cloud.ibm.com" in url:
         return True
     return False
 
@@ -161,6 +161,8 @@ def instantiate_client(client: type[T] , url: str | None=None) -> T:
                     client_instance = client(base_url=url, api_key=token, is_local=is_local_dev(url), verify=False)
                 elif verify is not None:
                     client_instance = client(base_url=url, api_key=token, is_local=is_local_dev(url), verify=verify)
+                else:
+                    client_instance = client(base_url=url, api_key=token, is_local=is_local_dev(url))
             else:
                 client_instance = client(base_url=url, api_key=token, is_local=is_local_dev(url))
 

ibm_watsonx_orchestrate/docker/compose-lite.yml

@@ -62,6 +62,7 @@ services:
       WATSONX_API_KEY: ${WATSONX_APIKEY}
       WATSONX_URL: ${WATSONX_URL}
       WATSONX_SPACE_ID: ${WATSONX_SPACE_ID}
+      NODE_TLS_REJECT_UNAUTHORIZED: ${AI_GATEWAY_TLS_REJECT_UNAUTHORIZED}
 
   wxo-agent-gateway:
     image: ${AGENT_GATEWAY_REGISTRY:-us.icr.io/watson-orchestrate-private}/wxo-agent-gateway:${AGENT_GATEWAY_TAG:-latest}
@@ -132,7 +133,7 @@ services:
       DOCPROC_ENABLED: ${DOCPROC_ENABLED:-false}
       IS_OBSERVABILITY_FEATURE_ENABLED: "true"
       ALLOW_INSECURE_TLS: "true"
-      ENABLE_EDIT_PROMPTS: "true"
+      ENABLE_EDIT_PROMPTS: "false"
       LANGFLOW_ENABLED: ${LANGFLOW_ENABLED:-false}
     command: 'npm start'
     ports:
@@ -327,6 +328,7 @@ services:
       ENABLE_WEBHOOKS: false
       DISABLE_JSON_LOG_CELERY: true
       WXO_DEPLOYMENT_PLATFORM: saas
+      CPD_VERIFY: ${CPD_VERIFY}
       CONNECTION_MANAGER_URL: http://wxo-server-connection-manager:3001
       CHANNEL_SESSION_REDIS_URL: redis://wxo-server-redis:6379/5
       WXO_MILVUS_URI: http://wxo-milvus-standalone:19530
@@ -376,6 +378,7 @@ services:
       IS_WXO_LITE: "TRUE"
       TRM_BASE_URL: http://tools-runtime-manager:8080
       AGENT_STEP_DETAILS: redis://wxo-server-redis:6379/0
+      RECURSION_LIMIT: ${RECURSION_LIMIT}
       AGENT_GATEWAY_URI: http://wxo-agent-gateway:8989
       JWT_SECRET: ${JWT_SECRET}
       POSTGRES_URL: postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@wxo-server-db:5432/postgres
@@ -446,6 +449,7 @@ services:
       IBM_TELEMETRY_TRACER_ENDPOINT: http://jaeger:4318/v1/traces
       USE_IBM_TELEMETRY: ${USE_IBM_TELEMETRY:-false}
       WXO_DEPLOYMENT_PLATFORM: saas
+      CPD_VERIFY: ${CPD_VERIFY}
       CALLBACK_HOST_URL: ${CALLBACK_HOST_URL:-http://wxo-server:4321}
       LANGFLOW_ENABLED: ${LANGFLOW_ENABLED:-false}
   
@@ -653,6 +657,7 @@ services:
       - WATSONX_URL=${WATSONX_URL}
       - PROXY_SERVER_URL=http://jaeger-proxy:9201
       - WXO_DEPLOYMENT_PLATFORM=saas
+      - CPD_VERIFY=${CPD_VERIFY}      
       - TENANT_API_KEY=${AGENTOPS_API_KEY}
       - TENANT_CONFIG_URL=http://wxo-server:4321
       - TENANT_DEFAULT_USERNAME=${ES_USERNAME}

ibm_watsonx_orchestrate/docker/default.env

@@ -36,7 +36,7 @@ DB_ENCRYPTION_KEY=dummy_db_encryption_key
 BASE_URL=dummy_base_url
 SERVER_TYPE=CELERY
 SQLALCHEMY_DEBUG=false
-
+RECURSION_LIMIT=50
 LANGFUSE_HOST=http://host.docker.internal:3010
 LANGFUSE_EMAIL=orchestrate@ibm.com
 LANGFUSE_USERNAME=orchestrate
@@ -58,10 +58,10 @@ REGISTRY_URL=
 
 
 
-SERVER_TAG=29-08-2025-59ef405
+SERVER_TAG=05-09-2025-Hb2zH5Ggf
 SERVER_REGISTRY=
 
-WORKER_TAG=29-08-2025-cf32b2d
+WORKER_TAG=05-09-2025-Hb2zH5Ggf
 WORKER_REGISTRY=
 
 AI_GATEWAY_TAG=20-08-2025-9ed6d40
@@ -73,9 +73,9 @@ AGENT_GATEWAY_REGISTRY=
 DB_REGISTRY=
 # If you build multiarch set all three of these to the same, we have a pr against main
 # to not have this separation, but we can merge it later
-DBTAG=29-07-2025-9f3661b
-AMDDBTAG=29-07-2025-9f3661b
-ARM64DBTAG=29-07-2025-9f3661b
+DBTAG=04-09-2025-48c39
+AMDDBTAG=04-09-2025-48c39
+ARM64DBTAG=04-09-2025-48c39
 
 UI_REGISTRY=
 UITAG=29-08-2025
@@ -92,7 +92,7 @@ TR_REGISTRY=
 BUILDER_TAG=27-08-2025-7432aca
 BUILDER_REGISTRY=
 
-FLOW_RUNTIME_TAG=18-08-2025-v3
+FLOW_RUNTIME_TAG=26-08-2025-3b7f19e
 FLOW_RUMTIME_REGISTRY=
 
 
@@ -105,7 +105,7 @@ JAEGER_PROXY_REGISTRY=
 SOCKET_HANDLER_TAG=29-05-2025
 SOCKET_HANDLER_REGISTRY=
 
-CPE_TAG=18-08-2025-ae1308e
+CPE_TAG=29-08-2025-e612bea
 CPE_REGISTRY=
 
 VOICE_CONTROLLER_TAG=12-08-2025
@@ -118,14 +118,16 @@ LANGFLOW_IMAGE=
 WDU_TAG=2.6.1
 WDU_REGISTRY=
 
-DOCPROC_DPS_TAG=20250815-010747-277-173db2a
-DOCPROC_LLMSERVICE_TAG=20250820-153924-128-55cf4d5
+DOCPROC_DPS_TAG=20250826-201302-283-24eb106
+DOCPROC_LLMSERVICE_TAG=20250826-main-133-42a5320
 DOCPROC_CACHE_TAG=20250814-master-82-cf33f87
-DOCPROC_DPI_TAG=20250815-004755-273-e65f26b4
+DOCPROC_DPI_TAG=20250828-154151-285-e4dd1cff
 DOCPROC_REGISTRY=
 
 # END -- IMAGE REGISTRIES AND TAGS
 
+CPD_VERIFY=true
+AI_GATEWAY_TLS_REJECT_UNAUTHORIZED=1
 TAVILY_API_KEY=dummy_tavily_api_key
 PREFERRED_MODELS=meta-llama/llama-3-2-90b-vision-instruct,meta-llama/llama-3-405b-instruct
 INCOMPATIBLE_MODELS=flan,embedding,cross-encoder,tinytimemixers

ibm_watsonx_orchestrate/flow_builder/data_map.py

@@ -12,7 +12,10 @@ class DataMap(BaseModel):
     def to_json(self) -> dict[str, Any]:
         model_spec = {}
         if self.maps and len(self.maps) > 0:
-            model_spec["maps"] = [assignment.model_dump() for assignment in self.maps]
+            model_spec["maps"] = []
+            for assignment in self.maps:
+                model_spec["maps"].append(assignment.model_dump())
+        return model_spec
 
     def add(self, line: Assignment) -> Self:
         self.maps.append(line)

ibm_watsonx_orchestrate/flow_builder/flows/flow.py

@@ -25,7 +25,7 @@ from ibm_watsonx_orchestrate.client.tools.tool_client import ToolClient
 from ibm_watsonx_orchestrate.client.tools.tempus_client import TempusClient
 from ibm_watsonx_orchestrate.client.utils import instantiate_client
 from ..types import (
-    DocProcKVPSchema, EndNodeSpec, Expression, ForeachPolicy, ForeachSpec, LoopSpec, BranchNodeSpec, MatchPolicy, PlainTextReadingOrder, PromptLLMParameters, PromptNodeSpec, TimerNodeSpec,
+    DocProcKVPSchema, Assignment, Conditions, EndNodeSpec, Expression, ForeachPolicy, ForeachSpec, LoopSpec, BranchNodeSpec, MatchPolicy, NodeIdCondition, PlainTextReadingOrder, PromptExample, PromptLLMParameters, PromptNodeSpec, TimerNodeSpec,
     StartNodeSpec, ToolSpec, JsonSchemaObject, ToolRequestBody, ToolResponseBody, UserFieldKind, UserFieldOption, UserFlowSpec, UserNodeSpec, WaitPolicy,
     DocProcSpec, TextExtractionResponse, DocProcInput, DecisionsNodeSpec, DecisionsRule, DocExtSpec, File, DocumentClassificationResponse, DocClassifierSpec, DocumentProcessingCommonInput
 )
@@ -64,7 +64,7 @@ class FlowEdge(BaseModel):
 
 class Flow(Node):
     '''Flow represents a flow that will be run by wxO Flow engine.'''
-    output_map: DataMap | None = None
+    output_map: dict[str, DataMap] | None = None
     nodes: dict[str, SerializeAsAny[Node]] = {}
     edges: List[FlowEdge] = []
     schemas: dict[str, JsonSchemaObject] = {}
@@ -401,6 +401,7 @@ class Flow(Node):
             display_name: str|None=None,
             system_prompt: str | list[str] | None = None,
             user_prompt: str | list[str] | None = None,
+            prompt_examples: list[PromptExample] | None = None,
             llm: str | None = None,
             llm_parameters: PromptLLMParameters | None = None,
             description: str | None = None,
@@ -422,6 +423,7 @@ class Flow(Node):
             description=description,
             system_prompt=system_prompt,
             user_prompt=user_prompt,
+            prompt_examples=prompt_examples,
             llm=llm,
             llm_parameters=llm_parameters,
             input_schema=_get_tool_request_body(input_schema_obj),
@@ -438,7 +440,7 @@ class Flow(Node):
         node = self._add_node(node)
         return cast(PromptNode, node)
     
-    def docclassfier(self, 
+    def docclassifier(self, 
             name: str, 
             llm : str = "watsonx/meta-llama/llama-3-2-90b-vision-instruct",
             version: str = "TIP",
@@ -605,6 +607,7 @@ class Flow(Node):
             display_name: str|None=None,
             description: str | None = None,
             input_map: DataMap = None,
+            document_structure: bool = False,
             kvp_schemas: list[DocProcKVPSchema] = None,
             enable_hw: bool = False) -> DocProcNode:
 
@@ -629,6 +632,7 @@ class Flow(Node):
             output_schema=_get_tool_response_body(output_schema_obj),
             output_schema_object = output_schema_obj,
             task=task,
+            document_structure=document_structure,
             plain_text_reading_order=plain_text_reading_order,
             enable_hw=enable_hw,
             kvp_schemas=kvp_schemas
@@ -721,7 +725,7 @@ class Flow(Node):
         '''Create a single node flow with an automatic START and END node.'''
         return self.sequence(START, node, END)
 
-    def branch(self, evaluator: Union[Callable, Expression]) -> "Branch":
+    def branch(self, evaluator: Union[Callable, Expression, Conditions]) -> 'Branch':
         '''Create a BRANCH node'''
         e = evaluator
         if isinstance(evaluator, Callable):
@@ -735,11 +739,19 @@ class Flow(Node):
             # e = new_script_spec
         elif isinstance(evaluator, str):
             e = Expression(expression=evaluator)
+        elif isinstance(evaluator, list):
+            e = Conditions(conditions=evaluator)
 
         spec = BranchNodeSpec(name = "branch_" + str(self._next_sequence_id()), evaluator=e)
         branch_node = Branch(spec = spec, containing_flow=self)
         return cast(Branch, self._add_node(branch_node))
     
+    def conditions(self) -> 'Branch':
+        '''Create a Branch node with empty Conditions evaluator (if-else)'''
+        spec = BranchNodeSpec(name = "branch_" + str(self._next_sequence_id()), evaluator=Conditions(conditions=[]))
+        branch_conditions_node = Branch(spec = spec, containing_flow=self)
+        return cast(Branch, self._add_node(branch_conditions_node))
+    
     def wait_for(self, *args) -> "Wait":
         '''Wait for all incoming nodes to complete.'''
         raise ValueError("Not implemented yet.")
@@ -754,6 +766,77 @@ class Flow(Node):
             
         # return cast(Wait, self.node(wait_node))
             
+    def map_flow_output_with_variable(self, target_output_variable: str, variable: str, default_value: str = None) -> Self:
+        if self.output_map and "spec" in self.output_map:
+            maps = self.output_map["spec"].maps or []
+        else:
+            maps = []
+        
+        curr_map_metadata = {
+            "assignmentType": "variable"
+        }
+
+        target_variable = "flow.output." + target_output_variable
+        value_expression = "flow." + variable
+
+        if default_value:
+            maps.append(Assignment(target_variable=target_variable, value_expression=value_expression, default_value=default_value, metadata=curr_map_metadata))
+        else:
+            maps.append(Assignment(target_variable=target_variable, value_expression=value_expression, metadata=curr_map_metadata))
+
+        flow_output_map_spec = DataMap(maps=maps)
+
+        if self.output_map and "spec" in self.output_map:
+            self.output_map["spec"] = flow_output_map_spec
+        else:
+            self.output_map = {"spec": flow_output_map_spec}
+        return self
+    
+    def map_output(self, output_variable: str, expression: str, default_value: str = None) -> Self:
+        if self.output_map and "spec" in self.output_map:
+            maps = self.output_map["spec"].maps or []
+        else:
+            maps = []
+        
+        curr_map_metadata = {
+            "assignmentType": "pyExpression"
+        }
+
+        target_variable = "flow.output." + output_variable
+        value_expression = expression
+
+        if default_value:
+            maps.append(Assignment(target_variable=target_variable, value_expression=value_expression, default_value=default_value, metadata=curr_map_metadata))
+        else:
+            maps.append(Assignment(target_variable=target_variable, value_expression=value_expression, metadata=curr_map_metadata))
+
+        flow_output_map_spec = DataMap(maps=maps)
+
+        if self.output_map and "spec" in self.output_map:
+            self.output_map["spec"] = flow_output_map_spec
+        else:
+            self.output_map = {"spec": flow_output_map_spec}
+        return self
+    
+    def map_flow_output_with_none(self, target_output_variable: str) -> Self:
+        if self.output_map and "spec" in self.output_map:
+            maps = self.output_map["spec"].maps or []
+        else:
+            maps = []
+        
+
+        target_variable = "flow.output." + target_output_variable
+
+        maps.append(Assignment(target_variable=target_variable, value_expression=None))
+
+        flow_output_map_spec = DataMap(maps=maps)
+
+        if self.output_map and "spec" in self.output_map:
+            self.output_map["spec"] = flow_output_map_spec
+        else:
+            self.output_map = {"spec": flow_output_map_spec}
+        return self
+
 
     def foreach(self, item_schema: type[BaseModel],
                 input_schema: type[BaseModel] |None=None,
@@ -814,8 +897,6 @@ class Flow(Node):
                  input_schema: type[BaseModel] |None=None,
                  output_schema: type[BaseModel] |None=None) -> "UserFlow": # return a UserFlow object
 
-        raise ValueError("userflow is NOT supported yet and it's interface will change.")
-
         output_schema_obj = _get_json_schema_obj("output", output_schema)
         input_schema_obj = _get_json_schema_obj("input", input_schema)
 
@@ -917,6 +998,11 @@ class Flow(Node):
         for key, value in self.metadata.items():
             metadata_dict[key] = value
         flow_dict["metadata"] = metadata_dict
+
+        if self.output_map and "spec" in self.output_map:
+            flow_dict["output_map"] = {
+                "spec": self.output_map["spec"].to_json()
+            }
         return flow_dict
 
     def _get_node_id(self, node: Union[str, Node]) -> str:
@@ -1226,6 +1312,27 @@ class Branch(FlowControl):
             raise ValueError("Cannot have custom label __default__. Use default() instead.")
 
         return self._add_case(label, node)
+    
+    def condition(self, to_node: Node, expression: str="", default: bool=False) -> Self:
+        '''
+        Add a condition to this branch node. 
+
+        Parameters:
+        expression (str): The expression of this condition.
+        to_node (Node): The node to go to when expression is evaluated to true.
+        default (bool): The condition is the default (else) case.
+        '''
+
+        node_id = self.containing_flow._get_node_id(to_node)
+        if default:
+            condition = NodeIdCondition(node_id=node_id, default=default)
+        else:
+            condition = NodeIdCondition(expression=expression, node_id=node_id, default=default)
+
+        self.spec.evaluator.conditions.append(condition)
+        self.containing_flow.edge(self, to_node)
+
+        return self
 
     def default(self, node: Node) -> Self:
         '''
@@ -1445,13 +1552,14 @@ class UserFlow(Flow):
               kind: UserFieldKind = UserFieldKind.Text,
               display_name: str | None = None,
               description: str | None = None,
+              direction: str | None = None,
               default: Any | None = None,
               text: str = None, # The text used to ask question to the user, e.g. 'what is your name?'
               option: UserFieldOption | None = None,
               is_list: bool = False,
               min: Any | None = None,
               max: Any | None = None,
-              input_map: DataMap = None,
+              input_map: DataMap | None= None,
               custom: dict[str, Any] = {}) -> UserNode:
         '''create a node in the flow'''
         # create a json schema object based on the single field
@@ -1483,6 +1591,8 @@ class UserFlow(Flow):
                    description = description,
                    default = default,
                    text = text,
+                   direction = direction,
+                   input_map = input_map,
                    option = option,
                    is_list = is_list,
                    min = min,