Merge remote-tracking branch 'origin' into inlined.auth

.github/workflows/samples.yml

@@ -0,0 +1,42 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Build Samples (only runs if /samples/** is changed)
+
+on: 
+  pull_request:
+    paths: samples/**
+
+env:
+  GITHUB_PULL_REQUEST_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+  GITHUB_PULL_REQUEST_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+
+jobs:
+  build:
+    name: Build Samples
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: pnpm/action-setup@v3
+    - name: Set up node v20
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20.x
+        cache: pnpm
+    - name: Install dependencies
+      run: pnpm install
+    - name: Build Samples
+      run: pnpm build:js-samples
+    - name: Validate working directory is clean
+      run: .github/workflows/scripts/ensure-clean-working-tree.sh

.github/workflows/scripts/ensure-clean-working-tree.sh

@@ -17,7 +17,7 @@
 if [ "$(git status --short)" ]
 then
     echo "Unclean git status"
-    git status --short
+    git status --long
     exit 1
 else 
     echo "Git status is clean"

docs/auth.md

@@ -10,16 +10,18 @@ are properly scoped to the user invoking the LLM, and the flow is being invoked
 only by verified client applications.
 
 Firebase Genkit provides mechanisms for managing authorization policies and
-contexts. Flows running on Firebase can use an auth policy callback (or helper)
-or Firebase will provide auth context into the flow where it can do its own checks.
-For non-Functions flows, auth can be managed and set as well through middleware.
+contexts. Flows running on Firebase can use an auth policy callback (or helper).
+Alternatively, Firebase also provides auth context into the flow where it can
+do its own  checks. For non-Functions flows, auth can be managed and set
+through middleware.
 
 ## Basic flow authorization
 
-Flows can check authorization in two ways: either the request binding (e.g. `onCallGenkit` for
-Cloud Functions for Fireabse or `express`) can enforce authorization, or those frameworks
-can pass auth policies to the flow itself where the flow will have access to the information
-for auth managed within the flow.
+Flows can check authorization in two ways: either the request binding
+(e.g. `onCallGenkit` for Cloud Functions for Firebase or `express`) can enforce
+authorization, or those frameworks can pass auth policies to the flow itself,
+where the flow has access to the information for auth managed within the
+flow.
 
 ```ts
 import { genkit, z } from 'genkit';
@@ -41,10 +43,11 @@ export const selfSummaryFlow = ai.defineFlow( {
 });
 ```
 
-It is up to the request binding to populate `context.auth` in this case. For example, `onCallGenkit`
-will automatically populate `context.auth` (Firebase Authentication), `context.app` (Firebase App Check),
-and `context.instanceIdToken` (Firebase Cloud Messaging). When calling a flow manually, you can add
-your own auth context manually.
+It is up to the request binding to populate `context.auth` in this case. For
+example, `onCallGenkit` automatically populates `context.auth`
+(Firebase Authentication), `context.app` (Firebase App Check), and
+`context.instanceIdToken` (Firebase Cloud Messaging). When calling a flow
+manually, you can add your own auth context manually.
 
 ```ts
 // Error: Authorization required.
@@ -111,15 +114,16 @@ genkit flow:run selfSummaryFlow '{"uid": "abc-def"}' --context '{"auth": {"email
 
 ## Cloud Functions for Firebase integration
 
-The Cloud Functions for Firebase SDK Firebase supports Genkit including integration with Firebase Auth / Google
-Cloud Identity Platform as well as built-in Firebase App Check support.
+The Cloud Functions for Firebase SDKs support Genkit including
+integration with Firebase Auth / Google Cloud Identity Platform, as well as
+built-in Firebase App Check support.
 
 ### Authorization
 
-The `onCallGenkit()` wrapper provided by the Firebase Functions library works natively with the
-Cloud Functions for Firebase
+The `onCallGenkit()` wrapper provided by the Firebase Functions library works
+natively with the Cloud Functions for Firebase
 [client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function).
-When using the SDK, the Firebase Auth header will automatically be included as
+When you use these SDKs, the Firebase Auth header is automatically included as
 long as your app client is also using the
 [Firebase Auth SDK](https://firebase.google.com/docs/auth).
 You can use Firebase Auth to protect your flows defined with `onCallGenkit()`:
@@ -145,12 +149,12 @@ export const selfSummary = onCallGenkit({
 }, selfSummaryFlow);
 ```
 
-When using the `onCallGenkit`, `context.auth` will be returned as an object with
+When you use `onCallGenkit`, `context.auth` is returned as an object with
 a `uid` for the user ID, and a `token` that is a
 [DecodedIdToken](https://firebase.google.com/docs/reference/admin/node/firebase-admin.auth.decodedidtoken).
-You can always retrieve this object at any time via `ai.currentContext()` as noted
-above. When running this flow during development, you would pass the user object
-in the same way:
+You can always retrieve this object at any time using `ai.currentContext()` as
+noted earlier. When running this flow during development, you would pass the
+user object in the same way:
 
 ```posix-terminal
 genkit flow:run selfSummaryFlow '{"uid": "abc-def"}' --context '{"auth": {"admin": true}}'
@@ -161,12 +165,14 @@ important that you use some sort of authorization mechanism to protect your data
 and the data of your customers. With that said, there are times when you need
 to deploy a Cloud Function with no code-based authorization checks (for example,
 your Function is not world-callable but instead is protected by
-[Cloud IAM](https://cloud.google.com/functions/docs/concepts/iam)). Cloud Functions
-for Firebase allows you to do this using the `invoker` property, which controls
-IAM access. The special value `'private'` leaves the function as the default IAM
-setting, which means that only callers with the [Cloud Run Invoker role](https://cloud.google.com/run/docs/reference/iam/roles)
+[Cloud IAM](https://cloud.google.com/functions/docs/concepts/iam)).
+Cloud Functions for Firebase lets you to do this using the `invoker` property,
+which controls IAM access. The special value `'private'` leaves the function as
+the default IAM setting, which means that only callers with the
+[Cloud Run Invoker role](https://cloud.google.com/run/docs/reference/iam/roles)
 can execute the function. You can instead provide the email address of a user
-or service account that should be granted permission to call this exact function.
+or service account that should be granted permission to call this exact
+function.
 
 <!-- prettier-ignore: see note above -->
 
@@ -191,8 +197,8 @@ export const selfSummary = onCallGenkit({
 Authentication on its own goes a long way to protect your app. But it's also
 important to ensure that only your client apps are calling your functions. The
 Firebase plugin for genkit includes first-class support for
-[Firebase App Check](https://firebase.google.com/docs/app-check). Simply add
-the following configuration options to your `onCallGenkit()`:
+[Firebase App Check](https://firebase.google.com/docs/app-check). Do this by
+adding the following configuration options to your `onCallGenkit()`:
 
 <!-- prettier-ignore: see note above -->
 
@@ -224,11 +230,11 @@ When deploying flows to a server context outside of Cloud Functions for
 Firebase, you'll want to have a way to set up your own authorization checks
 alongside the native flows. You have two options:
 
-1.  Use whatever server framework you like, and pass the auth context through via
-    the flow call as noted above.
+1.  Use whatever server framework you like, and pass the auth context through
+    using the flow call as noted earlier.
 
-1.  Use  `startFlowsServer()` available via `@genkit-ai/express` plugin and provide
-    Express auth middleware in the flow server config:
+1.  Use `startFlowsServer()`, which the `@genkit-ai/express` plugin
+    exposes, and provide Express auth middleware in the flow server config:
 
     ```ts
     import { genkit, z } from 'genkit';
@@ -267,11 +273,8 @@ alongside the native flows. You have two options:
           }
         })
       ],
-    });  // Registers the middleware
+    });  // Registers the auth provider middleware and policy
     ```
 
-    For more information about using Express, see the [Cloud Run](/genkit/cloud-run)
-    instructions.
-
-Please note, if you go with (1), you the `middleware` configuration option will
-be ignored by when the flow is invoked directly.
+    For more information about using Express, see the
+    [Cloud Run](/genkit/cloud-run) instructions.

docs/chat.md

@@ -19,7 +19,7 @@ If you want to run the code examples on this page, first complete the steps in
 the [Getting started](get-started) guide. All of the examples assume that you
 have already installed Genkit as a dependency in your project.
 
-Please note that the chat API is currently in beta and must be used from the
+Note that the chat API is currently in beta and must be used from the
 `genkit/beta` package.
 
 ## Chat session basics 

docs/devtools.md

@@ -3,7 +3,8 @@
 Firebase Genkit provides two key developer tools:
 
 - A Node.js CLI for command-line operations
-- An optional local web app, called the Developer UI, that interfaces with your Genkit configuration for interactive testing and development
+- An optional local web app, called the Developer UI, that interfaces with your
+Genkit configuration for interactive testing and development
 
 ### Command Line Interface (CLI)
 
@@ -15,9 +16,14 @@ npm install -D genkit-cli
 
 The CLI supports various commands to facilitate working with Genkit projects:
 
-- `genkit start -- <command to run your code>`: Start the developer UI and connect it to a running code process.
-- `genkit flow:run <flowName>`: Run a specified flow. Your runtime must already be running in a separate terminal with `GENKIT_ENV=dev` environment variable set.
-- `genkit eval:flow <flowName>`: Evaluate a specific flow. Your runtime must already be running in a separate terminal with `GENKIT_ENV=dev` environment variable set.
+- `genkit start -- <command to run your code>`: Start the developer UI and
+connect it to a running code process.
+- `genkit flow:run <flowName>`: Run a specified flow. Your runtime must already
+be running in a separate terminal with the `GENKIT_ENV=dev` environment 
+variable set.
+- `genkit eval:flow <flowName>`: Evaluate a specific flow. Your runtime must
+already be running in a separate terminal with the `GENKIT_ENV=dev` environment
+variable set.
 
 For a full list of commands, use:
 
@@ -27,17 +33,20 @@ npx genkit --help
 
 ### Genkit Developer UI
 
-The Genkit Developer UI is a local web app that allows you to interactively work with models, flows, prompts, and other elements in your Genkit project.
+The Genkit Developer UI is a local web app that allows you to 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 in your code by attaching to a running code process.
+The Developer UI is able to identify what Genkit components you have defined
+in your code by attaching to a running code process.
 
 To start the UI, run the following command:
 
 ```posix-terminal
 npx genkit start -- <command to run your code>
 ```
 
-The `<command to run your code>` will vary based on your project's setup and the file you want to execute. Here are some examples:
+The `<command to run your code>` will vary based on your project's setup and
+the file you want to execute. Here are some examples:
 
 ```posix-terminal
 # Running a typical development server
@@ -50,7 +59,8 @@ npx genkit start -- npx tsx --watch src/index.ts
 npx genkit start -- node --watch src/index.js
 ```
 
-Including the `--watch` option will enable the Developer UI to notice and reflect saved changes to your code without needing to restart it.
+Including the `--watch` option will enable the Developer UI to notice and
+reflect saved changes to your code without needing to restart it.
 
 After running the command, you will get an output like the following:
 
@@ -59,17 +69,22 @@ Telemetry API running on http://localhost:4033
 Genkit Developer UI: http://localhost:4000
 ```
 
-Open the local host address for the Genkit Developer UI in your browser to view it. You can also open it in the VS Code simple browser to view it alongside your code.
+Open the local host address for the Genkit Developer UI in your browser to
+view it. You can also open it in the VS Code simple browser to view it
+alongside your code.
 
-Alternatively, you can use add the `-o` option to the start command to automatically open the Developer UI in your default browser tab.
+Alternatively, you can use add the `-o` option to the start command to
+automatically open the Developer UI in your default browser tab.
 
 ```
 npx genkit start -o -- <command to run your code>
 ```
 
 ![Welcome to Genkit Developer UI](resources/welcome_to_genkit_developer_ui.png)
 
-The Developer UI has action runners for `flow`, `prompt`, `model`, `tool`, `retriever`, `indexer`, `embedder` and `evaluator` based on the components you have defined in your code.
+The Developer UI has action runners for `flow`, `prompt`, `model`, `tool`,
+`retriever`, `indexer`, `embedder` and `evaluator` based on the components
+you have defined in your code.
 
 Here's a quick gif tour with cats.
 

docs/dotprompt.md

@@ -402,8 +402,8 @@ these automatically-defined values and how you can use them.
 ### Multi-message prompts
 
 By default, Dotprompt constructs a single message with a "user" role.
-However, some prompts are best expressed as a combination of multiple messages,
-such as a system prompt.
+However, some prompts are best expressed as a combination of multiple
+messages, such as a system prompt.
 
 The `{{role}}` helper provides a simple way to
 construct multi-message prompts:
@@ -582,4 +582,4 @@ as in a prompt file, or a function that returns a `GenerateRequest`:
 
 ```ts
 {% includecode github_path="firebase/genkit/js/doc-snippets/src/dotprompt/index.ts" region_tag="definePromptFn" adjust_indentation="auto" %}
-```
+```

docs/evaluation.md

@@ -47,7 +47,7 @@ started](get-started.md) guide.</li>
 <li>Add the following code to define a simple RAG application to evaluate. For
 this guide, we use a dummy retriever that always returns the same documents.
 
-```js
+<pre class="prettyprint lang-js">
 import { genkit, z, Document } from "genkit";
 import {
   googleAI,
@@ -96,13 +96,13 @@ export const qaFlow = ai.defineFlow({
     return llmResponse.text;
   }
 );
-```
+</pre>
 </li>
 <li>(Optional) Add evaluation metrics to your application to use while
-evaluating. This guide uses the `MALICIOUSNESS` metric from the
-`genkitEval` plugin.
+evaluating. This guide uses the <code>MALICIOUSNESS</code> metric from the
+<code>genkitEval</code> plugin.
 
-```js
+<pre class="prettyprint lang-js">
 import { genkitEval, GenkitMetric } from "@genkit-ai/evaluator";
 import { gemini15Pro } from "@genkit-ai/googleai";
 
@@ -116,21 +116,21 @@ export const ai = genkit ({
     }),
   ]
 });
-```
+</pre>
 
-**Note:** The configuration above requires installing the
-[`@genkit-ai/evaluator`](https://www.npmjs.com/package/@genkit-ai/evaluator)
-package.
+<strong>Note:</strong> The configuration above requires installation of the
+<a href="https://www.npmjs.com/package/@genkit-ai/evaluator">
+<code>@genkit-ai/evaluator</code></a> package.
 
-```posix-terminal
-  npm install @genkit-ai/evaluator
-```
+<pre class="prettyprint lang-posix">
+npm install @genkit-ai/evaluator
+</pre>
 </li>
-<li>Start your Genkit application
+<li>Start your Genkit application.
 
-```posix-terminal
+<pre class="prettyprint lang-posix">
 genkit start -- <command to start your app>
-```
+</pre>
 </li>
 </ol>
 
@@ -173,7 +173,7 @@ to open the Datasets page.
 ### Run evaluation and view results
 
 To start evaluating the flow, click the **Run new evaluation** button on your
-dataset page. You can also start a new evaluation from the `Evaluations` tab.
+dataset page. You can also start a new evaluation from the _Evaluations_ tab.
 
 1. Select the `Flow` radio button to evaluate a flow.
 

genkit-tools/package.json

@@ -25,5 +25,5 @@
       "cross-spawn": "^7.0.5"
     }
   },
-  "packageManager": "pnpm@9.15.5+sha256.8472168c3e1fd0bff287e694b053fccbbf20579a3ff9526b6333beab8df65a8d"
+  "packageManager": "pnpm@10.2.0+sha256.72f1630812107c8723eb5be4517725f3e13f09cfd8f71571cf29f23ce318bdb7"
 }

js/package.json

@@ -34,5 +34,5 @@
       "cross-spawn": "^7.0.5"
     }
   },
-  "packageManager": "pnpm@9.15.5+sha256.8472168c3e1fd0bff287e694b053fccbbf20579a3ff9526b6333beab8df65a8d"
+  "packageManager": "pnpm@10.2.0+sha256.72f1630812107c8723eb5be4517725f3e13f09cfd8f71571cf29f23ce318bdb7"
 }