Clarify docs around slots and rules

Following up on this bug and the discussion it started, there are numerous clarifications that should be added to our docs. The main reason these live in a separate issue is that we wanted to ship a simple bugfix asap.

Clarifications re unset featurised slots There are many important facts, some of them scattered around the docs, others not mentioned at all. These should be compiled and collected in one place:

• a slot is originally unset (unless it has initial_value defined)
• this means its value is the Pythonic None
• where such a slot influences_conversation, Rasa Core is aware that it’s unset (the featurisation differs from when the slot is set to some legit value)
• in Python (custom actions), we unset a slot by setting it to None; in stories/rules, we write slot_name: null
• categorical slots can’t have the Pythonic None as a possible value. None (in domain.yml written as null) is reserved for when the slot is unset. However, "null" (quoted as a string) can be listed in the domain as a slot’s possible value, and so can be "None".

Clarification re featurisation of categorical slots We should make it absolutely clear in the docs that featurisation of categorical slots is done by casting both the possible slot values and the value to be featurised as str, and then lower-casing them. I.e. slot values are case-insensitive and, in case of values that aren’t strings, users should think about what the string-casted values will be.

Clarification re slot-agnostic vs slot-conditioned rules/stories What does it mean if a conversation-influencing slot isn’t mentioned in some given rule? If, for some given context, a rule prescribes certain next steps irrespective of slots, and another rule (or a story) for the same context specifies different behaviour while conditioning on slots, then these two rules/stories are in conflict. It may feel a bit surprising but it makes sense. A good example of this is reported here and elaborated on here. We should definitely mention this in the docs, especially for when people are writing rules.

Clarification re precedence of rules As pointed out by @kedz, our docs don’t mention how we decide which rule to apply when multiple rules are applicable. In reality, what we do is comparing the lengths of the rule keys in their string form. An example rule key of length 88 is: `[{“prev_action”:

{“action_name”: “action_listen”}

, “user”: {“intent”: “bot_challenge”}}]`. We assume that, where multiple rules are applicable, one must be a subset of the other (i.e. they agree with each other, or else we would’ve flagged them as conflicting rules earlier on), and we want to apply the most specific rule, i.e. the one which conditions on the longest history, i.e. the one with the longest key . This is a bit hacky and not obvious, so it should be mentioned in the docs.

Definition of done:

• For each clarification, figure out the right place(s) in the docs where it should live
• Think or ask around (CSE) to figure out if there are further important relevant bits that should be added to the 3 topics in question
• Create appropriate examples that would speak for themselves
• Update the docs with the content
• Get a review from both Research and CSE

[samsucik]

Exalate commented:

samsucik commented:

@melindaloubser1 I agree with your suggestion – it should be possible to specify some slots and also specify how the slots not explicitly mentioned should be treated. The two basic options being 1) don’t care about those other slots, 2) those other slots can’t be set. Your second suggestion allows this.

I think it’s best if you create a new issue for this, especially if you have evidence from users who struggled with this <g-emoji class="g-emoji" alias="slightly_smiling_face" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f642.png"> 🙂 </g-emoji>

[sync-by-unito[bot]]

➤ Maxime Verger commented:

💡 Heads up! We’re moving issues to Jira: https://rasa-open-source.atlassian.net/browse/OSS.

From now on, this Jira board is the place where you can browse (without an account) and create issues (you’ll need a free Jira account for that). This GitHub issue has already been migrated to Jira and will be closed on January 9th, 2023. Do not forget to subscribe to the corresponding Jira issue!

➡️ More information in the forum: https://forum.rasa.com/t/migration-of-rasa-oss-issues-to-jira/56569.