holosphere 1.1.20 → 2.0.0-alpha1

package/src/ai/h3-ai.js

@@ -0,0 +1,955 @@
+/**
+ * H3 AI - Geospatial intelligence for H3 hexagonal hierarchies
+ */
+
+import * as h3 from 'h3-js';
+
+/**
+ * H3 AI class for geospatial intelligence
+ */
+export class H3AI {
+  /**
+   * @param {LLMService} llmService - LLM service instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  constructor(llmService, holosphere = null) {
+    this.llm = llmService;
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Set HoloSphere instance
+   * @param {Object} holosphere - HoloSphere instance
+   */
+  setHoloSphere(holosphere) {
+    this.holosphere = holosphere;
+  }
+
+  /**
+   * Suggest optimal H3 resolution for a task/project based on its scope
+   * @param {Object} item - Item to analyze (task, project, quest)
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Resolution recommendation
+   */
+  async suggestResolution(item, options = {}) {
+    const { currentResolution = null, context = null } = options;
+
+    const systemPrompt = `You are a geospatial planning expert. Analyze this item and suggest the optimal H3 hexagonal resolution (0-15) for organizing it.
+
+H3 Resolution Guide:
+- Resolution 0-2: Continental/country scale (thousands of km)
+- Resolution 3-4: Regional/state scale (hundreds of km)
+- Resolution 5-6: Metropolitan/city scale (tens of km)
+- Resolution 7-8: District/neighborhood scale (km)
+- Resolution 9-10: Block/street scale (hundreds of meters)
+- Resolution 11-12: Building/lot scale (tens of meters)
+- Resolution 13-15: Room/precise scale (meters)
+
+Consider:
+1. Geographic scope mentioned in the item
+2. Number of potential participants/stakeholders
+3. Type of activity (local vs regional)
+4. Resource requirements and logistics
+5. Similar projects' typical scale
+
+${currentResolution !== null ? `Current resolution: ${currentResolution}` : ''}
+${context ? `Context:\n${JSON.stringify(context, null, 2)}` : ''}
+
+Return JSON:
+{
+  "recommendedResolution": n,
+  "reasoning": "why this resolution",
+  "alternativeResolutions": [{"resolution": n, "useCase": "when to use"}],
+  "geographicScope": "description of area covered",
+  "scaleSuggestions": {
+    "expansion": {"resolution": n, "reason": "when to expand"},
+    "contraction": {"resolution": n, "reason": "when to focus"}
+  }
+}`;
+
+    return this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(item, null, 2),
+      { temperature: 0.3 }
+    );
+  }
+
+  /**
+   * Analyze geographic distribution of data across H3 cells
+   * @param {string} holonId - Parent holon to analyze
+   * @param {string} lensName - Lens to analyze
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Distribution analysis
+   */
+  async analyzeDistribution(holonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const { includeChildren = true, maxChildren = 20 } = options;
+
+    // Get data from the holon
+    const parentData = await this.holosphere.getAll(holonId, lensName);
+
+    // Get data from children if requested
+    const childrenData = {};
+    if (includeChildren && h3.isValidCell(holonId)) {
+      const resolution = h3.getResolution(holonId);
+      if (resolution < 15) {
+        const children = h3.cellToChildren(holonId, resolution + 1);
+        for (const child of children.slice(0, maxChildren)) {
+          try {
+            const data = await this.holosphere.getAll(child, lensName);
+            if (data.length > 0) {
+              childrenData[child] = {
+                count: data.length,
+                sample: data.slice(0, 3),
+              };
+            }
+          } catch {
+            // Skip unavailable children
+          }
+        }
+      }
+    }
+
+    const systemPrompt = `You are a geospatial analyst. Analyze the distribution of data across this H3 hexagonal region.
+
+Parent holon: ${holonId}
+Resolution: ${h3.isValidCell(holonId) ? h3.getResolution(holonId) : 'N/A'}
+Parent data count: ${parentData.length}
+Children with data: ${Object.keys(childrenData).length}
+
+Analyze:
+1. Data density and distribution patterns
+2. Geographic hotspots and cold spots
+3. Coverage gaps
+4. Clustering patterns
+5. Recommendations for better coverage
+
+Return JSON:
+{
+  "distribution": {
+    "pattern": "clustered|uniform|sparse|concentrated",
+    "density": "high|medium|low",
+    "coverage": 0.0-1.0
+  },
+  "hotspots": [{"holonId": "id", "reason": "why"}],
+  "gaps": [{"description": "gap description", "suggestedAction": "what to do"}],
+  "clusters": [{"theme": "cluster theme", "holons": ["id1"]}],
+  "recommendations": ["rec1"],
+  "summary": "overview"
+}`;
+
+    const userMessage = `Parent data sample:
+${JSON.stringify(parentData.slice(0, 10), null, 2)}
+
+Children distribution:
+${JSON.stringify(childrenData, null, 2)}`;
+
+    const analysis = await this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.3 });
+
+    return {
+      holonId,
+      lensName,
+      resolution: h3.isValidCell(holonId) ? h3.getResolution(holonId) : null,
+      parentDataCount: parentData.length,
+      childrenAnalyzed: Object.keys(childrenData).length,
+      analysis,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Find relevant data from neighboring H3 cells
+   * @param {string} holonId - Center holon
+   * @param {string} lensName - Lens to search
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Neighbor recommendations
+   */
+  async findNeighborRelevance(holonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(holonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const { ringSize = 1, relevanceThreshold = 0.5 } = options;
+
+    // Get center data
+    const centerData = await this.holosphere.getAll(holonId, lensName);
+
+    // Get neighbor data
+    const neighbors = h3.gridDisk(holonId, ringSize).filter(n => n !== holonId);
+    const neighborData = {};
+
+    for (const neighbor of neighbors) {
+      try {
+        const data = await this.holosphere.getAll(neighbor, lensName);
+        if (data.length > 0) {
+          neighborData[neighbor] = data.slice(0, 5);
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    if (Object.keys(neighborData).length === 0) {
+      return {
+        holonId,
+        neighbors: [],
+        message: 'No data found in neighboring cells',
+      };
+    }
+
+    const systemPrompt = `You are a geospatial relevance analyst. Find items in neighboring H3 cells that are relevant to the center cell's data.
+
+Center cell: ${holonId}
+Ring size: ${ringSize} (immediate neighbors)
+
+Consider:
+1. Thematic overlap
+2. Potential collaborations
+3. Shared resources
+4. Cross-boundary projects
+5. Geographic continuity of activities
+
+Return JSON:
+{
+  "relevantNeighbors": [
+    {
+      "holonId": "neighbor_id",
+      "relevanceScore": 0.0-1.0,
+      "relevantItems": [{"id": "item_id", "reason": "why relevant"}],
+      "collaborationPotential": "description"
+    }
+  ],
+  "crossBoundaryOpportunities": [
+    {
+      "description": "opportunity",
+      "involvedHolons": ["id1", "id2"],
+      "suggestedAction": "what to do"
+    }
+  ],
+  "geographicPatterns": ["pattern1"],
+  "summary": "overview"
+}`;
+
+    const userMessage = `Center cell data:
+${JSON.stringify(centerData.slice(0, 10), null, 2)}
+
+Neighbor data:
+${JSON.stringify(neighborData, null, 2)}`;
+
+    const analysis = await this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.4 });
+
+    // Filter by threshold
+    if (analysis.relevantNeighbors) {
+      analysis.relevantNeighbors = analysis.relevantNeighbors
+        .filter(n => n.relevanceScore >= relevanceThreshold);
+    }
+
+    return {
+      holonId,
+      lensName,
+      ringSize,
+      neighborsAnalyzed: Object.keys(neighborData).length,
+      analysis,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Suggest geographic expansion or contraction for an item
+   * @param {Object} item - Item to analyze
+   * @param {string} currentHolonId - Current holon
+   * @param {string} lensName - Lens name
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Expansion/contraction suggestions
+   */
+  async suggestGeographicScope(item, currentHolonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(currentHolonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const currentResolution = h3.getResolution(currentHolonId);
+
+    // Get parent data
+    let parentData = [];
+    if (currentResolution > 0) {
+      const parent = h3.cellToParent(currentHolonId, currentResolution - 1);
+      try {
+        parentData = await this.holosphere.getAll(parent, lensName);
+      } catch {
+        // No parent data
+      }
+    }
+
+    // Get sample children data
+    let childrenData = [];
+    if (currentResolution < 15) {
+      const children = h3.cellToChildren(currentHolonId, currentResolution + 1);
+      for (const child of children.slice(0, 7)) {
+        try {
+          const data = await this.holosphere.getAll(child, lensName);
+          childrenData.push(...data.slice(0, 2));
+        } catch {
+          // Skip
+        }
+      }
+    }
+
+    const systemPrompt = `You are a geographic scope advisor. Analyze whether this item should expand to a larger region (parent holon) or focus on smaller sub-regions (children holons).
+
+Current holon: ${currentHolonId}
+Current resolution: ${currentResolution}
+
+Factors to consider:
+1. Item's stated scope and goals
+2. Current participation/activity level
+3. Resource requirements
+4. Similar activities in parent/children
+5. Natural geographic boundaries
+
+Return JSON:
+{
+  "currentScopeAssessment": {
+    "appropriate": true/false,
+    "reasoning": "why"
+  },
+  "expansionRecommendation": {
+    "recommended": true/false,
+    "targetResolution": n,
+    "reasoning": "why expand",
+    "benefits": ["benefit1"],
+    "risks": ["risk1"]
+  },
+  "contractionRecommendation": {
+    "recommended": true/false,
+    "targetResolution": n,
+    "reasoning": "why contract",
+    "suggestedFocusAreas": ["description"],
+    "benefits": ["benefit1"],
+    "risks": ["risk1"]
+  },
+  "optimalAction": "expand|contract|maintain",
+  "summary": "recommendation summary"
+}`;
+
+    const userMessage = `Item to analyze:
+${JSON.stringify(item, null, 2)}
+
+Parent region data (${parentData.length} items):
+${JSON.stringify(parentData.slice(0, 5), null, 2)}
+
+Children regions data (${childrenData.length} items):
+${JSON.stringify(childrenData.slice(0, 5), null, 2)}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.3 });
+  }
+
+  /**
+   * Analyze coverage gaps in a region
+   * @param {string} holonId - Region to analyze
+   * @param {string} lensName - Lens
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Coverage analysis
+   */
+  async analyzeCoverage(holonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(holonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const { targetResolution = null } = options;
+    const currentResolution = h3.getResolution(holonId);
+    const childResolution = targetResolution || Math.min(currentResolution + 1, 15);
+
+    // Get all children at target resolution
+    const children = h3.cellToChildren(holonId, childResolution);
+
+    // Check which children have data
+    const coverage = {
+      total: children.length,
+      withData: 0,
+      withoutData: 0,
+      dataDistribution: {},
+    };
+
+    const childrenWithData = [];
+    const childrenWithoutData = [];
+
+    for (const child of children) {
+      try {
+        const data = await this.holosphere.getAll(child, lensName);
+        if (data.length > 0) {
+          coverage.withData++;
+          coverage.dataDistribution[child] = data.length;
+          childrenWithData.push({ holon: child, count: data.length });
+        } else {
+          coverage.withoutData++;
+          childrenWithoutData.push(child);
+        }
+      } catch {
+        coverage.withoutData++;
+        childrenWithoutData.push(child);
+      }
+    }
+
+    const systemPrompt = `You are a geographic coverage analyst. Analyze the data coverage in this H3 region.
+
+Region: ${holonId}
+Resolution: ${currentResolution}
+Child resolution analyzed: ${childResolution}
+Total children: ${coverage.total}
+Children with data: ${coverage.withData}
+Children without data: ${coverage.withoutData}
+Coverage ratio: ${(coverage.withData / coverage.total * 100).toFixed(1)}%
+
+Analyze:
+1. Coverage patterns
+2. Potential reasons for gaps
+3. Priority areas for expansion
+4. Whether gaps are concerning or expected
+
+Return JSON:
+{
+  "coverageScore": 0.0-1.0,
+  "coverageQuality": "excellent|good|moderate|poor|minimal",
+  "patterns": {
+    "type": "clustered|scattered|peripheral|central|uniform",
+    "description": "pattern description"
+  },
+  "gaps": {
+    "count": n,
+    "significance": "high|medium|low",
+    "likelyReasons": ["reason1"],
+    "priorityAreas": ["description of areas to focus"]
+  },
+  "recommendations": [
+    {
+      "action": "what to do",
+      "priority": "high|medium|low",
+      "targetArea": "description"
+    }
+  ],
+  "summary": "overview"
+}`;
+
+    const analysis = await this.llm.getJSON(systemPrompt, '', { temperature: 0.3 });
+
+    return {
+      holonId,
+      lensName,
+      resolution: currentResolution,
+      childResolution,
+      coverage: {
+        ...coverage,
+        ratio: coverage.withData / coverage.total,
+      },
+      childrenWithData: childrenWithData.slice(0, 10),
+      gapCount: childrenWithoutData.length,
+      analysis,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Find patterns across multiple H3 resolutions
+   * @param {string} holonId - Starting holon
+   * @param {string} lensName - Lens
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Cross-resolution insights
+   */
+  async crossResolutionInsights(holonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(holonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const { levels = 3 } = options;
+    const currentResolution = h3.getResolution(holonId);
+
+    // Collect data at multiple resolutions
+    const resolutionData = {};
+
+    // Current level
+    const currentData = await this.holosphere.getAll(holonId, lensName);
+    resolutionData[currentResolution] = {
+      holon: holonId,
+      count: currentData.length,
+      sample: currentData.slice(0, 5),
+    };
+
+    // Parent levels
+    let parentHolon = holonId;
+    for (let i = 0; i < levels && h3.getResolution(parentHolon) > 0; i++) {
+      const res = h3.getResolution(parentHolon) - 1;
+      parentHolon = h3.cellToParent(parentHolon, res);
+      try {
+        const data = await this.holosphere.getAll(parentHolon, lensName);
+        resolutionData[res] = {
+          holon: parentHolon,
+          count: data.length,
+          sample: data.slice(0, 5),
+        };
+      } catch {
+        // Skip
+      }
+    }
+
+    // Child level (one level down)
+    if (currentResolution < 15) {
+      const childRes = currentResolution + 1;
+      const children = h3.cellToChildren(holonId, childRes);
+      let childTotal = 0;
+      const childSamples = [];
+
+      for (const child of children.slice(0, 7)) {
+        try {
+          const data = await this.holosphere.getAll(child, lensName);
+          childTotal += data.length;
+          if (data.length > 0) {
+            childSamples.push(...data.slice(0, 2));
+          }
+        } catch {
+          // Skip
+        }
+      }
+
+      resolutionData[childRes] = {
+        holon: `${children.length} children`,
+        count: childTotal,
+        sample: childSamples.slice(0, 5),
+      };
+    }
+
+    const systemPrompt = `You are a multi-scale geographic analyst. Find patterns that emerge across different H3 resolutions.
+
+Starting holon: ${holonId}
+Resolutions analyzed: ${Object.keys(resolutionData).sort().join(', ')}
+
+Data at each resolution:
+${JSON.stringify(resolutionData, null, 2)}
+
+Analyze:
+1. How themes evolve across scales
+2. What appears only at certain resolutions
+3. Aggregation patterns (local vs regional)
+4. Scale-dependent opportunities
+5. Optimal resolution for different activities
+
+Return JSON:
+{
+  "scalePatterns": [
+    {
+      "pattern": "description",
+      "visibleAt": [resolution_numbers],
+      "significance": "why this matters"
+    }
+  ],
+  "themeEvolution": {
+    "localThemes": ["themes at fine resolution"],
+    "regionalThemes": ["themes at coarse resolution"],
+    "consistentThemes": ["themes across all scales"]
+  },
+  "optimalResolutions": {
+    "forCollaboration": n,
+    "forResources": n,
+    "forCommunity": n,
+    "reasoning": "why"
+  },
+  "insights": ["insight1"],
+  "recommendations": ["rec1"],
+  "summary": "overview"
+}`;
+
+    return this.llm.getJSON(systemPrompt, '', { temperature: 0.4 });
+  }
+
+  /**
+   * Suggest item migration between holons based on geographic fit
+   * @param {Object} item - Item to analyze
+   * @param {string} currentHolonId - Current location
+   * @param {string} lensName - Lens
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Migration suggestions
+   */
+  async suggestMigration(item, currentHolonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(currentHolonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const { searchRadius = 2 } = options;
+
+    // Get data from nearby cells
+    const nearby = h3.gridDisk(currentHolonId, searchRadius);
+    const nearbyData = {};
+
+    for (const cell of nearby) {
+      if (cell === currentHolonId) continue;
+      try {
+        const data = await this.holosphere.getAll(cell, lensName);
+        if (data.length > 0) {
+          nearbyData[cell] = {
+            count: data.length,
+            sample: data.slice(0, 3),
+          };
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    // Also check parent
+    const currentRes = h3.getResolution(currentHolonId);
+    let parentData = null;
+    if (currentRes > 0) {
+      const parent = h3.cellToParent(currentHolonId, currentRes - 1);
+      try {
+        const data = await this.holosphere.getAll(parent, lensName);
+        parentData = { holon: parent, count: data.length, sample: data.slice(0, 3) };
+      } catch {
+        // Skip
+      }
+    }
+
+    const systemPrompt = `You are a geographic placement advisor. Determine if this item would be better suited in a different H3 cell.
+
+Current location: ${currentHolonId}
+Current resolution: ${currentRes}
+
+Consider:
+1. Thematic fit with existing data in each cell
+2. Geographic scope of the item
+3. Collaboration opportunities
+4. Resource proximity
+5. Community alignment
+
+Return JSON:
+{
+  "currentFit": {
+    "score": 0.0-1.0,
+    "reasoning": "why current location is/isn't appropriate"
+  },
+  "migrationRecommended": true/false,
+  "suggestedDestinations": [
+    {
+      "holonId": "cell_id",
+      "fitScore": 0.0-1.0,
+      "reasoning": "why this location",
+      "benefits": ["benefit1"],
+      "drawbacks": ["drawback1"]
+    }
+  ],
+  "stayReasons": ["reason to stay if applicable"],
+  "moveReasons": ["reason to move if applicable"],
+  "recommendation": "stay|move|duplicate",
+  "summary": "final recommendation"
+}`;
+
+    const userMessage = `Item to place:
+${JSON.stringify(item, null, 2)}
+
+Nearby cells with data:
+${JSON.stringify(nearbyData, null, 2)}
+
+${parentData ? `Parent cell data:\n${JSON.stringify(parentData, null, 2)}` : ''}`;
+
+    return this.llm.getJSON(systemPrompt, userMessage, { temperature: 0.3 });
+  }
+
+  /**
+   * Generate a geographic activity report for a region
+   * @param {string} holonId - Region to report on
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Geographic report
+   */
+  async generateGeographicReport(holonId, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    const { lenses = ['projects', 'quests', 'events', 'resources', 'default'] } = options;
+
+    // Collect data from all lenses
+    const lensData = {};
+    for (const lens of lenses) {
+      try {
+        const data = await this.holosphere.getAll(holonId, lens);
+        if (data.length > 0) {
+          lensData[lens] = {
+            count: data.length,
+            sample: data.slice(0, 5),
+          };
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    // Get geographic context
+    let geoContext = {};
+    if (h3.isValidCell(holonId)) {
+      const res = h3.getResolution(holonId);
+      const [lat, lng] = h3.cellToLatLng(holonId);
+      const boundary = h3.cellToBoundary(holonId);
+      const area = h3.cellArea(holonId, 'km2');
+
+      geoContext = {
+        resolution: res,
+        center: { lat, lng },
+        areaKm2: area,
+        vertexCount: boundary.length,
+      };
+    }
+
+    const systemPrompt = `You are a regional activity reporter. Generate a comprehensive report on geographic activity in this H3 region.
+
+Region: ${holonId}
+Geographic context: ${JSON.stringify(geoContext, null, 2)}
+Data available in ${Object.keys(lensData).length} categories
+
+Generate a report covering:
+1. Executive summary
+2. Activity overview by category
+3. Key highlights and achievements
+4. Geographic patterns
+5. Opportunities and challenges
+6. Recommendations
+
+Return JSON:
+{
+  "title": "Region Report Title",
+  "executiveSummary": "2-3 sentence overview",
+  "activityOverview": {
+    "totalItems": n,
+    "categorySummaries": {"lens": "summary"}
+  },
+  "highlights": [
+    {"title": "highlight", "description": "details", "category": "lens"}
+  ],
+  "geographicPatterns": ["pattern1"],
+  "strengths": ["strength1"],
+  "challenges": ["challenge1"],
+  "opportunities": ["opportunity1"],
+  "recommendations": [
+    {"priority": "high|medium|low", "action": "what to do", "rationale": "why"}
+  ],
+  "metrics": {
+    "activityLevel": "high|medium|low",
+    "diversity": "high|medium|low",
+    "growth": "growing|stable|declining"
+  }
+}`;
+
+    const report = await this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(lensData, null, 2),
+      { temperature: 0.4, maxTokens: 2000 }
+    );
+
+    return {
+      holonId,
+      geoContext,
+      lensesAnalyzed: Object.keys(lensData),
+      totalItems: Object.values(lensData).reduce((sum, l) => sum + l.count, 0),
+      report,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Find geographic clusters of related items
+   * @param {string} holonId - Region to analyze
+   * @param {string} lensName - Lens
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Geographic clusters
+   */
+  async findGeographicClusters(holonId, lensName, options = {}) {
+    if (!this.holosphere) {
+      throw new Error('HoloSphere instance required');
+    }
+
+    if (!h3.isValidCell(holonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const { clusterResolution = null } = options;
+    const currentRes = h3.getResolution(holonId);
+    const targetRes = clusterResolution || Math.min(currentRes + 1, 15);
+
+    // Get data from children at cluster resolution
+    const children = h3.cellToChildren(holonId, targetRes);
+    const cellData = {};
+
+    for (const child of children) {
+      try {
+        const data = await this.holosphere.getAll(child, lensName);
+        if (data.length > 0) {
+          cellData[child] = data;
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    if (Object.keys(cellData).length < 2) {
+      return {
+        holonId,
+        clusters: [],
+        message: 'Not enough data for clustering',
+      };
+    }
+
+    const systemPrompt = `You are a geographic clustering expert. Find thematic clusters in this spatial data.
+
+Region: ${holonId}
+Resolution analyzed: ${targetRes}
+Cells with data: ${Object.keys(cellData).length}
+
+Identify:
+1. Thematic clusters (cells with similar content)
+2. Activity clusters (cells with related activities)
+3. Isolated cells (unique content)
+4. Potential connections between clusters
+
+Return JSON:
+{
+  "clusters": [
+    {
+      "name": "cluster name",
+      "theme": "what unifies this cluster",
+      "cells": ["cell_id1", "cell_id2"],
+      "strength": 0.0-1.0,
+      "characteristics": ["char1"]
+    }
+  ],
+  "isolatedCells": [
+    {"cellId": "id", "uniqueAspect": "what makes it unique"}
+  ],
+  "interClusterConnections": [
+    {"cluster1": "name", "cluster2": "name", "connection": "how related"}
+  ],
+  "spatialPatterns": ["pattern1"],
+  "recommendations": ["rec1"]
+}`;
+
+    const analysis = await this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(cellData, null, 2),
+      { temperature: 0.4 }
+    );
+
+    return {
+      holonId,
+      lensName,
+      clusterResolution: targetRes,
+      cellsAnalyzed: Object.keys(cellData).length,
+      analysis,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Calculate and explain geographic impact of an item
+   * @param {Object} item - Item to analyze
+   * @param {string} holonId - Item's holon
+   * @param {string} lensName - Lens
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Impact analysis
+   */
+  async analyzeGeographicImpact(item, holonId, lensName, options = {}) {
+    if (!h3.isValidCell(holonId)) {
+      throw new Error('Invalid H3 cell');
+    }
+
+    const res = h3.getResolution(holonId);
+    const [lat, lng] = h3.cellToLatLng(holonId);
+    const area = h3.cellArea(holonId, 'km2');
+
+    // Get parent info for context
+    let parentContext = null;
+    if (res > 0) {
+      const parent = h3.cellToParent(holonId, Math.max(0, res - 2));
+      const parentArea = h3.cellArea(parent, 'km2');
+      parentContext = {
+        holon: parent,
+        resolution: res - 2,
+        areaKm2: parentArea,
+      };
+    }
+
+    const systemPrompt = `You are a geographic impact analyst. Analyze the geographic reach and impact of this item.
+
+Item location: ${holonId}
+Resolution: ${res}
+Center: ${lat.toFixed(4)}, ${lng.toFixed(4)}
+Area: ${area.toFixed(2)} km²
+
+${parentContext ? `Broader region: ${parentContext.areaKm2.toFixed(2)} km²` : ''}
+
+Analyze:
+1. Direct impact area (immediate cell)
+2. Indirect impact area (spillover effects)
+3. Potential reach (if expanded)
+4. Geographic barriers/enablers
+5. Network effects
+
+Return JSON:
+{
+  "directImpact": {
+    "areaKm2": n,
+    "description": "direct impact area",
+    "affectedPopulation": "estimate or N/A"
+  },
+  "indirectImpact": {
+    "estimatedReach": n,
+    "mechanisms": ["how impact spreads"],
+    "neighboringAreas": ["affected areas"]
+  },
+  "potentialReach": {
+    "ifExpanded": {
+      "maxAreaKm2": n,
+      "optimalResolution": n,
+      "limitingFactors": ["factor1"]
+    }
+  },
+  "geographicFactors": {
+    "enablers": ["what helps geographic spread"],
+    "barriers": ["what limits spread"]
+  },
+  "impactScore": {
+    "local": 0.0-1.0,
+    "regional": 0.0-1.0,
+    "network": 0.0-1.0
+  },
+  "recommendations": ["how to increase impact"],
+  "summary": "impact overview"
+}`;
+
+    return this.llm.getJSON(
+      systemPrompt,
+      JSON.stringify(item, null, 2),
+      { temperature: 0.3 }
+    );
+  }
+}
+
+export default H3AI;