@soulcraft/brainy 3.44.0 → 3.46.0

package/dist/vfs/ConceptSystem.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Universal Concept System for VFS
+ *
+ * Manages concepts that transcend files and exist independently
+ * Ideas that can be linked to multiple manifestations across domains
+ * PRODUCTION-READY: Real implementation using Brainy
+ */
+import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
+/**
+ * Universal concept that exists independently of files
+ */
+export interface UniversalConcept extends ManagedEntity {
+    id: string;
+    name: string;
+    description?: string;
+    domain: string;
+    category: string;
+    keywords: string[];
+    links: ConceptLink[];
+    manifestations: ConceptManifestation[];
+    strength: number;
+    created: number;
+    lastUpdated: number;
+    version: number;
+    metadata: Record<string, any>;
+    conceptType?: string;
+}
+/**
+ * A link between concepts
+ */
+export interface ConceptLink {
+    id: string;
+    targetConceptId: string;
+    relationship: 'extends' | 'implements' | 'uses' | 'opposite' | 'related' | 'contains' | 'part-of';
+    strength: number;
+    context?: string;
+    bidirectional: boolean;
+}
+/**
+ * A manifestation of a concept in a specific location
+ */
+export interface ConceptManifestation extends ManagedEntity {
+    id: string;
+    conceptId: string;
+    filePath: string;
+    context: string;
+    form: 'definition' | 'usage' | 'example' | 'discussion' | 'implementation';
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    confidence: number;
+    timestamp: number;
+    extractedBy: 'manual' | 'auto' | 'ai';
+}
+/**
+ * Configuration for concept system
+ */
+export interface ConceptSystemConfig {
+    autoLink?: boolean;
+    similarityThreshold?: number;
+    maxManifestations?: number;
+    strengthDecay?: number;
+}
+/**
+ * Concept graph structure for visualization
+ */
+export interface ConceptGraph {
+    concepts: Array<{
+        id: string;
+        name: string;
+        domain: string;
+        strength: number;
+        manifestationCount: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        relationship: string;
+        strength: number;
+    }>;
+}
+/**
+ * Universal Concept System
+ *
+ * Manages concepts that exist independently of any specific file or context
+ * Examples:
+ * - "Authentication" concept appearing in docs, code, tests
+ * - "Customer Journey" concept in marketing, UX, analytics
+ * - "Dependency Injection" pattern across multiple codebases
+ * - "Sustainability" theme in various research papers
+ */
+export declare class ConceptSystem extends EntityManager {
+    private config;
+    private conceptCache;
+    constructor(brain: Brainy, config?: ConceptSystemConfig);
+    /**
+     * Create a new universal concept
+     */
+    createConcept(concept: Omit<UniversalConcept, 'id' | 'created' | 'lastUpdated' | 'version' | 'links' | 'manifestations'>): Promise<string>;
+    /**
+     * Find concepts by various criteria
+     */
+    findConcepts(query: {
+        name?: string;
+        domain?: string;
+        category?: string;
+        keywords?: string[];
+        similar?: string;
+        manifestedIn?: string;
+    }): Promise<UniversalConcept[]>;
+    /**
+     * Link two concepts together
+     */
+    linkConcept(fromConceptId: string, toConceptId: string, relationship: ConceptLink['relationship'], options?: {
+        strength?: number;
+        context?: string;
+        bidirectional?: boolean;
+    }): Promise<string>;
+    /**
+     * Record a manifestation of a concept in a file
+     */
+    recordManifestation(conceptId: string, filePath: string, context: string, form: ConceptManifestation['form'], options?: {
+        position?: ConceptManifestation['position'];
+        confidence?: number;
+        extractedBy?: ConceptManifestation['extractedBy'];
+    }): Promise<string>;
+    /**
+     * Extract and link concepts from content
+     */
+    extractAndLinkConcepts(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Get concept graph for visualization
+     */
+    getConceptGraph(options?: {
+        domain?: string;
+        minStrength?: number;
+        maxConcepts?: number;
+    }): Promise<ConceptGraph>;
+    /**
+     * Find appearances of a concept
+     */
+    findAppearances(conceptId: string, options?: {
+        filePath?: string;
+        form?: ConceptManifestation['form'];
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<ConceptManifestation[]>;
+    /**
+     * Auto-link concept to similar concepts
+     */
+    private autoLinkConcept;
+    /**
+     * Get concept by ID
+     */
+    private getConcept;
+    /**
+     * Update stored concept
+     */
+    private updateConcept;
+    /**
+     * Calculate similarity between two concepts
+     */
+    private calculateConceptSimilarity;
+    /**
+     * Generate embedding for concept
+     */
+    private generateConceptEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Get reverse relationship type
+     */
+    private getReverseRelationship;
+    /**
+     * Map concept relationship to VerbType
+     */
+    private getVerbType;
+    /**
+     * Detect concept domain from context
+     */
+    private detectDomain;
+    /**
+     * Detect concept category
+     */
+    private detectCategory;
+    /**
+     * Detect manifestation form from context
+     */
+    private detectManifestationForm;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear concept cache
+     */
+    clearCache(conceptId?: string): void;
+}