Skip to main content

Overview

Create ChatTree​

  • "ChatTree" is the core component of all capabilities of the TeliChat organization and scheduling system (such as "InfoItem", "Python Script/Code Integration", "Knowledge Base", "Intent", etc.). It is the "brain" of the dialogue system and is responsible for the overall dialogue logic control and execution.
  • The name of the ChatTree file (without the ".py" or ".xmind" suffix) is the name of the ChatTree
  • ChatTree can be created either using Python or Xmind, and the two types of ChatTree can call each other.

Use Xmind to create a ChatTree​

  • Download and install Xmind software at https://xmind.com/download (the free version is sufficient)
  • The text content in each node, lines starting with two slashes "//" are comment lines and will be ignored
  • When creating, Xmind's nodes will automatically form a parent-child relationship, forming a "tree"; then you can use the link in Xmind to increase the parent-child relationship between the two nodes, but be careful not to form a "ring", only a "directed acyclic graph" (DAG)
  • Select item 1 of "Logic Chart" in the "Map" of the Xmind "Format"
  • The first line of each node is the node type in the form of "#...#" or "#...#...", and then starting from the next line, it may be the node attribute definition in the form of "@...", or it may be in other forms. For details, please refer to the chapters of each node and template_of_chattree_node.xmind (Note that when downloading, save the file name as "template_of_chattree_node.xmind").
  • Note: Node content should not contain double quotes, and can be replaced by single quotes or square brackets
  • You can also refer to the already drawn ChatTree file 911.xmind (note that the file name should be saved as "911.xmind" when downloading)

Create a ChatTree using Python​

  • Please create and edit Python files in the server directory displayed to the right of the "Refresh" button next to the "Python ChatTree" in the backend management UI
  • After creating the Python ChatTree file, add the following code at the beginning of the file: 
    import sys, os
    project_root = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "../../.."))
    if project_root not in sys.path:
        sys.path.append(project_root)
    from chattree_def import *
    chattree = ChatTree()
    Among them, the chattree variable in the last line is required and cannot be defined repeatedly.
  • If you need to import other Python packages or files, you may need to use sys.path.append() to add the path of the Python packages or files. If it is a relative path, it is relative to the TeliChatSecRun directory.
  • Then use the xxx_node = chattree.create_node() interface to create the node of the ChatTree:
    • create_node() has two parameters. The first parameter is the type of the node (str type, also in the form of "#...#" or "#...#..."), and the second parameter is the attributes of the node (dict type, there is no need to add "@" before the attribute name like the Xmind ChatTree)
    • A variable is needed to save the returned newly created node, and this variable needs to be used later for topological connection.
    • Note: Each attribute value should not contain double quotes and can be replaced by single quotes or square brackets
  • After creating all nodes, use >> to establish topological links between nodes
    • Such as: parent_node >> child_node or parent_node >> child_node >> grandchild_node
    • You can use Python's list to establish multiple connections at once, such as: parent_node >> [child_node1, child_node2, child_node3] or [parent_node1, parent_node2, parent_node2] >> child_node
    • Note that "rings" cannot be formed, only DAG (directed acyclic graphs)
  • Add the following code at the end of the file: 
    if __name__ == "__main__":
        chattree.render(__file__)
    In this way, the HTML interaction diagram of the ChatTree can be generated by running the Python file, which facilitates an intuitive understanding of the overall topology of the ChatTree. Specifically, run it in the TeliChatSecRun directory: 
    python3 <the_directory_displayed_in_the_backend_management_UI_mentioned_earlier>/chattree_file.py
    The generated HTML file will be saved in the same directory as the Python file, with the same name and the suffix ".html". Then use a browser to open the HTML file to preview (or use the plug-in Live Preview - Microsoft installed in VS Code to preview). For more information, see "ChatTree HTML Interaction Graph"
  • You can also refer to the already written ChatTree file 911.py (note that the file name is saved as "911.py" when downloading); at the same time, there are more Python ChatTrees in "ChatTree Examples" for reference
  • The chattree_def.py file in the TeliChatSecRun directory of the server contains the relevant interface definitions of the ChatTree. You can refer to it, but never modify any of its contents!

