[pf tool] Update how to doc of tool develop (#882)

# Description Please add an informative description that covers that changes made by the pull request and link all relevant issues. # All Promptflow Contribution checklist: - [ ] **The pull request does not introduce [breaking changes].** - [ ] **CHANGELOG is updated for new features, bug fixes or other significant changes.** - [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).** - [ ] **Create an issue and link to the pull request to get dedicated review from promptflow team. Learn more: [suggested workflow](../CONTRIBUTING.md#suggested-workflow).** ## General Guidelines and Best Practices - [ ] Title of the pull request is clear and informative. - [ ] There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, [see this page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md). ### Testing Guidelines - [ ] Pull request includes test coverage for the included changes.
microsoft · Dec 25, 2023 · 15b4576 · 15b4576
1 parent 6472a07
commit 15b4576
Show file tree

Hide file tree

Showing 26 changed files with 399 additions and 646 deletions.
diff --git a/docs/how-to-guides/develop-a-tool/add-a-tool-icon.md b/docs/how-to-guides/develop-a-tool/add-a-tool-icon.md
@@ -1,11 +1,12 @@
-# Adding a Tool Icon
+# Adding 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
 
 - Please ensure that your [Prompt flow for VS Code](https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow) is updated to version 1.4.2 or later.
+- Please install promptflow package and ensure that its version is 1.1.0 or later.
 - Create a tool package as described in [Create and Use Tool Package](create-and-use-tool-package.md).
 - Prepare custom icon image that meets these requirements:
 
@@ -14,39 +15,50 @@ Adding a custom tool icon is optional. If you do not provide one, the system use
   - Avoid complex images with lots of detail or contrast, as they may not resize well. 
 
   See [this example](https://github.com/microsoft/promptflow/blob/main/examples/tools/tool-package-quickstart/my_tool_package/icons/custom-tool-icon.png) as a reference.
-- Install dependencies to generate icon data URI:
 
-  ```
-  pip install pillow
-  ```
+## Add tool icon with _icon_ parameter
 
-## Add tool icon with _icon_ parameter 
-Run the command below in your tool project directory to automatically generate your tool YAML, use _-i_ or _--icon_ parameter to add a custom tool icon:
+### Initialize a package tool with icon
+You can use [pf tool init](../../reference/pf-command-reference.md#pf-tool-init) to initialize a package tool with icon:
+```bash
+pf tool init --package <package-name> --tool <tool-name> --set icon=<icon-path>
 ```
-python <promptflow github repo>\scripts\tool\generate_package_tool_meta.py -m <tool_module> -o <tool_yaml_path> -i <tool-icon-path>
-```
-Here we use [an existing tool project](https://github.com/microsoft/promptflow/tree/main/examples/tools/tool-package-quickstart) as an example.
-```
-cd D:\proj\github\promptflow\examples\tools\tool-package-quickstart
 
-python D:\proj\github\promptflow\scripts\tool\generate_package_tool_meta.py -m my_tool_package.tools.my_tool_1 -o my_tool_package\yamls\my_tool_1.yaml -i my_tool_package\icons\custom-tool-icon.png
+PF CLI will copy the icon file to the folder `<package-name>/icons/<icon-file-name>` and generate a tool script in the package. The tool icon will be configured in the tool script. Here we use [an existing tool](https://github.com/microsoft/promptflow/blob/main/examples/tools/tool-package-quickstart/my_tool_package/tools/my_tool_1.py) as an example, the code is as follows:
+```python
+from pathlib import Path
+
+from promptflow import tool
+from promptflow.connections import CustomConnection
+
+
+@tool(
+    name="My First Tool",
+    description="This is my first tool",
+    icon=Path(__file__).parent.parent / "icons" / "custom-tool-icon.png"
+)
+def my_tool(connection: CustomConnection, input_text: str) -> str:
+    # Replace with your tool code.
+    # Usually connection contains configs to connect to an API.
+    # Use CustomConnection is a dict. You can use it like: connection.api_key, connection.api_base
+    # Not all tools need a connection. You can remove it if you don't need it.
+    return "Hello " + input_text
 ```
 
-In the auto-generated tool YAML file, the custom tool icon data URI is added in the `icon` field:
-```yaml
-my_tool_package.tools.my_tool_1.my_tool:
-  function: my_tool
-  icon: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAACR0lEQVR4nKWS3UuTcRTHP79nm9ujM+fccqFGI5viRRpjJgkJ3hiCENVN/QMWdBHUVRdBNwX9ARHd2FVEWFLRjaS9XPmSC/EFTNOWc3Pi48y9PHNzz68L7UXTCvreHM65+PA953uElFLyHzLvHMwsJrnzfJqFeAan3cKV9mr8XseeAOXX5vqjSS53jdF+tIz1nIFAMDCzwpvJ5b87+LSYYHw+gcWkEAwluXnOR2Q1R+9YjJ7BKJG4zoXmqr0ddL3+QnV5EeUOK821LsJammcjEeZiafJScrd3bm8H6zkDd4mVztZKAK49/Mj8is4Z/35GPq9R5VJ5GYztDtB1HT1vovGQSiqVAqDugI3I6jpP3i9x9VQVfu8+1N/OvbWCqqqoBSa6h1fQNA1N0xiYTWJSBCZF8HgwSjQapbRQ2RUg5NYj3O6ZochmYkFL03S4mImIzjFvCf2xS5gtCRYXWvBUvKXjyEVeTN/DXuDgxsnuzSMK4HTAw1Q0hZba4NXEKp0tbpq9VkxCwTAETrsVwxBIBIYhMPI7YqyrtONQzSznJXrO4H5/GJ9LUGg0YFYydJxoYnwpj1s9SEN5KzZz4fYYAW6dr+VsowdFgamlPE/Hs8SzQZYzg0S+zjIc6iOWDDEc6uND+N12B9/VVu+mrd79o38wFCCdTeBSK6hxBii1eahxBlAtRbsDdmoiHGRNj1NZ7GM0NISvzM9oaIhiqwOO/wMgl4FsRpLf2KxGXpLNSLLInzH+CWBIA6RECIGUEiEUpDRACBSh8A3pXfGWdXfMgAAAAABJRU5ErkJggg==
-  inputs:
-    connection:
-      type:
-      - CustomConnection
-    input_text:
-      type:
-      - string
-  module: my_tool_package.tools.my_tool_1
-  name: my_tool
-  type: python
+The folder structure of the generated tool package is as follows:
+```
+<package-name>
+│   MANIFEST.in
+│   README.md
+│   setup.py
+│
+├───icons
+│       <icon-file-name>
+│
+└───<package-name>
+        <tool-name>.py
+        utils.py
+        __init__.py
 ```
 
 ## Verify the tool icon in VS Code extension
@@ -72,37 +84,42 @@ The content of `output.html` looks like the following, open it in a web browser
 </html>
 ```
 
-### Can I add a tool icon to an existing tool package?
-Yes, you can refer to the [preview icon](add-a-tool-icon.md#can-i-preview-the-tool-icon-image-before-adding-it-to-a-tool) section to generate the data URI and manually add the data URI to the tool's YAML file.
+### Can I add a tool icon to an existing tool package
+
+You can follow these steps to add an icon to an existing package tool:
+1. Copy the icon image to the package folder.
+2. Configure the icon for the tool.
+
+    In the tool script, add the `icon` parameter to the decorator method `@tool`, and the parameter value is the `icon path`. The code is as follows:
+    ```python
+    from promptflow import tool
+
+    @tool(name="tool_name", icon=<icon-path>)
+    def tool_func(input_text: str) -> str:
+        # Tool logic
+        pass
+    ```
+3. Update `MANIFEST.in` in the package folder.
+
+    This file is used to determine which files to include in the distribution of the project. You need to add the icon path relative to the package folder to this file.
+    ```
+    include <relative-icon-path>
+    ```
 
 ### Can I add tool icons for dark and light mode separately?
-Yes, you can add the tool icon data URIs manually or run the command below in your tool project directory to automatically generate your tool YAML, use _--icon-light_ to add a custom tool icon for the light mode and use _--icon-dark_ to add a custom tool icon for the dark mode:
-```
-python <promptflow github repo>\scripts\tool\generate_package_tool_meta.py -m <tool_module> -o <tool_yaml_path> --icon-light <light-tool-icon-path> --icon-dark <dark-tool-icon-path>
-```
-Here we use [an existing tool project](https://github.com/microsoft/promptflow/tree/main/examples/tools/tool-package-quickstart) as an example.
-```
-cd D:\proj\github\promptflow\examples\tools\tool-package-quickstart
+Yes, you can add the tool icon data to the tool code as follows:
+```python
+from promptflow import tool
 
-python D:\proj\github\promptflow\scripts\tool\generate_package_tool_meta.py -m my_tool_package.tools.my_tool_1 -o my_tool_package\yamls\my_tool_1.yaml --icon-light my_tool_package\icons\custom-tool-icon-light.png --icon-dark my_tool_package\icons\custom-tool-icon-dark.png
+@tool(name="tool_name", icon_dark=<icon-path>, icon_light=<icon-path>)
+def tool_func(input_text: str) -> str:
+    # Tool logic
+    pass
 ```
 
-In the auto-generated tool YAML file, the light and dark tool icon data URIs are added in the `icon` field:
-```yaml
-my_tool_package.tools.my_tool_1.my_tool:
-  function: my_tool
-  icon:
-    dark: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAB00lEQVR4nI1SO2iTURT+7iNNb16a+Cg6iJWqRKwVRIrWV6GVUkrFdqiVShBaxIIi4iY4iouDoy4ODkKn4uQkDs5FfEzFYjEtJYQo5P/z35j/3uNw7Z80iHqHC/ec8z3OuQeMMcYYAHenU8n84YMAABw7mo93dEQpAIyBAyAiF1Kq8/Wrl5fHR1x6tjC9uPBcSrlZD4BxIgIgBCei+bnC6cGxSuWHEEIIUa58H7l0dWZqwlqSUjhq7oDWEoAL584Y6ymljDHGmM543BhvaPAsAKLfEjIyB6BeryPw796+EWidUInr16b5z6rWAYCmKXeEEADGRy+SLgXlFfLWbbWoyytULZ4f6Hee2yDgnAG4OVsoff20try08eX92vLSzJVJAJw3q7dISSnDMFx48UypeCa97cPHz7fu3Y/FYo1Go8nbCiAiIUStVus/eaKvN691IAQnsltI24wZY9Kp1Ju373K5bDKZNMa6gf5ZIWrG9/0g0K3W/wYIw3Dvnq6dO7KNMPwvgOf5x3uPHOrp9n3/HwBrLYCu3bv6Tg0PjU0d2L8PAEWfDKCtac6YIVrfKN2Zn8tkUqvfigBaR88Ya66uezMgl93+9Mmjxw8fJBIqWv7NAvwCHeuq7gEPU/QAAAAASUVORK5CYII=
-    light: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAB2UlEQVR4nH1SO2hUQRQ9c18K33u72cXs7jOL8UeQCCJoJaIgKAiCWKilaGNlYREFDRGNjayVWKiFFmITECFKJKIokQRRsDFENoooUchHU5qdWZ2512KymxcNOcUwc5nDuefeA2FhZpGFU0S0Mf5S0zpdF2FhISgopUREKfXj59yhoycmPn4GAKDncuXa9VtKKWYGACgowHOdc9a6g0eOA7mx8apzzlp76vRZoGXw6XMRsdb6nwSAmYnoQ3Xi5fBIdk2SiSMiCoKgNZslteruvX4ASikvSwAEAGDqdYhAXO+VypevkwODQ4+HnlGcq2mDNLwtZq5pvWP3AYRJ0Lq2uG5rWNgYFjaBVt+8c19E/jRaWvQgImPj1e279ufaN8elzly5K1/u6r7QZ51zrjmoBqHJ+TU/39ax5cy5i53bdnb39KXtLpr28OMLgiCfz78YHpmemi0W2piZWdIWaMmDCIDWet/ePUlS0toQUWM8yxG8jrVuw/qOTBw19rUiQUQoCGZm50z9txf8By3/K0Rh+PDRk8lv3+MoWklBBACmpmdKxcKn96O3b1SqC6FSyxOUgohk4pjZ9T8YeDX6ptye+PoSpNIrfkGv3747fOzk+UtXjTE+BM14M8tfl7BQR9VzUXEAAAAASUVORK5CYII=
-  inputs:
-    connection:
-      type:
-      - CustomConnection
-    input_text:
-      type:
-      - string
-  module: my_tool_package.tools.my_tool_1
-  name: my_tool
-  type: python
+Or run the command below in your tool project directory to automatically generate tool code, use _--icon_light_ to add a custom tool icon for the light mode and use _--icon_dark_ to add a custom tool icon for the dark mode:
+```python
+pf tool init --tool <tool-name> --set icon_dark=<icon-path> icon_light=<icon-path>
 ```
-Note: Both light and dark icons are optional. If you set either a light or dark icon, it will be used in its respective mode, and the system default icon will be used in the other mode.
+
+Note: Both light and dark icons are optional. If you set either a light or dark icon, it will be used in its respective mode, and the system default icon will be used in the other mode.
diff --git a/docs/how-to-guides/develop-a-tool/add-category-and-tags-for-tool.md b/docs/how-to-guides/develop-a-tool/add-category-and-tags-for-tool.md
@@ -1,4 +1,4 @@
-# Adding Category and Tags for Tool
+# Adding category and tags for tool
 
 This document is dedicated to guiding you through the process of categorizing and tagging your tools for optimal organization and efficiency. Categories help you organize your tools into specific folders, making it much easier to find what you need. Tags, on the other hand, work like labels that offer more detailed descriptions. They enable you to quickly search and filter tools based on specific characteristics or functions. By using categories and tags, you'll not only tailor your tool library to your preferences but also save time by effortlessly finding the right tool for any task.
 
@@ -13,49 +13,62 @@ This document is dedicated to guiding you through the process of categorizing an
 
 ## Prerequisites
 - Please ensure that your [Prompt flow for VS Code](https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow) is updated to version 1.1.0 or later.
+- Please install promptflow package and ensure that its version is 1.1.0 or later.
 
 ## How to add category and tags for a tool
-Run the command below in your tool project directory to automatically generate your tool YAML, use _-c_ or _--category_ to add category, and use _--tags_ to add tags for your tool:
 
-```
-python <promptflow github repo>\scripts\tool\generate_package_tool_meta.py -m <tool_module> -o <tool_yaml_path> --category <tool_category> --tags <tool_tags>
-```
+You can use [pf tool init](../../reference/pf-command-reference.md#pf-tool-init) to initialize a package tool with category and tags:
+```python
+pf tool init --package <package-name> --tool <tool-name> --set category=<tool_category> tags=<tool_tags>
 
-Here, we use [an existing tool](https://github.com/microsoft/promptflow/tree/main/examples/tools/tool-package-quickstart/my_tool_package/yamls/my_tool_1.yaml) as an example. If you wish to create your own tool, please refer to the [create and use tool package](create-and-use-tool-package.md#create-custom-tool-package) guide. 
 ```
-cd D:\proj\github\promptflow\examples\tools\tool-package-quickstart
 
-python D:\proj\github\promptflow\scripts\tool\generate_package_tool_meta.py -m my_tool_package.tools.my_tool_1 -o my_tool_package\yamls\my_tool_1.yaml --category "test_tool" --tags "{'tag1':'value1','tag2':'value2'}"
+Here, we use an example to show the categories and tags of the tool after initialization. Assume that the user executes this command:
+```python
+pf tool init --tool my_tool --set name="My First Tool" description="This is my first tool"  category="test_tool" tags="{'tag1':'value1','tag2':'value2'}"
 ```
-In the auto-generated tool YAML file, the category and tags are shown as below:
-```yaml
-my_tool_package.tools.my_tool_1.my_tool:
-  function: my_tool
-  inputs:
-    connection:
-      type:
-      - CustomConnection
-    input_text:
-      type:
-      - string
-  module: my_tool_package.tools.my_tool_1
-  name: My First Tool
-  description: This is my first tool
-  type: python
-  # Category and tags are shown as below.
-  category: test_tool
-  tags:
-    tag1: value1
-    tag2: value2
+The generated tool script is as follows, where category and tags have been configured on the tool:
+```python
+from promptflow import tool
+from promptflow.connections import CustomConnection
+
+
+@tool(
+    name="My First Tool",
+    description="This is my first tool",
+    category="test_tool",
+    tags={"tag1": "value1", "tag2": "value2"},
+)
+def my_tool(self, input_text: str) -> str:
+    # Replace with your tool code.
+    # Usually connection contains configs to connect to an API.
+    # Use CustomConnection is a dict. You can use it like: connection.api_key, connection.api_base
+    # Not all tools need a connection. You can remove it if you don't need it.
+    return "Hello " + input_text
 ```
 
 ## Tool with category and tags experience in VS Code extension
-Follow the [steps](create-and-use-tool-package.md#use-your-tool-from-vscode-extension) to use your tool via the VS Code extension. 
-- Experience in the tool tree  
-![category_and_tags_in_tool_tree](../../media/how-to-guides/develop-a-tool/category_and_tags_in_tool_tree.png)  
-
-- Experience in the tool list  
-By clicking `More` in the visual editor, you can view your tools along with their category and tags:  
-![category_and_tags_in_tool_list](../../media/how-to-guides/develop-a-tool/category_and_tags_in_tool_list.png)  
-Furthermore, you have the option to search or filter tools based on tags:  
-![filter_tools_by_tag](../../media/how-to-guides/develop-a-tool/filter_tools_by_tag.png)  
+Follow the [steps](create-and-use-tool-package.md#use-your-tool-from-vscode-extension) to use your tool via the VS Code extension.
+- Experience in the tool tree
+![category_and_tags_in_tool_tree](../../media/how-to-guides/develop-a-tool/category_and_tags_in_tool_tree.png)
+
+- Experience in the tool list
+By clicking `More` in the visual editor, you can view your tools along with their category and tags:
+![category_and_tags_in_tool_list](../../media/how-to-guides/develop-a-tool/category_and_tags_in_tool_list.png)
+Furthermore, you have the option to search or filter tools based on tags:
+![filter_tools_by_tag](../../media/how-to-guides/develop-a-tool/filter_tools_by_tag.png)
+
+## FAQ
+### How to configure category and tags on an existing package tool
+Customer can configure category and tags directly on the tool script, as shown in the following code:
+```python
+@tool(
+    name="tool_name",
+    description="This is tool_name tool",
+    category=<tool-category>,
+    tags=<dict-of-the-tool-tags>,
+)
+def tool_name(input_text: str) -> str:
+    # tool logic
+    pass
+```