RasaHQ · tmbo · Aug 22, 2023 · Aug 22, 2023 · Aug 23, 2023 · Aug 24, 2023
diff --git a/docs/docs/flows.mdx b/docs/docs/flows.mdx
diff --git a/docs/docs/llms/flow-policy.mdx b/docs/docs/llms/flow-policy.mdx
@@ -0,0 +1,200 @@
+---
+id: flow-policy
+sidebar_label: Flow Policy
+title: Flow Policy
+abstract: |
+  This is a guide to implementing and managing conversational flows using the FlowPolicy.
+---
+
+import RasaDiscoveryBanner from "@theme/RasaDiscoveryBanner";
+import flowStackEvolution from "./flow_stack_evolution.png";
+import flowStackOverview from "./flow_stack.png";
+
+<RasaDiscoveryBanner />
+
+Rasa's Flow Policy is a state machine that allows you to manage and control your
+chatbot's conversational flows. It facilitates the integration of your business
+logic with machine learning capabilities.
+
+The Flow Policy oversees your bot's state, handles state transitions, and
+triggers new flows when needed. The "Flow Stack" represents all started but
+incomplete flows and refers to steps defined in the
+[flows specification](../flows.mdx).
+
+<Image
+  img={flowStackOverview}
+  caption="Flow Stack represents the current state of the conversation referring to a flow."
+  alt=""
+/>
+
+Using the Flow Policy, you can encapsulate your logic into flows, thereby
+guiding the conversation based on user input and system response. Other
+classifiers adjust the underlying state machine to handle edge cases.
+
+For more detailed information on defining flows, refer to the
+[flows specification](../flows.mdx).
+
+## Adding the FlowPolicy to your bot
+
+The Flow Policy can be integrated like [any other policy](../policies.mdx). It
+involves two steps:
+
+1. Configure the `FlowPolicy` in your `config.yml` file:
+
+   ```yaml-rasa title="config.yml"
+   policies:
+   # - ...
+     - name: rasa.core.policies.flow_policy.FlowPolicy
+   # - ...
+   ```
+
+2. Add flows to your bot as per the [flows specification](../flows.mdx). This
+   step involves defining the states and transitions that your bot should
+   recognize and react to.
+
+Once added, the `FlowPolicy` will read all defined flows from your training data
+and apply them.
+
+## How does it work?
+
+The `FlowPolicy` employs a Flow stack structure (Last In First Out) along with
+internal slots to manage your bot's state.
+
+### Managing the State
+
+Your bot's state is managed using a "flow stack". The flow stack stores the
+current position in each started flow. The stack follows a "last in, first out"
+sequence. The last started flow will be completed first, and then earlier
+inserted flows will continue. The flow stack is stored in the `flow_stack` slot.
+
+Here's an example flow and a conversation currently using it:
+
+```yaml title="flows.yml"
+flows:
+  transfer_money:
+    description: This flow enables users to send money to friends and family.
+
+    steps:
+      - id: "start"
+        intent: transfer_money
+        next: "ask_recipient"
+      - id: "ask_recipient"
+        question: transfer_money_recipient
+        next: "ask_amount"
+      - id: "ask_amount"
+        question: transfer_money_amount_of_money
+        next: "check_transfer_funds"
+    # - ...
+```
+
+The flow can be started with the intent `transfer_money`. The first step in the
+flow is `ask_recipient`. A correction by the user, _"oh sorry I meant John"_, 
+initiates a correction flow. This correction is not explicitly modeled in 
+the `transfer_money` flow; it's handled by a conversational pattern:
+
+<Image
+  img={flowStackEvolution}
+  caption="Flow stack changes during a correction of a previous user input"
+  alt=""
+/>
+
+
+
+The correction flow only executes when the user wants to correct a previous
+input. Once triggered, it's placed on top of the flow stack for execution.
+
+For the `transfer_money` flow, the correction flow is an interruption. Once
+completed, the `transfer_money` flow resumes. Before its res umption, a
+`resume_flow` flow is activated. You can customize what happens in `resume_flow`
+and `correction` flows in [Handling Unhappy Paths](./unhappy-paths.mdx).
+
+Upon completion of the `resume_flow` flow, the `transfer_money` flow resumes,
+and the bot returns to the state before the correction flow started. The
+`transfer_money` flow will re-ask the interrupted question.
+
+The `resume_flow` and `correction` flows are conversational patterns not
+explicitly modeled in the `transfer_money` flow. The `FlowPolicy` automatically
+triggers them when needed. For more details on defining conversational patterns,
+refer to [Handling Unhappy Paths](./unhappy-paths.mdx).
+
+### Transitioning Between States
+
+The `FlowPolicy` transitions between states either in response to user inputs or
+after an action's completion. Initially, it awaits user input. Once received, it
+advances the state of the machine until an action prediction is made. After
+completing the action and incorporating its result, it moves to the next state.
+
+### Starting New Flows
+
+Starting a new flow in the `FlowPolicy` can occur in two ways: by user input
+matching the first step in a flow, or by predicting the "flow action".
+
+#### User Input
+
+A user message like _"I want to transfer money"_ will trigger the
+`transfer_money` flow, provided this flow is defined to be initiated by such a
+message:
+
+```yaml title="flows.yml"
+flows:
+  transfer_money:
+    name: Transfer money
+    steps:
+      - id: "1"
+        intent: transfer_money
+        action: action_transfer_money
+      - id: "2"
+        action: utter_lets_transfer_money
+    # - ...
+```
+
+Here, the NLU model predicts the `transfer_money` intent, and as a result, the
+`FlowPolicy` initiates the `transfer_money` flow.
+
+#### Predicting Flow Actions
+
+Another policy predicting the action `flow_transfer_money` will result in the
+`FlowPolicy` initiating the `transfer_money` flow.
+
+### Interruptions and Digressions
+
+Flows and their specifications should ideally model the happy path of a
+conversation. The `FlowPolicy` depends on other components to identify
+digressions and interruptions and interrupt the flow accordingly. For details on
+which digressions and interruptions the flow policy can handle, refer to
+[Handling Unhappy Paths](./unhappy-paths.mdx).
+
+For example, the user message _"oh sorry I meant John"_ is a correction to a
+prior input. The `FlowPolicy` depends on another component, like the
+[LLM Flow Classifier](./llm-flow-classifier.mdx), to identify it as a correction
+and set the corresponding slots. Based on this, the `FlowPolicy` initiates the
+correction flow.
+
+## Configuration
+
+No additional configuration is required for the FlowPolicy beyond what's already
+outlined above.
+
+## FAQs
+
+### Can FlowPolicy be used with other Policies?
+
+Currently, we recommend not using the `FlowPolicy` in conjunction with the
+`RulePolicy`. The `RulePolicy` isn't aware of the flow stack and may interfere
+with the `FlowPolicy`.
+
+### What triggers a flow start?
+
+A flow can be initiated in several ways:
+
+1. One flow can ["link" to another flow](../flows.mdx#next-property), which will
+   initiate the linked flow and return to the original flow once the linked flow
+   completes.
+2. A flow starts when the user message matches the
+   [`user_message` step](../flows.mdx#user-message) of the flow. A
+   match is determined by the intent and entities of the user message.
+3. Flows, which are conversational patterns (e.g. correction, resume flow), are
+   automatically initiated by the `FlowPolicy` when needed.
+4. A flow starts when another policy predicts the corresponding flow action
+   named `flow_{flow_name}`. This action pushes the flow onto the flow stack,
+   and the `FlowPolicy` executes it.
diff --git a/docs/docs/llms/flow_stack.png b/docs/docs/llms/flow_stack.png
diff --git a/docs/docs/llms/flow_stack_evolution.png b/docs/docs/llms/flow_stack_evolution.png
diff --git a/docs/docs/llms/large-language-models.mdx b/docs/docs/llms/large-language-models.mdx
@@ -6,6 +6,7 @@ className: hide
 abstract:
 ---
 
+import llmUsageArchitecture from "./llm-usage-architecture.png";
 import RasaLabsLabel from "@theme/RasaLabsLabel";
 import RasaLabsBanner from "@theme/RasaLabsBanner";
 
@@ -50,15 +51,31 @@ It's essential that your system provides full
 control over these processes. Understanding how LLMs and other components
 behave and have the power to override any decision.
 
+### Orchestration at the center
+
+A robust future-proof architecture leverages multiple LLMs for multiple
+jobs. And it puts the orchestration of components at the center, with the LLMs
+as exchangeable utilities / components in various places.
+
+<Image
+  img={llmUsageArchitecture}
+  caption="LLM Component usage in Rasa"
+  alt=""
+/>
+
+LLMs are a key component of a future-proof architecture. More importantly,
+we have the flexibility to use different LLMs for different purposes
+and can plug the models of our choice as the technology evolves.
+
 ## Where to go from here
 
 This section of the documentation guides you through the diverse ways you can
 integrate LLMs into Rasa. We will delve into the following topics:
 
 1. [Setting up LLMs](./llm-setup.mdx)
-2. [Intentless Policy](./llm-intentless.mdx)
-4. [LLM Intent Classification](./llm-intent.mdx)
-5. [Response Rephrasing](./llm-nlg.mdx)
+2. [Dialogues with LLMs & Flows](./llm-dialogue.mdx)
+3. [Business Logic with Flows](../flows.mdx)
+4. [Handling Unhappy Paths](./unhappy-paths.mdx)
 
 Each link will direct you to a detailed guide on the respective topic, offering
 further depth and information about using LLMs with Rasa. By the end of this

diff --git a/docs/docs/llms/llm-detector.mdx b/docs/docs/llms/llm-detector.mdx
@@ -0,0 +1,13 @@
+---
+id: llm-detector
+sidebar_label: Detecting Out Of Scope
+title: Detecting Out-Of-Scope
+abstract: |
+    Detection of out of scope topics in a conversation. 
+---
+
+import RasaDiscoveryBanner from "@theme/RasaDiscoveryBanner";
+
+<RasaDiscoveryBanner />
+
+- explain how to use a flow and a prompt to detect a sensitive topics
diff --git a/docs/docs/llms/llm-dialogue.mdx b/docs/docs/llms/llm-dialogue.mdx
@@ -0,0 +1,88 @@
+---
+id: llm-dialogue
+sidebar_label: Dialogues with LLMs & Flows
+title: Dialogues with LLMs & Flows
+abstract: |
+  This documentation explores dialogue management by combining Large Language Models (LLMs) and business logic through Flows.
+---
+
+import RasaDiscoveryBanner from "@theme/RasaDiscoveryBanner";
+
+<RasaDiscoveryBanner />
+
+## Motivation
+
+Our approach aims to harness the strengths of both Large Language Models (LLMs)
+and the control needed for business logic. This innovative blend enables you to
+manage both the flexible and predictable aspects of dialogues within your
+chatbot.
+
+By utilizing LLMs, we can effectively handle ["unhappy paths"—instances](../glossary.mdx#happy--unhappy-paths) where
+user interactions diverge from the expected or desired course. Meanwhile,
+business logic or 'Flows' are used to manage ["happy paths"—scenarios](../glossary.mdx#happy--unhappy-paths) where
+interactions proceed as anticipated.
+
+Combining LLMs and Flows helps prevent "black box" behaviors, whereby the
+chatbot's responses can seem inexplicable or out of control. With this method,
+you only need to specify a minimal amount of business logic. At the same time,
+it opens up a wide range of possibilities for customizing your chatbot's
+dialogue behavior.
+
+## Approach
+
+Here's a breakdown of our approach:
+
+- We specify 'happy paths' using business logic. This means setting out clear,
+  pre-defined paths that the conversation should follow under ideal
+  circumstances using [Flows](../flows.mdx).
+- We identify patterns of 'unhappy paths' and specify these using separate
+  Flows. These [conversational patterns](./unhappy-paths.mdx) define how the
+  chatbot should respond when the user's input doesn't match the expected course
+  of a flow.
+- We use Flows to keep track of the conversation's state, ensuring we always
+  know where we are in the dialogue and what's been covered.
+- We employ LLMs to update the state of these Flows. These language models
+  process user input, adjusting the conversation's course as needed.
+- We use LLMs to [improve the chatbot's responses](./llm-nlg.mdx). These
+  language models generate the chatbot's responses, ensuring they feel natural and
+  fluent.
+
+## Configuration and Setup
+
+In order to set up and configure this approach:
+
+- You'll first need to get the `dm2` branches of `rasa` and `rasa-plus`. 
+  All components are implemented on these branches.
+- Next, you'll need to configure the `config.yml` file to ensure your bot
+  recognizes and applies this combination of LLMs and Flows.
+
+An example configuration file is shown below:
+
+```yaml title="config.yml"
+recipe: default.v1
+language: en
+pipeline:
+  - name: LLMFlowClassifier
+
+policies:
+  - name: rasa.core.policies.flow_policy.FlowPolicy
+  - name: RulePolicy
+```
+
+To use the rephrasing capability, you'll also need to add the following to your
+endpoint configuration:
+
+```yaml title="endpoints.yml"
+nlg:
+  type: rasa_plus.ml.LLMResponseRephraser
+```
+
+Additional configuration parameters are explained in detail in the documentation
+pages for each of these components:
+- [LLMFlowClassifier](./llm-flow-classifier.mdx)
+- [FlowPolicy](./flow-policy.mdx)
+- [LLMResponseRephraser](./llm-nlg.mdx) 
+
+## Example Conversation
+
+[Example conversation goes here]