Initial prototype

Author: dlarocque

common/api-review/vertexai.api.md

@@ -797,6 +797,8 @@ export interface UsageMetadata {
 export interface VertexAI {
     app: FirebaseApp;
     // (undocumented)
+    developerAPIEnabled: boolean;
+    // (undocumented)
     location: string;
 }
 
@@ -831,11 +833,13 @@ export abstract class VertexAIModel {
     // @internal (undocumented)
     protected _apiSettings: ApiSettings;
     readonly model: string;
-    static normalizeModelName(modelName: string): string;
+    static normalizeModelName(modelName: string, developerAPIEnabled?: boolean): string;
 }
 
 // @public
 export interface VertexAIOptions {
+    // (undocumented)
+    developerAPIEnabled: boolean;
     // (undocumented)
     location?: string;
 }

packages/vertexai/src/api.ts

@@ -29,6 +29,7 @@ import {
 } from './types';
 import { VertexAIError } from './errors';
 import { VertexAIModel, GenerativeModel, ImagenModel } from './models';
+import { createInstanceIdentifier } from './helpers';
 
 export { ChatSession } from './methods/chat-session';
 export * from './requests/schema-builder';
@@ -57,8 +58,12 @@ export function getVertexAI(
   // Dependencies
   const vertexProvider: Provider<'vertexAI'> = _getProvider(app, VERTEX_TYPE);
 
+  const identifier = createInstanceIdentifier(
+    options?.developerAPIEnabled,
+    options?.location
+  );
   return vertexProvider.getImmediate({
-    identifier: options?.location || DEFAULT_LOCATION
+    identifier
   });
 }
 

packages/vertexai/src/constants.ts

@@ -23,6 +23,9 @@ export const DEFAULT_LOCATION = 'us-central1';
 
 export const DEFAULT_BASE_URL = 'https://firebasevertexai.googleapis.com';
 
+export const DEVELOPER_API_BASE_URL =
+  'https://generativelanguage.googleapis.com';
+
 export const DEFAULT_API_VERSION = 'v1beta';
 
 export const PACKAGE_VERSION = version;

packages/vertexai/src/helpers.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * 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.
+ */
+
+import { DEFAULT_LOCATION } from './constants';
+
+/**
+ * @internal
+ */
+export function createInstanceIdentifier(
+  developerAPIEnabled?: boolean,
+  location?: string
+): string {
+  if (developerAPIEnabled) {
+    return 'developerAPI';
+  } else {
+    return `vertexAI/${location || DEFAULT_LOCATION}`;
+  }
+}
+
+/**
+ * @internal
+ */
+export function parseInstanceIdentifier(instanceIdentifier: string): {
+  developerAPIEnabled: boolean;
+  location?: string;
+} {
+  const identifierParts = instanceIdentifier.split('/');
+  if (identifierParts[0] === 'developerAPI') {
+    return {
+      developerAPIEnabled: true,
+      location: undefined
+    };
+  } else {
+    const location = identifierParts[1];
+    return {
+      developerAPIEnabled: false,
+      location
+    };
+  }
+}

packages/vertexai/src/index.node.ts

@@ -26,17 +26,35 @@ import { VertexAIService } from './service';
 import { VERTEX_TYPE } from './constants';
 import { Component, ComponentType } from '@firebase/component';
 import { name, version } from '../package.json';
+import { VertexAIOptions } from './public-types';
+import { parseInstanceIdentifier } from './helpers';
 
 function registerVertex(): void {
   _registerComponent(
     new Component(
       VERTEX_TYPE,
-      (container, { instanceIdentifier: location }) => {
+      (container, options) => {
         // getImmediate for FirebaseApp will always succeed
         const app = container.getProvider('app').getImmediate();
         const auth = container.getProvider('auth-internal');
         const appCheckProvider = container.getProvider('app-check-internal');
-        return new VertexAIService(app, auth, appCheckProvider, { location });
+
+        let vertexAIOptions: VertexAIOptions;
+        if (options.instanceIdentifier) {
+          vertexAIOptions = parseInstanceIdentifier(options.instanceIdentifier);
+        } else {
+          vertexAIOptions = {
+            developerAPIEnabled: false,
+            location: undefined
+          };
+        }
+
+        return new VertexAIService(
+          app,
+          auth,
+          appCheckProvider,
+          vertexAIOptions
+        );
       },
       ComponentType.PUBLIC
     ).setMultipleInstances(true)

packages/vertexai/src/index.ts

@@ -24,8 +24,14 @@
 import { registerVersion, _registerComponent } from '@firebase/app';
 import { VertexAIService } from './service';
 import { VERTEX_TYPE } from './constants';
-import { Component, ComponentType } from '@firebase/component';
+import {
+  Component,
+  ComponentType,
+  InstanceFactoryOptions
+} from '@firebase/component';
 import { name, version } from '../package.json';
+import { parseInstanceIdentifier } from './helpers';
+import { VertexAIOptions } from './public-types';
 
 declare global {
   interface Window {
@@ -37,12 +43,28 @@ function registerVertex(): void {
   _registerComponent(
     new Component(
       VERTEX_TYPE,
-      (container, { instanceIdentifier: location }) => {
+      (container, options) => {
         // getImmediate for FirebaseApp will always succeed
         const app = container.getProvider('app').getImmediate();
         const auth = container.getProvider('auth-internal');
         const appCheckProvider = container.getProvider('app-check-internal');
-        return new VertexAIService(app, auth, appCheckProvider, { location });
+
+        let vertexAIOptions: VertexAIOptions;
+        if (options.instanceIdentifier) {
+          vertexAIOptions = parseInstanceIdentifier(options.instanceIdentifier);
+        } else {
+          vertexAIOptions = {
+            developerAPIEnabled: false,
+            location: undefined
+          };
+        }
+
+        return new VertexAIService(
+          app,
+          auth,
+          appCheckProvider,
+          vertexAIOptions
+        );
       },
       ComponentType.PUBLIC
     ).setMultipleInstances(true)

packages/vertexai/src/mapper.ts

@@ -0,0 +1,42 @@
+import { CitationMetadata, GenerateContentCandidate, GenerateContentResponse } from "./types";
+import { DeveloperAPI } from "./types/developerAPI";
+
+/**
+ * Maps a `GenerateContentResponse` from the Developer API to the format of the 
+ * `GenerateContentResponse` that we get from VertexAI that is exposed in the public API.
+ * 
+ * @internal
+ * 
+ * @param developerAPIResponse The `GenerateContentResponse` from the Developer API.
+ * @returns A `GenerateContentResponse` that conforms to the public API's format.
+ */
+export function mapGenerateContentResponse(developerAPIResponse: DeveloperAPI.GenerateContentResponse): GenerateContentResponse {
+  let candidates: GenerateContentCandidate[] | undefined = developerAPIResponse.candidates ? [] : undefined;
+  if (candidates) {
+    developerAPIResponse.candidates?.forEach(candidate => {
+      let citationMetadata: CitationMetadata | undefined
+      if (candidate.citationMetadata) {
+        citationMetadata = {
+          citations: candidate.citationMetadata.citationSources
+        }
+      }
+      const mappedCandidate = {
+        index: candidate.index,
+        content: candidate.content,
+        finishReason: candidate.finishReason,
+        finishMessage: candidate.finishMessage,
+        safetyRatings: candidate.safetyRatings,
+        citationMetadata,
+        groundingMetadata: candidate.groundingMetadata
+      };
+      candidates.push(mappedCandidate);
+    });
+  }
+
+  const generateContentResponse = {
+    candidates,
+    promptFeedback: developerAPIResponse.promptFeedback,
+    usageMetadata: developerAPIResponse.usageMetadata
+  }
+  return generateContentResponse;
+}

packages/vertexai/src/methods/generate-content.ts

@@ -26,6 +26,7 @@ import { Task, makeRequest } from '../requests/request';
 import { createEnhancedContentResponse } from '../requests/response-helpers';
 import { processStream } from '../requests/stream-reader';
 import { ApiSettings } from '../types/internal';
+import { mapGenerateContentResponse } from '../mapper';
 
 export async function generateContentStream(
   apiSettings: ApiSettings,
@@ -58,8 +59,13 @@ export async function generateContent(
     JSON.stringify(params),
     requestOptions
   );
-  const responseJson: GenerateContentResponse = await response.json();
-  const enhancedResponse = createEnhancedContentResponse(responseJson);
+  const responseJson: any = await response.json();
+  const generateContentResponse: GenerateContentResponse = apiSettings.developerAPIEnabled
+    ? mapGenerateContentResponse(responseJson)
+    : await responseJson;
+  const enhancedResponse = createEnhancedContentResponse(
+    generateContentResponse
+  );
   return {
     response: enhancedResponse
   };

packages/vertexai/src/models/vertexai-model.ts

@@ -56,8 +56,6 @@ export abstract class VertexAIModel {
    * @internal
    */
   protected constructor(vertexAI: VertexAI, modelName: string) {
-    this.model = VertexAIModel.normalizeModelName(modelName);
-
     if (!vertexAI.app?.options?.apiKey) {
       throw new VertexAIError(
         VertexAIErrorCode.NO_API_KEY,
@@ -72,7 +70,8 @@ export abstract class VertexAIModel {
       this._apiSettings = {
         apiKey: vertexAI.app.options.apiKey,
         project: vertexAI.app.options.projectId,
-        location: vertexAI.location
+        location: vertexAI.location,
+        developerAPIEnabled: vertexAI.developerAPIEnabled
       };
 
       if (
@@ -92,6 +91,11 @@ export abstract class VertexAIModel {
         this._apiSettings.getAuthToken = () =>
           (vertexAI as VertexAIService).auth!.getToken();
       }
+
+      this.model = VertexAIModel.normalizeModelName(
+        modelName,
+        this._apiSettings.developerAPIEnabled
+      );
     }
   }
 
@@ -101,19 +105,26 @@ export abstract class VertexAIModel {
    * @param modelName - The model name to normalize.
    * @returns The fully qualified model resource name.
    */
-  static normalizeModelName(modelName: string): string {
+  static normalizeModelName(
+    modelName: string,
+    developerAPIEnabled?: boolean
+  ): string {
     let model: string;
-    if (modelName.includes('/')) {
-      if (modelName.startsWith('models/')) {
-        // Add 'publishers/google' if the user is only passing in 'models/model-name'.
-        model = `publishers/google/${modelName}`;
+    if (developerAPIEnabled) {
+      model = `models/${modelName}`;
+    } else {
+      if (modelName.includes('/')) {
+        if (modelName.startsWith('models/')) {
+          // Add 'publishers/google' if the user is only passing in 'models/model-name'.
+          model = `publishers/google/${modelName}`;
+        } else {
+          // Any other custom format (e.g. tuned models) must be passed in correctly.
+          model = modelName;
+        }
       } else {
-        // Any other custom format (e.g. tuned models) must be passed in correctly.
-        model = modelName;
+        // If path is not included, assume it's a non-tuned model.
+        model = `publishers/google/models/${modelName}`;
       }
-    } else {
-      // If path is not included, assume it's a non-tuned model.
-      model = `publishers/google/models/${modelName}`;
     }
 
     return model;

packages/vertexai/src/public-types.ts

@@ -28,13 +28,15 @@ export interface VertexAI {
    * The {@link @firebase/app#FirebaseApp} this <code>{@link VertexAI}</code> instance is associated with.
    */
   app: FirebaseApp;
-  location: string;
+  developerAPIEnabled: boolean;
+  location: string; // This is only applicable if we're using the VertexAI API.
 }
 
 /**
  * Options when initializing the Vertex AI in Firebase SDK.
  * @public
  */
 export interface VertexAIOptions {
+  developerAPIEnabled: boolean;
   location?: string;
 }