Merge branch 'main' into dev_container

.cspell.json

@@ -126,7 +126,9 @@
     "tcsetattr",
     "pysqlite",
     "AADSTS700082",
-    "levelno"
+    "levelno",
+    "LANCZOS",
+    "Mobius"
   ],
   "allowCompoundWords": true
 }

.github/workflows/promptflow-executor-e2e-test.yml

@@ -75,6 +75,8 @@ jobs:
         gci env:* | sort-object name
         az account show
         pip install langchain
+        # numexpr is required by langchain in e2e tests.
+        pip install numexpr
         python scripts/building/run_coverage_tests.py `
           -p ${{ env.testWorkingDirectory }}/promptflow `
           -t ${{ env.testWorkingDirectory }}/tests/executor/e2etests `

.github/workflows/promptflow-release-testing-matrix.yml

@@ -30,7 +30,7 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         testType: [sdk-cli, executor]
-        pythonVersion: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        pythonVersion: ['3.8', '3.9', '3.10', '3.11']
     runs-on: ${{ matrix.os }}
     steps:
     - name: checkout
@@ -39,8 +39,8 @@ jobs:
       run: 
         env | sort >> $GITHUB_OUTPUT
       shell: bash -el {0}
-    - name: Conda Setup - ${{ matrix.os }} - Python Version ${{ matrix.pythonVersion }}
-      uses: "./.github/actions/step_create_conda_environment"
+    - name: Python Env Setup - ${{ matrix.os }} - Python Version ${{ matrix.pythonVersion }}
+      uses: "./.github/actions/step_create_python_environment"
       with:
         pythonVersion: ${{ matrix.pythonVersion }}
     - name: Build wheel
@@ -66,7 +66,6 @@ jobs:
       run: |
         gci env:* | sort-object name
         az account show
-        conda activate release-env
         python "../../scripts/building/run_coverage_tests.py" `
           -p promptflow `
           -t ${{ github.workspace }}/src/promptflow/tests/sdk_cli_azure_test ${{ github.workspace }}/src/promptflow/tests/sdk_cli_test `
@@ -81,7 +80,6 @@ jobs:
       run: |
         gci env:* | sort-object name
         az account show
-        conda activate release-env
         pip install langchain
         python scripts/building/run_coverage_tests.py `
           -p ${{ github.workspace }}/src/promptflow/promptflow `

.github/workflows/tools_tests.yml

@@ -1,8 +1,10 @@
 name: tools_tests
 on:
