@midscene/shared 0.28.2 → 0.28.3

package/src/env/global-config-manager.ts

@@ -0,0 +1,174 @@
+import { getDebug } from '../logger';
+import { initDebugConfig } from './init-debug';
+import type { ModelConfigManager } from './model-config-manager';
+import {
+  BOOLEAN_ENV_KEYS,
+  GLOBAL_ENV_KEYS,
+  NUMBER_ENV_KEYS,
+  STRING_ENV_KEYS,
+} from './types';
+
+import {
+  ALL_ENV_KEYS,
+  MATCH_BY_POSITION,
+  MODEL_ENV_KEYS,
+  type TGlobalConfig,
+} from './types';
+
+/**
+ * Collect global configs from process.env, overrideAIConfig, etc.
+ * And provider methods to get merged config value
+ */
+export class GlobalConfigManager {
+  private override:
+    | {
+        newConfig?: Partial<TGlobalConfig>;
+        extendMode?: boolean;
+      }
+    | undefined;
+
+  private keysHaveBeenRead: Record<string, boolean> = {};
+
+  private globalModelConfigManager: ModelConfigManager | undefined = undefined;
+
+  constructor() {
+    initDebugConfig();
+  }
+
+  /**
+   * recalculate allEnvConfig every time because process.env can be updated any time
+   */
+  public getAllEnvConfig() {
+    const envConfig = ALL_ENV_KEYS.reduce(
+      (p, name) => {
+        p[name] = process.env[name];
+        return p;
+      },
+      Object.create(null) as Record<string, string | undefined>,
+    );
+
+    if (this.override) {
+      const { newConfig, extendMode } = this.override;
+      if (extendMode) {
+        return { ...envConfig, ...newConfig };
+      } else {
+        return { ...newConfig };
+      }
+    } else {
+      return envConfig;
+    }
+  }
+
+  getEnvConfigValue(key: (typeof STRING_ENV_KEYS)[number]) {
+    const allConfig = this.getAllEnvConfig();
+
+    if (!STRING_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigValue with key ${key} is not supported.`);
+    }
+    if (key === MATCH_BY_POSITION) {
+      throw new Error(
+        'MATCH_BY_POSITION is deprecated, use MIDSCENE_USE_VL_MODEL instead',
+      );
+    }
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  }
+
+  /**
+   * read number only from process.env
+   */
+  getEnvConfigInNumber(key: (typeof NUMBER_ENV_KEYS)[number]): number {
+    const allConfig = this.getAllEnvConfig();
+
+    if (!NUMBER_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigInNumber with key ${key} is not supported`);
+    }
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+    return Number(value || '');
+  }
+
+  /**
+   * read boolean only from process.env
+   */
+  getEnvConfigInBoolean(key: (typeof BOOLEAN_ENV_KEYS)[number]): boolean {
+    const allConfig = this.getAllEnvConfig();
+
+    if (!BOOLEAN_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigInBoolean with key ${key} is not supported`);
+    }
+
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+
+    if (!value) {
+      return false;
+    }
+    if (/^(true|1)$/i.test(value)) {
+      return true;
+    }
+    if (/^(false|0)$/i.test(value)) {
+      return false;
+    }
+    return !!value.trim();
+  }
+
+  registerModelConfigManager(globalModelConfigManager: ModelConfigManager) {
+    this.globalModelConfigManager = globalModelConfigManager;
+  }
+
+  /**
+   * for overrideAIConfig
+   * can only override keys in MODEL_ENV_KEYS
+   */
+  overrideAIConfig(
+    newConfig: Partial<
+      Record<
+        (typeof GLOBAL_ENV_KEYS)[number] | (typeof MODEL_ENV_KEYS)[number],
+        string
+      >
+    >,
+    extendMode = false, // true: merge with global config, false: override global config
+  ) {
+    for (const key in newConfig) {
+      if (![...GLOBAL_ENV_KEYS, ...MODEL_ENV_KEYS].includes(key as never)) {
+        throw new Error(`Failed to override AI config, invalid key: ${key}`);
+      }
+      const value = newConfig[key as keyof typeof newConfig];
+      if (typeof value !== 'string') {
+        throw new Error(
+          `Failed to override AI config, value for key ${key} must be a string, but got with type ${typeof value}`,
+        );
+      }
+      if (this.keysHaveBeenRead[key]) {
+        console.warn(
+          `Warning: try to override AI config with key ${key} ,but it has been read.`,
+        );
+      }
+    }
+    const savedNewConfig = extendMode
+      ? {
+          ...this.override?.newConfig,
+          ...newConfig,
+        }
+      : newConfig;
+
+    this.override = {
+      newConfig: {
+        ...savedNewConfig,
+      },
+      extendMode,
+    };
+
+    if (!this.globalModelConfigManager) {
+      throw new Error(
+        'globalModelConfigManager is not registered, which should not happen',
+      );
+    }
+    this.globalModelConfigManager.clearModelConfigMap();
+  }
+}

package/src/env/helper.ts

@@ -1,5 +1,5 @@
 import { assert } from '../utils';
-import type { IModelConfig } from './model-config';
+import type { IModelConfig } from './types';
 
 const maskKey = (key: string, maskChar = '*') => {
   if (typeof key !== 'string' || key.length === 0) {

package/src/env/index.ts

@@ -1,3 +1,4 @@
 export * from './utils';
 export * from './types';
-export { UITarsModelVersion } from './parse';
+export { ModelConfigManager } from './model-config-manager';
+export { GlobalConfigManager } from './global-config-manager';

package/src/env/model-config-manager.ts

@@ -0,0 +1,135 @@
+import {
+  decideModelConfigFromEnv,
+  decideModelConfigFromIntentConfig,
+} from './decide-model-config';
+import type { GlobalConfigManager } from './global-config-manager';
+
+import type { IModelConfig, TIntent, TModelConfigFn } from './types';
+
+const ALL_INTENTS: TIntent[] = ['VQA', 'default', 'grounding', 'planning'];
+
+export type TIntentConfigMap = Record<
+  TIntent,
+  ReturnType<TModelConfigFn> | undefined
+>;
+
+export class ModelConfigManager {
+  private modelConfigMap: Record<TIntent, IModelConfig> | undefined = undefined;
+
+  // once modelConfigFn is set, isolatedMode will be true
+  // modelConfigMap will only depend on modelConfigFn and not effect by process.env
+  private isolatedMode = false;
+
+  private globalConfigManager: GlobalConfigManager | undefined = undefined;
+
+  constructor(modelConfigFn?: TModelConfigFn) {
+    if (modelConfigFn) {
+      this.isolatedMode = true;
+      const intentConfigMap = this.calcIntentConfigMap(modelConfigFn);
+      this.modelConfigMap =
+        this.calcModelConfigMapBaseOnIntent(intentConfigMap);
+    }
+  }
+
+  private calcIntentConfigMap(modelConfigFn: TModelConfigFn): TIntentConfigMap {
+    const intentConfigMap: TIntentConfigMap = {
+      VQA: undefined,
+      default: undefined,
+      grounding: undefined,
+      planning: undefined,
+    };
+
+    for (const i of ALL_INTENTS) {
+      const result = modelConfigFn({ intent: i });
+      if (!result) {
+        throw new Error(
+          `The agent has an option named modelConfig is a function, but it return ${result} when call with intent ${i}, which should be a object.`,
+        );
+      }
+      intentConfigMap[i] = result;
+    }
+    return intentConfigMap;
+  }
+
+  private calcModelConfigMapBaseOnIntent(intentConfigMap: TIntentConfigMap) {
+    const modelConfigMap: Record<TIntent, IModelConfig | undefined> = {
+      VQA: undefined,
+      default: undefined,
+      grounding: undefined,
+      planning: undefined,
+    };
+    for (const i of ALL_INTENTS) {
+      const result = decideModelConfigFromIntentConfig(
+        i,
+        intentConfigMap[i] as unknown as Record<string, string | undefined>,
+      );
+      modelConfigMap[i] = result;
+    }
+    return modelConfigMap as Record<TIntent, IModelConfig>;
+  }
+
+  private calcModelConfigMapBaseOnEnv(
+    allEnvConfig: Record<string, string | undefined>,
+  ) {
+    const modelConfigMap: Record<TIntent, IModelConfig | undefined> = {
+      VQA: undefined,
+      default: undefined,
+      grounding: undefined,
+      planning: undefined,
+    };
+    for (const i of ALL_INTENTS) {
+      const result = decideModelConfigFromEnv(i, allEnvConfig);
+      modelConfigMap[i] = result;
+    }
+    return modelConfigMap as Record<TIntent, IModelConfig>;
+  }
+
+  /**
+   * should only be called by GlobalConfigManager
+   */
+  clearModelConfigMap() {
+    if (this.isolatedMode) {
+      throw new Error(
+        'ModelConfigManager work in isolated mode, so clearModelConfigMap should not be called',
+      );
+    }
+    this.modelConfigMap = undefined;
+  }
+
+  /**
+   * if isolatedMode is true, modelConfigMap was initialized in constructor and can't be changed
+   * if isolatedMode is false, modelConfigMap can be changed by process.env so we need to recalculate it when it's undefined
+   */
+  getModelConfig(intent: TIntent): IModelConfig {
+    if (this.isolatedMode) {
+      if (!this.modelConfigMap) {
+        throw new Error(
+          'modelConfigMap is not initialized in isolated mode, which should not happen',
+        );
+      }
+      return this.modelConfigMap[intent];
+    } else {
+      if (!this.modelConfigMap) {
+        if (!this.globalConfigManager) {
+          throw new Error(
+            'globalConfigManager is not registered, which should not happen',
+          );
+        }
+        this.modelConfigMap = this.calcModelConfigMapBaseOnEnv(
+          this.globalConfigManager.getAllEnvConfig(),
+        );
+      }
+      return this.modelConfigMap[intent];
+    }
+  }
+
+  getUploadTestServerUrl(): string | undefined {
+    const { openaiExtraConfig } = this.getModelConfig('default');
+    const serverUrl = openaiExtraConfig?.REPORT_SERVER_URL as string;
+    return serverUrl;
+  }
+
+  registerGlobalConfigManager(globalConfigManager: GlobalConfigManager) {
+    this.globalConfigManager = globalConfigManager;
+  }
+}

package/src/env/parse.ts

@@ -5,30 +5,11 @@ import {
   MIDSCENE_USE_VLM_UI_TARS,
   type TVlModeTypes,
   type TVlModeValues,
+  UITarsModelVersion,
+  VL_MODE_RAW_VALID_VALUES,
 } from './types';
 
-export enum UITarsModelVersion {
-  V1_0 = '1.0',
-  V1_5 = '1.5',
-  DOUBAO_1_5_15B = 'doubao-1.5-15B',
-  DOUBAO_1_5_20B = 'doubao-1.5-20B',
-}
-
-const vlModeRawValidValues: TVlModeValues[] = [
-  'doubao-vision',
-  'gemini',
-  'qwen-vl',
-  'vlm-ui-tars',
-  'vlm-ui-tars-doubao',
-  'vlm-ui-tars-doubao-1.5',
-];
-
-/**
- *
- * @param vlModeRaw
- * @returns
- */
-export const parseVlModeAndUiTarsFromRaw = (
+export const parseVlModeAndUiTarsModelVersionFromRawValue = (
   vlModeRaw?: string,
 ): {
   vlMode?: TVlModeTypes;
@@ -41,9 +22,9 @@ export const parseVlModeAndUiTarsFromRaw = (
     };
   }
 
-  if (!vlModeRawValidValues.includes(vlModeRaw as never)) {
+  if (!VL_MODE_RAW_VALID_VALUES.includes(vlModeRaw as never)) {
     throw new Error(
-      `the value ${vlModeRaw} is not a valid VL_MODE value, must be one of ${vlModeRawValidValues}`,
+      `the value ${vlModeRaw} is not a valid VL_MODE value, must be one of ${VL_MODE_RAW_VALID_VALUES}`,
     );
   }
   const raw = vlModeRaw as TVlModeValues;

package/src/env/types.ts

@@ -484,9 +484,67 @@ export type TModelConfigFn = (options: {
   | IModelConfigForVQA
   | IModelConfigForPlanning
   | IModeConfigForGrounding
-  | IModelConfigForDefault
-  | IModelConfigForDefaultLegacy;
+  | IModelConfigForDefault;
 
-export interface IModelPreferences {
+export enum UITarsModelVersion {
+  V1_0 = '1.0',
+  V1_5 = '1.5',
+  DOUBAO_1_5_15B = 'doubao-1.5-15B',
+  DOUBAO_1_5_20B = 'doubao-1.5-20B',
+}
+
+export const VL_MODE_RAW_VALID_VALUES: TVlModeValues[] = [
+  'doubao-vision',
+  'gemini',
+  'qwen-vl',
+  'vlm-ui-tars',
+  'vlm-ui-tars-doubao',
+  'vlm-ui-tars-doubao-1.5',
+];
+
+export interface IModelConfig {
+  /**
+   * proxy
+   */
+  socksProxy?: string;
+  httpProxy?: string;
+  /**
+   * model
+   */
+  modelName: string;
+  /**
+   * OpenAI
+   */
+  openaiBaseURL?: string;
+  openaiApiKey?: string;
+  openaiExtraConfig?: Record<string, unknown>;
+  /**
+   * Azure
+   */
+  openaiUseAzureDeprecated?: boolean;
+  useAzureOpenai?: boolean;
+  azureOpenaiScope?: string;
+  azureOpenaiKey?: string;
+  azureOpenaiEndpoint?: string;
+  azureOpenaiApiVersion?: string;
+  azureOpenaiDeployment?: string;
+  azureExtraConfig?: Record<string, unknown>;
+  /**
+   * Anthropic
+   */
+  useAnthropicSdk?: boolean;
+  anthropicApiKey?: string;
+  /**
+   * - vlModeRaw: exists only in non-legacy logic. value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars', 'vlm-ui-tars-doubao', 'vlm-ui-tars-doubao-1.5'
+   * - vlMode: based on the results of the vlModoRaw classification，value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars'
+   */
+  vlModeRaw?: string;
+  vlMode?: TVlModeTypes;
+  uiTarsModelVersion?: UITarsModelVersion;
+  modelDescription: string;
+  /**
+   * for debug
+   */
   intent: TIntent;
+  from: 'modelConfig' | 'env' | 'legacy-env';
 }

package/src/env/utils.ts

@@ -1,91 +1,17 @@
-import {
-  GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG,
-  GlobalConfigManager,
-} from './global-config';
-import type { UITarsModelVersion } from './parse';
+import { GlobalConfigManager } from './global-config-manager';
+import { ModelConfigManager } from './model-config-manager';
 import {
   type GLOBAL_ENV_KEYS,
-  type IModelPreferences,
   MIDSCENE_PREFERRED_LANGUAGE,
   type MODEL_ENV_KEYS,
-  type TVlModeTypes,
 } from './types';
 
-export const globalConfigManager = new GlobalConfigManager();
-
-export const uiTarsModelVersion = (
-  modelPreferences: IModelPreferences,
-): UITarsModelVersion | undefined => {
-  try {
-    const result = globalConfigManager.getModelConfigByIntent(
-      modelPreferences.intent,
-    );
-    return result.uiTarsVersion;
-  } catch (e) {
-    if ((e as any)?.[GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG]) {
-      console.warn(
-        "Call uiTarsModelVersion before globalConfig init, will return undefined. This warning should only appear in midscene's own unit tests.",
-      );
-      return undefined;
-    }
-    throw e;
-  }
-};
-
-export const vlLocateMode = (
-  modelPreferences: IModelPreferences,
-): TVlModeTypes | undefined => {
-  try {
-    const result = globalConfigManager.getModelConfigByIntent(
-      modelPreferences.intent,
-    );
-    return result.vlMode as TVlModeTypes;
-  } catch (e) {
-    if ((e as any)?.[GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG]) {
-      console.warn(
-        "Call vlLocateMode before globalConfig init, will return undefined. This warning should only appear in midscene's own unit tests.",
-      );
-      return undefined;
-    }
-    throw e;
-  }
-};
+export const globalModelConfigManager = new ModelConfigManager();
 
-export const getIsUseQwenVl = (modelPreferences: IModelPreferences) => {
-  try {
-    const result = globalConfigManager.getModelConfigByIntent(
-      modelPreferences.intent,
-    );
-    return result.vlMode === 'qwen-vl';
-  } catch (e) {
-    if ((e as any)?.[GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG]) {
-      console.warn(
-        "Call getIsUseQwenVl before globalConfig init, will return false. This warning should only appear in midscene's own unit tests.",
-      );
-      return false;
-    }
-    throw e;
-  }
-};
+export const globalConfigManager = new GlobalConfigManager();
 
-export function getModelName(
-  modelPreferences: IModelPreferences,
-): string | undefined {
-  try {
-    const result = globalConfigManager.getModelConfigByIntent(
-      modelPreferences.intent,
-    );
-    return result?.modelName;
-  } catch (e) {
-    if ((e as any)?.[GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG]) {
-      console.warn(
-        "Call getModelName before globalConfig init, will return undefined. This warning should only appear in midscene's own unit tests.",
-      );
-      return undefined;
-    }
-    throw e;
-  }
-}
+globalConfigManager.registerModelConfigManager(globalModelConfigManager);
+globalModelConfigManager.registerGlobalConfigManager(globalConfigManager);
 
 export const getPreferredLanguage = () => {
   const prefer = globalConfigManager.getEnvConfigValue(
@@ -100,23 +26,6 @@ export const getPreferredLanguage = () => {
   return isChina ? 'Chinese' : 'English';
 };
 
-export const getUploadTestServerUrl = (): string | undefined => {
-  try {
-    const { openaiExtraConfig } =
-      globalConfigManager.getModelConfigByIntent('default');
-    const serverUrl = openaiExtraConfig?.REPORT_SERVER_URL as string;
-    return serverUrl;
-  } catch (e) {
-    if ((e as any)?.[GLOBAL_CONFIG_MANAGER_UNINITIALIZED_FLAG]) {
-      console.warn(
-        "Call getUploadTestServerUrl before globalConfig init, will return undefined. This warning should only appear in midscene's own unit tests.",
-      );
-      return undefined;
-    }
-    throw e;
-  }
-};
-
 export const overrideAIConfig = (
   newConfig: Partial<
     Record<
@@ -126,5 +35,5 @@ export const overrideAIConfig = (
   >,
   extendMode = false, // true: merge with global config, false: override global config
 ) => {
-  globalConfigManager.registerOverride(newConfig, extendMode);
+  globalConfigManager.overrideAIConfig(newConfig, extendMode);
 };