From e727968ab3b08b23646ff9d41dbdec417a6a0fea Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 21:33:47 -0500 Subject: [PATCH 01/11] docs: migrate from 0.9 guide --- docs/migrating-from-0.9.md | 251 +++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 docs/migrating-from-0.9.md diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md new file mode 100644 index 0000000000..dfe597e107 --- /dev/null +++ b/docs/migrating-from-0.9.md @@ -0,0 +1,251 @@ +# Migrating from 0.9 + +Genkit 1.0 introduces some of breaking changes alongside feature enhancements that improve overall functionality. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. +If you're using 0.5, use <> to upgrade to 0.9 first before upgrading to 1.0 + + +## Streaming functions do not require an await + + +**Old:** + +```ts +const { stream, response } = await ai.generateStream(`hi`); +const { stream, output } = await myflow.stream(`hi`); +``` + +**New** + +```ts +const { stream, response } = ai.generateStream(`hi`); +const { stream, output } = myflow.stream(`hi`); +``` + + +## Beta APIs + +We're introducing an unstable, Beta API channel, and leaving session, chat and Genkit client APIs in beta as we continue to refine them. + +Note: When using the APIs as part of the Beta API, you may experience breaking changes outside of SemVer. Breaking chanhes may occur on minor release (we'll try to avoid making breaking beta API changes on patch releases). + +**Old:** + +```ts +import { genkit } from 'genkit'; +const ai = genkit({...}) +const session = ai.createSession({ ... }) +``` + +**New** + +```ts +import { genkit } from 'genkit/beta'; +const ai = genkit({...}) +const session = ai.createSession({ ... }) +``` + +**Old:** + +```ts +import { runFlow, streamFlow } from 'genkit/client'; +``` + +**New** + +```ts +import { runFlow, streamFlow } from 'genkit/beta/client'; +``` + +## Introducing new `@genkit-ai/express` package + +The package contains utilities to make it easier to build an express app using Express.js. + +Refer to https://js.api.genkit.dev/modules/_genkit-ai_express.html for more details. + +`startFlowServer` has moved from part of the genkit object to the express package, to use startFlowServer, update your imports. + + +**Old:** + +```ts +const ai = genkit({ ... }); +ai.startFlowServer({ + flows: [myFlow1, myFlow2], +}); +``` + +**New** + +```ts +import { startFlowServer } from '@genkit-ai/express'; +startFlowServer({ + flows: [myFlow1, myFlow2], +}); +``` + +## Changes to Flows + +`run` function for custom trace blocks has moving to `ai.run` + +**Old:** + +```ts +ai.defineFlow({name: 'banana'}, async (input, streamingCallback) => { + const step = await run('myCode', async () => { + return 'something' + }); +}) +```ts + +**New** + +```ts +ai.defineFlow({name: 'banana'}, async (input, {context, sendChunk}) => { + const step = await ai.run('myCode', async () => { + return 'something' + }); +}) +``` + +`ai.defineStreamingFlow` has been removed. Use `ai.defineFlow` instead. Also, `streamingCallback` moved to a field inside the second argument of he flow function and is now called `sendChunk`. + +**Old:** + +```ts +const flow = ai.defineStreamingFlow({name: 'banana'}, async (input, streamingCallback) => { + streamingCallback({chunk: 1}); +}) + +const {stream} = await flow() +for await (const chunk of stream) { + // ... +} +``` + +**New** + +```ts +const flow = ai.defineFlow({name: 'banana'}, async (input, {context, sendChunk}) => { + sendChunk({chunk: 1}); +}) + +const {stream, output} = flow.stream(input); +for await (const chunk of stream) { + // ... +} +``` + +Flow auth is now called context. You can access auth as a field inside context: + +**Old:** + +```ts +ai.defineFlow({name: 'banana'}, async (input) => { + const auth = getFlowAuth(); + // ... +}) +``` + +**New** + +```ts +ai.defineFlow({name: 'banana'}, async (input, { context }) => { + const auth = context.auth; +}) +``` + +`onFlow` moved to `firebase-functions/https` package and got renamed to `onCallGenkit`. Here's how to use it: + +```ts +import { onCallGenkit } from "firebase-functions/https"; +import { defineSecret } from "firebase-functions/params"; +import { genkit, z } from "genkit"; + +const apiKey = defineSecret("GOOGLE_GENAI_API_KEY"); + +const ai = genkit({ + plugins: [googleAI()], + model: gemini15Flash, +}); + +export const jokeTeller = ai.defineFlow( + { + name: "jokeTeller", + inputSchema: z.string().nullable(), + outputSchema: z.string(), + streamSchema: z.string(), + }, + async (type, { sendChunk }) => { + const { stream, response } = ai.generateStream( + `Tell me a longish ${type ?? "dad"} joke.` + ); + for await (const chunk of stream) { + sendChunk(chunk.text); + } + return (await response).text; + } +); + +export const tellJoke = onCallGenkit({ secrets: [apiKey] }, jokeTeller); +``` + +## Prompts + +We've make several improvements to prompts. + +You can define separate templates for prompt, system and messages: + +```ts +const hello = ai.definePrompt({ + name: 'hello', + system: 'talk like a pirate.', + prompt: 'hello {{ name }}', + input: { + schema: z.object({ + name: z.string() + }) + } +}); +const { text } = await hello({name: 'Genkit'}); +``` + +or you can define multi-message prompts in the messages field + +```ts +const hello = ai.definePrompt({ + name: 'hello', + messages: '{{ role "system" }}talk like a pirate. {{ role "user" }} hello {{ name }}', + input: { + schema: z.object({ + name: z.string() + }) + } +}); +``` + +instead of prompt templates you can use a function + +```ts +ai.definePrompt({ + name: 'hello', + prompt: async (input, { context }) => { + return `hello ${input.name}` + }, + input: { + schema: z.object({ + name: z.string() + }) + } +}); +``` + +Note that you can access the context (including auth information) from within the prompt: + +```ts +const hello = ai.definePrompt({ + name: 'hello', + messages: 'hello {{ @auth.email }}', +}); +``` + + From c1753982a255892f2f22a9ff2ed3a34232577251 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:33:16 -0500 Subject: [PATCH 02/11] Update docs/migrating-from-0.9.md Co-authored-by: Sam Phillips --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index dfe597e107..a1d34970a8 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -1,6 +1,6 @@ # Migrating from 0.9 -Genkit 1.0 introduces some of breaking changes alongside feature enhancements that improve overall functionality. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. +Genkit 1.0 introduces many feature enhancements that improve overall functionality as well as some some breaking changes. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. If you're using 0.5, use <> to upgrade to 0.9 first before upgrading to 1.0 From 29eb10a934138e80d4308fb411dfaabb53e8370e Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:33:38 -0500 Subject: [PATCH 03/11] Update docs/migrating-from-0.9.md Co-authored-by: Sam Phillips --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index a1d34970a8..3e73994f6f 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -1,7 +1,7 @@ # Migrating from 0.9 Genkit 1.0 introduces many feature enhancements that improve overall functionality as well as some some breaking changes. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. -If you're using 0.5, use <> to upgrade to 0.9 first before upgrading to 1.0 +If you're using 0.5, use the [0.5 to 0.9 migration guide](https://firebase.google.com/docs/genkit/migrating-from-0.5) to upgrade to 0.9 first before upgrading to 1.0 ## Streaming functions do not require an await From b0ca4dd6666b66318ae42d687cd828cd61d23b69 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:33:57 -0500 Subject: [PATCH 04/11] Update docs/migrating-from-0.9.md --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index 3e73994f6f..c996fa6f28 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -1,6 +1,6 @@ # Migrating from 0.9 -Genkit 1.0 introduces many feature enhancements that improve overall functionality as well as some some breaking changes. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. +Genkit 1.0 introduces many feature enhancements that improve overall functionality as well as some breaking changes. If you have been developing applications with Genkit 0.9, you will need to update your application code when you upgrade to the latest version. This guide outlines the most significant changes and offers steps to migrate your existing applications smoothly. If you're using 0.5, use the [0.5 to 0.9 migration guide](https://firebase.google.com/docs/genkit/migrating-from-0.5) to upgrade to 0.9 first before upgrading to 1.0 From 92fe72932c28c97f30071e34263bd299545d5eb0 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:34:36 -0500 Subject: [PATCH 05/11] Update docs/migrating-from-0.9.md Co-authored-by: Sam Phillips --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index c996fa6f28..ef2a28d72f 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -58,7 +58,7 @@ import { runFlow, streamFlow } from 'genkit/beta/client'; ## Introducing new `@genkit-ai/express` package -The package contains utilities to make it easier to build an express app using Express.js. +This new package contains utilities to make it easier to build an express app using Express.js. Refer to https://js.api.genkit.dev/modules/_genkit-ai_express.html for more details. From ed39b9451eabd11bfb214c0bf2c2dca449d403e3 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:35:11 -0500 Subject: [PATCH 06/11] Update docs/migrating-from-0.9.md --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index ef2a28d72f..edce9e548e 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -58,7 +58,7 @@ import { runFlow, streamFlow } from 'genkit/beta/client'; ## Introducing new `@genkit-ai/express` package -This new package contains utilities to make it easier to build an express app using Express.js. +This new package contains utilities to make it easier to build an Express.js server with Genkit. Refer to https://js.api.genkit.dev/modules/_genkit-ai_express.html for more details. From d69ec0a078e779eb102c1623c9867b5211e01b06 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:35:22 -0500 Subject: [PATCH 07/11] Update docs/migrating-from-0.9.md Co-authored-by: Sam Phillips --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index edce9e548e..81e563f705 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -62,7 +62,7 @@ This new package contains utilities to make it easier to build an Express.js ser Refer to https://js.api.genkit.dev/modules/_genkit-ai_express.html for more details. -`startFlowServer` has moved from part of the genkit object to the express package, to use startFlowServer, update your imports. +`startFlowServer` has moved from part of the genkit object to this new `@genkit-ai/express` package, to use startFlowServer, update your imports. **Old:** From 2e8f2b666d6a6197ceb2db25d631a4f40c1d4ab6 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Wed, 5 Feb 2025 22:35:59 -0500 Subject: [PATCH 08/11] Update docs/migrating-from-0.9.md Co-authored-by: Sam Phillips --- docs/migrating-from-0.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index 81e563f705..f127b62226 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -85,7 +85,7 @@ startFlowServer({ ## Changes to Flows -`run` function for custom trace blocks has moving to `ai.run` +The `run` function for custom trace blocks has moved to part of the `genkit` object, invoke it with `ai.run` instead **Old:** From 0a81ceb47f2c2a3806128c9b5b59f9e0296b331c Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Thu, 6 Feb 2025 14:33:32 -0500 Subject: [PATCH 09/11] fixes --- docs/migrating-from-0.9.md | 84 ++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 22 deletions(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index f127b62226..da7b6cab9d 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -4,27 +4,16 @@ Genkit 1.0 introduces many feature enhancements that improve overall functionali If you're using 0.5, use the [0.5 to 0.9 migration guide](https://firebase.google.com/docs/genkit/migrating-from-0.5) to upgrade to 0.9 first before upgrading to 1.0 -## Streaming functions do not require an await - - -**Old:** - -```ts -const { stream, response } = await ai.generateStream(`hi`); -const { stream, output } = await myflow.stream(`hi`); -``` - -**New** - -```ts -const { stream, response } = ai.generateStream(`hi`); -const { stream, output } = myflow.stream(`hi`); -``` - - ## Beta APIs -We're introducing an unstable, Beta API channel, and leaving session, chat and Genkit client APIs in beta as we continue to refine them. +We're introducing an unstable, Beta API channel, and leaving session, chat and Genkit client APIs in beta as we continue to refine them. More specifically the following functions are currently in the beta namespace: + + * `ai.chat` + * `ai.createSession` + * `ai.loadSession` + * `ai.currentSession` + * `ai.defineFormat` + * `ai.defineInterrupt` Note: When using the APIs as part of the Beta API, you may experience breaking changes outside of SemVer. Breaking chanhes may occur on minor release (we'll try to avoid making breaking beta API changes on patch releases). @@ -85,12 +74,18 @@ startFlowServer({ ## Changes to Flows +There are several changes to flows in 1.0: + - `ai.defineStreamingFlow` consilidated into `ai.defineFlow`, + - `onFlow` replaced by `onCallGenkit`, + - `run` moved to `ai.run`, + - changes to working with auth. + The `run` function for custom trace blocks has moved to part of the `genkit` object, invoke it with `ai.run` instead **Old:** ```ts -ai.defineFlow({name: 'banana'}, async (input, streamingCallback) => { +ai.defineFlow({name: 'banana'}, async (input) => { const step = await run('myCode', async () => { return 'something' }); @@ -100,7 +95,7 @@ ai.defineFlow({name: 'banana'}, async (input, streamingCallback) => { **New** ```ts -ai.defineFlow({name: 'banana'}, async (input, {context, sendChunk}) => { +ai.defineFlow({name: 'banana'}, async (input) => { const step = await ai.run('myCode', async () => { return 'something' }); @@ -135,7 +130,7 @@ for await (const chunk of stream) { } ``` -Flow auth is now called context. You can access auth as a field inside context: +FlowAuth auth is now called context. You can access auth as a field inside context: **Old:** @@ -156,6 +151,33 @@ ai.defineFlow({name: 'banana'}, async (input, { context }) => { `onFlow` moved to `firebase-functions/https` package and got renamed to `onCallGenkit`. Here's how to use it: +**Old** + +```ts +import { onFlow } from "@genkit-ai/firebase/functions"; + +export const generatePoem = onFlow( + ai, + { + name: "jokeTeller", + inputSchema: z.string().nullable(), + outputSchema: z.string(), + streamSchema: z.string(), + }, + async (type, streamingCallback) => { + const { stream, response } = await ai.generateStream( + `Tell me a longish ${type ?? "dad"} joke.` + ); + for await (const chunk of stream) { + streamingCallback(chunk.text); + } + return (await response).text; + } +); +``` + +**New** + ```ts import { onCallGenkit } from "firebase-functions/https"; import { defineSecret } from "firebase-functions/params"; @@ -249,3 +271,21 @@ const hello = ai.definePrompt({ ``` + +## Streaming functions do not require an await + + +**Old:** + +```ts +const { stream, response } = await ai.generateStream(`hi`); +const { stream, output } = await myflow.stream(`hi`); +``` + +**New** + +```ts +const { stream, response } = ai.generateStream(`hi`); +const { stream, output } = myflow.stream(`hi`); +``` + From 87d39b32986b5337719a69b60828214372683410 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Thu, 6 Feb 2025 14:45:50 -0500 Subject: [PATCH 10/11] more fixes --- docs/migrating-from-0.9.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index da7b6cab9d..93548e4a79 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -90,7 +90,7 @@ ai.defineFlow({name: 'banana'}, async (input) => { return 'something' }); }) -```ts +``` **New** @@ -213,9 +213,9 @@ export const tellJoke = onCallGenkit({ secrets: [apiKey] }, jokeTeller); ## Prompts -We've make several improvements to prompts. +We've make several changes and improvements to prompts. -You can define separate templates for prompt, system and messages: +You can define separate templates for prompt and system messages: ```ts const hello = ai.definePrompt({ From 55c991554c0158464caa8f3d98ee1ff6c7c0a503 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Thu, 6 Feb 2025 15:00:15 -0500 Subject: [PATCH 11/11] auth --- docs/migrating-from-0.9.md | 75 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/docs/migrating-from-0.9.md b/docs/migrating-from-0.9.md index 93548e4a79..cfec75a46a 100644 --- a/docs/migrating-from-0.9.md +++ b/docs/migrating-from-0.9.md @@ -149,6 +149,81 @@ ai.defineFlow({name: 'banana'}, async (input, { context }) => { }) ``` +also, if you've been using auth policies, they've been removed from `defineFlow` and are not handled depending on the server you're using: + +**Old:** + +```ts +export const simpleFlow = ai.defineFlow( + { + name: 'simpleFlow', + inputSchema: z.object({ uid: z.string() }), + outputSchema: z.string(), + authPolicy: (auth, input) => { + if (!auth) { + throw new Error('Authorization required.'); + } + if (input.uid !== auth.uid) { + throw new Error('You may only summarize your own profile data.'); + } + }, + }, + async (input) => { + // Flow logic here... + } +); +``` + +With express you would do something like this: + +**New:** + +```ts +import { UserFacingError } from 'genkit'; +import { ContextProvider, RequestData } from 'genkit/context'; +import { expressHandler, startFlowServer } from '@genkit-ai/express'; + +const context: ContextProvider = (req: RequestData) => { + return { + auth: parseAuthToken(req.headers['authorization']), + }; +}; + +export const simpleFlow = ai.defineFlow( + { + name: 'simpleFlow', + inputSchema: z.object({ uid: z.string() }), + outputSchema: z.string(), + }, + async (input, { context }) => { + if (!context.auth) { + throw new Error('Authorization required.'); + } + if (input.uid !== context.auth.uid) { + throw new Error('You may only summarize your own profile data.'); + } + // Flow logic here... + } +); + +const app = express(); +app.use(express.json()); +app.post( + '/simpleFlow', + expressHandler(simpleFlow, { context }) +); +app.listen(8080); + +// or + +startFlowServer( + flows: [withContextProvider(simpleFlow, context)], + port: 8080 +); + +``` + + `onFlow` moved to `firebase-functions/https` package and got renamed to `onCallGenkit`. Here's how to use it: **Old**