Skip to content

Docs/firebase fixes #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MaesterChestnut merged 3 commits into from
May 20, 2024
Merged

Docs/firebase fixes #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7b159fb
Modify firebase function related docs to pass firebase lint checks th…
May 16, 2024
5143c5f
use prettier-ignore instead of ignore whole file
May 16, 2024
cd31e56
Add clarity on purpose of prettier-ignore
May 20, 2024
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 20 additions & 9 deletions docs/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
<!-- NOTE: prettier-ignore used in some snippets to allow copy/paste into Firebase Functions which
use https://github.com/firebase/firebase-tools/blob/master/templates/init/functions/javascript/_eslintrc -->

# Authorization and integrity

When building any public-facing application, it's extremely important to protect
Expand Down Expand Up @@ -117,17 +120,19 @@ 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 `onFlow()`:

<!-- prettier-ignore: see note above -->

```ts
import { firebaseAuth } from '@genkit-ai/firebase/auth';
import { onFlow } from '@genkit-ai/firebase/functions';
import {firebaseAuth} from "@genkit-ai/firebase/auth";
import {onFlow} from "@genkit-ai/firebase/functions";

export const selfSummaryFlow = onFlow({
name: 'selfSummaryFlow',
name: "selfSummaryFlow",
inputSchema: z.string(),
outputSchema: z.string(),
authPolicy: firebaseAuth((user) => {
if (!user.email_verified && !user.admin) {
throw new Error('Email not verified');
throw new Error("Email not verified");
}
}),
}, (subject) => {...})
Expand All @@ -148,10 +153,12 @@ client, but in cases where you wish to allow unauthenticated access with special
handling for authenticated users (upselling features, say), then you can
configure the policy like so:

<!-- prettier-ignore: see note above -->

```ts
authPolicy: firebaseAuth((user) => {
if (user && !user.email_verified) {
throw new Error('Logged in users must have verified emails');
throw new Error("Logged in users must have verified emails");
}
}, {required: false}),
```
Expand All @@ -166,11 +173,13 @@ your Function is not world-callable but instead is protected by
indicate to the library that you are forgoing authorization checks by using the
`noAuth()` function:

<!-- prettier-ignore: see note above -->

```ts
import { onFlow, noAuth } from '@genkit-ai/firebase/functions';
import {onFlow, noAuth} from "@genkit-ai/firebase/functions";

