release: dec 2023 (#289)

Co-authored-by: Mais <[email protected]>
Co-authored-by: Darren Ackers <[email protected]>
Co-authored-by: google-cloud-firebase-extensions-bot <[email protected]>
Co-authored-by: Jacob Cable <[email protected]>
Co-authored-by: Majid <[email protected]>

.github/workflows/readmes-updated.yaml

@@ -31,7 +31,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           cache: 'npm'
           cache-dependency-path: '**/functions/package-lock.json'
 

.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: 'Create Releases'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Release Script
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ./.github/workflows/scripts/release.sh

.github/workflows/scripts/release.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+# Uncomment for testing purposes:
+
+#GITHUB_TOKEN=YOUR_TOKEN_HERE
+#GITHUB_REPOSITORY=invertase/extensions-release-testing
+
+# -------------------
+#      Functions
+# -------------------
+json_escape() {
+  printf '%s' "$1" | python -c 'import json,sys; print(json.dumps(sys.stdin.read()))'
+}
+
+# Creates a new GitHub release
+#   ARGS:
+#     1: Name of the release (becomes the release title on GitHub)
+#     2: Markdown body of the release
+#     3: Release Git tag
+create_github_release() {
+  local response=''
+  local release_name=$1
+  local release_body=$2
+  local release_tag=$3
+
+  local body='{
+    "tag_name": "%s",
+    "target_commitish": "master",
+    "name": "%s",
+    "body": %s,
+    "draft": false,
+    "prerelease": false
+  }'
+
+  # shellcheck disable=SC2059
+  body=$(printf "$body" "$release_tag" "$release_name" "$release_body")
+  response=$(curl --request POST \
+    --url https://api.github.com/repos/${GITHUB_REPOSITORY}/releases \
+    --header "Authorization: Bearer $GITHUB_TOKEN" \
+    --header 'Content-Type: application/json' \
+    --data "$body" \
+    -s)
+
+  created=$(echo "$response" | python -c "import sys, json; data = json.load(sys.stdin); print(data.get('id', sys.stdin))")
+  if [ "$created" != "$response" ]; then
+    printf "release created successfully!\n"
+  else
+    printf "release failed to create; "
+    printf "\n%s\n" "$body"
+    printf "\n%s\n" "$response"
+    exit 1
+  fi
+}
+
+# Updates an existing GitHub release
+#   ARGS:
+#     1: Name of the release (becomes the release title on GitHub)
+#     2: Markdown body of the release
+#     3: Release Git tag
+#     4: ID of the existing release
+update_github_release() {
+  local response=''
+  local release_name=$1
+  local release_body=$2
+  local release_tag=$3
+  local release_id=$4
+
+  local body='{
+	  "tag_name": "%s",
+	  "target_commitish": "master",
+	  "name": "%s",
+	  "body": %s,
+	  "draft": false,
+	  "prerelease": false
+	}'
+
+  # shellcheck disable=SC2059
+  body=$(printf "$body" "$release_tag" "$release_name" "$release_body")
+  response=$(curl --request PATCH \
+    --url "https://api.github.com/repos/$GITHUB_REPOSITORY/releases/$release_id" \
+    --header "Authorization: Bearer $GITHUB_TOKEN" \
+    --header 'Content-Type: application/json' \
+    --data "$body" \
+    -s)
+
+  updated=$(echo "$response" | python -c "import sys, json; data = json.load(sys.stdin); print(data.get('id', sys.stdin))")
+  if [ "$updated" != "$response" ]; then
+    printf "release updated successfully!\n"
+  else
+    printf "release failed to update; "
+    printf "\n%s\n" "$body"
+    printf "\n%s\n" "$response"
+    exit 1
+  fi
+}
+
+# Creates or updates a GitHub release
+#   ARGS:
+#     1: Extension name
+#     2: Extension version
+#     3: Markdown body to use for the release
+create_or_update_github_release() {
+  local response=''
+  local release_id=''
+  local extension_name=$1
+  local extension_version=$2
+  local release_body=$3
+  local release_tag="$extension_name-v$extension_version"
+  local release_name="$extension_name v$extension_version"
+
+  response=$(curl --request GET \
+    --url "https://api.github.com/repos/${GITHUB_REPOSITORY}/releases/tags/${release_tag}" \
+    --header "Authorization: Bearer $GITHUB_TOKEN" \
+    --header 'Content-Type: application/json' \
+    --data "$body" \
+    -s)
+
+  release_id=$(echo "$response" | python -c "import sys, json; data = json.load(sys.stdin); print(data.get('id', 'Not Found'))")
+  if [ "$release_id" != "Not Found" ]; then
+    existing_release_body=$(echo "$response" | python -c "import sys, json; data = json.load(sys.stdin); print(data.get('body', ''))")
+    existing_release_body=$(json_escape "$existing_release_body")
+    # Only update it if the release body is different (this can happen if a change log is manually updated)
+    printf "Existing release (%s) found for %s - " "$release_id" "$release_tag"
+    if [ "$existing_release_body" != "$release_body" ]; then
+      printf "updating it with updated release body ... "
+      update_github_release "$release_name" "$release_body" "$release_tag" "$release_id"
+    else
+      printf "skipping it as release body is already up to date.\n"
+    fi
+  else
+    response_message=$(echo "$response" | python -c "import sys, json; data = json.load(sys.stdin); print(data.get('message'))")
+    if [ "$response_message" != "Not Found" ]; then
+      echo "Failed to query release '$release_name' -> GitHub API request failed with response: $response_message"
+      echo "$response"
+      exit 1
+    else
+      printf "Creating new release '%s' ... " "$release_tag"
+      create_github_release "$release_name" "$release_body" "$release_tag"
+    fi
+  fi
+}
+
+# -------------------
+#    Main Script
+# -------------------
+
+# Ensure that the GITHUB_TOKEN env variable is defined
+if [[ -z "$GITHUB_TOKEN" ]]; then
+  echo "Missing required GITHUB_TOKEN env variable. Set this on the workflow action or on your local environment."
+  exit 1
+fi
+
+# Ensure that the GITHUB_REPOSITORY env variable is defined
+if [[ -z "$GITHUB_REPOSITORY" ]]; then
+  echo "Missing required GITHUB_REPOSITORY env variable. Set this on the workflow action or on your local environment."
+  exit 1
+fi
+
+# Find all extensions based on whether a extension.yaml file exists in the directory
+for i in $(find . -type f -name 'extension.yaml' -exec dirname {} \; | sort -u); do
+  # Pluck extension name from directory name
+  extension_name=$(echo "$i" | sed "s/\.\///")
+  # Pluck extension latest version from yaml file
+  extension_version=$(awk '/^version: /' "$i/extension.yaml" | sed "s/version: //")
+
+  changelog_contents="No changelog found for this version."
+
+  # Ensure changelog exists
+  if [ -f "$i/CHANGELOG.md" ]; then
+    # Pluck out change log contents for the latest extension version
+    changelog_contents=$(awk -v ver="$extension_version" '/^## Version / { if (p) { exit }; if ($3 == ver) { p=1; next} } p && NF' "$i/CHANGELOG.md")
+  else
+    echo "WARNING: A changelog could not be found at $i/CHANGELOG.md - a default entry will be used instead."
+  fi
+
+  # JSON escape the markdown content for the release body
+  changelog_contents=$(json_escape "$changelog_contents")
+
+  # Creates a new release if it does not exist
+  #   OR
+  # Updates an existing release with updated content (allows updating CHANGELOG.md which will update relevant release body)
+  create_or_update_github_release "$extension_name" "$extension_version" "$changelog_contents"
+done

