@futdevpro/nts-dynamo 1.15.36 → 1.15.37

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

@@ -1,20 +1,23 @@
 import { OpenAI } from 'openai';
 
-import { DyFM_OAI_Settings, DyFM_OAI_Model, DyFM_OAI_CallSettings } from '@futdevpro/fsm-dynamo/ai/open-ai';
+import { DyFM_OAI_Settings, DyFM_OAI_Model, DyFM_OAI_CallSettings, DyFM_OAI_Models } from '@futdevpro/fsm-dynamo/ai/open-ai';
 import { DyFM_AnyError, DyFM_Error, DyFM_Error_Settings, DyFM_Log, DyFM_notNull, DyFM_Object } from '@futdevpro/fsm-dynamo';
-import { 
-  DyFM_AI_Message, 
+import {
+  DyFM_AI_Message,
   DyFM_AI_MessageRole,
   DyFM_AI_Provider,
   DyFM_AI_ProviderCapabilities,
   DyFM_AI_CallSettings,
   DyFM_AI_Config,
-  DyFM_AI_LLM_Response
+  DyFM_AI_LLM_Response,
+  DyFM_AI_Tool,
+  DyFM_AI_ToolCall,
+  DyFM_AI_ModelInfo
 } from '@futdevpro/fsm-dynamo/ai';
 
 import { DyNTS_global_settings } from '../../../../../_collections/global-settings.const';
 import { ChatCompletion } from 'openai/resources';
-import { ChatCompletionCreateParamsBase, ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsBase, ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions';
 import { DyNTS_AI_CostEventCallback } from '../../../_models/interfaces/dynts-ai-cost-event-callback.interface';
 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';
@@ -567,6 +570,152 @@ export class DyNTS_OAI_LLM_ServiceBase extends DyNTS_AI_LLM_ServiceBase {
     }
   }
 
+  //#region Function calling (tool use) — FR-047
+
+  /** OpenAI tool-kepes modell-registry (a base capability-precheck-jehez). */
+  protected override getModelRegistry(): DyFM_AI_ModelInfo[] {
+    return DyFM_OAI_Models;
+  }
+
+  /**
+   * Egy OpenAI-kor a tool-loop-ban: felepiti a natív request-et (system + a teljes beszelgetes
+   * tool-uzenetekkel + tools), meghivja az API-t, es normalizalt DyFM_AI_LLM_Response-t ad vissza
+   * (toolCalls feltoltve, ha a model tool-t akar hivni). FR-002 cost-event: 'llm-tool-use'.
+   */
+  protected override async callModelWithTools(
+    set: {
+      conversation: DyFM_AI_Message[];
+      tools: DyFM_AI_Tool[];
+      settings?: DyFM_OAI_CallSettings;
+      issuer: string;
+    }
+  ): Promise<DyFM_AI_LLM_Response> {
+    try {
+      const settings: DyFM_OAI_CallSettings = set.settings ?? this.defaultSettings;
+
+      const messages: ChatCompletionMessageParam[] = [
+        this.toOpenAIMessage(this.getDefaultSystemMessage(settings)),
+        ...set.conversation.map((message: DyFM_AI_Message) => this.toOpenAIMessage(message)),
+      ];
+
+      const input: ChatCompletionCreateParamsBase = {
+        model: settings?.useModel ?? this.defaultModel,
+        messages: messages,
+        temperature: DyFM_notNull(settings?.temperature) ? settings.temperature : this.defaultSettings.temperature,
+        max_completion_tokens: DyFM_notNull(settings?.maxTokens) ? settings.maxTokens : this.defaultSettings.maxTokens,
+        top_p: DyFM_notNull(settings?.topP) ? settings.topP : this.defaultSettings.topP,
+        frequency_penalty: DyFM_notNull(settings?.frequencyPenalty) ? settings.frequencyPenalty : this.defaultSettings.frequencyPenalty,
+        presence_penalty: DyFM_notNull(settings?.presencePenalty) ? settings.presencePenalty : this.defaultSettings.presencePenalty,
+        tools: set.tools.map((tool: DyFM_AI_Tool) => this.toOpenAITool(tool)),
+        tool_choice: 'auto',
+      };
+
+      const start: number = Date.now();
+      const result: ChatCompletion = await this.openai.chat.completions.create(input) as ChatCompletion;
+      const durationMs: number = Date.now() - start;
+
+      const message = result.choices[0].message;
+
+      const toolCalls: DyFM_AI_ToolCall[] = (message.tool_calls ?? [])
+        .filter((toolCall) => toolCall.type === 'function')
+        .map((toolCall) => ({
+          id: toolCall.id,
+          name: toolCall.function.name,
+          arguments: this.parseToolArguments(toolCall.function.arguments),
+        }));
+
+      this.emitCostEvent({
+        callType: 'llm-tool-use',
+        provider: this.aiProvider,
+        model: String(input.model ?? this.defaultModel),
+        tokensUsed: {
+          input: result.usage?.prompt_tokens ?? 0,
+          output: result.usage?.completion_tokens ?? 0,
+          total: result.usage?.total_tokens ?? 0,
+        },
+        durationMs: durationMs,
+        issuer: set.issuer,
+        timestamp: new Date(),
+      });
+
+      return {
+        content: message.content ?? '',
+        toolCalls: toolCalls.length ? toolCalls : undefined,
+        usage: result.usage ? {
+          promptTokens: result.usage.prompt_tokens,
+          completionTokens: result.usage.completion_tokens,
+          totalTokens: result.usage.total_tokens,
+        } : undefined,
+        model: result.model,
+        finishReason: result.choices[0].finish_reason,
+        stopReason: result.choices[0].finish_reason,
+        rawResponse: result,
+      };
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('callModelWithTools', error, set.issuer),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-OLSB-TC0`,
+      });
+    }
+  }
+
+  /** Agnosztikus tool-definicio → OpenAI ChatCompletionTool. */
+  protected toOpenAITool(tool: DyFM_AI_Tool): ChatCompletionTool {
+    return {
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters as Record<string, unknown>,
+      },
+    };
+  }
+
+  /**
+   * Agnosztikus DyFM_AI_Message → OpenAI ChatCompletionMessageParam.
+   * Kezeli a tool-result (role:'tool') es a tool-hivo assistant (tool_calls) uzeneteket is.
+   */
+  protected toOpenAIMessage(message: DyFM_AI_Message): ChatCompletionMessageParam {
+    if (message.role === DyFM_AI_MessageRole.tool) {
+      return {
+        role: 'tool',
+        tool_call_id: message.toolCallId ?? '',
+        content: message.content,
+      };
+    }
+
+    if (message.role === DyFM_AI_MessageRole.assistant && message.toolCalls?.length) {
+      return {
+        role: 'assistant',
+        content: message.content || null,
+        tool_calls: message.toolCalls.map((toolCall: DyFM_AI_ToolCall) => ({
+          id: toolCall.id,
+          type: 'function' as const,
+          function: {
+            name: toolCall.name,
+            arguments: JSON.stringify(toolCall.arguments),
+          },
+        })),
+      };
+    }
+
+    return {
+      role: message.role as 'system' | 'user' | 'assistant',
+      content: message.content,
+    };
+  }
+
+  /** Tool-argumentumok parse-olasa (OpenAI JSON-string → object); hibas JSON eseten ures object. */
+  protected parseToolArguments(raw: string): Record<string, unknown> {
+    try {
+      return JSON.parse(raw || '{}');
+    } catch {
+      return {};
+    }
+  }
+
+  //#endregion
+
 //  async askJSONListQuestion(
 //    question: string,
 //    issuer: string,

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

@@ -1,5 +1,16 @@
 import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
-import { DyFM_AI_CallSettings, DyFM_AI_Message, DyFM_AI_LLM_Response, DyFM_AI_MessageRole } from '@futdevpro/fsm-dynamo/ai';
+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,
@@ -40,7 +51,174 @@ export abstract class DyNTS_AI_LLM_ServiceBase<
   }
 
   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