@futdevpro/nts-dynamo 1.15.39 → 1.15.40

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

@@ -1,510 +1,519 @@
-import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
-import {
-  DyFM_AI_CallSettings,
-  DyFM_AI_Message,
-  DyFM_AI_LLM_Response,
-  DyFM_AI_MessageRole,
-  DyFM_AI_Tool,
-  DyFM_AI_ToolCall,
-  DyFM_AI_ToolResult,
-  DyFM_AI_ToolHandlers,
-  DyFM_AI_ModelInfo,
-  DyFM_AI_ModelRegistry_Util,
-} from '@futdevpro/fsm-dynamo/ai';
-import { DyFM_Error, DyFM_Error_Settings, DyFM_getLocalStackLocation, DyFM_Log, DyFM_Object } from '@futdevpro/fsm-dynamo';
-import {
-  DyFM_AI_GenericSelect_Input,
-  DyFM_AI_GenericMultiSelect_Input,
-  DyFM_AI_JSONKeysDescription_Input,
-  DyFM_AI_JSONExactKeys_Input,
-  DyFM_AI_Message_Input,
-} from '../_models/ai-input-interfaces';
-import { Items } from 'openai/resources/conversations/items';
-
-/**
- * Abstract base class for LLM services
- * Defines all methods that must be implemented by AI providers
- */
-export abstract class DyNTS_AI_LLM_ServiceBase<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyNTS_AI_Provider_ServiceBase {
-  /** Default settings for LLM calls */
-  abstract readonly defaultSettings: T_AISettings;
-  
-  /** Default model to use for LLM calls */
-  /* abstract readonly defaultModel: string; */
-  
-  /** Provider-specific predefined requests */
-  abstract readonly predefinedRequests: any;
-
-  _debugLog: boolean = false;
-  get debugLog(): boolean {
-    return this.defaultSettings?.debugLog ?? this._debugLog;
-  }
-
-  get defaultSystemPrompt(): string {
-    return this.defaultSettings.systemPrompt;
-  }
-
-  get defaultModel(): string {
-    return this.defaultSettings.useModel;
-  }
-
-  defaultLogReplacer: string = '...long-context...';
-
-  //////////////////////////////////////////////////////////////////////////////////////////
-                          // FUNCTION CALLING (TOOL USE) — FR-047 //
-  //////////////////////////////////////////////////////////////////////////////////////////
-  // Provider-agnostic agent-loop. The loop logic lives here ONCE (ported from the legacy
-  // FDPNTS_GPT_ControlService.getAnswerWithTools); each provider only overrides
-  // `callModelWithTools` (one provider turn) and `getModelRegistry` (capability honesty).
-  // Tools are a REQUEST parameter (not on settings), per the FR-047 design.
-
-  /**
-   * A provider tool-kepes modell-registry-je (override providerenkent — pl. DyFM_OAI_Models).
-   * Ures default → a modell tool-kepessege ismeretlen → a precheck elutasitja (honesty).
-   */
-  protected getModelRegistry(): DyFM_AI_ModelInfo[] {
-    return [];
-  }
-
-  /**
-   * Ellenorzi, hogy a feloldott modell tamogatja-e a function calling-ot; ha nem, beszedes
-   * hibaval elhasal MIELOTT barmilyen API-hivas tortenne (kritikus pl. a Local providernel).
-   */
-  protected assertToolsSupported(modelId: string): void {
-    if (!DyFM_AI_ModelRegistry_Util.modelSupportsTools(this.getModelRegistry(), modelId)) {
-      throw new DyFM_Error({
-        message: `Model '${modelId}' does not support function calling (provider: ${this.aiProvider})`,
-        userMessage: `The selected AI model does not support tools.`,
-        errorCode: 'DyNTS-AILSB-TLC0',
-      });
-    }
-  }
-
-  /**
-   * GPT valasz Function Calling Agent Tool-okkal — provider-agnosztikus agent-loop.
-   * @description A `tools` definiciok + `toolHandlers` alapjan tool-loop-ot futtat: hivja a
-   *   modellt (callModelWithTools) → ha a valaszban tool-call van, lefuttatja a regisztralt
-   *   handler-t (runToolCall, never-throw) es az eredmenyt visszafuzi → ismetli, amig a model
-   *   vegso (tool-call nelkuli) valaszt ad, vagy a maxIterations limitet eleri. A tool-ok a
-   *   REQUEST-parameterben jonnek, nem a settings-ben.
-   */
-  async requestWithTools(
-    set: {
-      conversation: DyFM_AI_Message[];
-      tools: DyFM_AI_Tool[];
-      toolHandlers: DyFM_AI_ToolHandlers;
-      settings?: T_AISettings;
-      issuer: string;
-      maxIterations?: number;
-    }
-  ): Promise<DyFM_AI_LLM_Response> {
-    const modelId: string = (set.settings?.useModel ?? this.defaultModel) as string;
-    this.assertToolsSupported(modelId);
-
-    return this.runToolLoop(set);
-  }
-
-  /**
-   * Egy provider-kor a tool-loop-ban: elkuldi a beszelgetest + tool-okat, normalizalt valaszt ad.
-   * @description Override-olando providerenkent (OpenAI / Anthropic / Google / …). A default
-   *   elhasal — egy provider, ami nem implementalja, tool-use-t nem tud kiszolgalni.
-   */
-  protected async callModelWithTools(
-    _set: {
-      conversation: DyFM_AI_Message[];
-      tools: DyFM_AI_Tool[];
-      settings?: T_AISettings;
-      issuer: string;
-    }
-  ): Promise<DyFM_AI_LLM_Response> {
-    throw new DyFM_Error({
-      message: `callModelWithTools is not implemented for provider '${this.aiProvider}'`,
-      userMessage: `Function calling is not available for this AI provider yet.`,
-      errorCode: 'DyNTS-AILSB-TLN0',
-    });
-  }
-
-  /**
-   * A provider-agnosztikus agent-loop torzse. A bemeno `conversation` ele a provider teszi a
-   * system-message-et (callModelWithTools); a loop a tool-call/tool-result uzeneteket fuzi hozza.
-   */
-  protected async runToolLoop(
-    set: {
-      conversation: DyFM_AI_Message[];
-      tools: DyFM_AI_Tool[];
-      toolHandlers: DyFM_AI_ToolHandlers;
-      settings?: T_AISettings;
-      issuer: string;
-      maxIterations?: number;
-    }
-  ): Promise<DyFM_AI_LLM_Response> {
-    const maxIterations: number = set.maxIterations ?? 8;
-    const conversation: DyFM_AI_Message[] = [...set.conversation];
-
-    for (let iteration: number = 0; iteration < maxIterations; iteration++) {
-      const response: DyFM_AI_LLM_Response = await this.callModelWithTools({
-        conversation: conversation,
-        tools: set.tools,
-        settings: set.settings,
-        issuer: set.issuer,
-      });
-
-      // nincs tool-hivas → ez a vegso valasz
-      if (!response.toolCalls?.length) {
-        return response;
-      }
-
-      // a model tool-hivo (assistant) uzenetet visszatesszuk a kontextusba
-      conversation.push({
-        role: DyFM_AI_MessageRole.assistant,
-        content: response.content ?? '',
-        toolCalls: response.toolCalls,
-      });
-
-      // minden tool-hivast lefuttatunk (never-throw), es az eredmenyt visszaadjuk a modellnek
-      const results: DyFM_AI_ToolResult[] = await Promise.all(
-        response.toolCalls.map((call: DyFM_AI_ToolCall) => this.runToolCall(call, set.toolHandlers))
-      );
-
-      results.forEach((result: DyFM_AI_ToolResult) => {
-        conversation.push({
-          role: DyFM_AI_MessageRole.tool,
-          content: result.content,
-          toolCallId: result.toolCallId,
-        });
-      });
-    }
-
-    // a tool-loop nem konvergalt a limiten belul
-    throw new DyFM_Error({
-      message: `Tool loop did not converge within ${maxIterations} iterations`,
-      userMessage: `We encountered an error while running AI tools, please contact the responsible development team.`,
-      errorCode: 'DyNTS-AILSB-TL0',
-    });
-  }
-
-  /**
-   * Egy tool-hivas lefuttatasa a regisztralt handler-rel. SOHA nem dob — a tool-hiba string-kent
-   * megy vissza a modellnek (hogy korrigalhasson), hianyzo handler eseten is informativ uzenet
-   * (soha nem [object Object]).
-   */
-  protected async runToolCall(
-    call: DyFM_AI_ToolCall,
-    toolHandlers: DyFM_AI_ToolHandlers
-  ): Promise<DyFM_AI_ToolResult> {
-    const handler = toolHandlers[call.name];
-
-    if (!handler) {
-      return {
-        toolCallId: call.id,
-        content: `ERROR: no handler registered for tool '${call.name}'`,
-        isError: true,
-      };
-    }
-
-    try {
-      return {
-        toolCallId: call.id,
-        content: await handler(call.arguments),
-      };
-    } catch (error) {
-      return {
-        toolCallId: call.id,
-        content: `ERROR executing tool '${call.name}': ` +
-          `${error instanceof Error ? error.message : String(error)}`,
-        isError: true,
-      };
-    }
-  }
-
-  // Core abstract methods
-  /**
-   * Call LLM with system and user messages
-   */
-  /* abstract callLLM(
-    systemMessage: string,
-    userMessage: string,
-    settings?: DyFM_AI_CallSettings,
-    issuer?: string
-  ): Promise<string>; */
-  
-  /**
-   * Call LLM with message history
-   */
-  /* abstract callLLMWithHistory(
-    messages: DyFM_AI_Message[],
-    settings?: DyFM_AI_CallSettings,
-    issuer?: string
-  ): Promise<string>; */
-  
-  /**
-   * Call LLM and return raw response
-   */
-  /* abstract callLLMRaw(
-    messages: DyFM_AI_Message[],
-    settings?: DyFM_AI_CallSettings,
-    issuer?: string
-  ): Promise<DyFM_AI_LLM_Response>; */
-  
-  // Question methods (from OAI_LLM_ServiceBase)
-  abstract requestSimpleMessage(set: DyFM_AI_Message_Input<T_AISettings>): Promise<string>;
-  abstract requestYesNo(set: DyFM_AI_Message_Input<T_AISettings>): Promise<boolean>;
-  abstract requestPercentage(set: DyFM_AI_Message_Input<T_AISettings>): Promise<number>;
-
-  /* abstract askSelectQuestion(set: DyFM_AI_ListSelect_Input): Promise<string>; */
-  abstract requestSelect<T>(
-    set: DyFM_AI_GenericSelect_Input<T, T_AISettings>
-  ): Promise<T | { unparsableResult: string }>;
-  /* abstract askMultipleSelectQuestionWithOptions(set: DyFM_AI_MultiSelect_Input): Promise<string[]>; */
-  abstract requestMultiselect<T>(
-    set: DyFM_AI_GenericMultiSelect_Input<T, T_AISettings>
-  ): Promise<T[] | { unparsableResult: string }>;
-
-  abstract requestJSON<T>(set: DyFM_AI_Message_Input<T_AISettings>): Promise<T | { unparsableResult: string }>;
-  abstract requestJSONQuestionWithKeysDescription<T>(
-    set: DyFM_AI_JSONKeysDescription_Input<T_AISettings>
-  ): Promise<T | { unparsableResult: string }>;
-  /* abstract askJSONQuestionWithExactKeys(set: DyFM_AI_JSONExactKeys_Input): Promise<object>; */
-  abstract requestJSONWithExactKeys<T>(
-    set: DyFM_AI_JSONExactKeys_Input<T_AISettings>
-  ): Promise<T | { unparsableResult: string }>;
-  /* abstract sendMessage(set: DyFM_AI_SimpleMessage_Input): Promise<string>; */
-
-  /* abstract requestStringList(set: DyFM_AI_Base_Input<T_AISettings>): Promise<string[] | { unparsableResult: string }>; */
-  abstract requestList<T>(set: DyFM_AI_Message_Input<T_AISettings>): Promise<T[] | { unparsableResult: string }>;
-  
-  // Helper methods
-  /* protected abstract getDefaultErrorSettings(
-    method: string,
-    error: any,
-    issuer?: string
-  ): DyFM_Error_Settings; */
-  
-  /* protected abstract getTextListAsText(list: string[]): string; */
-  
-  /* protected abstract logQuestion(set: DyFM_AI_Base_Input<T_AISettings>): void; */
-
-  protected convertAnswerToBoolean(answer: string): boolean {
-    return answer.toUpperCase().includes(this.predefinedRequests.yesNo.upperCaseYes);
-  }
-
-  protected convertAnswerToNumber(answer: string, message: string): number {
-    if (this.isAnswerValid(answer, message)) {
-      return null;
-    }
-
-    if (isNaN(+answer)) {
-      DyFM_Log.T_error(
-        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToNumber got an invalid answer', 
-        {
-          question: message,
-          answer: answer,
-        }
-      );
-
-      return null;
-    }
-
-    return +answer;
-  }
-
-  protected convertAnswerToSelectOption<T>(answer: string, message: string, options: T[]): T {
-    if (this.isAnswerValid(answer, message)) {
-      return null;
-    }
-
-    answer = answer.toLocaleUpperCase();
-
-    const stringifiedOptions: string[] = this.stringifySelectOptions(options);
-    for (const stringifiedItem of stringifiedOptions) {
-      if (answer.includes(stringifiedItem.toLocaleUpperCase())) {
-        const parsedItem: T | { unparsableResult: string } = DyFM_Object.safeParseJSON<T>(stringifiedItem);
-
-        if ((parsedItem as { unparsableResult: string }).unparsableResult) {
-          DyFM_Log.T_error(
-            'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToSelectOption got an invalid answer', 
-            {
-              question: message,
-              answer: answer,
-            }
-          );
-
-          return stringifiedItem as T;
-        } else {
-          return parsedItem as T;
-        }
-      }
-    }
-
-    return null;
-  }
-
-  protected convertAnswerToSelectOptions<T>(answer: string, message: string, options: T[]): T[] {
-    if (this.isAnswerValid(answer, message)) {
-      return null;
-    }
-
-    const enrichedOptions: { stringifiedOption: string, parsedOption: T }[] = options.map(
-      (option: T) => ({
-        stringifiedOption: this.stringifySelectOption(option),
-        parsedOption: option
-      })
-    );
-    const result: T[] = [];
-
-    for (const item of enrichedOptions) {
-      if (answer.includes(item.stringifiedOption)) {
-        result.push(item.parsedOption);
-      }
-    }
-
-    return result;
-  }
-
-  protected convertAnswerToJSON<T>(answer: string, message: string): T | { unparsableResult: string } {
-    if (this.isAnswerValid(answer, message)) {
-      return { unparsableResult: answer };
-    }
-
-    const parsedItem: T | { unparsableResult: string } = DyFM_Object.safeParseJSON<T>(answer);
-    if ((parsedItem as { unparsableResult: string }).unparsableResult) {
-      DyFM_Log.T_error(
-        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToJSON got an invalid answer', 
-        {
-          question: message,
-          answer: answer,
-        }
-      );
-
-      return { unparsableResult: answer };
-    }
-
-    return parsedItem as T;
-  }
-
-  protected convertAnswerToList<T>(answer: string, message: string): T[] | { unparsableResult: string } {
-    if (this.isAnswerValid(answer, message)) {
-      return { unparsableResult: answer };
-    }
-
-    // Check if safeParseJSON returns unparsableResult before calling safeParseList
-    // because safeParseList doesn't properly handle unparsableResult
-    const parsedCheck: T[] | { unparsableResult: string } = DyFM_Object.safeParseJSON<T[]>(answer, true);
-    if ((parsedCheck as { unparsableResult: string }).unparsableResult) {
-      DyFM_Log.T_error(
-        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToList got an invalid answer', 
-        {
-          question: message,
-          answer: answer,
-        }
-      );
-
-      return { unparsableResult: answer };
-    }
-
-    return DyFM_Object.safeParseList<T[]>(answer);
-  }
-
-  protected stringifySelectOptions<T>(options: T[]): string[] {
-    return options.map(item => this.stringifySelectOption(item));
-  }
-
-  protected stringifySelectOption<T>(option: T): string {
-    return JSON.stringify(option);
-  }
-
-  protected isAnswerValid(answer: string, message: string): boolean {
-    if (!answer?.trim?.()?.length) {
-      DyFM_Log.T_error(
-        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToSelectOption got an invalid answer', 
-        {
-          question: message,
-          answer: answer,
-        }
-      );
-
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * olvasható mondatszerű-listaszerű formába teszi a listaelemeket
-   * pl.: ['a', 'b', 'c'] -> '"a", "b" or "c"'
-   */
-  protected 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(', ');
-  }
-  
-  protected logQuestion(
-    set: DyFM_AI_Message_Input<T_AISettings>
-  ): void {
-    if (set.settings?.debugLog ?? this._debugLog) {
-      console.log('\n - ', set.message);
-    }
-  }
-
-  protected getDefaultSystemMessage(settings: T_AISettings): DyFM_AI_Message {
-    return {
-      role: DyFM_AI_MessageRole.system,
-      content: settings?.systemPrompt || this.defaultSystemPrompt,
-    };
-  }
-
-  protected validateConversation(conversation: DyFM_AI_Message[]): void {
-    conversation.forEach((message: DyFM_AI_Message, index: number) => {
-      if (!message.role) {
-        throw new DyFM_Error({
-          message: `Message has no role at index ${index}`,
-          additionalContent: {
-            invalidMessage: message,
-            conversation: conversation,
-          }
-        });
-      }
-    });
-
-    conversation = conversation.filter(message => message.content);
-  }
-
-  protected logAnswer(answer: string): void {
-    if (this._debugLog) {
-      console.log(' - answer: ', answer);
-    }
-  }
-
-
-
-  //////////////////////////////////////////////////////////////////////////////////////////
-                                  // LLM CHAT METHODS //
-  //////////////////////////////////////////////////////////////////////////////////////////
- 
-
-  protected logConversation(
-    set: {
-      conversation: DyFM_AI_Message[], 
-      debugLog?: boolean,
-      /** this is used to readably replace too long contents to eg '...' in logs */
-      replaceThisInLog?: string,
-    }
-  ) {
-    if (set.debugLog || this._debugLog) {
-      DyFM_Log.info('Conversation log at', DyFM_getLocalStackLocation());
-
-      set.conversation.forEach(message => {
-        console.log(
-          ` - ${message.role}: ${message.content.replace(set.replaceThisInLog, this.defaultLogReplacer)}`
-        );
-      });
-    }
-  }
-}
+import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
+import {
+  DyFM_AI_CallSettings,
+  DyFM_AI_Message,
+  DyFM_AI_LLM_Response,
+  DyFM_AI_MessageRole,
+  DyFM_AI_Tool,
+  DyFM_AI_ToolCall,
+  DyFM_AI_ToolResult,
+  DyFM_AI_ToolHandlers,
+  DyFM_AI_ModelInfo,
+  DyFM_AI_ModelRegistry_Util,
+} from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_Error, DyFM_Error_Settings, DyFM_getLocalStackLocation, DyFM_Log, DyFM_Object } from '@futdevpro/fsm-dynamo';
+import {
+  DyFM_AI_GenericSelect_Input,
+  DyFM_AI_GenericMultiSelect_Input,
+  DyFM_AI_JSONKeysDescription_Input,
+  DyFM_AI_JSONExactKeys_Input,
+  DyFM_AI_Message_Input,
+} from '../_models/ai-input-interfaces';
+import { Items } from 'openai/resources/conversations/items';
+
+/**
+ * Abstract base class for LLM services
+ * Defines all methods that must be implemented by AI providers
+ */
+export abstract class DyNTS_AI_LLM_ServiceBase<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyNTS_AI_Provider_ServiceBase {
+  /** Default settings for LLM calls */
+  abstract readonly defaultSettings: T_AISettings;
+  
+  /** Default model to use for LLM calls */
+  /* abstract readonly defaultModel: string; */
+  
+  /** Provider-specific predefined requests */
+  abstract readonly predefinedRequests: any;
+
+  _debugLog: boolean = false;
+  get debugLog(): boolean {
+    return this.defaultSettings?.debugLog ?? this._debugLog;
+  }
+
+  get defaultSystemPrompt(): string {
+    return this.defaultSettings.systemPrompt;
+  }
+
+  get defaultModel(): string {
+    return this.defaultSettings.useModel;
+  }
+
+  defaultLogReplacer: string = '...long-context...';
+
+  //////////////////////////////////////////////////////////////////////////////////////////
+                          // FUNCTION CALLING (TOOL USE) — FR-047 //
+  //////////////////////////////////////////////////////////////////////////////////////////
+  // Provider-agnostic agent-loop. The loop logic lives here ONCE (ported from the legacy
+  // FDPNTS_GPT_ControlService.getAnswerWithTools); each provider only overrides
+  // `callModelWithTools` (one provider turn) and `getModelRegistry` (capability honesty).
+  // Tools are a REQUEST parameter (not on settings), per the FR-047 design.
+
+  /**
+   * A provider tool-kepes modell-registry-je (override providerenkent — pl. DyFM_OAI_Models).
+   * Ures default → a modell tool-kepessege ismeretlen → a precheck elutasitja (honesty).
+   */
+  protected getModelRegistry(): DyFM_AI_ModelInfo[] {
+    return [];
+  }
+
+  /**
+   * Ellenorzi, hogy a feloldott modell tamogatja-e a function calling-ot; ha nem, beszedes
+   * hibaval elhasal MIELOTT barmilyen API-hivas tortenne (kritikus pl. a Local providernel).
+   */
+  protected assertToolsSupported(modelId: string): void {
+    if (!DyFM_AI_ModelRegistry_Util.modelSupportsTools(this.getModelRegistry(), modelId)) {
+      throw new DyFM_Error({
+        message: `Model '${modelId}' does not support function calling (provider: ${this.aiProvider})`,
+        userMessage: `The selected AI model does not support tools.`,
+        errorCode: 'DyNTS-AILSB-TLC0',
+      });
+    }
+  }
+
+  /**
+   * GPT valasz Function Calling Agent Tool-okkal — provider-agnosztikus agent-loop.
+   * @description A `tools` definiciok + `toolHandlers` alapjan tool-loop-ot futtat: hivja a
+   *   modellt (callModelWithTools) → ha a valaszban tool-call van, lefuttatja a regisztralt
+   *   handler-t (runToolCall, never-throw) es az eredmenyt visszafuzi → ismetli, amig a model
+   *   vegso (tool-call nelkuli) valaszt ad, vagy a maxIterations limitet eleri. A tool-ok a
+   *   REQUEST-parameterben jonnek, nem a settings-ben.
+   */
+  async requestWithTools(
+    set: {
+      conversation: DyFM_AI_Message[];
+      tools: DyFM_AI_Tool[];
+      toolHandlers: DyFM_AI_ToolHandlers;
+      settings?: T_AISettings;
+      issuer: string;
+      maxIterations?: number;
+    }
+  ): Promise<DyFM_AI_LLM_Response> {
+    const modelId: string = (set.settings?.useModel ?? this.defaultModel) as string;
+
+    if (!modelId) {
+      throw new DyFM_Error({
+        message: `No model configured for function calling (provider: ${this.aiProvider})`,
+        userMessage: `No AI model is configured for tools.`,
+        errorCode: 'DyNTS-AILSB-TLM0',
+      });
+    }
+
+    this.assertToolsSupported(modelId);
+
+    return this.runToolLoop(set);
+  }
+
+  /**
+   * Egy provider-kor a tool-loop-ban: elkuldi a beszelgetest + tool-okat, normalizalt valaszt ad.
+   * @description Override-olando providerenkent (OpenAI / Anthropic / Google / …). A default
+   *   elhasal — egy provider, ami nem implementalja, tool-use-t nem tud kiszolgalni.
+   */
+  protected async callModelWithTools(
+    _set: {
+      conversation: DyFM_AI_Message[];
+      tools: DyFM_AI_Tool[];
+      settings?: T_AISettings;
+      issuer: string;
+    }
+  ): Promise<DyFM_AI_LLM_Response> {
+    throw new DyFM_Error({
+      message: `callModelWithTools is not implemented for provider '${this.aiProvider}'`,
+      userMessage: `Function calling is not available for this AI provider yet.`,
+      errorCode: 'DyNTS-AILSB-TLN0',
+    });
+  }
+
+  /**
+   * A provider-agnosztikus agent-loop torzse. A bemeno `conversation` ele a provider teszi a
+   * system-message-et (callModelWithTools); a loop a tool-call/tool-result uzeneteket fuzi hozza.
+   */
+  protected async runToolLoop(
+    set: {
+      conversation: DyFM_AI_Message[];
+      tools: DyFM_AI_Tool[];
+      toolHandlers: DyFM_AI_ToolHandlers;
+      settings?: T_AISettings;
+      issuer: string;
+      maxIterations?: number;
+    }
+  ): Promise<DyFM_AI_LLM_Response> {
+    const maxIterations: number = set.maxIterations ?? 8;
+    const conversation: DyFM_AI_Message[] = [...set.conversation];
+
+    for (let iteration: number = 0; iteration < maxIterations; iteration++) {
+      const response: DyFM_AI_LLM_Response = await this.callModelWithTools({
+        conversation: conversation,
+        tools: set.tools,
+        settings: set.settings,
+        issuer: set.issuer,
+      });
+
+      // nincs tool-hivas → ez a vegso valasz
+      if (!response.toolCalls?.length) {
+        return response;
+      }
+
+      // a model tool-hivo (assistant) uzenetet visszatesszuk a kontextusba
+      conversation.push({
+        role: DyFM_AI_MessageRole.assistant,
+        content: response.content ?? '',
+        toolCalls: response.toolCalls,
+      });
+
+      // minden tool-hivast lefuttatunk (never-throw), es az eredmenyt visszaadjuk a modellnek
+      const results: DyFM_AI_ToolResult[] = await Promise.all(
+        response.toolCalls.map((call: DyFM_AI_ToolCall) => this.runToolCall(call, set.toolHandlers))
+      );
+
+      results.forEach((result: DyFM_AI_ToolResult) => {
+        conversation.push({
+          role: DyFM_AI_MessageRole.tool,
+          content: result.content,
+          toolCallId: result.toolCallId,
+        });
+      });
+    }
+
+    // a tool-loop nem konvergalt a limiten belul
+    throw new DyFM_Error({
+      message: `Tool loop did not converge within ${maxIterations} iterations`,
+      userMessage: `We encountered an error while running AI tools, please contact the responsible development team.`,
+      errorCode: 'DyNTS-AILSB-TL0',
+    });
+  }
+
+  /**
+   * Egy tool-hivas lefuttatasa a regisztralt handler-rel. SOHA nem dob — a tool-hiba string-kent
+   * megy vissza a modellnek (hogy korrigalhasson), hianyzo handler eseten is informativ uzenet
+   * (soha nem [object Object]).
+   */
+  protected async runToolCall(
+    call: DyFM_AI_ToolCall,
+    toolHandlers: DyFM_AI_ToolHandlers
+  ): Promise<DyFM_AI_ToolResult> {
+    const handler = toolHandlers[call.name];
+
+    if (!handler) {
+      return {
+        toolCallId: call.id,
+        content: `ERROR: no handler registered for tool '${call.name}'`,
+        isError: true,
+      };
+    }
+
+    try {
+      return {
+        toolCallId: call.id,
+        content: await handler(call.arguments),
+      };
+    } catch (error) {
+      return {
+        toolCallId: call.id,
+        content: `ERROR executing tool '${call.name}': ` +
+          `${error instanceof Error ? error.message : String(error)}`,
+        isError: true,
+      };
+    }
+  }
+
+  // Core abstract methods
+  /**
+   * Call LLM with system and user messages
+   */
+  /* abstract callLLM(
+    systemMessage: string,
+    userMessage: string,
+    settings?: DyFM_AI_CallSettings,
+    issuer?: string
+  ): Promise<string>; */
+  
+  /**
+   * Call LLM with message history
+   */
+  /* abstract callLLMWithHistory(
+    messages: DyFM_AI_Message[],
+    settings?: DyFM_AI_CallSettings,
+    issuer?: string
+  ): Promise<string>; */
+  
+  /**
+   * Call LLM and return raw response
+   */
+  /* abstract callLLMRaw(
+    messages: DyFM_AI_Message[],
+    settings?: DyFM_AI_CallSettings,
+    issuer?: string
+  ): Promise<DyFM_AI_LLM_Response>; */
+  
+  // Question methods (from OAI_LLM_ServiceBase)
+  abstract requestSimpleMessage(set: DyFM_AI_Message_Input<T_AISettings>): Promise<string>;
+  abstract requestYesNo(set: DyFM_AI_Message_Input<T_AISettings>): Promise<boolean>;
+  abstract requestPercentage(set: DyFM_AI_Message_Input<T_AISettings>): Promise<number>;
+
+  /* abstract askSelectQuestion(set: DyFM_AI_ListSelect_Input): Promise<string>; */
+  abstract requestSelect<T>(
+    set: DyFM_AI_GenericSelect_Input<T, T_AISettings>
+  ): Promise<T | { unparsableResult: string }>;
+  /* abstract askMultipleSelectQuestionWithOptions(set: DyFM_AI_MultiSelect_Input): Promise<string[]>; */
+  abstract requestMultiselect<T>(
+    set: DyFM_AI_GenericMultiSelect_Input<T, T_AISettings>
+  ): Promise<T[] | { unparsableResult: string }>;
+
+  abstract requestJSON<T>(set: DyFM_AI_Message_Input<T_AISettings>): Promise<T | { unparsableResult: string }>;
+  abstract requestJSONQuestionWithKeysDescription<T>(
+    set: DyFM_AI_JSONKeysDescription_Input<T_AISettings>
+  ): Promise<T | { unparsableResult: string }>;
+  /* abstract askJSONQuestionWithExactKeys(set: DyFM_AI_JSONExactKeys_Input): Promise<object>; */
+  abstract requestJSONWithExactKeys<T>(
+    set: DyFM_AI_JSONExactKeys_Input<T_AISettings>
+  ): Promise<T | { unparsableResult: string }>;
+  /* abstract sendMessage(set: DyFM_AI_SimpleMessage_Input): Promise<string>; */
+
+  /* abstract requestStringList(set: DyFM_AI_Base_Input<T_AISettings>): Promise<string[] | { unparsableResult: string }>; */
+  abstract requestList<T>(set: DyFM_AI_Message_Input<T_AISettings>): Promise<T[] | { unparsableResult: string }>;
+  
+  // Helper methods
+  /* protected abstract getDefaultErrorSettings(
+    method: string,
+    error: any,
+    issuer?: string
+  ): DyFM_Error_Settings; */
+  
+  /* protected abstract getTextListAsText(list: string[]): string; */
+  
+  /* protected abstract logQuestion(set: DyFM_AI_Base_Input<T_AISettings>): void; */
+
+  protected convertAnswerToBoolean(answer: string): boolean {
+    return answer.toUpperCase().includes(this.predefinedRequests.yesNo.upperCaseYes);
+  }
+
+  protected convertAnswerToNumber(answer: string, message: string): number {
+    if (this.isAnswerValid(answer, message)) {
+      return null;
+    }
+
+    if (isNaN(+answer)) {
+      DyFM_Log.T_error(
+        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToNumber got an invalid answer', 
+        {
+          question: message,
+          answer: answer,
+        }
+      );
+
+      return null;
+    }
+
+    return +answer;
+  }
+
+  protected convertAnswerToSelectOption<T>(answer: string, message: string, options: T[]): T {
+    if (this.isAnswerValid(answer, message)) {
+      return null;
+    }
+
+    answer = answer.toLocaleUpperCase();
+
+    const stringifiedOptions: string[] = this.stringifySelectOptions(options);
+    for (const stringifiedItem of stringifiedOptions) {
+      if (answer.includes(stringifiedItem.toLocaleUpperCase())) {
+        const parsedItem: T | { unparsableResult: string } = DyFM_Object.safeParseJSON<T>(stringifiedItem);
+
+        if ((parsedItem as { unparsableResult: string }).unparsableResult) {
+          DyFM_Log.T_error(
+            'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToSelectOption got an invalid answer', 
+            {
+              question: message,
+              answer: answer,
+            }
+          );
+
+          return stringifiedItem as T;
+        } else {
+          return parsedItem as T;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  protected convertAnswerToSelectOptions<T>(answer: string, message: string, options: T[]): T[] {
+    if (this.isAnswerValid(answer, message)) {
+      return null;
+    }
+
+    const enrichedOptions: { stringifiedOption: string, parsedOption: T }[] = options.map(
+      (option: T) => ({
+        stringifiedOption: this.stringifySelectOption(option),
+        parsedOption: option
+      })
+    );
+    const result: T[] = [];
+
+    for (const item of enrichedOptions) {
+      if (answer.includes(item.stringifiedOption)) {
+        result.push(item.parsedOption);
+      }
+    }
+
+    return result;
+  }
+
+  protected convertAnswerToJSON<T>(answer: string, message: string): T | { unparsableResult: string } {
+    if (this.isAnswerValid(answer, message)) {
+      return { unparsableResult: answer };
+    }
+
+    const parsedItem: T | { unparsableResult: string } = DyFM_Object.safeParseJSON<T>(answer);
+    if ((parsedItem as { unparsableResult: string }).unparsableResult) {
+      DyFM_Log.T_error(
+        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToJSON got an invalid answer', 
+        {
+          question: message,
+          answer: answer,
+        }
+      );
+
+      return { unparsableResult: answer };
+    }
+
+    return parsedItem as T;
+  }
+
+  protected convertAnswerToList<T>(answer: string, message: string): T[] | { unparsableResult: string } {
+    if (this.isAnswerValid(answer, message)) {
+      return { unparsableResult: answer };
+    }
+
+    // Check if safeParseJSON returns unparsableResult before calling safeParseList
+    // because safeParseList doesn't properly handle unparsableResult
+    const parsedCheck: T[] | { unparsableResult: string } = DyFM_Object.safeParseJSON<T[]>(answer, true);
+    if ((parsedCheck as { unparsableResult: string }).unparsableResult) {
+      DyFM_Log.T_error(
+        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToList got an invalid answer', 
+        {
+          question: message,
+          answer: answer,
+        }
+      );
+
+      return { unparsableResult: answer };
+    }
+
+    return DyFM_Object.safeParseList<T[]>(answer);
+  }
+
+  protected stringifySelectOptions<T>(options: T[]): string[] {
+    return options.map(item => this.stringifySelectOption(item));
+  }
+
+  protected stringifySelectOption<T>(option: T): string {
+    return JSON.stringify(option);
+  }
+
+  protected isAnswerValid(answer: string, message: string): boolean {
+    if (!answer?.trim?.()?.length) {
+      DyFM_Log.T_error(
+        'DyNTS_AI_LLMChat_ServiceBase.convertAnswerToSelectOption got an invalid answer', 
+        {
+          question: message,
+          answer: answer,
+        }
+      );
+
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * olvasható mondatszerű-listaszerű formába teszi a listaelemeket
+   * pl.: ['a', 'b', 'c'] -> '"a", "b" or "c"'
+   */
+  protected 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(', ');
+  }
+  
+  protected logQuestion(
+    set: DyFM_AI_Message_Input<T_AISettings>
+  ): void {
+    if (set.settings?.debugLog ?? this._debugLog) {
+      console.log('\n - ', set.message);
+    }
+  }
+
+  protected getDefaultSystemMessage(settings: T_AISettings): DyFM_AI_Message {
+    return {
+      role: DyFM_AI_MessageRole.system,
+      content: settings?.systemPrompt || this.defaultSystemPrompt,
+    };
+  }
+
+  protected validateConversation(conversation: DyFM_AI_Message[]): void {
+    conversation.forEach((message: DyFM_AI_Message, index: number) => {
+      if (!message.role) {
+        throw new DyFM_Error({
+          message: `Message has no role at index ${index}`,
+          additionalContent: {
+            invalidMessage: message,
+            conversation: conversation,
+          }
+        });
+      }
+    });
+
+    conversation = conversation.filter(message => message.content);
+  }
+
+  protected logAnswer(answer: string): void {
+    if (this._debugLog) {
+      console.log(' - answer: ', answer);
+    }
+  }
+
+
+
+  //////////////////////////////////////////////////////////////////////////////////////////
+                                  // LLM CHAT METHODS //
+  //////////////////////////////////////////////////////////////////////////////////////////
+ 
+
+  protected logConversation(
+    set: {
+      conversation: DyFM_AI_Message[], 
+      debugLog?: boolean,
+      /** this is used to readably replace too long contents to eg '...' in logs */
+      replaceThisInLog?: string,
+    }
+  ) {
+    if (set.debugLog || this._debugLog) {
+      DyFM_Log.info('Conversation log at', DyFM_getLocalStackLocation());
+
+      set.conversation.forEach(message => {
+        console.log(
+          ` - ${message.role}: ${message.content.replace(set.replaceThisInLog, this.defaultLogReplacer)}`
+        );
+      });
+    }
+  }
+}