[incubator-nlpcraft] branch NLPCRAFT-520 updated: WIP.

[sergeykamov]

This is an automated email from the ASF dual-hosted git repository.

sergeykamov pushed a commit to branch NLPCRAFT-520
in repository https://gitbox.apache.org/repos/asf/incubator-nlpcraft.git


The following commit(s) were added to refs/heads/NLPCRAFT-520 by this push:
     new 2f0b61da WIP.
2f0b61da is described below

commit 2f0b61daa4a12392b38ee8d6e0051846c6bafa47
Author: Sergey Kamov <skhem...@gmail.com>
AuthorDate: Sat Jan 7 13:26:48 2023 +0400

    WIP.
---
 .../main/scala/org/apache/nlpcraft/NCEntity.scala  |  2 ++
 .../nlpcraft/nlp/parsers/NCSemanticElement.scala   | 32 ++++++++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.scala 
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.scala
index e241a7c8..73029ca5 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCEntity.scala
@@ -65,6 +65,8 @@ trait NCEntity extends NCPropertyMap:
 
     /**
       * Gets optional set of groups this entity belongs to.
+      * Groups can be used in 
[[https://nlpcraft.apache.org/intent-matching.html#idl NLPCraft IDL]].
+      * They are designed for convenient search any entity which belongs to 
the same group.
       *
       * @return Optional set of groups this entity belongs to. Returned set 
can be empty but never `null`. By
       *     default the entity belongs to a group of its own [[getType type]].
diff --git 
a/nlpcraft/src/main/scala/org/apache/nlpcraft/nlp/parsers/NCSemanticElement.scala
 
b/nlpcraft/src/main/scala/org/apache/nlpcraft/nlp/parsers/NCSemanticElement.scala
index 21165d08..e9f6c849 100644
--- 
a/nlpcraft/src/main/scala/org/apache/nlpcraft/nlp/parsers/NCSemanticElement.scala
+++ 
b/nlpcraft/src/main/scala/org/apache/nlpcraft/nlp/parsers/NCSemanticElement.scala
@@ -37,13 +37,40 @@ import org.apache.nlpcraft.*
   * Also semantic element can have an optional set of special synonyms called 
values or "proper nouns" for this element.
   * Unlike basic synonyms, each value is a pair of a name and a set of 
standard synonyms by which that value,
   * and ultimately its element, can be recognized in the user input.
+  * Note that the value name itself acts as an implicit synonym even when no 
additional synonyms added for that value.
   *
   * So [[NCEntity named entity]] can be found via 
[[NCSemanticElement.getSynonyms element synonyms]] or
   * [[NCSemanticElement.getValues element values]].
   * Other [[NCSemanticElement]] properties are passed into created 
corresponded  [[NCEntity]] instance.
   *
-  * See detailed description on the website 
[[https://nlpcraft.apache.org/built-in-entity-parser.html#parser-semantic 
Semantic Parser]].
+  * Example 1.
+  * <pre>
+  * - id: "ord:menu"
+  *   description: "Order menu."
+  *   synonyms:
+  *     - "{menu|carte|card}"
+  *     - "{products|goods|food|item|_} list"
+  * </pre>
+  * Described above element **ord&#58;menu** can be detected via synonyms: 
*menu*, *products*, *products list* etc.
+  *
+  * Example 2.
+  * <pre>
+  * - id: "ord:pizza:size"
+  *   description: "Size of pizza."
+  *   values:
+  *     "small": [ "{small|smallest|min|minimal|tiny} {size|piece|_}" ]
+  *     "medium": [ "{medium|intermediate|normal|regular} {size|piece|_}" ]
+  *     "large": [ "{big|biggest|large|max|maximum|huge|enormous} 
{size|piece|_}" ]
+  * </pre>
+  * Described above element **ord&#58;pizza&#58;size** can be detected via 
values synonyms: *small*, *medium size*, *big piece* etc.
+  * Note that **value** (small, medium or large in this example) is passed in 
created [[NCEntity]] as property with key
+  * **elemType&#58;value** (ord&#58;pizza&#58;size&#58;value in this example).
   *
+  * **NOTE** that given examples show how semantic elements synonyms and 
values are represented via YAML format
+  * when these elements passed in [[NCSemanticEntityParser]] via semantic 
model resource definition,
+  * but there aren't differences when semantic elements are defined via JSON 
files or prepared programmatically.
+  *
+  * See detailed description on the website 
[[https://nlpcraft.apache.org/built-in-entity-parser.html#parser-semantic 
Semantic Parser]].
   *
   * @see [[NCSemanticEntityParser]]
   */
@@ -75,7 +102,8 @@ trait NCSemanticElement:
     def getValues: Map[String, Set[String]] = Map.empty
 
     /**
-      * Gets elements synonyms list. They allows to find element in text. Note 
that macros can be used for synonyms definition.
+      * Gets elements synonyms list. They allows to find element in text.
+      * Note that macros can be used for synonyms definition, so returned 
synonyms can contain references to macroses.
       *
       * @return Synonyms.
       */