@genkit-ai/ai

import { z, Operation, ActionContext, ResolvableAction, ActionMetadata, Action, ActionRunOptions, JSONSchema7, ActionFnArg, StatusName, StreamingCallback, SimpleMiddleware, MiddlewareWithOptions, BackgroundAction, GenkitError } from '@genkit-ai/core'; import { Registry, ActionType, HasRegistry } from '@genkit-ai/core/registry'; import Handlebars from 'handlebars'; import { e as EmbedderParams, g as Embedding, c as EmbedderArgument, a as DocumentData, k as EmbeddingBatch, D as Document } from './document-JsI88Acr.mjs'; import { GenerateResponseChunk } from './generate/chunk.mjs'; import { GenerationCommonConfigSchema, ToolDefinition, MiddlewareRef, GenerateActionOptions, GenerateResponseChunkData, GenerateResponseData, GenerateRequest, ModelInfo, GenerateActionOptionsSchema, GenerateResponseSchema, GenerateResponseChunkSchema, Role, GenerateActionOutputConfig, GenerateRequestSchema, MessageData, CandidateData, GenerationUsage } from './model-types.mjs'; import { Session } from './session.mjs'; import { GenerateResponse } from './generate/response.mjs'; import { Part, ToolRequestPart, ToolResponsePart, MultipartToolResponseSchema, MediaPart } from './parts.mjs'; import { Formatter } from './formats/types.mjs'; import { ResourceArgument } from './resource.mjs'; /** * Copyright 2026 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * `GenkitAI` encapsulates Genkit's AI APIs. */ declare class GenkitAI { readonly registry: Registry; constructor(registry: Registry); /** * Embeds the given `content` using the specified `embedder`. */ embed<CustomOptions extends z.ZodTypeAny>(params: EmbedderParams<CustomOptions>): Promise<Embedding[]>; /** * A veneer for interacting with embedder models in bulk. */ embedMany<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny>(params: { embedder: EmbedderArgument<ConfigSchema>; content: string[] | DocumentData[]; metadata?: Record<string, unknown>; options?: z.infer<ConfigSchema>; }): Promise<EmbeddingBatch>; /** * Make a generate call to the default model with a simple text prompt. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * model: googleAI.model('gemini-flash-latest'), // default model * }) * * const { text } = await ai.generate('hi'); * ``` */ generate<O extends z.ZodTypeAny = z.ZodTypeAny>(strPrompt: string): Promise<GenerateResponse<z.infer<O>>>; /** * Make a generate call to the default model with a multipart request. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * model: googleAI.model('gemini-flash-latest'), // default model * }) * * const { text } = await ai.generate([ * { media: {url: 'http://....'} }, * { text: 'describe this image' } * ]); * ``` */ generate<O extends z.ZodTypeAny = z.ZodTypeAny>(parts: Part[]): Promise<GenerateResponse<z.infer<O>>>; /** * Generate calls a generative model based on the provided prompt and configuration. If * `messages` is provided, the generation will include a conversation history in its * request. If `tools` are provided, the generate method will automatically resolve * tool calls returned from the model unless `returnToolRequests` is set to `true`. * * See {@link GenerateOptions} for detailed information about available options. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * }) * * const { text } = await ai.generate({ * system: 'talk like a pirate', * prompt: [ * { media: { url: 'http://....' } }, * { text: 'describe this image' } * ], * messages: conversationHistory, * tools: [ userInfoLookup ], * model: googleAI.model('gemini-flash-latest'), * }); * ``` */ generate<O extends z.ZodTypeAny = z.ZodTypeAny, CustomOptions extends z.ZodTypeAny = typeof GenerationCommonConfigSchema>(opts: GenerateOptions<O, CustomOptions> | PromiseLike<GenerateOptions<O, CustomOptions>>): Promise<GenerateResponse<z.infer<O>>>; /** * Make a streaming generate call to the default model with a simple text prompt. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * model: googleAI.model('gemini-flash-latest'), // default model * }) * * const { response, stream } = ai.generateStream('hi'); * for await (const chunk of stream) { * console.log(chunk.text); * } * console.log((await response).text); * ``` */ generateStream<O extends z.ZodTypeAny = z.ZodTypeAny>(strPrompt: string): GenerateStreamResponse<z.infer<O>>; /** * Make a streaming generate call to the default model with a multipart request. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * model: googleAI.model('gemini-flash-latest'), // default model * }) * * const { response, stream } = ai.generateStream([ * { media: {url: 'http://....'} }, * { text: 'describe this image' } * ]); * for await (const chunk of stream) { * console.log(chunk.text); * } * console.log((await response).text); * ``` */ generateStream<O extends z.ZodTypeAny = z.ZodTypeAny>(parts: Part[]): GenerateStreamResponse<z.infer<O>>; /** * Streaming generate calls a generative model based on the provided prompt and configuration. If * `messages` is provided, the generation will include a conversation history in its * request. If `tools` are provided, the generate method will automatically resolve * tool calls returned from the model unless `returnToolRequests` is set to `true`. * * See {@link GenerateOptions} for detailed information about available options. * * ```ts * const ai = genkit({ * plugins: [googleAI()], * }) * * const { response, stream } = ai.generateStream({ * system: 'talk like a pirate', * prompt: [ * { media: { url: 'http://....' } }, * { text: 'describe this image' } * ], * messages: conversationHistory, * tools: [ userInfoLookup ], * model: googleAI.model('gemini-flash-latest'), * }); * for await (const chunk of stream) { * console.log(chunk.text); * } * console.log((await response).text); * ``` */ generateStream<O extends z.ZodTypeAny = z.ZodTypeAny, CustomOptions extends z.ZodTypeAny = typeof GenerationCommonConfigSchema>(opts: GenerateStreamOptions<O, CustomOptions> | PromiseLike<GenerateStreamOptions<O, CustomOptions>>): GenerateStreamResponse<z.infer<O>>; /** * Checks the status of of a given operation. Returns a new operation which will contain the updated status. * * ```ts * let operation = await ai.generateOperation({ * model: googleAI.model('veo-2.0-generate-001'), * prompt: 'A banana riding a bicycle.', * }); * * while (!operation.done) { * operation = await ai.checkOperation(operation!); * await new Promise((resolve) => setTimeout(resolve, 5000)); * } * ``` * * @param operation * @returns */ checkOperation<T>(operation: Operation<T>): Promise<Operation<T>>; /** * Cancels a given operation. Returns a new operation which will contain the updated status. * * @param operation * @returns */ cancelOperation<T>(operation: Operation<T>): Promise<Operation<T>>; /** * A flow step that executes the provided function. Each run step is recorded separately in the trace. * * ```ts * ai.defineFlow('hello', async() => { * await ai.run('step1', async () => { * // ... step 1 * }); * await ai.run('step2', async () => { * // ... step 2 * }); * return result; * }) * ``` */ run<T>(name: string, func: () => Promise<T>): Promise<T>; /** * A flow step that executes the provided function. Each run step is recorded separately in the trace. * * ```ts * ai.defineFlow('hello', async(name) => { * const greeting = await ai.run('step1', name, async (input) => { * return `Hello, ${input}!`; * }); * const result = await ai.run('step2', greeting, async (input) => { * // ... step 2 * }); * return result; * }) */ run<T>(name: string, input: any, func: (input?: any) => Promise<T>): Promise<T>; /** * Gets the current session if running within one, otherwise throws a {@link GenkitError}. * * @beta */ currentSession<S = any>(): Session<S>; /** * Returns current action (or flow) invocation context. Can be used to access things like auth * data set by HTTP server frameworks. If invoked outside of an action (e.g. flow or tool) will * return `undefined`. */ currentContext(): ActionContext | undefined; } /** * Copyright 2026 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * The v2 plugin interface for Genkit. Plugins implement this interface to provide * models, tools, middleware, and other actions to the Genkit framework. */ interface GenkitPluginV2 { version: 'v2'; name: string; init?: () => ResolvableAction[] | Promise<ResolvableAction[]>; resolve?: (actionType: ActionType, name: string) => ResolvableAction | undefined | Promise<ResolvableAction | undefined>; list?: () => ActionMetadata[] | Promise<ActionMetadata[]>; model(name: string): Promise<ModelAction>; middleware?: () => GenerateMiddleware<any, any>[]; } /** * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * Interface for tools that support the interrupts / human-in-the-loop pattern. * Provides `respond` and `restart` methods for resuming interrupted tool calls. * @beta */ interface Resumable { /** * respond constructs a tool response corresponding to the provided interrupt tool request * using the provided reply data, validating it against the output schema of the tool if * it exists. * * @beta */ respond( /** The interrupt tool request to which you want to respond. */ interrupt: ToolRequestPart, /** * The data with which you want to respond. Must conform to a tool's output schema or an * interrupt's input schema. **/ outputData: z.infer<O>, options?: { metadata?: Record<string, any>; }): ToolResponsePart; /** * restart constructs a tool request corresponding to the provided interrupt tool request * that will then re-trigger the tool after e.g. a user confirms. The `resumedMetadata` * supplied to this method will be passed to the tool to allow for custom handling of * restart logic. * * @param interrupt The interrupt tool request you want to restart. * @param resumedMetadata The metadata you want to provide to the tool to aide in reprocessing. Defaults to `true` if none is supplied. * @param options Additional options for restarting the tool. * * @beta */ restart(interrupt: ToolRequestPart, resumedMetadata?: any, options?: { /** * Replace the existing input arguments to the tool with different ones, for example * if the user revised an action before confirming. When input is replaced, the existing * tool request will be amended in the message history. **/ replaceInput?: z.infer; }): ToolRequestPart; } /** * An action with a `tool` type. */ type ToolAction = Action<I, O, z.ZodTypeAny, ToolRunOptions> & Resumable<I, O> & { __action: { metadata: { type: 'tool'; }; }; }; /** * An action with a `tool.v2` type. */ type MultipartToolAction = Action<I, typeof MultipartToolResponseSchema, z.ZodTypeAny, ToolRunOptions> & Resumable<I, O> & { __action: { metadata: { type: 'tool.v2'; }; }; }; /** * A dynamic action with a `tool` type. Dynamic tools are detached actions -- not associated with any registry. */ type DynamicToolAction = Action<I, O, z.ZodTypeAny, ToolRunOptions> & { /** @deprecated no-op, for backwards compatibility only. */ attach(registry: Registry): ToolAction<I, O>; } & Resumable<I, O> & { __action: { metadata: { type: 'tool'; }; }; }; /** Runtime options passed to a tool when it is executed by the framework. */ interface ToolRunOptions extends ActionRunOptions<z.ZodTypeAny> { /** * If resumed is supplied to a tool at runtime, that means that it was previously interrupted and this is a second * @beta **/ resumed?: boolean | Record<string, any>; /** The metadata from the tool request that triggered this run. */ metadata?: Record<string, any>; } /** * Configuration for a tool. */ interface ToolConfig { /** Unique name of the tool to use as a key in the registry. */ name: string; /** Description of the tool. This is passed to the model to help understand what the tool is used for. */ description: string; /** Input Zod schema. Mutually exclusive with `inputJsonSchema`. */ inputSchema?: I; /** Input JSON schema. Mutually exclusive with `inputSchema`. */ inputJsonSchema?: JSONSchema7; /** Output Zod schema. Mutually exclusive with `outputJsonSchema`. */ outputSchema?: O; /** Output JSON schema. Mutually exclusive with `outputSchema`. */ outputJsonSchema?: JSONSchema7; /** Metadata to be passed to the tool. */ metadata?: Record<string, any>; } /** * A reference to a tool in the form of a name, definition, or the action itself. */ type ToolArgument = string | ToolAction<I, O> | Action<I, O> | ExecutablePrompt<any, any, any>; /** * Converts an action to a tool action by setting the appropriate metadata. */ declare function asTool(registry: Registry, action: Action<I, O>): ToolAction<I, O>; /** * Resolves a mix of various formats of tool references to a list of tool actions by looking them up in the registry. */ declare function resolveTools<O extends z.ZodTypeAny = z.ZodTypeAny, CustomOptions extends z.ZodTypeAny = z.ZodTypeAny>(registry: Registry, tools?: (ToolArgument | ToolDefinition)[]): Promise<ToolAction[]>; declare function lookupToolByName(registry: Registry, name: string): Promise<ToolAction>; /** * Converts a tool action to a definition of the tool to be passed to a model. */ declare function toToolDefinition(tool: Action<z.ZodTypeAny, z.ZodTypeAny>): ToolDefinition; /** Options available inside a tool's implementation function, including `interrupt` and `context`. */ interface ToolFnOptions extends ActionFnArg<never> { /** * A function that can be called during tool execution that will result in the tool * getting interrupted (immediately) and tool request returned to the upstream caller. */ interrupt: (metadata?: Record<string, any>) => never; context: ActionContext; } /** The implementation function for a standard tool. Receives typed input and {@link ToolFnOptions}. */ type ToolFn = (input: z.infer, ctx: ToolFnOptions & ToolRunOptions) => Promise<z.infer<O>>; /** The implementation function for a multipart tool that can return structured output, content parts, and metadata. */ type MultipartToolFn = (input: z.infer, ctx: ToolFnOptions & ToolRunOptions) => Promise<{ output?: z.infer<O>; content?: Part[]; metadata?: Record<string, any>; }>; declare function defineTool(registry: Registry, config: { multipart: true; } & ToolConfig<I, O>, fn?: ToolFn<I, O>): MultipartToolAction<I, O>; declare function defineTool(registry: Registry, config: ToolConfig<I, O>, fn?: ToolFn<I, O>): ToolAction<I, O>; /** InterruptConfig defines the options for configuring an interrupt. */ type InterruptConfig = ToolConfig<I, R> & { /** requestMetadata adds additional `interrupt` metadata to the `toolRequest` generated by the interrupt */ requestMetadata?: Record<string, any> | ((input: z.infer) => Record<string, any> | Promise<Record<string, any>>); }; /** * restartTool constructs a tool request corresponding to the provided interrupt tool request * that will then re-trigger the tool after e.g. a user confirms. In contrast to ToolAction.restart, * this is a standalone utility that does not require an active ToolAction instance. * * @param interrupt The interrupt tool request you want to restart. * @param resumedMetadata The metadata you want to provide to the tool to aide in reprocessing. Defaults to `true` if none is supplied. * @param options Additional options for restarting the tool. * * @beta */ declare function restartTool(interrupt: ToolRequestPart, resumedMetadata?: any, options?: { /** * Replace the existing input arguments to the tool with different ones. **/ replaceInput?: any; }): ToolRequestPart; /** * respondTool constructs a tool response part corresponding to the provided interrupt tool request * that bypasses normal tool execution and sends a manual output result. In contrast to ToolAction.respond, * this is a standalone utility that does not require an active ToolAction instance. * * @param interrupt The interrupt tool request you are responding to. * @param responseData The manual output result you want to send back to the model. * @param options Additional options for responding to the tool. * * @beta */ declare function respondTool(interrupt: ToolRequestPart, responseData: any, options?: { metadata?: any; }): ToolResponsePart; declare function isToolRequest(part: Part): part is ToolRequestPart; declare function isToolResponse(part: Part): part is ToolResponsePart; declare function isDynamicTool(t: unknown): t is ToolAction | MultipartToolAction; declare function isMultipartTool(t: unknown): t is MultipartToolAction; declare function interrupt(config: InterruptConfig<I, O>): ToolAction<I, O>; declare function defineInterrupt(registry: Registry, config: InterruptConfig<I, O>): ToolAction<I, O>; /** * Thrown when tools execution is interrupted. It's meant to be caugh by the framework, not public API. */ declare class ToolInterruptError extends Error { readonly metadata?: Record<string, any> | undefined; constructor(metadata?: Record<string, any> | undefined); } declare function tool(config: { multipart: true; } & ToolConfig<I, O>, fn?: ToolFn<I, O>): MultipartToolAction<I, O>; declare function tool(config: ToolConfig<I, O>, fn?: ToolFn<I, O>): ToolAction<I, O>; /** * Defines a dynamic tool. Dynamic tools are just like regular tools but will not be registered in the * Genkit registry and can be defined dynamically at runtime. * * @deprecated renamed to {@link tool}. */ declare function dynamicTool(config: ToolConfig<I, O>, fn?: ToolFn<I, O>): DynamicToolAction<I, O>; /** * Copyright 2025 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** Descriptor for a registered middleware, returned by reflection API. */ declare const MiddlewareDescSchema: z.ZodObject<{ /** Unique name of the middleware. */ name: z.ZodString; /** Human-readable description of what the middleware does. */ description: z.ZodOptional<z.ZodString>; /** JSON Schema for the middleware's configuration. */ configSchema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>; /** User defined metadata for the middleware. */ metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>; }, "strip", z.ZodTypeAny, { name: string; metadata?: Record<string, any> | null | undefined; configSchema?: Record<string, any> | null | undefined; description?: string | undefined; }, { name: string; metadata?: Record<string, any> | null | undefined; configSchema?: Record<string, any> | null | undefined; description?: string | undefined; }>; /** Descriptor for a registered middleware, returned by reflection API. */ type MiddlewareDesc = z.infer<typeof MiddlewareDescSchema>; /** * Defines a Genkit Generate Middleware instance, which can be configured and registered. * When invoked with an optional configuration, it returns a reference suitable for * inclusion in a `GenerateOptions.use` array. */ interface GenerateMiddleware<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny, PluginOptions = void> extends MiddlewareDesc { /** Configures the middleware, returning a MiddlewareRef for usage in `generate({use: [...]})`. */ (config?: z.infer<ConfigSchema>): MiddlewareRef & { __def: GenerateMiddleware<ConfigSchema, PluginOptions>; }; /** The unique name of this middleware. */ name: string; /** An optional description of what the middleware does. */ description?: string; /** An optional Zod schema for validating the middleware's configuration. */ configSchema?: ConfigSchema; /** Metadata describing this middleware. */ metadata?: Record<string, any>; /** * Factory function that receives the validated configuration and creates * a `GenerateMiddlewareDef` holding the active hooks. */ instantiate: (options: MiddlewareFnOptions<ConfigSchema, PluginOptions>) => GenerateMiddlewareDef; /** * Optional plugin wrapper exposing this middleware for framework-level registration. */ plugin: (pluginOptions: PluginOptions) => GenkitPluginV2; /** Generates a JSON-compatible representation of the middleware metadata. */ toJson: () => MiddlewareDesc; } /** * An instantiated implementation of a Generate Middleware. * Provides optional hooks to intercept the high-level `generate` action, * the underlying `model` execution, or individual `tool` calls, as well as * tools to inject into the execution. */ interface GenerateMiddlewareDef { /** * Hook for intercepting the top-level generate action. * Can be used to inject request parameters, modify the response, or catch errors. */ generate?: (envelope: { request: GenerateActionOptions; currentTurn: number; messageIndex: number; }, ctx: ActionRunOptions<GenerateResponseChunkData>, next: (envelope: { request: GenerateActionOptions; currentTurn: number; messageIndex: number; }, ctx: ActionRunOptions<GenerateResponseChunkData>) => Promise<GenerateResponseData>) => Promise<GenerateResponseData>; /** * Hook for intercepting the underlying model execution. * Ideal for model-level caching, retry logic, or prompt/response parsing. */ model?: (req: GenerateRequest<any>, ctx: ActionRunOptions<GenerateResponseChunkData>, next: (req: GenerateRequest<any>, ctx: ActionRunOptions<GenerateResponseChunkData>) => Promise<GenerateResponseData>) => Promise<GenerateResponseData>; /** * Hook for intercepting individual tool calls. * Enables caching tool responses, validating inputs, or overriding tool execution. */ tool?: (req: ToolRequestPart, ctx: ActionRunOptions<any>, next: (req: ToolRequestPart, ctx: ActionRunOptions<any>) => Promise<ToolResponsePart | undefined>) => Promise<ToolResponsePart | undefined>; /** * Tools to statically inject into the generation request whenever this middleware is active. */ tools?: ToolAction[]; } /** * Options passed to the middleware factory function. */ interface MiddlewareFnOptions<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny, PluginOptions = void> { config: z.infer<ConfigSchema> | undefined; pluginConfig: PluginOptions; ai: GenkitAI; } declare function generateMiddleware<PluginOptions = void, ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny>(options: { name: string; configSchema?: ConfigSchema; description?: string; metadata?: Record<string, any>; }, middlewareFn: (options: MiddlewareFnOptions<ConfigSchema, PluginOptions>) => GenerateMiddlewareDef): GenerateMiddleware<ConfigSchema, PluginOptions>; declare function resolveMiddleware(registry: Registry, refs?: MiddlewareRef[]): Promise<GenerateMiddlewareDef[]>; /** * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * Preprocess a GenerateRequest to download referenced http(s) media URLs and * inline them as data URIs. */ declare function downloadRequestMedia(options?: { maxBytes?: number; filter?: (part: MediaPart) => boolean; }): ModelMiddleware; /** * Validates that a GenerateRequest does not include unsupported features. */ declare function validateSupport(options: { name: string; supports?: ModelInfo['supports']; }): ModelMiddleware; /** * Provide a simulated system prompt for models that don't support it natively. */ declare function simulateSystemPrompt(options?: { preface: string; acknowledgement: string; }): ModelMiddleware; /** Options for the {@link augmentWithContext} middleware. */ interface AugmentWithContextOptions { /** Preceding text to place before the rendered context documents. */ preface?: string | null; /** A function to render a document into a text part to be included in the message. */ itemTemplate?: (d: Document, options?: AugmentWithContextOptions) => string; /** The metadata key to use for citation reference. Pass `null` to provide no citations. */ citationKey?: string | null; } /** Default preface text inserted before context documents in the prompt. */ declare const CONTEXT_PREFACE = "\n\nUse the following information to complete your task:\n\n"; /** * Model middleware that appends retrieved context documents to the last user message * so models without native document/context support can still use RAG-style augmentation. */ declare function augmentWithContext(options?: AugmentWithContextOptions): ModelMiddleware; /** * Options for the `retry` middleware. * @deprecated Use `retry` from the `@genkit-ai/middleware` package instead. */ interface RetryOptions { /** * The maximum number of times to retry a failed request. * @default 3 */ maxRetries?: number; /** * An array of `StatusName` values that should trigger a retry. * @default ['UNAVAILABLE', 'DEADLINE_EXCEEDED', 'RESOURCE_EXHAUSTED', 'ABORTED', 'INTERNAL'] */ statuses?: StatusName[]; /** * The initial delay between retries, in milliseconds. * @default 1000 */ initialDelayMs?: number; /** * The maximum delay between retries, in milliseconds. * @default 60000 */ maxDelayMs?: number; /** * The factor by which the delay increases after each retry (exponential backoff). * @default 2 */ backoffFactor?: number; /** * Whether to disable jitter on the delay. Jitter adds a random factor to the * delay to help prevent a "thundering herd" of clients all retrying at the * same time. * @default false */ noJitter?: boolean; /** * A callback to be executed on each retry attempt. */ onError?: (error: Error, attempt: number) => void; } /** * FOR TESTING ONLY. * @internal */ declare const TEST_ONLY: { setRetryTimeout(impl: (callback: (...args: any[]) => void, ms?: number) => NodeJS.Timeout): void; }; /** * Creates a middleware that retries requests on specific error statuses. * * @deprecated Use `retry` from the `@genkit-ai/middleware` package instead. * * ```ts * const { text } = await ai.generate({ * model: googleAI.model('gemini-pro-latest'), * prompt: 'You are a helpful AI assistant named Walt, say hello', * use: [ * retry({ * maxRetries: 2, * initialDelayMs: 1000, * backoffFactor: 2, * }), * ], * }); * ``` */ declare function retry(options?: RetryOptions): ModelMiddleware; /** * Options for the `fallback` middleware. * @deprecated Use `fallback` from the `@genkit-ai/middleware` package instead. */ interface FallbackOptions { /** * An array of models to try in order. */ models: ModelArgument[]; /** * An array of `StatusName` values that should trigger a fallback. * @default ['UNAVAILABLE', 'DEADLINE_EXCEEDED', 'RESOURCE_EXHAUSTED', 'ABORTED', 'INTERNAL', 'NOT_FOUND', 'UNIMPLEMENTED'] */ statuses?: StatusName[]; /** * A callback to be executed on each fallback attempt. */ onError?: (error: Error) => void; } /** * Creates a middleware that falls back to a different model on specific error statuses. * * @deprecated Use `fallback` from the `@genkit-ai/middleware` package instead. * * ```ts * const { text } = await ai.generate({ * model: googleAI.model('gemini-pro-latest'), * prompt: 'You are a helpful AI assistant named Walt, say hello', * use: [ * fallback(ai, { * models: [googleAI.model('gemini-flash-latest')], * statuses: ['RESOURCE_EXHAUSTED'], * }), * ], * }); * ``` */ declare function fallback(ai: HasRegistry, options: FallbackOptions): ModelMiddleware; /** Options for the {@link simulateConstrainedGeneration} middleware. */ interface SimulatedConstrainedGenerationOptions { instructionsRenderer?: (schema: Record<string, any>) => string; } /** * Model middleware that simulates constrained generation by injecting generation * instructions into the user message. */ declare function simulateConstrainedGeneration(options?: SimulatedConstrainedGenerationOptions): ModelMiddleware; /** * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ type GenerateAction = Action<typeof GenerateActionOptionsSchema, typeof GenerateResponseSchema, typeof GenerateResponseChunkSchema>; /** Defines (registers) a utilty generate action. */ declare function defineGenerateAction(registry: Registry): GenerateAction; /** * Encapsulates all generate logic. This is similar to `generateAction` except not an action and can take middleware. */ declare function generateHelper(registry: Registry, options: { rawRequest: GenerateActionOptions; middleware?: GenerateMiddlewareDef[]; currentTurn?: number; messageIndex?: number; abortSignal?: AbortSignal; streamingCallback?: StreamingCallback<GenerateResponseChunk>; context?: Record<string, any>; }): Promise<GenerateResponseData>; declare function shouldInjectFormatInstructions(formatConfig?: Formatter['config'], rawRequestConfig?: z.infer<typeof GenerateActionOutputConfig>): string | boolean | undefined; declare function inferRoleFromParts(parts: Part[]): Role; /** * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** An action that represents a generative AI model, accepting a {@link GenerateRequest} and returning a {@link GenerateResponseData}. */ type ModelAction<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny> = Action<typeof GenerateRequestSchema, typeof GenerateResponseSchema, typeof GenerateResponseChunkSchema> & { __configSchema: CustomOptionsSchema; }; /** An action that represents a generative AI model that runs in the background (asynchronously). */ type BackgroundModelAction<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny> = BackgroundAction<typeof GenerateRequestSchema, typeof GenerateResponseSchema> & { __configSchema: CustomOptionsSchema; }; /** A simple middleware function that can intercept and transform model requests and responses. */ type ModelMiddleware = SimpleMiddleware<z.infer<typeof GenerateRequestSchema>, z.infer<typeof GenerateResponseSchema>>; /** A middleware function that receives additional {@link ActionRunOptions} (e.g. streaming callback) alongside the request. */ type ModelMiddlewareWithOptions = MiddlewareWithOptions<z.infer<typeof GenerateRequestSchema>, z.infer<typeof GenerateResponseSchema>, z.infer<typeof GenerateResponseChunkSchema>>; /** Union of middleware types accepted by model definitions: either a {@link ModelMiddleware} or {@link ModelMiddlewareWithOptions}. */ type ModelMiddlewareArgument = ModelMiddleware | ModelMiddlewareWithOptions; /** Options for defining a new model via {@link defineModel} or {@link model}. */ type DefineModelOptions<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny> = { name: string; /** Known version names for this model, e.g. `gemini-1.0-pro-001`. */ versions?: string[]; /** Capabilities this model supports. */ supports?: ModelInfo['supports']; /** Custom options schema for this model. */ configSchema?: CustomOptionsSchema; /** Descriptive name for this model e.g. 'Google AI - Gemini Pro'. */ label?: string; /** Middleware to be used with this model. */ use?: ModelMiddlewareArgument[]; }; /** * Creates a {@link ModelAction} without registering it. Useful for plugin authors * who need to return a model action from a resolver. */ declare function model<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(options: DefineModelOptions<CustomOptionsSchema>, runner: (request: GenerateRequest<CustomOptionsSchema>, options: ActionFnArg<GenerateResponseChunkData>) => Promise<GenerateResponseData>): ModelAction<CustomOptionsSchema>; /** * Defines a new model and adds it to the registry. */ declare function defineModel<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(registry: Registry, options: { apiVersion: 'v2'; } & DefineModelOptions<CustomOptionsSchema>, runner: (request: GenerateRequest<CustomOptionsSchema>, options: ActionFnArg<GenerateResponseChunkData>) => Promise<GenerateResponseData>): ModelAction<CustomOptionsSchema>; /** * Defines a new model and adds it to the registry. */ declare function defineModel<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(registry: Registry, options: DefineModelOptions<CustomOptionsSchema>, runner: (request: GenerateRequest<CustomOptionsSchema>, streamingCallback?: StreamingCallback<GenerateResponseChunkData>) => Promise<GenerateResponseData>): ModelAction<CustomOptionsSchema>; /** Options for defining a background model that processes requests asynchronously. */ type DefineBackgroundModelOptions<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny> = DefineModelOptions<CustomOptionsSchema> & { start: (request: GenerateRequest<CustomOptionsSchema>) => Promise<Operation<GenerateResponseData>>; check: (operation: Operation<GenerateResponseData>) => Promise<Operation<GenerateResponseData>>; cancel?: (operation: Operation<GenerateResponseData>) => Promise<Operation<GenerateResponseData>>; }; /** * Defines a new model that runs in the background. */ declare function defineBackgroundModel<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(registry: Registry, options: DefineBackgroundModelOptions<CustomOptionsSchema>): BackgroundModelAction<CustomOptionsSchema>; /** * Defines a new model that runs in the background. */ declare function backgroundModel<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(options: DefineBackgroundModelOptions<CustomOptionsSchema>): BackgroundModelAction<CustomOptionsSchema>; /** Zod schema for a {@link ModelReference}. */ declare const ModelReferenceSchema: z.ZodObject<{ name: z.ZodString; config: z.ZodOptional<z.ZodAny>; }, "strip", z.ZodTypeAny, { name: string; config?: any; }, { name: string; config?: any; }>; /** * A reference to a model that includes optional configuration and version info. * Can be passed anywhere a {@link ModelArgument} is accepted. */ interface ModelReference<CustomOptions extends z.ZodTypeAny> extends z.infer<typeof ModelReferenceSchema> { name: string; configSchema?: CustomOptions; info?: ModelInfo; version?: string; config?: z.infer<CustomOptions>; withConfig(cfg: z.infer<CustomOptions>): ModelReference<CustomOptions>; withVersion(version: string): ModelReference<CustomOptions>; } /** * Packages model information into ActionMetadata object. */ declare function modelActionMetadata({ name, info, configSchema, background, }: { name: string; info?: ModelInfo; configSchema?: z.ZodTypeAny; background?: boolean; }): ActionMetadata; /** Cretes a model reference. */ declare function modelRef<CustomOptionsSchema extends z.ZodTypeAny = z.ZodTypeAny>(options: Omit<ModelReference<CustomOptionsSchema>, 'withConfig' | 'withVersion'> & { namespace?: string; }): ModelReference<CustomOptionsSchema>; /** * Calculates basic usage statistics from the given model inputs and outputs. */ declare function getBasicUsageStats(input: MessageData[], response: MessageData | CandidateData[]): GenerationUsage; /** * Union type for all the ways a model can be specified: by name string, * {@link ModelAction}, or {@link ModelReference}. */ type ModelArgument<CustomOptions extends z.ZodTypeAny = z.ZodTypeAny> = ModelAction<CustomOptions> | ModelReference<CustomOptions> | string; /** The result of resolving a {@link ModelArgument} to a concrete action, config, and version. */ interface ResolvedModel<CustomOptions extends z.ZodTypeAny = z.ZodTypeAny> { modelAction: ModelAction; config?: z.infer<CustomOptions>; version?: string; } declare function resolveModel<C extends z.ZodTypeAny = z.ZodTypeAny>(registry: Registry, model: ModelArgument<C> | undefined, options?: { warnDeprecated?: boolean; }): Promise<ResolvedModel<C>>; /** * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** Specifies how tools should be called by the model. */ type ToolChoice = 'auto' | 'required' | 'none'; /** Configuration for the desired output format and schema of a generate request. */ interface OutputOptions<O extends z.ZodTypeAny = z.ZodTypeAny> { format?: string; contentType?: string; instructions?: boolean | string; schema?: O; jsonSchema?: any; constrained?: boolean; } /** ResumeOptions configure how to resume generation after an interrupt. */ interface ResumeOptions { /** * respond should contain a single or list of `toolResponse` parts corresponding * to interrupt `toolRequest` parts from the most recent model message. Each * entry must have a matching `name` and `ref` (if supplied) for its `toolRequest` * counterpart. * * Tools have a `.respond` helper method to construct a reply ToolResponse and validate * the data against its schema. Call `myTool.respond(interruptToolRequest, yourReplyData)`. */ respond?: ToolResponsePart | ToolResponsePart[]; /** * restart will run a tool again with additionally supplied metadata passed through as * a `resumed` option in the second argument. This allows for scenarios like conditionally * requesting confirmation of an LLM's tool request. * * Tools have a `.restart` helper method to construct a restart ToolRequest. Call * `myTool.restart(interruptToolRequest, resumeMetadata)`. * */ restart?: ToolRequestPart | ToolRequestPart[]; /** Additional metadata to annotate the created tool message with in the "resume" key. */ metadata?: Record<string, any>; } /** * Options for making a generation request using {@link Genkit.generate} or {@link Genkit.generateStream}. */ interface GenerateOptions<O extends z.ZodTypeAny = z.ZodTypeAny, CustomOptions extends z.ZodTypeAny = z.ZodTypeAny> { /** A model name (e.g. `vertexai/gemini-1.0-pro`) or reference. */ model?: ModelArgument<CustomOptions>; /** The system prompt to be included in the generate request. Can be a string for a simple text prompt or one or more parts for multi-modal prompts (subject to model support). */ system?: string | Part | Part[]; /** The prompt for which to generate a response. Can be a string for a simple text prompt or one or more parts for multi-modal prompts. */ prompt?: string | Part | Part[]; /** Retrieved documents to be used as context for this generation. */ docs?: DocumentData[]; /** Conversation messages (history) for multi-turn prompting when supported by the underlying model. */ messages?: (MessageData & { content: Part[] | string | (string | Part)[]; })[]; /** List of registered tool names or actions to treat as a tool for this generation if supported by the underlying model. */ tools?: ToolArgument[]; /** List of dynamic resources to be made available to this generate request. */ resources?: ResourceArgument[]; /** Specifies how tools should be called by the model. */ toolChoice?: ToolChoice; /** Configuration for the generation request. */ config?: z.infer<CustomOptions>; /** Configuration for the desired output of the request. Defaults to the model's default output if unspecified. */ output?: OutputOptions<O>; /** * resume provides convenient capabilities for continuing generation * after an interrupt is triggered. Example: * * ```ts * const myInterrupt = ai.defineInterrupt({...}); * * const response = await ai.generate({ * tools: [myInterrupt], * prompt: "Call myInterrupt", * }); * * const interrupt = response.interrupts[0]; * * const resumedResponse = await ai.generate({ * messages: response.messages, * resume: myInterrupt.respond(interrupt, {note: "this is the reply data"}), * }); * ``` * * @beta */ resume?: ResumeOptions; /** When true, return tool calls for manual processing instead of automatically resolving them. */ returnToolRequests?: boolean; /** Maximum number of tool call iterations that can be performed in a single generate call (default 5). */ maxTurns?: number; /** When provided, models supporting streaming will call the provided callback with chunks as generation progresses. */ onChunk?: StreamingCallback<GenerateResponseChunk>; /** * When provided, models supporting streaming will call the provided callback with chunks as generation progresses. * * @deprecated use {@link onChunk} instead. */ streamingCallback?: StreamingCallback<GenerateResponseChunk>; /** Middleware to be used with this model call. */ use?: (ModelMiddlewareArgument | GenerateMiddleware | MiddlewareRef)[]; /** Additional context (data, like e.g. auth) to be passed down to tools, prompts and other sub actions. */ context?: ActionContext; /** Abort signal for the generate request. */ abortSignal?: AbortSignal; /** Custom step name for this generate call to display in trace views. Defaults to "generate". */ stepName?: string; /** * Additional metadata describing the GenerateOptions, used by tooling. If * this is an instance of a rendered dotprompt, will contain any prompt * metadata contained in the original frontmatter. **/ metadata?: Record<string, any>; } declare function toGenerateRequest(registry: Registry, options: GenerateOptions): Promise<GenerateRequest>; /** An error that includes the partial {@link GenerateResponse} that triggered it. */ declare class GenerationResponseError extends GenkitError { detail: { response: GenerateResponse; [otherDetails: string]: any; }; constructor(response: GenerateResponse<any>, message: string, status?: GenkitError['status'], detail?: Record<string, any>); } /** A GenerationBlockedError is thrown when a generation is blocked. */ declare class GenerationBlockedError extends GenerationResponseError { } /** * Normalizes a mix of middleware representations into an array of standardized `MiddlewareRef`s. * Any raw functional middleware or unregistered middleware objects are dynamically registered * into the provided registry. * * @param registry The registry to use for looking up or dynamically registering middleware. * @param middlewareList An array of middleware functions, instances, or references. * @returns A promise resolving to an array of normalized `MiddlewareRef` objects. */ declare function normalizeMiddleware(registry: Registry, middlewareList?: (ModelMiddlewareArgument | GenerateMiddleware | MiddlewareRef)[]): Promise<MiddlewareRef[]>; /** * Generate calls a generative model based on the provided prompt and configuration. If * `history` is provided, the generation will include a conversation history in its * request. If `tools` are provided, the generate method will automatically resolve * tool calls returned from the model unless `returnToolRequests` is set to `true`. * * See `GenerateOptions` for detailed information about available options. * * @param options The options for this generation request. * @returns The generated response based on the provided parameters. */ declare function generate<O extends z.ZodTypeAny = z.ZodTypeAny, CustomOptions extends z.ZodTypeAny = typeof GenerationCommonConfigSchema>(registry: Registry, options: GenerateOpt