@smartnet360/svelte-components 0.0.101 → 0.0.103

package/dist/core/CoverageMap/ai/AITools.js

@@ -0,0 +1,380 @@
+/**
+ * AI Integration Layer - Tool-Callable Functions
+ *
+ * This module provides functions designed to be called by AI assistants
+ * (e.g., ChatGPT) for coverage analysis and recommendations.
+ *
+ * Design principles:
+ * - Functions are stateless and pure where possible
+ * - Inputs and outputs are JSON-serializable
+ * - Each function has clear purpose and documentation
+ * - Error handling returns structured error objects
+ *
+ * Phase 2 Implementation Note:
+ * These functions will be exposed via a tool registry that ChatGPT
+ * can call through function calling / tool use APIs.
+ */
+// ============================================================================
+// AI TOOL FUNCTIONS
+// ============================================================================
+/**
+ * Analyze coverage quality and generate recommendations
+ *
+ * This function takes coverage calculation results and generates
+ * structured analysis suitable for AI interpretation.
+ *
+ * In Phase 2, ChatGPT will call this with coverage data and receive
+ * structured metrics that it can analyze and explain in natural language.
+ *
+ * @param result - Coverage calculation result
+ * @returns Structured analysis data
+ *
+ * @example
+ * // AI will call:
+ * const analysis = analyzeCoverageQuality(coverageResult);
+ *
+ * // AI receives:
+ * {
+ *   overallQuality: "good",
+ *   coveragePercent: 78.5,
+ *   avgSignal: -82.3,
+ *   issues: ["excessive_range", "weak_avg_signal"],
+ *   metrics: { ... }
+ * }
+ *
+ * // AI interprets and responds:
+ * "Your coverage is good overall at 78.5%. However, I notice two issues:
+ *  1. Excessive range detected - consider adding downtilt to reduce interference
+ *  2. Average signal is weak at -82.3 dBm - most users will experience medium throughput"
+ */
+export function analyzeCoverageQuality(result) {
+    const stats = result.grid.stats;
+    const metrics = result.summary.metrics;
+    // Determine overall quality
+    let overallQuality;
+    if (stats.coveragePercentage >= 90 && metrics.excellentPercent >= 50) {
+        overallQuality = 'excellent';
+    }
+    else if (stats.coveragePercentage >= 70 && metrics.goodPercent + metrics.excellentPercent >= 60) {
+        overallQuality = 'good';
+    }
+    else if (stats.coveragePercentage >= 50) {
+        overallQuality = 'fair';
+    }
+    else {
+        overallQuality = 'poor';
+    }
+    // Extract issues
+    const issues = [];
+    if (stats.coveragePercentage < 60) {
+        issues.push('low_coverage');
+    }
+    if (metrics.poorPercent + metrics.fairPercent > 70) {
+        issues.push('weak_signal_dominance');
+    }
+    if (metrics.maxRange > 15) {
+        issues.push('excessive_range');
+    }
+    if (metrics.maxRange < 1) {
+        issues.push('undershooting');
+    }
+    if (metrics.avgSignal < -90) {
+        issues.push('weak_avg_signal');
+    }
+    if (metrics.excellentPercent < 10) {
+        issues.push('minimal_excellent_coverage');
+    }
+    // Sector breakdown
+    const sectorBreakdown = Object.entries(stats.sectorStats || {}).map(([id, stat]) => ({
+        sectorId: id,
+        maxRangeKm: stat.maxRangeKm,
+        avgSignalDbm: stat.avgSignalDbm,
+        coverageAreaKm2: stat.coverageAreaKm2
+    }));
+    return {
+        overallQuality,
+        coveragePercent: stats.coveragePercentage,
+        avgSignal: metrics.avgSignal,
+        maxRange: metrics.maxRange,
+        issues,
+        metrics,
+        sectorBreakdown
+    };
+}
+/**
+ * Generate optimization suggestions
+ *
+ * Based on coverage analysis, generates specific parameter adjustment
+ * recommendations that can be presented to the user.
+ *
+ * In Phase 2, AI will use this to generate specific, actionable recommendations.
+ *
+ * @param result - Coverage result
+ * @returns Array of recommendations
+ */
+export function generateOptimizationSuggestions(result) {
+    const analysis = analyzeCoverageQuality(result);
+    const recommendations = [];
+    const config = result.config;
+    // Check each issue and generate recommendations
+    for (const issue of analysis.issues) {
+        switch (issue) {
+            case 'excessive_range':
+                // Recommend increasing downtilt
+                for (const sector of config.site.sectors) {
+                    if (sector.enabled) {
+                        const currentTilt = sector.mechanicalTilt + sector.electricalTilt;
+                        recommendations.push({
+                            sectorId: sector.sectorId,
+                            parameter: 'tilt',
+                            currentValue: currentTilt,
+                            suggestedValue: currentTilt + 3,
+                            reasoning: 'Range exceeds 15km which may cause interference to neighboring sites. ' +
+                                'Increasing downtilt will focus energy closer to the site.',
+                            expectedImprovement: 'Reduced interference, better signal quality nearby',
+                            priority: 'high'
+                        });
+                    }
+                }
+                break;
+            case 'weak_signal_dominance':
+                // Recommend increasing power or reducing tilt
+                for (const sector of config.site.sectors) {
+                    if (sector.enabled && sector.txPower < 46) {
+                        recommendations.push({
+                            sectorId: sector.sectorId,
+                            parameter: 'power',
+                            currentValue: sector.txPower,
+                            suggestedValue: Math.min(sector.txPower + 3, 46),
+                            reasoning: 'Over 70% of coverage has weak signal. Increasing power will improve signal strength.',
+                            expectedImprovement: '+3dB signal strength across coverage area',
+                            priority: 'high'
+                        });
+                    }
+                }
+                break;
+            case 'undershooting':
+                // Recommend reducing tilt or increasing power
+                for (const sector of config.site.sectors) {
+                    if (sector.enabled) {
+                        const currentTilt = sector.mechanicalTilt + sector.electricalTilt;
+                        if (currentTilt > 3) {
+                            recommendations.push({
+                                sectorId: sector.sectorId,
+                                parameter: 'tilt',
+                                currentValue: currentTilt,
+                                suggestedValue: Math.max(currentTilt - 3, 0),
+                                reasoning: 'Coverage range is very short (< 1km). Reducing tilt will extend coverage.',
+                                expectedImprovement: 'Extended coverage range',
+                                priority: 'high'
+                            });
+                        }
+                    }
+                }
+                break;
+            case 'low_coverage':
+                // Recommend antenna height or power increase
+                for (const sector of config.site.sectors) {
+                    if (sector.enabled) {
+                        recommendations.push({
+                            sectorId: sector.sectorId,
+                            parameter: 'height',
+                            currentValue: sector.position.height,
+                            suggestedValue: sector.position.height + 10,
+                            reasoning: 'Overall coverage is low. Increasing antenna height will extend coverage.',
+                            expectedImprovement: 'Wider coverage area',
+                            priority: 'medium'
+                        });
+                    }
+                }
+                break;
+        }
+    }
+    return recommendations;
+}
+/**
+ * Compare two coverage scenarios
+ *
+ * Useful for before/after analysis when user changes parameters.
+ *
+ * @param before - Coverage before changes
+ * @param after - Coverage after changes
+ * @returns Comparison analysis
+ */
+export function compareCoverageScenarios(before, after) {
+    const beforeAnalysis = analyzeCoverageQuality(before);
+    const afterAnalysis = analyzeCoverageQuality(after);
+    const coverageChange = afterAnalysis.coveragePercent - beforeAnalysis.coveragePercent;
+    const signalChange = afterAnalysis.avgSignal - beforeAnalysis.avgSignal;
+    const rangeChange = afterAnalysis.maxRange - beforeAnalysis.maxRange;
+    const improvements = [];
+    const degradations = [];
+    if (coverageChange > 5)
+        improvements.push(`Coverage increased by ${coverageChange.toFixed(1)}%`);
+    if (coverageChange < -5)
+        degradations.push(`Coverage decreased by ${Math.abs(coverageChange).toFixed(1)}%`);
+    if (signalChange > 3)
+        improvements.push(`Average signal improved by ${signalChange.toFixed(1)} dB`);
+    if (signalChange < -3)
+        degradations.push(`Average signal degraded by ${Math.abs(signalChange).toFixed(1)} dB`);
+    // Range change is contextual
+    if (Math.abs(rangeChange) > 1) {
+        if (beforeAnalysis.maxRange > 15 && rangeChange < 0) {
+            improvements.push(`Range reduced from ${beforeAnalysis.maxRange.toFixed(1)}km to ${afterAnalysis.maxRange.toFixed(1)}km (reduces interference)`);
+        }
+        else if (beforeAnalysis.maxRange < 5 && rangeChange > 0) {
+            improvements.push(`Range increased from ${beforeAnalysis.maxRange.toFixed(1)}km to ${afterAnalysis.maxRange.toFixed(1)}km (extends coverage)`);
+        }
+    }
+    // Generate summary
+    let summary;
+    if (improvements.length > degradations.length) {
+        summary = 'Overall improvement';
+    }
+    else if (degradations.length > improvements.length) {
+        summary = 'Overall degradation';
+    }
+    else {
+        summary = 'Mixed results - some improvements, some trade-offs';
+    }
+    return {
+        coverageChange,
+        signalChange,
+        rangeChange,
+        improvements,
+        degradations,
+        summary
+    };
+}
+/**
+ * Extract key metrics for AI analysis
+ *
+ * Flattens coverage result into simple key-value pairs
+ * that are easy for AI to interpret.
+ *
+ * @param result - Coverage result
+ * @returns Flat metrics object
+ */
+export function extractAIMetrics(result) {
+    const stats = result.grid.stats;
+    const config = result.config;
+    return {
+        // Coverage metrics
+        coverage_percent: stats.coveragePercentage,
+        coverage_area_km2: stats.coveredAreaKm2,
+        total_area_km2: stats.totalAreaKm2,
+        // Quality distribution
+        excellent_percent: (stats.excellentAreaKm2 / stats.totalAreaKm2) * 100,
+        good_percent: (stats.goodAreaKm2 / stats.totalAreaKm2) * 100,
+        fair_percent: (stats.fairAreaKm2 / stats.totalAreaKm2) * 100,
+        poor_percent: (stats.poorAreaKm2 / stats.totalAreaKm2) * 100,
+        // Configuration
+        cell_size_m: config.gridSettings.cellSizeMeters,
+        max_radius_km: config.gridSettings.maxRadiusKm,
+        path_loss_model: config.gridSettings.pathLossModel,
+        // Performance
+        calculation_time_s: result.calculationTimeMs / 1000,
+        grid_cells: result.grid.rows * result.grid.cols,
+        // Site info
+        site_name: config.site.siteName,
+        sector_count: config.site.sectors.filter((s) => s.enabled).length
+    };
+}
+// ============================================================================
+// AI TOOL REGISTRY
+// ============================================================================
+/**
+ * Registry of all AI-callable tools
+ *
+ * In Phase 2, this will be used to expose functions to ChatGPT.
+ * Each entry describes the function, its parameters, and its purpose.
+ */
+export const AI_TOOLS = [
+    {
+        name: 'analyze_coverage_quality',
+        description: 'Analyze coverage calculation results and return structured quality assessment with issues and metrics',
+        parameters: {
+            type: 'object',
+            properties: {
+                coverageResult: {
+                    type: 'object',
+                    description: 'Complete coverage calculation result object'
+                }
+            },
+            required: ['coverageResult']
+        },
+        execute: async (params) => analyzeCoverageQuality(params.coverageResult)
+    },
+    {
+        name: 'generate_optimization_suggestions',
+        description: 'Generate specific parameter adjustment recommendations to improve coverage',
+        parameters: {
+            type: 'object',
+            properties: {
+                coverageResult: {
+                    type: 'object',
+                    description: 'Coverage result to analyze'
+                }
+            },
+            required: ['coverageResult']
+        },
+        execute: async (params) => generateOptimizationSuggestions(params.coverageResult)
+    },
+    {
+        name: 'compare_coverage_scenarios',
+        description: 'Compare two coverage scenarios (before/after) and identify improvements or degradations',
+        parameters: {
+            type: 'object',
+            properties: {
+                before: {
+                    type: 'object',
+                    description: 'Coverage result before changes'
+                },
+                after: {
+                    type: 'object',
+                    description: 'Coverage result after changes'
+                }
+            },
+            required: ['before', 'after']
+        },
+        execute: async (params) => compareCoverageScenarios(params.before, params.after)
+    },
+    {
+        name: 'extract_ai_metrics',
+        description: 'Extract flat key-value metrics from coverage result for easy AI interpretation',
+        parameters: {
+            type: 'object',
+            properties: {
+                coverageResult: {
+                    type: 'object',
+                    description: 'Coverage result to extract metrics from'
+                }
+            },
+            required: ['coverageResult']
+        },
+        execute: async (params) => extractAIMetrics(params.coverageResult)
+    }
+];
+/**
+ * Get AI tool by name
+ *
+ * @param name - Tool name
+ * @returns Tool function or undefined
+ */
+export function getAITool(name) {
+    return AI_TOOLS.find((tool) => tool.name === name);
+}
+/**
+ * Execute AI tool by name
+ *
+ * @param name - Tool name
+ * @param params - Tool parameters
+ * @returns Tool result
+ */
+export async function executeAITool(name, params) {
+    const tool = getAITool(name);
+    if (!tool) {
+        throw new Error(`AI tool not found: ${name}`);
+    }
+    return tool.execute(params);
+}

