@futdevpro/nts-dynamo 1.15.24 → 1.15.29

package/src/_modules/ai/_modules/open-ai/_services/oai-embedding.control-service.spec.ts

@@ -1,4 +1,5 @@
 
+import { DyNTS_AI_CostEvent } from '../../../_models/interfaces/dynts-ai-cost-event.interface';
 import { DyNTS_OAI_Embedding_ControlService } from './oai-embedding.control-service';
 import { DyFM_OAI_Settings, DyFM_OAI_Model } from '@futdevpro/fsm-dynamo/ai/open-ai';
 import { DyFM_Error } from '@futdevpro/fsm-dynamo';
@@ -236,5 +237,96 @@ describe('| DyNTS_OAI_Embedding_ControlService', () => {
       expect(result.model).toBe('text-embedding-3-large');
     });
   });
+
+  describe('| FR-002 cost-event emit', () => {
+
+    /** Helper: lecseréli a service onCostEvent callback-jét spy-jal. */
+    function withCostEventCapture(): DyNTS_AI_CostEvent[] {
+      const received: DyNTS_AI_CostEvent[] = [];
+      (service as any).onCostEvent = (e: DyNTS_AI_CostEvent) => { received.push(e); };
+      return received;
+    }
+
+    it('| createEmbedding emits 1 cost-event with embedding-single callType', async () => {
+      const received: DyNTS_AI_CostEvent[] = withCostEventCapture();
+
+      await service.createEmbedding({
+        text: 'hello',
+        model: DyFM_OAI_Model.textEmbedding_3Small,
+        issuer: 'test-issuer',
+      });
+
+      expect(received.length).toBe(1);
+      expect(received[0].callType).toBe('embedding-single');
+      expect(received[0].provider).toBe('open-ai');
+      expect(received[0].model).toBe(DyFM_OAI_Model.textEmbedding_3Small);
+      expect(received[0].tokensUsed.input).toBe(5);
+      expect(received[0].tokensUsed.total).toBe(5);
+      expect(received[0].tokensUsed.output).toBeUndefined();
+      expect(received[0].issuer).toBe('test-issuer');
+      expect(received[0].timestamp).toBeInstanceOf(Date);
+      expect(received[0].durationMs).toBeGreaterThanOrEqual(0);
+      expect(received[0].estimatedCostUsd).toBeUndefined();
+    });
+
+    it('| createEmbeddings emits 1 cost-event with embedding-batch callType', async () => {
+      const received: DyNTS_AI_CostEvent[] = withCostEventCapture();
+
+      // Override-oljuk a top-level beforeEach mockját (prompt_tokens:5) hogy a batch
+      // szándékát tükrözze (2 input → magasabb token-count). A korábbi 10/10 expect
+      // assert-eket a default mock 5-tel cáfolta (BL-20260518-001).
+      mockEmbeddingsCreate.and.returnValue({
+        data: [
+          { embedding: [0.1, 0.2, 0.3], index: 0, object: 'embedding' },
+          { embedding: [0.4, 0.5, 0.6], index: 1, object: 'embedding' },
+        ],
+        model: 'text-embedding-3-small',
+        object: 'list',
+        usage: { prompt_tokens: 10, total_tokens: 10 },
+      });
+
+      await service.createEmbeddings({
+        texts: ['a', 'b'],
+        model: DyFM_OAI_Model.textEmbedding_3Small,
+        issuer: 'batch-issuer',
+      });
+
+      expect(received.length).toBe(1);
+      expect(received[0].callType).toBe('embedding-batch');
+      expect(received[0].issuer).toBe('batch-issuer');
+      expect(received[0].tokensUsed.input).toBe(10);
+      expect(received[0].tokensUsed.total).toBe(10);
+    });
+
+    it('| does NOT emit when the API call throws (emit only after success)', async () => {
+      const received: DyNTS_AI_CostEvent[] = withCostEventCapture();
+      mockEmbeddingsCreate.and.throwError(new Error('upstream API failed'));
+
+      try {
+        await service.createEmbedding({
+          text: 'hello',
+          model: DyFM_OAI_Model.textEmbedding_3Small,
+          issuer: 'test-issuer',
+        });
+        fail('Should have thrown');
+      } catch {
+        // expected
+      }
+
+      expect(received.length).toBe(0);
+    });
+
+    it('| stays non-breaking: with no onCostEvent the call still succeeds', async () => {
+      (service as any).onCostEvent = undefined;
+
+      const result = await service.createEmbedding({
+        text: 'hello',
+        model: DyFM_OAI_Model.textEmbedding_3Small,
+        issuer: 'test-issuer',
+      });
+
+      expect(result).toEqual([0.1, 0.2, 0.3]);
+    });
+  });
 });
 

