@kybernesis/brain-core 0.10.0 → 0.12.0

package/dist/relational-intent.js

@@ -0,0 +1,151 @@
+/**
+ * Relational-query parser — adapted from gbrain's relational-intent.ts to
+ * Cortex's RelationshipType vocabulary.
+ *
+ * Detects queries whose answer is a RELATIONSHIP (an edge between entities)
+ * rather than a passage — "who founded acme", "who works at X", "what connects
+ * A and B". The relational recall arm (hybrid-search Channel 5) fires ONLY when
+ * this returns non-null, so a plain-recall query never triggers entity-graph
+ * augmentation — that gating is the fix for the recall regression an always-on
+ * entity arm caused (see docs/research/gap-analysis-2026-06-12.md, #3 result).
+ *
+ * Pure module: no DB, no LLM, no async. Detection is regex-only and parsed from
+ * the ORIGINAL query (never an expanded variant) so the arm stays reproducible.
+ *
+ * Precision-first: returns a CANDIDATE. The arm only contributes if a seed
+ * entity also resolves in the store (resolution lives in the storage seam).
+ * Patterns require the relation phrase and entity to be adjacent, so
+ * "who invested TIME in X" does not match "who invested in <seed>".
+ *
+ * ReDoS-safe: seed captures are length-bounded (`.{1,80}?`), patterns anchored.
+ */
+/** Cortex RelationshipType values the parser may emit (must stay a subset of
+ *  constants.ts RelationshipTypeSchema). 'co-occurred' is intentionally absent
+ *  — it is traversal noise, never a query target. */
+export const KNOWN_LINK_TYPES = new Set([
+    'founded', 'works_at', 'invested_in', 'met_with', 'created', 'manages',
+    'partners_with', 'located_in', 'discussed', 'related_to', 'reports_to',
+    'uses', 'depends_on', 'part_of',
+]);
+const STOPWORD_SEEDS = new Set([
+    'it', 'that', 'this', 'them', 'these', 'those', 'here', 'there',
+    'everyone', 'anyone', 'someone', 'anybody', 'somebody', 'people',
+    'things', 'us', 'me', 'him', 'her', 'you', 'who', 'what', 'which',
+]);
+// Bounded lazy seed capture so the trailing anchor decides the boundary.
+const SEED = '(.{1,80}?)';
+// "who <verb> <seed>" → traverse INTO the seed via these typed edges.
+const WHO_REL_VERBS = [
+    { verb: 'founded|co-?founded|started', linkTypes: ['founded'], direction: 'in' },
+    { verb: 'invested in|invests in|funded|backed|backs', linkTypes: ['invested_in'], direction: 'in' },
+    { verb: 'works at|worked at|works for', linkTypes: ['works_at'], direction: 'in' },
+    { verb: 'created|made|built|authored', linkTypes: ['created'], direction: 'in' },
+    { verb: 'manages|managed|runs|leads|led', linkTypes: ['manages'], direction: 'in' },
+    { verb: 'reports to|reported to', linkTypes: ['reports_to'], direction: 'in' },
+    { verb: 'met with|met', linkTypes: ['met_with'], direction: 'both' },
+    { verb: 'partners with|partnered with', linkTypes: ['partners_with'], direction: 'both' },
+];
+function buildPatterns() {
+    const patterns = [];
+    // connects — two seeds, type-agnostic. Most specific, checked first.
+    patterns.push({
+        re: new RegExp(`\\b(?:what|which)\\s+(?:companies?|people|things|entities)?\\s*(?:connects?|links?|ties? together|is (?:the )?(?:connection|link|relationship) between)\\s+${SEED}\\s+(?:and|&)\\s+${SEED}\\s*\\??$`, 'i'),
+        kind: 'connects', linkTypes: null, direction: 'both', seedGroups: 2,
+    });
+    patterns.push({
+        re: new RegExp(`\\bhow\\s+(?:are|is|do|does)\\s+${SEED}\\s+(?:and|&)\\s+${SEED}\\s+(?:connected|related|linked|associated)\\b`, 'i'),
+        kind: 'connects', linkTypes: null, direction: 'both', seedGroups: 2,
+    });
+    // intro — type-agnostic walk around the named entity.
+    patterns.push({
+        re: new RegExp(`\\bwho\\s+(?:introduced|connected|referred)\\s+(?:me|us|him|her|them)\\s+to\\s+${SEED}\\s*\\??$`, 'i'),
+        kind: 'intro', linkTypes: null, direction: 'both', seedGroups: 1,
+    });
+    // who_at — entity in the middle: "who at acme works on payments".
+    patterns.push({
+        re: new RegExp(`\\bwho\\s+(?:at|from|in)\\s+${SEED}\\s+(?:works? on|works?|leads?|runs?|builds?|owns?|handles?|manages?)\\b`, 'i'),
+        kind: 'who_at', linkTypes: ['works_at'], direction: 'in', seedGroups: 1,
+    });
+    // who_rel — "who <verb> <seed>".
+    for (const v of WHO_REL_VERBS) {
+        patterns.push({
+            re: new RegExp(`\\bwho\\s+(?:${v.verb})\\s+${SEED}\\s*\\??$`, 'i'),
+            kind: 'who_rel', linkTypes: v.linkTypes, direction: v.direction, seedGroups: 1,
+        });
+    }
+    // outgoing — "what did <seed> invest in", "where does <seed> work".
+    patterns.push({
+        re: new RegExp(`\\bwhat\\s+(?:companies?|startups?|deals?)?\\s*(?:has|have|did|does)?\\s*${SEED}\\s+(?:invest(?:ed)? in)\\b`, 'i'),
+        kind: 'who_rel', linkTypes: ['invested_in'], direction: 'out', seedGroups: 1,
+    });
+    patterns.push({
+        re: new RegExp(`\\bwhere\\s+(?:does|did|has)\\s+${SEED}\\s+work\\b`, 'i'),
+        kind: 'who_rel', linkTypes: ['works_at'], direction: 'out', seedGroups: 1,
+    });
+    // lookup — single-entity "what/who is X", "tell me about X", "what does X
+    // stand for", "difference between X and Y". Type-agnostic, 0-hop in the
+    // storage layer (return the entity's own docs). Checked LAST so the specific
+    // relational verbs above win first. The seed may carry trailing context
+    // ("Ian in the community"); the storage resolver word-boundary-matches known
+    // entity names WITHIN the seed, so a non-entity seed simply resolves to
+    // nothing and the arm contributes nothing (precision-first).
+    patterns.push({
+        re: new RegExp(`\\bwhat\\s+(?:is|are|was|were)\\s+the\\s+difference\\s+between\\s+${SEED}\\s+and\\s+${SEED}\\s*\\??$`, 'i'),
+        kind: 'lookup', linkTypes: null, direction: 'both', seedGroups: 2,
+    });
+    patterns.push({
+        re: new RegExp(`\\bwhat\\s+does\\s+${SEED}\\s+(?:stand for|mean|refer to)\\b`, 'i'),
+        kind: 'lookup', linkTypes: null, direction: 'both', seedGroups: 1,
+    });
+    patterns.push({
+        re: new RegExp(`\\btell\\s+me\\s+about\\s+${SEED}\\s*\\??$`, 'i'),
+        kind: 'lookup', linkTypes: null, direction: 'both', seedGroups: 1,
+    });
+    patterns.push({
+        re: new RegExp(`\\b(?:who|what)(?:'s|\\s+(?:is|are|was|were))\\s+${SEED}\\s*\\??$`, 'i'),
+        kind: 'lookup', linkTypes: null, direction: 'both', seedGroups: 1,
+    });
+    return patterns;
+}
+function cleanSeed(raw) {
+    return raw
+        .trim()
+        .replace(/\?+$/, '')
+        .replace(/^["'`]|["'`]$/g, '')
+        .replace(/^(?:the|a|an)\s+/i, '')
+        .trim();
+}
+function validSeed(s) {
+    if (s.length === 0 || s.length > 80)
+        return false;
+    if (STOPWORD_SEEDS.has(s.toLowerCase()))
+        return false;
+    return true;
+}
+/**
+ * Parse a query into a RelationalQuery, or null if it isn't relational.
+ * First matching pattern wins (patterns ordered specific → general).
+ */
+export function parseRelationalQuery(query) {
+    if (!query || query.length > 512)
+        return null;
+    const patterns = buildPatterns();
+    for (const p of patterns) {
+        const m = p.re.exec(query);
+        if (!m)
+            continue;
+        if (p.seedGroups === 2) {
+            const a = cleanSeed(m[1] ?? '');
+            const b = cleanSeed(m[2] ?? '');
+            if (!validSeed(a) || !validSeed(b))
+                continue;
+            return { kind: p.kind, seeds: [a, b], linkTypes: p.linkTypes, direction: p.direction, relationPhrase: m[0].trim() };
+        }
+        const seed = cleanSeed(m[1] ?? '');
+        if (!validSeed(seed))
+            continue;
+        return { kind: p.kind, seeds: [seed], linkTypes: p.linkTypes, direction: p.direction, relationPhrase: m[0].trim() };
+    }
+    return null;
+}
+//# sourceMappingURL=relational-intent.js.map

package/dist/relational-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relational-intent.js","sourceRoot":"","sources":["../src/relational-intent.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/brain-core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Kernel brain methods — timeline, entity-graph, facts, vectors, retrieval, sleep",
   "license": "MIT",
   "author": "David Cruwys (AppyDave)",
@@ -27,11 +27,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@kybernesis/brain-contracts": "0.10.0",
-    "@kybernesis/brain-storage-sqlite": "0.10.0"
+    "@kybernesis/brain-contracts": "0.12.0",
+    "@kybernesis/brain-storage-sqlite": "0.12.0"
   },
   "peerDependencies": {
-    "@kybernesis/brain-storage-vec": "0.10.0"
+    "@kybernesis/brain-storage-vec": "0.12.0"
   },
   "peerDependenciesMeta": {
     "@kybernesis/brain-storage-vec": {
@@ -39,8 +39,10 @@
     }
   },
   "devDependencies": {
-    "@kybernesis/brain-testkit": "0.10.0",
-    "@kybernesis/brain-storage-vec": "0.10.0"
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.10.0",
+    "@kybernesis/brain-testkit": "0.12.0",
+    "@kybernesis/brain-storage-vec": "0.12.0"
   },
   "publishConfig": {
     "access": "public"