docs: Third tranche of docs updates (#1871)

* Docs: Edits to Auth doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Docs: Edits to Firebase doc for 1.0 GA * Accepting typo-fix suggestion in docs/firebase.md Co-authored-by: Chris Ray Gill <[email protected]> --------- Co-authored-by: Chris Ray Gill <[email protected]>
firebase · Feb 6, 2025 · 55baddf · 55baddf
1 parent 0baad30
commit 55baddf
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 40 deletions.
diff --git a/docs/cloud-run.md b/docs/cloud-run.md
@@ -83,13 +83,14 @@ When you deploy your flows with Cloud Run, you have two options for
 authorization:
 
 - **Cloud IAM-based authorization**: Use Google Cloud's native access management
-  facilities to gate access to your endpoints. See
+  facilities to gate access to your endpoints. For information on providing
+  these credentials, see
   [Authentication](https://cloud.google.com/run/docs/authenticating/overview)
-  in the Cloud Run docs for information on providing these credentials.
+  in the Cloud Run docs.
 
 - **Authorization policy defined in code**: Use the authorization policy feature
-  of Genkit express plugin to verify authorization info using custom code. This is often,
-  but not necessarily, token-based authorization.
+  of the Genkit express plugin to verify authorization info using custom code.
+  This is often, but not necessarily, token-based authorization.
 
 If you want to define an authorization policy in code, use the `authPolicy`
 parameter in the flow definition:

diff --git a/docs/devtools.md b/docs/devtools.md
@@ -33,7 +33,7 @@ npx genkit --help
 
 ### Genkit Developer UI
 
-The Genkit Developer UI is a local web app that allows you to interactively
+The Genkit Developer UI is a local web app that lets you interactively
 work with models, flows, prompts, and other elements in your Genkit project.
 
 The Developer UI is able to identify what Genkit components you have defined

diff --git a/docs/firebase.md b/docs/firebase.md
@@ -3,7 +3,7 @@
 Cloud Functions for Firebase has an `onCallGenkit` method that lets you
 quickly create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd)
 with a Genkit action (e.g. a Flow). These functions can be called using
-`genkit/beta/client`or the [Functions clientSDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function),
+`genkit/beta/client`or the [Functions client SDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function),
 which automatically adds auth info.
 
 ## Before you begin

diff --git a/docs/plugins/firebase.md b/docs/plugins/firebase.md
@@ -3,10 +3,14 @@ use https://github.com/firebase/firebase-tools/blob/master/templates/init/functi
 
 # Firebase plugin
 
-The Firebase plugin provides integrations with Firebase services, allowing you to build intelligent and scalable AI applications. Key features include:
+The Firebase plugin provides integrations with Firebase services, so you can
+build intelligent and scalable AI applications. Key features include:
 
-- **Firestore Vector Store**: Use Firestore for indexing and retrieval with vector embeddings.  
-- **Telemetry**: Export telemetry to [Google's Cloud operations suite](https://cloud.google.com/products/operations) that powers the Firebase Genkit Monitoring console.
+- **Firestore Vector Store**: Use Firestore for indexing and retrieval
+with vector embeddings.
+- **Telemetry**: Export telemetry to
+[Google's Cloud operations suite](https://cloud.google.com/products/operations) that powers the Firebase Genkit
+Monitoring console.
 
 ## Installation
 
@@ -20,13 +24,19 @@ npm install @genkit-ai/firebase
 
 ### Firebase Project Setup
 
-1. All Firebase products require a Firebase project. You can create a new project or enable Firebase in an existing Google Cloud project using the [Firebase console](https://console.firebase.google.com/).
-2. If deploying flows with Cloud Functions, [upgrade your Firebase project](https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered) to the Blaze plan.
-3. If you want to run code locally that exports telemetry, you need the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) tool installed.
+1. All Firebase products require a Firebase project. You can create a new
+   project or enable Firebase in an existing Google Cloud project using the
+   [Firebase console](https://console.firebase.google.com/).
+1. If deploying flows with Cloud functions,
+   [upgrade your Firebase project](https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered)
+   to the Blaze plan.
+1. If you want to run code locally that exports telemetry, you need the
+   [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) tool installed.
 
 ### Firebase Admin SDK Initialization
 
-You must initialize the Firebase Admin SDK in your application. This is not handled automatically by the plugin.
+You must initialize the Firebase Admin SDK in your application.
+This is not handled automatically by the plugin.
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->
@@ -38,32 +48,49 @@ initializeApp({
 });
 ```
 
-The plugin requires you to specify your Firebase project ID. You can specify your Firebase project ID in either of the following ways:
+The plugin requires you to specify your Firebase project ID. You can specify
+your Firebase project ID in either of the following ways:
 
-- Set `projectId` in the `initializeApp()` configuration object as shown in the snippet above.
+- Set `projectId` in the `initializeApp()` configuration object as shown
+in the snippet above.
 
-- Set the `GCLOUD_PROJECT` environment variable. If you're running your flow from a Google Cloud environment (Cloud Functions, Cloud Run, and so on), `GCLOUD_PROJECT` is automatically set to the project ID of the environment.
+- Set the `GCLOUD_PROJECT` environment variable. If you're running your
+  flow from a Google Cloud environment (Cloud Functions, Cloud Run, and
+  so on), `GCLOUD_PROJECT` is automatically set to the project ID of the
+  environment.
 
-  If you set `GCLOUD_PROJECT`, you can omit the configuration parameter in `initializeApp()`.
+  If you set `GCLOUD_PROJECT`, you can omit the configuration
+  parameter in `initializeApp()`.
 
 ### Credentials
 
-To provide Firebase credentials, you also need to set up Google Cloud Application Default Credentials. To specify your credentials:
+To provide Firebase credentials, you also need to set up Google Cloud
+Application Default Credentials. To specify your credentials:
 
-- If you're running your flow from a Google Cloud environment (Cloud Functions, Cloud Run, and so on), this is set automatically.
+- If you're running your flow from a Google Cloud environment (Cloud Functions,
+- Cloud Run, and so on), this is set automatically.
 
 - For other environments:
 
-  1. Generate service account credentials for your Firebase project and download the JSON key file. You can do so on the [Service account](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) page of the Firebase console.
-  2. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the file path of the JSON file that contains your service account key, or you can set the environment variable `GCLOUD_SERVICE_ACCOUNT_CREDS` to the content of the JSON file.
+  1. Generate service account credentials for your Firebase project and
+  download the JSON key file. You can do so on the
+ [Service account](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk)
+  page of the Firebase console.
+  1. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the file
+  path of the JSON file that contains your service account key, or you can set
+  the environment variable `GCLOUD_SERVICE_ACCOUNT_CREDS` to the content of the JSON file.
 
 ## Features and usage
 
 ### Telemetry
 
-Firebase Genkit Monitoring is powered by Google's Cloud operation suite. This requires telemetry related API's to be enabled for your project. Please refer to the [Google Cloud plugin](google-cloud.md#set-up-a-google-cloud-account) documentation for more details.
+Firebase Genkit Monitoring is powered by Google's Cloud operation suite. This
+requires telemetry related API's to be enabled for your project. Please refer
+to the [Google Cloud plugin](google-cloud.md#set-up-a-google-cloud-account)
+documentation for more details.
 
-Grant the following roles to the **"Default compute service account"** within the [Google Cloud IAM Console](https://console.cloud.google.com/iam-admin/iam):
+Grant the following roles to the **"Default compute service account"** within
+the [Google Cloud IAM Console](https://console.cloud.google.com/iam-admin/iam):
 
 - **Monitoring Metric Writer** (roles/monitoring.metricWriter)
 - **Cloud Trace Agent** (roles/cloudtrace.agent)
@@ -87,11 +114,18 @@ This plugin shares [configuration options](google-cloud.md#plugin-configuration)
 
 You can use Cloud Firestore as a vector store for RAG indexing and retrieval.
 
-This section contains information specific to the `firebase` plugin and Cloud Firestore's vector search feature. See the [Retrieval-augmented generation](/../rag.md) page for a more detailed discussion on implementing RAG using Genkit.
+This section contains information specific to the `firebase` plugin and Cloud
+Firestore's vector search feature. See the
+[Retrieval-augmented generation](/../rag.md) page for a more detailed
+discussion on implementing RAG using Genkit.
 
-#### Using GCLOUD_SERVICE_ACCOUNT_CREDS and Firestore
+#### Using `GCLOUD_SERVICE_ACCOUNT_CREDS` and Firestore
 
-If you are using service account credentials by passing credentials directly via `GCLOUD_SERVICE_ACCOUNT_CREDS` and are also using Firestore as a vector store, you will need to pass credentials directly to the Firestore instance during initialization or the singleton may be initialized with application default credentials depending on plugin initialization order.
+If you are using service account credentials by passing credentials directly
+via `GCLOUD_SERVICE_ACCOUNT_CREDS` and are also using Firestore as a vector
+store, you need to pass credentials directly to the Firestore instance
+during initialization or the singleton may be initialized with application
+default credentials depending on plugin initialization order.
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->
@@ -111,7 +145,8 @@ if (process.env.GCLOUD_SERVICE_ACCOUNT_CREDS) {
 
 #### Define a Firestore retriever
 
-Use `defineFirestoreRetriever()` to create a retriever for Firestore vector-based queries.
+Use `defineFirestoreRetriever()` to create a retriever for Firestore
+vector-based queries.
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->
@@ -136,7 +171,8 @@ const retriever = defineFirestoreRetriever(ai, {
 
 #### Retrieve documents
 
-To retrieve documents using the defined retriever, pass the retriever instance and query options to `ai.retrieve`.
+To retrieve documents using the defined retriever, pass the retriever instance
+and query options to `ai.retrieve`.
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->
@@ -167,11 +203,16 @@ The following options can be passed to the `options` field in `ai.retrieve`:
   ```
 
 - **`collection`**: *(string)*
-  Override the default collection specified in the retriever configuration. This is useful for querying subcollections or dynamically switching between collections.
+  Override the default collection specified in the retriever configuration.
+- This is useful for querying subcollections or dynamically switching between
+- collections.
 
 #### Populate Firestore with Embeddings
 
-To populate your Firestore collection, use an embedding generator along with the Admin SDK. For example, the menu ingestion script from the [Retrieval-augmented generation](http://../rag.md) page could be adapted for Firestore in the following way:
+To populate your Firestore collection, use an embedding generator along with
+the Admin SDK. For example, the menu ingestion script from the
+[Retrieval-augmented generation](http://../rag.md) page could be adapted for
+Firestore in the following way:
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->
@@ -237,11 +278,16 @@ async function extractTextFromPdf(filePath: string) {
 }
 ```
 
-Firestore depends on indexes to provide fast and efficient querying on collections. (Note that "index" here refers to database indexes, and not Genkit's indexer and retriever abstractions.)
+Firestore depends on indexes to provide fast and efficient querying on
+collections. (Note that "index" here refers to database indexes, and not
+Genkit's indexer and retriever abstractions.)
 
-The prior example requires the `embedding` field to be indexed to work. To create the index:
+The prior example requires the `embedding` field to be indexed to work.
+To create the index:
 
-- Run the `gcloud` command described in the [Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes) section of the Firestore docs.
+- Run the `gcloud` command described in the
+[Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes)
+section of the Firestore docs.
 
   The command looks like the following:
 
@@ -251,21 +297,29 @@ The prior example requires the `embedding` field to be indexed to work. To creat
     --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=yourEmbeddingField
   ```
 
-  However, the correct indexing configuration depends on the queries you will make and the embedding model you're using.
+  However, the correct indexing configuration depends on the queries you
+  make and the embedding model you're using.
 
 
-- Alternatively, call `ai.retrieve()` and Firestore will throw an error with the correct command to create the index.
+- Alternatively, call `ai.retrieve()` and Firestore will throw an error with
+  the correct command to create the index.
 
 #### Learn more
 
-- See the [Retrieval-augmented generation](http://../rag.md) page for a general discussion on indexers and retrievers in Genkit.
-- See [Search with vector embeddings](https://firebase.google.com/docs/firestore/vector-search) in the Cloud Firestore docs for more on the vector search feature.
+- See the [Retrieval-augmented generation](http://../rag.md) page for a general discussion
+on indexers and retrievers in Genkit.
+- See [Search with vector embeddings](https://firebase.google.com/docs/firestore/vector-search) in the Cloud Firestore docs for more
+on the vector search feature.
 
 ### Deploy flows as Cloud Functions
 
-To deploy a flow with Cloud Functions, use the Firebase Functions library's native support for genkit. The `onCallGenkit` method allows
-you to create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd) from a flow. It will automatically support
-streaming and JSON requests. You can use the [Cloud Functions client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function) to call them.
+To deploy a flow with Cloud Functions, use the Firebase Functions library's
+built-in support for genkit. The `onCallGenkit` method lets
+you to create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd)
+from a flow. It automatically supports
+streaming and JSON requests. You can use the
+[Cloud Functions client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function)
+to call them.
 
 <!--See note above on prettier-ignore -->
 <!-- prettier-ignore -->