From 9ce522178cd0b97b826b8cc1bf03cb7499604331 Mon Sep 17 00:00:00 2001 From: Pavel Jbanov Date: Tue, 4 Feb 2025 15:48:55 -0500 Subject: [PATCH] docs: updated some docs (#1813) --- docs/cloud-run.md | 33 +++++++++++++++++++++------------ docs/plugin-authoring.md | 32 ++++++++++++-------------------- docs/tool-calling.md | 10 +++++----- 3 files changed, 38 insertions(+), 37 deletions(-) diff --git a/docs/cloud-run.md b/docs/cloud-run.md index e37b655c4..5551019a1 100644 --- a/docs/cloud-run.md +++ b/docs/cloud-run.md @@ -88,26 +88,32 @@ authorization: in the Cloud Run docs for information on providing these credentials. - **Authorization policy defined in code**: Use the authorization policy feature - of Genkit flows to verify authorization info using custom code. This is often, + of Genkit express plugin to verify authorization info using custom code. This is often, but not necessarily, token-based authorization. If you want to define an authorization policy in code, use the `authPolicy` parameter in the flow definition: ```ts -const myFlow = ai.defineFlow( - { - name: "myFlow", - authPolicy: (auth, input) => { - if (!auth) { - throw new Error("Authorization required."); +// middleware for handling auth tokens in headers. +const authMiddleware = async (req, resp, next) => { + // parse auth headers and convert to auth object. + (req as RequestWithAuth).auth = { + user: await verifyAuthToken(req.header('authorization')), + }; + next(); +}; + +app.post( + '/simpleFlow', + authMiddleware, + expressHandler(simpleFlow, { + authPolicy: ({ auth }) => { + if (!auth.user) { + throw new Error('not authorized'); } - // Custom checks go here... }, - }, - async () => { - // ... - } + }) ); ``` @@ -116,6 +122,9 @@ of the request object. You typically set this property using Express middleware. See [Authorization and integrity](/docs/genkit/auth#non-firebase_http_authorization). +Refer to [express plugin documentation](https://js.api.genkit.dev/modules/_genkit-ai_express.html) +for more details. + ### Make API credentials available to deployed flows Once deployed, your flows need some way to authenticate with any remote services diff --git a/docs/plugin-authoring.md b/docs/plugin-authoring.md index 3929b0994..dcd4d5fb7 100644 --- a/docs/plugin-authoring.md +++ b/docs/plugin-authoring.md @@ -64,9 +64,8 @@ requires a secret value, such as API keys, you should offer both an option and a default environment variable to configure it: ```ts -import { Genkit, z } from 'genkit'; +import { GenkitError, Genkit, z } from 'genkit'; import { GenkitPlugin, genkitPlugin } from 'genkit/plugin'; -import { GenkitError } from '@genkit-ai/core'; interface MyPluginOptions { apiKey?: string; @@ -107,23 +106,21 @@ A custom model generally consists of three components: 3. A function that implements the model accepting `GenerateRequest` and returning `GenerateResponse`. -To build a model plugin, you'll need to use the `@genkit-ai/ai` package: - -```posix-terminal -npm i --save @genkit-ai/ai -``` +To build a model plugin, you'll need to use the `genkit/model` package: At a high level, a model plugin might look something like this: ```ts import { genkitPlugin, GenkitPlugin } from 'genkit/plugin'; -import { GenkitError } from '@genkit-ai/core'; -import { GenerationCommonConfigSchema } from '@genkit-ai/ai/model'; -import { simulateSystemPrompt } from '@genkit-ai/ai/model/middleware'; -import { z } from 'genkit'; +import { GenerationCommonConfigSchema } from 'genkit/model'; +import { simulateSystemPrompt } from 'genkit/model/middleware'; +import { Genkit, GenkitError, z } from 'genkit'; +export interface MyPluginOptions { + // ... +} -export function myPlugin(options?: MyPluginOptions) { +export function myPlugin(options?: MyPluginOptions): GenkitPlugin { return genkitPlugin('my-plugin', async (ai: Genkit) => { ai.defineModel({ // be sure to include your plugin as a provider prefix @@ -153,8 +150,6 @@ export function myPlugin(options?: MyPluginOptions) { }); }); }; - - ``` #### Transforming Requests and Responses @@ -174,7 +169,7 @@ export a model reference from your package that includes only the metadata for a model but not its implementation: ```ts -import { modelRef } from "@genkit-ai/ai/model"; +import { modelRef } from "genkit/model"; export myModelRef = modelRef({ name: "my-plugin/my-model", @@ -189,11 +184,10 @@ When calling `generate()`, model references and string model names can be used i ```ts import { myModelRef } from 'genkitx-my-plugin'; -import { generate } from '@genkit-ai/ai'; -generate({ model: myModelRef }); +ai.generate({ model: myModelRef }); // is equivalent to -generate({ model: 'my-plugin/my-model' }); +ai.generate({ model: 'my-plugin/my-model' }); ``` ## Publishing a plugin @@ -209,8 +203,6 @@ plugin: - `genkit-retriever`: include this keyword if your package defines any retrievers. - `genkit-indexer`: include this keyword if your package defines any indexers. - `genkit-embedder`: include this keyword if your package defines any indexers. -- `genkit-tracestore`: include this keyword if your package defines any trace stores. -- `genkit-statestore`: include this keyword if your package defines any state stores. - `genkit-telemetry`: include this keyword if your package defines a telemetry provider. - `genkit-deploy`: include this keyword if your package includes helpers to deploy Genkit apps to cloud providers. - `genkit-flow`: include this keyword if your package enhances Genkit flows. diff --git a/docs/tool-calling.md b/docs/tool-calling.md index 3fbef9b27..ec7e3c259 100644 --- a/docs/tool-calling.md +++ b/docs/tool-calling.md @@ -120,11 +120,11 @@ const getWeather = ai.defineTool( ); ``` -The syntax here looks just like the `defineFlow()` syntax; however, all four of -the `name`, `description`, `inputSchema`, and `outputSchema` parameters are -required. When writing a tool definition, take special care with the wording and -descriptiveness of these parameters, as they are vital for the LLM to -effectively make use of the available tools. +The syntax here looks just like the `defineFlow()` syntax; however, `name`, +`description` and `inputSchema` parameters are required. When writing a tool +definition, take special care with the wording and descriptiveness of these +parameters, as they are vital for the LLM to effectively make use of the +available tools. ### Using tools