holosphere 1.1.20 → 2.0.0-alpha0

package/src/ai/nl-query.js

@@ -0,0 +1,223 @@
+/**
+ * Natural Language Query - Query HoloSphere data using natural language
+ */
+
+/**
+ * NL Query class for natural language to structured query conversion
+ */
+export class NLQuery {
+  /**
+   * @param {LLMService} llmService - LLM service instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  constructor(llmService, holosphere = null) {
+    this.llm = llmService;
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Set HoloSphere instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  setHoloSphere(holosphere) {
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Parse natural language query into structured format
+   * @param {string} query - Natural language query
+   * @param {Object} context - Context (available holons, lenses, etc.)
+   * @returns {Promise<Object>} Structured query
+   */
+  async parse(query, context = {}) {
+    const systemPrompt = `You are a query parser. Convert natural language queries into structured JSON filters for a geospatial database.
+
+Available holons: ${context.holons?.join(', ') || 'any'}
+Available lenses: ${context.lenses?.join(', ') || 'any'}
+
+Return a JSON object with:
+{
+  "holon": "holon_id or null",
+  "lens": "lens_name or null",
+  "filters": {
+    "field_name": { "op": "eq|ne|gt|gte|lt|lte|contains|in", "value": value }
+  },
+  "sort": { "field": "field_name", "order": "asc|desc" } or null,
+  "limit": number or null,
+  "spatial": { "near": "location_name", "radius": "distance" } or null,
+  "temporal": { "after": "date", "before": "date" } or null
+}
+
+Examples:
+- "show projects near Rome" -> { "lens": "projects", "spatial": { "near": "Rome" } }
+- "find quests with more than 10 participants" -> { "lens": "quests", "filters": { "participants": { "op": "gt", "value": 10 } } }`;
+
+    const result = await this.llm.getJSON(systemPrompt, query, { temperature: 0.2 });
+    return result;
+  }
+
+  /**
+   * Execute natural language query
+   * @param {string} query - Natural language query
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} Query results
+   */
+  async execute(query, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required for query execution');
+    }
+
+    // Parse the query
+    const parsed = await this.parse(query, options.context);
+
+    // Get data from HoloSphere
+    let results = [];
+
+    if (parsed.holon && parsed.lens) {
+      results = await this.holosphere.getAll(parsed.holon, parsed.lens);
+    } else if (parsed.lens) {
+      // Search across all holons for this lens (would need holon list)
+      if (options.holons) {
+        for (const holon of options.holons) {
+          const data = await this.holosphere.getAll(holon, parsed.lens);
+          results.push(...data.map(item => ({ ...item, _holon: holon })));
+        }
+      }
+    }
+
+    // Apply filters
+    if (parsed.filters) {
+      results = this._applyFilters(results, parsed.filters);
+    }
+
+    // Apply sorting
+    if (parsed.sort) {
+      results = this._applySort(results, parsed.sort);
+    }
+
+    // Apply limit
+    if (parsed.limit) {
+      results = results.slice(0, parsed.limit);
+    }
+
+    return {
+      query,
+      parsed,
+      results,
+      count: results.length,
+    };
+  }
+
+  /**
+   * Apply filters to results
+   * @private
+   */
+  _applyFilters(results, filters) {
+    return results.filter(item => {
+      for (const [field, condition] of Object.entries(filters)) {
+        const value = this._getNestedValue(item, field);
+
+        if (!this._matchCondition(value, condition)) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Get nested value from object
+   * @private
+   */
+  _getNestedValue(obj, path) {
+    return path.split('.').reduce((acc, key) => acc?.[key], obj);
+  }
+
+  /**
+   * Check if value matches condition
+   * @private
+   */
+  _matchCondition(value, condition) {
+    const { op, value: targetValue } = condition;
+
+    switch (op) {
+      case 'eq':
+        return value === targetValue;
+      case 'ne':
+        return value !== targetValue;
+      case 'gt':
+        return value > targetValue;
+      case 'gte':
+        return value >= targetValue;
+      case 'lt':
+        return value < targetValue;
+      case 'lte':
+        return value <= targetValue;
+      case 'contains':
+        return String(value).toLowerCase().includes(String(targetValue).toLowerCase());
+      case 'in':
+        return Array.isArray(targetValue) && targetValue.includes(value);
+      default:
+        return true;
+    }
+  }
+
+  /**
+   * Apply sorting to results
+   * @private
+   */
+  _applySort(results, sort) {
+    const { field, order } = sort;
+    const multiplier = order === 'desc' ? -1 : 1;
+
+    return [...results].sort((a, b) => {
+      const aVal = this._getNestedValue(a, field);
+      const bVal = this._getNestedValue(b, field);
+
+      if (aVal < bVal) return -1 * multiplier;
+      if (aVal > bVal) return 1 * multiplier;
+      return 0;
+    });
+  }
+
+  /**
+   * Suggest queries based on context
+   * @param {Object} context - Current context
+   * @returns {Promise<string[]>} Suggested queries
+   */
+  async suggest(context = {}) {
+    const systemPrompt = `Suggest 5 useful natural language queries for exploring geospatial data.
+
+Available holons: ${context.holons?.join(', ') || 'geographic areas'}
+Available lenses: ${context.lenses?.join(', ') || 'projects, quests, events, resources'}
+
+Return ONLY a JSON array of query strings.`;
+
+    return this.llm.getJSON(systemPrompt, 'Generate query suggestions', { temperature: 0.7 });
+  }
+
+  /**
+   * Explain query results in natural language
+   * @param {string} query - Original query
+   * @param {Array} results - Query results
+   * @returns {Promise<string>} Natural language explanation
+   */
+  async explain(query, results) {
+    const systemPrompt = `You are a helpful data analyst. Explain the results of a query in natural language.
+
+Original query: ${query}
+Number of results: ${results.length}
+
+Provide a brief, helpful summary of what was found.`;
+
+    const sampleResults = results.slice(0, 5);
+
+    return this.llm.sendMessage(
+      systemPrompt,
+      `Results sample: ${JSON.stringify(sampleResults, null, 2)}`,
+      { temperature: 0.5 }
+    );
+  }
+}
+
+export default NLQuery;

package/src/ai/relationships.js

@@ -0,0 +1,353 @@
+/**
+ * Relationship Discovery - Find hidden connections across data
+ */
+
+/**
+ * Relationship Discovery class
+ */
+export class RelationshipDiscovery {
+  /**
+   * @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;
+  }
+
+  /**
+   * Discover relationships in holon data
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens to analyze (optional)
+   * @returns {Promise<Object>} Discovered relationships
+   */
+  async discoverRelationships(holon, lens = null) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    // Get data from holon
+    let data = [];
+    const lenses = lens ? [lens] : ['projects', 'quests', 'events', 'resources', 'default'];
+
+    for (const l of lenses) {
+      try {
+        const lensData = await this.holosphere.getAll(holon, l);
+        data.push(...lensData.map(item => ({ ...item, _lens: l })));
+      } catch {
+        // Skip unavailable lenses
+      }
+    }
+
+    if (data.length < 2) {
+      return { holon, relationships: [], message: 'Not enough data for relationship discovery' };
+    }
+
+    const systemPrompt = `You are a relationship discovery expert. Find hidden connections between items in this dataset.
+
+Region: ${holon}
+Items: ${data.length}
+
+Look for:
+1. Thematic connections (shared topics, goals)
+2. Entity connections (shared people, organizations)
+3. Temporal connections (same timeframes)
+4. Causal connections (one enables/requires another)
+5. Geographic connections (same sub-regions)
+
+Return JSON:
+{
+  "relationships": [
+    {
+      "item1": {"id": "id1", "title": "title"},
+      "item2": {"id": "id2", "title": "title"},
+      "type": "thematic|entity|temporal|causal|geographic",
+      "strength": 0.0-1.0,
+      "description": "relationship description"
+    }
+  ],
+  "clusters": [
+    {
+      "theme": "cluster theme",
+      "items": ["id1", "id2"]
+    }
+  ],
+  "key_entities": ["entity1", "entity2"],
+  "summary": "overview of relationship network"
+}`;
+
+    const relationships = await this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(data.slice(0, 40), null, 2),
+      { temperature: 0.3 }
+    );
+
+    return {
+      holon,
+      lens,
+      itemCount: data.length,
+      relationships,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Find items similar to a given item
+   * @param {Object} item - Item to find similar items for
+   * @param {string} holon - Holon to search in (optional)
+   * @param {string} lens - Lens to search in (optional)
+   * @param {Object} options - Search options
+   * @returns {Promise<Array>} Similar items
+   */
+  async findSimilar(item, holon = null, lens = null, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const { limit = 10, threshold = 0.5, useEmbeddings = true } = options;
+
+    // If embeddings available, use semantic search
+    if (useEmbeddings && this.embeddings && holon && lens) {
+      return this.embeddings.findSimilar(item, holon, lens, { limit, threshold });
+    }
+
+    // Fall back to LLM-based similarity
+    if (!holon) {
+      throw new Error('Holon required for LLM-based similarity');
+    }
+
+    const searchLenses = lens ? [lens] : ['projects', 'quests', 'events', 'resources', 'default'];
+    let candidates = [];
+
+    for (const l of searchLenses) {
+      try {
+        const data = await this.holosphere.getAll(holon, l);
+        candidates.push(...data.map(d => ({ ...d, _lens: l })));
+      } catch {
+        // Skip
+      }
+    }
+
+    if (candidates.length === 0) {
+      return [];
+    }
+
+    const systemPrompt = `Find items most similar to the reference item.
+
+Reference item:
+${JSON.stringify(item, null, 2)}
+
+Consider:
+1. Topic/theme similarity
+2. Goal alignment
+3. Participant overlap
+4. Resource requirements
+5. Timeline compatibility
+
+Return JSON array of similar items with similarity scores:
+[
+  {
+    "item": {item object},
+    "similarity": 0.0-1.0,
+    "reasons": ["reason1"]
+  }
+]
+
+Order by similarity descending. Max ${limit} items with similarity >= ${threshold}.`;
+
+    const results = await this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(candidates.slice(0, 50), null, 2),
+      { temperature: 0.2 }
+    );
+
+    return results.slice(0, limit).filter(r => r.similarity >= threshold);
+  }
+
+  /**
+   * Build relationship graph
+   * @param {string} holon - Holon
+   * @param {string} lens - Lens
+   * @returns {Promise<Object>} Graph structure
+   */
+  async buildGraph(holon, lens) {
+    const discovered = await this.discoverRelationships(holon, lens);
+
+    const nodes = new Map();
+    const edges = [];
+
+    // Build nodes from relationships
+    for (const rel of discovered.relationships?.relationships || []) {
+      if (!nodes.has(rel.item1.id)) {
+        nodes.set(rel.item1.id, { id: rel.item1.id, label: rel.item1.title });
+      }
+      if (!nodes.has(rel.item2.id)) {
+        nodes.set(rel.item2.id, { id: rel.item2.id, label: rel.item2.title });
+      }
+
+      edges.push({
+        source: rel.item1.id,
+        target: rel.item2.id,
+        type: rel.type,
+        weight: rel.strength,
+      });
+    }
+
+    return {
+      nodes: Array.from(nodes.values()),
+      edges,
+      clusters: discovered.relationships?.clusters || [],
+    };
+  }
+
+  /**
+   * Find cross-holon relationships
+   * @param {string[]} holons - Holons to analyze
+   * @param {string} lens - Lens
+   * @returns {Promise<Object>} Cross-holon relationships
+   */
+  async findCrossHolonRelationships(holons, lens) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const allData = {};
+
+    for (const holon of holons.slice(0, 5)) {
+      try {
+        const data = await this.holosphere.getAll(holon, lens);
+        if (data.length > 0) {
+          allData[holon] = data.slice(0, 15);
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    if (Object.keys(allData).length < 2) {
+      return { message: 'Need at least 2 holons with data' };
+    }
+
+    const systemPrompt = `Find relationships between items across different geographic regions.
+
+Regions and their data:
+${JSON.stringify(allData, null, 2)}
+
+Identify:
+1. Cross-region collaborations
+2. Shared themes across regions
+3. Potential synergies
+4. Knowledge transfer opportunities
+
+Return JSON:
+{
+  "cross_relationships": [
+    {
+      "holon1": "id",
+      "item1": "item_id",
+      "holon2": "id",
+      "item2": "item_id",
+      "type": "type",
+      "potential": "collaboration|knowledge_share|synergy"
+    }
+  ],
+  "shared_themes": [{"theme": "theme", "holons": ["id1", "id2"]}],
+  "opportunities": ["opp1"]
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.4 });
+  }
+
+  /**
+   * Suggest connections for an item
+   * @param {Object} item - Item to find connections for
+   * @param {string} holon - Holon
+   * @param {string} lens - Lens
+   * @returns {Promise<Object>} Suggested connections
+   */
+  async suggestConnections(item, holon, lens) {
+    const similar = await this.findSimilar(item, holon, lens, { limit: 10 });
+
+    const systemPrompt = `Based on similar items found, suggest specific actions to create connections.
+
+Reference item:
+${JSON.stringify(item, null, 2)}
+
+Similar items found:
+${JSON.stringify(similar, null, 2)}
+
+Suggest:
+1. Collaboration opportunities
+2. Resource sharing possibilities
+3. Joint initiatives
+4. Knowledge exchange
+
+Return JSON:
+{
+  "collaborations": [{"with": "item_id", "action": "suggested action"}],
+  "resource_sharing": [{"items": ["id1", "id2"], "resource": "what to share"}],
+  "initiatives": [{"description": "joint initiative", "participants": ["id1"]}],
+  "knowledge_exchange": [{"from": "id", "to": "id", "topic": "topic"}]
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.5 });
+  }
+
+  /**
+   * Detect relationship patterns
+   * @param {string} holon - Holon
+   * @param {string} lens - Lens
+   * @returns {Promise<Object>} Detected patterns
+   */
+  async detectPatterns(holon, lens) {
+    const relationships = await this.discoverRelationships(holon, lens);
+
+    const systemPrompt = `Analyze relationships and detect higher-level patterns.
+
+Relationships:
+${JSON.stringify(relationships.relationships, null, 2)}
+
+Detect:
+1. Hub-spoke patterns (central connectors)
+2. Cluster patterns (tight groups)
+3. Bridge patterns (connecting different groups)
+4. Chain patterns (sequential relationships)
+5. Cyclical patterns (mutual dependencies)
+
+Return JSON:
+{
+  "patterns": [
+    {
+      "type": "hub|cluster|bridge|chain|cycle",
+      "description": "pattern description",
+      "items": ["id1", "id2"],
+      "significance": "why this matters"
+    }
+  ],
+  "network_structure": "description of overall structure",
+  "recommendations": ["rec1"]
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.3 });
+  }
+}
+
+export default RelationshipDiscovery;