@rpascene/shared 0.30.8

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

@@ -0,0 +1,319 @@
+import type {
+  IModelConfig,
+  TIntent,
+  TVlModeTypes,
+  UITarsModelVersion,
+} from './types';
+
+import {
+  DEFAULT_MODEL_CONFIG_KEYS,
+  DEFAULT_MODEL_CONFIG_KEYS_LEGACY,
+  GROUNDING_MODEL_CONFIG_KEYS,
+  PLANNING_MODEL_CONFIG_KEYS,
+  VQA_MODEL_CONFIG_KEYS,
+} from './constants';
+
+import { getDebug } from '../logger';
+import { assert } from '../utils';
+import { createAssert, maskConfig, parseJson } from './helper';
+import { initDebugConfig } from './init-debug';
+import {
+  parseVlModeAndUiTarsFromGlobalConfig,
+  parseVlModeAndUiTarsModelVersionFromRawValue,
+} from './parse';
+
+type TModelConfigKeys =
+  | typeof VQA_MODEL_CONFIG_KEYS
+  | typeof GROUNDING_MODEL_CONFIG_KEYS
+  | typeof PLANNING_MODEL_CONFIG_KEYS
+  | typeof DEFAULT_MODEL_CONFIG_KEYS
+  | typeof DEFAULT_MODEL_CONFIG_KEYS_LEGACY;
+
+const KEYS_MAP: Record<TIntent, TModelConfigKeys> = {
+  VQA: VQA_MODEL_CONFIG_KEYS,
+  grounding: GROUNDING_MODEL_CONFIG_KEYS,
+  planning: PLANNING_MODEL_CONFIG_KEYS,
+  default: DEFAULT_MODEL_CONFIG_KEYS,
+} as const;
+
+/**
+ * Choose OpenAI SDK config, such as OpenAI, AzureOpenAI, AnthropicSDK, etc.
+ */
+export const decideOpenaiSdkConfig = ({
+  keys,
+  provider,
+  valueAssert,
+}: {
+  keys: TModelConfigKeys;
+  provider: Record<string, string | undefined>;
+  valueAssert: (
+    value: string | undefined,
+    key: string,
+    modelVendorFlag?: string,
+  ) => void;
+}): Omit<
+  IModelConfig,
+  | 'modelName'
+  | 'from'
+  | 'vlMode'
+  | 'uiTarsVersion'
+  | 'modelDescription'
+  | 'intent'
+> => {
+  initDebugConfig();
+  const debugLog = getDebug('ai:config');
+
+  const socksProxy = provider[keys.socksProxy];
+  const httpProxy = provider[keys.httpProxy];
+  const vlMode = provider[keys.vlMode];
+
+  debugLog('enter decideOpenaiSdkConfig with keys:', keys);
+  if (provider[keys.openaiUseAzureDeprecated]) {
+    debugLog(
+      `provider has ${keys.openaiUseAzureDeprecated} with value${provider[keys.openaiUseAzureDeprecated]}`,
+    );
+    const openaiBaseURL = provider[keys.openaiBaseURL];
+    const openaiApiKey = provider[keys.openaiApiKey];
+    const openaiExtraConfig = parseJson(
+      keys.openaiExtraConfig,
+      provider[keys.openaiExtraConfig],
+    );
+
+    valueAssert(openaiApiKey, keys.openaiApiKey, keys.openaiUseAzureDeprecated);
+
+    return {
+      socksProxy,
+      httpProxy,
+      vlModeRaw: vlMode,
+      openaiUseAzureDeprecated: true,
+      openaiApiKey,
+      openaiBaseURL,
+      openaiExtraConfig,
+    };
+  } else if (provider[keys.useAzureOpenai]) {
+    debugLog(
+      `provider has ${keys.useAzureOpenai} with value ${provider[keys.useAzureOpenai]}`,
+    );
+    const azureOpenaiScope = provider[keys.azureOpenaiScope];
+
+    const azureOpenaiKey = provider[keys.azureOpenaiKey];
+    const azureOpenaiEndpoint = provider[keys.azureOpenaiEndpoint];
+    const azureOpenaiDeployment = provider[keys.azureOpenaiDeployment];
+    const azureOpenaiApiVersion = provider[keys.azureOpenaiApiVersion];
+
+    const azureExtraConfig = parseJson(
+      keys.azureExtraConfig,
+      provider[keys.azureExtraConfig],
+    );
+    const openaiExtraConfig = parseJson(
+      keys.openaiExtraConfig,
+      provider[keys.openaiExtraConfig],
+    );
+
+    valueAssert(azureOpenaiKey, keys.azureOpenaiKey, keys.useAzureOpenai);
+
+    return {
+      socksProxy,
+      httpProxy,
+      vlModeRaw: vlMode,
+      useAzureOpenai: true,
+      azureOpenaiScope,
+      azureOpenaiKey,
+      azureOpenaiEndpoint,
+      azureOpenaiDeployment,
+      azureOpenaiApiVersion,
+      azureExtraConfig,
+      openaiExtraConfig,
+    };
+  } else if (provider[keys.useAnthropicSdk]) {
+    debugLog(
+      `provider has ${keys.useAnthropicSdk} with value ${provider[keys.useAnthropicSdk]}`,
+    );
+    const anthropicApiKey = provider[keys.anthropicApiKey];
+    valueAssert(anthropicApiKey, keys.anthropicApiKey, keys.useAnthropicSdk);
+
+    return {
+      socksProxy,
+      httpProxy,
+      useAnthropicSdk: true,
+      anthropicApiKey,
+    };
+  } else {
+    debugLog('provider has no specific model SDK declared');
+    const openaiBaseURL = provider[keys.openaiBaseURL];
+    const openaiApiKey = provider[keys.openaiApiKey];
+    const openaiExtraConfig = parseJson(
+      keys.openaiExtraConfig,
+      provider[keys.openaiExtraConfig],
+    );
+
+    valueAssert(openaiApiKey, keys.openaiApiKey);
+
+    return {
+      socksProxy,
+      httpProxy,
+      vlModeRaw: vlMode,
+      openaiBaseURL,
+      openaiApiKey,
+      openaiExtraConfig,
+    };
+  }
+};
+
+const getModelDescription = (
+  vlMode: TVlModeTypes | undefined,
+  uiTarsVersion: UITarsModelVersion | undefined,
+) => {
+  if (vlMode) {
+    if (uiTarsVersion) {
+      return `UI-TARS=${uiTarsVersion}`;
+    } else {
+      return `${vlMode} mode`;
+    }
+  }
+  return '';
+};
+
+export const decideModelConfigFromIntentConfig = (
+  intent: TIntent,
+  intentConfig: Record<string, string | undefined>,
+): IModelConfig => {
+  const debugLog = getDebug('ai:config');
+
+  debugLog('decideModelConfig base on agent.modelConfig()');
+
+  const keysForFn = KEYS_MAP[intent];
+
+  const candidateModelNameFromConfig = intentConfig[keysForFn.modelName];
+
+  debugLog('Got modelName from modelConfigFn', candidateModelNameFromConfig);
+
+  const chosenKeys = (() => {
+    if (candidateModelNameFromConfig) {
+      debugLog(
+        'query modelConfig from fn by intent got corresponding modelName, will get other corresponding keys',
+      );
+      return keysForFn;
+    } else {
+      debugLog(
+        'query modelConfig from fn by intent got no corresponding modelName, will get other keys by default',
+      );
+      assert(
+        intentConfig[DEFAULT_MODEL_CONFIG_KEYS.modelName],
+        `The return value of agent.modelConfig do not have a valid value with key ${DEFAULT_MODEL_CONFIG_KEYS.modelName}.`,
+      );
+      return DEFAULT_MODEL_CONFIG_KEYS;
+    }
+  })();
+
+  const result = decideOpenaiSdkConfig({
+    keys: chosenKeys,
+    provider: intentConfig,
+    valueAssert: createAssert(
+      chosenKeys.modelName,
+      'modelConfig',
+      candidateModelNameFromConfig,
+    ),
+  });
+
+  const { vlMode, uiTarsVersion } =
+    parseVlModeAndUiTarsModelVersionFromRawValue(result.vlModeRaw);
+
+  const modelDescription = getModelDescription(vlMode, uiTarsVersion);
+
+  const finalResult: IModelConfig = {
+    ...result,
+    modelName: intentConfig[chosenKeys.modelName]!,
+    vlMode,
+    uiTarsModelVersion: uiTarsVersion,
+    modelDescription,
+    from: 'modelConfig',
+    intent,
+  };
+
+  debugLog(
+    `decideModelConfig result by agent.modelConfig() with intent ${intent}:`,
+    maskConfig(finalResult),
+  );
+  return finalResult;
+};
+
+export const decideModelConfigFromEnv = (
+  intent: TIntent,
+  allEnvConfig: Record<string, string | undefined>,
+): IModelConfig => {
+  initDebugConfig();
+  const debugLog = getDebug('ai:config');
+
+  const keysForEnv =
+    intent === 'default' ? DEFAULT_MODEL_CONFIG_KEYS_LEGACY : KEYS_MAP[intent];
+
+  if (intent !== 'default' && allEnvConfig[keysForEnv.modelName]) {
+    const modelName = allEnvConfig[keysForEnv.modelName]!;
+
+    debugLog(
+      `Got intent ${intent} corresponding modelName ${modelName} by key ${keysForEnv.modelName} from globalConfig, will get other config by intent.`,
+    );
+
+    const result = decideOpenaiSdkConfig({
+      keys: keysForEnv,
+      provider: allEnvConfig,
+      valueAssert: createAssert(keysForEnv.modelName, 'process.env', modelName),
+    });
+
+    const { vlMode, uiTarsVersion } =
+      parseVlModeAndUiTarsModelVersionFromRawValue(result.vlModeRaw);
+    const modelDescription = getModelDescription(vlMode, uiTarsVersion);
+
+    const finalResult: IModelConfig = {
+      ...result,
+      modelName,
+      vlMode,
+      uiTarsModelVersion: uiTarsVersion,
+      modelDescription,
+      from: 'env',
+      intent,
+    };
+
+    debugLog(
+      `decideModelConfig result by process.env with intent ${intent}:`,
+      maskConfig(finalResult),
+    );
+    return finalResult;
+  }
+
+  debugLog(`decideModelConfig as legacy logic with intent ${intent}.`);
+
+  // TODO: when fallback to legacy logic, prefer to read RPASCENE_OPENAI_API_KEY rather than OPENAI_API_KEY
+  const result = decideOpenaiSdkConfig({
+    keys: DEFAULT_MODEL_CONFIG_KEYS_LEGACY,
+    provider: allEnvConfig,
+    valueAssert: createAssert(
+      DEFAULT_MODEL_CONFIG_KEYS_LEGACY.modelName,
+      'process.env',
+    ),
+  });
+
+  const { vlMode, uiTarsVersion } =
+    parseVlModeAndUiTarsFromGlobalConfig(allEnvConfig);
+
+  const modelDescription = getModelDescription(vlMode, uiTarsVersion);
+
+  const finalResult: IModelConfig = {
+    ...result,
+    // In the legacy logic, GPT-4o is the default model.
+    modelName:
+      allEnvConfig[DEFAULT_MODEL_CONFIG_KEYS_LEGACY.modelName] || 'gpt-4o',
+    vlMode,
+    uiTarsModelVersion: uiTarsVersion,
+    modelDescription,
+    from: 'legacy-env',
+    intent,
+  };
+
+  debugLog(
+    `decideModelConfig result by legacy logic with intent ${intent}:`,
+    maskConfig(finalResult),
+  );
+  return finalResult;
+};

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 RPASCENE_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

