holosphere 1.1.20 → 2.0.0-alpha1

package/tests/unit/ai/h3-ai.test.js

@@ -0,0 +1,458 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { H3AI } from '../../../src/ai/h3-ai.js';
+
+// Mock h3-js
+vi.mock('h3-js', () => ({
+  isValidCell: vi.fn().mockReturnValue(true),
+  getResolution: vi.fn().mockReturnValue(7),
+  cellToParent: vi.fn().mockReturnValue('parent_cell'),
+  cellToChildren: vi.fn().mockReturnValue(['child1', 'child2', 'child3']),
+  gridDisk: vi.fn().mockReturnValue(['center', 'neighbor1', 'neighbor2']),
+  cellToLatLng: vi.fn().mockReturnValue([41.9028, 12.4964]),
+  cellToBoundary: vi.fn().mockReturnValue([[0, 0], [0, 1], [1, 1], [1, 0]]),
+  cellArea: vi.fn().mockReturnValue(5.16)
+}));
+
+describe('Unit: H3AI', () => {
+  let h3ai;
+  let mockLLM;
+  let mockHolosphere;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    mockLLM = {
+      getJSON: vi.fn()
+    };
+
+    mockHolosphere = {
+      getAll: vi.fn().mockResolvedValue([])
+    };
+
+    h3ai = new H3AI(mockLLM, mockHolosphere);
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with LLM service', () => {
+      const h = new H3AI(mockLLM);
+      expect(h.llm).toBe(mockLLM);
+      expect(h.holosphere).toBeNull();
+    });
+
+    it('should accept optional HoloSphere instance', () => {
+      expect(h3ai.holosphere).toBe(mockHolosphere);
+    });
+  });
+
+  describe('setHoloSphere', () => {
+    it('should set HoloSphere instance', () => {
+      const h = new H3AI(mockLLM);
+      h.setHoloSphere(mockHolosphere);
+      expect(h.holosphere).toBe(mockHolosphere);
+    });
+  });
+
+  describe('suggestResolution', () => {
+    it('should suggest optimal H3 resolution', async () => {
+      mockLLM.getJSON.mockResolvedValue({
+        recommendedResolution: 8,
+        reasoning: 'Project scope covers neighborhood area',
+        alternativeResolutions: [
+          { resolution: 7, useCase: 'Broader community' },
+          { resolution: 9, useCase: 'More focused blocks' }
+        ],
+        geographicScope: '~1 km area',
+        scaleSuggestions: {
+          expansion: { resolution: 6, reason: 'Regional collaboration' },
+          contraction: { resolution: 9, reason: 'Local focus' }
+        }
+      });
+
+      const item = { title: 'Neighborhood Garden Project', scope: 'local' };
+      const result = await h3ai.suggestResolution(item);
+
+      expect(result.recommendedResolution).toBe(8);
+      expect(result.reasoning).toBeDefined();
+      expect(result.alternativeResolutions).toHaveLength(2);
+    });
+
+    it('should include current resolution in prompt when provided', async () => {
+      mockLLM.getJSON.mockResolvedValue({ recommendedResolution: 7 });
+
+      await h3ai.suggestResolution({ title: 'Project' }, { currentResolution: 5 });
+
+      const call = mockLLM.getJSON.mock.calls[0];
+      expect(call[0]).toContain('Current resolution: 5');
+    });
+
+    it('should include context when provided', async () => {
+      mockLLM.getJSON.mockResolvedValue({ recommendedResolution: 7 });
+
+      await h3ai.suggestResolution({ title: 'Project' }, { context: { similarProjects: 10 } });
+
+      const call = mockLLM.getJSON.mock.calls[0];
+      expect(call[0]).toContain('similarProjects');
+    });
+  });
+
+  describe('analyzeDistribution', () => {
+    it('should analyze data distribution across H3 cells', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }, { id: 2 }])  // parent
+        .mockResolvedValueOnce([{ id: 3 }])            // child1
+        .mockResolvedValueOnce([])                      // child2
+        .mockResolvedValueOnce([{ id: 4 }]);           // child3
+
+      mockLLM.getJSON.mockResolvedValue({
+        distribution: { pattern: 'clustered', density: 'medium', coverage: 0.6 },
+        hotspots: [{ holonId: 'child1', reason: 'Most activity' }],
+        gaps: [{ description: 'Child2 area', suggestedAction: 'Outreach' }],
+        clusters: [{ theme: 'Active areas', holons: ['child1', 'child3'] }],
+        recommendations: ['Expand to child2'],
+        summary: 'Moderate distribution with gaps'
+      });
+
+      const result = await h3ai.analyzeDistribution('holon1', 'projects');
+
+      expect(result.holonId).toBe('holon1');
+      expect(result.parentDataCount).toBe(2);
+      expect(result.analysis.distribution.pattern).toBe('clustered');
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.analyzeDistribution('holon', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+
+    it('should skip children analysis when includeChildren is false', async () => {
+      mockHolosphere.getAll.mockResolvedValue([{ id: 1 }]);
+      mockLLM.getJSON.mockResolvedValue({ distribution: {} });
+
+      await h3ai.analyzeDistribution('holon1', 'lens', { includeChildren: false });
+
+      expect(mockHolosphere.getAll).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('findNeighborRelevance', () => {
+    it('should find relevant data from neighboring cells', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1, title: 'Center item' }])
+        .mockResolvedValueOnce([{ id: 2, title: 'Neighbor item' }])
+        .mockResolvedValueOnce([]);
+
+      mockLLM.getJSON.mockResolvedValue({
+        relevantNeighbors: [
+          {
+            holonId: 'neighbor1',
+            relevanceScore: 0.8,
+            relevantItems: [{ id: 2, reason: 'Similar topic' }],
+            collaborationPotential: 'High potential for collaboration'
+          }
+        ],
+        crossBoundaryOpportunities: [
+          { description: 'Joint project', involvedHolons: ['center', 'neighbor1'] }
+        ],
+        geographicPatterns: ['Activity cluster'],
+        summary: 'Strong neighbor relevance'
+      });
+
+      const result = await h3ai.findNeighborRelevance('center', 'projects');
+
+      expect(result.holonId).toBe('center');
+      expect(result.analysis.relevantNeighbors).toHaveLength(1);
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.findNeighborRelevance('holon', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+
+    it('should filter by relevance threshold', async () => {
+      mockHolosphere.getAll.mockResolvedValue([{ id: 1 }]);
+
+      mockLLM.getJSON.mockResolvedValue({
+        relevantNeighbors: [
+          { holonId: 'n1', relevanceScore: 0.9 },
+          { holonId: 'n2', relevanceScore: 0.3 }
+        ]
+      });
+
+      const result = await h3ai.findNeighborRelevance('center', 'lens', { relevanceThreshold: 0.5 });
+
+      expect(result.analysis.relevantNeighbors).toHaveLength(1);
+    });
+
+    it('should return empty if no neighbor data', async () => {
+      mockHolosphere.getAll.mockResolvedValue([{ id: 1 }]);
+
+      // Center has data, neighbors don't
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }])
+        .mockResolvedValue([]);
+
+      const result = await h3ai.findNeighborRelevance('center', 'lens');
+
+      expect(result.neighbors).toEqual([]);
+    });
+  });
+
+  describe('suggestGeographicScope', () => {
+    it('should suggest expansion or contraction', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }])   // parent
+        .mockResolvedValueOnce([{ id: 2 }]);  // child
+
+      mockLLM.getJSON.mockResolvedValue({
+        currentScopeAssessment: { appropriate: false, reasoning: 'Too narrow' },
+        expansionRecommendation: {
+          recommended: true,
+          targetResolution: 6,
+          reasoning: 'Project has regional impact',
+          benefits: ['More visibility'],
+          risks: ['Diluted focus']
+        },
+        contractionRecommendation: {
+          recommended: false,
+          targetResolution: 8,
+          reasoning: 'Already focused',
+          benefits: [],
+          risks: []
+        },
+        optimalAction: 'expand',
+        summary: 'Consider expanding scope'
+      });
+
+      const result = await h3ai.suggestGeographicScope(
+        { title: 'Regional Project' },
+        'current_cell',
+        'projects'
+      );
+
+      expect(result.optimalAction).toBe('expand');
+      expect(result.expansionRecommendation.recommended).toBe(true);
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.suggestGeographicScope({}, 'cell', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+  });
+
+  describe('analyzeCoverage', () => {
+    it('should analyze coverage gaps in region', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }])  // child1
+        .mockResolvedValueOnce([])           // child2
+        .mockResolvedValueOnce([{ id: 2 }]); // child3
+
+      mockLLM.getJSON.mockResolvedValue({
+        coverageScore: 0.67,
+        coverageQuality: 'moderate',
+        patterns: { type: 'scattered', description: 'Patchy coverage' },
+        gaps: { count: 1, significance: 'medium', likelyReasons: ['New area'] },
+        recommendations: [{ action: 'Outreach', priority: 'high' }],
+        summary: 'Moderate coverage with gaps'
+      });
+
+      const result = await h3ai.analyzeCoverage('parent_cell', 'projects');
+
+      expect(result.coverage.ratio).toBeCloseTo(0.67, 1);
+      expect(result.analysis.coverageQuality).toBe('moderate');
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.analyzeCoverage('cell', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+  });
+
+  describe('crossResolutionInsights', () => {
+    it('should find patterns across H3 resolutions', async () => {
+      mockHolosphere.getAll.mockResolvedValue([{ id: 1 }]);
+
+      mockLLM.getJSON.mockResolvedValue({
+        scalePatterns: [
+          { pattern: 'Local clustering', visibleAt: [8, 9], significance: 'Community focus' }
+        ],
+        themeEvolution: {
+          localThemes: ['Gardening'],
+          regionalThemes: ['Food security'],
+          consistentThemes: ['Sustainability']
+        },
+        optimalResolutions: {
+          forCollaboration: 7,
+          forResources: 8,
+          forCommunity: 9,
+          reasoning: 'Different scales for different needs'
+        },
+        insights: ['Multi-scale approach recommended'],
+        recommendations: ['Focus on resolution 8 for main activities'],
+        summary: 'Rich multi-scale patterns'
+      });
+
+      const result = await h3ai.crossResolutionInsights('cell', 'projects');
+
+      expect(result.scalePatterns).toBeDefined();
+      expect(result.optimalResolutions).toBeDefined();
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.crossResolutionInsights('cell', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+  });
+
+  describe('suggestMigration', () => {
+    it('should suggest item migration between cells', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 'nearby', title: 'Similar project' }])
+        .mockResolvedValueOnce([{ id: 'parent', title: 'Parent data' }]);
+
+      mockLLM.getJSON.mockResolvedValue({
+        currentFit: { score: 0.5, reasoning: 'Marginal fit' },
+        migrationRecommended: true,
+        suggestedDestinations: [
+          {
+            holonId: 'neighbor1',
+            fitScore: 0.9,
+            reasoning: 'Better thematic match',
+            benefits: ['More visibility'],
+            drawbacks: ['Smaller community']
+          }
+        ],
+        stayReasons: ['Established presence'],
+        moveReasons: ['Better fit elsewhere'],
+        recommendation: 'move',
+        summary: 'Consider moving to neighbor1'
+      });
+
+      const result = await h3ai.suggestMigration(
+        { id: 'item1', title: 'Project' },
+        'current_cell',
+        'projects'
+      );
+
+      expect(result.migrationRecommended).toBe(true);
+      expect(result.recommendation).toBe('move');
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.suggestMigration({}, 'cell', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+  });
+
+  describe('generateGeographicReport', () => {
+    it('should generate comprehensive geographic report', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }])  // projects
+        .mockResolvedValueOnce([{ id: 2 }])  // quests
+        .mockResolvedValueOnce([]);          // events
+
+      mockLLM.getJSON.mockResolvedValue({
+        title: 'Region Report',
+        executiveSummary: 'Active region with 2 items',
+        activityOverview: { totalItems: 2, categorySummaries: { projects: '1 project' } },
+        highlights: [{ title: 'Growth', description: 'Increasing activity', category: 'projects' }],
+        geographicPatterns: ['Central clustering'],
+        strengths: ['Active community'],
+        challenges: ['Limited resources'],
+        opportunities: ['Expansion potential'],
+        recommendations: [{ priority: 'high', action: 'Recruit', rationale: 'Grow team' }],
+        metrics: { activityLevel: 'medium', diversity: 'low', growth: 'growing' }
+      });
+
+      const result = await h3ai.generateGeographicReport('cell');
+
+      expect(result.holonId).toBe('cell');
+      expect(result.geoContext).toBeDefined();
+      expect(result.report.title).toBe('Region Report');
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.generateGeographicReport('cell'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+  });
+
+  describe('findGeographicClusters', () => {
+    it('should find thematic clusters in spatial data', async () => {
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1, theme: 'A' }])
+        .mockResolvedValueOnce([{ id: 2, theme: 'A' }])
+        .mockResolvedValueOnce([{ id: 3, theme: 'B' }]);
+
+      mockLLM.getJSON.mockResolvedValue({
+        clusters: [
+          { name: 'Theme A cluster', theme: 'A', cells: ['child1', 'child2'], strength: 0.9 }
+        ],
+        isolatedCells: [{ cellId: 'child3', uniqueAspect: 'Different theme' }],
+        interClusterConnections: [],
+        spatialPatterns: ['Eastern concentration'],
+        recommendations: ['Connect isolated cell']
+      });
+
+      const result = await h3ai.findGeographicClusters('parent', 'lens');
+
+      expect(result.analysis.clusters).toHaveLength(1);
+      expect(result.analysis.isolatedCells).toHaveLength(1);
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const h = new H3AI(mockLLM);
+
+      await expect(h.findGeographicClusters('cell', 'lens'))
+        .rejects.toThrow('HoloSphere instance required');
+    });
+
+    it('should return message if not enough data', async () => {
+      // Only one child has data (cellToChildren returns 3, we need less than 2 with data)
+      mockHolosphere.getAll
+        .mockResolvedValueOnce([{ id: 1 }])  // child1 has data
+        .mockResolvedValueOnce([])           // child2 empty
+        .mockResolvedValueOnce([]);          // child3 empty
+
+      const result = await h3ai.findGeographicClusters('parent', 'lens');
+
+      expect(result.message).toBe('Not enough data for clustering');
+    });
+  });
+
+  describe('analyzeGeographicImpact', () => {
+    it('should analyze geographic impact of item', async () => {
+      mockLLM.getJSON.mockResolvedValue({
+        directImpact: { areaKm2: 5.16, description: 'Immediate neighborhood', affectedPopulation: '~500' },
+        indirectImpact: { estimatedReach: 20, mechanisms: ['Word of mouth'], neighboringAreas: ['Area B'] },
+        potentialReach: { ifExpanded: { maxAreaKm2: 50, optimalResolution: 5, limitingFactors: ['Resources'] } },
+        geographicFactors: { enablers: ['Good transport'], barriers: ['Physical barriers'] },
+        impactScore: { local: 0.8, regional: 0.4, network: 0.6 },
+        recommendations: ['Expand to adjacent areas'],
+        summary: 'Strong local impact with expansion potential'
+      });
+
+      const result = await h3ai.analyzeGeographicImpact(
+        { id: 'item1', title: 'Community Project' },
+        'cell',
+        'projects'
+      );
+
+      expect(result.directImpact.areaKm2).toBe(5.16);
+      expect(result.impactScore.local).toBe(0.8);
+    });
+  });
+});