@futdevpro/nts-dynamo 1.15.23 → 1.15.29

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',
 }
 

package/src/_modules/local-vector-search/_services/lvs-bm25.util.spec.ts

@@ -0,0 +1,159 @@
+import {
+  DyNTS_LVS_BM25_Corpus,
+  DyNTS_LVS_BM25_DocScore,
+  dyNTS_LVS_BM25_minMaxNormalize,
+} from './lvs-bm25.util';
+
+
+describe('| DyNTS_LVS_BM25_Corpus.tokenize', (): void => {
+  it('| lowercase + split on \\w+ boundaries', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('Hello, World!')).toEqual(['hello', 'world']);
+  });
+
+  it('| identifier marad egy tokenkent (PascalCase)', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('UserController')).toEqual(['usercontroller']);
+  });
+
+  it('| hyphenated nev ket tokenre esik', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('auth-flow')).toEqual(['auth', 'flow']);
+  });
+
+  it('| ures string → ures array', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('')).toEqual([]);
+  });
+
+  it('| csak whitespace/punctuation → ures array', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('   ,.!  ')).toEqual([]);
+  });
+
+  it('| underscore megmarad (snake_case is egy token)', (): void => {
+    expect(DyNTS_LVS_BM25_Corpus.tokenize('user_controller')).toEqual(['user_controller']);
+  });
+});
+
+
+describe('| DyNTS_LVS_BM25_Corpus.score', (): void => {
+  it('| ures corpus → ures array', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([]);
+    expect(corpus.size()).toBe(0);
+    expect(corpus.score('anything')).toEqual([]);
+  });
+
+  it('| ures query → minden doc 0 score-t kap', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'foo bar' },
+      { id: 'b', text: 'baz' },
+    ]);
+    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('');
+    expect(out.length).toBe(2);
+    expect(out.every((s: DyNTS_LVS_BM25_DocScore) => s.score === 0)).toBe(true);
+  });
+
+  it('| query NEM matchelo termmel → minden score 0', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'foo bar' },
+      { id: 'b', text: 'baz' },
+    ]);
+    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('xyz');
+    expect(out.every((s: DyNTS_LVS_BM25_DocScore) => s.score === 0)).toBe(true);
+  });
+
+  it('| relevant doc magasabb score-t kap mint nem-relevant', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'the UserController handles authentication' },
+      { id: 'b', text: 'cooking recipes for desserts' },
+      { id: 'c', text: 'database setup guide' },
+    ]);
+    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('UserController');
+    const a: DyNTS_LVS_BM25_DocScore = out.find((s) => s.id === 'a')!;
+    const b: DyNTS_LVS_BM25_DocScore = out.find((s) => s.id === 'b')!;
+    expect(a.score).toBeGreaterThan(0);
+    expect(b.score).toBe(0);
+    expect(a.score).toBeGreaterThan(b.score);
+  });
+
+  it('| rarer term (alacsonyabb df) magasabb IDF-et ad → magasabb score', (): void => {
+    // 'common' minden docban → alacsony IDF; 'rare' csak az 'a' docban → magas IDF
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'common rare' },
+      { id: 'b', text: 'common' },
+      { id: 'c', text: 'common' },
+      { id: 'd', text: 'common' },
+    ]);
+    const commonOut: DyNTS_LVS_BM25_DocScore[] = corpus.score('common');
+    const rareOut: DyNTS_LVS_BM25_DocScore[] = corpus.score('rare');
+    const aCommon: number = commonOut.find((s) => s.id === 'a')!.score;
+    const aRare: number = rareOut.find((s) => s.id === 'a')!.score;
+    expect(aRare).toBeGreaterThan(aCommon);
+  });
+
+  it('| query-term ismetles NEM no monotonan a score-on (term saturation k1)', (): void => {
+    // 'a' egy 'foo'-t tartalmaz, 'b' tobbet
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'foo bar baz qux' },
+      { id: 'b', text: 'foo foo foo foo bar baz qux' },
+    ]);
+    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('foo');
+    const a: number = out.find((s) => s.id === 'a')!.score;
+    const b: number = out.find((s) => s.id === 'b')!.score;
+    // b > a, de NEM 4x a-szor (saturation)
+    expect(b).toBeGreaterThan(a);
+    expect(b).toBeLessThan(4 * a);
+  });
+
+  it('| case-insensitive — uppercase query matchel lowercase doc-ot', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'usercontroller is great' },
+    ]);
+    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('USERCONTROLLER');
+    expect(out[0].score).toBeGreaterThan(0);
+  });
+
+  it('| ket query term aggregalja az IDF-eket additivan', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'auth flow handler' },
+      { id: 'b', text: 'auth only' },
+      { id: 'c', text: 'flow only' },
+    ]);
+    const both: number = corpus.score('auth flow').find((s) => s.id === 'a')!.score;
+    const authOnly: number = corpus.score('auth').find((s) => s.id === 'a')!.score;
+    expect(both).toBeGreaterThan(authOnly);
+  });
+
+  it('| invalid input doc (null/missing id/text) silently skipd', (): void => {
+    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
+      { id: 'a', text: 'hello' },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      null as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      { id: 'b' } as any,
+    ]);
+    expect(corpus.size()).toBe(1);
+  });
+});
+
+
+describe('| dyNTS_LVS_BM25_minMaxNormalize', (): void => {
+  it('| ures input → ures array', (): void => {
+    expect(dyNTS_LVS_BM25_minMaxNormalize([])).toEqual([]);
+  });
+
+  it('| min 0, max 10 → normalizalva [0..1]', (): void => {
+    const out: DyNTS_LVS_BM25_DocScore[] = dyNTS_LVS_BM25_minMaxNormalize([
+      { id: 'a', score: 0 },
+      { id: 'b', score: 5 },
+      { id: 'c', score: 10 },
+    ]);
+    expect(out.find((s) => s.id === 'a')!.score).toBeCloseTo(0, 5);
+    expect(out.find((s) => s.id === 'b')!.score).toBeCloseTo(0.5, 5);
+    expect(out.find((s) => s.id === 'c')!.score).toBeCloseTo(1, 5);
+  });
+
+  it('| azonos score → minden 0 (NEM 0.5, nincs jel diszkriminaciora)', (): void => {
+    const out: DyNTS_LVS_BM25_DocScore[] = dyNTS_LVS_BM25_minMaxNormalize([
+      { id: 'a', score: 3 },
+      { id: 'b', score: 3 },
+    ]);
+    expect(out.every((s) => s.score === 0)).toBe(true);
+  });
+});