GITBOOK-17: zorroj's Nov 7 changes

en/SUMMARY.md

@@ -22,6 +22,7 @@
 * [Prompt Engineering](application/prompt-engineering/README.md)
   * [Text Generator](application/prompt-engineering/text-generation-application.md)
   * [Conversation Application](application/prompt-engineering/conversation-application.md)
+  * [External-data-tool](application/prompt-engineering/external\_data\_tool.md)
 * [Developing with APIs](application/developing-with-apis.md)
 * [Logs & Annotations](application/logs.md)
 
@@ -52,7 +53,11 @@
   * [OpenLLM](advanced/model-configuration/openllm.md)
   * [LocalAI](advanced/model-configuration/localai.md)
 * [More Integration](advanced/more-integration.md)
-* [API-based Extension](advanced/api\_based\_extension.md)
+* [Extension](advanced/extension/README.md)
+  * [API-based Extension](advanced/extension/api\_based\_extension/README.md)
+    * [External\_data\_tool](advanced/extension/api\_based\_extension/external\_data\_tool.md)
+    * [Moderation](advanced/extension/api\_based\_extension/moderation.md)
+  * [Code-based Extension](advanced/extension/code-based-extension.md)
 
 ## use cases
 

en/advanced/extension/README.md

@@ -0,0 +1,10 @@
+# Extension
+
+In the process of creating AI applications, developers face constantly changing business needs and complex technical challenges. Effectively leveraging extension capabilities can not only enhance the flexibility and functionality of applications but also ensure the security and compliance of enterprise data. Dify offers the following two methods of extension:
+
+[api\_based\_extension](api\_based\_extension/ "mention")
+
+[code-based-extension.md](code-based-extension.md "mention")
+
+
+

en/advanced/extension/api_based_extension/external_data_tool.md

@@ -0,0 +1,62 @@
+# External\_data\_tool
+
+When creating AI applications, developers can use API extensions to incorporate additional data from external tools into prompts as supplementary information for LLMs.
+
+Please read [.](./ "mention") to complete the development and integration of basic API service capabilities.
+
+### Extension Point
+
+`app.external_data_tool.query`: Apply external data tools to query extension points.
+
+This extension point takes the application variable content passed in by the end user and the input content (fixed parameters for conversational applications) as parameters to the API. Developers need to implement the query logic for the corresponding tool and return the query results as a string type.
+
+#### Request Body
+
+```json
+{
+    "point": "app.external_data_tool.query", 
+    "params": {
+        "app_id": string,  
+        "tool_variable": string,  
+        "inputs": {  
+            "var_1": "value_1",
+            "var_2": "value_2",
+            ...
+        },
+        "query": string | null  
+    }
+}
+```
+
+* Example
+
+```json
+{
+    "point": "app.external_data_tool.query",
+    "params": {
+        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
+        "tool_variable": "weather_retrieve",
+        "inputs": {
+            "location": "London"
+        },
+        "query": "How's the weather today?"
+    }
+}
+```
+
+#### API Response
+
+```json
+{
+    "result": string
+}
+```
+
+* Example
+
+```json
+{
+    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
+}
+```
+

en/advanced/extension/api_based_extension/moderation.md

@@ -0,0 +1,148 @@
+# Moderation
+
+This module is used to review the content input by end-users and the output from LLMs within the application, divided into two types of extension points.
+
+Please read [.](./ "mention") to complete the development and integration of basic API service capabilities.
+
+## Extension Point
+
+`app.moderation.input`: End-user input content review extension point. It is used to review the content of variables passed in by end-users and the input content of dialogues in conversational applications.
+
+`app.moderation.output`: LLM output content review extension point. It is used to review the content output by LLM. When the LLM output is streaming, the content will be requested by the API in segments of 100 characters to avoid delays in review when the output content is lengthy.
+
+### `app.moderation.input`
+
+#### Request Body
+
+```json
+{
+    "point": "app.moderation.input", 
+        "app_id": string,  
+        "inputs": {  
+            "var_1": "value_1",
+            "var_2": "value_2",
+            ...
+        },
+        "query": string | null  
+    }
+}
+```
+
+* Example
+
+```json
+{
+    "point": "app.moderation.input",
+    "params": {
+        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
+        "inputs": {
+            "var_1": "I will kill you.",
+            "var_2": "I will fuck you."
+        },
+        "query": "Happy everydays."
+    }
+}
+```
+
+#### API Response
+
+```json
+{
+    "flagged": bool,  
+    "action": string, 
+    "preset_response": string,  
+    "inputs": {  
+        "var_1": "value_1",
+        "var_2": "value_2",
+        ...
+    },
+    "query": string | null  
+}
+```
+
+* Example
+
+`action=direct_output`
+
+```json
+{
+    "flagged": true,
+    "action": "direct_output",
+    "preset_response": "Your content violates our usage policy."
+}
+```
+
+`action=overrided`
+
+```
+{
+    "flagged": true,
+    "action": "overrided",
+    "inputs": {
+        "var_1": "I will *** you.",
+        "var_2": "I will *** you."
+    },
+    "query": "Happy everydays."
+}
+```
+
+### `app.moderation.output`
+
+#### Request Body
+
+```JSON
+{
+    "point": "app.moderation.output", 
+    "params": {
+        "app_id": string,  
+        "text": string  
+    }
+}
+```
+
+*   Example
+
+
+
+    ```JSON
+    {
+        "point": "app.moderation.output",
+        "params": {
+            "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
+            "text": "I will kill you."
+        }
+    }
+    ```
+
+#### API Response
+
+```JSON
+{
+    "flagged": bool,  
+    "action": string, 
+    "preset_response": string,  
+    "text": string  
+```
+
+* Example
+
+`action=direct_output`
+
+* ```JSON
+  {
+      "flagged": true,
+      "action": "direct_output",
+      "preset_response": "Your content violates our usage policy."
+  }
+  ```
+
+`action=overrided`
+
+* ```JSON
+  {
+      "flagged": true,
+      "action": "overrided",
+      "text": "I will *** you."
+  }
+  ```
+

