@kybernesis/brain-core 0.1.0

package/dist/fact-contradiction.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fact contradiction detection — port of KAD's fact-contradiction.ts.
+ *
+ * When new facts are stored, checks if they contradict existing facts
+ * for the same entities. Uses Claude Haiku for semantic comparison.
+ */
+import type { TenantContext } from '@kybernesis/brain-contracts';
+export interface ContradictionResult {
+    contradictions: Array<{
+        oldFactId: number;
+        relationship: 'updates' | 'extends';
+        rationale: string;
+    }>;
+    checked: number;
+}
+/**
+ * Detect contradictions between a new fact and existing facts for the same
+ * entities. Returns which existing facts are updated or extended by the new one.
+ */
+export declare function detectContradictions(t: TenantContext, newFact: {
+    content: string;
+    entities: string[];
+    category: string;
+}): Promise<ContradictionResult>;
+//# sourceMappingURL=fact-contradiction.d.ts.map

package/dist/fact-contradiction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-contradiction.d.ts","sourceRoot":"","sources":["../src/fact-contradiction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAKjE,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,KAAK,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,SAAS,GAAG,SAAS,CAAC;QACpC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,CAAC,EAAE,aAAa,EAChB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjE,OAAO,CAAC,mBAAmB,CAAC,CAmF9B"}

package/dist/fact-contradiction.js

@@ -0,0 +1,109 @@
+/**
+ * Fact contradiction detection — port of KAD's fact-contradiction.ts.
+ *
+ * When new facts are stored, checks if they contradict existing facts
+ * for the same entities. Uses Claude Haiku for semantic comparison.
+ */
+import { getFactsForEntity } from './fact-store.js';
+import { callClaude } from './claude-call.js';
+const RELATED_CATEGORIES = {
+    biographical: new Set(['biographical']),
+    preference: new Set(['preference']),
+    event: new Set(['event', 'temporal']),
+    relationship: new Set(['relationship']),
+    temporal: new Set(['event', 'temporal']),
+    opinion: new Set(['opinion']),
+    plan: new Set(['plan']),
+    general: new Set([
+        'biographical', 'preference', 'event', 'relationship',
+        'temporal', 'opinion', 'plan', 'general',
+    ]),
+};
+function areCategoriesRelated(a, b) {
+    const related = RELATED_CATEGORIES[a];
+    if (!related)
+        return true;
+    return related.has(b);
+}
+/**
+ * Detect contradictions between a new fact and existing facts for the same
+ * entities. Returns which existing facts are updated or extended by the new one.
+ */
+export async function detectContradictions(t, newFact) {
+    if (!newFact.entities || newFact.entities.length === 0) {
+        return { contradictions: [], checked: 0 };
+    }
+    const candidateMap = new Map();
+    for (const entity of newFact.entities) {
+        try {
+            const facts = await getFactsForEntity(t, entity, { latestOnly: true, limit: 20 });
+            for (const fact of facts)
+                candidateMap.set(fact.id, fact);
+        }
+        catch (err) {
+            console.warn(`[brain-core/fact-contradiction] fetch failed for "${entity}"`, { err: String(err) });
+        }
+    }
+    const candidates = Array.from(candidateMap.values()).filter((f) => areCategoriesRelated(newFact.category, f.category));
+    if (candidates.length === 0)
+        return { contradictions: [], checked: 0 };
+    const toCheck = candidates.slice(0, 10);
+    try {
+        const existingList = toCheck
+            .map((f, i) => `${i + 1}. "${f.content}" (id=${f.id})`)
+            .join('\n');
+        const prompt = `Given a NEW fact and a list of EXISTING facts about the same person/entity, determine if the new fact contradicts (updates/replaces) any existing fact.
+
+NEW FACT: "${newFact.content}"
+
+EXISTING FACTS:
+${existingList}
+
+For each existing fact, determine:
+- "updates" — the new fact replaces this (e.g., "favorite color is green" updates "favorite color is blue")
+- "extends" — the new fact adds detail without contradicting (e.g., "lives in Brooklyn" extends "lives in NYC")
+- "none" — no relationship
+
+Return JSON array:
+[{"id": 42, "relationship": "updates", "rationale": "favorite color changed"}]
+
+Only include facts with "updates" or "extends" relationship. Return [] if no relationships found.`;
+        const response = await callClaude(prompt, { maxTokens: 512 });
+        if (!response)
+            return { contradictions: [], checked: toCheck.length };
+        const jsonMatch = response.match(/\[[\s\S]*?\]/);
+        if (!jsonMatch)
+            return { contradictions: [], checked: toCheck.length };
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonMatch[0]);
+            if (!Array.isArray(parsed))
+                return { contradictions: [], checked: toCheck.length };
+        }
+        catch {
+            return { contradictions: [], checked: toCheck.length };
+        }
+        const validIds = new Set(toCheck.map((f) => f.id));
+        const contradictions = parsed
+            .filter((item) => {
+            if (!item || typeof item !== 'object')
+                return false;
+            const o = item;
+            return (typeof o['id'] === 'number' &&
+                validIds.has(o['id']) &&
+                (o['relationship'] === 'updates' || o['relationship'] === 'extends') &&
+                typeof o['rationale'] === 'string');
+        })
+            .map((item) => ({
+            oldFactId: item.id,
+            relationship: item.relationship,
+            rationale: item.rationale,
+        }));
+        return { contradictions, checked: toCheck.length };
+    }
+    catch (err) {
+        console.warn('[brain-core/fact-contradiction] detection failed', { err: String(err) });
+        return { contradictions: [], checked: toCheck.length };
+    }
+}
+//# sourceMappingURL=fact-contradiction.js.map

