fawn-memory 0.0.4 → 0.0.7

package/dist/knowpro/answerContextSchema.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { DateRange } from "./interfaces.js";
+
+export type AnswerContext = {
+    // Relevant entities
+    // Use the 'name' and 'type' properties of entities to PRECISELY identify those that answer the user question.
+    entities?: RelevantKnowledge[] | undefined;
+    // Relevant topics
+    topics?: RelevantKnowledge[] | undefined;
+    // Relevant messages
+    messages?: RelevantMessage[] | undefined;
+};
+
+export type EntityNames = string | string[];
+
+export type RelevantKnowledge = {
+    // The actual knowledge
+    knowledge: unknown;
+    // Entity or entities who mentioned the knowledge
+    origin?: EntityNames | undefined;
+    // Entity or entities who received or consumed this knowledge
+    audience?: EntityNames | undefined;
+    // Time period during which this knowledge was gathered
+    timeRange?: DateRange | undefined;
+};
+
+export type RelevantMessage = {
+    from?: EntityNames | undefined;
+    to?: EntityNames | undefined;
+    timestamp?: Date | undefined;
+    // Text chunks in this message
+    messageText?: string | string[] | undefined;
+};

package/dist/knowpro/answerResponseSchema.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export type AnswerType =
+    | "NoAnswer" // If question cannot be accurately answered from [ANSWER CONTEXT]
+    | "Answered"; // Fully answer question
+
+export type AnswerResponse = {
+    // use "NoAnswer" if no highly relevant answer found in the [ANSWER CONTEXT]
+    type: AnswerType;
+    // the answer to display if [ANSWER CONTEXT] is highly relevant and can be used to answer the user's question
+    answer?: string | undefined;
+    // If NoAnswer, explain why..
+    // particularly explain why you didn't use any supplied entities
+    whyNoAnswer?: string;
+};

package/dist/knowpro/dateTimeSchema.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export type DateVal = {
+    day: number;
+    month: number;
+    year: number;
+};
+
+export type TimeVal = {
+    // In 24 hour form
+    hour: number;
+    minute: number;
+    seconds: number;
+};
+
+export type DateTime = {
+    date: DateVal;
+    time?: TimeVal | undefined;
+};
+
+export type DateTimeRange = {
+    startDate: DateTime;
+    stopDate?: DateTime | undefined;
+};

package/dist/knowpro/knowledgeSchema.ts

@@ -0,0 +1,63 @@
+// Quantity must be a number, do not infer amounts.
+export type Quantity = {
+    amount: number;
+    units: string;
+};
+
+// String quantifier, e.g. 'many', 'few', 'several', 'a lot of', 'some'.
+export type Quantifier = {
+    amount: string;
+    units: string;
+};
+
+export type Value = string | number | boolean | Quantity | Quantifier;
+
+export type Facet = {
+    name: string;
+    // Very concise values.
+    value: Value;
+};
+
+// Specific, tangible people, places, institutions or things only
+export type ConcreteEntity = {
+    // the name of the entity or thing such as "Bach", "Great Gatsby", "frog" or "piano"
+    name: string;
+    // the types of the entity such as "speaker", "person", "artist", "animal", "object", "instrument", "school", "room", "museum", "food" etc.
+    // An entity can have multiple types; entity types should be single words
+    type: string[];
+    // A specific, inherent, defining, or non-immediate facet of the entity such as "blue", "old", "famous", "sister", "aunt_of", "weight: 4 kg"
+    // trivial actions or state changes are not facets
+    // facets are concise "properties"
+    facets?: Facet[];
+};
+
+export type ActionParam = {
+    name: string;
+    value: Value;
+};
+
+export type VerbTense = "past" | "present" | "future";
+
+export type Action = {
+    // Each verb is typically a word
+    verbs: string[];
+    verbTense: VerbTense;
+    subjectEntityName: string | "none";
+    objectEntityName: string | "none";
+    indirectObjectEntityName: string | "none";
+    params?: (string | ActionParam)[];
+    // If the action implies this additional facet or property of the subjectEntity, such as hobbies, activities, interests, personality
+    subjectEntityFacet?: Facet | undefined;
+};
+
+// Detailed and comprehensive knowledge response
+export type KnowledgeResponse = {
+    entities: ConcreteEntity[];
+    // The 'subjectEntityName' and 'objectEntityName' must correspond to the 'name' of an entity listed in the 'entities' array.
+    actions: Action[];
+    // Some actions can ALSO be expressed in a reverse way... e.g. (A give to B) --> (B receive from A) and vice versa
+    // If so, also return the reverse form of the action, full filled out
+    inverseActions: Action[];
+    // Detailed, descriptive topics and keyword.
+    topics: string[];
+};

package/dist/knowpro/relatedTermsSchema.ts

@@ -0,0 +1,25 @@
+/**
+ * Schema for LLM-based related terms expansion.
+ * Given a list of terms, the LLM returns semantically related words.
+ */
+
+/**
+ * A term and its semantically related words.
+ */
+export interface TermWithRelated {
+    /** The original term */
+    term: string;
+    /** Semantically related words (synonyms, near-synonyms, conceptually related).
+     * Do NOT include morphological variants (plurals, verb tenses) - only semantically different words.
+     * Examples: book -> [novel, publication, text], buy -> [purchase, acquire], happy -> [joyful, pleased]
+     */
+    relatedTerms: string[];
+}
+
+/**
+ * Response containing related terms for a batch of input terms.
+ */
+export interface RelatedTermsResponse {
+    /** Array of terms with their related words */
+    terms: TermWithRelated[];
+}

