@ninebix/nmt-system 1.0.0

package/dist/src/core/attractor-model.d.ts

@@ -0,0 +1,381 @@
+/**
+ * Future Attractor Model - Goal-Driven Probability Steering
+ *
+ * Based on Probabilistic Ontology Framework - Teleological Determinism:
+ * - Future states act as "attractors" that influence present choices
+ * - Current state probabilities are shaped by potential futures
+ * - Goals create probability gradients that guide decision paths
+ *
+ * @module core/attractor-model
+ */
+import type { UUID, Embedding384, INeuronStore } from '../types/index.js';
+/**
+ * Attractor state representing a future goal
+ */
+export interface Attractor {
+    id: UUID;
+    name: string;
+    description: string;
+    embedding: Embedding384;
+    strength: number;
+    probability: number;
+    priority: number;
+    deadline?: string;
+    prerequisites: UUID[];
+    createdAt: string;
+    updatedAt: string;
+    activations: number;
+}
+/**
+ * Probability field around an attractor
+ */
+export interface ProbabilityField {
+    attractor: Attractor;
+    gradient: Map<UUID, number>;
+    reachableStates: UUID[];
+    pathProbabilities: PathProbability[];
+}
+/**
+ * Probability of a path to attractor
+ */
+export interface PathProbability {
+    path: UUID[];
+    probability: number;
+    estimatedSteps: number;
+    bottlenecks: UUID[];
+}
+/**
+ * Current state in the probability space
+ */
+export interface CurrentState {
+    neuronId: UUID;
+    embedding: Embedding384;
+    timestamp: string;
+    activeAttractors: UUID[];
+    dominantAttractor?: UUID;
+    transitionProbabilities: Map<UUID, number>;
+}
+/**
+ * Transition between states
+ */
+export interface StateTransition {
+    from: UUID;
+    to: UUID;
+    probability: number;
+    attractorInfluence: Map<UUID, number>;
+    timestamp: string;
+}
+/**
+ * A* Search Result
+ */
+export interface AStarResult {
+    found: boolean;
+    path: UUID[];
+    totalCost: number;
+    nodesExplored: number;
+    pathProbability: number;
+    bottlenecks: {
+        nodeId: UUID;
+        costContribution: number;
+    }[];
+}
+/**
+ * Attractor Model Options
+ */
+export interface AttractorModelOptions {
+    neuronStore: INeuronStore;
+    maxAttractors?: number;
+    defaultStrength?: number;
+    decayRate?: number;
+    influenceRadius?: number;
+    heuristicWeight?: number;
+    maxSearchNodes?: number;
+}
+/**
+ * Attractor Model - Goal-Driven Probability Steering
+ *
+ * Implements teleological determinism where future goals (attractors)
+ * influence present state probabilities through probability fields.
+ *
+ * Key Concepts:
+ * - **Attractors**: Future goal states that "pull" the system towards them
+ * - **Probability Fields**: Gradients that guide state transitions
+ * - **Influence**: How strongly an attractor affects current decisions
+ *
+ * @example
+ * ```typescript
+ * const model = new AttractorModel({ neuronStore: store });
+ *
+ * // Create a goal attractor
+ * const attractor = model.createAttractor(
+ *   'goal-1',
+ *   'Complete Project',
+ *   'Finish all remaining tasks',
+ *   goalEmbedding,
+ *   { strength: 0.8, priority: 10 }
+ * );
+ *
+ * // Calculate influence on current state
+ * const influence = model.calculateInfluence(currentStateEmbedding);
+ * console.log(`Goal influence: ${influence.get('goal-1')}`);
+ *
+ * // Find path to goal
+ * const path = await model.findPathToAttractor('current-neuron', 'goal-1');
+ * console.log(`Path probability: ${path?.probability}`);
+ * ```
+ *
+ * @see {@link Attractor} for attractor state structure
+ * @see {@link ProbabilityField} for field configuration
+ */
+export declare class AttractorModel {
+    private store;
+    private maxAttractors;
+    private defaultStrength;
+    private decayRate;
+    private influenceRadius;
+    private heuristicWeight;
+    private maxSearchNodes;
+    private attractors;
+    private fields;
+    private stateHistory;
+    private transitions;
+    private dominantAttractor;
+    private embeddingCache;
+    constructor(options: AttractorModelOptions);
+    /**
+     * Create a new attractor (future goal state).
+     *
+     * Attractors represent desired future states that influence present
+     * probability distributions. The strength and priority determine how
+     * much pull the attractor has on state transitions.
+     *
+     * @param id - Unique identifier for the attractor
+     * @param name - Human-readable name for the goal
+     * @param description - Detailed description of the goal state
+     * @param embedding - Semantic embedding representing the goal
+     * @param options - Configuration options
+     * @param options.strength - Pull strength (0-1), default: 0.5
+     * @param options.probability - Initial probability of reaching (0-1), default: 0.5
+     * @param options.priority - User-defined priority (1-10), default: 5
+     * @param options.deadline - Optional ISO8601 deadline
+     * @param options.prerequisites - IDs of required states before this
+     * @returns The created Attractor object
+     *
+     * @example
+     * ```typescript
+     * const attractor = model.createAttractor(
+     *   'learn-typescript',
+     *   'Master TypeScript',
+     *   'Become proficient in TypeScript development',
+     *   tsEmbedding,
+     *   { strength: 0.9, priority: 8, deadline: '2024-12-31' }
+     * );
+     * ```
+     */
+    createAttractor(id: UUID, name: string, description: string, embedding: Embedding384, options?: Partial<Omit<Attractor, 'id' | 'name' | 'description' | 'embedding' | 'createdAt' | 'updatedAt' | 'activations'>>): Attractor;
+    /**
+     * Get attractor by ID
+     */
+    getAttractor(id: UUID): Attractor | undefined;
+    /**
+     * Update attractor properties
+     */
+    updateAttractor(id: UUID, updates: Partial<Attractor>): Attractor | null;
+    /**
+     * Calculate influence of all attractors on a given state.
+     *
+     * Influence is calculated using exponential decay based on semantic
+     * distance, multiplied by attractor strength and priority.
+     *
+     * @param stateEmbedding - The current state's embedding vector
+     * @returns Map of attractor IDs to their influence values (0-1)
+     *
+     * @example
+     * ```typescript
+     * const influences = model.calculateInfluence(currentEmbedding);
+     * for (const [attractorId, influence] of influences) {
+     *   if (influence > 0.5) {
+     *     console.log(`Strong pull from ${attractorId}: ${influence}`);
+     *   }
+     * }
+     * ```
+     */
+    calculateInfluence(stateEmbedding: Embedding384): Map<UUID, number>;
+    /**
+     * Get the dominant attractor for a state
+     */
+    getDominantAttractor(stateEmbedding: Embedding384): Attractor | null;
+    /**
+     * Calculate transition probabilities from current state
+     */
+    calculateTransitionProbabilities(currentNeuronId: UUID, candidateIds: UUID[]): Promise<Map<UUID, number>>;
+    /**
+     * Find optimal path from current state to an attractor using A* algorithm.
+     *
+     * A* guarantees the optimal path by combining:
+     * - g(n): Actual cost from start to node n
+     * - h(n): Heuristic estimate from n to goal (semantic distance)
+     * - f(n) = g(n) + h(n): Total estimated cost
+     *
+     * The heuristic uses semantic distance (1 - cosine similarity) which is
+     * admissible (never overestimates) for semantic spaces.
+     *
+     * @param currentNeuronId - Starting neuron ID
+     * @param attractorId - Target attractor ID
+     * @param maxDepth - Maximum search depth, default: 10
+     * @returns Path information including probability and bottlenecks, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const result = await model.findPathToAttractor('start', 'goal', 10);
+     * if (result.found) {
+     *   console.log(`Optimal path: ${result.path.join(' → ')}`);
+     *   console.log(`Path probability: ${(result.pathProbability * 100).toFixed(1)}%`);
+     *   console.log(`Nodes explored: ${result.nodesExplored}`);
+     *   for (const bottleneck of result.bottlenecks) {
+     *     console.log(`Bottleneck: ${bottleneck.nodeId} (cost: ${bottleneck.costContribution})`);
+     *   }
+     * }
+     * ```
+     */
+    findPathToAttractor(currentNeuronId: UUID, attractorId: UUID, maxDepth?: number): Promise<PathProbability | null>;
+    /**
+     * A* Search Algorithm Implementation
+     *
+     * Uses:
+     * - g(n) = sum of edge costs (1 - synapse.weight) from start
+     * - h(n) = semantic distance (1 - cosine_similarity) to goal
+     * - f(n) = g(n) + w * h(n) where w is heuristicWeight
+     *
+     * @param startId - Starting neuron ID
+     * @param goal - Target attractor
+     * @param maxDepth - Maximum path length
+     * @returns A* search result with path, cost, and bottlenecks
+     */
+    aStarSearch(startId: UUID, goal: Attractor, maxDepth?: number): Promise<AStarResult>;
+    /**
+     * Calculate heuristic for A* (semantic distance to goal)
+     *
+     * Uses 1 - cosine_similarity as distance metric.
+     * This heuristic is admissible for semantic spaces.
+     */
+    private calculateHeuristic;
+    /**
+     * Reconstruct path from A* search
+     */
+    private reconstructPath;
+    /**
+     * Calculate path probability (product of edge weights)
+     */
+    private calculatePathProbability;
+    /**
+     * Identify bottlenecks from A* search (high-cost edges)
+     */
+    private identifyAStarBottlenecks;
+    /**
+     * Find multiple alternative paths to attractor
+     *
+     * Uses A* with path exclusion to find k-best paths
+     */
+    findAlternativePaths(currentNeuronId: UUID, attractorId: UUID, k?: number, maxDepth?: number): Promise<AStarResult[]>;
+    /**
+     * A* search with path exclusion for k-best paths
+     */
+    private aStarSearchWithExclusion;
+    /**
+     * Bidirectional A* search for faster pathfinding
+     *
+     * Searches from both start and goal simultaneously
+     */
+    bidirectionalAStarSearch(startId: UUID, attractorId: UUID, maxDepth?: number): Promise<AStarResult>;
+    /**
+     * Clear embedding cache to free memory
+     */
+    clearCache(): void;
+    /**
+     * Record a state transition between neurons.
+     *
+     * Tracks how state transitions are influenced by attractors,
+     * updating attractor activation counts when transitions move
+     * towards them.
+     *
+     * @param fromId - Source neuron ID
+     * @param toId - Target neuron ID
+     * @returns The recorded transition with attractor influences
+     * @throws Error if either neuron ID is invalid
+     */
+    recordTransition(fromId: UUID, toId: UUID): Promise<StateTransition>;
+    /**
+     * Update attractor probabilities based on current state
+     */
+    updateAttractorProbabilities(currentNeuronId: UUID): Promise<void>;
+    /**
+     * Decay attractor strengths over time.
+     *
+     * Applies exponential decay to attractors that haven't been
+     * updated in 24+ hours. Very weak attractors with few activations
+     * are automatically removed.
+     *
+     * Call this periodically (e.g., hourly) to maintain attractor health.
+     */
+    decayAttractors(): void;
+    /**
+     * Get all active attractors
+     */
+    getActiveAttractors(): Attractor[];
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        totalAttractors: number;
+        activeAttractors: number;
+        transitions: number;
+        stateHistory: number;
+        averageStrength: number;
+        averageActivations: number;
+    };
+    /**
+     * Serialize attractor model state for persistence.
+     *
+     * Converts all attractors, transitions, and state to a JSON-serializable
+     * object. Embeddings are converted to plain arrays.
+     *
+     * @returns Serialized state object for storage
+     * @see {@link load} for restoring state
+     */
+    serialize(): object;
+    /**
+     * Load attractor model from serialized data.
+     *
+     * Restores all attractors, transitions, and state from previously
+     * serialized data. Embeddings are converted back to Float32Array.
+     *
+     * @param data - Previously serialized attractor model state
+     * @see {@link serialize} for creating serialized state
+     */
+    load(data: any): void;
+    private updateProbabilityField;
+    private pruneWeakestAttractor;
+    /**
+     * Simple bottleneck identification for legacy compatibility
+     * @deprecated Use identifyAStarBottlenecks for accurate bottleneck detection
+     */
+    private identifyBottlenecks;
+    /**
+     * Get path cost breakdown
+     */
+    analyzePathCost(path: UUID[]): Promise<{
+        totalCost: number;
+        edgeCosts: {
+            from: UUID;
+            to: UUID;
+            cost: number;
+        }[];
+        avgCost: number;
+    }>;
+}
+/**
+ * Create an AttractorModel instance
+ */
+export declare function createAttractorModel(options: AttractorModelOptions): AttractorModel;
+//# sourceMappingURL=attractor-model.d.ts.map

package/dist/src/core/attractor-model.d.ts.map

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