diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..586bfebaf --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,6 @@ +{ + "image": "mcr.microsoft.com/devcontainers/universal:2", + "features" : { + } +} + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 77e35085e..d50a2f6df 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/.gitignore b/.gitignore index 2862b8731..75ce9fff1 100644 --- a/.gitignore +++ b/.gitignore @@ -23,6 +23,7 @@ js/testapps/firebase-functions-sample1/public/config.js ui-debug.log firebase-debug.log **/*.env +.genkit # RAG sample files !js/testapps/rag/package.json js/testapps/rag/*.json diff --git a/docs/get-started.md b/docs/get-started.md index 0b7c02b89..ead5745fb 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 a7351a5b6..e3e72f53f 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 591daafe3..0e288c2ac 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 9547e6f4b..5245838ec 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 (
-