holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/lib/ai-methods.js

@@ -1,15 +1,24 @@
 /**
- * AI Methods Mixin
- * All AI-powered operations for HoloSphere
+ * @fileoverview AI methods mixin providing comprehensive AI-powered operations for HoloSphere.
+ * Includes LLM operations, embeddings, semantic search, natural language queries, spatial analysis,
+ * and specialized AI features for geographic and hierarchical data processing.
+ * @module lib/ai-methods
  */
 
 /**
- * Mixin that adds AI methods to a HoloSphere class
+ * Mixin that adds AI methods to a HoloSphere class.
+ * Provides access to LLM, embeddings, semantic search, council, classification,
+ * spatial analysis, aggregation, federation advisor, relationships, and task breakdown.
  * @param {Class} Base - Base class to extend
  * @returns {Class} Extended class with AI methods
  */
 export function withAIMethods(Base) {
   return class extends Base {
+    /**
+     * Internal method to ensure AI services are initialized.
+     * @private
+     * @throws {Error} If AI services are not initialized
+     */
     _requireAI() {
       if (!this._ai) {
         throw new Error('AI services not initialized. Provide openaiKey in config.');
@@ -18,31 +27,70 @@ export function withAIMethods(Base) {
 
     // --- Core LLM Methods ---
 
+    /**
+     * Summarize text using AI.
+     * @param {string} text - Text content to summarize
+     * @param {Object} [options={}] - Summarization options (model, maxLength, etc.)
+     * @returns {Promise<string>} Generated summary
+     */
     async summarize(text, options = {}) {
       this._requireAI();
       return this._ai.llm.summarize(text, options);
     }
 
+    /**
+     * Analyze text for a specific aspect using AI.
+     * @param {string} text - Text content to analyze
+     * @param {string} aspect - Aspect to analyze (e.g., 'sentiment', 'tone', 'themes')
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<string>} Analysis result
+     */
     async analyze(text, aspect, options = {}) {
       this._requireAI();
       return this._ai.llm.analyze(text, aspect, options);
     }
 
+    /**
+     * Extract keywords from text using AI.
+     * @param {string} text - Text content to process
+     * @param {Object} [options={}] - Extraction options (count, focus, etc.)
+     * @returns {Promise<string[]>} Array of extracted keywords
+     */
     async extractKeywords(text, options = {}) {
       this._requireAI();
       return this._ai.llm.extractKeywords(text, options);
     }
 
+    /**
+     * Categorize text into one of the provided categories.
+     * @param {string} text - Text content to categorize
+     * @param {string[]} categories - Array of possible categories
+     * @param {Object} [options={}] - Categorization options
+     * @returns {Promise<string>} Selected category
+     */
     async categorize(text, categories, options = {}) {
       this._requireAI();
       return this._ai.llm.categorize(text, categories, options);
     }
 
+    /**
+     * Translate text to target language using AI.
+     * @param {string} text - Text to translate
+     * @param {string} targetLanguage - Target language (e.g., 'Spanish', 'French')
+     * @param {Object} [options={}] - Translation options
+     * @returns {Promise<string>} Translated text
+     */
     async translate(text, targetLanguage, options = {}) {
       this._requireAI();
       return this._ai.llm.translate(text, targetLanguage, options);
     }
 
+    /**
+     * Generate questions from text using AI.
+     * @param {string} text - Text content to generate questions from
+     * @param {Object} [options={}] - Generation options (count, type, etc.)
+     * @returns {Promise<string[]>} Array of generated questions
+     */
     async generateQuestions(text, options = {}) {
       this._requireAI();
       return this._ai.llm.generateQuestions(text, options);
@@ -50,6 +98,14 @@ export function withAIMethods(Base) {
 
     // --- Schema Extraction ---
 
+    /**
+     * Extract structured data from text according to a lens schema.
+     * @param {string} text - Text to extract data from
+     * @param {string} lensName - Name of lens with defined schema
+     * @param {Object} [options={}] - Extraction options
+     * @returns {Promise<Object>} Extracted data matching schema
+     * @throws {Error} If schema not found for lens
+     */
     async extractToSchema(text, lensName, options = {}) {
       this._requireAI();
       const schemaObj = await this.getSchema(lensName);
@@ -61,26 +117,61 @@ export function withAIMethods(Base) {
 
     // --- Fuzzy JSON Operations ---
 
+    /**
+     * AI-powered fuzzy addition of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy addition
+     */
     async jsonAdd(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.add(obj1, obj2, options);
     }
 
+    /**
+     * AI-powered fuzzy subtraction of JSON objects.
+     * @param {Object} obj1 - Object to subtract from
+     * @param {Object} obj2 - Object to subtract
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy subtraction
+     */
     async jsonSubtract(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.subtract(obj1, obj2, options);
     }
 
+    /**
+     * AI-powered fuzzy union of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy union
+     */
     async jsonUnion(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.union(obj1, obj2, options);
     }
 
+    /**
+     * AI-powered fuzzy difference of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy difference
+     */
     async jsonDifference(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.difference(obj1, obj2, options);
     }
 
+    /**
+     * AI-powered fuzzy concatenation of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy concatenation
+     */
     async jsonConcatenate(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.concatenate(obj1, obj2, options);
@@ -88,16 +179,37 @@ export function withAIMethods(Base) {
 
     // --- Embeddings & Semantic Search ---
 
+    /**
+     * Generate embedding vector for text.
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     */
     async embed(text) {
       this._requireAI();
       return this._ai.embeddings.embed(text);
     }
 
+    /**
+     * Perform semantic search on holon data using embeddings.
+     * @param {string} query - Search query text
+     * @param {string} holonId - Holon to search within
+     * @param {string} lensName - Lens to search within
+     * @param {Object} [options={}] - Search options (limit, threshold, etc.)
+     * @returns {Promise<Object[]>} Ranked search results
+     */
     async semanticSearch(query, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.embeddings.semanticSearch(query, holonId, lensName, options);
     }
 
+    /**
+     * Store data with automatically generated embedding.
+     * @param {string} holonId - Holon ID to store in
+     * @param {string} lensName - Lens name to store under
+     * @param {Object} data - Data object to store
+     * @param {string} [textField='description'] - Field to use for embedding generation
+     * @returns {Promise<Object>} Stored data with embedding
+     */
     async storeWithEmbedding(holonId, lensName, data, textField = 'description') {
       this._requireAI();
       return this._ai.embeddings.storeWithEmbedding(holonId, lensName, data, textField);
@@ -105,11 +217,24 @@ export function withAIMethods(Base) {
 
     // --- Multi-Perspective Council ---
 
+    /**
+     * Ask a question to the multi-perspective AI council.
+     * @param {string} question - Question to ask
+     * @param {Object} [options={}] - Council options (perspectives, synthesis, etc.)
+     * @returns {Promise<Object>} Council responses and synthesis
+     */
     async askCouncil(question, options = {}) {
       this._requireAI();
       return this._ai.council.ask(question, options);
     }
 
+    /**
+     * Ask a question to a custom set of perspectives.
+     * @param {string} question - Question to ask
+     * @param {string[]} perspectives - Array of perspective descriptions
+     * @param {Object} [options={}] - Council options
+     * @returns {Promise<Object>} Custom council responses and synthesis
+     */
     async askCouncilCustom(question, perspectives, options = {}) {
       this._requireAI();
       return this._ai.council.askCustom(question, perspectives, options);
@@ -117,11 +242,25 @@ export function withAIMethods(Base) {
 
     // --- Text-to-Speech ---
 
+    /**
+     * Convert text to speech audio.
+     * @param {string} text - Text to convert to speech
+     * @param {string} [voice='nova'] - Voice to use (alloy, echo, fable, onyx, nova, shimmer)
+     * @param {Object} [options={}] - TTS options (speed, format, etc.)
+     * @returns {Promise<Buffer>} Audio buffer
+     */
     async textToSpeech(text, voice = 'nova', options = {}) {
       this._requireAI();
       return this._ai.tts.speak(text, voice, options);
     }
 
+    /**
+     * Convert text to speech audio (base64 encoded).
+     * @param {string} text - Text to convert to speech
+     * @param {string} [voice='nova'] - Voice to use
+     * @param {Object} [options={}] - TTS options
+     * @returns {Promise<string>} Base64-encoded audio
+     */
     async textToSpeechBase64(text, voice = 'nova', options = {}) {
       this._requireAI();
       return this._ai.tts.speakBase64(text, voice, options);
@@ -129,11 +268,24 @@ export function withAIMethods(Base) {
 
     // --- Natural Language Queries ---
 
+    /**
+     * Execute a natural language query on holon data.
+     * @param {string} query - Natural language query
+     * @param {string|null} [holonId=null] - Optional holon to query
+     * @param {string|null} [lensName=null] - Optional lens to query
+     * @param {Object} [options={}] - Query options
+     * @returns {Promise<Object>} Query results
+     */
     async nlQuery(query, holonId = null, lensName = null, options = {}) {
       this._requireAI();
       return this._ai.nlQuery.execute(query, holonId, lensName, options);
     }
 
+    /**
+     * Parse a natural language query into structured components.
+     * @param {string} query - Natural language query
+     * @returns {Promise<Object>} Parsed query structure
+     */
     async parseNLQuery(query) {
       this._requireAI();
       return this._ai.nlQuery.parse(query);
@@ -141,16 +293,35 @@ export function withAIMethods(Base) {
 
     // --- Auto-Classification ---
 
+    /**
+     * Classify content to determine appropriate lens.
+     * @param {string|Object} content - Content to classify
+     * @param {Object} [options={}] - Classification options
+     * @returns {Promise<string>} Recommended lens name
+     */
     async classifyToLens(content, options = {}) {
       this._requireAI();
       return this._ai.classifier.classifyToLens(content, options);
     }
 
+    /**
+     * Automatically classify and store content in appropriate lens.
+     * @param {string} holonId - Holon to store in
+     * @param {string|Object} content - Content to classify and store
+     * @param {Object} [options={}] - Storage options
+     * @returns {Promise<Object>} Stored data with classification info
+     */
     async autoStore(holonId, content, options = {}) {
       this._requireAI();
       return this._ai.classifier.autoStore(holonId, content, options);
     }
 
+    /**
+     * Register a lens for auto-classification.
+     * @param {string} lensName - Lens name to register
+     * @param {string} description - Lens description for classification
+     * @param {string[]} [keywords=[]] - Keywords associated with lens
+     */
     registerLensForClassification(lensName, description, keywords = []) {
       this._requireAI();
       this._ai.classifier.registerLens(lensName, description, keywords);
@@ -158,16 +329,38 @@ export function withAIMethods(Base) {
 
     // --- Spatial Analysis ---
 
+    /**
+     * Analyze a geographic region using AI.
+     * @param {string} holonId - H3 holon ID to analyze
+     * @param {string|null} [lensName=null] - Optional lens to focus on
+     * @param {string|null} [aspect=null] - Optional aspect to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Region analysis
+     */
     async analyzeRegion(holonId, lensName = null, aspect = null, options = {}) {
       this._requireAI();
       return this._ai.spatial.analyzeRegion(holonId, lensName, aspect, options);
     }
 
+    /**
+     * Compare two geographic regions using AI.
+     * @param {string} holon1 - First H3 holon ID
+     * @param {string} holon2 - Second H3 holon ID
+     * @param {string|null} [lensName=null] - Optional lens to focus comparison
+     * @returns {Promise<Object>} Comparison analysis
+     */
     async compareRegions(holon1, holon2, lensName = null) {
       this._requireAI();
       return this._ai.spatial.compareRegions(holon1, holon2, lensName);
     }
 
+    /**
+     * Analyze spatial trends over time.
+     * @param {string} holonId - H3 holon ID
+     * @param {string} lensName - Lens to analyze trends for
+     * @param {Object|null} [timeRange=null] - Time range for trend analysis
+     * @returns {Promise<Object>} Trend analysis
+     */
     async spatialTrends(holonId, lensName, timeRange = null) {
       this._requireAI();
       return this._ai.spatial.spatialTrends(holonId, lensName, timeRange);
@@ -175,11 +368,23 @@ export function withAIMethods(Base) {
 
     // --- Smart Aggregation ---
 
+    /**
+     * Intelligently upcast data with AI-powered aggregation.
+     * @param {string} holonId - H3 holon ID to upcast from
+     * @param {string} lensName - Lens to upcast
+     * @param {Object} [options={}] - Upcast options
+     * @returns {Promise<Object>} Smart upcast result
+     */
     async smartUpcast(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.aggregation.smartUpcast(holonId, lensName, options);
     }
 
+    /**
+     * Generate AI-powered summary of holon data.
+     * @param {string} holonId - Holon ID to summarize
+     * @returns {Promise<string>} Generated holon summary
+     */
     async generateHolonSummary(holonId) {
       this._requireAI();
       return this._ai.aggregation.generateHolonSummary(holonId);
@@ -187,16 +392,32 @@ export function withAIMethods(Base) {
 
     // --- Federation Advisor ---
 
+    /**
+     * Get AI suggestions for holon federations.
+     * @param {string} holonId - Holon to analyze for federation
+     * @param {Object} [options={}] - Suggestion options
+     * @returns {Promise<Object[]>} Array of federation suggestions
+     */
     async suggestFederations(holonId, options = {}) {
       this._requireAI();
       return this._ai.federationAdvisor.suggestFederations(holonId, options);
     }
 
+    /**
+     * Analyze health of holon's federations.
+     * @param {string} holonId - Holon to analyze
+     * @returns {Promise<Object>} Federation health report
+     */
     async analyzeFederationHealth(holonId) {
       this._requireAI();
       return this._ai.federationAdvisor.analyzeFederationHealth(holonId);
     }
 
+    /**
+     * Get AI recommendations for optimizing federations.
+     * @param {string} holonId - Holon to optimize
+     * @returns {Promise<Object>} Optimization recommendations
+     */
     async optimizeFederation(holonId) {
       this._requireAI();
       return this._ai.federationAdvisor.optimizeFederation(holonId);
@@ -204,21 +425,48 @@ export function withAIMethods(Base) {
 
     // --- Relationship Discovery ---
 
+    /**
+     * Discover relationships between data items using AI.
+     * @param {string} holonId - Holon to analyze
+     * @param {string|null} [lensName=null] - Optional lens to focus on
+     * @returns {Promise<Object[]>} Discovered relationships
+     */
     async discoverRelationships(holonId, lensName = null) {
       this._requireAI();
       return this._ai.relationships.discoverRelationships(holonId, lensName);
     }
 
+    /**
+     * Find similar items using AI and embeddings.
+     * @param {Object} item - Item to find similar items for
+     * @param {string} holonId - Holon to search within
+     * @param {string|null} [lensName=null] - Optional lens to search
+     * @param {Object} [options={}] - Search options (limit, threshold, etc.)
+     * @returns {Promise<Object[]>} Similar items
+     */
     async findSimilar(item, holonId, lensName = null, options = {}) {
       this._requireAI();
       return this._ai.relationships.findSimilar(item, holonId, lensName, options);
     }
 
+    /**
+     * Build relationship graph for holon data.
+     * @param {string} holonId - Holon ID
+     * @param {string} lensName - Lens to build graph for
+     * @returns {Promise<Object>} Relationship graph structure
+     */
     async buildRelationshipGraph(holonId, lensName) {
       this._requireAI();
       return this._ai.relationships.buildGraph(holonId, lensName);
     }
 
+    /**
+     * Get AI suggestions for connecting an item to others.
+     * @param {Object} item - Item to suggest connections for
+     * @param {string} holonId - Holon context
+     * @param {string} lensName - Lens context
+     * @returns {Promise<Object[]>} Connection suggestions
+     */
     async suggestConnections(item, holonId, lensName) {
       this._requireAI();
       return this._ai.relationships.suggestConnections(item, holonId, lensName);
@@ -226,26 +474,56 @@ export function withAIMethods(Base) {
 
     // --- Task Breakdown ---
 
+    /**
+     * Break down complex item into subtasks using AI.
+     * @param {Object} item - Item to break down
+     * @param {string} holonId - Holon to store breakdown in
+     * @param {string} lensName - Lens to use for subtasks
+     * @param {Object} [options={}] - Breakdown options (depth, strategy, etc.)
+     * @returns {Promise<Object>} Breakdown structure
+     */
     async breakdown(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.taskBreakdown.breakdown(item, holonId, lensName, options);
     }
 
+    /**
+     * Get AI suggestion for breakdown strategy.
+     * @param {Object} item - Item to analyze
+     * @returns {Promise<Object>} Suggested breakdown strategy
+     */
     async suggestBreakdownStrategy(item) {
       this._requireAI();
       return this._ai.taskBreakdown.suggestStrategy(item);
     }
 
+    /**
+     * Flatten hierarchical breakdown into linear array.
+     * @param {Object} breakdownResult - Breakdown structure to flatten
+     * @returns {Object[]} Flattened breakdown items
+     */
     flattenBreakdown(breakdownResult) {
       this._requireAI();
       return this._ai.taskBreakdown.flatten(breakdownResult);
     }
 
+    /**
+     * Get dependency-ordered list of breakdown items.
+     * @param {Object} breakdownResult - Breakdown structure
+     * @returns {Object[]} Items ordered by dependencies
+     */
     getBreakdownDependencyOrder(breakdownResult) {
       this._requireAI();
       return this._ai.taskBreakdown.getDependencyOrder(breakdownResult);
     }
 
+    /**
+     * Get progress status of breakdown items.
+     * @param {string} holonId - Holon ID
+     * @param {string} lensName - Lens name
+     * @param {string} itemId - Parent item ID
+     * @returns {Promise<Object>} Progress report
+     */
     async getBreakdownProgress(holonId, lensName, itemId) {
       this._requireAI();
       return this._ai.taskBreakdown.getProgress(holonId, lensName, itemId);
@@ -253,51 +531,122 @@ export function withAIMethods(Base) {
 
     // --- H3 Geospatial AI ---
 
+    /**
+     * Get AI suggestion for optimal H3 resolution for item.
+     * @param {Object} item - Item to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<number>} Suggested H3 resolution level
+     */
     async suggestH3Resolution(item, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestResolution(item, options);
     }
 
+    /**
+     * Analyze H3 distribution patterns in data.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Distribution analysis
+     */
     async analyzeH3Distribution(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeDistribution(holonId, lensName, options);
     }
 
+    /**
+     * Find relevance of neighbor H3 cells.
+     * @param {string} holonId - H3 holon ID
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object[]>} Neighbor relevance scores
+     */
     async findH3NeighborRelevance(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.findNeighborRelevance(holonId, lensName, options);
     }
 
+    /**
+     * Get AI suggestion for geographic scope of item.
+     * @param {Object} item - Item to analyze
+     * @param {string} holonId - Context holon
+     * @param {string} lensName - Context lens
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Geographic scope suggestion
+     */
     async suggestGeographicScope(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestGeographicScope(item, holonId, lensName, options);
     }
 
+    /**
+     * Analyze H3 coverage patterns.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Coverage analysis
+     */
     async analyzeH3Coverage(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeCoverage(holonId, lensName, options);
     }
 
+    /**
+     * Get insights across different H3 resolutions.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Cross-resolution insights
+     */
     async crossH3ResolutionInsights(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.crossResolutionInsights(holonId, lensName, options);
     }
 
+    /**
+     * Get AI suggestion for migrating item to different H3 resolution.
+     * @param {Object} item - Item to migrate
+     * @param {string} holonId - Current holon
+     * @param {string} lensName - Lens context
+     * @param {Object} [options={}] - Migration options
+     * @returns {Promise<Object>} Migration suggestion
+     */
     async suggestH3Migration(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestMigration(item, holonId, lensName, options);
     }
 
+    /**
+     * Generate comprehensive geographic report for holon.
+     * @param {string} holonId - H3 holon to report on
+     * @param {Object} [options={}] - Report options
+     * @returns {Promise<string>} Generated geographic report
+     */
     async generateH3Report(holonId, options = {}) {
       this._requireAI();
       return this._ai.h3ai.generateGeographicReport(holonId, options);
     }
 
+    /**
+     * Find geographic clusters in holon data.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Clustering options
+     * @returns {Promise<Object[]>} Identified clusters
+     */
     async findH3Clusters(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.findGeographicClusters(holonId, lensName, options);
     }
 
+    /**
+     * Analyze geographic impact of an item.
+     * @param {Object} item - Item to analyze impact for
+     * @param {string} holonId - Context holon
+     * @param {string} lensName - Context lens
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Impact analysis
+     */
     async analyzeH3Impact(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeGeographicImpact(item, holonId, lensName, options);