Key concepts​

Knowledge Base​

Code File​

  • Only required for xmind ChatTree
  • For details, see "Code File"

InfoItem​

  • Similar to "variables" in programming languages, InfoItem are used to collect and store the information content provided by the user during the dialogue process (can also store content unrelated to user input), and reference and use it in subsequent dialogue nodes
  • InfoItems are divided into "User Input InfoItem", "Code Definition InfoItem" and "System InfoItems". For details, see "InfoItem"
  • How to use InfoItems in code, see "Python Script/Function" for details

Intent​

  • The user's intention in the dialogue will appear in various nodes defined by the ChatTree
  • For details, please refer to the chapters of various nodes and "Intent"

Text Output​

  • Refers to the content output to the user by various nodes in the ChatTree. It may be directly output text, or it may be a description of how to output (similar to LLM prompt)
  • For details, please refer to the chapters of various nodes and "Text Output"

Python Script/Function​

  • Python scripts/functions can be used in both Python ChatTree and Xmind ChatTree to implement complex business logic or technical processing
  • For details, see "Python Script/Function"

Operating Mechanism​

Topology​

  • "ChatTree" must be a DAG (directed acyclic graph)
  • There is and is only one "#start#" as the root node. There may also be (or not) a "#trigger#" node as the root node. In addition, there cannot be other root nodes.
  • The parent node points to the child node through an arrowed line, or in Xmind the left is the parent node and the right is the child node (the link in Xmind also uses the direction of the arrow to distinguish parent and child nodes)
  • If a node has multiple parent nodes, it may be traversed (executed) multiple times in a round of dialogue

Overall Execution Logic​

  • After starting the execution and after each round of dialogue, the "ChatTree" will stop at an interaction node (including the "#single_turn_interact#" node with a clear "system question" and the "#multi_turn_interact#" node without "system question") to output to the user and wait for the user's input before continuing to execute; Which interaction node does it stop at each time, starting from the "#start#" node, traverse from left to right and top to bottom in the direction of the arrow (similar to a tree with the root node on the left and the overall expansion to the right, or a depth-first search of a DAG). The first "#single_turn_interact#" node encountered in which the InfoItem defined in it has no value or the "#multi_turn_interact#" node has not been executed.
  • After the user inputs at the above-mentioned stopped interaction node, based on the user input, the system will extract global InfoItems, not only the InfoItems defined by the current interaction node, but also the InfoItems defined by all "#single_turn_interact#" nodes will be extracted (InfoItems defined by the "#multi_turn_interact#" nodes of non-current interaction nodes will not be extracted)
  • The extracted information will be assigned to relevant InfoItems (maybe one, multiple, or none), and then re-execute the above traversal to find the next "#single_turn_interact#" node with no value for the InfoItem or the "#multi_turn_interact#" node that has not yet been executed.
  • During the above traversal process of finding the next interactive node to stay, the relevant nodes passed by will not be executed by default. Only these two types of nodes will be executed:
    • Nodes on the traversal path from the currently stopped interaction node to the next stopped interaction node
    • All descendant nodes of the "#single_turn_interact#" node (which may or may not have been stopped at this node before) where the InfoItem assigned or changed value by the current user input is located, and these descendant nodes have been traversed before encountering the next stopped interaction node (this situation is generally a checksum processing of a specific user input InfoItem, which will not be executed again for the same reason after being executed once)
  • If the user does not refuse to answer the question in the current "#single_turn_interact#" node (or the InfoItem of the node has "required" modifier), nor does the user request to end the dialogue, and the content of the InfoItem of the node cannot be extracted from the user's answer, the system execution will stay at the interaction node and (possibly) ask again
  • In addition to the factors related to the above InfoItems, the execution order is affected by global intent recognition: the intents in all "#user_intent#" nodes after the "#trigger#" node and after the "#single_turn_interact#" node with InfoItem "topic" modifier will be globally recognized during each interaction. When matching, they will enter the corresponding "#user_intent#" node after "#trigger#" for execution (it will return to the node just now to continue after the execution is completed), or enter the corresponding "#user_intent#" node after the "#single_turn_interact#" node with Infoitem "topic" modifier for execution (i.e. the topic switch, it will not return after execution is completed). For details, see "Node - #trigger#" and "Node - #single_turn_interact#"

