agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist/src/types/attention.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Attention Type Definitions for AgentDB v2
+ *
+ * Shared types for @ruvector/attention integration across memory controllers.
+ * These types are used by AttentionService and all enhanced controllers.
+ *
+ * @module types/attention
+ * @see controllers/AttentionService
+ * @see docs/integration/ARCHITECTURE.md
+ */
+/**
+ * Available attention mechanisms from @ruvector/attention
+ */
+export type AttentionMechanism = 'multihead' | 'flash' | 'hyperbolic' | 'graphrope' | 'moe' | 'dualspace' | 'linear';
+/**
+ * Runtime environment detection
+ */
+export type AttentionRuntime = 'node' | 'browser' | 'auto';
+/**
+ * Backend implementation (NAPI for Node.js, WASM for browser)
+ */
+export type AttentionBackend = 'napi' | 'wasm';
+/**
+ * Configuration for memory controllers with attention enhancements
+ */
+export interface MemoryControllerAttentionConfig {
+    /** Enable hyperbolic attention for CausalMemoryGraph */
+    enableHyperbolicAttention?: boolean;
+    /** Enable FlashAttention for large memory consolidation */
+    enableFlashAttention?: boolean;
+    /** Enable GraphRoPE for graph-aware retrieval */
+    enableGraphRoPE?: boolean;
+    /** Enable MoE for expert routing */
+    enableMoERouting?: boolean;
+    /** Enable DualSpace for hybrid retrieval */
+    enableDualSpace?: boolean;
+    /** Hyperbolic attention curvature (default: -1.0) */
+    hyperbolicCurvature?: number;
+    /** FlashAttention block size (default: 256) */
+    flashBlockSize?: number;
+    /** GraphRoPE maximum hops (default: 32) */
+    maxGraphHops?: number;
+    /** MoE number of experts (default: 4) */
+    numExperts?: number;
+    /** MoE top-k expert selection (default: 1) */
+    expertTopK?: number;
+    /** Fallback to vector search on errors (default: true) */
+    fallbackToVector?: boolean;
+}
+/**
+ * Search result with attention scores (extends standard SearchResult)
+ */
+export interface AttentionEnhancedResult {
+    /** Original result ID */
+    id: string | number;
+    /** Original similarity/distance */
+    similarity: number;
+    /** Attention weight (0-1, higher = more relevant) */
+    attentionScore?: number;
+    /** Mechanism used for re-ranking */
+    mechanism?: AttentionMechanism;
+    /** Attention-weighted final score */
+    finalScore?: number;
+    /** Optional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Causal query with hyperbolic attention options
+ */
+export interface CausalQueryWithAttention {
+    /** Base causal query parameters */
+    interventionMemoryId: number;
+    interventionMemoryType: string;
+    outcomeMemoryId?: number;
+    minConfidence?: number;
+    minUplift?: number;
+    /** Hyperbolic attention options */
+    useHyperbolicAttention?: boolean;
+    curvature?: number;
+    temperature?: number;
+    /** Return attention weights for visualization */
+    returnWeights?: boolean;
+}
+/**
+ * Causal edge with hyperbolic attention metadata
+ */
+export interface CausalEdgeWithAttention {
+    /** Standard causal edge fields */
+    id?: number;
+    fromMemoryId: number;
+    fromMemoryType: string;
+    toMemoryId: number;
+    toMemoryType: string;
+    similarity: number;
+    uplift?: number;
+    confidence: number;
+    /** Hyperbolic attention enhancements */
+    hyperbolicScore?: number;
+    attentionWeight?: number;
+    mechanism?: 'hyperbolic' | 'vector';
+    /** Tree distance in Poincaré ball */
+    poincareDistance?: number;
+}
+/**
+ * Pattern search query with Flash/MoE attention options
+ */
+export interface PatternSearchWithAttention {
+    /** Base pattern search parameters */
+    task?: string;
+    taskEmbedding?: Float32Array;
+    k?: number;
+    threshold?: number;
+    /** Flash attention for large libraries */
+    useFlashAttention?: boolean;
+    blockSize?: number;
+    /** MoE routing to specialized experts */
+    useMoERouting?: boolean;
+    numExperts?: number;
+    expertTopK?: number;
+    /** Return routing decisions */
+    returnExpertRouting?: boolean;
+}
+/**
+ * Reasoning pattern with attention metadata
+ */
+export interface ReasoningPatternWithAttention {
+    /** Standard pattern fields */
+    id?: number;
+    taskType: string;
+    approach: string;
+    successRate: number;
+    uses?: number;
+    avgReward?: number;
+    /** Attention enhancements */
+    flashScore?: number;
+    expertId?: number;
+    expertScore?: number;
+    routingWeight?: number;
+}
+/**
+ * Explanation query with GraphRoPE options
+ */
+export interface ExplanationQueryWithAttention {
+    /** Base explanation parameters */
+    query: string;
+    maxDepth?: number;
+    minConfidence?: number;
+    /** GraphRoPE for hop-aware ranking */
+    useGraphRoPE?: boolean;
+    maxHops?: number;
+    hopDecayFactor?: number;
+    /** Return attention heatmap for visualization */
+    returnAttentionHeatmap?: boolean;
+}
+/**
+ * Explanation chain with graph attention metadata
+ */
+export interface ExplanationChainWithAttention {
+    /** Standard explanation fields */
+    nodes: Array<{
+        id: number;
+        type: string;
+        content: string;
+    }>;
+    edges: Array<{
+        from: number;
+        to: number;
+        mechanism: string;
+    }>;
+    confidence: number;
+    /** GraphRoPE enhancements */
+    hopDistances?: number[];
+    graphRoPEScores?: number[];
+    positionalBias?: number[];
+}
+/**
+ * Attention heatmap data for visualization
+ */
+export interface AttentionHeatmap {
+    /** Query identifier */
+    queryId: string;
+    /** Key identifiers */
+    keyIds: string[];
+    /** Attention weights matrix (queries × keys) */
+    weights: number[][];
+    /** Mechanism used */
+    mechanism: AttentionMechanism;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Attention weight distribution stats
+ */
+export interface AttentionWeightStats {
+    /** Mean attention weight */
+    mean: number;
+    /** Standard deviation */
+    stdDev: number;
+    /** Entropy (measure of distribution uniformity) */
+    entropy: number;
+    /** Maximum weight */
+    max: number;
+    /** Minimum weight */
+    min: number;
+    /** Top-k indices */
+    topKIndices: number[];
+    /** Top-k weights */
+    topKWeights: number[];
+}
+/**
+ * Attention performance metrics (subset for memory controllers)
+ */
+export interface AttentionPerformanceMetrics {
+    /** Mechanism used */
+    mechanism: AttentionMechanism;
+    /** Latency in milliseconds */
+    latencyMs: number;
+    /** Memory used in bytes */
+    memoryUsed: number;
+    /** Number of keys processed */
+    numKeys: number;
+    /** Backend used */
+    backend: AttentionBackend;
+}
+/**
+ * Feature flag utility type for controllers
+ */
+export interface AttentionFeatureFlags {
+    hyperbolic: boolean;
+    flash: boolean;
+    graphrope: boolean;
+    moe: boolean;
+    dualspace: boolean;
+    linear: boolean;
+}
+export type { AttentionConfig, AttentionOptions, AttentionResult, AttentionMetrics, } from '../controllers/AttentionService.js';
+/**
+ * Type guard for attention-enhanced causal edge
+ */
+export declare function isCausalEdgeWithAttention(edge: any): edge is CausalEdgeWithAttention;
+/**
+ * Type guard for attention-enhanced pattern
+ */
+export declare function isPatternWithAttention(pattern: any): pattern is ReasoningPatternWithAttention;
+/**
+ * Type guard for attention-enhanced explanation
+ */
+export declare function isExplanationWithAttention(explanation: any): explanation is ExplanationChainWithAttention;
+//# sourceMappingURL=attention.d.ts.map

package/dist/src/types/attention.d.ts.map

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

package/dist/src/types/attention.js

@@ -0,0 +1,43 @@
+/**
+ * Attention Type Definitions for AgentDB v2
+ *
+ * Shared types for @ruvector/attention integration across memory controllers.
+ * These types are used by AttentionService and all enhanced controllers.
+ *
+ * @module types/attention
+ * @see controllers/AttentionService
+ * @see docs/integration/ARCHITECTURE.md
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for attention-enhanced causal edge
+ */
+export function isCausalEdgeWithAttention(edge) {
+    return (typeof edge === 'object' &&
+        edge !== null &&
+        'fromMemoryId' in edge &&
+        'toMemoryId' in edge &&
+        ('hyperbolicScore' in edge || 'attentionWeight' in edge));
+}
+/**
+ * Type guard for attention-enhanced pattern
+ */
+export function isPatternWithAttention(pattern) {
+    return (typeof pattern === 'object' &&
+        pattern !== null &&
+        'taskType' in pattern &&
+        ('flashScore' in pattern || 'expertId' in pattern));
+}
+/**
+ * Type guard for attention-enhanced explanation
+ */
+export function isExplanationWithAttention(explanation) {
+    return (typeof explanation === 'object' &&
+        explanation !== null &&
+        'nodes' in explanation &&
+        'edges' in explanation &&
+        ('hopDistances' in explanation || 'graphRoPEScores' in explanation));
+}
+//# sourceMappingURL=attention.js.map

package/dist/src/types/attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.js","sourceRoot":"","sources":["../../../src/types/attention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgVH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,IAAS;IAET,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,cAAc,IAAI,IAAI;QACtB,YAAY,IAAI,IAAI;QACpB,CAAC,iBAAiB,IAAI,IAAI,IAAI,iBAAiB,IAAI,IAAI,CAAC,CACzD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAY;IAEZ,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,UAAU,IAAI,OAAO;QACrB,CAAC,YAAY,IAAI,OAAO,IAAI,UAAU,IAAI,OAAO,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,WAAgB;IAEhB,OAAO,CACL,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,KAAK,IAAI;QACpB,OAAO,IAAI,WAAW;QACtB,OAAO,IAAI,WAAW;QACtB,CAAC,cAAc,IAAI,WAAW,IAAI,iBAAiB,IAAI,WAAW,CAAC,CACpE,CAAC;AACJ,CAAC"}