@futdevpro/nts-dynamo 1.10.76 → 1.11.1

package/src/_modules/open-ai/_services/oai-llm.service-base.ts

@@ -0,0 +1,648 @@
+import { OpenAI } from 'openai';
+
+import { DyFM_OpenAI_Settings, DyFM_OpenAIModel, DyFM_GPTCall_Settings } from '@futdevpro/fsm-dynamo/open-ai';
+import { DyFM_AnyError, DyFM_Error, DyFM_Error_Settings, DyFM_Log, DyFM_notNull } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_OAI_GPT_Message } from '../_models/interfaces/oai-gpt-message.interface';
+import { ChatCompletion } from 'openai/resources';
+import { ChatCompletionCreateParamsBase, ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { DyNTS_OAI_GPT_Message_Role } from '../_enums/oai-gpt-message-role.enum';
+import { DyNTS_OAI_LLM_Predefined_Requests } from '../_models/interfaces/oai-llm-predefined-requests.interface';
+import { DyNTS_OAI_global_settings } from '../_collections/oai-global-settings.const';
+import { DyNTS_OAI_LLMDefaultPredefined_Requests } from '../_collections/oai-llm-predefined-requests.conts';
+
+
+/**
+ * {
+ *   organization: 'org-XY',
+ *   apiKey: 'sk-XY',
+ *   project: 'proj_XY',
+ * }
+ */
+
+// Di Dictionary DiModel DiEz DiAz
+
+export class DyNTS_OAI_LLM_ServiceBase {
+    
+  readonly defaultErrorUserMsg: string = 
+    `We encountered an unhandled Control Service Error, ` +
+    `\nplease contact the responsible development team.`; 
+
+  readonly openai: OpenAI;
+
+  /* readonly defaultSystemPrompt: string;
+  readonly defaultModel: DyFM_OpenAIModel | string; */
+  readonly defaultSettings: DyFM_GPTCall_Settings;
+
+  get debugLog(): boolean {
+    return this.defaultSettings.debugLog;
+  }
+
+  get defaultSystemPrompt(): string {
+    return this.defaultSettings.systemPrompt;
+  }
+
+  get defaultModel(): DyFM_OpenAIModel | string {
+    return this.defaultSettings.useModel;
+  }
+
+  readonly predefinedRequests: DyNTS_OAI_LLM_Predefined_Requests = 
+    DyNTS_OAI_LLMDefaultPredefined_Requests;
+
+  constructor(
+    set?: DyFM_OpenAI_Settings
+  ) {
+    DyNTS_global_settings.openAi_settings ??= DyNTS_OAI_global_settings;
+    
+    this.openai = new OpenAI(
+      set?.openAIConfig ?? 
+      {
+        organization: DyNTS_global_settings.env_settings.openAi.organization,
+        apiKey: DyNTS_global_settings.env_settings.openAi.apiKey,
+        project: DyNTS_global_settings.env_settings.openAi.project,
+      }
+    );
+
+    this.defaultSettings = set?.defaultSettings ?? 
+      DyNTS_OAI_global_settings.defaultSettings ?? 
+      new DyFM_GPTCall_Settings();
+  }
+  
+  readonly defaultLogReplacer: string = '...';
+
+  //#region Ask Questions
+
+  /**
+   * Asks the AI to answer a yes/no question
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.yesNo.request} to ask the question,
+   * and the {@link DyNTS_OAI_LLM_Predefined_Requests.yesNo.upperCaseYes} to check the answer
+   */
+  async askYesNoQuestion(
+    question: string, 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<boolean> {
+    question += this.predefinedRequests.yesNo.request;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return answer.toUpperCase().includes(this.predefinedRequests.yesNo.upperCaseYes);
+  }
+  /** the exact same as {@link askYesNoQuestion} */
+  yesNoQuestion = this.askYesNoQuestion;
+
+  /**
+   * Asks the AI to answer a percentage question
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.percentageOnly} to ask the question
+   */
+  async askPercentageQuestion(
+    question: string, 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<number> {
+    question += this.predefinedRequests.percentageOnly;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    if (isNaN(+answer)) {
+      DyFM_Log.error('GPT_ServiceBase', 'asykPercentageQuestion', 'Invalid answer', {
+        question,
+        answer,
+      });
+
+      return null;
+    }
+
+    return +answer;
+  }
+  /** the exact same as {@link askPercentageQuestion} */
+  percentageQuestion = this.askPercentageQuestion;
+
+  /**
+   * Asks the AI to select one of the options from the list
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.selectRequest} to ask the question
+   */
+  async askSelectQuestion(
+    question: string, 
+    selectFrom: string[], 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<string> {
+    // replace the {{DyNTS_selectOptions}} with the list of options
+    const selectQuestionAddition = this.predefinedRequests.selectRequest.replace(
+      '{{DyNTS_selectOptions}}', 
+      this.getTextListAsText(selectFrom)
+    );
+    question += selectQuestionAddition;
+
+    let answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+    
+    answer = answer.toLocaleUpperCase();
+    
+    for (const item of selectFrom) {
+      if (answer.includes(item.toLocaleUpperCase())) return item;
+    }
+
+    return null;
+  }
+  /** the exact same as {@link askSelectQuestion} */
+  selectQuestion = this.askSelectQuestion;
+
+  /**
+   * Asks the AI to select one of the options from the list
+   * Similar to {@link askSelectQuestion}, 
+   * but with a more generic approach that can be used for objects
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.selectRequest} to ask the question
+   */
+  async requestSelect<T>(
+    question: string,
+    selectFrom: T[],
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string,
+  ): Promise<T | { unparsableResult: string }> {
+    const selectQuestionAddition = this.predefinedRequests.selectRequest.replace(
+      '{{DyNTS_selectOptions}}', 
+      this.getTextListAsText(selectFrom.map(item => `"${JSON.stringify(item)}"`))
+    );
+    question += selectQuestionAddition;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return DyFM_safeParseJSON<T>(answer);
+  }
+  /** the exact same as {@link requestSelect} */
+  selectRequest = this.requestSelect;
+
+  /**
+   * Asks the AI to select one or more of the options from the list
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.multiselect} to ask the question
+   */
+  async askMultipleSelectQuestionWithOptions(
+    question: string, 
+    options: string[], 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<string[]> {
+    const selectQuestionAddition = this.predefinedRequests.multiselect.replace(
+      '{{DyNTS_selectOptions}}', 
+      this.getTextListAsText(options)
+    );
+    question += selectQuestionAddition;
+
+    let answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+    
+    answer = answer.toLocaleUpperCase();
+    
+    const result: string[] = [];
+
+    for (const item of options) {
+      if (answer.includes(item.toLocaleUpperCase())) {
+        result.push(item);
+      }
+    }
+
+    return result;
+  }
+  /** the exact same as {@link askMultipleSelectQuestionWithOptions} */
+  multipleSelectQuestion = this.askMultipleSelectQuestionWithOptions;
+
+  /**
+   * Asks the AI to select one or more of the options from the list
+   * Similar to {@link askMultipleSelectQuestionWithOptions}, 
+   * but with a more generic approach that can be used for objects
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.multiselect} to ask the question
+   */
+  async requestMultipleSelect<T>(
+    question: string,
+    options: T[],
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string,
+  ): Promise<T[]> {
+    const selectQuestionAddition = this.predefinedRequests.multiselect.replace(
+      '{{DyNTS_selectOptions}}', 
+      this.getTextListAsText(options.map(item => `"${JSON.stringify(item)}"`))
+    );
+    question += selectQuestionAddition;
+    
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return DyFM_safeParseList<T[]>(answer);
+  }
+  /** the exact same as {@link requestMultipleSelect} */
+  multipleSelectRequest = this.requestMultipleSelect;
+
+  /**
+   * Asks the AI to answer a question that must result a JSON object
+   * 
+   * If the answer is not a valid JSON object, it will return { unparsableResult: answer }
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.jsonRequest} to ask the question
+   * 
+   * (uses {@link DyFM_safeParseJSON})
+   */
+  async askJSONQuestion<T = any>(
+    question: string, 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<T | { unparsableResult: string }> {
+    question += this.predefinedRequests.jsonRequest;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+    
+    return DyFM_safeParseJSON<T>(answer);
+  }
+  /** the exact same as {@link askJSONQuestion} */
+  jsonQuestion = this.askJSONQuestion;
+
+  /**
+   * Asks the AI to answer a question that must result a JSON object with specific key descriptions
+   * 
+   * If the answer is not a valid JSON object, it will return { unparsableResult: answer }
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.jsonRequestWithKeysDescription} to ask the question
+   * 
+   * (uses {@link DyFM_safeParseJSON})
+   */
+  async askJSONQuestionWithKeysDescription<T = any>(
+    question: string, 
+    keysDescription: string,
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<T | { unparsableResult: string }> {
+    const jsonRequestWithKeysDescription = this.predefinedRequests.jsonRequestWithKeysDescription.replace(
+      '{{DyNTS_jsonKeysDescription}}', 
+      keysDescription
+    );
+    question += jsonRequestWithKeysDescription;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return DyFM_safeParseJSON<T>(answer);
+  }
+  /** the exact same as {@link askJSONQuestionWithKeysDescription} */
+  jsonQuestionWithKeysDescription = this.askJSONQuestionWithKeysDescription;
+
+  /**
+   * Asks the AI to answer a question that must result a JSON object with specific keys
+   * 
+   * If the answer is not a valid JSON object, it will return { unparsableResult: answer }
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.jsonRequestWithExactKeys} to ask the question
+   * 
+   * (uses {@link DyFM_safeParseJSON})
+   */
+  async askJSONQuestionWithExactKeys<T = any>(
+    question: string, 
+    keys: string[],
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string
+  ): Promise<T | { unparsableResult: string }> {
+    const jsonRequestWithExactKeys = this.predefinedRequests.jsonRequestWithExactKeys.replace(
+      '{{DyNTS_jsonKeys}}', 
+      this.getTextListAsText(keys)
+    );
+    question += jsonRequestWithExactKeys;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return DyFM_safeParseJSON<T>(answer);
+  }
+  /** the exact same as {@link askJSONQuestionWithExactKeys} */
+  jsonQuestionWithExactKeys = this.askJSONQuestionWithExactKeys;
+
+  /**
+   * Asks the AI to answer a question that must result a list of strings
+   * 
+   * If the answer is not a valid JSON list, it will return the answer as a single item in an array
+   * 
+   * Uses the {@link DyNTS_OAI_LLM_Predefined_Requests.listRequest} to ask the question
+   * 
+   * (uses {@link DyFM_safeParseList})
+   */
+  async askListQuestion(
+    question: string, 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string,
+  ): Promise<string[]> {
+    question += this.predefinedRequests.listRequest;
+
+    const answer = await this.askQuestion(question, issuer, settings, debugLog, replaceThisInLog);
+
+    return DyFM_safeParseList(answer);
+  }
+  /** the exact same as {@link askListQuestion} */
+  listQuestion = this.askListQuestion;
+  /** the exact same as {@link askListQuestion} */
+  listRequest = this.askListQuestion;
+  
+  /**
+   * Asks the AI to answer a question
+   * 
+   * Uses the {@link resolveSimpleUserMessage}
+   */
+  async askQuestion(
+    question: string, 
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    debugLog?: boolean,
+    /** this is used to readably replace too long contents to eg '...' in logs */
+    replaceThisInLog?: string,
+  ): Promise<string> {
+    this.logQuestion(question, replaceThisInLog, debugLog);
+
+    const answer = await this.resolveSimpleUserMessage(question, issuer, settings);
+
+    if (this.debugLog) {
+      console.log(' - ', answer);
+    }
+
+    return answer;
+  }
+  /** the exact same as {@link askQuestion} */
+  answer = this.askQuestion;
+  /** the exact same as {@link askQuestion} */
+  getQuestionAnswer = this.askQuestion;
+  /** the exact same as {@link askQuestion} */
+  simpleQuestion = this.askQuestion;
+  /** the exact same as {@link askQuestion} */
+  askSimpleQuestion = this.askQuestion;
+
+  /**
+   * Resolves a simple user message and returns the answer as string
+   * 
+   * Uses the {@link resolveMessage}
+   */
+  async resolveSimpleUserMessage(
+    message: string,
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings
+  ): Promise<string> {
+    return this.resolveMessage(
+      [{ role: DyNTS_OAI_GPT_Message_Role.user, content: message }], 
+      issuer,
+      settings, 
+      false
+    ) as Promise<string>;
+  }
+  /** the exact same as {@link resolveSimpleUserMessage} */
+  simpleUserMessage = this.resolveSimpleUserMessage;
+
+  //#endregion
+
+  /**
+   * Resolves a conversation
+   * 
+   * Uses the {@link getMessageCreateInput}
+   */
+  async resolveMessage(
+    conversation: DyNTS_OAI_GPT_Message[],
+    issuer: string,
+    settings?: DyFM_GPTCall_Settings,
+    getFullResponse?: boolean
+  ): Promise<string | ChatCompletion> {
+    try {
+      conversation.unshift(this.getDefaultSystemMessage(settings));
+
+      const result: ChatCompletion = await this.openai.chat.completions.create(
+        this.getMessageCreateInput(conversation, issuer, settings)
+      ) as ChatCompletion;
+
+      if (getFullResponse) {
+        return result;
+      }
+
+      return result.choices[0].message.content;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('resolveConversation', error, issuer),
+        
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-OAB-RC0`,
+      });
+    }
+  }
+
+  //#region Tools
+
+  /**
+   * Logs the question if the debugLog is true
+   */
+  protected logQuestion(question: string, replaceThisInLog?: string, debugLog?: boolean): void {
+    if (debugLog ?? this.debugLog) {
+      if (replaceThisInLog) {
+        question = question.replace(replaceThisInLog, this.defaultLogReplacer);
+      }
+
+      console.log('\n - ', question);
+    }
+  }
+
+  /**
+   * olvasható mondatszerű-listaszerű formába teszi a listaelemeket
+   * pl.: ['a', 'b', 'c'] -> '"a", "b" or "c"'
+   */
+  getTextListAsText(list: string[]): string {
+    list = list.filter(item => item?.trim()).map(item => `"${item}"`);
+
+    /* list = list.map(item => item.toLocaleLowerCase()); */
+
+    list.push(list.pop() + ' or ' + list.pop());
+
+    return list.join(', ');
+  }
+
+  /**
+   * Creates a message create input
+   * 
+   * Uses the {@link getDefaultSystemMessage}
+   */
+  protected getMessageCreateInput(
+    messages: DyNTS_OAI_GPT_Message[],
+    issuer: string,
+    settings: DyFM_GPTCall_Settings = this.defaultSettings
+  ): ChatCompletionCreateParamsBase {
+    try {
+      const result: ChatCompletionCreateParamsBase = {
+        model: settings.useModel ?? this.defaultModel,
+        messages: messages as ChatCompletionMessageParam[],
+      };
+
+      if (DyFM_notNull(settings.temperature)) {
+        result.temperature = settings.temperature;
+      }
+      
+      if (DyFM_notNull(settings.maxTokens)) {
+        result.max_tokens = settings.maxTokens;
+      }
+
+      if (DyFM_notNull(settings.topP)) {
+        result.top_p = settings.topP;
+      }
+
+      if (DyFM_notNull(settings.frequencyPenalty)) {
+        result.frequency_penalty = settings.frequencyPenalty;
+      }
+
+      if (DyFM_notNull(settings.presencePenalty)) {
+        result.presence_penalty = settings.presencePenalty;
+      }
+
+      return result;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('getMessageCreateSettings', error, issuer),
+        
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-OAB-RC0`,
+      });
+    }
+  }
+
+  protected getDefaultSystemMessage(settings: DyFM_GPTCall_Settings): DyNTS_OAI_GPT_Message {
+    return {
+      role: DyNTS_OAI_GPT_Message_Role.system,
+      content: settings.systemPrompt || this.defaultSystemPrompt,
+    };
+  }
+  
+  protected getDefaultErrorSettings(
+    fnName: string, 
+    error: DyFM_AnyError,
+    issuer: string
+  ): DyFM_Error_Settings {
+    return {
+      status: (error as DyFM_Error)?.___status ?? 500,
+      message: (error as Error)?.message ??
+        (error as DyFM_Error)?._message ??
+        `${fnName} was UNSUCCESSFUL (${DyNTS_global_settings.systemShortCodeName})`,
+      addECToUserMsg: !(error as DyFM_Error)?.__userMessage,
+      userMessage: (error as DyFM_Error)?.__userMessage ?? this.defaultErrorUserMsg,
+      issuer: issuer,
+      issuerService: this.constructor?.name,
+      error: error,
+    };
+  }
+
+  //#endregion
+}
+
+/**
+ * parses the JSON list, if it fails, it returns the answer as a single item in an array
+ * 
+ * (uses {@link DyFM_safeParseJSON})
+ */
+export function DyFM_safeParseList<T extends Array<any>>(
+  textedJSON: string, 
+  disableErrorLog?: boolean
+): T {
+  const parsed = DyFM_safeParseJSON<T>(textedJSON, true);
+
+  if (Array.isArray(parsed)) {
+    return parsed;
+  } else if (typeof parsed === 'object') {
+    if (!disableErrorLog) {
+      DyFM_Log.warn(
+        'DyFM_safeParseList result is an object, returning its values', 
+        {
+          parsed: parsed,
+        }
+      );
+    }
+
+    return Object.values(parsed) as T;
+  } else {
+
+    if (!disableErrorLog) {
+      DyFM_Log.warn(
+        'DyFM_safeParseList result is not an array or object, returning it as a single item', 
+        {
+          parsed: parsed,
+        }
+      );
+    }
+
+    return [ parsed ] as string[] as T;
+  }
+}
+
+/**
+ * parses the JSON, if it fails, it returns { unparsableResult: textedJSON }
+ * 
+ * (uses {@link DyFM_failableSafeParseJSON})
+ */
+export function DyFM_safeParseJSON<T = any>(
+  textedJSON: string,
+  disableErrorLog?: boolean
+): T | { unparsableResult: string } {
+  try {
+    return DyFM_failableSafeParseJSON(textedJSON);
+  } catch (error) {
+    if (!disableErrorLog) {
+      DyFM_Log.error(
+        'Unable to parse JSON answer:', 
+        {
+          unparsedJSON: textedJSON,
+          error: error,
+        }
+      );
+    }
+
+    return { unparsableResult: textedJSON };
+  }
+}
+
+/**
+ * parses the JSON, if it fails, it throws an error
+ * (also will extract the JSON from "```json ... ```" wrapper)
+ */
+export function DyFM_failableSafeParseJSON<T = any>(textedJSON: string): T {
+  if (!textedJSON) {
+    throw new Error(`No content provided to JSON parse ("${textedJSON}")`);
+  }
+
+  const match = textedJSON.match(/```json(.*)```/s);
+  textedJSON = textedJSON.replaceAll('\n', '');
+
+  if (match) {
+    return JSON.parse(match[1].replaceAll('\n', ''));
+  } else {
+    return JSON.parse(
+      textedJSON.replaceAll('```json', '').replaceAll('```', '')
+    );
+  }
+}