Invoke-PowerShellFunctionAnnotation

Overview

This PowerShell function automates the process of adding descriptive annotations to other PowerShell script functions using the Google Cloud Generative AI (Gemini 1.5 Pro) API. It can process a single script or an entire directory of scripts, adding a comment block above each function definition with a concise description generated by the AI.

Key Features:

• Automated Function Annotation: Leverages the power of Gemini 1.5 Pro to understand and describe PowerShell functions.
• Single Script or Batch Processing: Can annotate a single PowerShell script file or all .ps1 files within a specified directory (including subdirectories).
• Clear Annotation Format: Adds standard PowerShell comment blocks (<# ... #>) above each function, including a "Description" field.
• Path Handling: Robustly handles file and directory paths, including those with quotes.
• Error Handling: Includes error handling for API calls and file operations.
• Informative Output: Provides a summary of the annotation process, including the number of successful and failed scripts.
• Interactive Mode: Prompts the user for necessary information like API key, source, and destination paths.

Installation

This function can be directly used within a PowerShell session or saved as a .ps1 file and then executed.

Method 1: Direct Execution in PowerShell

1. Copy the entire code block of the Invoke-PowerShellScriptAnnotation function (including the main script part).
2. Paste it directly into your PowerShell console.

Method 2: Saving as a .ps1 file

1. Copy the entire code block of the Invoke-PowerShellScriptAnnotation function (including the main script part).
2. Save it as a .ps1 file (e.g., Annotate-Scripts.ps1).
3. You can then execute the script from your PowerShell console using:

   .\Annotate-Scripts.ps1

Prerequisites

• PowerShell: This function is written in PowerShell and requires a compatible version to run.
• Google Cloud Generative AI API Key: You will need a valid API key to access the Gemini 1.5 Pro model. You can obtain this from the Google Cloud Console.
  • Ensure the Generative Language API is enabled in your Google Cloud project.
  • Create an API key with the necessary permissions.
• Network Connectivity: The script needs internet access to communicate with the Google Cloud API.

Usage

When you run the script, it will interactively prompt you for the necessary information. Here's a breakdown of the steps:

1. Processing Type: You will be asked whether you want to annotate a single script or a batch of scripts. Enter single or batch.
2. API Key: You will be prompted to enter your Google Cloud Generative AI API Key.
3. Source Path:
   • If you selected single, you will be asked to enter the full path to the PowerShell script you want to annotate.
   • If you selected batch, you will be asked to enter the full path to the directory containing the PowerShell scripts.
4. Destination Path:
   • If you selected single, you will be asked to enter the full path where you want to save the annotated script (including the filename).
   • If you selected batch, you will be asked to enter the full path to the directory where you want to save the annotated scripts. The directory structure from the source will be preserved in the destination.
5. Confirmation: Before proceeding, you will be asked to confirm your choices. Enter y to continue or n to cancel.