holosphere 2.0.0-alpha1 → 2.0.0-alpha10

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/cdn-entry.js

@@ -0,0 +1,22 @@
+/**
+ * CDN Entry Point for HoloSphere
+ *
+ * This file creates a clean global API for browser usage.
+ * After including the script, use: new HoloSphere({ appName: 'my-app' })
+ *
+ * Also exposes h3 library as window.h3 for hexagon visualization.
+ */
+
+// Import the main class
+import { HoloSphere } from './index.js';
+
+// Import h3-js for hexagon boundary visualization
+import * as h3 from 'h3-js';
+
+// Expose h3 globally for widget use
+if (typeof window !== 'undefined') {
+  window.h3 = h3;
+}
+
+// Export only the main class as default
+export default HoloSphere;

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;