holosphere 1.1.20 → 2.0.0-alpha0

package/src/ai/index.js

@@ -0,0 +1,112 @@
+/**
+ * HoloSphere AI Module
+ * Comprehensive AI functionality using OpenAI chat completions
+ */
+
+// Import all modules for local use and re-export
+import { LLMService, default as LLM } from './llm-service.js';
+import { SchemaExtractor } from './schema-extractor.js';
+import { JSONOps } from './json-ops.js';
+import { Embeddings } from './embeddings.js';
+import { Council } from './council.js';
+import { TTS, VOICES, MODELS } from './tts.js';
+import { NLQuery } from './nl-query.js';
+import { Classifier } from './classifier.js';
+import { SpatialAnalysis } from './spatial.js';
+import { SmartAggregation } from './aggregation.js';
+import { FederationAdvisor } from './federation-ai.js';
+import { RelationshipDiscovery } from './relationships.js';
+import { TaskBreakdown } from './breakdown.js';
+import { H3AI } from './h3-ai.js';
+
+// Re-export all modules
+export {
+  LLMService,
+  LLM,
+  SchemaExtractor,
+  JSONOps,
+  Embeddings,
+  Council,
+  TTS,
+  VOICES,
+  MODELS,
+  NLQuery,
+  Classifier,
+  SpatialAnalysis,
+  SmartAggregation,
+  FederationAdvisor,
+  RelationshipDiscovery,
+  TaskBreakdown,
+  H3AI,
+};
+
+/**
+ * Create all AI services with shared LLM instance
+ * @param {string} apiKey - OpenAI API key
+ * @param {Object} holosphere - HoloSphere instance (optional)
+ * @param {Object} options - Configuration options
+ * @param {Object} openaiClient - Optional pre-created OpenAI client
+ * @returns {Object} AI services
+ */
+export function createAIServices(apiKey, holosphere = null, options = {}, openaiClient = null) {
+  // Create shared LLM service
+  const llm = new LLMService(apiKey, options.llm);
+
+  // Use provided OpenAI client or create a placeholder
+  // Note: For embeddings/TTS, caller should provide openaiClient or use individual services
+  const openai = openaiClient;
+
+  // Create all services
+  const embeddings = new Embeddings(openai, holosphere);
+  const schemaExtractor = new SchemaExtractor(llm);
+  const jsonOps = new JSONOps(llm);
+  const council = new Council(llm);
+  const tts = new TTS(openai);
+  const nlQuery = new NLQuery(llm, holosphere);
+  const classifier = new Classifier(llm, holosphere);
+  const spatial = new SpatialAnalysis(llm, holosphere);
+  const aggregation = new SmartAggregation(llm, holosphere);
+  const federationAdvisor = new FederationAdvisor(llm, holosphere, embeddings);
+  const relationships = new RelationshipDiscovery(llm, holosphere, embeddings);
+  const taskBreakdown = new TaskBreakdown(llm, holosphere);
+  const h3ai = new H3AI(llm, holosphere);
+
+  return {
+    llm,
+    openai,
+    embeddings,
+    schemaExtractor,
+    jsonOps,
+    council,
+    tts,
+    nlQuery,
+    classifier,
+    spatial,
+    aggregation,
+    federationAdvisor,
+    relationships,
+    taskBreakdown,
+    h3ai,
+  };
+}
+
+// Default export
+export default {
+  LLMService,
+  SchemaExtractor,
+  JSONOps,
+  Embeddings,
+  Council,
+  TTS,
+  VOICES,
+  MODELS,
+  NLQuery,
+  Classifier,
+  SpatialAnalysis,
+  SmartAggregation,
+  FederationAdvisor,
+  RelationshipDiscovery,
+  TaskBreakdown,
+  H3AI,
+  createAIServices,
+};

package/src/ai/json-ops.js