en/advanced/extension/code-based-extension.md

@@ -0,0 +1,8 @@
+# Code-based Extension
+
+For developers deploying Dify locally who wish to implement extension capabilities, there is no need to rewrite an API service. Instead, they can use Code-based Extension, which allows for the expansion or enhancement of the program's capabilities in the form of code (i.e., plugin capabilities) on top of Dify's existing features, without disrupting the original code logic of Dify. It follows certain interfaces or specifications to ensure compatibility and pluggability with the main program. Currently, Dify has opened up two types of Code-based Extensions, which are:
+
+* Add a new type of external data tool 
+* Expand sensitive content review policies
+
+On the basis of the above functions, you can follow the specifications of the code-level interface to achieve the purpose of horizontal expansion.

en/application/prompt-engineering/external_data_tool.md

@@ -0,0 +1,30 @@
+# External-data-tool
+
+Previously, [datasets](../../advanced/datasets/ "mention") allowed developers to directly upload long texts in various formats and structured data to build datasets, enabling AI applications to converse based on the latest context uploaded by users. With this update, the external data tool empowers developers to use their own search capabilities or external data such as internal knowledge bases as the context for LLMs. This is achieved by extending APIs to fetch external data and embedding it into Prompts. Compared to uploading datasets to the cloud, using external data tools offers significant advantages in ensuring the security of private data, customizing searches, and obtaining real-time data.
+
+## What does it do?
+
+When end-users make a request to the conversational system, the platform backend triggers the external data tool (i.e., calling its own API), which queries external information related to the user's question, such as employee profiles, real-time records, etc. The tool then returns through the API the portions relevant to the current request. The platform backend will assemble the returned results into text as context injected into the Prompt, in order to produce replies that are more personalized and meet user needs more accurately.
+
+## Quick Start
+
+1. Before using the external data tool, you need to prepare an API and an API Key for authentication. Head to [external\_data\_tool.md](../../advanced/extension/api\_based\_extension/external\_data\_tool.md "mention").
+2. Dify offers centralized API management; After adding API extension configurations in the settings interface, they can be directly utilized across various applications on Dify.
+
+<figure><img src="../../.gitbook/assets/api_based.png" alt=""><figcaption><p>API-based Extension<br></p></figcaption></figure>
+
+3. Taking "Query Weather" as an example, enter the name, API endpoint, and API Key in the "Add New API-based Extension" dialog box. After saving, we can then call the API.
+
+<figure><img src="../../.gitbook/assets/api_based_extension.png" alt=""><figcaption><p>Weather Inquiry</p></figcaption></figure>
+
+4. On the prompt orchestration page, click the "+ Add" button to the right of "Tools," and in the "Add Tool" dialog that opens, fill in the name and variable name (the variable name will be referenced in the Prompt, so please use English), as well as select the API-based extension added in Step 2.
+
+<figure><img src="../../.gitbook/assets/api_based_extension1.png" alt=""><figcaption><p>External_data_tool</p></figcaption></figure>
+
+5. In the prompt orchestration box, we can assemble the queried external data into the Prompt. For instance, if we want to query today's weather in London, we can add a variable named `location`, enter "London", and combine it with the external data tool's extension variable name `weather_data`. The debug output would be as follows:
+
+<figure><img src="../../.gitbook/assets/Weather_search_tool.jpeg" alt=""><figcaption><p>Weather_search_tool</p></figcaption></figure>
+
+In the Prompt Log, we can also see the real-time data returned by the API:
+
+<figure><img src="../../.gitbook/assets/log.jpeg" alt="" width="335"><figcaption><p>Prompt Log</p></figcaption></figure>