holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/jsdoc.json

@@ -0,0 +1,26 @@
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".+\\.js$",
+    "excludePattern": "(node_modules|tests|contracts)"
+  },
+  "opts": {
+    "template": "node_modules/clean-jsdoc-theme",
+    "destination": "./docs/api",
+    "recurse": true,
+    "readme": "./README.md"
+  },
+  "plugins": ["plugins/markdown"],
+  "templates": {
+    "cleverLinks": true,
+    "monospaceLinks": true,
+    "default": {
+      "outputSourceFiles": true,
+      "includeDate": false
+    }
+  },
+  "tags": {
+    "allowUnknownTags": true,
+    "dictionaries": ["jsdoc", "closure"]
+  }
+}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "holosphere",
-  "version": "2.0.0-alpha0",
-  "description": "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with GunDB distributed P2P storage",
+  "version": "2.0.0-alpha10",
+  "description": "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with distributed P2P storage",
   "type": "module",
   "bin": {
-    "holosphere-activitypub": "./bin/holosphere-activitypub.js"
+    "holosphere-activitypub": "bin/holosphere-activitypub.js"
   },
   "main": "./dist/cjs/holosphere.cjs",
   "module": "./dist/esm/holosphere.js",
   "browser": "./dist/cdn/holosphere.min.js",
-  "types": "./dist/types/index.d.ts",
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/esm/holosphere.js",
@@ -19,6 +19,9 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:cdn": "vite build --config vite.config.cdn.js",
+    "build:all": "npm run build && npm run build:cdn",
+    "docs": "jsdoc -c jsdoc.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -33,14 +36,27 @@
     "distributed",
     "holonic",
     "federation",
-    "noosphere"
+    "noosphere",
+    "smart-contracts",
+    "ethereum",
+    "erc20",
+    "fractal"
   ],