package/dist/fact-contradiction.js.map

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

package/dist/fact-extractor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Real-time fact extraction — port of KAD's fact-extractor.ts.
+ *
+ * Lightweight inline extraction that runs after a conversation is stored.
+ * Haiku-backed, capped at 3 facts per call to keep latency low.
+ */
+import type { TenantContext } from '@kybernesis/brain-contracts';
+/**
+ * Extract facts from a conversation in real-time (best-effort).
+ * Called after entity graph storage in storeConversation().
+ * Never throws — all errors are caught and logged.
+ */
+export declare function extractFactsRealtime(t: TenantContext, conversationId: string, text: string, options?: {
+    entities?: string[];
+    sourcePath?: string;
+    timestamp?: string;
+    sourceType?: string;
+    arpMetadata?: {
+        project_id?: string;
+        tags?: string[];
+        classification?: 'public' | 'internal' | 'confidential' | 'pii';
+        connection_id?: string;
+        source_did?: string;
+    };
+}): Promise<number>;
+//# sourceMappingURL=fact-extractor.d.ts.map

package/dist/fact-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-extractor.d.ts","sourceRoot":"","sources":["../src/fact-extractor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AA0BjE;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,CAAC,EAAE,aAAa,EAChB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QACZ,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,cAAc,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,KAAK,CAAC;QAChE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACE,GACL,OAAO,CAAC,MAAM,CAAC,CAgFjB"}

package/dist/fact-extractor.js

