rename custom tool package, add tool icon and structure md

update

update

update

update

update

update

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/deploy-custom-tool/custom-tool-package-creation-and-usage.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 [Custom tool package creation and usage](../how-to-guides/develop-custom-tool/custom-tool-package-creation-and-usage.md)
 
 ## Next steps
 

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

@@ -4,7 +4,7 @@ In this document, we will guide you through the process of developing your own t
 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.
@@ -76,47 +76,6 @@ hello-world-proj/
     python D:\proj\github\promptflow\scripts\tool\generate_package_tool_meta.py -m hello_world.tools.hello_world_tool -o hello_world\yamls\hello_world_tool.yaml -n "Hello World Tool" -d "This is my hello world tool."
     ```
     To populate your tool module, adhere to the pattern \<package_name\>.tools.\<tool_name\>, which represents the folder path to your tool within the package.
-
-    In the auto-generated tool yaml file, you can customize your tool's icon and structure by adding the tool icon's data URI and the structure path directly to the YAML file:
-    ```
-    my_tool_package.tools.my_tool_1.my_tool:
-      name: My First Tool
-      description: This is my first tool
-      icon: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAADDklEQVR4nG1TTWicVRQ9933v+yYZax0a0hBDJ7EIjaUTjTO2KwlCCtaFriJ0oQUhmaVgQrIo5XMMUmNU1EVgxuLGHzCBoW50kQyhUG1DMtqknaS6sCYWaZr+pTOTmXnfe++6GG1V5qwu3HsO53LvodHZ2BoE1pjx3WT/5TP+fJ9MvXBOg0EgMP4GMyiZicv2obwp5w4NCqYXAXRjNBfLAqhPM0tmdpaW0i4AjOd7O98pJHrfvXCoDQB89gX+hdFcLCtg6bzvQzAYRKSJyCQSyeD0L7F+N+zMPxpxfqJI6Oz41cNPpChlT68diaeX4mEAIEM/UN0e0/L6ja7dIhjYvHWjRW1T8WJkZNCEt6NGOYH0yDVV+6OxNu949ApBLFRr5rPxZy/NyukrvkdEauf6bwk30jpx/8/fC0ozOfqRaLG4pYXx2NZgjeFeoxFxFKLWmjbHxVl/vk8SM9Mnm9jbZmtfh00l8YcRC01698TGes9+7Yn0rj2SyneDLWWD4+W7tB4OiWNK8cVPXy4sAiACgPdv8kBTBNPFeyiFWrDr1h28/l4rfTE8m3hONptoUDGXPzq68isaQALAjsGTWoMrDGEBsEKJmYnIWQTsIgD4PkQqBVu/BkSK6rX0mWV1Cx1KgRXDLd60GiRuExEDD6+WSj38iX/IACBLywipNjwDF6JsIEQgbntC3QeA8lfdhz0qRU3grDSduNZwBWGfhlXAufC2LuyrlSqsq19Odey5xOnW10KmvCCbxYzD+rz6fN/zAMDTcP4j0J1J6nQ7nTylr3844laa39pYfCw3m/v4nnx8ipTS1U1TlQ61sMabdcrBBwID0wOOSCYzwRCzu2G95TLom5IMPWUJcWOaHBFAkgVBk2BFpf/bn3l1xoixuZ7h9rfJHOzq+PnbbPaN5trWsdW+I/1C7RxXyrsWcp1QddteUAFNAAAKq9r3IXwfYmyuZ/hBmBrhzmRXZ+mDzt7i1P69jfqjuViWxuZiq0y4ag2+nzy6ciaTT8qheFoDBGoQ50wyH4zkYoPC4iUiHPgLhm17gdgF0NgAAAAASUVORK5CYII=
-      structure: test/my_first_tool
-      module: my_tool_package.tools.my_tool_1
-      function: my_tool
-      type: python
-      inputs:
-        connection:
-          type:
-          - CustomConnection
-        input_text:
-          type:
-          - string
-    ```
-    5.1 **Tool icon**: The tool icon is a graphic representation of your tool in the user interface (UI). If you don't supply a tool icon, the system will use a default one.
-    You can use the below command to generate your tool icon data uri:
-    ```
-    python scripts\tool\convert_image_to_data_url.py --image-path <image_input_path> -o <html_output_path>
-    ```    
-    For example:
-    ```
-    python scripts\tool\convert_image_to_data_url.py --image-path "AzureContentSafetyIcon.png" -o "output.html"
-    ```
-     - To run this script, `pip install pillow`.
-     - The supported image formats are `PNG`, `JPG`, and `SVG`.
-     - The output file's extension **must be** `html`.
-    This will generate an HTML file at the specified output file path. To see the result, open the file in a web browser.
-     - The script also checks the size of your image, and if necessary, automatically resizes it to 16*16 pixels. To maintain the quality of your image, consider the following suggestions:
-       - If possible, provide an image that is 16*16 pixels to avoid distortion from resizing.  
-       - Avoid complex images with a lot of detail or contrast, as they may not resize well.
-    
-    5.2 **Tool structure**: The tool structure path would be used by UI to display the tool's hierarchy structure.
-     - The structure string is case-insensitive and must contain characters from "a-zA-Z0-9-_".
-     - A maximum of three layers is permitted.
-
-
 6. **tests**: This directory contains all your tests, though they are not required for creating your custom tool package. When adding a new tool, you can also create corresponding tests and place them in this directory. Run below command under your tool project:
     ```
     pytest tests
