Interface NCElement

  • All Superinterfaces:
    NCMetadata, Serializable

    public interface NCElement
    extends NCMetadata, Serializable
    Data model element.

    Data model element defines a named entity that will be detected in the user input. A model element typically is one or more individual words that have a consistent semantic meaning and typically denote a real-world object, such as persons, locations, number, date and time, organizations, products, etc. Such object can be abstract or have a physical existence.

    Read full documentation in Data Model section and review examples.

    See Also:
    NCCustomParser
    • Method Detail

      • getId

        String getId()
        Gets unique ID of this element.

        This unique ID should be human readable for simpler debugging and testing of the model. Although element ID could be any arbitrary string it is highly recommended to have element ID as a lower case string starting with some model prefix, followed by colon and then the element's name. For example, some built-in NLPCraft IDs are: nlpcraft:date, nlpcraft:city.

        Few important notes:

        • Element IDs starting with nlpcraft: are reserved for built-in NLPCraft IDs.
        • Element ID is an implicit synonym for that element. Thus element ID can be used in the user input directly to clearly disambiguate the element in the input sentence instead of relying on synonyms or other ways of detection.

        JSON
        If using JSON/YAML model presentation this is set by id property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ]
                 }
             ]
         
        Returns:
        Unique ID of this element.
        See Also:
        NCToken.getId()
      • getGroups

        default List<String> getGroups()
        Gets the list of groups this elements belongs to.

        Model element can belong to one or more groups. By default, the element belongs to a single group whose group ID is equal to its ID. The proper grouping of the model elements is required for operation of Short-Term-Memory (STM) in conversation (if and when conversation is used). Specifically, a token (i.e. found model element) that is part of the group set will override other tokens from the same set or a its superset. In other words, tokens with a smaller group set (more specific token) will override the tokens from a larger group set (more generic tokens).

        Note that built-in tokens (including from 3rd party token providers) belong to a single group whose group ID is equal to their IDs.

        JSON
        If using JSON/YAML model presentation this is set by groups property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "groups": ["group1", "group2"]
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ]
                 }
             ]
         
        Returns:
        List of groups this element belongs to. By default, the model element belongs to one group with ID equal to the element ID.
        See Also:
        NCConversation, getId()
      • isMemberOf

        default boolean isMemberOf​(String grp)
        Shortcut method to test if this element is a member of given group. It is equivalent to:
             return getGroups().contains(grp);
         
        Parameters:
        grp - Token group to test.
        Returns:
        True if this element belongs to the given group, false otherwise.
      • getMetadata

        default Map<String,​Object> getMetadata()
        Gets optional user-defined element's metadata. When a token for this element is detected in the input this metadata is merged into NCMetadata.getMetadata() method returned metadata.

        JSON
        If using JSON/YAML model presentation this is set by description property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ],
                     "metadata": {
                         "str": "val1",
                         "num": 100,
                         "bool": false
                     }
                 }
             ]
         
        Specified by:
        getMetadata in interface NCMetadata
        Returns:
        Element's metadata or empty collection if none provided. Default implementation return empty collection.
        See Also:
        NCMetadata.meta(String), NCMetadata.metaOpt(String), NCMetadata.meta(String, Object)
      • getDescription

        default String getDescription()
        Gets optional element description.

        JSON
        If using JSON/YAML model presentation this is set by description property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ]
                 }
             ]
         
        Returns:
        Optional element description. Default implementation returns null.
      • getValues

        default List<NCValue> getValues()
        Gets optional map of values for this element.

        Each element can generally be recognized either by one of its synonyms or values. Elements and their values are analogous to types and instances of that type in programming languages. Each value has a name and optional set of its own synonyms by which that value, and ultimately its element, can be recognized by. Note that value name itself acts as an implicit synonym even when no additional synonyms added for that value.

        Consider this example. A model element x:car can have:

        • Set of general synonyms: {transportation|transport|_} {vehicle|car|sedan|auto|automobile|suv|crossover|coupe|truck}
        • Set of values:
          • mercedes with synonyms (mercedes, mercedes-benz, mb, benz)
          • bmw with synonyms (bmw, bimmer)
          • chevrolet with synonyms (chevy, chevrolet)
        With that setup x:car element will be recognized by any of the following input sub-string:
        • transport car
        • benz
        • automobile
        • transport vehicle
        • sedan
        • chevy
        • bimmer
        • x:car

        JSON
        If using JSON/YAML model presentation this is set by values property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ],
                     "values": [
                          {
                              "name": "name1",
                              "synonyms": ["syn1", "syn2"]
                          }
                     ]
                 }
             ]
         
        Returns:
        Map of value's name and its synonyms or null if not defined.
      • getParentId

        default String getParentId()
        Gets optional ID of the immediate parent element. Parent ID allows model elements to form into hierarchy.

        JSON
        If using JSON/YAML model presentation this is set by parentId property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "parentId": "parent",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ]
                 }
             ]
         
        Returns:
        Optional parent element ID, or null if not specified. Default implementation returns null.
      • getSynonyms

        default List<String> getSynonyms()
        Gets the list of synonyms by which this model element will be recognized by. Read more about many different forms of synonyms in Data Model section and review examples.

        JSON
        If using JSON/YAML model presentation this is set by synonyms property:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ]
                 }
             ]
         
        Returns:
        List of synonyms for this element. List is generally optional since element's ID acts as an implicit synonym. Default implementation returns an empty list.
      • getValueLoader

        default Optional<NCValueLoader> getValueLoader()
        Gets optional dynamic value loader. This loader will be used additionally to any values defined in getValues() method. Default implementation returns null.

        JSON
        If using JSON/YAML model presentation this is set by valueLoader property with value of a fully qualified class name implementing NCValueLoader interface. Note that only one instance of the value loader will be created per model and given class name:

             "elements": [
                 {
                     "id": "phone:act",
                     "description": "Phone action.",
                     "synonyms": [
                         "{give|_} {call|phone|ring|dial|dial up|ping|contact}"
                     ],
                     "values": [
                          {
                              "name": "name1",
                              "synonyms": ["syn1", "syn2"]
                          }
                     ],
                     "valueLoader": "my.package.ValueLoader"
                 }
             ]
         
        Returns:
        Optional instance of dynamic value loader.
      • isPermutateSynonyms

        default Optional<Boolean> isPermutateSynonyms()
        Whether or not to permutate multi-word synonyms. Automatic multi-word synonyms permutations greatly increase the total number of synonyms in the system and allows for better multi-word synonym detection. For example, if permutation is allowed the synonym "a b c" will be automatically converted into a sequence of synonyms of "a b c", "b a c", "a c b".

        This property overrides the value from NCModelView.isPermutateSynonyms(). One should use this property if model's value isn't applicable to this element.

        JSON
        If using JSON/YAML model presentation this is set by permutateSynonyms:

             "elements": [
                 {
                      "id": "elem",
                      "permutateSynonyms": true,
                      ...
                 }
             ]
         
        Returns:
        Optional synonym permutate property overriding model's one.
        See Also:
        NCModelView.isPermutateSynonyms()
      • isSparse

        default Optional<Boolean> isSparse()
        Whether or not this element allows the non-stop words gaps in its multi-word synonyms.

        This property overrides the value from NCModelView.isSparse(). One should use this property if model's value isn't applicable to this element.

        JSON
        If using JSON/YAML model presentation this is set by sparse:

             "elements": [
                 {
                      "id": "elem",
                      "sparse": true,
                      ...
                 }
             ]
         
        Returns:
        Optional multi-word synonym sparsity property overriding model's one.
        See Also:
        NCModelView.isSparse()