@soulcraft/brainy 4.1.4 → 4.2.1

package/dist/neural/signals/ContextSignal.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ContextSignal - Relationship-based entity type classification
+ *
+ * PRODUCTION-READY: Infers types from relationship patterns in context
+ *
+ * Weight: 5% (lowest, but critical for ambiguous cases)
+ * Speed: Very fast (~1ms) - pure pattern matching on context
+ *
+ * Key insight: Context reveals type even when entity itself is ambiguous
+ * Examples:
+ * - "CEO of X" → X is Organization
+ * - "lives in Y" → Y is Location
+ * - "uses Z" → Z is Technology
+ * - "attended W" → W is Event
+ *
+ * This signal fills the gap when:
+ * - Entity is too ambiguous for other signals
+ * - Multiple signals conflict
+ * - Need relationship-aware classification
+ */
+import type { Brainy } from '../../brainy.js';
+import type { NounType } from '../../types/graphTypes.js';
+/**
+ * Signal result with classification details
+ */
+export interface TypeSignal {
+    source: 'context-relationship' | 'context-attribute' | 'context-combined';
+    type: NounType;
+    confidence: number;
+    evidence: string;
+    metadata?: {
+        relationshipPattern?: string;
+        contextMatch?: string;
+        relatedEntities?: string[];
+    };
+}
+/**
+ * Options for context signal
+ */
+export interface ContextSignalOptions {
+    minConfidence?: number;
+    timeout?: number;
+    cacheSize?: number;
+}
+/**
+ * ContextSignal - Infer entity types from relationship context
+ *
+ * Production features:
+ * - 50+ relationship patterns organized by type
+ * - Attribute patterns (e.g., "fast X" → X is Object/Technology)
+ * - Multi-pattern matching with confidence boosting
+ * - LRU cache for hot entities
+ * - Graceful degradation on errors
+ */
+export declare class ContextSignal {
+    private brain;
+    private options;
+    private relationshipPatterns;
+    private cache;
+    private cacheOrder;
+    private stats;
+    constructor(brain: Brainy, options?: ContextSignalOptions);
+    /**
+     * Initialize relationship patterns
+     *
+     * Patterns organized by target type:
+     * - Person: roles, actions, possessives
+     * - Organization: membership, leadership, employment
+     * - Location: spatial relationships, residence
+     * - Technology: usage, implementation, integration
+     * - Event: attendance, occurrence, scheduling
+     * - Concept: understanding, application, theory
+     * - Object: ownership, interaction, description
+     */
+    private initializePatterns;
+    /**
+     * Add relationship patterns in bulk
+     */
+    private addPatterns;
+    /**
+     * Classify entity type using context-based signals
+     *
+     * Main entry point - checks relationship patterns in definition/context
+     *
+     * @param candidate Entity text to classify
+     * @param context Context with definition and related entities
+     * @returns TypeSignal with classification result
+     */
+    classify(candidate: string, context?: {
+        definition?: string;
+        allTerms?: string[];
+        metadata?: any;
+    }): Promise<TypeSignal | null>;
+    /**
+     * Build search text from candidate and context
+     *
+     * Extracts text around candidate to find relationship patterns
+     */
+    private buildSearchText;
+    /**
+     * Match relationship patterns in context
+     *
+     * Looks for patterns like "CEO of X" where X is the candidate
+     */
+    private matchRelationshipPatterns;
+    /**
+     * Match attribute patterns in context
+     *
+     * Looks for descriptive patterns like "fast X" where X is the candidate
+     */
+    private matchAttributePatterns;
+    /**
+     * Combine results from relationship and attribute matching
+     *
+     * Prefers relationship matches over attribute matches
+     */
+    private combineResults;
+    /**
+     * Get statistics about signal performance
+     */
+    getStats(): {
+        cacheSize: number;
+        cacheHitRate: number;
+        relationshipMatchRate: number;
+        attributeMatchRate: number;
+        calls: number;
+        cacheHits: number;
+        relationshipMatches: number;
+        attributeMatches: number;
+        combinedMatches: number;
+    };
+    /**
+     * Reset statistics (useful for testing)
+     */
+    resetStats(): void;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+    /**
+     * Get pattern count (for testing)
+     */
+    getPatternCount(): number;
+    /**
+     * Generate cache key from candidate and context
+     */
+    private getCacheKey;
+    /**
+     * Get from LRU cache (returns undefined if not found, null if cached as null)
+     */
+    private getFromCache;
+    /**
+     * Add to LRU cache with eviction
+     */
+    private addToCache;
+    /**
+     * Escape special regex characters
+     */
+    private escapeRegex;
+}
+/**
+ * Create a new ContextSignal instance
+ *
+ * Convenience factory function
+ */
+export declare function createContextSignal(brain: Brainy, options?: ContextSignalOptions): ContextSignal;