review

Author: sr-remsha

docs/tutorials/1.developers/4.apps-development/3.enable-app.md

@@ -14,10 +14,11 @@ DIAL-native applications can be categorized as either schema-rich or apps withou
 
 ##### Schema-rich applications
 
-Schema-rich apps, in comparison with apps without schemas, allow users to create instances of applications with different properties via DIAL Core API that are normally hidden in the app's internal environment and cannot be changed. There is a method in DIAL SDK (`application_properties = await request.request_dial_application_properties()`) that returns application properties with a configuration request to DIAL Core.
-This goes beyond simply adjusting the basic settings of an application container, offering dynamics and flexibility compared to apps without schemas.
+[Schema-rich applications](#enable-schema-rich-applications) enable users to create instances of applications with different properties via [DIAL Core API](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomApplication). Unlike apps without schemas, where business logic properties are embedded in the application code or container environment and are difficult to access, schema-rich applications provide greater flexibility. 
 
-[Schema-rich applications](#enable-schema-rich-applications) are defined by a JSON schema that conforms to the main [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema). JSON schema describes the application's structure, including properties and endpoints (completion, configuration, and other), can include URLs for application editor (enabling a wizard in the UI for creating/editing applications) and custom application UI, [custom buttons](/docs/tutorials/1.developers/4.apps-development/1.custom-buttons.md) used by the application.
+Schema-rich applications are defined by a JSON schema that conforms to the main [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema). JSON schema describes the application's structure, including properties and endpoints (completion, configuration, and other), can include URLs for application editor (enabling a wizard in the UI for creating/editing applications) and custom application UI, [custom buttons](/docs/tutorials/1.developers/4.apps-development/1.custom-buttons.md) used by the application.
+
+There is a method in [DIAL SDK](https://github.com/epam/ai-dial-sdk) (`application_properties = await request.request_dial_application_properties()`) that returns application properties with a configuration request to DIAL Core.
 
 Schema-rich applications are usually associated with a specific **Application Type** - a template for creating applications of that type.  
 
@@ -56,7 +57,7 @@ Send a [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomAppl
   - If `applicationTypeSchemaId` is provided but `applicationProperties` are `NULL`, the application is considered a "stub" and can be updated later, but completion requests will not be possible until then.
   - For applications with schemas, all requests are routed **ONLY** to endpoints specified in the schema. If you specify endpoints in the [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomApplication) request, such request will fail.
 
-    Example:
+    Example of a PUT request body: 
 
     ```json
     {
@@ -93,7 +94,7 @@ JSON Schemas of application types can include `applicationTypeEditorUrl` to enab
 
 DIAL admins can create schema-rich applications by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration in the `applications` section.
 
-Example:
+Example of dynamic settings in DIAL Core:
 
 ```json
  "applications":
@@ -127,7 +128,7 @@ To enable such an app in DIAL, you can add its representation in JSON format dir
 
 Send a [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomApplication) request to DIAL Core, where in the request body you provide specific endpoints and parameters for your application. You can see them in DIAL Core documentation under the [dynamic setting](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) for `applications`.
 
-Example: 
+Example of a PUT request body: 
 
 ```json
 {
@@ -161,7 +162,7 @@ The configuration of an application is saved as a BLOB in the DIAL Core file sys
 
 DIAL admins can create an application by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration for the `applications` section.
 
-Example:
+Example of dynamic settings in DIAL Core:
 
 ```json
  "applications": {
@@ -193,10 +194,11 @@ If you enable your application by directly modifying the [DIAL Core configuratio
 
 ##### Example
 
-In the following example, the `my_app` application is accessible to users with the `app_user` role. For this user role, usage limits are set on the `chat-gpt-35-turbo` model, as specified in the `limits` section. When a user with the `app_user` role uses the application, the app will use the `chat-gpt-35-turbo` model within these prescribed limits.
+Applications use language models on behalf of users and within the defined limits, provided both model and application can be accessed by a specific user role.
 
-Applications use language models on behalf of users, provided both model and application can be accessed by a specific user role. In this case, costs of using a model are defined by the limits configured for a specific user role.
+In the following example, the `my_app` application is accessible to users with the `app_user` role. For this user role, usage limits are set on the `chat-gpt-35-turbo` model, as specified in the `limits` section. When a user with the `app_user` role uses the application, the app will use the `chat-gpt-35-turbo` model within these prescribed limits.
 
+Example of dynamic settings in DIAL Core:
 
 ```json
 "applications":
@@ -227,35 +229,27 @@ You can use DIAL UI and API to publish and/or share applications with other user
 
 Applications can rely on resources like documents and files to operate. When the application is shared or published, it is crucial to ensure that these resources are accessible, if needed, to all involved parties in the operation flow.
 
-Access to application files can be necessary in the following scenarios:
-
-1. When an application is shared with other users
-2. When an application is published
-3. When files are supplied by a user to an application
-4. When files are shared as part of a request from one application to another
-
-Handling of these scenarios differs significantly between schema-rich applications and those without schemas.
+Providing access to application files differs significantly between schema-rich applications and those without schemas.
 
 ##### For applications without schemas
 
-Developers must incorporate custom logic to handle file access when the application is shared or published. It requires careful implementation to ensure all necessary resources are available for authorized users and apps.
+Developers must incorporate a programming logic into the application to handle file access when the application is shared or published. It requires careful implementation to ensure all necessary resources are available for authorized users and apps.
 
 ##### For schema-rich applications
 
-The JSON schema of schema-rich apps can include links to resources (e.g., files or documents). 
+In schema-rich applications, **auto-share** principle applies to handle access to files. 
 
-The following logic applies to resources marked with the `"dial_file": true` property, regardless of whether the app was enabled via configuration or created using the UI or API:
+JSON schema of schema-rich apps can include links to resources (e.g., files or documents) that are required by the application to operate. Auto-share logic applies to all resources marked as `"dial_file": true`. If the resource is marked as `"dial_file": true`, it will be **automatically** shared when this application is shared with other users, published or as part of a requests chain between applications. **Important**: To prevent specific resources from being shared automatically, avoid using `"dial_file": true` in schema.
 
-* Files are automatically shared or published alongside the application (scenarios 1 and 2).
-* Files are automatically included in chat completion requests or when making API calls between applications (scenarios 3 and 4).
+Let's consider the following scenario as an example:
 
-![](../img/files-sharing.svg)
-
-**Important**: To prevent specific resources from being shared automatically, avoid marking their schema properties with `"dial_file": true`. 
+1. A DIAL Chat user initiates a conversation with a schema-rich RAG application (App1).
+2. DIAL Core issues a [per-request API key](/docs/platform/3.core/3.per-request-keys.md#files-sharing) for this request.
+3. DIAL Core checks the schema of the App1 and gives READ access for the per-request API key to all files marked as `"dial_file": true`. This way, the application automatically gets access to necessary files to generate responses. 
 
-##### Example  
+![](../img/files-sharing2.svg)
 
-A schema for a RAG application might define a field like `rag_files`:  
+Schema for such application can include:  
 
 ```json
 "rag_files": {
@@ -267,15 +261,17 @@ A schema for a RAG application might define a field like `rag_files`:
 }
 ```
 
-In the actual configuration of the application, the referenced files look as follows:  
+Configuration of the application in DIAL Core dynamic settings can include a path to a specific file that will be shared:  
 
 ```json
 "applicationProperties": {
 	"rag_files": ["files/csdvsdvsd/my_file.docx"]
 }
 ```
 
-In this example, the files listed in the `rag_files` field will automatically follow the sharing behavior described above.  
+Similarly, if App1 was to call App2 to perform a specific action, another per-request API key would be issued with access to App2 files: 
+
+![](../img/files-sharing.svg)
 
 ## Enable NOT DIAL-Native Apps
 

docs/tutorials/1.developers/4.apps-development/5.quick-app-configuration.md

@@ -6,7 +6,7 @@ Quick app is one of the [application types](/docs/platform/0.architecture-and-co
 
 Quick app application type is [schema-rich](/docs/tutorials/1.developers/4.apps-development/3.enable-app.md#schema-rich-applications) - the structure of custom applications of this type is defined by the JSON schema of Quick apps. This document provides a detailed overview of the Quick app JSON schema, explaining the available configuration options primarily useful if you are creating Quick apps using DIAL API.
 
-Quick apps are code-less and conceptually similar to OpenAI's GPTs. They can include tools such as client toolsets, web API toolsets, use apps and models deployed in DIAL as tools and URLs to files to perform specific actions. For example, you can create an app with a toolset allowing it to call an external API to get a real-time weather forecast for a specific location. Another example is a RAG-like application that can generate responses based on predefined sources.
+Quick apps are code-less and conceptually similar to OpenAI's GPTs. They can include tools such as client toolsets, web API toolsets, use apps and models deployed in DIAL as tools and URLs to files for RAG. For example, you can create an app with a toolset allowing it to call an external API to get a real-time weather forecast for a specific location. Another example is a RAG-like application that can generate responses based on predefined sources.
 
 > * Watch a [Demo Video](/docs/video%20demos/2.Applications/5.quick-apps.md) with an introduction to Quick Apps.
 > * Refer to [Enable App](/docs/tutorials/1.developers/4.apps-development/3.enable-app.md) to learn how to enable Quick apps that you create in DIAL and make them available for other users.
@@ -27,7 +27,7 @@ The structure of Quick app applications is defined by the schema with ID `https:
 
 ## Starter Buttons
 
-You can enhance user interactions in your application by adding buttons, known as starters, at the beginning of the conversation. These buttons allow users to take specific actions to launch a conversation.
+You can enhance user interactions in your application by adding buttons, known as starters, at the beginning of the conversation. These buttons allow users to select a predefined message to launch a conversation.
 
 Use `starters` to enable starter buttons.
 
@@ -49,10 +49,10 @@ Use `starters` to enable starter buttons.
 
 Use tools to extend the functionality of your Quick App. Applications or models deployed in DIAL, external services and web APIs can serve as tools.
 
-### Apps & Models
+### Apps & Models as Tools
 
 Your Quick app can be configured to use other applications and models deployed in DIAL as tools to perform specific actions.
-Use `applications_as_tools` property of the Quick app schema to enable this. It can reference
+Set `applications_as_tools` property in your Quick app to enable this. It can reference
 specific applications/models by their IDs or use groups of [conditions](#conditions) to dynamically match applications/models based on specific properties.
 
 | Field                   | Type   | Required | Description    | Example   |
@@ -72,7 +72,7 @@ specific applications/models by their IDs or use groups of [conditions](#conditi
 ##### Conditions
 
 `applications_as_tools` can accept both direct application/model IDs as `strings` and `conditions` objects that
-define matching criteria for applications/models. If provided both, `conditions` object logically serves as AND in relation to `string`. The objects within the `conditions` array are combined using a logical OR operation.
+define matching criteria for applications/models. If provided both, `conditions` object logically serves as OR in relation to `string`. The objects within the `conditions` array are combined using a logical AND operation.
 
 ##### Example in which two tools are enabled RAG and Copilot Deck App
 
@@ -139,7 +139,7 @@ You can match applications/models based on these properties:
 
 Your application can use external tools that can be invoked outside of the Quick app application. Include the `client_toolset` property to enable this. 
 
-Unlike apps and models as tools, when the LLM decides to call a `client_toolset` tool, the processing chain is stopped, and Quick app responds with a `tool_call` message. 
+Unlike apps and models as tools, when the LLM decides to call a `client_toolset` tool, the processing chain is stopped, and Quick app responds with AI message with a `tool_call`. 
 The response also includes additional metadata (`intermediate_steps_to_restore`) that needs to be sent back to Quick app along with the `tool_call` result once the tool execution is completed to ensure proper flow restoration. 
 
 ##### Example
@@ -223,7 +223,7 @@ Each `WebApiToolsetInfo` object has the following structure:
 
 | Field            | Type                                                         | Required | Description                                    |
 |------------------|--------------------------------------------------------------|:----------:|------------------------------------------------|
-| `tool_endpoints` | array of `ToolEndpointInfo`                                    | Yes      | Collection of endpoints the tool can call. Refer to [Tool Endpoints Definition](#tool-endpoints-definition)for details.    |
+| `tool_endpoints` | array of `ToolEndpointInfo`                                    | Yes      | Collection of endpoints the tool can call. Refer to [Tool Endpoints Definition](#tool-endpoints-definition) for details.    |
 | `auth_info`      | `WebApiToolsetKeyAuthInfo` or null | Yes      | Authentication configuration for the endpoints. Refer to [API Key Authentication](#api-key-authentication) for details. |
 
 ##### Tool Endpoints Definition
@@ -330,7 +330,10 @@ Provide these parameters to configure authentication for the web API endpoints.
 
 ### RAG Integration
 
-Retrieval Augmented Generation (RAG) is integrated into Quick Apps as a tool named `query_document` with the `description`. When writing instructions for applications that use RAG, we recommend following these guidelines:
+Retrieval Augmented Generation (RAG) is integrated into Quick Apps as a tool named `query_document` with the `description: "Ask RAG a question about the documents assuming it will have access to the conversation history."`. When writing instructions for applications using
+RAG, you should explicitly mention the need to query the document first before answering questions. 
+
+For optimal results, the instructions should:
 
 1. Direct application to use the RAG tool to retrieve relevant information.
 2. Explicitly state to use only the information found in the documents.