@@ -0,0 +1,98 @@
+/**
+ * Real-time fact extraction — port of KAD's fact-extractor.ts.
+ *
+ * Lightweight inline extraction that runs after a conversation is stored.
+ * Haiku-backed, capped at 3 facts per call to keep latency low.
+ */
+import { SOURCE_CONFIDENCE } from '@kybernesis/brain-contracts';
+import { storeFact, ensureFactsTable } from './fact-store.js';
+import { detectTemporalExpiry } from './fact-temporal.js';
+import { callClaude } from './claude-call.js';
+const VALID_CATEGORIES = new Set([
+    'biographical', 'preference', 'event', 'relationship',
+    'temporal', 'opinion', 'plan', 'general',
+]);
+const REALTIME_FACT_PROMPT = `Extract 1-3 concrete facts about specific people, companies, or projects from this conversation. Only clear, verifiable facts — skip vague observations, greetings, and meta-commentary.
+
+Each fact object has:
+- "content": The fact statement (8-25 words, include names not pronouns)
+- "category": One of: biographical, preference, event, relationship, temporal, opinion, plan, general
+- "confidence": 0.5-0.9 (how confident you are)
+- "entities": Array of person/entity names
+
+Return a JSON array, or [] if no concrete facts.
+
+Conversation:
+`;
+/**
+ * Extract facts from a conversation in real-time (best-effort).
+ * Called after entity graph storage in storeConversation().
+ * Never throws — all errors are caught and logged.
+ */
+export async function extractFactsRealtime(t, conversationId, text, options = {}) {
+    const { entities = [], sourcePath = `realtime://${conversationId}`, timestamp = new Date().toISOString(), sourceType = 'chat', arpMetadata, } = options;
+    // Guard: skip short conversations or those with no entities
+    if (text.length < 50 || entities.length === 0)
+        return 0;
+    await ensureFactsTable(t);
+    let factsCreated = 0;
+    try {
+        const content = text.slice(0, 2000);
+        const response = await callClaude(REALTIME_FACT_PROMPT + content, { maxTokens: 256 });
+        if (!response)
+            return 0;
+        const jsonMatch = response.match(/\[[\s\S]*\]/);
+        if (!jsonMatch)
+            return 0;
+        let rawFacts;
+        try {
+            const parsed = JSON.parse(jsonMatch[0]);
+            if (!Array.isArray(parsed))
+                return 0;
+            rawFacts = parsed;
+        }
+        catch (err) {
+            console.warn('[brain-core/fact-extractor] JSON parse failed', { err: String(err) });
+            return 0;
+        }
+        const parentId = sourcePath.replace('channel://', '');
+        const maxConfidence = SOURCE_CONFIDENCE[sourceType] ?? 0.85;
+        for (const [i, fact] of rawFacts.slice(0, 3).entries()) {
+            if (!fact.content || fact.content.length < 10 || fact.content.length > 200)
+                continue;
+            if (!fact.entities || fact.entities.length === 0)
+                continue;
+            const category = VALID_CATEGORIES.has(fact.category) ? fact.category : 'general';
+            const confidence = Math.min(fact.confidence || 0.6, maxConfidence, 0.60);
+            const temporal = detectTemporalExpiry(fact.content, timestamp);
+            const factInput = {
+                content: fact.content,
+                sourcePath: `realtime://${parentId}/${i}`,
+                sourceConversationId: parentId,
+                entities: fact.entities,
+                timestamp,
+                confidence,
+                category: category,
+                sourceType: 'ai-extraction',
+                ...(temporal.expires_at ? { expiresAt: temporal.expires_at } : {}),
+                ...(arpMetadata?.project_id ? { projectId: arpMetadata.project_id } : {}),
+                tags: arpMetadata?.tags ?? [],
+                ...(arpMetadata?.classification ? { classification: arpMetadata.classification } : {}),
+                ...(arpMetadata?.connection_id ? { connectionId: arpMetadata.connection_id } : {}),
+                ...(arpMetadata?.source_did ? { sourceDid: arpMetadata.source_did } : {}),
+            };
+            try {
+                await storeFact(t, factInput);
+                factsCreated++;
+            }
+            catch {
+                // Individual fact storage is best-effort
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[brain-core/fact-extractor] extraction skipped', { error: String(err) });
+    }
+    return factsCreated;
+}
+//# sourceMappingURL=fact-extractor.js.map

package/dist/fact-extractor.js.map

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

package/dist/fact-retrieval.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Fact-first retrieval engine — port of KAD's fact-retrieval.ts.
+ *
+ * 4-layer retrieval:
+ *   Layer 1:   Direct FTS5 + semantic search on facts
+ *   Layer 2:   Entity expansion (1-3 hop BFS graph traversal)
+ *   Layer 2.5: Scene expansion + bridge discovery
+ *   Layer 3:   Supporting context (source conversation segments)
+ *   Layer 4:   Context optimization (prune to token budget, deduplicate)
+ *
+ * Bug Fix #2 applied here: uses sanitizeFtsQuery for all FTS MATCH calls.
+ * Bug Fix #9 applied here: wordMatchRatio denominator is FTS-query token count.
+ */
+import type { TenantContext } from '@kybernesis/brain-contracts';
+export interface FactSearchOptions {
+    limit?: number;
+    tokenBudget?: number;
+    includeSupporting?: boolean;
+    maxSupportingPerFact?: number;
+}
+export interface FactSearchResult {
+    facts: Array<{
+        id: number;
+        content: string;
+        category: string;
+        confidence: number;
+        timestamp: string;
+        entities: string[];
+        score: number;
+        source: 'direct' | 'entity_expansion' | 'graph_expansion' | 'scene_expansion' | 'bridge';
+    }>;
+    supporting_context: Array<{
+        content: string;
+        source_path: string;
+        timestamp: string;
+        related_fact_id: number;
+    }>;
+    assembled_context: string;
+    token_estimate: number;
+    stats: {
+        direct_facts: number;
+        expanded_facts: number;
+        graph_expanded_facts: number;
+        scene_expanded_facts: number;
+        bridge_facts: number;
+        supporting_chunks: number;
+        pruned_items: number;
+    };
+}
+export declare function factFirstSearch(t: TenantContext, query: string, options?: FactSearchOptions): Promise<FactSearchResult>;
+//# sourceMappingURL=fact-retrieval.d.ts.map

package/dist/fact-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-retrieval.d.ts","sourceRoot":"","sources":["../src/fact-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,QAAQ,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,QAAQ,CAAC;KAC1F,CAAC,CAAC;IACH,kBAAkB,EAAE,KAAK,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAgUD,wBAAsB,eAAe,CACnC,CAAC,EAAE,aAAa,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA4I3B"}