Update fronius-inverter extension

extensions/fronius-inverter/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Version 1.1 - {PR_MERGE_DATE}
+
+- Added comprehensive documentation with detailed JSDoc comments throughout the codebase.
+
+- **AI-Powered Analysis Tools:**
+- Added system analysis tool that provides insights about current production, consumption, and energy flow.
+- Implemented error explanation tool that interprets inverter error codes and suggests troubleshooting steps.
+- Created optimization suggestions tool that offers practical tips to improve system performance based on current data.
+- All AI tools fetch real-time data directly from the Fronius API for accurate analysis.
+
 ## [Initial Release] - 2025-03-03
 
 - **Unified Dashboard:**  

extensions/fronius-inverter/README.md

@@ -12,4 +12,19 @@ A Raycast extension to monitor your Fronius Gen24 inverter in realtime. This ext
 - **Inverter Watch (Menu Bar)**  
   - Runs in the menu bar, polling every 30 seconds for inverter errors.
   - Displays a badge with a warning emoji and error count if errors exist, or a green check if all is OK.
-  - Tap “Show Dashboard” to quickly open the full dashboard view.
+  - Tap "Show Dashboard" to quickly open the full dashboard view.
+
+- **AI-Powered Insights**
+  - **System Analysis**: Get intelligent insights about your current system state, including production efficiency, consumption patterns, and energy flow observations.
+  - **Error Explanation**: When errors occur, receive detailed explanations of what the error codes mean, potential causes, and recommended troubleshooting steps.
+  - **Optimization Suggestions**: Receive practical recommendations to optimize your solar system's performance based on real-time data.
+  - All AI features use real-time data directly from your Fronius inverter for accurate and relevant insights.
+
+## Requirements
+
+- Fronius Gen24 inverter with accessible API on your local network
+- Raycast Pro subscription (for AI features)
+
+## Configuration
+
+In the extension preferences, set the base URL of your Fronius inverter (e.g., http://192.168.0.75).

extensions/fronius-inverter/package.json

@@ -25,6 +25,52 @@
       "command": "src/watch.tsx"
     }
   ],