export const selfSummaryFlow = onFlow({
name: 'selfSummaryFlow',
name: "selfSummaryFlow",
inputSchema: z.string(),
outputSchema: z.string(),
// WARNING: Only do this if you have some other gatekeeping in place, like
Expand All @@ -187,11 +196,13 @@ 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 `onFlow()`:

<!-- prettier-ignore: see note above -->

```ts
import { onFlow } from '@genkit-ai/firebase/functions';
import {onFlow} from "@genkit-ai/firebase/functions";

export const selfSummaryFlow = onFlow({
name: 'selfSummaryFlow',
name: "selfSummaryFlow",
inputSchema: z.string(),
outputSchema: z.string(),

Expand Down
28 changes: 17 additions & 11 deletions docs/firebase.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
<!-- NOTE: prettier-ignore used in some snippets to allow copy/paste into Firebase Functions which
use https://github.com/firebase/firebase-tools/blob/master/templates/init/functions/javascript/_eslintrc -->

# Genkit with Firebase Cloud Functions

Firebase Genkit includes a plugin that helps you deploy your flows to Firebase
Expand Down Expand Up @@ -69,14 +72,16 @@ deploying the default sample flow to Firebase.

1. Edit `src/index.ts` and add the following after the existing imports:

```js
import { defineSecret } from 'firebase-functions/params';
defineSecret('GOOGLE_GENAI_API_KEY');
```
<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import {defineSecret} from "firebase-functions/params";
defineSecret("GOOGLE_GENAI_API_KEY");
```

Now, when you deploy this function, your API key will be stored in
Cloud Secret Manager, and available from the Cloud Functions
environment.
Now, when you deploy this function, your API key will be stored in
Cloud Secret Manager, and available from the Cloud Functions
environment.

- {Gemini (Vertex AI)}

Expand Down Expand Up @@ -107,13 +112,14 @@ deploying the default sample flow to Firebase.

1. If you'll access your flow from a web app (which you will be doing in the
next section), in the `httpsOptions` parameter, set a CORS policy:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
export const menuSuggestionFlow = onFlow(
{
name: 'menuSuggestionFlow',
name: "menuSuggestionFlow",
// ...
httpsOptions: { cors: '*' }, // Add this line.
httpsOptions: {cors: true}, // Add this line.
},
async (subject) => {
// ...
Expand Down Expand Up @@ -229,7 +235,7 @@ app:
</div>
<div id="callGenkit" hidden>
Subject: <input type="text" id="subject" />
<button id="suggestMenuItem">Suggest a menu item</button>
<button id="suggestMenuItem">Suggest a menu theme</button>
<p id="menuItem"></p>
</div>
<script type="module">
Expand Down
84 changes: 52 additions & 32 deletions docs/plugins/firebase.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
<!-- NOTE: prettier-ignore used in some snippets to allow copy/paste into Firebase Functions which
use https://github.com/firebase/firebase-tools/blob/master/templates/init/functions/javascript/_eslintrc -->

# Firebase plugin

The Firebase plugin provides several integrations with Firebase services:
Expand All @@ -19,11 +22,13 @@ npm i --save @genkit-ai/firebase

To use this plugin, specify it when you call `configureGenkit()`:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import { firebase } from '@genkit-ai/firebase';
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
plugins: [firebase({ projectId: 'your-firebase-project' })],
plugins: [firebase({projectId: "your-firebase-project"})],
});
```

Expand Down Expand Up @@ -66,50 +71,56 @@ You can use Cloud Firestore as a vector store for RAG indexing and retrieval.
The `firebase` plugin provides a convenience function for defining Firestore
retrievers, `defineFirestoreRetriever()`:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import { defineFirestoreRetriever } from '@genkit-ai/firebase';
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';
import {defineFirestoreRetriever} from "@genkit-ai/firebase";
import {initializeApp} from "firebase-admin/app";
import {getFirestore} from "firebase-admin/firestore";

const app = initializeApp();
const firestore = getFirestore(app);

const yourRetrieverRef = defineFirestoreRetriever({
name: 'yourRetriever',
name: "yourRetriever",
firestore: getFirestore(app),
collection: 'yourCollection',
contentField: 'yourDataChunks',
vectorField: 'embedding',
collection: "yourCollection",
contentField: "yourDataChunks",
vectorField: "embedding",
embedder: textEmbeddingGecko,
distanceMeasure: 'COSINE', // 'EUCLIDEAN', 'DOT_PRODUCT', or 'COSINE' (default)
distanceMeasure: "COSINE", // "EUCLIDEAN", "DOT_PRODUCT", or "COSINE" (default)
});
```

To use it, pass it to the `retrieve()` function:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
const docs = await retrieve({
retriever: yourRetrieverRef,
query: 'look for something',
config: { limit: 5 },
query: "look for something",
config: {limit: 5},
});
```

For indexing, use an embedding generator along with the Admin SDK:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import { initializeApp } from 'firebase-admin';
import { getFirestore, FieldValue } from 'firebase-admin/firestore';
import { textEmbeddingGecko } from '@genkit-ai/vertexai';
import { embed } from '@genkit-ai/ai/embedder';
import {initializeApp} from "firebase-admin";
import {getFirestore, FieldValue} from "firebase-admin/firestore";
import {textEmbeddingGecko} from "@genkit-ai/vertexai";
import {embed} from "@genkit-ai/ai/embedder";

const app = initializeApp();
const firestore = getFirestore(app);

const indexConfig = {
collection: 'yourCollection',
contentField: 'yourDataChunks',
vectorField: 'embedding',
collection: "yourCollection",
contentField: "yourDataChunks",
vectorField: "embedding",
embedder: textEmbeddingGecko,
};

Expand Down Expand Up @@ -138,24 +149,28 @@ discussion on indexers and retrievers.

You can use Cloud Firestore to store traces:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import { firebase } from '@genkit-ai/firebase';
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
plugins: [firebase()],
traceStore: 'firebase',
traceStore: "firebase",
enableTracingAndMetrics: true,
});
```

By default, the plugin stores traces in a collection called `genkit-traces` in
the project's default database. To change either setting:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
firebase({
traceStore: {
collection: 'your-collection';
databaseId: 'your-db';
collection: "your-collection";
databaseId: "your-db";
}
})
```
Expand All @@ -171,17 +186,19 @@ to Firebase's
[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 -->
```js
import { firebase } from '@genkit-ai/firebase';
import { onFlow, noAuth } from '@genkit-ai/firebase/functions';
import {firebase} from "@genkit-ai/firebase";
import {onFlow, noAuth} from "@genkit-ai/firebase/functions";

configureGenkit({
plugins: [firebase()],
});

export const exampleFlow = onFlow(
{
name: 'exampleFlow',
name: "exampleFlow",
authPolicy: noAuth(), // WARNING: noAuth() creates an open endpoint!
},
async (prompt) => {
Expand All @@ -202,13 +219,14 @@ The `onFlow()` function has some options not present in `defineFlow()`:

- `httpsOptions`: an [`HttpsOptions`](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.httpsoptions)
object used to configure your Cloud Function:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
export const exampleFlow = onFlow(
{
name: 'exampleFlow',
name: "exampleFlow",
httpsOptions: {
cors: '*',
cors: true,
},
// ...
},
Expand All @@ -230,14 +248,16 @@ The `onFlow()` function has some options not present in `defineFlow()`:
This plugin provides a helper function to create authorization policies around
Firebase Auth:

<!--See note above on prettier-ignore -->
<!-- prettier-ignore -->
```js
import { firebaseAuth } from '@genkit-ai/firebase/auth';
import {firebaseAuth} from "@genkit-ai/firebase/auth";

export const exampleFlow = onFlow(
{
name: 'exampleFlow',
name: "exampleFlow",
authPolicy: firebaseAuth((user) => {
if (!user.email_verified) throw new Error('Requires verification!');
if (!user.email_verified) throw new Error("Requires verification!");
}),
},
async (prompt) => {
Expand Down