feat(genai): controlled generation

genai/controlled-generation/ctrlgen-with-class-schema.js

@@ -0,0 +1,60 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+// [START googlegenaisdk_ctrlgen_with_class_schema]
+const {GoogleGenAI} = require('@google/genai');
+
+const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
+const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+async function generateContent(
+  projectId = GOOGLE_CLOUD_PROJECT,
+  location = GOOGLE_CLOUD_LOCATION
+) {
+  const ai = new GoogleGenAI({
+    vertexai: true,
+    project: projectId,
+    location: location,
+  });
+
+  class Recipe {
+    /**
+     * @param {string} recipe_name
+     * @param {string[]} ingredients
+     */
+    constructor(recipe_name, ingredients) {
+      this.recipe_name = recipe_name;
+      this.ingredients = ingredients;
+    }
+  }
+
+  const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: 'List a few popular cookie recipes?',
+    config: {
+      responseMimeType: 'application/json',
+      responseSchema: Recipe,
+    },
+  });
+
+  console.log(response.text);
+  return response.text;
+}
+// [END googlegenaisdk_ctrlgen_with_class_schema]
+
+module.exports = {
+  generateContent,
+};

genai/controlled-generation/ctrlgen-with-enum-class-schema.js

@@ -0,0 +1,73 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+// [START googlegenaisdk_ctrlgen_with_enum_class_schema]
+const {GoogleGenAI} = require('@google/genai');
+
+const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
+const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+async function generateContent(
+  projectId = GOOGLE_CLOUD_PROJECT,
+  location = GOOGLE_CLOUD_LOCATION
+) {
+  const ai = new GoogleGenAI({
+    vertexai: true,
+    project: projectId,
+    location: location,
+  });
+
+  class InstrumentClass {
+    static values() {
+      return [
+        InstrumentClass.PERCUSSION,
+        InstrumentClass.STRING,
+        InstrumentClass.WOODWIND,
+        InstrumentClass.BRASS,
+        InstrumentClass.KEYBOARD,
+      ];
+    }
+  }
+
+  InstrumentClass.PERCUSSION = 'Percussion';
+  InstrumentClass.STRING = 'String';
+  InstrumentClass.WOODWIND = 'Woodwind';
+  InstrumentClass.BRASS = 'Brass';
+  InstrumentClass.KEYBOARD = 'Keyboard';
+
+  const responseSchema = {
+    type: 'string',
+    enum: InstrumentClass.values(),
+  };
+
+  const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: 'What type of instrument is a guitar?',
+    config: {
+      responseMimeType: 'text/x.enum',
+      responseSchema: responseSchema,
+    },
+  });
+
+  console.log(response.text);
+
+  return response.text;
+}
+// [END googlegenaisdk_ctrlgen_with_enum_class_schema]
+
+module.exports = {
+  generateContent,
+};

genai/controlled-generation/ctrlgen-with-enum-schema.js

