Merge pull request #57 from google-marketing-solutions/release-v1.3

Release v1.3

Author: akushnarov

CODE_OF_CONDUCT.md

@@ -0,0 +1,108 @@
+<!--
+Copyright 2023 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.
+-->
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+This Code of Conduct also applies outside the project spaces when the Project
+Steward has a reasonable belief that an individual's behavior may have a
+negative impact on the project or its community.
+
+## Conflict Resolution
+
+We do not believe that all conflict is bad; healthy debate and disagreement
+often yield positive results. However, it is never okay to be disrespectful or
+to engage in behavior that violates the project’s code of conduct.
+
+If you see someone violating the code of conduct, you are encouraged to address
+the behavior directly with those involved. Many issues can be resolved quickly
+and easily, and this gives people more control over the outcome of their
+dispute. If you are unable to resolve the matter for any reason, or if the
+behavior is threatening or harassing, report it. We are dedicated to providing
+an environment where participants feel welcome and safe.
+
+Reports should be directed to _[PROJECT STEWARD NAME(s) AND EMAIL(s)]_, the
+Project Steward(s) for _[PROJECT NAME]_. It is the Project Steward’s duty to
+receive and address reported violations of the code of conduct. They will then
+work with a committee consisting of representatives from the Open Source
+Programs Office and the Google Open Source Strategy team. If for any reason you
+are uncomfortable reaching out to the Project Steward, please email
+opensource@google.com.
+
+We will investigate every complaint, but you may not receive a direct response.
+We will use our discretion in determining when and how to follow up on reported
+incidents, which may range from not taking action to permanent expulsion from
+the project and project-sponsored spaces. We will notify the accused of the
+report and provide them an opportunity to discuss it before any action is taken.
+The identity of the reporter will be omitted from the details of the report
+supplied to the accused. In potentially harmful situations, such as ongoing
+harassment or threats to anyone's safety, we may take action without notice.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
+available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct/

CONTRIBUTING CONTRIBUTING.mdCONTRIBUTING renamed to CONTRIBUTING.md

@@ -1,3 +1,18 @@
+<!--
+Copyright 2023 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.
+-->
 # How to Contribute
 
 We would love to accept your patches and contributions to this project.

README.md

@@ -54,24 +54,38 @@ Here are some of Adios's powerful features:
 - **Seamless A/B testing**: Easily create Google Ads experiments to compare the performance of your new image assets against your existing setup, optimizing click-through rates and campaign success.
 
 ## Releases & features
+
+### Adios v1.3
+
+Features:
+
+- Increased configuration flexibility in the 'Config' sheet. Now you can easily change AI models, GCP region, and other settings without editing the code.
+- Improved the stability and reliability of Gen API interactions. The tool now automatically retries failed requests, ensuring a smoother and more robust user experience.
+- Improved documentation in the Config sheet and on GitHub ([README](README.md)) to provide clearer guidance and support.
+
 ### Adios v1.2
 
 Features:
+
 - [Enhanced Triggers](#enhanced-triggers): Optimized how long-running services operate, addressing execution time limits for large-scale ad group processing. (See Google Apps Script [quotas for details](https://developers.google.com/apps-script/guides/services/quotas#current_limitations)).
 - [Google Ads API Mocks](#google-ads-api-mocks): Experiment with Adios features and functionality without needing a Google Ads account.
 - Text-to-Image prompt generation has been switched to Gemini 1.5 Flash.
 - The Google Ads API has been upgraded to version 17.
 
 ### Adios v1.1
+
 https://github.com/google-marketing-solutions/adios/assets/3335483/9be71a1a-43da-49ba-b203-598e797f1d64
 
 Features:
+
 - Automatic, AI ([Gemini](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/overview)) based image policy validation. Now you can write your brand, company, _you name it_ ads policies as a text and the generated image will be validated against those policies.
 - Ad Group names translations. Now you can translate your ad group names (or parts of them) e.g. into better text-to-image prompts.
 - Keyword based image generation. Previously you could generate images only based on the ad group names.
 
 ### Adios v1.0
+
 Features:
+
 - Generate image assets (ad group level) based on the ad group names
 - Image validation UI (validate manually generated images before uploading to Google Ads).
 - Upload generated assets to the Google Ads assets library.
@@ -84,7 +98,9 @@ Note: these features can be used separately, e.g. you can just upload images to
 
 https://github.com/google-marketing-solutions/adios/assets/3335483/f22172d3-38f1-4fdb-b366-67a33700180e
 
-1. Make a copy of the [template Spreadsheet: Adios v1.2](https://docs.google.com/spreadsheets/d/1DUNphGZIRL6mPDyrqgXErL-7p-gs0WmTqIjZl2ZXdSM/edit?usp=sharing) (in the main menu `File > Make a copy`). Earlier versions:
+1. Make a copy of the [template Spreadsheet: Adios v1.3](https://docs.google.com/spreadsheets/d/1e4OXlUaAYI1B0n7j5WOGEbzNsmAAFfkGg8rXZXejk3c/edit?usp=sharing) (in the main menu `File > Make a copy`). Earlier versions:
+
+   - [Adios v1.2](https://docs.google.com/spreadsheets/d/1DUNphGZIRL6mPDyrqgXErL-7p-gs0WmTqIjZl2ZXdSM/edit?usp=sharing)
    - [Adios v1.1](https://docs.google.com/spreadsheets/d/1A0UbhSiF1ox47WUbA4VZ4oh4WlwzbRbkuQHQshHNWiU/edit?usp=sharing&resourcekey=0-283C6nDIyps8TKhcgtxXeQ)
    - [Adios 1.0](https://docs.google.com/spreadsheets/d/1YnFCTif5ruLqs4qJIMcJmvejMEhvFHBzkBwfDp_oWRE/edit?resourcekey=0-mj_eJDv4XRwv2zwOJnYXug)
 
@@ -105,8 +121,28 @@ https://github.com/google-marketing-solutions/adios/assets/3335483/f22172d3-38f1
 
 1. Now you can run or schedule the Adios services using the Adios menu
 
+## Configuration
+
+Adios' configuration parameters are primarily located in the default "Config" sheet of the [template spreadsheet](#installation-guide). It is essential to complete the configuration before using Adios.
+
+Mandatory fields:
+
+- GCP Project Specific Parameters
+  - GCP Project
+  - GCS Bucket
+- Google Ads Specific Parameters (in case you use [Mocks](#google-ads-api-mocks), this is not required)
+  - Google Ads API Key (aka "developer token")
+  - Account ID, Manager Account ID, Campaign IDs
+
+Other Parameters:
+
+- **Preset Parameters**: Several parameters in the "Config" sheet come with preset values. You can modify these if needed based on your specific requirements.
+- **Optional Parameters**: Adios offers additional optional parameters to fine-tune its behavior.
+
 ## Assets generation
-Notes: 
+
+Notes:
+
 - this step is not required if you already have the assets.
 - starting from Adios v1.1 you can generate assets based on ad group keywords (check this [video](https://github.com/google-marketing-solutions/adios/assets/3335483/9be71a1a-43da-49ba-b203-598e797f1d64)).
 
@@ -116,8 +152,8 @@ https://github.com/google-marketing-solutions/adios/assets/3335483/72db55da-7ed1
 
 Want to try out image generation without real ad groups? Simulate them easily with a spreadsheet:
 
-- __Configure Adios__: In the "Config" sheet, add a variable named "Google Ads Mock Sheet". Choose a name for your mock sheet (e.g., "Mock") and set it as the value for this variable.
-- __Create Your Mock Data__: Create a new sheet with the name you chose (e.g., "Mock"). Make sure it has two columns:
+- **Configure Adios**: In the "Config" sheet, add a variable named "Google Ads Mock Sheet". Choose a name for your mock sheet (e.g., "Mock") and set it as the value for this variable.
+- **Create Your Mock Data**: Create a new sheet with the name you chose (e.g., "Mock"). Make sure it has two columns:
   - "Ad Group Name": Enter a name for each simulated ad group.
   - "Keywords": List the keywords associated with each ad group (comma separated).
 
@@ -162,6 +198,7 @@ As a result you will be able to see newly created experiments in the
    while your experiment is running may make it harder to interpret your results.
 
 ## Using the Validation UI
+
 Adios provides an optional UI for users to check the generated images and approve/reject them before uploading them to the Google Ads account.
 
 https://github.com/google-marketing-solutions/adios/assets/3335483/d3b15133-6f9e-4057-8fd7-b4ac77aff954
@@ -170,7 +207,7 @@ You can use it as follows:
 
 1. Ensure that there is a set `Validated DIR` in the configuration Spreadsheet (e.g. `VALIDATED`)
 
-    This is the name for the directory in the GCS bucket, where approved images will be saved. Disapproved images will be saved to the directory specified in `Disapproved DIR`.
+   This is the name for the directory in the GCS bucket, where approved images will be saved. Disapproved images will be saved to the directory specified in `Disapproved DIR`.
 
 1. In the Spreadsheet, open Extensions > Apps Script
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "adios",
-  "version": "1.1",
-  "description": "",
+  "version": "1.3",
+  "description": "Adios: One-stop solution for Google Ads image assets management",
   "main": "build/index.js",
   "license": "Apache-2.0",
   "keywords": [],

src/config.ts

@@ -40,6 +40,10 @@ interface Config {
   'Text Prompt Suffix': string;
   'Prompt translations sheet': string;
   'Google Ads Mock Sheet': string;
+  'GCP Region'?: string;
+  'VertexAI Api Domain Part'?: string;
+  'Gemini Model'?: string;
+  'Image Generation Model'?: string;
 }
 
 export const sheet =
@@ -71,6 +75,10 @@ const DEFAULT_CONFIG = {
   'Text Prompt Suffix': '',
   'Prompt translations sheet': '',
   'Google Ads Mock Sheet': '',
+  'GCP Region': undefined,
+  'VertexAI Api Domain Part': undefined,
+  'Gemini Model': undefined,
+  'Image Generation Model': undefined,
 };
 
 export const ADIOS_MODES = {

src/image-generation-service.ts

@@ -17,7 +17,12 @@ import { ADIOS_MODES, CONFIG } from './config';
 import { GcsApi } from './gcs-api';
 import { GoogleAdsApiFactory } from './google-ads-api-mock';
 import { Triggerable } from './triggerable';
-import { VertexAiApi } from './vertex-ai-api';
+import {
+  GeminiApiCallError,
+  ImageGenerationApiCallError,
+  JsonParseError,
+  VertexAiApi,
+} from './vertex-ai-api';
 
 export class ImageGenerationService extends Triggerable {
   private readonly _gcsApi;
@@ -28,8 +33,11 @@ export class ImageGenerationService extends Triggerable {
     super();
     this._gcsApi = new GcsApi(CONFIG['GCS Bucket']);
     this._vertexAiApi = new VertexAiApi(
-      'us-central1-aiplatform.googleapis.com',
-      CONFIG['GCP Project']!
+      CONFIG['GCP Project'],
+      CONFIG['GCP Region'],
+      CONFIG['VertexAI Api Domain Part'],
+      CONFIG['Gemini Model'],
+      CONFIG['Image Generation Model']
     );
     this._googleAdsApi = GoogleAdsApiFactory.createObject();
   }
@@ -95,7 +103,7 @@ export class ImageGenerationService extends Triggerable {
       // Process it in batches of max VISION_API_LIMIT images (as for now, 4)
       while (generatedImages < adGroupImgCount && numTries <= MAX_TRIES) {
         const imgCount = Math.min(
-          this._vertexAiApi.VISION_API_LIMIT,
+          this._vertexAiApi.IMAGE_GENERATION_API_LIMIT,
           adGroupImgCount - generatedImages
         );
 
@@ -161,7 +169,21 @@ export class ImageGenerationService extends Triggerable {
             textPrompt += ' ' + CONFIG['Text Prompt Suffix'];
           }
           Logger.log('Prompt to generate Imagen Prompt: ' + textPrompt);
-          imgPrompt = this._vertexAiApi.callGeminiApi(textPrompt);
+          try {
+            imgPrompt = this._vertexAiApi.callGeminiApi(textPrompt);
+          } catch (e) {
+            if (e instanceof JsonParseError) {
+              Logger.log('Gemini output is not correct JSON, retrying');
+            } else if (e instanceof GeminiApiCallError) {
+              Logger.log('Gemini call error, retrying');
+            } else {
+              throw e; // Unknown error
+            }
+
+            // retrying
+            numTries++;
+            continue;
+          }
         }
 
         if (CONFIG['Prompt translations sheet']) {
@@ -175,7 +197,23 @@ export class ImageGenerationService extends Triggerable {
         Logger.log(
           `Imagen Prompt for AdGroup ${adGroup.adGroup.name}: "${imgPrompt}"`
         );
-        const images = this._vertexAiApi.callVisionApi(imgPrompt, imgCount);
+
+        let images: string[] = [];
+        try {
+          images = this._vertexAiApi.callImageGenerationApi(
+            imgPrompt,
+            imgCount
+          );
+        } catch (e) {
+          if (e instanceof ImageGenerationApiCallError) {
+            Logger.log(
+              'Not able to generate images, this might be because of the blocked content (see the logs)...'
+            );
+          } else {
+            throw e; // Unknown error
+          }
+        }
+
         Logger.log(
           `Received ${images?.length || 0} images for ${adGroup.adGroup.name}(${
             adGroup.adGroup.id