package/src/_modules/ai/_modules/open-ai/_services/oai-embedding.control-service.ts

@@ -27,10 +27,27 @@ export class DyNTS_OAI_Embedding_ControlService extends DyNTS_OAI_LLM_ServiceBas
         });
       }
 
-      const response = await this.openai.embeddings.create({
+      // FR-002 — per-call cost-event timing: a tényleges API-call latency mérve
+      const start: number = Date.now();
+      const response: CreateEmbeddingResponse = await this.openai.embeddings.create({
         model: set.model,
         input: set.text,
       });
+      const durationMs: number = Date.now() - start;
+
+      // FR-002 — cost-event emit (safe, no-op ha nincs onCostEvent callback)
+      this.emitCostEvent({
+        callType: 'embedding-single',
+        provider: this.aiProvider,
+        model: String(set.model),
+        tokensUsed: {
+          input: response.usage?.prompt_tokens ?? 0,
+          total: response.usage?.total_tokens ?? 0,
+        },
+        durationMs: durationMs,
+        issuer: set.issuer,
+        timestamp: new Date(),
+      });
 
       if (set.fullResponse) {
         return response;
@@ -63,10 +80,27 @@ export class DyNTS_OAI_Embedding_ControlService extends DyNTS_OAI_LLM_ServiceBas
         });
       }
 