-  "author": "",
-  "license": "MIT",
+  "author": "Roberto Valenti",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liminalvillage/holosphere2.git"
+  },
+  "homepage": "https://github.com/liminalvillage/holosphere2#readme",
+  "bugs": {
+    "url": "https://github.com/liminalvillage/holosphere2/issues"
+  },
   "dependencies": {
     "@noble/curves": "^1.3.0",
     "ajv": "^8.12.0",
     "dotenv": "^17.2.3",
+    "ethers": "^6.13.4",
     "express": "^4.21.0",
     "h3-js": "^4.1.0",
     "nostr-tools": "^2.17.0",
@@ -52,7 +68,9 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^1.3.0",
+    "clean-jsdoc-theme": "^4.3.0",
     "eslint": "^8.57.0",
+    "jsdoc": "^4.0.4",
     "prettier": "^3.2.5",
     "terser": "^5.44.0",
     "vite": "^5.1.0",

package/src/ai/aggregation.js

@@ -1,11 +1,22 @@
 /**
- * Smart Aggregation - AI-assisted hierarchical data aggregation up the holon tree
+ * @fileoverview AI-assisted hierarchical data aggregation up the H3 holon tree.
+ * Provides smart upcast, summary generation, and temporal comparison across hierarchical levels.
+ * @module ai/aggregation
  */
 
 import * as h3 from 'h3-js';
 
 /**
- * Smart Aggregation class
+ * Service class for intelligent hierarchical data aggregation.
+ * Automatically summarizes data at each level and propagates insights up the H3 hierarchy,
+ * enabling multi-scale understanding of geographic data.
+ *
+ * @class SmartAggregation
+ * @example
+ * const aggregation = new SmartAggregation(llmService, holosphere);
+ * const upcast = await aggregation.smartUpcast(holonId, 'projects', { maxLevels: 3 });
+ * const summary = await aggregation.generateHolonSummary(holonId);
+ * const comparison = await aggregation.comparePeriods(holonId, 'events', period1, period2);
  */
 export class SmartAggregation {
   /**

package/src/ai/breakdown.js

@@ -1,9 +1,19 @@
 /**
- * Task Breakdown - Recursively decompose tasks/quests into subtasks
+ * @fileoverview Recursive task decomposition system for breaking down complex tasks into manageable subtasks.
+ * Provides AI-powered hierarchical task breakdown with dependency tracking and progress monitoring.
+ * @module ai/breakdown
  */
 
 /**
- * Task Breakdown class
+ * Service class for recursively decomposing tasks/quests into hierarchical subtasks.
+ * Uses AI to intelligently break down complex tasks while maintaining dependency relationships
+ * and enabling progress tracking across the task tree.
+ *
+ * @class TaskBreakdown
+ * @example
+ * const taskBreakdown = new TaskBreakdown(llmService, holosphere);
+ * const result = await taskBreakdown.breakdown(task, holonId, 'quests', { depth: 3 });
+ * const progress = await taskBreakdown.getProgress(holonId, 'quests', taskId);
  */
 export class TaskBreakdown {
   /**

package/src/ai/classifier.js

@@ -1,9 +1,20 @@
 /**
- * Classifier - Auto-classification of content to appropriate lenses
+ * @fileoverview AI-powered content classification to appropriate data lenses.
+ * Provides automatic categorization, multi-label classification, and schema suggestion.
+ * @module ai/classifier
  */
 
 /**
- * Classifier class for content categorization
+ * Service class for automatically classifying content into appropriate lenses.
+ * Uses AI to determine the best lens(es) for content storage and provides
+ * schema validation and suggestion capabilities.
+ *
+ * @class Classifier
+ * @example
+ * const classifier = new Classifier(llmService, holosphere);
+ * classifier.registerLens('projects', 'Community projects and initiatives');
+ * const result = await classifier.classifyToLens(content);
+ * await classifier.autoStore(holonId, content);
  */
 export class Classifier {
   /**
@@ -36,7 +47,7 @@ export class Classifier {
 
   /**
    * Register multiple lenses
-   * @param {Object<string, {description: string, schema?: Object}>} lenses
+   * @param {Object.<string, Object>} lenses - Map of lens names to config objects with description and optional schema
    */
   registerLenses(lenses) {
     for (const [name, config] of Object.entries(lenses)) {

package/src/ai/council.js

@@ -1,8 +1,10 @@
 /**
- * Council - Multi-perspective wisdom from different viewpoints
+ * @fileoverview Multi-perspective wisdom gathering from different viewpoints.
+ * Implements a council of perspectives to analyze questions from diverse angles.
+ * @module ai/council
  */
 
-// Default 12 perspectives based on HolonsBot
+// Default 12 perspectives based on HolonsBot holistic framework
 const DEFAULT_PERSPECTIVES = [
   { name: 'Values & Worldview', prompt: 'Answer from the embodied perspective of Values and Worldview - considering ethics, beliefs, culture, and meaning.' },
   { name: 'Health & Wellbeing', prompt: 'Answer from the embodied perspective of Health & Wellbeing - considering physical, mental, and social health.' },
@@ -19,7 +21,16 @@ const DEFAULT_PERSPECTIVES = [
 ];
 
 /**
- * Council class for multi-perspective answers
+ * Service class for gathering multi-perspective wisdom on questions and topics.
+ * Simulates a council of experts answering from diverse viewpoints,
+ * then synthesizes their responses into balanced insights.
+ *
+ * @class Council
+ * @example
+ * const council = new Council(llmService);
+ * const result = await council.ask("How should we approach climate change?");
+ * console.log(result.perspectives); // Array of perspective responses
+ * console.log(result.summary); // Synthesized wisdom
  */
 export class Council {
   /**
@@ -48,10 +59,14 @@ export class Council {
   }
 
   /**
-   * Ask a question to the council
-   * @param {string} question - Question to ask
-   * @param {Object} options - Options
-   * @returns {Promise<{perspectives: Array, summary: string}>}
+   * Ask a question to the council and receive diverse perspective responses.
+   *
+   * @param {string} question - Question to ask the council
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.parallel=true] - Query perspectives in parallel or sequentially
+   * @param {boolean} [options.includeSummary=true] - Generate a synthesis summary
+   * @param {Array} [options.perspectives] - Override default perspectives
+   * @returns {Promise<{question: string, perspectives: Array, summary: string, timestamp: number}>} Council responses
    */
   async ask(question, options = {}) {
     const { parallel = true, includeSummary = true } = options;

package/src/ai/embeddings.js

@@ -1,9 +1,19 @@
 /**
- * Embeddings - Vector embedding generation and semantic search
+ * @fileoverview Vector embedding generation and semantic search functionality using OpenAI's text-embedding models.
+ * Provides methods for generating embeddings, calculating similarity, semantic search, and k-means clustering.
+ * @module ai/embeddings
  */
 
 /**
- * Embeddings class for vector operations
+ * Service class for vector embeddings and semantic operations.
+ * Supports single and batch embedding generation, cosine similarity calculations,
+ * semantic search across HoloSphere data, and k-means clustering.
+ *
+ * @class Embeddings
+ * @example
+ * const embeddings = new Embeddings(openaiClient, holosphere);
+ * const vector = await embeddings.embed("sample text");
+ * const results = await embeddings.semanticSearch("query", holon, lens);
  */
 export class Embeddings {
   /**
@@ -26,9 +36,11 @@ export class Embeddings {
   }
 
   /**
-   * Generate embedding for text
+   * Generate a vector embedding for the given text.
+   *
    * @param {string} text - Text to embed
-   * @returns {Promise<number[]>} Embedding vector
+   * @returns {Promise<number[]>} Embedding vector (1536 dimensions by default)
+   * @throws {Error} If embedding generation fails
    */
   async embed(text) {
     try {
@@ -62,10 +74,13 @@ export class Embeddings {
   }
 
   /**
-   * Calculate cosine similarity between two vectors
-   * @param {number[]} vec1 - First vector
-   * @param {number[]} vec2 - Second vector
-   * @returns {number} Similarity score (0-1)
+   * Calculate cosine similarity between two embedding vectors.
+   * Returns a score between -1 and 1, where 1 indicates identical vectors.
+   *
+   * @param {number[]} vec1 - First embedding vector
+   * @param {number[]} vec2 - Second embedding vector
+   * @returns {number} Similarity score (0-1 for normalized vectors)
+   * @throws {Error} If vectors have different lengths
    */
   cosineSimilarity(vec1, vec2) {
     if (vec1.length !== vec2.length) {
@@ -124,12 +139,17 @@ export class Embeddings {
   }
 
   /**
-   * Semantic search within a holon/lens
-   * @param {string} query - Search query
+   * Perform semantic search within a holon/lens using vector similarity.
+   * Returns items ranked by semantic similarity to the query.
+   *
+   * @param {string} query - Natural language search query
    * @param {string} holon - Holon identifier
    * @param {string} lens - Lens name
-   * @param {Object} options - Search options
-   * @returns {Promise<Array<{item: Object, similarity: number}>>} Ranked results
+   * @param {Object} [options={}] - Search options
+   * @param {number} [options.limit=10] - Maximum results to return
+   * @param {number} [options.threshold=0.5] - Minimum similarity score (0-1)
+   * @returns {Promise<Array<{item: Object, similarity: number}>>} Results ranked by similarity descending
+   * @throws {Error} If HoloSphere instance not configured
    */
   async semanticSearch(query, holon, lens, options = {}) {
     if (!this.holosphere) {
@@ -180,10 +200,12 @@ export class Embeddings {
   }
 
   /**
-   * Cluster items by semantic similarity
+   * Cluster items by semantic similarity using k-means algorithm.
+   * Automatically generates embeddings for items that don't have them.
+   *
    * @param {Object[]} items - Items to cluster
-   * @param {number} numClusters - Approximate number of clusters
-   * @returns {Promise<Object[][]>} Clustered items
+   * @param {number} [numClusters=5] - Target number of clusters
+   * @returns {Promise<Object[][]>} Array of clusters, each containing related items
    */
   async cluster(items, numClusters = 5) {
     // Get embeddings for items that don't have them

package/src/ai/federation-ai.js

@@ -1,9 +1,20 @@
 /**
- * Federation Advisor - AI-powered federation suggestions and analysis
+ * @fileoverview AI-powered federation recommendations and network health analysis.
+ * Provides suggestions for federation partnerships, health monitoring, and network optimization.
+ * @module ai/federation-ai
  */
 
 /**
- * Federation Advisor class
+ * Service class for analyzing and optimizing holon federation networks.
+ * Suggests federation partnerships based on content similarity, analyzes network health,
+ * identifies bridges between clusters, and recommends optimizations.
+ *
+ * @class FederationAdvisor
+ * @example
+ * const advisor = new FederationAdvisor(llmService, holosphere, embeddings);
+ * const suggestions = await advisor.suggestFederations(holonId, { candidateHolons });
+ * const health = await advisor.analyzeFederationHealth(holonId);
+ * const bridges = await advisor.findBridges(holonIds);
  */
 export class FederationAdvisor {
   /**

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 {
   /**