package/dist/knowpro/searchQuerySchema.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { DateTimeRange } from "./dateTimeSchema.js";
+
+export type FacetTerm = {
+    // the name of the facet, such as "color", "profession", "patent number"; "*" means match any facet name
+    facetName: string;
+    // the value of the facet, such as "red", "writer"; "*" means match any facet value
+    facetValue: string;
+};
+
+// Use to find information about specific, tangible people, places, institutions or things only..
+// This includes entities with particular facets
+// Abstract concepts or topics are not entityTerms. Use string for them
+// Any terms will match fuzzily.
+export type EntityTerm = {
+    // the name of the entity or thing such as "Bach", "Great Gatsby", "frog" or "piano" or "we", "I"; "*" means match any entity name
+    name: string;
+    isNamePronoun: boolean;
+    // the specific types of the entity such as "book", "movie", "song", "speaker", "person", "artist", "animal", "instrument", "school", "room", "museum", "food" etc.
+    // Generic types like "object", "thing" etc. are NOT allowed
+    // An entity can have multiple types; entity types should be single words
+    type?: string[];
+    // Facet terms search for properties or attributes of the entity.
+    // Eg: color(blue), profession(writer), author(*), aunt(Agatha), weight(4kg), phoneNumber(...), etc.
+    facets?: FacetTerm[];
+};
+
+// Use for action verbs only. Ensure nouns are not misinterpreted as verbs
+export type VerbsTerm = {
+    words: string[]; // individual words in single verb or compound verb
+    tense: "Past" | "Present" | "Future";
+};
+
+export type ActionTerm = {
+    // Action verbs describing the interaction
+    actionVerbs?: VerbsTerm | undefined;
+    // The origin of the action or information, typically the entity performing the action
+    actorEntities: EntityTerm[] | "*";
+    // the recipient or target of the action or information
+    // Action verbs can imply relevant facet names on the targetEntity. E.g. write -> writer, sing -> singer etc.
+    targetEntities?: EntityTerm[];
+    // additional entities participating in the action.
+    // E.g. in the phrase "Jane ate the spaghetti with the fork", "the fork" would be an additional entity
+    // E.g. in the phrase "Did Jane speak about Bach with Nina", "Bach" would be the additional entity
+    additionalEntities?: EntityTerm[];
+    // Is the intent of the phrase translated to this ActionTerm to actually get information about a specific entities?
+    // Examples:
+    // true: if asking for specific information about an entity, such as "What did Mia say her phone number was?"
+    // false if involves actions and interactions between entities, such as "What phone number did Mia mention in her note to Jane?"
+    isInformational: boolean;
+};
+
+export type ScopeFilter = {
+    // Search terms to use to limit search
+    entitySearchTerms?: EntityTerm[] | undefined;
+    // Use only if request explicitly asks for time range, particular year, month etc.
+    timeRange?: DateTimeRange | undefined; // in this time range
+};
+
+//
+// Search a search engine using filters:
+// entitySearchTerms cannot contain entities already in actionSearchTerms
+export type SearchFilter = {
+    // Use actionSearchTerm for queries involving actions and interactions between entities.
+    actionSearchTerm?: ActionTerm;
+    // Use entitySearchTerms for queries asking for specific information about entities and their attributes.
+    // E.g. "What is Mia's phone number?" or "Where did Jane study?"
+    entitySearchTerms?: EntityTerm[];
+    // searchTerms:
+    // Concepts, topics or other terms that don't fit (or are not already handled by) ActionTerms or EntityTerms.
+    // - Do not use noisy searchTerms like "topic", "topics", "subject", "discussion" etc. even if they are mentioned in the user request
+    // - Phrases like 'email address' or 'first name' are a single term
+    // - use empty searchTerms array when use asks for summaries
+    searchTerms?: string[];
+    // Use to limit matches to particular sub-set of a conversation, document, etc
+    // E.g. if the user request specifies a particular section or context, use scopeSubQuery to limit the search.
+    scopeSubQuery?: ScopeFilter | undefined;
+};
+
+export type SearchExpr = {
+    rewrittenQuery: string;
+    // Translate rewritten query into filters
+    filters: SearchFilter[];
+};
+
+export type SearchQuery = {
+    // One expression for each search required by user request
+    // Each SearchExpr runs independently, so make them standalone by resolving references like 'it', 'that', 'them' etc.
+    searchExpressions: SearchExpr[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fawn-memory",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "description": "",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && shx cp src/knowpro/*Schema.ts dist/knowpro/",
     "dev": "tsx src/index.ts",
     "lint": "eslint .",
     "clean": "rimraf dist",
@@ -23,6 +23,7 @@
   },
   "packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a",
   "devDependencies": {
+    "shx": "^0.3.4",
     "@eslint/js": "^9.39.2",
     "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.50.0",