firestore-genai-chatbot/CHANGELOG.md

@@ -0,0 +1,3 @@
+## Version 0.0.1
+
+Initial release of the firestore-genai-chatbot extension.

firestore-genai-chatbot/POSTINSTALL.md

@@ -0,0 +1,50 @@
+## Testing the extension
+
+You can test out the extension right away by following these steps:
+
+1. Go to the [Cloud Firestore dashboard](https://console.firebase.google.com/project/_/firestore) in the Firebase console.
+2. If it doesn't already exist, create the collection you specified during installation: **${param:COLLECTION_NAME}**.
+3. Add a document with a **${param:PROMPT_FIELD}** field containing your first message:
+
+```
+${param:PROMPT_FIELD}: "How are you today?"
+```
+
+4. In a few seconds, you'll see a ${param:ORDER_FIELD} field and then a status field should appear in the document. The status field will update as the extension processes the message.
+5. When processing is finished, the ${param:RESPONSE_FIELD} field of the document should be populated with the response from the Google AI Gemini API.
+
+```javascript
+const ref = await admin
+    .firestore()
+    .collection("${param:COLLECTION_NAME}")
+    .add({
+        ${param:PROMPT_FIELD}: "How are you today?",
+    })
+
+ref.onSnapshot(snap => {
+    if (snap.get('${param:RESPONSE_FIELD}')) console.log(
+        'RESPONSE:' +
+        snap.get('${param:RESPONSE_FIELD}')
+    )
+})
+```
+
+## About the providers
+
+The extension gives you a choice of what provider to use for the available models:
+
+- Google AI: For more details on this Gemini API, see the [Gemini homepage](https://ai.google.dev/docs).
+
+## About the models
+
+The extension gives you a choice of 2 models:
+
+- [Gemini Pro](https://ai.google.dev/models/gemini) chat model
+
+## Handling errors
+
+If the extension encounters an error, it will write an error message to the document in `status` field. You can use this field to monitor for errors in your documents. Currently some errors will instruct you to visit the Cloud Function logs for the extension, to avoid exposing sensitive information.
+
+## Monitoring
+
+As a best practice, you can [monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions#monitor) of your installed extension, including checks on its health, usage, and logs.

firestore-genai-chatbot/PREINSTALL.md

@@ -0,0 +1,57 @@
+Use this extension to easily deploy a chatbot using Gemini large language models, stored and managed by Cloud Firestore.
+
+On install you will be asked to provide:
+
+- **Generative AI Provider** This extension makes use of either the Vertex AI Gemini API, or the Google AI Gemini API. To use Google AI you will need to provide a valid API key, Vertex AI will attempt to use Application Default Credentials to authenticate with your Google Cloud Project.
+
+- **Language model**: Which language model do you want to use? Please ensure you pick a model supported by your selected provider.
+
+- **Firestore collection path**: Used to store conversation history represented as documents. This extension will listen to the specified collection(s) for new message documents.
+
+The collection path also supports wildcards, so you can trigger the extension on multiple collections, each with their own private conversation history. This is useful if you want to create separate conversations for different users, or support multiple chat sessions.
+
+Message documents might look like this:
+
+```
+{
+  prompt: “What is the best museum to visit in Barcelona, Spain?”
+}
+```
+
+When a message document is added, the extension will:
+
+- Obtain conversation history by sorting the documents of the collection.
+- Query the language model you selected during configuration.
+- Write the message back to the triggering document in a configurable response field.
+
+A createTime field will be automatically created for you on document creation, and will be used to order the conversation history. Gemini, like any other LLM, will have a limited context window, so only the most recent messages will be used as history to generate the next response. Alternatively, If documents in the specified collection already contain a field representing timestamps, you can use that as the order field instead.
+
+You can configure the chatbot to return different responses by providing context during installation. For example, if you want the chatbot to act as a travel guide, you might use this as the context:
+
+```
+I want you to act as a travel guide. I will ask you questions about various travel destinations, and you will describe those destinations and give me suggestions on places to visit.
+```
+
+You can also configure the model to return different results by tweaking model parameters (temperature, candidate count, etc.), which are exposed as configuration during install as well.
+
+### Choosing a language model
+
+This extension supports the following language models:
+
+- [Gemini Pro](https://ai.google.dev/models/gemini)
+
+### Regenerating a response
+
+Changing the state field of a completed document's status from `COMPLETED` to anything else will retrigger the extension for that document.
+
+## Billing
+
+To install an extension, your project must be on the Blaze (pay as you go) plan. You will be charged a small amount (typically around $0.01/month) for the Firebase resources required by this extension (even if it is not used).
+This extension uses other Firebase and Google Cloud Platform services, which have associated charges if you exceed the service’s no-cost tier:
+
+- Cloud Firestore
+- Cloud Functions (See [FAQs](https://firebase.google.com/support/faq#extensions-pricing))
+
+[Learn more about Firebase billing.](https://firebase.google.com/pricing)
+
+Additionally, this extension uses the Google AI Gemini API. For more details on this Gemini API, see the [Gemini homepage](https://ai.google.dev/docs).