Memory updates (#1439)

* Additional wrapper APIs on base Memory class to simplify and
demonstrate:
  * Searching for matching entities and topics
  * Searching _using_ entities and topics 
* These also show how to use the more powerful searchKnowledge and
search APIs
* Better documentation
* Unit Tests

Author: umeshma

ts/packages/knowPro/src/interfaces.ts

@@ -67,6 +67,8 @@ export interface IMessage extends IKnowledgeSource {
 export type ScoredMessageOrdinal = {
     /**
      * The ordinal number of the message.
+     * Use this ordinal to get the message frm the conversation's message collection {@link IMessageCollection}
+     * @see {@link IConversation.messages}
      */
     messageOrdinal: MessageOrdinal;
     /**
@@ -187,7 +189,9 @@ export interface IConversation<TMessage extends IMessage = IMessage> {
  */
 export type ScoredSemanticRefOrdinal = {
     /**
-     * Ordinal number for the semantic reference.
+     * Ordinal number for the SemanticRef {@link SemanticRef}.
+     * Use this ordinal to resolve the SemanticRef from the conversation's semantic refs collection {@link ISemanticRefCollection}
+     * @see {@link IConversation.semanticRefs}
      */
     semanticRefOrdinal: SemanticRefOrdinal;
     /**
@@ -657,7 +661,13 @@ export type WhenFilter = {
 };
 
 export type SemanticRefSearchResult = {
+    /**
+     * The search terms that caused these semantic refs to match
+     */
     termMatches: Set<string>;
+    /**
+     * Scored semantic ref matches
+     */
     semanticRefMatches: ScoredSemanticRefOrdinal[];
 };
 

ts/packages/knowPro/src/knowledgeLib.ts

@@ -20,6 +20,7 @@ import {
     IMessageCollection,
 } from "./interfaces.js";
 import { conversation as kpLib } from "knowledge-processor";
+import { getSemanticRefsFromScoredOrdinals } from "./searchLib.js";
 
 export function facetValueToString(facet: kpLib.Facet): string {
     const value = facet.value;
@@ -67,14 +68,6 @@ export function* getScoredSemanticRefsFromOrdinals(
     }
 }
 
-export function getSemanticRefsFromScoredOrdinals(
-    semanticRefs: ISemanticRefCollection,
-    scoredOrdinals: ScoredSemanticRefOrdinal[],
-): SemanticRef[] {
-    const ordinals = scoredOrdinals.map((sr) => sr.semanticRefOrdinal);
-    return semanticRefs.getMultiple(ordinals);
-}
-
 export function* messageOrdinalsFromSemanticRefs(semanticRefs: SemanticRef[]) {
     for (const sr of semanticRefs) {
         yield sr.range.start.messageOrdinal;

ts/packages/knowPro/src/search.ts

@@ -82,8 +82,17 @@ export function createSearchOptionsTypical(): SearchOptions {
     };
 }
 
+/**
+ * Search matches returned by searchConversation {@link searchConversation}
+ */
 export type ConversationSearchResult = {
+    /**
+     * The ordinals of matching messages. You can use these ordinals to load messages
+     */
     messageMatches: ScoredMessageOrdinal[];
+    /**
+     * For each matching knowledge type, the ordinals of the matching knowledge.
+     */
     knowledgeMatches: Map<KnowledgeType, SemanticRefSearchResult>;
     rawSearchQuery?: string | undefined;
 };

ts/packages/knowPro/src/searchLib.ts

@@ -7,11 +7,14 @@
  */
 
 import {
+    ISemanticRefCollection,
     KnowledgePropertyName,
     PropertySearchTerm,
+    ScoredSemanticRefOrdinal,
     SearchTerm,
     SearchTermGroup,
     SearchTermGroupTypes,
+    SemanticRef,
 } from "./interfaces.js";
 import * as kpLib from "knowledge-processor";
 import { PropertyNames } from "./propertyIndex.js";
@@ -171,6 +174,76 @@ export function createPropertySearchTerms(
     return propertySearchTerms;
 }
 
+export function createTopicSearchTermGroup(
+    topicTerms: string | string[],
+    exactMatch: boolean = false,
+): SearchTermGroup {
+    const termGroup = createOrMaxTermGroup();
+    if (typeof topicTerms === "string") {
+        termGroup.terms.push(
+            createPropertySearchTerm(
+                PropertyNames.Topic,
+                topicTerms,
+                exactMatch,
+            ),
+        );
+    } else {
+        for (const term of topicTerms) {
+            termGroup.terms.push(
+                createPropertySearchTerm(PropertyNames.Topic, term, exactMatch),
+            );
+        }
+    }
+    return termGroup;
+}
+
+export function createEntitySearchTermGroup(
+    name: string | undefined,
+    type?: string | undefined,
+    faceName?: string | undefined,
+    facetValue?: string | undefined,
+    exactMatch: boolean = false,
+): SearchTermGroup {
+    const termGroup = createOrMaxTermGroup();
+    if (name) {
+        termGroup.terms.push(
+            createPropertySearchTerm(
+                PropertyNames.EntityName,
+                name,
+                exactMatch,
+            ),
+        );
+    }
+    if (type) {
+        termGroup.terms.push(
+            createPropertySearchTerm(
+                PropertyNames.EntityType,
+                type,
+                exactMatch,
+            ),
+        );
+    }
+    if (faceName) {
+        termGroup.terms.push(
+            createPropertySearchTerm(
+                PropertyNames.FacetName,
+                faceName,
+                exactMatch,
+            ),
+        );
+    }
+    if (facetValue) {
+        termGroup.terms.push(
+            createPropertySearchTerm(
+                PropertyNames.FacetValue,
+                facetValue,
+                exactMatch,
+            ),
+        );
+    }
+    return termGroup;
+}
+
 export function createTagSearchTermGroup(
     tags: string[],
     exactMatch: boolean = true,
@@ -210,3 +283,11 @@ export function createMultipleChoiceQuestion(
     }
     return text;
 }
+
+export function getSemanticRefsFromScoredOrdinals(
+    semanticRefs: ISemanticRefCollection,
+    scoredOrdinals: ScoredSemanticRefOrdinal[],
+): SemanticRef[] {
+    const ordinals = scoredOrdinals.map((sr) => sr.semanticRefOrdinal);
+    return semanticRefs.getMultiple(ordinals);
+}

ts/packages/knowPro/test/search.spec.ts

@@ -4,6 +4,7 @@
 import {
     IConversation,
     KnowledgeType,
+    PropertySearchTerm,
     SearchTermGroup,
     SemanticRefSearchResult,
 } from "../src/interfaces.js";
@@ -14,6 +15,8 @@ import {
     createOrTermGroup,
     createPropertySearchTerm,
     createOrMaxTermGroup,
+    createTopicSearchTermGroup,
+    createEntitySearchTermGroup,
 } from "../src/searchLib.js";
 import {
     emptyConversation,
@@ -30,10 +33,12 @@ import {
     resolveAndVerifyKnowledgeMatches,
     resolveAndVerifySemanticRefs,
     verifyDidMatchSearchGroup,
+    verifyPropertySearchTermName,
     verifySemanticRefResult,
 } from "./verify.js";
 import { hasTestKeys, describeIf } from "test-lib";
-import { validateSearchTermGroup } from "../src/compileLib.js";
+import { isPropertyTerm, validateSearchTermGroup } from "../src/compileLib.js";
+import { PropertyNames } from "../src/propertyIndex.js";
 
 /**
  * These tests are designed to run offline.
@@ -226,6 +231,39 @@ describe("search.offline", () => {
         },
         testTimeout,
     );
+    test(
+        "propertySearchGroup",
+        () => {
+            let topicTerms = ["music", "dance"];
+            let termGroup = createTopicSearchTermGroup(topicTerms);
+            validateSearchTermGroup(termGroup);
+
+            expect(termGroup.terms.length).toEqual(topicTerms.length);
+            for (let i = 0; i < termGroup.terms.length; ++i) {
+                const term = termGroup.terms[i];
+                expect(isPropertyTerm(term)).toBeTruthy();
+                if (isPropertyTerm(term)) {
+                    verifyPropertySearchTermName(term, PropertyNames.Topic);
+                    expect(term.propertyValue.term.text).toEqual(topicTerms[i]);
+                }
+            }
+
+            termGroup = createEntitySearchTermGroup(
+                "jane",
+                "person",
+                "job",
+                "scientist",
+            );
+            validateSearchTermGroup(termGroup);
+            expect(termGroup.terms.length).toEqual(4);
+            let propertyTerm = termGroup.terms[2] as PropertySearchTerm;
+            verifyPropertySearchTermName(propertyTerm, "facet.name");
+            propertyTerm = termGroup.terms[3] as PropertySearchTerm;
+            verifyPropertySearchTermName(propertyTerm, "facet.value");
+        },
+        testTimeout,
+    );
+
     async function runSearchKnowledge(
         termGroup: SearchTermGroup,
         knowledgeType: KnowledgeType,

ts/packages/knowPro/test/verify.ts

@@ -12,6 +12,7 @@ import {
     SemanticRef,
     TextRange,
     SemanticRefSearchResult,
+    PropertySearchTerm,
 } from "../src/interfaces.js";
 import { ConversationSearchResult } from "../src/search.js";
 import {
@@ -198,3 +199,15 @@ export function verifyAnswerResponse(response: AnswerResponse) {
         expect(response.whyNoAnswer).toBeDefined();
     }
 }
+
+export function verifyPropertySearchTermName(
+    property: PropertySearchTerm,
+    name: string,
+) {
+    expect(property.propertyName).toBeDefined();
+    if (typeof property.propertyName === "string") {
+        expect(property.propertyName).toEqual(name);
+    } else {
+        expect(property.propertyName.term.text).toEqual(name);
+    }
+}