@futdevpro/nts-dynamo 1.15.34 → 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

package/src/_services/server/app.server.ts

@@ -47,6 +47,9 @@ import {
 import {
   DyNTS_StaticClient_Settings
 } from '../../_models/interfaces/static-client-settings.interface';
+import {
+  DyNTS_Cors_Settings
+} from '../../_models/interfaces/cors-settings.interface';
 import { DyNTS_SingletonService } from '../base/singleton.service';
 import { DyNTS_GlobalService } from '../core/global.service';
 import { DyNTS_RoutingModule } from '../route/routing-module.service';
@@ -1074,20 +1077,24 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
    */
   protected async initOpenExpress(): Promise<void> {
     if (this.fnLogs) DyFM_Log.log('\nfn:. initOpenExpress');
-    this.openExpress = Express();    
+    this.openExpress = Express();
     this.openExpress.set('maxHeaderSize', 10 * megabyte); // 1024 * 1024 * 10, // 10MB
     this.openExpress.use(BodyParser.urlencoded(this._portSettings.httpUrlencoded));
     this.openExpress.use(BodyParser.json(this._portSettings.httpJson));
+    // FR-041 — CORS allowlist enforcement. No-op if getCorsSettings() is not overridden.
+    this.mountCors(this.openExpress);
   }
 
   /**
-   * 
+   *
    */
   protected async initSecureExpress(): Promise<void> {
     if (this.fnLogs) DyFM_Log.log('\nfn:. initSecureExpress');
-    this.secureExpress = Express();    
+    this.secureExpress = Express();
     this.secureExpress.use(BodyParser.urlencoded(this._portSettings.httpsUrlencoded));
     this.secureExpress.use(BodyParser.json(this._portSettings.httpsJson));
+    // FR-041 — CORS allowlist enforcement (same as open express).
+    this.mountCors(this.secureExpress);
 
     const options = {
       key: FileSystem.readFileSync(this._cert.keyPath),
@@ -1412,6 +1419,69 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
     }
   }
 
+  /**
+   * FR-041 — CORS middleware. Echoes a matching `Access-Control-Allow-Origin`
+   * for any request whose Origin header is in `getCorsSettings().allowedOrigins`,
+   * adds the canonical `Access-Control-*` companion headers, and short-circuits
+   * the OPTIONS preflight with a 204.
+   *
+   * No-op when the subclass does NOT override `getCorsSettings()` — preserves
+   * back-compat for apps that have always been same-origin and never needed
+   * CORS (the typical pre-FR-041 case).
+   *
+   * Why hand-rolled instead of the `cors` npm package:
+   *  - ~30 lines, zero new dependency.
+   *  - Full control over Vary/credentials/preflight semantics.
+   *  - Aligns with FDP "no unnecessary deps" philosophy.
+   */
+  protected mountCors(express: Express.Application): void {
+    const settings: DyNTS_Cors_Settings | undefined = this.getCorsSettings?.();
+    if (!settings) {
+      return;
+    }
+
+    const allowCreds: boolean = settings.allowCredentials !== false;
+    const methods: string[] = settings.allowedMethods ?? [
+      'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS',
+    ];
+    const headers: string[] = settings.allowedHeaders ?? [
+      'Authorization', 'Content-Type', 'X-Admin-Key', 'X-Requested-With',
+    ];
+    const exposed: string[] = settings.exposedHeaders ?? [
+      'Content-Length', 'Content-Type',
+    ];
+    const maxAge: number = settings.maxAgeSeconds ?? 86400;
+
+    const isAllowed: (origin: string) => boolean = (origin: string): boolean => {
+      if (settings.allowedOrigins === '*') return true;
+      if (typeof settings.allowedOrigins === 'function') {
+        return settings.allowedOrigins(origin);
+      }
+      return settings.allowedOrigins.includes(origin);
+    };
+
+    express.use((req: Express.Request, res: Express.Response, next: Express.NextFunction): void => {
+      const origin: string | undefined = req.headers.origin;
+      if (origin && isAllowed(origin)) {
+        // Echo the matching origin (NOT wildcard) because credentials require it.
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        if (allowCreds) {
+          res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
+        res.setHeader('Access-Control-Allow-Headers', headers.join(', '));
+        res.setHeader('Access-Control-Expose-Headers', exposed.join(', '));
+        res.setHeader('Access-Control-Max-Age', String(maxAge));
+        res.setHeader('Vary', 'Origin');
+      }
+      if (req.method === 'OPTIONS') {
+        res.status(204).end();
+        return;
+      }
+      next();
+    });
+  }
+
   /**
    * Ha getStaticClientSettings() visszaad beállításokat, a client static fájlok a '/' alatt
    * lesznek kiszolgálva (API route-ok után). SPA fallback opcionális (fallbackPath).
@@ -1580,6 +1650,15 @@ export abstract class DyNTS_App extends DyNTS_SingletonService {
    */
   getStaticClientSettings?(): DyNTS_StaticClient_Settings | undefined;
 
+  /**
+   * FR-041 — Ha megadva, CORS middleware mount-olódik mindkét Express instance-ra
+   * (open + secure). Az `allowedOrigins` listán szereplő Origin-eket echo-zza vissza,
+   * `Access-Control-Allow-Credentials: true`-val (default) együtt a Bearer JWT
+   * cross-domain auth flow miatt. OPTIONS preflight 204-gyel rövidre záródik.
+   * Ha undefined → no CORS headers, no preflight handling — back-compat.
+   */
+  getCorsSettings?(): DyNTS_Cors_Settings | undefined;
+
   /**
    * MISSING Description (TODO)
    */

package/src/index.ts

@@ -50,6 +50,7 @@ export * from './_models/interfaces/global-service-settings.interface';
 export * from './_models/interfaces/global-settings.interface';
 export * from './_models/interfaces/routing-module-settings.interface';
 export * from './_models/interfaces/static-client-settings.interface';
+export * from './_models/interfaces/cors-settings.interface';
 
 // models/CONTROL MODELS
 export * from './_models/control-models/api-call-params.control-model';