@@ -156,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-custom-tool/index.md

@@ -0,0 +1,11 @@
+# Develop custom tool
+We provide guides on how to develop custom tool and use it.
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+custom-tool-package-creation-and-usage
+specify-tool-structure
+use-tool-icon
+```

docs/how-to-guides/develop-custom-tool/specify-tool-structure.md

@@ -0,0 +1,23 @@
+# Tool Structure
+The tool's structural path will be utilized by UI to display the hierarchical structure of the tool. If you do not specify a tool structure, the UI will display the tool at the root level.
+- The structure string is not case-sensitive and must only contain characters from "a-zA-Z0-9-_".
+- A maximum of three layers is allowed.
+
+## Specifying Tool Structure
+In the auto-generated tool YAML file, you have the option to customize your tool's structure by directly adding the structure path to the YAML file:
+```
+my_tool_package.tools.my_tool_1.my_tool:
+    name: My First Tool
+    description: This is my first tool
+    structure: test/my_first_tool
+    module: my_tool_package.tools.my_tool_1
+    function: my_tool
+    type: python
+    inputs:
+    connection:
+        type:
+        - CustomConnection
+    input_text:
+        type:
+        - string
+```

docs/how-to-guides/develop-custom-tool/use-tool-icon.md

@@ -0,0 +1,37 @@
+# Tool Icon
+The tool icon serves as a graphical representation of your tool in the user interface (UI). If you do not provide a custom tool icon, the system will use a default one.
+
+## Generating a Tool Icon from a Custom Image
+You can use the following command to generate a data URI for your custom tool icon:
+```
+python scripts\tool\convert_image_to_data_url.py --image-path <image_input_path> -o <html_output_path>
+```    
+For example:
+```
+python scripts\tool\convert_image_to_data_url.py --image-path "AzureContentSafetyIcon.png" -o "output.html"
+```
+- To execute this script, use `pip install pillow`.
+- Supported image formats include `PNG`, `JPG`, and `SVG`.
+- The extension of the output file **must be** `html`. This will generate an HTML file at the specified output file path. To view the result, open the file in a web browser.  
+- The script also checks the size of your image, and if necessary, automatically resizes it to 16*16 pixels. To maintain the quality of your image, consider the following suggestions:  
+   - If possible, provide an image that is 16*16 pixels to avoid distortion from resizing.  
+   - Avoid using complex images with a lot of detail or contrast, as they may not resize well.
+
+## Using the Tool Icon in the Tool YAML File
+In the auto-generated tool YAML file, you can customize your tool's icon by adding the tool icon's data URI directly to the YAML file:
+```
+my_tool_package.tools.my_tool_1.my_tool:
+    name: My First Tool
+    description: This is my first tool
+    icon: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAADDklEQVR4nG1TTWicVRQ9933v+yYZax0a0hBDJ7EIjaUTjTO2KwlCCtaFriJ0oQUhmaVgQrIo5XMMUmNU1EVgxuLGHzCBoW50kQyhUG1DMtqknaS6sCYWaZr+pTOTmXnfe++6GG1V5qwu3HsO53LvodHZ2BoE1pjx3WT/5TP+fJ9MvXBOg0EgMP4GMyiZicv2obwp5w4NCqYXAXRjNBfLAqhPM0tmdpaW0i4AjOd7O98pJHrfvXCoDQB89gX+hdFcLCtg6bzvQzAYRKSJyCQSyeD0L7F+N+zMPxpxfqJI6Oz41cNPpChlT68diaeX4mEAIEM/UN0e0/L6ja7dIhjYvHWjRW1T8WJkZNCEt6NGOYH0yDVV+6OxNu949ApBLFRr5rPxZy/NyukrvkdEauf6bwk30jpx/8/fC0ozOfqRaLG4pYXx2NZgjeFeoxFxFKLWmjbHxVl/vk8SM9Mnm9jbZmtfh00l8YcRC01698TGes9+7Yn0rj2SyneDLWWD4+W7tB4OiWNK8cVPXy4sAiACgPdv8kBTBNPFeyiFWrDr1h28/l4rfTE8m3hONptoUDGXPzq68isaQALAjsGTWoMrDGEBsEKJmYnIWQTsIgD4PkQqBVu/BkSK6rX0mWV1Cx1KgRXDLd60GiRuExEDD6+WSj38iX/IACBLywipNjwDF6JsIEQgbntC3QeA8lfdhz0qRU3grDSduNZwBWGfhlXAufC2LuyrlSqsq19Odey5xOnW10KmvCCbxYzD+rz6fN/zAMDTcP4j0J1J6nQ7nTylr3844laa39pYfCw3m/v4nnx8ipTS1U1TlQ61sMabdcrBBwID0wOOSCYzwRCzu2G95TLom5IMPWUJcWOaHBFAkgVBk2BFpf/bn3l1xoixuZ7h9rfJHOzq+PnbbPaN5trWsdW+I/1C7RxXyrsWcp1QddteUAFNAAAKq9r3IXwfYmyuZ/hBmBrhzmRXZ+mDzt7i1P69jfqjuViWxuZiq0y4ag2+nzy6ciaTT8qheFoDBGoQ50wyH4zkYoPC4iUiHPgLhm17gdgF0NgAAAAASUVORK5CYII=
+    module: my_tool_package.tools.my_tool_1
+    function: my_tool
+    type: python
+    inputs:
+    connection:
+        type:
+        - CustomConnection
+    input_text:
+        type:
+        - string
+```

docs/how-to-guides/index.md

@@ -14,7 +14,7 @@ enable-streaming-mode
 manage-connections
 manage-runs
 column-mapping
-how-to-create-and-use-your-own-tool-package
+develop-custom-tool/index
 faq
 
 ```

src/promptflow-tools/README.md

@@ -7,4 +7,4 @@
 
 Tools are the fundamental building blocks of a flow in Azure Machine Learning prompt flow. Each tool is a simple, executable unit with a specific function, allowing users to perform various tasks. By combining different tools, users can create a flow that accomplishes a wide range of goals. One of the key benefit of prompt flow tools is their seamless integration with third-party APIs and python open source packages. This not only improves the functionality of large language models but also makes the development process more efficient.
 
-In this package, we provide a set of builtin tools of prompt flow, which are the most commonly used tools in the development of AI applications. We also provide a flexible way for users to create their own tools and share them with others. See [Custom tool package creation and usage](https://github.com/microsoft/promptflow/blob/main/docs/how-to-guides/how-to-create-and-use-your-own-tool-package.md) for more details.
+In this package, we provide a set of builtin tools of prompt flow, which are the most commonly used tools in the development of AI applications. We also provide a flexible way for users to create their own tools and share them with others. See [Custom tool package creation and usage](https://github.com/microsoft/promptflow/blob/main/docs/how-to-guides/develop-custom-tool/custom-tool-package-creation-and-usage.md) for more details.