package/dist/core/CoverageMap/core/CoverageCalculator.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Coverage Calculator - Main Orchestrator
+ *
+ * This is the main entry point for coverage calculations.
+ * It orchestrates all components and provides a clean API for:
+ * - Single sector coverage calculation
+ * - Multi-sector site coverage
+ * - Progress reporting
+ * - AI-ready result formatting
+ *
+ * Usage:
+ *   const calculator = new CoverageCalculator();
+ *   const result = await calculator.calculate(config, progressCallback);
+ *   // Result includes grid, statistics, and AI-ready summary
+ */
+import type { CoverageConfig, CoverageResult, ProgressCallback, SiteConfiguration } from '../types';
+/**
+ * Main Coverage Calculator
+ *
+ * Provides high-level API for coverage calculations with:
+ * - Configuration validation
+ * - Progress reporting
+ * - Error handling
+ * - Result formatting
+ * - AI-ready summaries
+ */
+export declare class CoverageCalculator {
+    /**
+     * Calculate coverage for a site configuration
+     *
+     * This is the main calculation method. It:
+     * 1. Validates configuration
+     * 2. Determines if single or multi-sector
+     * 3. Performs calculation
+     * 4. Generates statistics and summary
+     * 5. Formats result for consumption (including AI)
+     *
+     * @param config - Complete coverage configuration
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to complete coverage result
+     *
+     * @example
+     * const calculator = new CoverageCalculator();
+     * const result = await calculator.calculate({
+     *   site: siteConfig,
+     *   gridSettings: { cellSizeMeters: 50, maxRadiusKm: 10, ... },
+     *   signalThresholds: { excellent: -70, good: -85, ... },
+     *   calculateInterference: true
+     * }, (progress) => {
+     *   console.log(`Progress: ${progress.progress}% - ${progress.message}`);
+     * });
+     *
+     * // Access results
+     * console.log(`Coverage: ${result.grid.stats.coveragePercentage}%`);
+     * console.log(`Summary: ${result.summary.description}`);
+     * // Pass to AI for analysis
+     * const aiAnalysis = await analyzeWithAI(result);
+     */
+    calculate(config: CoverageConfig, onProgress?: ProgressCallback): Promise<CoverageResult>;
+    /**
+     * Validate configuration before calculation
+     *
+     * Checks for common configuration errors:
+     * - Invalid distances (negative, zero, too large)
+     * - Invalid frequencies (outside valid ranges)
+     * - Invalid antenna heights
+     * - Missing required data
+     *
+     * Throws descriptive errors if validation fails.
+     *
+     * @param config - Configuration to validate
+     * @throws Error if configuration is invalid
+     */
+    private validateConfiguration;
+    /**
+     * Generate human-readable and AI-ready summary
+     *
+     * Creates a comprehensive summary of coverage results including:
+     * - Description: Human-readable text summary
+     * - Issues: List of detected problems/warnings
+     * - Metrics: Key numerical metrics for AI analysis
+     *
+     * This summary is designed to be consumed by:
+     * 1. Human users (description text)
+     * 2. UI components (structured data)
+     * 3. AI analysis tools (metrics + issues)
+     *
+     * @param config - Original configuration
+     * @param grid - Calculation results
+     * @param sectorCount - Number of sectors calculated
+     * @returns Summary object
+     */
+    private generateSummary;
+    /**
+     * Create human-readable description
+     */
+    private createDescription;
+    /**
+     * Detect common issues and warnings
+     */
+    private detectIssues;
+}
+/**
+ * Quick coverage calculation (simplified API)
+ *
+ * For simple use cases where you don't need full configuration control.
+ * Uses sensible defaults for most parameters.
+ *
+ * @param site - Site configuration
+ * @param options - Optional overrides
+ * @returns Coverage result
+ *
+ * @example
+ * const result = await quickCalculate(mySite, {
+ *   cellSizeMeters: 100,  // Faster calculation
+ *   maxRadiusKm: 5        // Smaller area
+ * });
+ */
+export declare function quickCalculate(site: SiteConfiguration, options?: {
+    cellSizeMeters?: number;
+    maxRadiusKm?: number;
+    pathLossModel?: 'free-space' | 'hata-urban' | 'hata-suburban' | 'cost231';
+}): Promise<CoverageResult>;
+/**
+ * Calculate coverage and export for AI analysis
+ *
+ * Convenience function that calculates coverage and formats
+ * the result specifically for AI consumption.
+ *
+ * @param config - Coverage configuration
+ * @returns AI-ready analysis object
+ */
+export declare function calculateForAI(config: CoverageConfig): Promise<{
+    summary: string;
+    metrics: Record<string, number>;
+    issues: string[];
+    sectorData: any[];
+}>;