@@ -0,0 +1,225 @@
+/**
+ * Fuzzy JSON Operations - AI-assisted semantic operations on JSON structures
+ */
+
+/**
+ * JSON Operations class for semantic JSON manipulation
+ */
+export class JSONOps {
+  /**
+   * @param {LLMService} llmService - LLM service instance
+   */
+  constructor(llmService) {
+    this.llm = llmService;
+  }
+
+  /**
+   * Semantically merge two JSON objects
+   * @param {Object} obj1 - First object
+   * @param {Object} obj2 - Second object
+   * @param {Object} options - Merge options
+   * @returns {Promise<Object>} Merged object
+   */
+  async add(obj1, obj2, options = {}) {
+    const systemPrompt = `You are a JSON merge expert. Semantically merge these two JSON objects.
+
+Rules:
+1. Combine information from both objects intelligently
+2. For conflicting values, prefer the more complete/detailed one${options.preferSecond ? ', or prefer the second object' : ''}
+3. Merge arrays by combining items, removing duplicates by semantic similarity
+4. Preserve all unique information from both objects
+5. Return ONLY valid JSON`;
+
+    const userMessage = `Object 1:
+${JSON.stringify(obj1, null, 2)}
+
+Object 2:
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Remove concepts from obj1 based on obj2
+   * @param {Object} obj1 - Base object
+   * @param {Object} obj2 - Object containing concepts to remove
+   * @returns {Promise<Object>} Result with concepts removed
+   */
+  async subtract(obj1, obj2) {
+    const systemPrompt = `You are a JSON manipulation expert. Remove concepts from the first object that are semantically present in the second object.
+
+Rules:
+1. Remove fields from obj1 that have semantic equivalents in obj2
+2. For arrays, remove items that are semantically similar to items in obj2
+3. Preserve fields/items in obj1 that have no semantic match in obj2
+4. Remove nested content that matches semantically
+5. Return ONLY valid JSON`;
+
+    const userMessage = `Base object (to modify):
+${JSON.stringify(obj1, null, 2)}
+
+Concepts to remove:
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Combine objects with semantic deduplication
+   * @param {Object} obj1 - First object
+   * @param {Object} obj2 - Second object
+   * @returns {Promise<Object>} Union of objects
+   */
+  async union(obj1, obj2) {
+    const systemPrompt = `You are a JSON merge expert. Create a semantic union of these two JSON objects.
+
+Rules:
+1. Include all unique information from both objects
+2. For duplicate concepts, keep only one (the more complete version)
+3. Deduplicate array items by semantic similarity, not just exact match
+4. Merge nested objects recursively with the same rules
+5. Return ONLY valid JSON`;
+
+    const userMessage = `Object 1:
+${JSON.stringify(obj1, null, 2)}
+
+Object 2:
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Find differences between two objects
+   * @param {Object} obj1 - First object
+   * @param {Object} obj2 - Second object
+   * @returns {Promise<{added: Object, removed: Object, changed: Object}>} Differences
+   */
+  async difference(obj1, obj2) {
+    const systemPrompt = `You are a JSON comparison expert. Find the semantic differences between these two JSON objects.
+
+Return a JSON object with:
+- "added": fields/values present in obj2 but not in obj1
+- "removed": fields/values present in obj1 but not in obj2
+- "changed": fields where the value changed (show both old and new)
+
+Consider semantic similarity - fields with different names but same meaning should be considered the same.
+Return ONLY valid JSON with the structure: {"added": {}, "removed": {}, "changed": {}}`;
+
+    const userMessage = `Object 1 (original):
+${JSON.stringify(obj1, null, 2)}
+
+Object 2 (new):
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Concatenate arrays and text fields semantically
+   * @param {Object} obj1 - First object
+   * @param {Object} obj2 - Second object
+   * @returns {Promise<Object>} Concatenated object
+   */
+  async concatenate(obj1, obj2) {
+    const systemPrompt = `You are a JSON concatenation expert. Concatenate these two JSON objects.
+
+Rules:
+1. For string fields: append obj2 values to obj1 values with appropriate separators
+2. For array fields: append obj2 arrays to obj1 arrays
+3. For number fields: sum the values
+4. For object fields: recursively concatenate
+5. For boolean fields: use logical OR
+6. Preserve the structure of obj1
+7. Return ONLY valid JSON`;
+
+    const userMessage = `Object 1:
+${JSON.stringify(obj1, null, 2)}
+
+Object 2:
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Find intersection - common concepts between objects
+   * @param {Object} obj1 - First object
+   * @param {Object} obj2 - Second object
+   * @returns {Promise<Object>} Common elements
+   */
+  async intersection(obj1, obj2) {
+    const systemPrompt = `You are a JSON comparison expert. Find the semantic intersection of these two JSON objects.
+
+Rules:
+1. Return only fields/values that are semantically present in BOTH objects
+2. For arrays, return only items that have semantic matches in both
+3. Consider semantic similarity, not just exact matches
+4. Return ONLY valid JSON`;
+
+    const userMessage = `Object 1:
+${JSON.stringify(obj1, null, 2)}
+
+Object 2:
+${JSON.stringify(obj2, null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.2 });
+  }
+
+  /**
+   * Transform object structure
+   * @param {Object} obj - Object to transform
+   * @param {string} targetStructure - Description of target structure
+   * @returns {Promise<Object>} Transformed object
+   */
+  async transform(obj, targetStructure) {
+    const systemPrompt = `You are a JSON transformation expert. Transform this JSON object according to the target structure description.
+
+Target structure: ${targetStructure}
+
+Rules:
+1. Map existing fields to the new structure
+2. Preserve all information, reorganizing as needed
+3. Use appropriate type conversions
+4. Return ONLY valid JSON`;
+
+    return this.llm.getJSON(systemPrompt, JSON.stringify(obj, null, 2), { temperature: 0.3 });
+  }
+
+  /**
+   * Simplify/flatten nested object
+   * @param {Object} obj - Object to simplify
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Simplified object
+   */
+  async simplify(obj, options = {}) {
+    const systemPrompt = `You are a JSON simplification expert. Simplify this nested JSON object.
+
+Rules:
+1. Flatten deeply nested structures where appropriate
+2. Combine redundant fields
+3. Remove null/empty values${options.keepEmpty ? ' (unless specified to keep)' : ''}
+4. Use clear, concise field names
+5. Return ONLY valid JSON`;
+
+    return this.llm.getJSON(systemPrompt, JSON.stringify(obj, null, 2), { temperature: 0.3 });
+  }
+
+  /**
+   * Apply a natural language operation to JSON
+   * @param {Object} obj - Object to modify
+   * @param {string} operation - Natural language description of operation
+   * @returns {Promise<Object>} Modified object
+   */
+  async apply(obj, operation) {
+    const systemPrompt = `You are a JSON manipulation expert. Apply the following operation to the JSON object:
+
+Operation: ${operation}
+
+Return ONLY valid JSON with the operation applied.`;
+
+    return this.llm.getJSON(systemPrompt, JSON.stringify(obj, null, 2), { temperature: 0.3 });
+  }
+}
+
+export default JSONOps;

package/src/ai/llm-service.js

@@ -0,0 +1,205 @@
+/**
+ * LLM Service - Core OpenAI wrapper for HoloSphere
+ * Provides simple chat completions without Assistants API
+ */
+
+import OpenAI from 'openai';
+
+/**
+ * LLM Service class for interacting with OpenAI
+ */
+export class LLMService {
+  /**
+   * @param {string} apiKey - OpenAI API key
+   * @param {Object} options - Configuration options
+   * @param {string} options.model - Model to use (default: 'gpt-4o-mini')
+   * @param {number} options.maxTokens - Max tokens (default: 2000)
+   * @param {number} options.temperature - Temperature (default: 0.7)
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error('OpenAI API key is required');
+    }
+
+    this.openai = new OpenAI({ apiKey });
+    this.model = options.model || 'gpt-4o-mini';
+    this.maxTokens = options.maxTokens || 2000;
+    this.temperature = options.temperature || 0.7;
+  }
+
+  /**
+   * Send a message to the LLM
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userMessage - User message
+   * @param {Object} options - Override options
+   * @returns {Promise<string>} Response content
+   */
+  async sendMessage(systemPrompt, userMessage, options = {}) {
+    try {
+      const response = await this.openai.chat.completions.create({
+        model: options.model || this.model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: userMessage }
+        ],
+        max_tokens: options.maxTokens || this.maxTokens,
+        temperature: options.temperature ?? this.temperature,
+      });
+
+      return response.choices[0]?.message?.content?.trim() || '';
+    } catch (error) {
+      throw new Error(`LLM request failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Send multiple messages (conversation)
+   * @param {Array<{role: string, content: string}>} messages - Messages array
+   * @param {Object} options - Override options
+   * @returns {Promise<string>} Response content
+   */
+  async chat(messages, options = {}) {
+    try {
+      const response = await this.openai.chat.completions.create({
+        model: options.model || this.model,
+        messages,
+        max_tokens: options.maxTokens || this.maxTokens,
+        temperature: options.temperature ?? this.temperature,
+      });
+
+      return response.choices[0]?.message?.content?.trim() || '';
+    } catch (error) {
+      throw new Error(`LLM chat failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Summarize text
+   * @param {string} text - Text to summarize
+   * @param {Object} options - Options (maxLength, style)
+   * @returns {Promise<string>} Summary
+   */
+  async summarize(text, options = {}) {
+    const systemPrompt = `You are a helpful assistant that summarizes text concisely while preserving key information. Keep summaries clear and focused.${
+      options.maxLength ? ` Keep the summary under ${options.maxLength} words.` : ''
+    }${options.style ? ` Style: ${options.style}.` : ''}`;
+
+    return this.sendMessage(systemPrompt, text, { temperature: 0.5 });
+  }
+
+  /**
+   * Analyze text from a specific perspective
+   * @param {string} text - Text to analyze
+   * @param {string} aspect - Aspect to analyze (sentiment, themes, tone, etc.)
+   * @returns {Promise<string>} Analysis
+   */
+  async analyze(text, aspect) {
+    const systemPrompt = `You are an expert analyst. Analyze the following text from the perspective of "${aspect}". Provide a clear, structured analysis.`;
+    return this.sendMessage(systemPrompt, text, { temperature: 0.3 });
+  }
+
+  /**
+   * Extract keywords from text
+   * @param {string} text - Text to extract keywords from
+   * @param {number} maxKeywords - Maximum keywords (default: 10)
+   * @returns {Promise<string[]>} Array of keywords
+   */
+  async extractKeywords(text, maxKeywords = 10) {
+    const systemPrompt = `Extract the ${maxKeywords} most important keywords or key phrases from the text. Return ONLY a JSON array of strings, nothing else. Example: ["keyword1", "keyword2"]`;
+    const response = await this.sendMessage(systemPrompt, text, { temperature: 0.2 });
+
+    try {
+      return JSON.parse(response);
+    } catch {
+      // Try to extract array from response if JSON parsing fails
+      const match = response.match(/\[[\s\S]*\]/);
+      if (match) {
+        return JSON.parse(match[0]);
+      }
+      return response.split(',').map(k => k.trim().replace(/["\[\]]/g, ''));
+    }
+  }
+
+  /**
+   * Categorize text into given categories
+   * @param {string} text - Text to categorize
+   * @param {string[]} categories - Available categories
+   * @returns {Promise<{category: string, confidence: number, reasoning: string}>}
+   */
+  async categorize(text, categories) {
+    const systemPrompt = `Categorize the following text into one of these categories: ${categories.join(', ')}.
+Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.0-1.0, "reasoning": "brief explanation"}`;
+
+    const response = await this.sendMessage(systemPrompt, text, { temperature: 0.2 });
+
+    try {
+      return JSON.parse(response);
+    } catch {
+      const match = response.match(/\{[\s\S]*\}/);
+      if (match) {
+        return JSON.parse(match[0]);
+      }
+      return { category: categories[0], confidence: 0.5, reasoning: response };
+    }
+  }
+
+  /**
+   * Translate text to target language
+   * @param {string} text - Text to translate
+   * @param {string} targetLanguage - Target language
+   * @returns {Promise<string>} Translated text
+   */
+  async translate(text, targetLanguage) {
+    const systemPrompt = `Translate the following text to ${targetLanguage}. Return ONLY the translation, nothing else.`;
+    return this.sendMessage(systemPrompt, text, { temperature: 0.3 });
+  }
+
+  /**
+   * Generate questions about content
+   * @param {string} text - Text to generate questions about
+   * @param {number} count - Number of questions (default: 5)
+   * @returns {Promise<string[]>} Array of questions
+   */
+  async generateQuestions(text, count = 5) {
+    const systemPrompt = `Generate ${count} insightful questions about the following text. Return ONLY a JSON array of question strings, nothing else. Example: ["Question 1?", "Question 2?"]`;
+    const response = await this.sendMessage(systemPrompt, text, { temperature: 0.7 });
+
+    try {
+      return JSON.parse(response);
+    } catch {
+      const match = response.match(/\[[\s\S]*\]/);
+      if (match) {
+        return JSON.parse(match[0]);
+      }
+      return response.split('\n').filter(q => q.trim().endsWith('?'));
+    }
+  }
+
+  /**
+   * Get JSON response from LLM
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userMessage - User message
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Parsed JSON response
+   */
+  async getJSON(systemPrompt, userMessage, options = {}) {
+    const response = await this.sendMessage(
+      systemPrompt + '\n\nReturn ONLY valid JSON, no additional text.',
+      userMessage,
+      { ...options, temperature: options.temperature ?? 0.2 }
+    );
+
+    try {
+      return JSON.parse(response);
+    } catch {
+      // Try to extract JSON from response
+      const match = response.match(/[\[{][\s\S]*[\]}]/);
+      if (match) {
+        return JSON.parse(match[0]);
+      }
+      throw new Error(`Failed to parse JSON response: ${response.substring(0, 100)}`);
+    }
+  }
+}
+
+export default LLMService;