@@ -36,7 +36,7 @@ async function generateContent(
   };
 
   const response = await ai.models.generateContent({
-    model: 'gemini-2.0-flash',
+    model: 'gemini-2.5-flash',
     contents: 'What type of instrument is an oboe?',
     config: {
       responseMimeType: 'text/x.enum',

genai/controlled-generation/ctrlgen-with-nested-class-schema.js

@@ -0,0 +1,74 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+// [START googlegenaisdk_ctrlgen_with_nested_class_schema]
+const {GoogleGenAI} = require('@google/genai');
+
+const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
+const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+async function generateContent(
+  projectId = GOOGLE_CLOUD_PROJECT,
+  location = GOOGLE_CLOUD_LOCATION
+) {
+  const ai = new GoogleGenAI({
+    vertexai: true,
+    project: projectId,
+    location: location,
+  });
+
+  const Grade = Object.freeze({
+    A_PLUS: 'a+',
+    A: 'a',
+    B: 'b',
+    C: 'c',
+    D: 'd',
+    F: 'f',
+  });
+
+  class Recipe {
+    /**
+     * @param {string} recipe_name
+     * @param {string} rating - Must be one of Grade enum values
+     */
+    constructor(recipe_name, rating) {
+      if (!Object.values(Grade).includes(rating)) {
+        throw new Error(`Invalid rating: ${rating}`);
+      }
+      this.recipe_name = recipe_name;
+      this.rating = rating;
+    }
+  }
+
+  const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents:
+      'List about 10 home-baked cookies and give them grades based on tastiness.',
+    config: {
+      responseMimeType: 'application/json',
+      responseSchema: Recipe,
+    },
+  });
+
+  console.log(response.text);
+
+  return response.text;
+}
+// [END googlegenaisdk_ctrlgen_with_nested_class_schema]
+
+module.exports = {
+  generateContent,
+};

genai/controlled-generation/ctrlgen-with-nullable-schema.js

@@ -0,0 +1,80 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+// [START googlegenaisdk_ctrlgen_with_nullable_schema]
+const {GoogleGenAI} = require('@google/genai');
+
+const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
+const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+async function generateContent(
+  projectId = GOOGLE_CLOUD_PROJECT,
+  location = GOOGLE_CLOUD_LOCATION
+) {
+  const ai = new GoogleGenAI({
+    vertexai: true,
+    project: projectId,
+    location: location,
+  });
+
+  const prompt = `
+  The week ahead brings a mix of weather conditions.
+  Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
+  Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
+  Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
+  Wednesday may see thunderstorms, with a temperature of 68°F.
+  Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
+  Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
+  Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
+`;
+
+  const responseSchema = {
+    type: 'object',
+    properties: {
+      forecast: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            Day: {type: 'string', nullable: true},
+            Forecast: {type: 'string', nullable: true},
+            Temperature: {type: 'integer', nullable: true},
+            Humidity: {type: 'string', nullable: true},
+            'Wind Speed': {type: 'integer', nullable: true},
+          },
+          required: ['Day', 'Temperature', 'Forecast', 'Wind Speed'],
+        },
+      },
+    },
+  };
+
+  const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: prompt,
+    config: {
+      responseMimeType: 'application/json',
+      responseSchema: responseSchema,
+    },
+  });
+  console.log(response.text);
+
+  return response.text;
+}
+// [END googlegenaisdk_ctrlgen_with_nullable_schema]
+
+module.exports = {
+  generateContent,
+};

genai/controlled-generation/ctrlgen-with-resp-schema.js

@@ -0,0 +1,67 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+// [START googlegenaisdk_ctrlgen_with_resp_schema]
+const {GoogleGenAI} = require('@google/genai');
+
+const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
+const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+async function generateContent(
+  projectId = GOOGLE_CLOUD_PROJECT,
+  location = GOOGLE_CLOUD_LOCATION
+) {
+  const ai = new GoogleGenAI({
+    vertexai: true,
+    project: projectId,
+    location: location,
+  });
+
+  const prompt = 'List a few popular cookie recipes.';
+
+  const responseSchema = {
+    type: 'ARRAY',
+    items: {
+      type: 'OBJECT',
+      properties: {
+        recipe_name: {type: 'STRING'},
+        ingredients: {
+          type: 'ARRAY',
+          items: {type: 'STRING'},
+        },
+      },
+      required: ['recipe_name', 'ingredients'],
+    },
+  };
+
+  const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: prompt,
+    config: {
+      responseMimeType: 'application/json',
+      responseSchema: responseSchema,
+    },
+  });
+
+  console.log(response.text);
+
+  return response.text;
+}
+// [END googlegenaisdk_ctrlgen_with_resp_schema]
+
+module.exports = {
+  generateContent,
+};

genai/test/ctrlgen-with-class-schema.test.js

@@ -0,0 +1,29 @@
+// 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
+//
+//     https://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.
+
+'use strict';
+
+const {assert} = require('chai');
+const {describe, it} = require('mocha');
+
+const projectId = process.env.CAIP_PROJECT_ID;
+const sample = require('../controlled-generation/ctrlgen-with-class-schema.js');
+
+describe('ctrlgen-with-class-schema', () => {
+  it('should generate text content in Json', async function () {
+    this.timeout(10000);
+    const output = await sample.generateContent(projectId);
+    assert(output.length > 0 && output.includes('Cookies'));
+  });
+});