holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/ai/h3-ai.js

@@ -1,11 +1,23 @@
 /**
- * H3 AI - Geospatial intelligence for H3 hexagonal hierarchies
+ * @fileoverview Geospatial intelligence for H3 hexagonal hierarchies.
+ * Provides AI-powered analysis of geographic data distribution, resolution suggestions,
+ * coverage analysis, and cross-resolution insights using the H3 geospatial indexing system.
+ * @module ai/h3-ai
  */
 
 import * as h3 from 'h3-js';
 
 /**
- * H3 AI class for geospatial intelligence
+ * Service class for geospatial intelligence using H3 hexagonal hierarchies.
+ * Analyzes geographic data patterns, suggests optimal resolutions, identifies coverage gaps,
+ * and provides multi-scale geographic insights across H3's hierarchical grid system.
+ *
+ * @class H3AI
+ * @example
+ * const h3ai = new H3AI(llmService, holosphere);
+ * const resolution = await h3ai.suggestResolution(project);
+ * const coverage = await h3ai.analyzeCoverage(holonId, 'projects');
+ * const distribution = await h3ai.analyzeDistribution(holonId, 'events');
  */
 export class H3AI {
   /**

package/src/ai/index.js

@@ -1,6 +1,8 @@
 /**
- * HoloSphere AI Module
- * Comprehensive AI functionality using OpenAI chat completions
+ * @fileoverview HoloSphere AI Module - Comprehensive AI functionality using OpenAI.
+ * Provides unified access to all AI services including LLM, embeddings, semantic operations,
+ * spatial analysis, task breakdown, and relationship discovery.
+ * @module ai
  */
 
 // Import all modules for local use and re-export
@@ -41,12 +43,19 @@ export {
 };
 
 /**
- * Create all AI services with shared LLM instance
+ * Factory function to create all AI services with shared LLM instance.
+ * Provides a convenient way to initialize the complete AI stack with a single call.
+ *
  * @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
+ * @param {Object} [holosphere=null] - HoloSphere instance for data operations
+ * @param {Object} [options={}] - Configuration options
+ * @param {Object} [options.llm] - LLM service configuration (model, maxTokens, temperature)
+ * @param {Object} [openaiClient=null] - Pre-created OpenAI client for embeddings/TTS
+ * @returns {Object} Object containing all initialized AI service instances
+ * @example
+ * const ai = createAIServices(apiKey, holosphere, { llm: { model: 'gpt-4o-mini' } });
+ * const summary = await ai.llm.summarize(text);
+ * const results = await ai.nlQuery.execute("find projects near Rome");
  */
 export function createAIServices(apiKey, holosphere = null, options = {}, openaiClient = null) {
   // Create shared LLM service

package/src/ai/json-ops.js

@@ -1,9 +1,19 @@
 /**
- * Fuzzy JSON Operations - AI-assisted semantic operations on JSON structures
+ * @fileoverview AI-assisted semantic operations on JSON structures.
+ * Provides fuzzy operations like merge, subtract, union, and transform that understand semantic meaning.
+ * @module ai/json-ops
  */
 
 /**
- * JSON Operations class for semantic JSON manipulation
+ * Service class for semantic JSON manipulation using AI.
+ * Performs intelligent operations on JSON objects that go beyond simple structural merging,
+ * understanding semantic similarity and conceptual relationships between data.
+ *
+ * @class JSONOps
+ * @example
+ * const jsonOps = new JSONOps(llmService);
+ * const merged = await jsonOps.add(obj1, obj2);
+ * const diff = await jsonOps.difference(oldData, newData);
  */
 export class JSONOps {
   /**
@@ -14,11 +24,14 @@ export class JSONOps {
   }
 
   /**
-   * Semantically merge two JSON objects
+   * Semantically merge two JSON objects with intelligent deduplication.
+   * Combines information from both objects, resolving conflicts semantically.
+   *
    * @param {Object} obj1 - First object
    * @param {Object} obj2 - Second object
-   * @param {Object} options - Merge options
-   * @returns {Promise<Object>} Merged object
+   * @param {Object} [options={}] - Merge options
+   * @param {boolean} [options.preferSecond=false] - Prefer second object's values in conflicts
+   * @returns {Promise<Object>} Merged object with combined information
    */
   async add(obj1, obj2, options = {}) {
     const systemPrompt = `You are a JSON merge expert. Semantically merge these two JSON objects.

package/src/ai/llm-service.js

@@ -1,12 +1,20 @@
 /**
- * LLM Service - Core OpenAI wrapper for HoloSphere
- * Provides simple chat completions without Assistants API
+ * @fileoverview Core OpenAI wrapper providing simple chat completions without Assistants API.
+ * @module ai/llm-service
  */
 
 import OpenAI from 'openai';
 
 /**
- * LLM Service class for interacting with OpenAI
+ * Service class for interacting with OpenAI's chat completion API.
+ * Provides high-level methods for common LLM operations including summarization,
+ * analysis, categorization, translation, and structured JSON responses.
+ *
+ * @class LLMService
+ * @example
+ * const llm = new LLMService(apiKey, { model: 'gpt-4o-mini' });
+ * const summary = await llm.summarize(longText);
+ * const keywords = await llm.extractKeywords(text);
  */
 export class LLMService {
   /**
@@ -28,11 +36,16 @@ export class LLMService {
   }
 
   /**
-   * Send a message to the LLM
-   * @param {string} systemPrompt - System prompt
-   * @param {string} userMessage - User message
-   * @param {Object} options - Override options
+   * Send a single-turn message to the LLM with system and user prompts.
+   *
+   * @param {string} systemPrompt - System prompt defining role and behavior
+   * @param {string} userMessage - User message content
+   * @param {Object} [options={}] - Override options
+   * @param {string} [options.model] - Override model
+   * @param {number} [options.maxTokens] - Override max tokens
+   * @param {number} [options.temperature] - Override temperature
    * @returns {Promise<string>} Response content
+   * @throws {Error} If LLM request fails
    */
   async sendMessage(systemPrompt, userMessage, options = {}) {
     try {
@@ -53,10 +66,15 @@ export class LLMService {
   }
 
   /**
-   * Send multiple messages (conversation)
-   * @param {Array<{role: string, content: string}>} messages - Messages array
-   * @param {Object} options - Override options
+   * Send multiple messages in a conversation format.
+   *
+   * @param {Array<{role: string, content: string}>} messages - Array of message objects with role and content
+   * @param {Object} [options={}] - Override options
+   * @param {string} [options.model] - Override model
+   * @param {number} [options.maxTokens] - Override max tokens
+   * @param {number} [options.temperature] - Override temperature
    * @returns {Promise<string>} Response content
+   * @throws {Error} If LLM chat fails
    */
   async chat(messages, options = {}) {
     try {
@@ -74,10 +92,13 @@ export class LLMService {
   }
 
   /**
-   * Summarize text
+   * Generate a concise summary of text while preserving key information.
+   *
    * @param {string} text - Text to summarize
-   * @param {Object} options - Options (maxLength, style)
-   * @returns {Promise<string>} Summary
+   * @param {Object} [options={}] - Summarization options
+   * @param {number} [options.maxLength] - Maximum word count for summary
+   * @param {string} [options.style] - Summary style (e.g., 'bullet points', 'executive summary')
+   * @returns {Promise<string>} Summary text
    */
   async summarize(text, options = {}) {
     const systemPrompt = `You are a helpful assistant that summarizes text concisely while preserving key information. Keep summaries clear and focused.${
@@ -88,10 +109,11 @@ export class LLMService {
   }
 
   /**
-   * Analyze text from a specific perspective
+   * Analyze text from a specific perspective or aspect.
+   *
    * @param {string} text - Text to analyze
-   * @param {string} aspect - Aspect to analyze (sentiment, themes, tone, etc.)
-   * @returns {Promise<string>} Analysis
+   * @param {string} aspect - Analysis aspect (e.g., 'sentiment', 'themes', 'tone', 'bias')
+   * @returns {Promise<string>} Structured 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.`;
@@ -99,10 +121,12 @@ export class LLMService {
   }
 
   /**
-   * Extract keywords from text
+   * Extract key words and phrases from text.
+   *
    * @param {string} text - Text to extract keywords from
-   * @param {number} maxKeywords - Maximum keywords (default: 10)
-   * @returns {Promise<string[]>} Array of keywords
+   * @param {number} [maxKeywords=10] - Maximum number of keywords to extract
+   * @returns {Promise<string[]>} Array of keyword strings
+   * @throws {Error} If JSON parsing fails after retry attempts
    */
   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"]`;
@@ -121,10 +145,11 @@ export class LLMService {
   }
 
   /**
-   * Categorize text into given categories
+   * Categorize text into one of the provided categories with confidence score.
+   *
    * @param {string} text - Text to categorize
-   * @param {string[]} categories - Available categories
-   * @returns {Promise<{category: string, confidence: number, reasoning: string}>}
+   * @param {string[]} categories - Available category options
+   * @returns {Promise<{category: string, confidence: number, reasoning: string}>} Categorization result
    */
   async categorize(text, categories) {
     const systemPrompt = `Categorize the following text into one of these categories: ${categories.join(', ')}.
@@ -144,9 +169,10 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
   }
 
   /**
-   * Translate text to target language
+   * Translate text to a target language.
+   *
    * @param {string} text - Text to translate
-   * @param {string} targetLanguage - Target language
+   * @param {string} targetLanguage - Target language name (e.g., 'Spanish', 'French')
    * @returns {Promise<string>} Translated text
    */
   async translate(text, targetLanguage) {
@@ -155,10 +181,11 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
   }
 
   /**
-   * Generate questions about content
+   * Generate insightful questions about the content.
+   *
    * @param {string} text - Text to generate questions about
-   * @param {number} count - Number of questions (default: 5)
-   * @returns {Promise<string[]>} Array of questions
+   * @param {number} [count=5] - Number of questions to generate
+   * @returns {Promise<string[]>} Array of question strings
    */
   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?"]`;
@@ -176,11 +203,15 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
   }
 
   /**
-   * Get JSON response from LLM
-   * @param {string} systemPrompt - System prompt
+   * Get a structured JSON response from the LLM with automatic parsing.
+   * Attempts to extract JSON from response even if surrounded by additional text.
+   *
+   * @param {string} systemPrompt - System prompt (JSON instruction will be appended)
    * @param {string} userMessage - User message
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Parsed JSON response
+   * @param {Object} [options={}] - Request options
+   * @param {number} [options.temperature=0.2] - Temperature (defaults to 0.2 for structured output)
+   * @returns {Promise<Object>} Parsed JSON object
+   * @throws {Error} If JSON parsing fails completely
    */
   async getJSON(systemPrompt, userMessage, options = {}) {
     const response = await this.sendMessage(

package/src/ai/nl-query.js

@@ -1,9 +1,19 @@
 /**
- * Natural Language Query - Query HoloSphere data using natural language
+ * @fileoverview Natural language query interface for HoloSphere data.
+ * Converts natural language queries to structured filters and executes searches.
+ * @module ai/nl-query
  */
 
 /**
- * NL Query class for natural language to structured query conversion
+ * Service class for querying HoloSphere data using natural language.
+ * Translates natural language queries into structured filters with support for
+ * spatial, temporal, and field-based filtering.
+ *
+ * @class NLQuery
+ * @example
+ * const nlQuery = new NLQuery(llmService, holosphere);
+ * const results = await nlQuery.execute("find projects near Rome with more than 10 participants");
+ * const suggestions = await nlQuery.suggest({ holons: ['rome', 'milan'] });
  */
 export class NLQuery {
   /**

package/src/ai/relationships.js

@@ -1,9 +1,20 @@
 /**
- * Relationship Discovery - Find hidden connections across data
+ * @fileoverview Discover hidden connections and relationships across data.
+ * Provides relationship discovery, graph building, pattern detection, and connection suggestions.
+ * @module ai/relationships
  */
 
 /**
- * Relationship Discovery class
+ * Service class for discovering hidden connections and relationships in data.
+ * Identifies thematic, entity, temporal, causal, and geographic relationships,
+ * builds relationship graphs, and suggests collaboration opportunities.
+ *
+ * @class RelationshipDiscovery
+ * @example
+ * const discovery = new RelationshipDiscovery(llmService, holosphere, embeddings);
+ * const relationships = await discovery.discoverRelationships(holonId, 'projects');
+ * const similar = await discovery.findSimilar(item, holonId, 'quests');
+ * const graph = await discovery.buildGraph(holonId, 'events');
  */
 export class RelationshipDiscovery {
   /**

package/src/ai/schema-extractor.js

@@ -1,9 +1,18 @@
 /**
- * Schema Extractor - Extract structured data from text using JSON schemas
+ * @fileoverview Extract structured data from unstructured text using JSON schemas.
+ * Provides schema-based data extraction, validation, and field completion.
+ * @module ai/schema-extractor
  */
 
 /**
- * Schema Extractor class
+ * Service class for extracting structured data from text using JSON schemas.
+ * Leverages LLM to parse unstructured content and map it to defined schemas.
+ *
+ * @class SchemaExtractor
+ * @example
+ * const extractor = new SchemaExtractor(llmService);
+ * const schema = { properties: { name: { type: "string" }, age: { type: "number" } } };
+ * const data = await extractor.extractToSchema(text, schema);
  */
 export class SchemaExtractor {
   /**
@@ -14,10 +23,13 @@ export class SchemaExtractor {
   }
 
   /**
-   * Extract data from text based on JSON schema
-   * @param {string} text - Text to extract from
-   * @param {Object} schema - JSON schema defining expected structure
-   * @param {Object} options - Extraction options
+   * Extract structured data from text according to a JSON schema.
+   * Uses LLM to intelligently parse unstructured text and map to schema fields.
+   *
+   * @param {string} text - Unstructured text to extract from
+   * @param {Object} schema - JSON schema defining target structure
+   * @param {Object} [options={}] - Extraction options
+   * @param {number} [options.maxTokens=2000] - Maximum tokens for response
    * @returns {Promise<Object>} Extracted data conforming to schema
    */
   async extractToSchema(text, schema, options = {}) {
@@ -157,10 +169,12 @@ Return JSON with ONLY the missing fields that you can extract. Do not modify exi
   }
 
   /**
-   * Validate extracted data against schema
-   * @param {Object} data - Extracted data
-   * @param {Object} schema - JSON schema
-   * @returns {{valid: boolean, errors: string[]}}
+   * Validate extracted data against a JSON schema.
+   * Performs basic type checking and required field validation.
+   *
+   * @param {Object} data - Extracted data to validate
+   * @param {Object} schema - JSON schema to validate against
+   * @returns {{valid: boolean, errors: string[]}} Validation result with error list
    */
   validateExtraction(data, schema) {
     const errors = [];

package/src/ai/spatial.js

@@ -1,9 +1,20 @@
 /**
- * Spatial Analysis - AI-powered analysis of data patterns across geographic regions
+ * @fileoverview AI-powered spatial analysis of data patterns across geographic regions.
+ * Provides region analysis, comparison, trend detection, hotspot identification, and reporting.
+ * @module ai/spatial
  */
 
 /**
- * Spatial Analysis class
+ * Service class for analyzing spatial data patterns across geographic regions.
+ * Identifies trends, compares regions, finds hotspots, and generates comprehensive
+ * spatial reports using AI-driven analysis.
+ *
+ * @class SpatialAnalysis
+ * @example
+ * const spatial = new SpatialAnalysis(llmService, holosphere);
+ * const analysis = await spatial.analyzeRegion(holonId, 'projects', 'activity');
+ * const comparison = await spatial.compareRegions(holon1, holon2, 'quests');
+ * const trends = await spatial.spatialTrends(holonId, 'events', { start: '2024-01-01' });
  */
 export class SpatialAnalysis {
   /**

package/src/ai/tts.js

@@ -1,9 +1,12 @@
 /**
- * Text-to-Speech - OpenAI TTS integration
+ * @fileoverview OpenAI text-to-speech integration for audio generation.
+ * Provides methods for converting text to speech with various voices and formats.
+ * @module ai/tts
  */
 
 /**
- * Available voices for TTS
+ * Available voice options for text-to-speech.
+ * @enum {string}
  */
 export const VOICES = {
   ALLOY: 'alloy',
@@ -15,7 +18,8 @@ export const VOICES = {
 };
 
 /**
- * Available TTS models
+ * Available TTS model options.
+ * @enum {string}
  */
 export const MODELS = {
   TTS_1: 'tts-1',
@@ -23,7 +27,14 @@ export const MODELS = {
 };
 
 /**
- * TTS class for text-to-speech conversion
+ * Service class for converting text to speech using OpenAI's TTS API.
+ * Supports multiple voices, output formats, and handles long text with automatic chunking.
+ *
+ * @class TTS
+ * @example
+ * const tts = new TTS(openaiClient);
+ * const audioBuffer = await tts.speak("Hello world", { voice: VOICES.NOVA });
+ * const dataUrl = await tts.speakDataUrl("Hello", { voice: VOICES.ECHO });
  */
 export class TTS {
   /**
@@ -36,10 +47,16 @@ export class TTS {
   }
 
   /**
-   * Convert text to speech
-   * @param {string} text - Text to convert
-   * @param {Object} options - TTS options
-   * @returns {Promise<Buffer>} Audio buffer (MP3)
+   * Convert text to speech audio.
+   *
+   * @param {string} text - Text to convert to speech
+   * @param {Object} [options={}] - TTS generation options
+   * @param {string} [options.voice] - Voice to use (from VOICES enum)
+   * @param {string} [options.model] - Model to use (from MODELS enum)
+   * @param {number} [options.speed=1.0] - Speech speed (0.25 to 4.0)
+   * @param {string} [options.responseFormat='mp3'] - Audio format (mp3, opus, aac, flac)
+   * @returns {Promise<Buffer>} Audio buffer
+   * @throws {Error} If TTS generation fails
    */
   async speak(text, options = {}) {
     const {

package/src/content/social-protocols.js

@@ -1,16 +1,20 @@
 /**
- * Social Protocol Adapters (Nostr, ActivityPub)
+ * @fileoverview Social protocol adapters for Nostr (NIP-01) and ActivityPub formats.
+ * Provides validation, transformation, and filtering utilities for social content integration.
+ * @module content/social-protocols
  */
 
 // Import ValidationError from the validator module
 import { ValidationError } from '../schema/validator.js';
 
 /**
- * Validate Nostr NIP-01 event format
- * @param {Object} event - Nostr event
- * @param {boolean} partial - Allow partial events (missing id, pubkey, sig)
- * @returns {boolean} True if valid
- * @throws {ValidationError} If strict validation fails
+ * Validate Nostr NIP-01 event format.
+ * Checks required fields (kind, tags, content, created_at) and optionally id, pubkey, sig.
+ * @param {Object} event - Nostr event object to validate
+ * @param {boolean} [partial=true] - Allow partial events (missing id, pubkey, sig for signing)
+ * @param {boolean} [throwOnError=false] - Throw ValidationError on failure instead of returning false
+ * @returns {boolean} True if valid, false otherwise (unless throwOnError is true)
+ * @throws {ValidationError} If validation fails and throwOnError is true
  */
 export function validateNostrEvent(event, partial = true, throwOnError = false) {
   if (!event || typeof event !== 'object') {
@@ -56,12 +60,13 @@ export function validateNostrEvent(event, partial = true, throwOnError = false)
 }
 
 /**
- * Validate ActivityPub object format
- * @param {Object} object - ActivityPub object
- * @param {boolean} throwOnError - Throw ValidationError on failure
- * @param {boolean} requireId - Require id field (default: false, will be auto-generated)
- * @returns {boolean} True if valid
- * @throws {ValidationError} If strict validation fails
+ * Validate ActivityPub object format.
+ * Checks for required @context and type fields, optionally validates id field.
+ * @param {Object} object - ActivityPub object to validate
+ * @param {boolean} [throwOnError=false] - Throw ValidationError on failure instead of returning false
+ * @param {boolean} [requireId=false] - Require id field (default: false, will be auto-generated)
+ * @returns {boolean} True if valid, false otherwise (unless throwOnError is true)
+ * @throws {ValidationError} If validation fails and throwOnError is true
  */
 export function validateActivityPubObject(object, throwOnError = false, requireId = false) {
   if (!object || typeof object !== 'object') {
@@ -85,9 +90,10 @@ export function validateActivityPubObject(object, throwOnError = false, requireI
 }
 
 /**
- * Transform Nostr event to HoloSphere format
- * @param {Object} event - Nostr event
- * @returns {Object} HoloSphere data object
+ * Transform Nostr event to HoloSphere storage format.
+ * Normalizes Nostr events and adds metadata for HoloSphere compatibility.
+ * @param {Object} event - Nostr NIP-01 event object
+ * @returns {Object} HoloSphere data object with protocol metadata
  */
 export function transformNostrEvent(event) {
   // Generate missing fields if needed
@@ -115,9 +121,10 @@ export function transformNostrEvent(event) {
 }
 
 /**
- * Transform ActivityPub object to HoloSphere format
+ * Transform ActivityPub object to HoloSphere storage format.
+ * Normalizes ActivityPub objects and adds metadata for HoloSphere compatibility.
  * @param {Object} object - ActivityPub object
- * @returns {Object} HoloSphere data object
+ * @returns {Object} HoloSphere data object with protocol metadata
  */
 export function transformActivityPubObject(object) {
   // Generate ID if not provided
@@ -139,10 +146,11 @@ export function transformActivityPubObject(object) {
 }
 
 /**
- * Filter social content by access level
- * @param {Object[]} content - Social content array
- * @param {string} accessLevel - Access level filter
- * @returns {Object[]} Filtered content
+ * Filter social content by access level.
+ * Returns items matching the specified access level or all items if no level specified.
+ * @param {Object[]} content - Array of social content items
+ * @param {string} accessLevel - Access level to filter by (e.g., 'public', 'private')
+ * @returns {Object[]} Filtered content array
  */
 export function filterByAccessLevel(content, accessLevel) {
   if (!accessLevel) return content;
@@ -153,10 +161,11 @@ export function filterByAccessLevel(content, accessLevel) {
 }
 
 /**
- * Filter social content by protocol
- * @param {Object[]} content - Social content array
- * @param {string} protocol - Protocol filter ('nostr' or 'activitypub')
- * @returns {Object[]} Filtered content
+ * Filter social content by protocol type.
+ * Returns items matching the specified protocol or all items if 'all' is specified.
+ * @param {Object[]} content - Array of social content items
+ * @param {string} protocol - Protocol to filter by ('nostr', 'activitypub', or 'all')
+ * @returns {Object[]} Filtered content array
  */
 export function filterByProtocol(content, protocol) {
   if (!protocol || protocol === 'all') return content;