feat(ai): server prompt templates

.changeset/metal-ties-cry.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/ai': minor
+---
+
+Add support for Server Prompt Templates.

common/api-review/ai.api.md

@@ -96,6 +96,10 @@ export interface AudioConversationController {
 export abstract class Backend {
     protected constructor(type: BackendType);
     readonly backendType: BackendType;
+    // @internal (undocumented)
+    abstract _getModelPath(project: string, model: string): string;
+    // @internal (undocumented)
+    abstract _getTemplatePath(project: string, templateId: string): string;
 }
 
 // @public
@@ -561,9 +565,19 @@ export function getImagenModel(ai: AI, modelParams: ImagenModelParams, requestOp
 // @beta
 export function getLiveGenerativeModel(ai: AI, modelParams: LiveModelParams): LiveGenerativeModel;
 
+// @beta
+export function getTemplateGenerativeModel(ai: AI, requestOptions?: RequestOptions): TemplateGenerativeModel;
+
+// @beta
+export function getTemplateImagenModel(ai: AI, requestOptions?: RequestOptions): TemplateImagenModel;
+
 // @public
 export class GoogleAIBackend extends Backend {
     constructor();
+    // (undocumented)
+    _getModelPath(project: string, model: string): string;
+    // (undocumented)
+    _getTemplatePath(project: string, templateId: string): string;
 }
 
 // Warning: (ae-internal-missing-underscore) The name "GoogleAICitationMetadata" should be prefixed with an underscore because the declaration is marked as @internal
@@ -1304,6 +1318,38 @@ export class StringSchema extends Schema {
     toJSON(): SchemaRequest;
 }
 
+// @beta
+export class TemplateChatSession {
+    constructor(_apiSettings: ApiSettings, templateId: string, _history?: Content[], requestOptions?: RequestOptions | undefined);
+    getHistory(): Promise<Content[]>;
+    // (undocumented)
+    requestOptions?: RequestOptions | undefined;
+    sendMessage(request: string | Array<string | Part>, inputs?: object): Promise<GenerateContentResult>;
+    sendMessageStream(request: string | Array<string | Part>, inputs?: object): Promise<GenerateContentStreamResult>;
+    // (undocumented)
+    templateId: string;
+}
+
+// @beta
+export class TemplateGenerativeModel {
+    constructor(ai: AI, requestOptions?: RequestOptions);
+    // @internal (undocumented)
+    _apiSettings: ApiSettings;
+    generateContent(templateId: string, templateVariables: object): Promise<GenerateContentResult>;
+    generateContentStream(templateId: string, templateVariables: object): Promise<GenerateContentStreamResult>;
+    requestOptions?: RequestOptions;
+    startChat(templateId: string, history?: Content[]): TemplateChatSession;
+}
+
+// @beta
+export class TemplateImagenModel {
+    constructor(ai: AI, requestOptions?: RequestOptions);
+    // @internal (undocumented)
+    _apiSettings: ApiSettings;
+    generateImages(templateId: string, templateVariables: object): Promise<ImagenGenerationResponse<ImagenInlineImage>>;
+    requestOptions?: RequestOptions;
+}
+
 // @public
 export interface TextPart {
     // (undocumented)
@@ -1397,6 +1443,10 @@ export interface UsageMetadata {
 // @public
 export class VertexAIBackend extends Backend {
     constructor(location?: string);
+    // (undocumented)
+    _getModelPath(project: string, model: string): string;
+    // (undocumented)
+    _getTemplatePath(project: string, templateId: string): string;
     readonly location: string;
 }
 

docs-devsite/_toc.yaml

@@ -196,6 +196,12 @@ toc:
     path: /docs/reference/js/ai.startchatparams.md
   - title: StringSchema
     path: /docs/reference/js/ai.stringschema.md
+  - title: TemplateChatSession
+    path: /docs/reference/js/ai.templatechatsession.md
+  - title: TemplateGenerativeModel
+    path: /docs/reference/js/ai.templategenerativemodel.md
+  - title: TemplateImagenModel
+    path: /docs/reference/js/ai.templateimagenmodel.md
   - title: TextPart
     path: /docs/reference/js/ai.textpart.md
   - title: ThinkingConfig

docs-devsite/ai.googleaibackend.md

@@ -27,6 +27,13 @@ export declare class GoogleAIBackend extends Backend
 |  --- | --- | --- |
 |  [(constructor)()](./ai.googleaibackend.md#googleaibackendconstructor) |  | Creates a configuration object for the Gemini Developer API backend. |
 
+## Methods
+
+|  Method | Modifiers | Description |
+|  --- | --- | --- |
+|  [\_getModelPath(project, model)](./ai.googleaibackend.md#googleaibackend_getmodelpath) |  |  |
+|  [\_getTemplatePath(project, templateId)](./ai.googleaibackend.md#googleaibackend_gettemplatepath) |  |  |
+
 ## GoogleAIBackend.(constructor)
 
 Creates a configuration object for the Gemini Developer API backend.
@@ -36,3 +43,42 @@ Creates a configuration object for the Gemini Developer API backend.
 ```typescript
 constructor();
 ```
+
+## GoogleAIBackend.\_getModelPath()
+
+<b>Signature:</b>
+
+```typescript
+_getModelPath(project: string, model: string): string;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  project | string |  |
+|  model | string |  |
+
+<b>Returns:</b>
+
+string
+
+## GoogleAIBackend.\_getTemplatePath()
+
+<b>Signature:</b>
+
+```typescript
+_getTemplatePath(project: string, templateId: string): string;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  project | string |  |
+|  templateId | string |  |
+
+<b>Returns:</b>
+
+string
+

docs-devsite/ai.md

@@ -22,6 +22,8 @@ The Firebase AI Web SDK.
 |  [getGenerativeModel(ai, modelParams, requestOptions)](./ai.md#getgenerativemodel_c63f46a) | Returns a [GenerativeModel](./ai.generativemodel.md#generativemodel_class) class with methods for inference and other functionality. |
 |  [getImagenModel(ai, modelParams, requestOptions)](./ai.md#getimagenmodel_e1f6645) | Returns an [ImagenModel](./ai.imagenmodel.md#imagenmodel_class) class with methods for using Imagen.<!-- -->Only Imagen 3 models (named <code>imagen-3.0-*</code>) are supported. |
 |  [getLiveGenerativeModel(ai, modelParams)](./ai.md#getlivegenerativemodel_f2099ac) | <b><i>(Public Preview)</i></b> Returns a [LiveGenerativeModel](./ai.livegenerativemodel.md#livegenerativemodel_class) class for real-time, bidirectional communication.<!-- -->The Live API is only supported in modern browser windows and Node &gt;<!-- -->= 22. |
+|  [getTemplateGenerativeModel(ai, requestOptions)](./ai.md#gettemplategenerativemodel_9476bbc) | <b><i>(Public Preview)</i></b> Returns a [TemplateGenerativeModel](./ai.templategenerativemodel.md#templategenerativemodel_class) class for executing server-side templates. |
+|  [getTemplateImagenModel(ai, requestOptions)](./ai.md#gettemplateimagenmodel_9476bbc) | <b><i>(Public Preview)</i></b> Returns a [TemplateImagenModel](./ai.templateimagenmodel.md#templateimagenmodel_class) class for executing server-side Imagen templates. |
 |  <b>function(liveSession, ...)</b> |
 |  [startAudioConversation(liveSession, options)](./ai.md#startaudioconversation_01c8e7f) | <b><i>(Public Preview)</i></b> Starts a real-time, bidirectional audio conversation with the model. This helper function manages the complexities of microphone access, audio recording, playback, and interruptions. |
 
@@ -47,6 +49,9 @@ The Firebase AI Web SDK.
 |  [ObjectSchema](./ai.objectschema.md#objectschema_class) | Schema class for "object" types. The <code>properties</code> param must be a map of <code>Schema</code> objects. |
 |  [Schema](./ai.schema.md#schema_class) | Parent class encompassing all Schema types, with static methods that allow building specific Schema types. This class can be converted with <code>JSON.stringify()</code> into a JSON string accepted by Vertex AI REST endpoints. (This string conversion is automatically done when calling SDK methods.) |
 |  [StringSchema](./ai.stringschema.md#stringschema_class) | Schema class for "string" types. Can be used with or without enum values. |
+|  [TemplateChatSession](./ai.templatechatsession.md#templatechatsession_class) | <b><i>(Public Preview)</i></b> A chat session that enables sending chat messages and stores the history of sent and received messages so far.<!-- -->This session is for multi-turn chats using a server-side template. It should be instantiated with [TemplateGenerativeModel.startChat()](./ai.templategenerativemodel.md#templategenerativemodelstartchat)<!-- -->. |
+|  [TemplateGenerativeModel](./ai.templategenerativemodel.md#templategenerativemodel_class) | <b><i>(Public Preview)</i></b> [GenerativeModel](./ai.generativemodel.md#generativemodel_class) APIs that execute on a server-side template.<!-- -->This class should only be instantiated with [getTemplateGenerativeModel()](./ai.md#gettemplategenerativemodel_9476bbc)<!-- -->. |
+|  [TemplateImagenModel](./ai.templateimagenmodel.md#templateimagenmodel_class) | <b><i>(Public Preview)</i></b> Class for Imagen model APIs that execute on a server-side template.<!-- -->This class should only be instantiated with [getTemplateImagenModel()](./ai.md#gettemplateimagenmodel_9476bbc)<!-- -->. |
 |  [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class) | Configuration class for the Vertex AI Gemini API.<!-- -->Use this with [AIOptions](./ai.aioptions.md#aioptions_interface) when initializing the AI service via [getAI()](./ai.md#getai_a94a413) to specify the Vertex AI Gemini API as the backend. |
 
 ## Interfaces
@@ -339,6 +344,54 @@ export declare function getLiveGenerativeModel(ai: AI, modelParams: LiveModelPar
 
 If the `apiKey` or `projectId` fields are missing in your Firebase config.
 
+### getTemplateGenerativeModel(ai, requestOptions) {:#gettemplategenerativemodel_9476bbc}
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Returns a [TemplateGenerativeModel](./ai.templategenerativemodel.md#templategenerativemodel_class) class for executing server-side templates.
+
+<b>Signature:</b>
+
+```typescript
+export declare function getTemplateGenerativeModel(ai: AI, requestOptions?: RequestOptions): TemplateGenerativeModel;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  ai | [AI](./ai.ai.md#ai_interface) | An [AI](./ai.ai.md#ai_interface) instance. |
+|  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) | Additional options to use when making requests. |
+
+<b>Returns:</b>
+
+[TemplateGenerativeModel](./ai.templategenerativemodel.md#templategenerativemodel_class)
+
+### getTemplateImagenModel(ai, requestOptions) {:#gettemplateimagenmodel_9476bbc}
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Returns a [TemplateImagenModel](./ai.templateimagenmodel.md#templateimagenmodel_class) class for executing server-side Imagen templates.
+
+<b>Signature:</b>
+
+```typescript
+export declare function getTemplateImagenModel(ai: AI, requestOptions?: RequestOptions): TemplateImagenModel;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  ai | [AI](./ai.ai.md#ai_interface) | An [AI](./ai.ai.md#ai_interface) instance. |
+|  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) | Additional options to use when making requests. |
+
+<b>Returns:</b>
+
+[TemplateImagenModel](./ai.templateimagenmodel.md#templateimagenmodel_class)
+
 ## function(liveSession, ...)
 
 ### startAudioConversation(liveSession, options) {:#startaudioconversation_01c8e7f}

docs-devsite/ai.templatechatsession.md

@@ -0,0 +1,154 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# TemplateChatSession class
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+A chat session that enables sending chat messages and stores the history of sent and received messages so far.
+
+This session is for multi-turn chats using a server-side template. It should be instantiated with [TemplateGenerativeModel.startChat()](./ai.templategenerativemodel.md#templategenerativemodelstartchat)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export declare class TemplateChatSession 
+```
+
+## Constructors
+
+|  Constructor | Modifiers | Description |
+|  --- | --- | --- |
+|  [(constructor)(\_apiSettings, templateId, \_history, requestOptions)](./ai.templatechatsession.md#templatechatsessionconstructor) |  | <b><i>(Public Preview)</i></b>  Constructs a new instance of the <code>TemplateChatSession</code> class |
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [requestOptions](./ai.templatechatsession.md#templatechatsessionrequestoptions) |  | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) \| undefined | <b><i>(Public Preview)</i></b> |
+|  [templateId](./ai.templatechatsession.md#templatechatsessiontemplateid) |  | string | <b><i>(Public Preview)</i></b> |
+
+## Methods
+
+|  Method | Modifiers | Description |
+|  --- | --- | --- |
+|  [getHistory()](./ai.templatechatsession.md#templatechatsessiongethistory) |  | <b><i>(Public Preview)</i></b> Gets the chat history so far. Blocked prompts are not added to history. Neither blocked candidates nor the prompts that generated them are added to history. |
+|  [sendMessage(request, inputs)](./ai.templatechatsession.md#templatechatsessionsendmessage) |  | <b><i>(Public Preview)</i></b> Sends a chat message and receives a non-streaming [GenerateContentResult](./ai.generatecontentresult.md#generatecontentresult_interface)<!-- -->. |
+|  [sendMessageStream(request, inputs)](./ai.templatechatsession.md#templatechatsessionsendmessagestream) |  | <b><i>(Public Preview)</i></b> Sends a chat message and receives the response as a [GenerateContentStreamResult](./ai.generatecontentstreamresult.md#generatecontentstreamresult_interface) containing an iterable stream and a response promise. |
+
+## TemplateChatSession.(constructor)
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+ Constructs a new instance of the `TemplateChatSession` class
+
+<b>Signature:</b>
+
+```typescript
+constructor(_apiSettings: ApiSettings, templateId: string, _history?: Content[], requestOptions?: RequestOptions | undefined);
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  \_apiSettings | ApiSettings |  |
+|  templateId | string |  |
+|  \_history | [Content](./ai.content.md#content_interface)<!-- -->\[\] |  |
+|  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) \| undefined |  |
+
+## TemplateChatSession.requestOptions
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+<b>Signature:</b>
+
+```typescript
+requestOptions?: RequestOptions | undefined;
+```
+
+## TemplateChatSession.templateId
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+<b>Signature:</b>
+
+```typescript
+templateId: string;
+```
+
+## TemplateChatSession.getHistory()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Gets the chat history so far. Blocked prompts are not added to history. Neither blocked candidates nor the prompts that generated them are added to history.
+
+<b>Signature:</b>
+
+```typescript
+getHistory(): Promise<Content[]>;
+```
+<b>Returns:</b>
+
+Promise&lt;[Content](./ai.content.md#content_interface)<!-- -->\[\]&gt;
+
+## TemplateChatSession.sendMessage()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Sends a chat message and receives a non-streaming [GenerateContentResult](./ai.generatecontentresult.md#generatecontentresult_interface)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+sendMessage(request: string | Array<string | Part>, inputs?: object): Promise<GenerateContentResult>;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  request | string \| Array&lt;string \| [Part](./ai.md#part)<!-- -->&gt; | The user message to store in the history |
+|  inputs | object | A key-value map of variables to populate the template with. This should likely include the user message. |
+
+<b>Returns:</b>
+
+Promise&lt;[GenerateContentResult](./ai.generatecontentresult.md#generatecontentresult_interface)<!-- -->&gt;
+
+## TemplateChatSession.sendMessageStream()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Sends a chat message and receives the response as a [GenerateContentStreamResult](./ai.generatecontentstreamresult.md#generatecontentstreamresult_interface) containing an iterable stream and a response promise.
+
+<b>Signature:</b>
+
+```typescript
+sendMessageStream(request: string | Array<string | Part>, inputs?: object): Promise<GenerateContentStreamResult>;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  request | string \| Array&lt;string \| [Part](./ai.md#part)<!-- -->&gt; | The message to send to the model. |
+|  inputs | object | A key-value map of variables to populate the template with. |
+
+<b>Returns:</b>
+
+Promise&lt;[GenerateContentStreamResult](./ai.generatecontentstreamresult.md#generatecontentstreamresult_interface)<!-- -->&gt;
+