-  # Triggers the workflow pull request events but only for the main branch
-  pull_request:
-    branches: [ main ]
+  pull_request_target:
+    paths:
+      - src/promptflow-tools/**
+      - '**tools_tests.yml'
+  workflow_dispatch:
 jobs:
   run_tool_ci_job:
     # The type of runner that the job will run on
@@ -16,32 +18,18 @@ jobs:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - name: Checkout repository
         uses: actions/checkout@v3
-
-      - name: Check for changes
-        id: check_changes  
-        run: |  
-          git fetch origin ${{ github.base_ref }} # Fetch the base branch  
-          CHANGED=$(git diff --name-only FETCH_HEAD..HEAD -- 'src/promptflow-tools/')  
-          if [ -n "$CHANGED" ]; then  
-            echo "Changes detected in src/promptflow-tools/"  
-            echo "run_tests=true"   >> $GITHUB_OUTPUT
-          else  
-            echo "No changes detected in src/promptflow-tools/"
-            echo "run_tests=false" >> $GITHUB_OUTPUT
-          fi 
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
       - name: Setup
-        if: steps.check_changes.outputs.run_tests == 'true'
         run: |
           python -m pip install --upgrade pip
-          pip install promptflow
           pip install pytest pytest_mock
           pip install azure-identity azure-keyvault-secrets
+          pip install -r ./src/promptflow-tools/requirements.txt
       - name: Generate configs
-        if: steps.check_changes.outputs.run_tests == 'true'
         run: |
           python ./scripts/tool/generate_connection_config.py --tenant_id ${{ secrets.TENANT_ID }} --client_id ${{ secrets.CLIENT_ID }} --client_secret ${{ secrets.CLIENT_SECRET }}
 
       - name: Run tests
-        if: steps.check_changes.outputs.run_tests == 'true'
         run: |
           pytest ./src/promptflow-tools/tests

docs/README.md

@@ -10,7 +10,7 @@ Below is a table of important doc pages.
 |----------------|----------------|
 |Quick start|[Get started with prompt flow](./how-to-guides/quick-start.md)|
 |Concepts|[Flows](./concepts/concept-flows.md)<br> [Tools](./concepts/concept-tools.md)<br> [Connections](./concepts/concept-connections.md)<br> [Variants](./concepts/concept-variants.md)<br> |
-|How-to guides|[How to initialize and test a flow](./how-to-guides/init-and-test-a-flow.md) <br>[How to run and evaluate a flow](./how-to-guides/run-and-evaluate-a-flow.md)<br> [How to tune prompts using variants](./how-to-guides/tune-prompts-with-variants.md)<br>[How to deploy a flow](./how-to-guides/deploy-a-flow/index.md)<br>[How to create and use your own tool package](./how-to-guides/how-to-create-and-use-your-own-tool-package.md)|
+|How-to guides|[How to initialize and test a flow](./how-to-guides/init-and-test-a-flow.md) <br>[How to run and evaluate a flow](./how-to-guides/run-and-evaluate-a-flow.md)<br> [How to tune prompts using variants](./how-to-guides/tune-prompts-with-variants.md)<br>[How to deploy a flow](./how-to-guides/deploy-a-flow/index.md)<br>[How to create and use your own tool package](./how-to-guides/develop-a-tool/create-and-use-tool-package.md)|
 |Tools reference|[LLM tool](./tools-reference/llm-tool.md)<br> [Prompt tool](./tools-reference/prompt-tool.md)<br> [Python tool](./tools-reference/python-tool.md)<br> [SERP API tool](./tools-reference/serp-api-tool.md)<br> [Embedding tool](./tools-reference/embedding_tool.md)||
 
 

docs/concepts/concept-tools.md

@@ -22,7 +22,7 @@ Our partners also contributes other useful tools for advanced scenarios, here ar
 ## Custom tools
 
 You can create your own tools that can be shared with your team or anyone in the world. 
-Learn more on [Custom tool package creation and usage](../how-to-guides/how-to-create-and-use-your-own-tool-package.md)
+Learn more on [Create and Use Tool Package](../how-to-guides/develop-a-tool/create-and-use-tool-package.md)
 
 ## Next steps
 

docs/how-to-guides/add-conditional-control-to-a-flow.md

@@ -0,0 +1,84 @@
+# Add conditional control to a flow
+
+:::{admonition} Experimental feature
+This is an experimental feature, and may change at any time. Learn [more](faq.md#stable-vs-experimental).
+:::
+
+In Prompt flow, we support control logic by activate config, like if-else, switch. Activate config enables conditional execution of nodes within your flow, ensuring that specific actions are taken only when the specified conditions are met.
+
+This guide will help you learn how to use activate config to add conditional control to your flow.
+
+## Prerequisites
+
+Please ensure that your promptflow version is greater than `0.1.0b5`.
+
+## Usage
+
+Each node in your flow can have an associated activate config, specifying when it should execute and when it should bypass. If a node has activate config, it will only be executed when the activate condition is met. The configuration consists of two essential components:
+- `activate.when`: The condition that triggers the execution of the node. It can be based on the outputs of a previous node, or the inputs of the flow.
+- `activate.is`: The condition's value, which can be a constant value of string, boolean, integer, double.
+
+You can manually change the flow.dag.yaml in the flow folder or use the visual editor in VS Code Extension to add activate config to nodes in the flow.
+
+::::{tab-set}
+:::{tab-item} YAML
+:sync: YAML
+
+You can add activate config in the node section of flow yaml.
+```yaml
+activate:
+  when: ${node.output}
+  is: true
+```
+
+:::
+
+:::{tab-item} VS Code Extension
+:sync: VS Code Extension
+
+- Click `Visual editor` in the flow.dag.yaml to enter the flow interface.
+![visual_editor](../media/how-to-guides/conditional-flow-with-activate/visual_editor.png)
+
+- Click on the `Activation config` section in the node you want to add and fill in the values for "when" and "is".
+![activate_config](../media/how-to-guides/conditional-flow-with-activate/activate_config.png)
+
+:::
+
+::::
+
+### Further details and important notes
+1. If the node using the python tool has an input that references a node that may be bypassed, please provide a default value for this input. This helps prevent errors in the current node due to missing parameters.
+
+    ![provide_default_value](../media/how-to-guides/conditional-flow-with-activate/provide_default_value.png)
+
+2. Please avoid directly connecting nodes that might be bypassed to the flow's outputs. This can lead to flow failures due to a lack of valid values on the flow output.
+
+    ![output_bypassed](../media/how-to-guides/conditional-flow-with-activate/output_bypassed.png)
+
+3. In a conditional flow, if a node is bypassed, it status will be marked as `Bypassed`, as shown in the figure below. There are three situations in which the node will be bypassed.
+  ![bypassed_nodes](../media/how-to-guides/conditional-flow-with-activate/bypassed_nodes.png)
+
+
+    (1) If a node has activate config and the value of `activate.when` is equals to `activate.is`, it will be bypassed.
+
+    (2) If a node has activate config and the node pointed to by `activate.when` is bypassed, it will be bypassed.
+
+    ![activate_when_bypassed](../media/how-to-guides/conditional-flow-with-activate/activate_when_bypassed.png)
+
+    (3) If a node does not have activate config but depends on other nodes that have been bypassed, it will be bypassed.
+
+    ![dependencies_bypassed](../media/how-to-guides/conditional-flow-with-activate/dependencies_bypassed.png)
+
+
+
+## Example flow
+
+Let's illustrate how to use activate config with practical examples.
+
+- If-Else scenario: Learn how to develop a conditional flow for if-else scenarios. [View Example](https://github.com/microsoft/promptflow/tree/main/examples/flows/standard/conditional-flow-for-if-else)
+- Switch scenario: Explore conditional flow for switch scenarios. [View Example](https://github.com/microsoft/promptflow/tree/main/examples/flows/standard/conditional-flow-for-switch)
+
+
+## Next steps
+
+- [Run and evaluate a flow](./run-and-evaluate-a-flow.md)

docs/how-to-guides/develop-a-tool/add-a-tool-icon.md

@@ -0,0 +1,58 @@
+# Add a Tool Icon
+A tool icon serves as a graphical representation of your tool in the user interface (UI). Follow this guidance to add a custom tool icon when developing your own tool package.  
+
+Adding a custom tool icon is optional. If you do not provide one, the system uses a default icon.
+
+## Prerequisites
+
+- Create a tool package as described in [Create and Use Tool Package](create-and-use-tool-package.md).
+- Prepare a custom tool icon image. The image should meet following requirements:
+  - The image should be in `PNG` or `JPG` format.
+  - 16x16 pixel image to avoid distortion from resizing.
+  - Avoid complex images with much detail or contrast as they may not resize well.   
+    You could see for example.
+- Install dependencies of generating icon data URI:
+
+  ```
+  pip install pillow
+  ```
+## Generate a tool icon data URI
+Run below command under the root folder to generate a data URI for your custom tool icon. Make sure the output file has an `.html` extension, this makes it easier to check the image's data URI: 
+```
+python <path-to-scripts>\tool\convert_image_to_data_url.py --image-path <image_input_path> -o <html_output_path>
+```     
+For example:
+```
+python D:\proj\github\promptflow\scripts\tool\convert_image_to_data_url.py --image-path D:\proj\github\promptflow\examples\tools\tool-package-quickstart\my_tool_package\icons\custom-tool-icon.png -o output.html
+```
+The content of `output.html` looks like the following, and you can open it in a web browser to see the result.
+```html
+<html>
+<body>
+<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAACq0lEQVR4nKWTPWxTVxiGn3N/bF/fGyd2YxsQ5LdSmoqGgKJMEQNZYGBFkVhY2JGYmFG3ioWZpWukqqpaqaVKq6pFIAECAkSxMA6RHZP4Jnbs+O/6xvdjcCLKT6ee7ZwjvfrOc55XiYjwP5bx740IZDf3+PVZicdrVeK2yfzJJBem02iaQv1XQCCCCNz+Lce91R1mRvtYd5uEDIfl9SqpWIjZLxOIgPooRQtE0JQiU6xx91mJfNkjZoX47vIkM2Nx6l6Xmz9kWHywgVIQBB++WImI1Nv7fP/XOqah0fKFdH8YQwXcf1Vh6WWZTrfLaDLK4rVZrJD+wSQGwJrbQtc0rs4PAXDr5xy/PHW5NJsmGQuhNI0/XrisFmtMjwxwOLVCYXTaTdq+kHagXq0iAo4phE2dn564XD8/zLlTRwn8gK1dQaHQtfcgDDMcwQo1Wc43mEp16YpibdsjEKHdEX5/8YZEpIhjCckBi9a+ibfvETEsIobdY1Bp+Pz4cAvP67C522IsbeN1A0zd5r77LWF7hebe1xxJrzKRmON56W/OHDnHwskbaCIQt03OTsbJljxeuz4rxSYXp2JcmYszedQhrNscj/ehJIKuQpiaBegHEFVPoOHBKOPpKMXdNtlSmzt/bpC0XTb9LxgcmGDq2CT5mpC0hhiO1UhGe8ANBYgCQ1dcnR9iJGnxT6ZMrtLmbV1H78/QrD0nagQ82ljCP+HzqLBEsB8wP7bQ+8ZDpoauuHA6xfnpFA3Px4mY3M2cJbeTZjTxFQYm44lv0MRkPDH1aRcOtdaUwon0rgrbBdbd10S1AXJbWRxzkLXNLDEz1VP54wDtQLHuQUl36xUKpTzl6jYFN89OdYeCm6eyV3mv8mdKxuFxueHS8PawTJuW3yAacmh26jiRfhL2IO8AhSUo7nmFnjUAAAAASUVORK5CYII=" alt="My Image">
+</body>
+</html>
+```
+
+## Use the tool icon data URI in the tool YAML
+In the auto-generated tool YAML file, customize the tool icon by adding the data URI:
+```yaml
+hello_world.tools.hello_world_tool.get_greeting_message
+  function: get_greeting_message
+  inputs:
+    connection:
+      type:
+      - CustomConnection
+    input_text:
+      type:
+      - string
+  module: hello_world.tools.hello_world_tool
+  name: Hello World Tool
+  description: This is hello world tool
+  type: python
+  icon: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAACq0lEQVR4nKWTPWxTVxiGn3N/bF/fGyd2YxsQ5LdSmoqGgKJMEQNZYGBFkVhY2JGYmFG3ioWZpWukqqpaqaVKq6pFIAECAkSxMA6RHZP4Jnbs+O/6xvdjcCLKT6ee7ZwjvfrOc55XiYjwP5bx740IZDf3+PVZicdrVeK2yfzJJBem02iaQv1XQCCCCNz+Lce91R1mRvtYd5uEDIfl9SqpWIjZLxOIgPooRQtE0JQiU6xx91mJfNkjZoX47vIkM2Nx6l6Xmz9kWHywgVIQBB++WImI1Nv7fP/XOqah0fKFdH8YQwXcf1Vh6WWZTrfLaDLK4rVZrJD+wSQGwJrbQtc0rs4PAXDr5xy/PHW5NJsmGQuhNI0/XrisFmtMjwxwOLVCYXTaTdq+kHagXq0iAo4phE2dn564XD8/zLlTRwn8gK1dQaHQtfcgDDMcwQo1Wc43mEp16YpibdsjEKHdEX5/8YZEpIhjCckBi9a+ibfvETEsIobdY1Bp+Pz4cAvP67C522IsbeN1A0zd5r77LWF7hebe1xxJrzKRmON56W/OHDnHwskbaCIQt03OTsbJljxeuz4rxSYXp2JcmYszedQhrNscj/ehJIKuQpiaBegHEFVPoOHBKOPpKMXdNtlSmzt/bpC0XTb9LxgcmGDq2CT5mpC0hhiO1UhGe8ANBYgCQ1dcnR9iJGnxT6ZMrtLmbV1H78/QrD0nagQ82ljCP+HzqLBEsB8wP7bQ+8ZDpoauuHA6xfnpFA3Px4mY3M2cJbeTZjTxFQYm44lv0MRkPDH1aRcOtdaUwon0rgrbBdbd10S1AXJbWRxzkLXNLDEz1VP54wDtQLHuQUl36xUKpTzl6jYFN89OdYeCm6eyV3mv8mdKxuFxueHS8PawTJuW3yAacmh26jiRfhL2IO8AhSUo7nmFnjUAAAAASUVORK5CYII=
+```
+
+## Verify the tool icon in VS Code extension
+Follow [steps](create-and-use-tool-package.md#use-your-tool-from-vscode-extension) to use your tool from VS Code extension. Your tool displays with the custom icon:  
+![custom-tool-with-icon-in-extension](../../media/contributing/custom-tool-with-icon-in-extension.png)

docs/how-to-guides/how-to-create-and-use-your-own-tool-package.md → docs/how-to-guides/develop-a-tool/create-and-use-tool-package.md

@@ -1,10 +1,10 @@
-# Custom tool package creation and usage
+# Create and Use Tool Package
 In this document, we will guide you through the process of developing your own tool package, offering detailed steps and advice on how to utilize your creation.
 
 The custom tool is the prompt flow tool developed by yourself. If you find it useful, you can follow this guidance to make it a tool package. This will enable you to conveniently reuse it, share it with your team, or distribute it to anyone in the world.
 
 After successful installation of the package, your custom "tool" will show up in VSCode extension as below: 
-![custom-tool-list](../media/contributing/custom-tool-list-in-extension.png)
+![custom-tool-list](../../media/contributing/custom-tool-list-in-extension.png)
 
 ## Create your own tool package
 Your tool package should be a python package. To try it quickly, just use [my-tools-package 0.0.1](https://pypi.org/project/my-tools-package/) and skip this section.
@@ -115,7 +115,7 @@ hello-world-proj/
    ``` 
 
 * Step3: Go to the extension and open one flow folder. Click 'flow.dag.yaml' and preview the flow. Next, click `+` button and you will see your tools. You may need to reload the windows to clean previous cache if you don't see your tool in the list.
-![auto-list-tool-in-extension](../media/contributing/auto-list-tool-in-extension.png)
+![auto-list-tool-in-extension](../../media/contributing/auto-list-tool-in-extension.png)
 
 
 ## FAQ

docs/how-to-guides/develop-a-tool/index.md

@@ -0,0 +1,10 @@
+# Develop a tool
+We provide guides on how to develop a tool and use it.
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+create-and-use-tool-package
+add-a-tool-icon
+```

docs/how-to-guides/faq.md

@@ -33,3 +33,21 @@ For more detail about keyring third-party backend, please refer to 'Third-Party
 If you are using WSL, this is a known issue for `webbrowser` under WSL; see [this issue](https://github.com/python/cpython/issues/89752) for more information. Please try to upgrade your WSL to 22.04 or later, this issue should be resolved.
 
 If you are still facing this issue with WSL 22.04 or later, or you are not even using WSL, please open an issue to us.
+
+### Installed tool not appearing in VSCode Extension tool list
+
+After installing a tool package via `pip install [tool-package-name]`, the new tool may not immediately appear in the tool list within the VSCode Extension, as shown below:
+
+![VSCode Extension tool list](../media/how-to-guides/vscode-tool-list.png)
+
+This is often due to outdated cache. To refresh the tool list and make newly installed tools visible:
+
+1. Open the VSCode Extension window.
+
+2. Bring up the command palette by pressing "Ctrl+Shift+P".
+
+3. Type and select the "Developer: Reload Webviews" command. 
+
+4. Wait a moment for the tool list refreshing.
+
+Reloading clears the previous cache and populates the tool list with any newly installed tools. So that the missing tools are now visible.

docs/how-to-guides/index.md

@@ -7,14 +7,15 @@ Simple and short articles grouped by topics, each introduces a core feature of p
 
 develop-a-flow/index
 init-and-test-a-flow
+add-conditional-control-to-a-flow
 run-and-evaluate-a-flow
 tune-prompts-with-variants
 deploy-a-flow/index
 enable-streaming-mode
 manage-connections
 manage-runs
 column-mapping
-how-to-create-and-use-your-own-tool-package
+develop-a-tool/index
 faq
 
 ```

docs/how-to-guides/init-and-test-a-flow.md

@@ -294,4 +294,4 @@ Break points and debugging functionalities for the Python steps in your flow. Ju
 
 ## Next steps
 
-- [Run and evaluate a flow](./run-and-evaluate-a-flow.md)
+- [Add conditional control to a flow](./add-conditional-control-to-a-flow.md)