@@ -0,0 +1,80 @@
+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: IModelConfig) => {
+  return Object.fromEntries(
+    Object.entries(config).map(([key, value]) => {
+      if (['openaiApiKey', 'azureOpenaiKey', 'anthropicApiKey'].includes(key)) {
+        return [key, maskKey(value)];
+      } else if (['openaiExtraConfig', 'azureExtraConfig'].includes(key)) {
+        return [key, maskKey(JSON.stringify(value))];
+      }
+      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;
+};
+
+export const createAssert =
+  (
+    modelNameKey: string,
+    provider: 'process.env' | 'modelConfig',
+    modelName?: string,
+  ) =>
+  (value: string | undefined, key: string, modelVendorFlag?: string) => {
+    return
+    if (modelName) {
+      if (modelVendorFlag) {
+        assert(
+          value,
+          `The ${key} must be a non-empty string because of the ${modelNameKey} is declared as ${modelName} and ${modelVendorFlag} has also been specified in ${provider}, but got: ${value}. Please check your config.`,
+        );
+      } else {
+        assert(
+          value,
+          `The ${key} must be a non-empty string because of the ${modelNameKey} is declared as ${modelName} in ${provider}, but got: ${value}. Please check your config.`,
+        );
+      }
+    } else {
+      assert(
+        value,
+        `The ${key} must be a non-empty string, but got: ${value}. Please check your config.`,
+      );
+    }
+  };

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,29 @@
+import { enableDebug } from '../logger';
+import { getBasicEnvValue } from './basic';
+import { RPASCENE_DEBUG_AI_PROFILE, RPASCENE_DEBUG_AI_RESPONSE } from './types';
+
+export const initDebugConfig = () => {
+  const shouldPrintTiming = getBasicEnvValue(RPASCENE_DEBUG_AI_PROFILE);
+  let debugConfig = '';
+  if (shouldPrintTiming) {
+    console.warn(
+      'RPASCENE_DEBUG_AI_PROFILE is deprecated, use DEBUG=rpascene:ai:profile instead',
+    );
+    debugConfig = 'ai:profile';
+  }
+  const shouldPrintAIResponse = getBasicEnvValue(RPASCENE_DEBUG_AI_RESPONSE);
+
+  if (shouldPrintAIResponse) {
+    console.warn(
+      'RPASCENE_DEBUG_AI_RESPONSE is deprecated, use DEBUG=rpascene:ai:response instead',
+    );
+    if (debugConfig) {
+      debugConfig = 'ai:*';
+    } else {
+      debugConfig = 'ai:call';
+    }
+  }
+  if (debugConfig) {
+    enableDebug(debugConfig);
+  }
+};