pair-programming/technical_debt_gemini.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5a6f7481-4064-4e8c-9b94-21905d6db6d7",
   "metadata": {},
   "source": [
    "# Technical Debt with Gemini"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e19aa2e-8c1b-43ff-b540-cea603a79b5c",
   "metadata": {},
   "source": [
    "#### Setup\n",
    "Set the Gemini API key with the provided helper function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "13f21190-1c61-4fb8-957d-ef5d070bf333",
   "metadata": {
    "height": 319
   },
   "outputs": [],
   "source": [
    "#!pip install python-dotenv\n",
    "import os\n",
    "from dotenv import load_dotenv, find_dotenv\n",
    "\n",
    "def get_api_key():\n",
    "    \n",
    "    _ = load_dotenv(find_dotenv()) # read local .env file\n",
    "    return os.getenv('GOOGLE_API_KEY')\n",
    "\n",
    "# PaLM legacy\n",
    "## import google.generativeai as palm\n",
    "## palm.configure(api_key=get_api_key())\n",
    "\n",
    "# Gemini API\n",
    "import os\n",
    "import google.generativeai as genai\n",
    "from google.api_core import client_options as client_options_lib\n",
    "\n",
    "genai.configure(\n",
    "    api_key=get_api_key(),\n",
    "    transport=\"rest\",\n",
    "    client_options=client_options_lib.ClientOptions(\n",
    "        api_endpoint=os.getenv(\"GOOGLE_API_BASE\"),\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b7550f9-c19b-4bdf-83d7-61ee51d94083",
   "metadata": {},
   "source": [
    "#### Pick the model that generates text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "eff6eccb-49ba-439c-9c11-94d7d9dc8902",
   "metadata": {
    "height": 64
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Model(name='models/text-bison-001',\n",
       "      base_model_id='',\n",
       "      version='001',\n",
       "      display_name='PaLM 2 (Legacy)',\n",
       "      description='A legacy model that understands text and generates text as an output',\n",
       "      input_token_limit=8196,\n",
       "      output_token_limit=1024,\n",
       "      supported_generation_methods=['generateText', 'countTextTokens', 'createTunedTextModel'],\n",
       "      temperature=0.7,\n",
       "      top_p=0.95,\n",
       "      top_k=40)"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "models = [m for m in genai.list_models() if 'generateText' in m.supported_generation_methods]\n",
    "model_bison = models[0]\n",
    "model_bison"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "963ec2a9",
   "metadata": {
    "height": 47
   },
   "outputs": [],
   "source": [
    "# Set the model to connect to the Gemini API\n",
    "model_flash = genai.GenerativeModel(model_name='gemini-1.5-flash')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "089429a3-357d-4df2-a11a-9ba4bc9b7e85",
   "metadata": {},
   "source": [
    "#### Helper function to call the PaLM API\n",
    "\n",
    "```Python\n",
    "from google.api_core import retry\n",
    "@retry.Retry()\n",
    "def generate_text(prompt, \n",
    "                  model=model_bison, \n",
    "                  temperature=0.0):\n",
    "    return palm.generate_text(prompt=prompt,\n",
    "                              model=model,\n",
    "                              temperature=temperature)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e213e43",
   "metadata": {},
   "source": [
    "### Helper function to call the Gemini API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "87831e1c-493f-473c-a13a-f7856678aef8",
   "metadata": {
    "height": 98
   },
   "outputs": [],
   "source": [
    "def generate_text(prompt,\n",
    "                  model=model_flash,\n",
    "                  temperature=0.0):\n",
    "    return model_flash.generate_content(prompt,\n",
    "                                  generation_config={'temperature':temperature})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87eef99a-7840-4296-beaf-ea0b758bb9a1",
   "metadata": {},
   "source": [
    "### Ask an LLM to explain a complex code base"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "71c2070a-56f6-4c88-b5eb-f6cb0ca5e6a7",
   "metadata": {
    "height": 4397
   },
   "outputs": [],
   "source": [
    "#@title Complex Code Block\n",
    "# Note: Taken from https://github.com/lmoroney/odmlbook/blob/63c0825094b2f44efc5c4d3226425a51990e73d6/BookSource/Chapter08/ios/cats_vs_dogs/CatVsDogClassifierSample/ModelDataHandler/ModelDataHandler.swift\n",
    "CODE_BLOCK = \"\"\"\n",
    "// Copyright 2019 The TensorFlow Authors. All Rights Reserved.\n",
    "//\n",
    "// Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "// you may not use this file except in compliance with the License.\n",
    "// You may obtain a copy of the License at\n",
    "//\n",
    "//    http://www.apache.org/licenses/LICENSE-2.0\n",
    "//\n",
    "// Unless required by applicable law or agreed to in writing, software\n",
    "// distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "// See the License for the specific language governing permissions and\n",
    "// limitations under the License.\n",
    "\n",
    "import CoreImage\n",
    "import TensorFlowLite\n",
    "import UIKit\n",
    "\n",
    "\n",
    "/// An inference from invoking the `Interpreter`.\n",
    "struct Inference {\n",
    "  let confidence: Float\n",
    "  let label: String\n",
    "}\n",
    "\n",
    "/// Information about a model file or labels file.\n",
    "typealias FileInfo = (name: String, extension: String)\n",
    "\n",
    "/// Information about the MobileNet model.\n",
    "enum MobileNet {\n",
    "  static let modelInfo: FileInfo = (name: \"converted_model\", extension: \"tflite\")\n",
    "}\n",
    "\n",
    "/// This class handles all data preprocessing and makes calls to run inference on a given frame\n",
    "/// by invoking the `Interpreter`. It then formats the inferences obtained and returns the top N\n",
    "/// results for a successful inference.\n",
    "class ModelDataHandler {\n",
    "\n",
    "  // MARK: - Public Properties\n",
    "\n",
    "  /// The current thread count used by the TensorFlow Lite Interpreter.\n",
    "  let threadCount: Int\n",
    "\n",
    "  let resultCount = 1\n",
    "\n",
    "  // MARK: - Model Parameters\n",
    "\n",
    "  let batchSize = 1\n",
    "  let inputChannels = 3\n",
    "  let inputWidth = 224\n",
    "  let inputHeight = 224\n",
    "\n",
    "  // MARK: - Private Properties\n",
    "\n",
    "  /// List of labels from the given labels file.\n",
    "  private var labels: [String] = [\"Cat\", \"Dog\"]\n",
    "\n",
    "  /// TensorFlow Lite `Interpreter` object for performing inference on a given model.\n",
    "  private var interpreter: Interpreter\n",
    "\n",
    "  /// Information about the alpha component in RGBA data.\n",
    "  private let alphaComponent = (baseOffset: 4, moduloRemainder: 3)\n",
    "\n",
    "  // MARK: - Initialization\n",
    "\n",
    "  /// A failable initializer for `ModelDataHandler`. A new instance is created if the model and\n",
    "  /// labels files are successfully loaded from the app's main bundle. Default `threadCount` is 1.\n",
    "  init?(modelFileInfo: FileInfo, threadCount: Int = 1) {\n",
    "    let modelFilename = modelFileInfo.name\n",
    "\n",
    "    // Construct the path to the model file.\n",
    "    guard let modelPath = Bundle.main.path(\n",
    "      forResource: modelFilename,\n",
    "      ofType: modelFileInfo.extension\n",
    "      ) else {\n",
    "        print(\"Failed to load the model file with name: \\(modelFilename).\")\n",
    "        return nil\n",
    "    }\n",
    "\n",
    "    // Specify the options for the `Interpreter`.\n",
    "    self.threadCount = threadCount\n",
    "    var options = InterpreterOptions()\n",
    "    options.threadCount = threadCount\n",
    "    do {\n",
    "      // Create the `Interpreter`.\n",
    "      interpreter = try Interpreter(modelPath: modelPath, options: options)\n",
    "    } catch let error {\n",
    "      print(\"Failed to create the interpreter with error: \\(error.localizedDescription)\")\n",
    "      return nil\n",
    "    }\n",
    "\n",
    "  }\n",
    "\n",
    "  // MARK: - Public Methods\n",
    "\n",
    "  /// Performs image preprocessing, invokes the `Interpreter`, and process the inference results.\n",
    "  func runModel(onFrame pixelBuffer: CVPixelBuffer) -> [Inference]? {\n",
    "    let sourcePixelFormat = CVPixelBufferGetPixelFormatType(pixelBuffer)\n",
    "    assert(sourcePixelFormat == kCVPixelFormatType_32ARGB ||\n",
    "      sourcePixelFormat == kCVPixelFormatType_32BGRA ||\n",
    "      sourcePixelFormat == kCVPixelFormatType_32RGBA)\n",
    "\n",
    "\n",
    "    let imageChannels = 4\n",
    "    assert(imageChannels >= inputChannels)\n",
    "\n",
    "    // Crops the image to the biggest square in the center and scales it down to model dimensions.\n",
    "    let scaledSize = CGSize(width: inputWidth, height: inputHeight)\n",
    "    guard let thumbnailPixelBuffer = pixelBuffer.centerThumbnail(ofSize: scaledSize) else {\n",
    "      return nil\n",
    "    }\n",
    "\n",
    "    let outputTensor: Tensor\n",
    "    do {\n",
    "      // Allocate memory for the model's input `Tensor`s.\n",
    "      try interpreter.allocateTensors()\n",
    "\n",
    "      // Remove the alpha component from the image buffer to get the RGB data.\n",
    "      guard let rgbData = rgbDataFromBuffer(\n",
    "        thumbnailPixelBuffer,\n",
    "        byteCount: batchSize * inputWidth * inputHeight * inputChannels\n",
    "        ) else {\n",
    "          print(\"Failed to convert the image buffer to RGB data.\")\n",
    "          return nil\n",
    "      }\n",
    "\n",
    "      // Copy the RGB data to the input `Tensor`.\n",
    "      try interpreter.copy(rgbData, toInputAt: 0)\n",
    "\n",
    "      // Run inference by invoking the `Interpreter`.\n",
    "      try interpreter.invoke()\n",
    "\n",
    "      // Get the output `Tensor` to process the inference results.\n",
    "      outputTensor = try interpreter.output(at: 0)\n",
    "    } catch let error {\n",
    "      print(\"Failed to invoke the interpreter with error: \\(error.localizedDescription)\")\n",
    "      return nil\n",
    "    }\n",
    "\n",
    "    let results = [Float32](unsafeData: outputTensor.data) ?? []\n",
    "\n",
    "    // Process the results.\n",
    "    let topNInferences = getTopN(results: results)\n",
    "\n",
    "    // Return the inference time and inference results.\n",
    "    return topNInferences\n",
    "  }\n",
    "\n",
    "  // MARK: - Private Methods\n",
    "\n",
    "  /// Returns the top N inference results sorted in descending order.\n",
    "  private func getTopN(results: [Float]) -> [Inference] {\n",
    "    // Create a zipped array of tuples [(labelIndex: Int, confidence: Float)].\n",
    "    let zippedResults = zip(labels.indices, results)\n",
    "\n",
    "    // Sort the zipped results by confidence value in descending order.\n",
    "    let sortedResults = zippedResults.sorted { $0.1 > $1.1 }.prefix(resultCount)\n",
    "\n",
    "    // Return the `Inference` results.\n",
    "    return sortedResults.map { result in Inference(confidence: result.1, label: labels[result.0]) }\n",
    "  }\n",
    "\n",
    "  /// Loads the labels from the labels file and stores them in the `labels` property.\n",
    "  private func loadLabels(fileInfo: FileInfo) {\n",
    "    let filename = fileInfo.name\n",
    "    let fileExtension = fileInfo.extension\n",
    "    guard let fileURL = Bundle.main.url(forResource: filename, withExtension: fileExtension) else {\n",
    "      fatalError(\"Labels file not found in bundle. Please add a labels file with name \" +\n",
    "        \"\\(filename).\\(fileExtension) and try again.\")\n",
    "    }\n",
    "    do {\n",
    "      let contents = try String(contentsOf: fileURL, encoding: .utf8)\n",
    "      labels = contents.components(separatedBy: .newlines)\n",
    "    } catch {\n",
    "      fatalError(\"Labels file named \\(filename).\\(fileExtension) cannot be read. Please add a \" +\n",
    "        \"valid labels file and try again.\")\n",
    "    }\n",
    "  }\n",
    "\n",
    "  /// Returns the RGB data representation of the given image buffer with the specified `byteCount`.\n",
    "  ///\n",
    "  /// - Parameters\n",
    "  ///   - buffer: The pixel buffer to convert to RGB data.\n",
    "  ///   - byteCount: The expected byte count for the RGB data calculated using the values that the\n",
    "  ///       model was trained on: `batchSize * imageWidth * imageHeight * componentsCount`.\n",
    "  ///   - isModelQuantized: Whether the model is quantized (i.e. fixed point values rather than\n",
    "  ///       floating point values).\n",
    "  /// - Returns: The RGB data representation of the image buffer or `nil` if the buffer could not be\n",
    "  ///     converted.\n",
    "  private func rgbDataFromBuffer(\n",
    "    _ buffer: CVPixelBuffer,\n",
    "    byteCount: Int\n",
    "    ) -> Data? {\n",
    "    CVPixelBufferLockBaseAddress(buffer, .readOnly)\n",
    "    defer { CVPixelBufferUnlockBaseAddress(buffer, .readOnly) }\n",
    "    guard let mutableRawPointer = CVPixelBufferGetBaseAddress(buffer) else {\n",
    "      return nil\n",
    "    }\n",
    "    let count = CVPixelBufferGetDataSize(buffer)\n",
    "    let bufferData = Data(bytesNoCopy: mutableRawPointer, count: count, deallocator: .none)\n",
    "    var rgbBytes = [Float](repeating: 0, count: byteCount)\n",
    "    var index = 0\n",
    "    for component in bufferData.enumerated() {\n",
    "      let offset = component.offset\n",
    "      let isAlphaComponent = (offset % alphaComponent.baseOffset) == alphaComponent.moduloRemainder\n",
    "      guard !isAlphaComponent else { continue }\n",
    "      rgbBytes[index] = Float(component.element) / 255.0\n",
    "      index += 1\n",
    "    }\n",
    "\n",
    "    return rgbBytes.withUnsafeBufferPointer(Data.init)\n",
    "\n",
    "  }\n",
    "}\n",
    "\n",
    "// MARK: - Extensions\n",
    "\n",
    "extension Data {\n",
    "  /// Creates a new buffer by copying the buffer pointer of the given array.\n",
    "  ///\n",
    "  /// - Warning: The given array's element type `T` must be trivial in that it can be copied bit\n",
    "  ///     for bit with no indirection or reference-counting operations; otherwise, reinterpreting\n",
    "  ///     data from the resulting buffer has undefined behavior.\n",
    "  /// - Parameter array: An array with elements of type `T`.\n",
    "  init<T>(copyingBufferOf array: [T]) {\n",
    "    self = array.withUnsafeBufferPointer(Data.init)\n",
    "  }\n",
    "}\n",
    "\n",
    "extension Array {\n",
    "  /// Creates a new array from the bytes of the given unsafe data.\n",
    "  ///\n",
    "  /// - Warning: The array's `Element` type must be trivial in that it can be copied bit for bit\n",
    "  ///     with no indirection or reference-counting operations; otherwise, copying the raw bytes in\n",
    "  ///     the `unsafeData`'s buffer to a new array returns an unsafe copy.\n",
    "  /// - Note: Returns `nil` if `unsafeData.count` is not a multiple of\n",
    "  ///     `MemoryLayout<Element>.stride`.\n",
    "  /// - Parameter unsafeData: The data containing the bytes to turn into an array.\n",
    "  init?(unsafeData: Data) {\n",
    "\n",
    "    guard unsafeData.count % MemoryLayout<Element>.stride == 0 else { return nil }\n",
    "    #if swift(>=5.0)\n",
    "    self = unsafeData.withUnsafeBytes { .init($0.bindMemory(to: Element.self)) }\n",
    "    #else\n",
    "    self = unsafeData.withUnsafeBytes {\n",
    "      .init(UnsafeBufferPointer<Element>(\n",
    "        start: $0,\n",
    "        count: unsafeData.count / MemoryLayout<Element>.stride\n",
    "      ))\n",
    "    }\n",
    "    #endif  // swift(>=5.0)\n",
    "  }\n",
    "}\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "ff3c49c7-a4d3-4eca-8bf0-4e0cdbd337d0",
   "metadata": {
    "height": 132
   },
   "outputs": [],
   "source": [
    "prompt_template = \"\"\"\n",
    "Can you please explain how this code works?\n",
    "\n",
    "{question}\n",
    "\n",
    "Use a lot of detail and make it as clear as possible.\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "90c20db9-f6e9-4d27-96b5-d43f0b24a484",
   "metadata": {
    "height": 166
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This code implements a mobile image classification model using TensorFlow Lite in a Swift iOS application. Let's break down the code section by section:\n",
      "\n",
      "**1. Imports and Structs:**\n",
      "\n",
      "* `CoreImage`: Provides image processing capabilities.\n",
      "* `TensorFlowLite`: The core library for running TensorFlow Lite models.\n",
      "* `UIKit`:  Provides UI elements (though not directly used in this specific code snippet, it's necessary for the broader application context).\n",
      "* `Inference`: A struct to hold the results of an inference (confidence score and label).\n",
      "* `FileInfo`: A typealias for a tuple representing model or label file information (name and extension).\n",
      "* `MobileNet`: An enum holding information about the specific MobileNet model used (filename).\n",
      "\n",
      "**2. `ModelDataHandler` Class:**\n",
      "\n",
      "This class is the heart of the inference process. It handles:\n",
      "\n",
      "* **Model Loading:** The `init?` method loads the TensorFlow Lite model from the app's bundle.  It checks for errors during model loading and interpreter creation.  If anything goes wrong, it returns `nil`, indicating failure.  The `threadCount` parameter controls the number of threads used by the interpreter for parallel processing.\n",
      "\n",
      "* **Model Parameters:**  Constants defining the model's input shape (batch size, width, height, channels).  These are crucial for pre-processing the input image.\n",
      "\n",
      "* **Labels:** The `labels` array stores the class labels (e.g., \"Cat\", \"Dog\").  Ideally, these would be loaded from a separate labels file (see `loadLabels` below).\n",
      "\n",
      "* **Interpreter:** The `interpreter` property is an instance of `Interpreter`, the TensorFlow Lite object responsible for running the model.\n",
      "\n",
      "* **`runModel(onFrame:)`:** This is the main function that performs inference.  It takes a `CVPixelBuffer` (a Core Video pixel buffer representing the image) as input.  The steps are:\n",
      "\n",
      "    * **Pixel Buffer Validation:** It checks the pixel format of the input buffer to ensure it's compatible (ARGB, BGRA, or RGBA).\n",
      "\n",
      "    * **Image Preprocessing:**  `pixelBuffer.centerThumbnail(ofSize:)` crops the image to a square and resizes it to the model's input dimensions (`inputWidth` x `inputHeight`). This is crucial because MobileNet expects a specific input size.\n",
      "\n",
      "    * **Tensor Allocation:** `interpreter.allocateTensors()` allocates memory for the input and output tensors of the model.\n",
      "\n",
      "    * **RGB Data Extraction:** `rgbDataFromBuffer()` converts the pixel buffer's data into a `Data` object containing RGB values.  It handles the removal of the alpha channel (transparency) if present.  The conversion to `Float` values (divided by 255.0 to normalize to the range 0-1) is important because many TensorFlow Lite models expect floating-point inputs.\n",
      "\n",
      "    * **Input Copying:** `interpreter.copy(rgbData, toInputAt: 0)` copies the preprocessed RGB data into the model's input tensor.\n",
      "\n",
      "    * **Inference Execution:** `interpreter.invoke()` runs the inference.\n",
      "\n",
      "    * **Output Retrieval:** `interpreter.output(at: 0)` retrieves the output tensor containing the classification results.\n",
      "\n",
      "    * **Result Processing:** The output tensor's data is converted into a `[Float]` array.  `getTopN()` then selects the top `resultCount` (default is 1) predictions, sorting them by confidence.\n",
      "\n",
      "    * **Return Value:** The function returns an array of `Inference` structs, each containing a label and its associated confidence score.\n",
      "\n",
      "* **`getTopN(results:)`:** This helper function takes the raw output from the model and returns the top N predictions, sorted by confidence.\n",
      "\n",
      "* **`loadLabels(fileInfo:)`:** This function (not directly called in the provided snippet) would load class labels from a text file, where each line represents a label.\n",
      "\n",
      "* **`rgbDataFromBuffer(_:byteCount:)`:** This function converts the image data from the `CVPixelBuffer` into a `Data` object containing the RGB values, suitable for feeding into the TensorFlow Lite model.  It handles different pixel formats and removes the alpha channel.\n",
      "\n",
      "\n",
      "**3. Extensions:**\n",
      "\n",
      "* **`Data` Extension:** Adds an initializer to create a `Data` object from the buffer of an array.  This is a convenient way to convert the array of floats to `Data` for TensorFlow Lite.\n",
      "\n",
      "* **`Array` Extension:** Adds an initializer to create an array from a `Data` object.  This is used to convert the output tensor's raw bytes into a `Float` array.  It handles potential errors if the data size isn't a multiple of the element size.\n",
      "\n",
      "\n",
      "**In Summary:**\n",
      "\n",
      "This code provides a complete pipeline for image classification using TensorFlow Lite on iOS. It handles model loading, image preprocessing, inference execution, and result processing.  The use of `CVPixelBuffer` ensures efficient handling of image data, and the error handling makes the code robust.  The extensions add useful functionality for data conversion between different formats.  The code is well-structured and uses clear variable names, making it relatively easy to understand.  The missing `loadLabels` call suggests that the labels are hardcoded for simplicity in this example, but in a real application, it would likely load labels from a file.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "completion = generate_text(\n",
    "    prompt = prompt_template.format(question=CODE_BLOCK)\n",
    ")\n",
    "\n",
    "# Gemini API\n",
    "print(completion.text)\n",
    "\n",
    "# PaLM legacy\n",
    "## print(completion.result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5dcb1824-56dd-4e34-8079-9767cd9539e0",
   "metadata": {},
   "source": [
    "#### Try it out on your own code!\n",
    "- Try inputting some code into the `CODE_BLOCK` variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "42ddae3b-5936-4b8e-b5ac-d6671c7a03e6",
   "metadata": {
    "height": 336
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Let's break down the Python function `foo(a)` step-by-step:\n",
      "\n",
      "**1. Function Definition:**\n",
      "\n",
      "```python\n",
      "def foo(a):\n",
      "  # ... function body ...\n",
      "```\n",
      "\n",
      "This line defines a function named `foo`.  The `def` keyword indicates a function definition.  `foo` is the function's name, and `(a)` specifies that it takes one argument (or parameter), which we'll call `a`.  The colon (`:`) signifies the start of the function's body.\n",
      "\n",
      "**2. Local Variable Assignment:**\n",
      "\n",
      "```python\n",
      "  b = a + 1\n",
      "```\n",
      "\n",
      "Inside the function's body, this line creates a *local variable* named `b`.  A local variable is only accessible within the function where it's defined.  It assigns the value of `a + 1` to `b`.  In other words, it takes the input value `a`, adds 1 to it, and stores the result in `b`.  For example:\n",
      "\n",
      "* If `a` is 5, then `b` becomes 6.\n",
      "* If `a` is -2, then `b` becomes -1.\n",
      "* If `a` is 0, then `b` becomes 1.\n",
      "\n",
      "**3. Return Statement:**\n",
      "\n",
      "```python\n",
      "  return 2*b\n",
      "```\n",
      "\n",
      "This line is the function's *return statement*.  It specifies the value that the function will send back to the part of the code that called it.  It calculates `2 * b` (twice the value of `b`) and returns this result.\n",
      "\n",
      "**Putting it all together:**\n",
      "\n",
      "The function `foo(a)` takes a number `a` as input, adds 1 to it to get `b`, then multiplies `b` by 2, and finally returns this final result.\n",
      "\n",
      "**Example Usage:**\n",
      "\n",
      "Let's see how it works with some examples:\n",
      "\n",
      "```python\n",
      "result1 = foo(5)  # a is 5\n",
      "print(result1)    # Output: 12 (because b = 5 + 1 = 6, and 2 * 6 = 12)\n",
      "\n",
      "result2 = foo(-2) # a is -2\n",
      "print(result2)   # Output: -2 (because b = -2 + 1 = -1, and 2 * -1 = -2)\n",
      "\n",
      "result3 = foo(0)  # a is 0\n",
      "print(result3)   # Output: 2 (because b = 0 + 1 = 1, and 2 * 1 = 2)\n",
      "```\n",
      "\n",
      "In essence, the function `foo` performs a simple arithmetic operation: it takes an input, adds 1, and then doubles the result.  The use of local variables (`b`) keeps the internal calculations separate from any variables that might exist outside the function, promoting code clarity and preventing accidental modification of variables in other parts of your program.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "CODE_BLOCK = \"\"\" \n",
    "# replace this with your own code\n",
    "def foo(a):\n",
    "  b = a + 1\n",
    "  return 2*b\n",
    "\"\"\"\n",
    "\n",
    "prompt_template = \"\"\"\n",
    "Can you please explain how this code works?\n",
    "\n",
    "{question}\n",
    "\n",
    "Use a lot of detail and make it as clear as possible.\n",
    "\"\"\"\n",
    "\n",
    "completion = generate_text(\n",
    "    prompt = prompt_template.format(question=CODE_BLOCK)\n",
    ")\n",
    "print(completion.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e93864a7-fd47-427b-b6f1-b492e159560d",
   "metadata": {},
   "source": [
    "### Ask an LLM to document a complex code base"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "57ac2cb3-0865-4d9b-89ba-bfc237ebad3b",
   "metadata": {
    "height": 149
   },
   "outputs": [],
   "source": [
    "prompt_template = \"\"\"\n",
    "Please write technical documentation for this code and \\n\n",
    "make it easy for a non swift developer to understand:\n",
    "\n",
    "{question}\n",
    "\n",
    "Output the results in markdown\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "1dcb82c6-a870-476b-b587-688d0344f33d",
   "metadata": {
    "height": 81
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "## Function: `foo(a)`\n",
      "\n",
      "This document describes the function `foo(a)`, written in Python.  This function takes a single numerical input and performs a simple calculation.\n",
      "\n",
      "**1. Function Signature:**\n",
      "\n",
      "```python\n",
      "def foo(a):\n",
      "  # ... function body ...\n",
      "```\n",
      "\n",
      "The function is defined using the `def` keyword.  It's named `foo` and accepts one argument, `a`.  We assume `a` is a number (integer or floating-point).\n",
      "\n",
      "**2. Function Body:**\n",
      "\n",
      "```python\n",
      "  b = a + 1\n",
      "  return 2*b\n",
      "```\n",
      "\n",
      "The function body consists of two lines:\n",
      "\n",
      "* **`b = a + 1`**: This line calculates an intermediate value `b`. It adds 1 to the input value `a` and assigns the result to the variable `b`.\n",
      "\n",
      "* **`return 2*b`**: This line calculates the final result. It multiplies the value of `b` by 2 and returns this result as the output of the function.\n",
      "\n",
      "**3. Function Behavior:**\n",
      "\n",
      "The function `foo(a)` performs the following steps:\n",
      "\n",
      "1. Takes a numerical input `a`.\n",
      "2. Adds 1 to `a` to get `b`.\n",
      "3. Multiplies `b` by 2.\n",
      "4. Returns the final result (which is `2 * (a + 1)`).\n",
      "\n",
      "**4. Example Usage:**\n",
      "\n",
      "Let's illustrate with some examples:\n",
      "\n",
      "| Input `a` | Calculation                  | Output `foo(a)` |\n",
      "|------------|------------------------------|-----------------|\n",
      "| 5          | 2 * (5 + 1) = 12             | 12              |\n",
      "| 0          | 2 * (0 + 1) = 2             | 2               |\n",
      "| -2         | 2 * (-2 + 1) = -2            | -2              |\n",
      "| 3.14       | 2 * (3.14 + 1) = 8.28       | 8.28            |\n",
      "\n",
      "\n",
      "**5. Error Handling:**\n",
      "\n",
      "The function doesn't include explicit error handling.  If the input `a` is not a number, a `TypeError` will likely occur.  More robust code might include checks to handle non-numeric inputs.\n",
      "\n",
      "\n",
      "**6.  In other languages:**\n",
      "\n",
      "The equivalent function in other languages would look very similar.  The core operations (addition and multiplication) are standard across most programming languages.  For example, in JavaScript:\n",
      "\n",
      "```javascript\n",
      "function foo(a) {\n",
      "  let b = a + 1;\n",
      "  return 2 * b;\n",
      "}\n",
      "```\n",
      "\n",
      "This documentation provides a clear and concise explanation of the `foo(a)` function, making it understandable even for those unfamiliar with Python.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "completion = generate_text(\n",
    "    prompt = prompt_template.format(question=CODE_BLOCK)\n",
    ")\n",
    "print(completion.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9676f08-dd6a-4e83-9022-eb14ce4775f9",
   "metadata": {},
   "source": [
    "### Try it out on your own code!\n",
    "- Notice that we've modified the prompt slightly to refer to Python instead of Swift."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "17699e40-d85e-4b9e-a569-e55dcdc2a23b",
   "metadata": {
    "height": 353
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Function: `foo(a)` - Technical Documentation\n",
      "\n",
      "## Purpose\n",
      "\n",
      "The function `foo(a)` takes a single numerical input (`a`) and performs a simple calculation to produce a numerical output.\n",
      "\n",
      "## Input\n",
      "\n",
      "*   **`a`**:  A number (integer or floating-point). This is the input value the function will use for its calculation.\n",
      "\n",
      "## Process\n",
      "\n",
      "1.  **Increment:** The function first adds 1 to the input value `a`, storing the result in a new variable called `b`.  ( `b = a + 1` )\n",
      "2.  **Multiplication:** It then multiplies the value of `b` by 2. (`return 2 * b`)\n",
      "\n",
      "## Output\n",
      "\n",
      "*   The function returns a single numerical value which is twice the value of (`a + 1`).\n",
      "\n",
      "## Example\n",
      "\n",
      "Let's say the input `a` is 5:\n",
      "\n",
      "1.  `b = a + 1` becomes `b = 5 + 1`, resulting in `b = 6`.\n",
      "2.  `return 2 * b` becomes `return 2 * 6`, resulting in a final output of `12`.\n",
      "\n",
      "Therefore, `foo(5)` would return `12`.\n",
      "\n",
      "\n",
      "##  Code in Python\n",
      "\n",
      "```python\n",
      "def foo(a):\n",
      "  b = a + 1\n",
      "  return 2*b\n",
      "```\n",
      "\n",
      "##  How to Use (Conceptual, not specific to any language)\n",
      "\n",
      "To use this function, you would provide a numerical value as input. The function will then perform the calculations described above and return the resulting number.  The way you would *call* this function would depend on the programming language you are using.  For example, in Python, you would write something like: `result = foo(5)`  and the variable `result` would then hold the value 12.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "CODE_BLOCK = \"\"\" \n",
    "# replace this with your own code\n",
    "def foo(a):\n",
    "  b = a + 1\n",
    "  return 2*b\n",
    "\"\"\"\n",
    "\n",
    "prompt_template = \"\"\"\n",
    "Please write technical documentation for this code and \\n\n",
    "make it easy for a non Python developer to understand:\n",
    "\n",
    "{question}\n",
    "\n",
    "Output the results in markdown\n",
    "\"\"\"\n",
    "\n",
    "completion = generate_text(\n",
    "    prompt = prompt_template.format(question=CODE_BLOCK)\n",
    ")\n",
    "print(completion.text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bcd7fd23-141c-477a-97c9-e7723df9d424",
   "metadata": {
    "height": 30
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c770b6f1",
   "metadata": {
    "height": 30
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}