Flow policy experimental docs (#12523)

* added flow polciy documentation

* Apply suggestions from code review

Co-authored-by: Maxime Vdb <m.verger@rasa.com>

* made suggested docs improvmenets

---------

Co-authored-by: Maxime Vdb <m.verger@rasa.com>

docs/docs/llms/flow-policy.mdx

@@ -3,9 +3,208 @@ id: flow-policy
 sidebar_label: Flow Policy
 title: Flow Policy
 abstract: |
-  Running Flows with the FlowPolicy.
+  Guide on implementing and managing Flows with the FlowPolicy.
 ---
 
 import RasaDiscoveryBanner from "@theme/RasaDiscoveryBanner";
+import flowStackEvolution from "./flow_stack_evolution.png";
+import flowStackOverview from "./flow_stack.png";
 
-<RasaDiscoveryBanner/>
+<RasaDiscoveryBanner />
+
+The Flow Policy in Rasa is a state machine that enables you to manage
+conversational flows in your chatbot and combine your business logic with
+machine learning.
+
+The policy manages the state of your bot, transitioning between states, and
+initiating new flows when required. The "Flow Stack" represents all flows that
+have been started and not yet completed and reference steps defined using the
+[flows specification](../flows.mdx).
+
+<Image
+  img={flowStackOverview}
+  caption="Flow Stack reflecting the state of the conversation referencing a flow."
+  alt=""
+/>
+
+The policy allows you to express your logic in flows, shaping the way a
+conversation progresses based on user input and system response. Other
+classifiers will modify the underlying state machine to handle edge-cases.
+
+Please refer to the [flows specification](../flows.mdx) for detailed information
+on defining flows.
+
+## Adding the `FlowPolicy` to your bot
+
+The flow policy can be used like [any other policy](../policies.mdx).
+Incorporating the `FlowPolicy` into your bot involves a two-step process. First,
+you need to configure the `FlowPolicy` in your `config.yml` file. The
+configuration ensures that your bot recognizes and applies the `FlowPolicy` when
+running:
+
+```yaml-rasa title="config.yml"
+policies:
+# - ...
+  - name: rasa.core.policies.flow_policy.FlowPolicy
+# - ...
+```
+
+Second, you need to add flows to your bot in accordance with the
+[flows specification](../flows.mdx). This step involves defining the states and
+transitions your bot should recognize and respond to.
+
+Once added, the `FlowPolicy` will read all defined flows from your training data
+and apply them.
+
+## How does it work?
+
+The `FlowPolicy` leverages a Flow stack structure (Last In First Out) together
+with internal slots to manage the state of your bot.
+
+### Managing the State
+
+The state of your bot is managed using a "flow stack". The flow stack stores the
+position in each started flow. The stack is ordered as "last in, first out"
+queue. The flow that got started last, will be completed first, before flows
+inserted earlier will be continued. The flow stack is stored in the `flow_stack`
+slot.
+
+Let's take the following example flow and a conversation that is currently using
+it:
+
+```yaml title="flows.yml"
+flows:
+  transfer_money:
+    description: This flow let's users 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"
+    # - ...
+```
+
+<Image
+  img={flowStackEvolution}
+  caption="Changes to the flow stack during a correction of a prior user input"
+  alt=""
+/>
+
+The correction _"oh sorry I meant John"_ from the user triggers a correction
+flow to be started. This **correction is not explicitly modeled** in the
+`transfer_money` flow but rather handled by a so called "conversational
+pattern".
+
+The correction flow is only executed when the user wants to correct a prior
+input. When triggered, the correction flow is put on top of the flow stack and
+executed.
+
+From the `transfer_money` flow, the correction flow is an interruption. Once the
+correction flow is completed, the `transfer_money` flow is resumed. Before the
+`transfer_money` is resumed, the `resume_flow` flow is triggered. What happens
+in the `resume_flow` and `correction` flows can be
+[customized](./unhappy-paths.mdx).
+
+Once the `resume_flow` flow is completed, the `transfer_money` flow is resumed
+and the bot is back in the state it was before the correction flow was started.
+The `transfer_money` flow will re-ask the question that was interrupted by the
+correction flow.
+
+Both, the `resume_flow` and the `correction` flow are "conersational patterns"
+that are not explicitly modeled in the `transfer_money` flow. They are
+automatically triggered by the `FlowPolicy` when required. Details on how to
+define conversational patterns can be found in
+[Handling Unhappy Paths](./unhappy-paths.mdx).
+
+### Transitioning Between States
+
+The `FlowPolicy` transitions between states in response to user inputs or after
+an action has been completed. Initially, it waits for user input. Once received,
+it advances the state of the machine until it makes an action prediction. After
+the action has been completed and its result incorporated, it continues
+advancing to the next state.
+
+### Starting New Flows
+
+Starting a new flow in the `FlowPolicy` can be done in one of two ways. Either,
+by user input that matches the first step in a flow or by predicting the "flow
+action".
+
+#### User Input
+
+The user message _"i want to transfer money"_ will trigger a flow
+`transfer_money` if this flow is defined to be triggered by this message, e.g.:
+
+```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
+    # - ...
+```
+
+The NLU model will predict the intent `transfer_money` and the `FlowPolicy` will
+start the flow `transfer_money` as a result.
+
+#### Predicting Flow Actions
+
+Another policy can predict the action `flow_transfer_money` and the `FlowPolicy`
+will start the flow `transfer_money` as a result.
+
+### Interruptions and Digressions
+
+Flows and their specification should model the happy path of a conversation.
+Digressions and interruptions are not explicitly modeled in a flow. Instead, the
+`FlowPolicy` relies on other components to identify these cases and interrupt
+the flow. The digressions and interruptions the flow policy is able to handle
+are documented in [Handling Unhappy Paths](./unhappy-paths.mdx).
+
+Sometimes, the user might provide something that a flow does not expect. The
+`FlowPolicy` does not identify these cases itself, but relies on other
+components to identify these cases and interrupt the flow.
+
+For example, the user message _"oh sorry I meant John"_ is a correction to a
+prior input. The `FlowPolicy` relies on another component to identify that this
+is a correction and set the corresponding slots, e.g. the
+[LLM Flow Classifier](./llm-flow-classifier.mdx). Based on this, the
+`FlowPolicy` will then start the correction flow.
+
+## Configuration
+
+Currently, there is no additional configuration required for the FlowPolicy
+beyond what has been outlined above.
+
+## FAQ
+
+### Using the FlowPolicy with other Polices
+
+Currently, we recommend to avoid using the `FlowPolicy` together with the
+`RulePolicy`. The `RulePolicy` is not aware of the flow stack and its
+predictions are known to interfere with the `FlowPolicy`.
+
+### What triggers the start of a flow?
+
+A flow can be started in multiple ways:
+
+1. one flow can ["link" to another flow](../flows.mdx#next-next), which will
+   start the linked flow and return to the original flow once the linked flow is
+   completed.
+2. a flow will be started when the user message matches the
+   [`user_message` step](../flows.mdx#user-message-user_message) of the flow. A
+   match is based on the intent and entities of the user message.
+3. Flows, which are "comversational patterns" (e.g. correction, resume flow) are
+   started automatically by the `FlowPolicy` when required.
+4. A flow will be started when another policy predicts the corresponding flow
+   action named `flow_{flow_name}`. This action will push the flow onto the flow
+   stack and the `FlowPolicy` will run it.