+  "tools": [
+    {
+      "name": "analyzeSystem",
+      "title": "Analyze Solar System",
+      "description": "Analyzes the current state of the Fronius solar system and provides insights",
+      "file": "src/tools/analyzeSystem.ts",
+      "input": "How much energy is my solar system producing right now?"
+    },
+    {
+      "name": "explainErrors",
+      "title": "Explain Inverter Errors",
+      "description": "Provides an explanation and troubleshooting steps for inverter error codes",
+      "file": "src/tools/explainErrors.ts",
+      "input": "What does error code 567 mean on my inverter?"
+    },
+    {
+      "name": "optimizationSuggestions",
+      "title": "Get Optimization Suggestions",
+      "description": "Provides optimization suggestions based on current system performance",
+      "file": "src/tools/optimizationSuggestions.ts",
+      "input": "How can I optimize my solar system performance?"
+    }
+  ],
+  "ai": {
+    "instructions": "You are an assistant for a Fronius solar inverter monitoring system. You can help users understand their solar system performance, troubleshoot errors, and provide optimization suggestions.\n\nYou have access to the following tools:\n\n1. analyzeSystem - Use this to analyze the current state of the solar system and provide insights based on power production, grid interaction, and home consumption.\n\n2. explainErrors - Use this to explain error codes from the inverter and provide troubleshooting steps.\n\n3. optimizationSuggestions - Use this to provide suggestions for optimizing energy usage and system performance.\n\nWhen users ask about their solar system, try to understand what specific information they're looking for and use the appropriate tool to help them.",
+    "evals": [
+      {
+        "name": "analyzeSystemEval",
+        "description": "Validates that system analysis provides accurate and helpful insights",
+        "file": "src/evals/analyzeSystemEval.ts",
+        "input": "How much energy is my solar system producing right now?"
+      },
+      {
+        "name": "explainErrorsEval",
+        "description": "Validates that error explanations are accurate and provide useful troubleshooting steps",
+        "file": "src/evals/explainErrorsEval.ts",
+        "input": "What does error code 567 mean on my inverter?"
+      },
+      {
+        "name": "optimizationSuggestionsEval",
+        "description": "Validates that optimization suggestions are practical and relevant to the system state",
+        "file": "src/evals/optimizationSuggestionsEval.ts",
+        "input": "How can I optimize my solar system performance?"
+      }
+    ]
+  },
   "preferences": [
     {
       "name": "baseUrl",

extensions/fronius-inverter/src/api.ts

@@ -2,6 +2,19 @@
 import { InverterInfoResponse, PowerFlowRealtimeDataResponse } from "./types";
 const _fetch = typeof fetch !== "undefined" ? fetch : require("node-fetch");
 
+/**
+ * Fetches detailed information about all connected Fronius inverters
+ *
+ * This function makes a request to the Fronius Solar API v1 GetInverterInfo endpoint,
+ * which returns comprehensive information about all inverters connected to the system.
+ * The data includes custom names, device IDs, current state, error codes, and power values.
+ *
+ * This information is used for displaying inverter status and detecting error conditions.
+ *
+ * @param {string} baseUrl - The base URL of the Fronius inverter (e.g., http://192.168.0.75)
+ * @returns {Promise<InverterInfoResponse>} A promise that resolves to the inverter information response
+ * @throws {Error} If the request fails or returns a non-OK status
+ */
 export async function fetchInverterInfo(baseUrl: string): Promise<InverterInfoResponse> {
   const url = `${baseUrl}/solar_api/v1/GetInverterInfo.cgi`;
   const response = await _fetch(url);
@@ -11,6 +24,20 @@ export async function fetchInverterInfo(baseUrl: string): Promise<InverterInfoRe
   return response.json() as Promise<InverterInfoResponse>;
 }
 
+/**
+ * Fetches real-time power flow data from the Fronius system
+ *
+ * This function makes a request to the Fronius Solar API v1 GetPowerFlowRealtimeData endpoint,
+ * which returns current power flow information for the entire system. The data includes
+ * current PV production, grid power (import/export), home consumption, battery status,
+ * and energy totals.
+ *
+ * This information is used for displaying the system overview and calculating performance metrics.
+ *
+ * @param {string} baseUrl - The base URL of the Fronius inverter (e.g., http://192.168.0.75)
+ * @returns {Promise<PowerFlowRealtimeDataResponse>} A promise that resolves to the power flow data response
+ * @throws {Error} If the request fails or returns a non-OK status
+ */
 export async function fetchPowerFlowRealtimeData(baseUrl: string): Promise<PowerFlowRealtimeDataResponse> {
   const url = `${baseUrl}/solar_api/v1/GetPowerFlowRealtimeData.fcgi`;
   const response = await _fetch(url);

extensions/fronius-inverter/src/evals/analyzeSystemEval.ts

@@ -0,0 +1,49 @@
+import { AI } from "@raycast/api";
+import analyzeSystem from "../tools/analyzeSystem";
+
+/**
+ * Evaluation for the analyzeSystem tool
+ *
+ * This evaluation validates that the system analysis provides accurate and helpful insights.
+ * It checks that the analysis:
+ * 1. Correctly interprets the current system state
+ * 2. Provides meaningful observations about production and consumption
+ * 3. Offers actionable insights based on the energy flow data
+ * 4. Maintains conciseness and clarity in the response
+ *
+ * @returns {Promise<boolean>} True if the evaluation passes, false otherwise
+ */
+export default async function analyzeSystemEval(): Promise<boolean> {
+  try {
+    // Get the analysis from the tool
+    const analysis = await analyzeSystem();
+
+    if (!analysis || analysis.trim().length === 0) {
+      console.error("Analysis returned empty result");
+      return false;
+    }
+
+    // Use Raycast AI to evaluate the quality of the analysis
+    const evaluation = await AI.ask(`
+      Evaluate this solar system analysis for accuracy, helpfulness, and actionability:
+
+      "${analysis}"
+
+      Criteria:
+      1. Does it correctly summarize the current system state?
+      2. Does it provide meaningful observations about production/consumption?
+      3. Does it offer at least one actionable insight?
+      4. Is it concise (3-4 sentences total)?
+
+      For each criterion, answer YES or NO.
+      Then provide an overall PASS or FAIL verdict.
+      A PASS requires at least 3 YES answers.
+    `);
+
+    // Check if the evaluation contains a PASS verdict
+    return evaluation.includes("PASS");
+  } catch (error) {
+    console.error("Error in analyzeSystemEval:", error);
+    return false;
+  }
+}

extensions/fronius-inverter/src/evals/explainErrorsEval.ts

@@ -0,0 +1,54 @@
+import { AI } from "@raycast/api";
+import explainErrors from "../tools/explainErrors";
+
+/**
+ * Evaluation for the explainErrors tool
+ *
+ * This evaluation validates that the error explanations are accurate and provide useful troubleshooting steps.
+ * It checks that the explanation:
+ * 1. Correctly identifies and explains the error codes
+ * 2. Provides plausible causes for the issues
+ * 3. Offers practical troubleshooting steps
+ * 4. Is clear and understandable for non-technical users
+ *
+ * @returns {Promise<boolean>} True if the evaluation passes, false otherwise
+ */
+export default async function explainErrorsEval(): Promise<boolean> {
+  try {
+    // Get the error explanation from the tool
+    const explanation = await explainErrors();
+
+    // If no errors are detected, the tool should return a confirmation message
+    if (explanation === "No errors detected. All inverters are operating normally.") {
+      return true;
+    }
+
+    if (!explanation || explanation.trim().length === 0) {
+      console.error("Error explanation returned empty result");
+      return false;
+    }
+
+    // Use Raycast AI to evaluate the quality of the error explanation
+    const evaluation = await AI.ask(`
+      Evaluate this Fronius inverter error explanation for accuracy, helpfulness, and practicality:
+
+      "${explanation}"
+
+      Criteria:
+      1. Does it clearly explain what the error means?
+      2. Does it provide plausible causes for the issue?
+      3. Does it offer practical troubleshooting steps?
+      4. Is it understandable for non-technical users?
+
+      For each criterion, answer YES or NO.
+      Then provide an overall PASS or FAIL verdict.
+      A PASS requires at least 3 YES answers.
+    `);
+
+    // Check if the evaluation contains a PASS verdict
+    return evaluation.includes("PASS");
+  } catch (error) {
+    console.error("Error in explainErrorsEval:", error);
+    return false;
+  }
+}

extensions/fronius-inverter/src/evals/optimizationSuggestionsEval.ts

@@ -0,0 +1,49 @@
+import { AI } from "@raycast/api";
+import optimizationSuggestions from "../tools/optimizationSuggestions";
+
+/**
+ * Evaluation for the optimizationSuggestions tool
+ *
+ * This evaluation validates that the optimization suggestions are practical and relevant to the system state.
+ * It checks that the suggestions:
+ * 1. Are relevant to the current system performance data
+ * 2. Are practical and actionable for homeowners
+ * 3. Provide clear benefits if implemented
+ * 4. Are specific rather than generic
+ *
+ * @returns {Promise<boolean>} True if the evaluation passes, false otherwise
+ */
+export default async function optimizationSuggestionsEval(): Promise<boolean> {
+  try {
+    // Get the optimization suggestions from the tool
+    const suggestions = await optimizationSuggestions();
+
+    if (!suggestions || suggestions.trim().length === 0) {
+      console.error("Optimization suggestions returned empty result");
+      return false;
+    }
+
+    // Use Raycast AI to evaluate the quality of the optimization suggestions
+    const evaluation = await AI.ask(`
+      Evaluate these solar system optimization suggestions for practicality and relevance:
+
+      "${suggestions}"
+
+      Criteria:
+      1. Are the suggestions relevant to the system performance data?
+      2. Are they practical and actionable for homeowners?
+      3. Do they provide clear benefits if implemented?
+      4. Are they specific rather than generic advice?
+
+      For each criterion, answer YES or NO.
+      Then provide an overall PASS or FAIL verdict.
+      A PASS requires at least 3 YES answers.
+    `);
+
+    // Check if the evaluation contains a PASS verdict
+    return evaluation.includes("PASS");
+  } catch (error) {
+    console.error("Error in optimizationSuggestionsEval:", error);
+    return false;
+  }
+}

extensions/fronius-inverter/src/tools/analyzeSystem.ts

@@ -0,0 +1,61 @@
+import { AI, getPreferenceValues } from "@raycast/api";
+import { fetchPowerFlowRealtimeData } from "../api";
+
+interface Preferences {
+  baseUrl: string;
+}
+
+/**
+ * Analyzes the current state of the Fronius solar system using AI
+ *
+ * This tool fetches real-time data directly from the Fronius inverter API and uses
+ * Raycast's AI capabilities to provide meaningful insights about the system's performance.
+ * The analysis includes information about current production, consumption patterns,
+ * grid interaction, and battery status (if available).
+ *
+ * The tool is designed to help users understand their solar system's current state
+ * at a glance and identify potential optimization opportunities or issues.
+ *
+ * @returns {Promise<string>} A detailed analysis of the system state with insights and recommendations
+ */
+export default async function analyzeSystem(): Promise<string> {
+  // Get the base URL from user preferences
+  const { baseUrl } = getPreferenceValues<Preferences>();
+
+  // Fetch the latest power flow data directly from the Fronius API
+  try {
+    const powerResponse = await fetchPowerFlowRealtimeData(baseUrl);
+    const site = powerResponse.Body.Data.Site;
+
+    // Extract and organize the relevant data for analysis
+    const data = {
+      currentPower: site.P_PV, // Current solar production in watts
+      dailyEnergy: site.E_Total || 0, // Total energy produced today in watt-hours
+      gridPower: site.P_Grid, // Grid power (negative = exporting to grid) in watts
+      loadPower: site.P_Load, // Current home consumption in watts
+      batteryPower: site.P_Akku, // Battery power (negative = charging) in watts
+      batteryStateOfCharge: site.StateOfCharge_Relative, // Battery charge level in percentage
+    };
+
+    // Use Raycast AI to analyze the data and generate insights
+    return await AI.ask(`
+      Analyze this solar system data and provide insights:
+      - Current production: ${data.currentPower}W
+      - Today's energy: ${data.dailyEnergy}Wh
+      - Grid power (negative=export): ${data.gridPower}W
+      - Home consumption: ${data.loadPower}W
+      ${data.batteryPower !== undefined ? `- Battery power (negative=charging): ${data.batteryPower}W` : ""}
+      ${data.batteryStateOfCharge !== undefined ? `- Battery charge: ${data.batteryStateOfCharge}%` : ""}
+
+      Please provide:
+      1. A brief summary of the current system state
+      2. Any notable observations (high/low production, consumption patterns)
+      3. One actionable insight based on the current energy flow
+
+      Keep it concise (3-4 sentences total).
+    `);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to fetch power flow data: ${errorMessage}`);
+  }
+}