Traversal (execution) logic of specific types of nodes​

  • Only nodes after the "#condition#" node that meet the conditions will be traversed (executed), note that the values ​​of the InfoItems in the "script" or "description" of the condition node may be changed at any time
  • If there are "#user_intent#" nodes after the "#single_turn_interact#" node, then only the successor nodes of the "#user_intent#" node that match the value of the InfoItem of the "#single_turn_interact#" node will be traversed (executed), and other "#user_intent#" nodes will be ignored.
  • If the question in the "#single_turn_interact#" node (without the "required" InfoItem modifier) is refused to answer by the user (the relevant InfoItem will be assigned the value None), all subsequent descendant nodes of the node will not be traversed (executed)
  • According to the above logic, if the user's reply changes the value of the relevant InfoItems on the previous dialogue path, the dialogue will proceed according to the new path: for example, a "#single_turn_interact#" node switches between None and non-None values, or the "#single_interact#" node followed by the "#user_intent#" node switches to a new intent, etc.
  • The "#multi_turn_interact#" node will execute itself in a loop until the descriptive "exit_intent" is met or a specific system InfoItem ("{_multi_turn_interact_exit_reason_}") is assigned in the node's script, then the system will exit the loop and continue the execution of subsequent nodes (see "Node - #multi_turn_interact#")
  • For the "#activity#ask_again" node, if its InfoItem is the InfoItem of the "#single_tuen_interact#" node that has been executed before, it will immediately jump to the "#single_turn_interact#" node to ask the question again; if it is the InfoItem of the "#single turn_interact#" node that has not been executed yet, it may be asked again later

Integration of Python Scripts/Functions​

  • Python scripts/functions can be integrated in multiple places in the "ChatTree" (see "Python Script/Function"). These scripts/functions can call tools or perform more complex deterministic logic; In TeliChat, the LLM itself will not make tool calls, minimizing the negative impact of LLM "illusion"
  • For the "#start#" node's "on_infoitem_change_trigger" attribute, the system will automatically call the relevant Python scripts/functions immediately after the value of the corresponding InfoItem changes; the change in the value of these InfoItems may be caused by user input, or may be caused by the assignment of the relevant Python scripts/functions. For details, see the "on_infoitem_change_trigger" attribute in "Node - #start#"

User Interaction and Prompt Word Content​

  • As mentioned earlier, the system will interact with the user in the "#single_turn_interact#" and "#multi_turn_interact#" nodes, and the output content of "#inform_user#" will only be cached when executed, and will not be actually output until the next "#single_turn_interact#" or "#multi_turn_interact#" or the end of the dialogue (user request to end or the system actively ends) (if the current interaction node is "single_turn_interact", then together with "system question")
  • "Intent", "Text Output", "InfoItem" and other contents in related nodes will all be part of the prompt word
    • Among the above three types of prompt word components, there are only two roles:
      • "You" (i.e. AI robot)
      • "User" (i.e. the person talking to the AI)
    • In the above three types of prompt word components, the description of the subject is omitted, and the subject must be “user”
    • Among the components of the above three types of prompt words, it is necessary to pay attention to titles such as "self", which generally refers to "user"
  • In any interaction, the system will also match relevant response script, static reference information (i.e. knowledge base) and dynamic reference information based on user input, and automatically add relevant content to the system's prompt words. For details, please refer to the relevant content in "Node - #start#"
  • The "#start#" node's "background_information", "chattree_title", "system_role", "user_role", "language_style", "fixed_closing_remarks" and other attributes will also affect the system's prompt word content.
  • Sometimes it is necessary to explain and clarify related concepts. This can be achieved by defining "term concepts" in "Knowledge Base". The system will intelligently select and add the final prompt word when constructing the prompt word.