@godscene/shared 1.7.11

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

@@ -0,0 +1,191 @@
+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 (key === MATCH_BY_POSITION) {
+      throw new Error(
+        'MATCH_BY_POSITION is discarded, use MIDSCENE_MODEL_FAMILY instead',
+      );
+    }
+
+    if (!STRING_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigValue with key ${key} is not supported.`);
+    }
+
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return 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();
+  }
+
+  /**
+   * Read environment variable value and convert it to number.
+   * Returns undefined if the value is not set or cannot be converted to a valid number.
+   */
+  getEnvConfigValueAsNumber(
+    key: (typeof STRING_ENV_KEYS)[number] | (typeof NUMBER_ENV_KEYS)[number],
+  ): number | undefined {
+    if (
+      !STRING_ENV_KEYS.includes(key as never) &&
+      !NUMBER_ENV_KEYS.includes(key as never)
+    ) {
+      throw new Error(
+        `getEnvConfigValueAsNumber with key ${key} is not supported.`,
+      );
+    }
+
+    const allConfig = this.getAllEnvConfig();
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const numValue = Number(trimmed);
+    return Number.isNaN(numValue) ? undefined : numValue;
+  }
+
+  registerModelConfigManager(globalModelConfigManager: ModelConfigManager) {
+    this.globalModelConfigManager = globalModelConfigManager;
+  }
+
+  /**
+   * @deprecated use the modelConfig param in Agent constructor instead
+   */
+  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

@@ -0,0 +1,58 @@
+import { assert } from '../utils';
+import type { IModelConfig } from './types';
+
+const maskKey = (key: string, maskChar = '*') => {
+  if (typeof key !== 'string' || key.length === 0) {
+    return key;
+  }
+
+  const prefixLen = 3;
+  const suffixLen = 3;
+  const keepLength = prefixLen + suffixLen;
+
+  if (key.length <= keepLength) {
+    return key;
+  }
+
+  const prefix = key.substring(0, prefixLen);
+  const suffix = key.substring(key.length - suffixLen);
+  const maskLength = key.length - keepLength;
+  const mask = maskChar.repeat(maskLength);
+
+  return `${prefix}${mask}${suffix}`;
+};
+
+export const maskConfig = (config: Record<string, unknown>) => {
+  return Object.fromEntries(
+    Object.entries(config).map(([key, value]) => {
+      if (!value) return [key, value];
+
+      if (typeof value === 'string' && /key/i.test(key)) {
+        return [key, maskKey(value)];
+      }
+      if (typeof value === 'object') {
+        const valueStr = JSON.stringify(value);
+        if (/key/i.test(valueStr)) {
+          return [key, maskKey(valueStr)];
+        }
+      }
+      return [key, value];
+    }),
+  );
+};
+
+export const parseJson = (key: string, value: string | undefined) => {
+  if (value) {
+    try {
+      return JSON.parse(value);
+    } catch (e) {
+      throw new Error(
+        `Failed to parse ${key} as a JSON. ${(e as Error).message}`,
+        {
+          cause: e,
+        },
+      );
+    }
+  }
+  return undefined;
+};

package/src/env/index.ts

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

package/src/env/init-debug.ts

@@ -0,0 +1,34 @@
+import { enableDebug } from '../logger';
+import { getBasicEnvValue } from './basic';
+import {
+  MIDSCENE_DEBUG_MODEL_PROFILE,
+  MIDSCENE_DEBUG_MODEL_RESPONSE,
+} from './types';
+
+export const initDebugConfig = () => {
+  const shouldPrintTiming = getBasicEnvValue(MIDSCENE_DEBUG_MODEL_PROFILE);
+  let debugConfig = '';
+  if (shouldPrintTiming) {
+    console.warn(
+      'MIDSCENE_DEBUG_MODEL_PROFILE is deprecated, use DEBUG=midscene:ai:profile instead',
+    );
+    debugConfig = 'ai:profile';
+  }
+  const shouldPrintModelResponse = getBasicEnvValue(
+    MIDSCENE_DEBUG_MODEL_RESPONSE,
+  );
+
+  if (shouldPrintModelResponse) {
+    console.warn(
+      'MIDSCENE_DEBUG_MODEL_RESPONSE is deprecated, use DEBUG=midscene:ai:response instead',
+    );
+    if (debugConfig) {
+      debugConfig = 'ai:*';
+    } else {
+      debugConfig = 'ai:call';
+    }
+  }
+  if (debugConfig) {
+    enableDebug(debugConfig);
+  }
+};

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

@@ -0,0 +1,149 @@
+import type { GlobalConfigManager } from './global-config-manager';
+import { decideModelConfigFromIntentConfig } from './parse-model-config';
+
+import type {
+  CreateOpenAIClientFn,
+  IModelConfig,
+  TIntent,
+  TModelConfig,
+} from './types';
+
+export class ModelConfigManager {
+  private modelConfigMap: Record<TIntent, IModelConfig> | undefined = undefined;
+
+  private isInitialized = false;
+
+  // once modelConfig is set, isolatedMode will be true
+  // modelConfigMap will only depend on provided config and not be affected by process.env
+  private isolatedMode = false;
+
+  private globalConfigManager: GlobalConfigManager | undefined = undefined;
+
+  private modelConfig?: TModelConfig;
+  private createOpenAIClientFn?: CreateOpenAIClientFn;
+
+  constructor(
+    modelConfig?: TModelConfig,
+    createOpenAIClientFn?: CreateOpenAIClientFn,
+  ) {
+    this.modelConfig = modelConfig;
+    this.createOpenAIClientFn = createOpenAIClientFn;
+  }
+
+  private initialize() {
+    if (this.isInitialized) {
+      return;
+    }
+
+    let configMap: Record<string, string | undefined>;
+    if (this.modelConfig) {
+      this.isolatedMode = true;
+      configMap = this.normalizeModelConfig(this.modelConfig);
+    } else {
+      configMap = this.globalConfigManager?.getAllEnvConfig() || {};
+    }
+
+    const defaultConfig = decideModelConfigFromIntentConfig(
+      'default',
+      configMap,
+    );
+    if (!defaultConfig) {
+      throw new Error(
+        'Model configuration is incomplete: model name (MIDSCENE_MODEL_NAME) is required. See https://midscenejs.com/model-strategy.html',
+      );
+    }
+
+    const insightConfig = decideModelConfigFromIntentConfig(
+      'insight',
+      configMap,
+    );
+
+    const planningConfig = decideModelConfigFromIntentConfig(
+      'planning',
+      configMap,
+    );
+
+    // Each intent uses its own timeout from parsed config (MIDSCENE_MODEL_TIMEOUT,
+    // MIDSCENE_INSIGHT_MODEL_TIMEOUT, MIDSCENE_PLANNING_MODEL_TIMEOUT).
+    this.modelConfigMap = {
+      default: {
+        ...defaultConfig,
+        createOpenAIClient: this.createOpenAIClientFn,
+      },
+      insight: {
+        ...(insightConfig || defaultConfig),
+        createOpenAIClient: this.createOpenAIClientFn,
+      },
+      planning: {
+        ...(planningConfig || defaultConfig),
+        createOpenAIClient: this.createOpenAIClientFn,
+      },
+    };
+
+    this.isInitialized = true;
+  }
+
+  private normalizeModelConfig(
+    config: TModelConfig,
+  ): Record<string, string | undefined> {
+    return Object.entries(config).reduce<Record<string, string | undefined>>(
+      (acc, [key, value]) => {
+        if (value === undefined || value === null) {
+          return acc;
+        }
+        acc[key] = String(value);
+        return acc;
+      },
+      Object.create(null),
+    );
+  }
+
+  /**
+   * 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.isInitialized = false;
+  }
+
+  /**
+   * 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 {
+    // check if initialized
+    if (!this.isInitialized) {
+      this.initialize();
+    }
+    if (!this.modelConfigMap) {
+      throw new Error(
+        'modelConfigMap is not initialized, which should not happen',
+      );
+    }
+    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;
+  }
+
+  throwErrorIfNonVLModel() {
+    const modelConfig = this.getModelConfig('default');
+
+    if (!modelConfig.modelFamily) {
+      throw new Error(
+        'MIDSCENE_MODEL_FAMILY is not set to a visual language model (VL model), the element localization can not be achieved. Check your model configuration. See https://midscenejs.com/model-strategy.html',
+      );
+    }
+  }
+}