holosphere 1.1.19 → 2.0.0-alpha0

package/src/ai/embeddings.js

@@ -0,0 +1,279 @@
+/**
+ * Embeddings - Vector embedding generation and semantic search
+ */
+
+/**
+ * Embeddings class for vector operations
+ */
+export class Embeddings {
+  /**
+   * @param {Object} openai - OpenAI client instance
+   * @param {Object} holosphere - HoloSphere instance for storage
+   */
+  constructor(openai, holosphere = null) {
+    this.openai = openai;
+    this.holosphere = holosphere;
+    this.model = 'text-embedding-3-small';
+    this.dimensions = 1536;
+  }
+
+  /**
+   * Set HoloSphere instance for storage
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  setHoloSphere(holosphere) {
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Generate embedding for text
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>} Embedding vector
+   */
+  async embed(text) {
+    try {
+      const response = await this.openai.embeddings.create({
+        model: this.model,
+        input: text,
+      });
+
+      return response.data[0].embedding;
+    } catch (error) {
+      throw new Error(`Embedding generation failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Generate embeddings for multiple texts
+   * @param {string[]} texts - Array of texts
+   * @returns {Promise<number[][]>} Array of embeddings
+   */
+  async embedBatch(texts) {
+    try {
+      const response = await this.openai.embeddings.create({
+        model: this.model,
+        input: texts,
+      });
+
+      return response.data.map(d => d.embedding);
+    } catch (error) {
+      throw new Error(`Batch embedding failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   * @param {number[]} vec1 - First vector
+   * @param {number[]} vec2 - Second vector
+   * @returns {number} Similarity score (0-1)
+   */
+  cosineSimilarity(vec1, vec2) {
+    if (vec1.length !== vec2.length) {
+      throw new Error('Vectors must have same length');
+    }
+
+    let dotProduct = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+
+    for (let i = 0; i < vec1.length; i++) {
+      dotProduct += vec1[i] * vec2[i];
+      norm1 += vec1[i] * vec1[i];
+      norm2 += vec2[i] * vec2[i];
+    }
+
+    return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
+  }
+
+  /**
+   * Store item with embedding in HoloSphere
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens name
+   * @param {Object} item - Item to store
+   * @param {string} textField - Field to embed (default: 'content' or 'text')
+   * @returns {Promise<Object>} Stored item with embedding
+   */
+  async storeWithEmbedding(holon, lens, item, textField = null) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required for storage');
+    }
+
+    // Determine text to embed
+    const text = textField
+      ? item[textField]
+      : item.content || item.text || item.description || JSON.stringify(item);
+
+    if (!text) {
+      throw new Error('No text found to embed');
+    }
+
+    // Generate embedding
+    const embedding = await this.embed(text);
+
+    // Store with embedding
+    const itemWithEmbedding = {
+      ...item,
+      _embedding: embedding,
+      _embeddedField: textField || 'auto',
+      _embeddedAt: Date.now(),
+    };
+
+    await this.holosphere.put(holon, lens, itemWithEmbedding);
+
+    return itemWithEmbedding;
+  }
+
+  /**
+   * Semantic search within a holon/lens
+   * @param {string} query - Search query
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens name
+   * @param {Object} options - Search options
+   * @returns {Promise<Array<{item: Object, similarity: number}>>} Ranked results
+   */
+  async semanticSearch(query, holon, lens, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required for search');
+    }
+
+    const { limit = 10, threshold = 0.5 } = options;
+
+    // Get query embedding
+    const queryEmbedding = await this.embed(query);
+
+    // Get all items from holon/lens
+    const items = await this.holosphere.getAll(holon, lens);
+
+    // Calculate similarities
+    const results = [];
+
+    for (const item of items) {
+      if (item._embedding) {
+        const similarity = this.cosineSimilarity(queryEmbedding, item._embedding);
+
+        if (similarity >= threshold) {
+          results.push({
+            item: { ...item, _embedding: undefined }, // Don't return embedding
+            similarity,
+          });
+        }
+      }
+    }
+
+    // Sort by similarity and limit
+    results.sort((a, b) => b.similarity - a.similarity);
+
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Find similar items to a given item
+   * @param {Object} item - Item to find similar items for
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens name
+   * @param {Object} options - Search options
+   * @returns {Promise<Array>} Similar items
+   */
+  async findSimilar(item, holon, lens, options = {}) {
+    const text = item.content || item.text || item.description || JSON.stringify(item);
+    return this.semanticSearch(text, holon, lens, options);
+  }
+
+  /**
+   * Cluster items by semantic similarity
+   * @param {Object[]} items - Items to cluster
+   * @param {number} numClusters - Approximate number of clusters
+   * @returns {Promise<Object[][]>} Clustered items
+   */
+  async cluster(items, numClusters = 5) {
+    // Get embeddings for items that don't have them
+    const itemsWithEmbeddings = await Promise.all(
+      items.map(async (item) => {
+        if (item._embedding) {
+          return item;
+        }
+        const text = item.content || item.text || item.description || JSON.stringify(item);
+        const embedding = await this.embed(text);
+        return { ...item, _embedding: embedding };
+      })
+    );
+
+    // Simple k-means clustering
+    const clusters = this._kMeans(itemsWithEmbeddings, numClusters);
+
+    // Return clusters without embeddings
+    return clusters.map(cluster =>
+      cluster.map(item => ({ ...item, _embedding: undefined }))
+    );
+  }
+
+  /**
+   * Simple k-means clustering
+   * @private
+   */
+  _kMeans(items, k, maxIterations = 100) {
+    if (items.length <= k) {
+      return items.map(item => [item]);
+    }
+
+    // Initialize centroids randomly
+    const shuffled = [...items].sort(() => Math.random() - 0.5);
+    let centroids = shuffled.slice(0, k).map(item => [...item._embedding]);
+
+    let assignments = new Array(items.length);
+
+    for (let iter = 0; iter < maxIterations; iter++) {
+      // Assign items to nearest centroid
+      const newAssignments = items.map((item) => {
+        let minDist = Infinity;
+        let nearest = 0;
+
+        for (let c = 0; c < centroids.length; c++) {
+          const dist = 1 - this.cosineSimilarity(item._embedding, centroids[c]);
+          if (dist < minDist) {
+            minDist = dist;
+            nearest = c;
+          }
+        }
+
+        return nearest;
+      });
+
+      // Check for convergence
+      if (JSON.stringify(newAssignments) === JSON.stringify(assignments)) {
+        break;
+      }
+
+      assignments = newAssignments;
+
+      // Update centroids
+      for (let c = 0; c < k; c++) {
+        const clusterItems = items.filter((_, i) => assignments[i] === c);
+
+        if (clusterItems.length > 0) {
+          centroids[c] = new Array(this.dimensions).fill(0);
+
+          for (const item of clusterItems) {
+            for (let d = 0; d < this.dimensions; d++) {
+              centroids[c][d] += item._embedding[d];
+            }
+          }
+
+          for (let d = 0; d < this.dimensions; d++) {
+            centroids[c][d] /= clusterItems.length;
+          }
+        }
+      }
+    }
+
+    // Group items by cluster
+    const clusters = Array.from({ length: k }, () => []);
+    items.forEach((item, i) => {
+      clusters[assignments[i]].push(item);
+    });
+
+    return clusters.filter(c => c.length > 0);
+  }
+}
+
+export default Embeddings;

package/src/ai/federation-ai.js

@@ -0,0 +1,324 @@
+/**
+ * Federation Advisor - AI-powered federation suggestions and analysis
+ */
+
+/**
+ * Federation Advisor class
+ */
+export class FederationAdvisor {
+  /**
+   * @param {LLMService} llmService - LLM service instance
+   * @param {Object} holosphere - HoloSphere instance
+   * @param {Object} embeddings - Embeddings instance (optional)
+   */
+  constructor(llmService, holosphere = null, embeddings = null) {
+    this.llm = llmService;
+    this.holosphere = holosphere;
+    this.embeddings = embeddings;
+  }
+
+  /**
+   * Set HoloSphere instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  setHoloSphere(holosphere) {
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Set Embeddings instance
+   * @param {Object} embeddings - Embeddings instance
+   */
+  setEmbeddings(embeddings) {
+    this.embeddings = embeddings;
+  }
+
+  /**
+   * Suggest federations based on content similarity
+   * @param {string} holon - Holon to find federation partners for
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Suggested federations
+   */
+  async suggestFederations(holon, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const { candidateHolons = [], lens = 'default', maxSuggestions = 5 } = options;
+
+    // Get data from source holon
+    const sourceData = await this.holosphere.getAll(holon, lens);
+
+    if (sourceData.length === 0) {
+      return { holon, suggestions: [], message: 'No data in source holon' };
+    }
+
+    // If we have candidate holons, compare with each
+    const comparisons = [];
+
+    for (const candidate of candidateHolons.slice(0, 10)) {
+      if (candidate === holon) continue;
+
+      try {
+        const candidateData = await this.holosphere.getAll(candidate, lens);
+        if (candidateData.length > 0) {
+          comparisons.push({
+            holon: candidate,
+            dataCount: candidateData.length,
+            dataSample: candidateData.slice(0, 10),
+          });
+        }
+      } catch {
+        // Skip unavailable holons
+      }
+    }
+
+    if (comparisons.length === 0) {
+      return { holon, suggestions: [], message: 'No candidate holons with data' };
+    }
+
+    const systemPrompt = `You are a federation advisor. Analyze which regions would benefit from federating (sharing data) with the source region.
+
+Source region: ${holon}
+Source data count: ${sourceData.length}
+
+Consider:
+1. Content similarity - similar topics benefit from shared visibility
+2. Complementary content - different but related content enables collaboration
+3. Geographic proximity relevance
+4. Potential for knowledge sharing
+
+Return JSON array:
+[
+  {
+    "holon": "id",
+    "score": 0.0-1.0,
+    "reasoning": "why federate",
+    "benefits": ["benefit1"],
+    "type": "similarity|complementary|geographic"
+  }
+]
+
+Order by score descending, max ${maxSuggestions} suggestions.`;
+
+    const userMessage = `Source data sample:
+${JSON.stringify(sourceData.slice(0, 15), null, 2)}
+
+Candidate regions:
+${JSON.stringify(comparisons, null, 2)}`;
+
+    const suggestions = await this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.3 });
+
+    return {
+      holon,
+      lens,
+      suggestions: suggestions.slice(0, maxSuggestions),
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Analyze federation health
+   * @param {string} holon - Holon to analyze
+   * @returns {Promise<Object>} Federation health analysis
+   */
+  async analyzeFederationHealth(holon) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    // Get federation info
+    const federation = await this.holosphere.getFederation(holon);
+
+    if (!federation || !federation.federation || federation.federation.length === 0) {
+      return {
+        holon,
+        health: 'none',
+        message: 'No federations configured',
+        score: 0,
+      };
+    }
+
+    // Analyze each federation
+    const federationAnalysis = [];
+
+    for (const fedHolon of federation.federation.slice(0, 5)) {
+      try {
+        const fedData = await this.holosphere.getAll(fedHolon, 'default');
+        federationAnalysis.push({
+          holon: fedHolon,
+          active: fedData.length > 0,
+          dataCount: fedData.length,
+        });
+      } catch {
+        federationAnalysis.push({
+          holon: fedHolon,
+          active: false,
+          error: true,
+        });
+      }
+    }
+
+    const systemPrompt = `You are a federation health analyst. Assess the health of this holon's federation relationships.
+
+Source holon: ${holon}
+Federation partners: ${federation.federation.length}
+Active federations: ${federationAnalysis.filter(f => f.active).length}
+
+Federation details:
+${JSON.stringify(federationAnalysis, null, 2)}
+
+Analyze:
+1. Overall federation health
+2. Active vs inactive relationships
+3. Balance of the federation network
+4. Recommendations
+
+Return JSON:
+{
+  "health_score": 0.0-1.0,
+  "status": "healthy|degraded|unhealthy",
+  "active_count": n,
+  "inactive_count": n,
+  "issues": ["issue1"],
+  "recommendations": ["rec1"],
+  "summary": "text"
+}`;
+
+    const analysis = await this.llm.getJSON(systemPrompt, '', { temperature: 0.3 });
+
+    return {
+      holon,
+      federation: federation.federation,
+      analysis,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Suggest federation optimizations
+   * @param {string} holon - Holon to optimize
+   * @returns {Promise<Object>} Optimization suggestions
+   */
+  async optimizeFederation(holon) {
+    const health = await this.analyzeFederationHealth(holon);
+
+    if (health.health === 'none') {
+      return { holon, suggestions: ['Consider establishing initial federations'] };
+    }
+
+    const systemPrompt = `Based on federation health analysis, suggest optimizations.
+
+Health analysis:
+${JSON.stringify(health.analysis, null, 2)}
+
+Suggest:
+1. Federations to strengthen
+2. Federations to reconsider
+3. New potential federations
+4. Data flow improvements
+
+Return JSON:
+{
+  "strengthen": ["holon_id"],
+  "reconsider": ["holon_id"],
+  "new_potential": ["description"],
+  "improvements": ["improvement1"],
+  "priority": "high|medium|low"
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.4 });
+  }
+
+  /**
+   * Analyze data flow in federation network
+   * @param {string} holon - Starting holon
+   * @returns {Promise<Object>} Data flow analysis
+   */
+  async analyzeDataFlow(holon) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const federation = await this.holosphere.getFederation(holon);
+
+    if (!federation) {
+      return { holon, message: 'No federation configured' };
+    }
+
+    const systemPrompt = `Analyze the data flow patterns in a federation network.
+
+Source holon: ${holon}
+Federated with: ${federation.federation?.join(', ') || 'none'}
+Notifies: ${federation.notify?.join(', ') || 'none'}
+
+Consider:
+1. Bidirectional vs unidirectional relationships
+2. Hub patterns (many connections)
+3. Data propagation paths
+4. Potential bottlenecks
+
+Return JSON:
+{
+  "flow_type": "bidirectional|unidirectional|mixed",
+  "topology": "hub|mesh|chain|star",
+  "propagation_depth": n,
+  "bottlenecks": ["desc"],
+  "recommendations": ["rec1"]
+}`;
+
+    return this.llm.getJSON(systemPrompt, JSON.stringify(federation, null, 2), { temperature: 0.3 });
+  }
+
+  /**
+   * Find federation bridges - holons that connect disparate networks
+   * @param {string[]} holons - List of holons to analyze
+   * @returns {Promise<Object>} Bridge analysis
+   */
+  async findBridges(holons) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const network = [];
+
+    for (const holon of holons.slice(0, 20)) {
+      try {
+        const fed = await this.holosphere.getFederation(holon);
+        if (fed) {
+          network.push({
+            holon,
+            federations: fed.federation || [],
+            notifies: fed.notify || [],
+          });
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    const systemPrompt = `Analyze a federation network to identify bridge holons (connectors between clusters).
+
+Network:
+${JSON.stringify(network, null, 2)}
+
+Identify:
+1. Bridge holons that connect clusters
+2. Isolated holons
+3. Central hubs
+4. Network clusters
+
+Return JSON:
+{
+  "bridges": [{"holon": "id", "connects": ["cluster1", "cluster2"]}],
+  "isolated": ["holon_id"],
+  "hubs": [{"holon": "id", "connections": n}],
+  "clusters": [["holon1", "holon2"]],
+  "network_health": 0.0-1.0
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.3 });
+  }
+}
+
+export default FederationAdvisor;