diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 77e35085e1..d50a2f6df5 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,5 +2,4 @@ Description here... Checklist (if applicable): - [ ] Tested (manually, unit tested, etc.) -- [ ] Changelog updated - [ ] Docs updated diff --git a/docs-go/plugins/firebase.md b/docs-go/plugins/firebase.md new file mode 100644 index 0000000000..a8cb3769d1 --- /dev/null +++ b/docs-go/plugins/firebase.md @@ -0,0 +1,188 @@ + +# Firebase Genkit Plugin + +The Firebase plugin for Genkit allows flows to integrate seamlessly with Firebase services, such as Firestore and Firebase Authentication. + +This plugin includes initialization for Firebase, a retriever for Firestore, and Firebase Authentication integration for enhanced flow security. + +## Prerequisites + +Before using this plugin, ensure you have the following prerequisites: + +1. **Google Cloud Account**: Sign up for a Google Cloud account if you don’t already have one [here](https://cloud.google.com/gcp). + +2. **Google Cloud SDK**: Ensure that you have the [Google Cloud SDK (gcloud)](https://cloud.google.com/sdk/docs/install) installed on your local machine. + +3. **Firebase Project**: Create a Firebase project or use an existing one. This project should have Firestore and Firebase Authentication enabled. + +4. **APIs to Enable**: + - [Firestore API](https://console.cloud.google.com/apis/library/firestore.googleapis.com) + - [Firebase Authentication API](https://console.cloud.google.com/apis/library/identitytoolkit.googleapis.com) + + You can enable these APIs from the [API Dashboard](https://console.cloud.google.com/apis/dashboard) of your Google Cloud project. + +5. **Firebase CLI**: To locally run or interact with Firebase, ensure you have the Firebase CLI installed. + +## Setup Instructions + +### Firebase Initialization + +To initialize Firebase in your Genkit project, first, import the `firebase` package: + +```go +import "github.com/firebase/genkit/go/plugins/firebase" +``` + +### Configuration + +You need to provide the Firebase configuration in the form of a `FirebasePluginConfig` struct. This example assumes that you are loading the project ID and Firestore collection from environment variables: + +```go +// Load project ID and Firestore collection from environment variables +projectID := os.Getenv("FIREBASE_PROJECT_ID") +collectionName := os.Getenv("FIRESTORE_COLLECTION") + +firebaseConfig := &firebase.FirebasePluginConfig{ + App: firebaseApp, // Pass the pre-initialized Firebase app + Retrievers: []firebase.RetrieverOptions{ + { + Name: "example-retriever", + Client: firestoreClient, + Collection: collectionName, + Embedder: embedder, + VectorField: "embedding", + ContentField: "text", + MetadataFields: []string{"metadata"}, + Limit: 10, + DistanceMeasure: firestore.DistanceMeasureEuclidean, + VectorType: firebase.Vector64, + }, + }, +} +``` + +### Initialize Firebase + +To initialize Firebase with the configuration, call the `Init` function. This ensures that the Firebase App is only initialized once: + +```go +ctx := context.Background() +err := firebase.Init(ctx, firebaseConfig) +if err != nil { + log.Fatalf("Error initializing Firebase: %v", err) +} +``` + +Once initialized, the Firebase app can be accessed using the `App` function: + +```go +app, err := firebase.App(ctx) +if err != nil { + log.Fatalf("Error getting Firebase app: %v", err) +} +``` + +### Firestore Retriever + +The Firebase plugin provides a Firestore retriever that can be used to query documents in a Firestore collection based on vector similarity. + +1. **Options Configuration**: + You need to configure `RetrieverOptions`, which include: + + - **Client**: The Firestore client. + - **Collection**: The Firestore collection you want to query. + - **Embedder**: The AI embedder to convert documents into embeddings. + - **VectorField**: The Firestore field containing the vector embeddings. + - **ContentField**: The field containing the text of the document. + - **MetadataFields**: A list of fields to include in the document metadata. + +```go +retrieverOptions := firebase.RetrieverOptions{ + Name: "example-retriever", + Client: firestoreClient, + Collection: collectionName, + Embedder: embedder, + VectorField: "embedding", + ContentField: "text", + MetadataFields: []string{"metadata"}, + Limit: 10, + DistanceMeasure: firestore.DistanceMeasureEuclidean, + VectorType: firebase.Vector64, +} +``` + +2. **Define the Retriever**: + +```go +retriever, err := firebase.DefineFirestoreRetriever(retrieverOptions) +if err != nil { + log.Fatalf("Error defining Firestore retriever: %v", err) +} +``` + +3. **Use the Retriever**: + +To perform a retrieval based on a query document: + +```go +req := &ai.RetrieverRequest{ + Document: ai.DocumentFromText("Query text", nil), +} + +resp, err := retriever.Retrieve(ctx, req) +if err != nil { + log.Fatalf("Error retrieving documents: %v", err) +} + +for _, doc := range resp.Documents { + log.Printf("Retrieved document: %s", doc.Content[0].Text) +} +``` + +### Firebase Authentication + +The Firebase plugin integrates Firebase Authentication to provide authorization and access control in Genkit flows. + +1. **Creating an Auth Object**: + Use the `NewAuth` function to create an auth object, specifying whether authentication is required and the policy for checking the context: + +```go +auth, err := firebase.NewAuth(ctx, nil, true) +if err != nil { + log.Fatalf("Error initializing Firebase Auth: %v", err) +} +``` + +2. **Providing Authentication Context**: + To use authentication, the `ProvideAuthContext` function extracts the authentication header from a request, verifies the token, and provides the auth context: + +```go +ctx, err := auth.ProvideAuthContext(ctx, "Bearer your-id-token") +if err != nil { + log.Fatalf("Error providing auth context: %v", err) +} +``` + +3. **Checking Authorization Policy**: + The `CheckAuthPolicy` function ensures that the current auth context satisfies any policies you’ve defined for your flow: + +```go +err := auth.CheckAuthPolicy(ctx, inputData) +if err != nil { + log.Fatalf("Authorization check failed: %v", err) +} +``` + +## Local Testing + +When testing flows locally, ensure that the Google Cloud credentials are available to the Firebase SDK. Use the following command to authenticate: + +```bash +gcloud auth application-default login +``` + +This will provide your local environment with the necessary credentials to interact with Firebase services. + +## Conclusion + +The Firebase Genkit Plugin simplifies the integration of Firebase services, including Firestore and Firebase Authentication, into your Genkit flows. With features like Firestore vector queries and flow-level authentication, it provides powerful tools for building intelligent, secure applications. diff --git a/docs/get-started.md b/docs/get-started.md index 0b7c02b890..ead5745fb2 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,189 +1,74 @@ # Get started -To get started with Firebase Genkit, install the Genkit CLI and run -`genkit init` in a Node.js project. The rest of this page shows you how. +This guide shows you how to get started with Genkit in a Node.js app. -## Requirements +## Prerequisites -Node.js 20 or later. +This guide assumes that you're familiar with building applications with Node.js. -Recommendation: The [`nvm`](https://github.com/nvm-sh/nvm) and -[`nvm-windows`](https://github.com/coreybutler/nvm-windows) tools are a -convenient way to install Node. +To complete this quickstart, make sure that your development environment meets the following requirements: -## Install Genkit {:#install} +* Node.js v20+ +* npm -Install the Genkit CLI by running the following command: +## Install Genkit dependencies -```posix-terminal -npm i -g genkit -``` - -This command installs the Genkit CLI into your Node installation directory -so that it can be used outside of a Node project. +Install the following Genkit dependencies to use Genkit in your project: -## Create and explore a sample project {:#explore} +* `@genkit-ai/ai` and `@genkit-ai/core` provide Genkit core capabilities. +* `@genkit-ai/googleai` provide access to the Google AI Gemini models. +* `genkit` provides the Genkit CLI and tooling to help you test and debug your solution later. -1. Create a new Node project: +```posix-terminal +npm install @genkit-ai/ai @genkit-ai/core @genkit-ai/googleai - ```posix-terminal - mkdir genkit-intro && cd genkit-intro +npm install -g genkit +``` - npm init -y - ``` +## Configure your model API key - Look at package.json and make sure the `main` field is set to - `lib/index.js`. +For this guide, we’ll show you how to use the Gemini API which provides a generous free tier and does not require a credit card to get started. To use the Gemini API, you'll need an API key. If you don't already have one, create a key in Google AI Studio. -1. Initialize a Genkit project: +Get an API key from Google AI Studio - ```posix-terminal - genkit init - ``` - - 1. Select your model: - - - {Gemini (Google AI)} - - The simplest way to get started is with Google AI Gemini API. Make sure - it's - [available in your region](https://ai.google.dev/available_regions). - - [Generate an API key](https://aistudio.google.com/app/apikey) for the - Gemini API using Google AI Studio. Then, set the `GOOGLE_GENAI_API_KEY` - environment variable to your key: - - ```posix-terminal - export GOOGLE_GENAI_API_KEY= - ``` +After you’ve created an API key, set the `GOOGLE_GENAI_API_KEY` environment variable to your key with the following command: - - {Gemini (Vertex AI)} - - If the Google AI Gemini API is not available in your region, consider - using the Vertex AI API which also offers Gemini and other models. You - will need to have a billing-enabled Google Cloud project, enable AI - Platform API, and set some additional environment variables: - - ```posix-terminal - gcloud services enable aiplatform.googleapis.com - - export GCLOUD_PROJECT= +``` +export GOOGLE_GENAI_API_KEY= +``` - export GCLOUD_LOCATION=us-central1 - ``` +Note: While this tutorial uses the Gemini API from AI Studio, Genkit supports a wide variety of model providers including [Gemini from Vertex AI](https://firebase.google.com/docs/genkit/plugins/vertex-ai#generative_ai_models), Anthropic’s Claude 3 models and Llama 3.1 through the [Vertex AI Model Garden](https://firebase.google.com/docs/genkit/plugins/vertex-ai#anthropic_claude_3_on_vertex_ai_model_garden), open source models through [Ollama](https://firebase.google.com/docs/genkit/plugins/ollama), and several other [community-supported providers](https://firebase.google.com/docs/genkit/models#models-supported) like OpenAI and Cohere. - See https://cloud.google.com/vertex-ai/generative-ai/pricing for Vertex AI pricing. - - 1. Choose default answers to the rest of the questions, which will - initialize your project folder with some sample code. +## Import the library - The `genkit init` command creates a sample source file, `index.ts`, which - defines a single flow, `menuSuggestionFlow`, that prompts an LLM to suggest - an item for a restaurant with a given theme. +Import the Genkit core libraries and the plugin for the Google AI Gemini APIs. - This file looks something like the following (the plugin configuration steps - might look different if you selected Vertex AI): +```javascript +import { generate } from '@genkit-ai/ai'; +import { configureGenkit } from '@genkit-ai/core'; +import { googleAI, gemini15Flash } from '@genkit-ai/googleai'; +``` - ```ts - import * as z from 'zod'; +## Make your first request - // Import the Genkit core libraries and plugins. - import { generate } from '@genkit-ai/ai'; - import { configureGenkit } from '@genkit-ai/core'; - import { defineFlow, startFlowsServer } from '@genkit-ai/flow'; - import { googleAI } from '@genkit-ai/googleai'; +Use the `generate` method to generate a text response. - // Import models from the Google AI plugin. The Google AI API provides access to - // several generative models. Here, we import Gemini 1.5 Flash. - import { gemini15Flash } from '@genkit-ai/googleai'; +```javascript +configureGenkit({ plugins: [googleAI()] }); - configureGenkit({ - plugins: [ - // Load the Google AI plugin. You can optionally specify your API key - // by passing in a config object; if you don't, the Google AI plugin uses - // the value from the GOOGLE_GENAI_API_KEY environment variable, which is - // the recommended practice. - googleAI(), - ], - // Log debug output to tbe console. - logLevel: 'debug', - // Perform OpenTelemetry instrumentation and enable trace collection. - enableTracingAndMetrics: true, - }); +const result = await generate({ + model: gemini15Flash, + prompt: 'Tell me a heroic story about a software developer.', +}); - // Define a simple flow that prompts an LLM to generate menu suggestions. - export const menuSuggestionFlow = defineFlow( - { - name: 'menuSuggestionFlow', - inputSchema: z.string(), - outputSchema: z.string(), - }, - async (subject) => { - // Construct a request and send it to the model API. - const llmResponse = await generate({ - prompt: `Suggest an item for the menu of a ${subject} themed restaurant`, - model: gemini15Flash, - config: { - temperature: 1, - }, - }); - - // Handle the response from the model API. In this sample, we just convert - // it to a string, but more complicated flows might coerce the response into - // structured output or chain the response into another LLM call, etc. - return llmResponse.text(); - } - ); - - // Start a flow server, which exposes your flows as HTTP endpoints. This call - // must come last, after all of your plug-in configuration and flow definitions. - // You can optionally specify a subset of flows to serve, and configure some - // HTTP server options, but by default, the flow server serves all defined flows. - startFlowsServer(); - ``` - - As you build out your app's AI features with Genkit, you will likely - create flows with multiple steps such as input preprocessing, more - sophisticated prompt construction, integrating external information - sources for retrieval-augmented generation (RAG), and more. - -1. Now you can run and explore Genkit features and the sample project locally - on your machine. Download and start the Genkit Developer UI: - - ```posix-terminal - genkit start - ``` - - Welcome to Genkit Developer UI - - The Genkit Developer UI is now running on your machine. When you run models - or flows in the next step, your machine will perform the orchestration tasks - needed to get the steps of your flow working together; calls to external - services such as the Gemini API will continue to be made against live - servers. - - Also, because you are in a dev environment, Genkit will store traces and - flow state in local files. - -1. The Genkit Developer UI downloads and opens automatically when you run the - `genkit start` command. - - The Developer UI lets you see which flows you have defined and models you - configured, run them, and examine traces of previous runs. Try out some of - these features: - - - On the **Run** tab, you will see a list of all of the flows that you have - defined and any models that have been configured by plugins. - - Click **menuSuggestionFlow** and try running it with some input text (for example, - `"cat"`). If all goes well, you'll be rewarded with a menu suggestion for a cat - themed restaurant. - - - On the **Inspect** tab, you'll see a history of flow executions. For each - flow, you can see the parameters that were passed to the flow and a - trace of each step as they ran. +console.log(result.text()) +``` ## Next steps -Check out how to build and deploy your Genkit app with [Firebase](firebase.md), -[Cloud Run](cloud-run.md), or any [Node.js platform](deploy-node.md). +Now that you’re set up to make model requests with Genkit, learn how to use more Genkit capabilities to build your AI-powered apps and workflows. To get started with additional Genkit capabilities, see the following guides: + +* [Developer tools](docs/genkit/devtools): Learn how to set up and use Genkit’s CLI and developer UI to help you locally test and debug your app. +* [Generating content](/docs/genkit/models): Learn how to use Genkit’s unified generation API to generate text and structured data from any supported model. +* [Creating flows](docs/genkit/flows): Learn how to use special Genkit functions, called flows, that provide end-to-end observability for workflows and rich debugging from Genkit tooling. +* [Prompting models](/docs/genkit/prompts): Learn how Genkit lets you treat prompt templates as functions, encapsulating model configurations and input/output schema. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index a7351a5b61..e3e72f53f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -56,7 +56,7 @@ See the following code samples for a concrete idea of how to use these capabilit - {Basic generation} ```javascript - import { generate } from `@genkit-ai/ai`; + import { generate } from '@genkit-ai/ai'; import { gemini15Flash, claude3Sonnet, llama31 } from '@genkit-ai/vertexai'; import { gpt4o } from 'genkitx-openai'; @@ -70,9 +70,9 @@ See the following code samples for a concrete idea of how to use these capabilit - {Structured generation} ```javascript - import { generate } from `@genkit-ai/ai`; - import { gemini15Flash } from `@genkit-ai/googleai`; - import { z } from `zod`; + import { generate } from '@genkit-ai/ai'; + import { gemini15Flash } from '@genkit-ai/googleai'; + import { z } from 'zod'; const result = await generate({ model: gemini15Flash, @@ -95,9 +95,9 @@ See the following code samples for a concrete idea of how to use these capabilit - {Tool calling} ```javascript - import { generate, defineTool } from `@genkit-ai/ai`; - import { gemini15Flash } from `@genkit-ai/googleai`; - import { z } from `zod`; + import { generate, defineTool } from '@genkit-ai/ai'; + import { gemini15Flash } from '@genkit-ai/googleai'; + import { z } from 'zod'; // Define tool to get weather data for a given location const lookupWeather = defineTool({ @@ -126,9 +126,9 @@ See the following code samples for a concrete idea of how to use these capabilit - {Retrieval} ```javascript - import { generate, retrieve } from `@genkit-ai/ai`; + import { generate, retrieve } from '@genkit-ai/ai'; import { devLocalRetrieverRef } from '@genkit-ai/dev-local-vectorstore'; - import { gemini15Flash } from `@genkit-ai/googleai`; + import { gemini15Flash } from '@genkit-ai/googleai'; // Sample assumes Genkit documentation has been chunked, stored, and indexed in // local vectorstore in previous step. diff --git a/docs/monitoring.md b/docs/monitoring.md index 591daafe37..0e288c2acc 100644 --- a/docs/monitoring.md +++ b/docs/monitoring.md @@ -31,7 +31,7 @@ want to enable TTL for the trace documents: https://firebase.google.com/docs/firestore/ttl ```ts -import { firebase } from '@genkit-ai/plugin-firebase'; +import { firebase } from '@genkit-ai/firebase'; configureGenkit({ plugins: [firebase()], diff --git a/docs/nextjs.md b/docs/nextjs.md index 9547e6f4b6..5245838ec9 100644 --- a/docs/nextjs.md +++ b/docs/nextjs.md @@ -127,21 +127,23 @@ Node.js 20 or later. import { useState } from 'react'; export default function Home() { - const [menuItem, setMenu] = useState(''); + const [menuItem, setMenuItem] = useState(''); async function getMenuItem(formData: FormData) { const theme = formData.get('theme')?.toString() ?? ''; const suggestion = await callMenuSuggestionFlow(theme); - setMenu(suggestion); + setMenuItem(suggestion); } return (
-