-      const response = await this.openai.embeddings.create({
+      // FR-002 — per-call cost-event timing
+      const start: number = Date.now();
+      const response: CreateEmbeddingResponse = await this.openai.embeddings.create({
         model: set.model,
         input: set.texts,
       });
+      const durationMs: number = Date.now() - start;
+
+      // FR-002 — cost-event emit (batch-call → 'embedding-batch')
+      this.emitCostEvent({
+        callType: 'embedding-batch',
+        provider: this.aiProvider,
+        model: String(set.model),
+        tokensUsed: {
+          input: response.usage?.prompt_tokens ?? 0,
+          total: response.usage?.total_tokens ?? 0,
+        },
+        durationMs: durationMs,
+        issuer: set.issuer,
+        timestamp: new Date(),
+      });
 
       if (set.fullResponse) {
         return response;
@@ -84,12 +118,12 @@ export class DyNTS_OAI_Embedding_ControlService extends DyNTS_OAI_LLM_ServiceBas
 
   /**
    * Visszaadja az embedding model információkat
-   * 
+   *
    * Returns embedding model information
    */
   getEmbeddingInfo(model: string): DyFM_DAI_EmbeddingInfo {
     const dimensions = DyFM_OAI_EmbeddingModelDimensions[model as keyof typeof DyFM_OAI_EmbeddingModelDimensions];
-    
+
     return {
       provider: DyFM_AI_Provider.OpenAI,
       model: model

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

@@ -467,12 +467,31 @@ export class DyNTS_OAI_LLMChat_ServiceBase extends DyNTS_OAI_LLM_ServiceBase imp
         conversation: shortenedConversation,
       });
 
+      // FR-002 — per-call cost-event timing
+      const callInput = this.getMessageCreateInput({
+        ...set,
+        conversation: shortenedConversation,
+      });
+      const start: number = Date.now();
       const result: ChatCompletion = await this.openai.chat.completions.create(
-        this.getMessageCreateInput({
-          ...set,
-          conversation: shortenedConversation,
-        })
+        callInput,
       ) as ChatCompletion;
+      const durationMs: number = Date.now() - start;
+
+      // FR-002 — cost-event emit (resolveConversation = 'llm-chat' flow alapból)
+      this.emitCostEvent({
+        callType: 'llm-chat',
+        provider: this.aiProvider,
+        model: String(callInput.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(),
+      });
 
       if (set.getFullResponse) {
         return result;
@@ -482,7 +501,7 @@ export class DyNTS_OAI_LLMChat_ServiceBase extends DyNTS_OAI_LLM_ServiceBase imp
     } catch (error) {
       throw new DyFM_Error({
         ...this.getDefaultErrorSettings('resolveConversation', error, set.issuer),
-        
+
         errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-OAB-RC0`,
       });
     }

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

@@ -343,6 +343,58 @@ describe('| DyNTS_OAI_LLM_ServiceBase', () => {
     });
   });
 
+  describe('| FR-002 cost-event emit', () => {
+
+    it('| should emit cost-event with llm-completion callType for single user message', async () => {
+      const received: any[] = [];
+      (service as any).onCostEvent = (e: any) => { received.push(e); };
+
+      await service.resolveMessage({
+        conversation: [{ role: DyFM_AI_MessageRole.user, content: 'Q?' }],
+        issuer: 'llm-issuer-1',
+      });
+
+      expect(received.length).toBe(1);
+      expect(received[0].callType).toBe('llm-completion');
+      expect(received[0].provider).toBe('open-ai');
+      expect(received[0].model).toBe(DyFM_OAI_Model.gpt4o_mini);
+      expect(received[0].tokensUsed.input).toBe(10);
+      expect(received[0].tokensUsed.output).toBe(5);
+      expect(received[0].tokensUsed.total).toBe(15);
+      expect(received[0].issuer).toBe('llm-issuer-1');
+      expect(received[0].timestamp).toBeInstanceOf(Date);
+      expect(received[0].durationMs).toBeGreaterThanOrEqual(0);
+      expect(received[0].estimatedCostUsd).toBeUndefined();
+    });
+
+    it('| should emit cost-event with llm-chat callType for multi-message conversation', async () => {
+      const received: any[] = [];
+      (service as any).onCostEvent = (e: any) => { received.push(e); };
+
+      await service.resolveMessage({
+        conversation: [
+          { role: DyFM_AI_MessageRole.user,      content: 'Q1?' },
+          { role: DyFM_AI_MessageRole.assistant, content: 'A1.' },
+          { role: DyFM_AI_MessageRole.user,      content: 'Q2?' },
+        ],
+        issuer: 'llm-issuer-chat',
+      });
+
+      expect(received.length).toBe(1);
+      expect(received[0].callType).toBe('llm-chat');
+    });
+
+    it('| constructor accepts onCostEvent option (non-breaking additive)', () => {
+      const cb: any = jasmine.createSpy('onCostEvent');
+      const s: DyNTS_OAI_LLM_ServiceBase = new DyNTS_OAI_LLM_ServiceBase({
+        ...mockSettings,
+        onCostEvent: cb,
+      });
+
+      expect((s as any).onCostEvent).toBe(cb);
+    });
+  });
+
   describe('| getMessageCreateInput', () => {
     it('| should create input with default settings', () => {
       const conversation: DyFM_AI_Message[] = [

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

@@ -15,6 +15,7 @@ import {
 import { DyNTS_global_settings } from '../../../../../_collections/global-settings.const';
 import { ChatCompletion } from 'openai/resources';
 import { ChatCompletionCreateParamsBase, ChatCompletionMessageParam } 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';
 import { DyNTS_OAI_LLMDefaultPredefined_Requests } from '../_collections/oai-llm-predefined-requests.conts';
@@ -82,14 +83,14 @@ export class DyNTS_OAI_LLM_ServiceBase extends DyNTS_AI_LLM_ServiceBase {
   predefinedRequests: DyNTS_OAI_LLM_Predefined_Requests = DyNTS_OAI_LLMDefaultPredefined_Requests;
 
   constructor(
-    set?: DyFM_OAI_Settings
+    set?: DyFM_OAI_Settings & { onCostEvent?: DyNTS_AI_CostEventCallback }
   ) {
     super();
-    
+
     DyNTS_global_settings.openAi_settings ??= DyNTS_OAI_global_settings;
-    
+
     this.openai = new OpenAI(
-      set?.config ?? 
+      set?.config ??
       {
         organization: DyNTS_global_settings.env_settings.openAi.organization,
         apiKey: DyNTS_global_settings.env_settings.openAi.apiKey,
@@ -97,9 +98,14 @@ export class DyNTS_OAI_LLM_ServiceBase extends DyNTS_AI_LLM_ServiceBase {
       }
     );
 
-    this.defaultSettings = set?.defaultSettings ?? 
-      DyNTS_OAI_global_settings.defaultSettings ?? 
+    this.defaultSettings = set?.defaultSettings ??
+      DyNTS_OAI_global_settings.defaultSettings ??
       new DyFM_OAI_CallSettings();
+
+    // FR-002 — opcionális per-call cost-event callback átadás a base-osztálynak
+    if (set?.onCostEvent) {
+      this.onCostEvent = set.onCostEvent;
+    }
   }
 
   /**
@@ -445,13 +451,36 @@ export class DyNTS_OAI_LLM_ServiceBase extends DyNTS_AI_LLM_ServiceBase {
     } */
   ): Promise<string | ChatCompletion> {
     try {
-      set.conversation.unshift(this.getDefaultSystemMessage(set.settings));
-
+      // FR-002 — callType meghatározás a unshift ELŐTT (a system-message hozzáadás
+      // után már 2+ message lenne, ami a "chat" kategóriát mindig kiváltja).
+      // 1 user-message → 'llm-completion'; több → 'llm-chat'. A 'llm-tool-use'
+      // categoria a tools paraméterek bevezetésekor kerül használatba (jövőbeli FR).
+      const userMessageCount: number = set.conversation.length;
 
+      set.conversation.unshift(this.getDefaultSystemMessage(set.settings));
 
+      // FR-002 — per-call cost-event timing: a tényleges API-call latency mérve
+      const input: ChatCompletionCreateParamsBase = this.getMessageCreateInput(set);
+      const start: number = Date.now();
       const result: ChatCompletion = await this.openai.chat.completions.create(
-        this.getMessageCreateInput(set)
+        input,
       ) as ChatCompletion;
+      const durationMs: number = Date.now() - start;
+
+      // FR-002 — cost-event emit (safe, no-op ha nincs onCostEvent callback)
+      this.emitCostEvent({
+        callType: userMessageCount === 1 ? 'llm-completion' : 'llm-chat',
+        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(),
+      });
 
       if (set.getFullResponse) {
         return result;
@@ -461,7 +490,7 @@ export class DyNTS_OAI_LLM_ServiceBase extends DyNTS_AI_LLM_ServiceBase {
     } catch (error) {
       throw new DyFM_Error({
         ...this.getDefaultErrorSettings('resolveConversation', error, set.issuer),
-        
+
         errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-OLSB-RM0`,
       });
     }

package/src/_modules/ai/_services/ai-provider.service-base.spec.ts

@@ -1,4 +1,6 @@
 
+import { DyNTS_AI_CostEvent } from '../_models/interfaces/dynts-ai-cost-event.interface';
+import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
 import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
 import { DyFM_AI_Provider, DyFM_AI_ProviderCapabilities, DyFM_AI_Config } from '@futdevpro/fsm-dynamo/ai';
 
@@ -25,11 +27,35 @@ class TestProviderService extends DyNTS_AI_Provider_ServiceBase {
     return true;
   };
 
+  /** Test-only helper: ráad egy callback-et a protected onCostEvent fielden át. */
+  public setOnCostEventForTest(cb: DyNTS_AI_CostEventCallback | undefined): void {
+    this.onCostEvent = cb;
+  }
+
+  /** Test-only helper: meghívja a protected emitCostEvent-et (a sub-class amúgy is hívná). */
+  public emitForTest(event: DyNTS_AI_CostEvent): void {
+    this.emitCostEvent(event);
+  }
+
   static getInstance(): TestProviderService {
     return TestProviderService.getSingletonInstance();
   }
 }
 
+/** Helper: minimal valid DyNTS_AI_CostEvent. */
+function makeCostEvent(overrides: Partial<DyNTS_AI_CostEvent> = {}): DyNTS_AI_CostEvent {
+  return {
+    callType: 'embedding-single',
+    provider: 'openai',
+    model: 'text-embedding-3-small',
+    tokensUsed: { input: 10, total: 10 },
+    durationMs: 42,
+    issuer: 'test-issuer',
+    timestamp: new Date(),
+    ...overrides,
+  };
+}
+
 describe('| DyNTS_AI_Provider_ServiceBase', () => {
   let service: TestProviderService;
 
@@ -75,5 +101,58 @@ describe('| DyNTS_AI_Provider_ServiceBase', () => {
       expect(result).toBe(true);
     });
   });
+
+  describe('| emitCostEvent (FR-002 cost-event hook)', () => {
+
+    afterEach(() => {
+      // Reset callback hogy ne szivárogjon át teszt-cases között (singleton service)
+      service.setOnCostEventForTest(undefined);
+    });
+
+    it('| should be no-op when onCostEvent is undefined', () => {
+      service.setOnCostEventForTest(undefined);
+
+      expect(() => {
+        service.emitForTest(makeCostEvent());
+      }).not.toThrow();
+    });
+
+    it('| should invoke the registered callback with the event payload', () => {
+      const received: DyNTS_AI_CostEvent[] = [];
+      service.setOnCostEventForTest((e: DyNTS_AI_CostEvent) => {
+        received.push(e);
+      });
+
+      const event: DyNTS_AI_CostEvent = makeCostEvent({
+        model: 'gpt-4o-mini',
+        callType: 'llm-completion',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+      });
+      service.emitForTest(event);
+
+      expect(received.length).toBe(1);
+      expect(received[0]).toEqual(event);
+      expect(received[0].tokensUsed.total).toBe(150);
+    });
+
+    it('| should NOT throw when the callback itself throws (safe emit)', () => {
+      service.setOnCostEventForTest(() => {
+        throw new Error('consumer callback failure');
+      });
+
+      expect(() => {
+        service.emitForTest(makeCostEvent());
+      }).not.toThrow();
+    });
+
+    it('| should leave estimatedCostUsd undefined by default (Dynamo has no pricing registry)', () => {
+      const received: DyNTS_AI_CostEvent[] = [];
+      service.setOnCostEventForTest((e: DyNTS_AI_CostEvent) => { received.push(e); });
+
+      service.emitForTest(makeCostEvent());
+
+      expect(received[0].estimatedCostUsd).toBeUndefined();
+    });
+  });
 });
 

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

@@ -1,29 +1,67 @@
 import { DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
 import { DyFM_AI_ProviderCapabilities } from '@futdevpro/fsm-dynamo/ai';
 import { DyFM_AI_Config } from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_AI_CostEvent } from '../_models/interfaces/dynts-ai-cost-event.interface';
+import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
 import { DyNTS_SingletonService } from '../../../_services/base/singleton.service';
 
 /**
  * Abstract base class for all AI providers
  * Defines the common interface that all AI providers must implement
+ *
+ * **Cost-event hook (FR-002)**: a leszármazott concrete service-ek (OAI
+ * Embedding / LLM / Chat) a constructor-ban opcionálisan kapnak egy
+ * `onCostEvent` callback-et. Minden sikeres AI-call után `emitCostEvent`-tel
+ * hívják, ami safe (try/catch) — a callback hibája NEM akasztja meg az
+ * AI-call-t. Lásd `DyNTS_AI_CostEvent` interface.
  */
 export abstract class DyNTS_AI_Provider_ServiceBase extends DyNTS_SingletonService {
   /** The AI provider this service represents */
   abstract readonly aiProvider: DyFM_AI_Provider;
-  
+
   /** The capabilities supported by this provider */
   abstract readonly capabilities: DyFM_AI_ProviderCapabilities;
-  
+
+  /**
+   * Optional per-call cost-event callback (FR-002).
+   * A leszármazott service-ek minden sikeres AI-call után meghívják az
+   * `emitCostEvent` helper-en keresztül. Non-breaking: ha undefined, nincs emit.
+   */
+  protected onCostEvent?: DyNTS_AI_CostEventCallback;
+
   /**
    * Initialize the provider with configuration
    * @param config - Provider-specific configuration
    */
   abstract setup(config: DyFM_AI_Config): void;
-  
+
   /**
    * Test the connection to the AI provider
    * @param issuer - The issuer making the request
    * @returns Promise<boolean> - True if connection is successful
    */
   abstract testConnection(issuer: string): Promise<boolean>;
+
+  /**
+   * Safe cost-event emit: ha van regisztrált `onCostEvent` callback, meghívja.
+   * A callback hibája NEM propagálódik — try/catch-csel safen hívjuk és
+   * `DyFM_Log.warn`-nal jelezzük. Ezzel a consumer-oldali integráció
+   * (CCAP `CT_`, telemetry, stb.) hibái nem akasztják meg az AI-call-t.
+   */
+  protected emitCostEvent(event: DyNTS_AI_CostEvent): void {
+    if (!this.onCostEvent) {
+      return;
+    }
+    try {
+      this.onCostEvent(event);
+    } catch (err: unknown) {
+      const msg: string = err instanceof Error ? err.message : String(err);
+      DyFM_Log.warn(
+        `DyNTS AI | onCostEvent callback threw (call-type: ${event.callType},`
+        + ` model: ${event.model}, issuer: ${event.issuer}): ${msg}`,
+      );
+    }
+  }
 }

package/src/_modules/local-vector-search/_enums/lvs-search-mode.enum.ts

@@ -15,5 +15,21 @@ export enum LVS_Search_Mode {
    * Eredmények növekvő sorrendben (legkisebb távolság először)
    */
   l2Distance = 'l2-distance',
+  /**
+   * Hybrid search: cosine similarity (vektor-fele) + BM25 (text-fele) score-merge.
+   *
+   * Hasznalat:
+   *  - `searchMode: LVS_Search_Mode.hybrid`
+   *  - `textSearchKey: keyof T` — KOTELEZO; melyik string property-n fut a BM25
+   *  - `hybridWeight?: { vector: number; text: number }` — default { vector: 0.5, text: 0.5 }
+   *
+   * BM25 min-max normalizalva [0,1] a candidate-szettre (cosine mar 0..1), igy
+   * a `weight` direkt linearis kombinacio. Ha minden BM25 score 0 (egyetlen
+   * query term sem matchel), a hybrid effektivan cosine-only-re degradalodik.
+   *
+   * L2+hybrid kombinacio NEM tamogatott — a hybrid mindig cosine-alapu
+   * vector-half-fel mukodik.
+   */
+  hybrid = 'hybrid',
 }