@futdevpro/nts-dynamo 1.15.68 → 1.15.70

package/src/_modules/ai/_services/ai-embedding-mock.service.ts

@@ -1,233 +1,233 @@
-import * as crypto from 'crypto';
-import { CreateEmbeddingResponse } from 'openai/resources';
-
-import { DyFM_AI_Provider, DyFM_AI_ProviderCapabilities, DyFM_AI_Config } from '@futdevpro/fsm-dynamo/ai';
-import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
-
-import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
-import { DyNTS_AI_Embedding_ServiceBase } from './ai-embedding.service-base';
-
-/** A mock-embedding default dimenziója (kicsi, hogy a teszt-pool gyors legyen, de elég a koszinuszhoz). */
-export const DyNTS_AI_MOCK_EMBEDDING_DIMS: number = 64;
-
-/**
- * A mock embedding-service config-set-je. A `dims` a generált vektor dimenziója (default
- * `DyNTS_AI_MOCK_EMBEDDING_DIMS`), az `onCostEvent` a per-call cost-event sink (FR-002 / BFR-AM-007).
- */
-export interface DyNTS_AI_Embedding_MockSettings {
-  /** A generált vektor dimenziója (default `DyNTS_AI_MOCK_EMBEDDING_DIMS`). */
-  dims?: number;
-  /** Per-call cost-event callback (FR-002 / BFR-AM-007). Non-breaking: ha undefined, nincs emit. */
-  onCostEvent?: DyNTS_AI_CostEventCallback;
-}
-
-/**
- * `DyNTS_AI_Embedding_MockService` (BFR-AM-008) — determinisztikus, hash-alapú, fix-dimenziós,
- * l2-normalizált pszeudo-vektor a szövegből. Provider- és hálózat-mentes → a tesztek + a tsc-/offline-
- * smoke valódi API-kulcs nélkül futnak. Azonos `(model, text)` → azonos vektor (idempotens), így a
- * koszinusz-keresés determinisztikusan tesztelhető. A FAM `FAM_Mock_EmbeddingProvider` workaround-ját
- * emeli bedrock-szintre, mint újrahasználható test-double.
- *
- * **Cost-event (BFR-AM-007):** minden call után `emitCostEvent`-tel jelez (fake token-fogyasztás,
- * 4 char ≈ 1 token), provider `'mock'`, callType `embedding-single` / `embedding-batch`. Így a
- * cost-aggregáló pipeline mock-providerrel is end-to-end tesztelhető.
- */
-export class DyNTS_AI_Embedding_MockService extends DyNTS_AI_Embedding_ServiceBase {
-
-  /** A mock a `LocalAI` provider-enum alá tartozik (nincs külső hívás). */
-  readonly aiProvider: DyFM_AI_Provider = DyFM_AI_Provider.LocalAI;
-
-  /** A cost-event provider-string (a `DyNTS_AI_CostEvent.provider` szabad-string mezőjéhez). */
-  protected readonly costProvider: string = 'mock';
-
-  /** Mock capability-k: csak embedding (determinisztikus). */
-  readonly capabilities: DyFM_AI_ProviderCapabilities = {
-    chat: false,
-    embeddings: true,
-    imageGeneration: false,
-    vision: false,
-    audioGeneration: false,
-    audioAnalysis: false,
-    functionCalling: false,
-    streaming: false,
-    batchOperations: true,
-    supportedModelTypes: [],
-  };
-
-  /** A generált vektor dimenziója. */
-  protected dims: number;
-
-  /** @param set opcionális dims + onCostEvent. */
-  constructor(set?: DyNTS_AI_Embedding_MockSettings) {
-    super();
-    this.dims = set?.dims && set.dims > 0 ? set.dims : DyNTS_AI_MOCK_EMBEDDING_DIMS;
-
-    if (set?.onCostEvent) {
-      this.onCostEvent = set.onCostEvent;
-    }
-  }
-
-  /** A mock-nak nincs külső config-ja; a `setup` a dimenzió override-jára szolgál (config.dimensions). */
-  setup(config: DyFM_AI_Config): void {
-    const dims: unknown = Reflect.get(config ?? {}, 'dimensions');
-
-    if (typeof dims === 'number' && dims > 0) {
-      this.dims = dims;
-    }
-  }
-
-  /**
-   * Egy determinisztikus embedding. A `model`-t beleszövi a seed-be, hogy modell-váltás más vektort
-   * adjon (re-embed teszteléshez). `fullResponse=true` → OpenAI-alakú válasz-objektum.
-   */
-  async createEmbedding(
-    set: {
-      text: string;
-      model: string;
-      fullResponse?: boolean;
-      issuer: string;
-    }
-  ): Promise<number[] | CreateEmbeddingResponse> {
-    const start: number = Date.now();
-    const vector: number[] = this.deterministicVector(`${set.model}::${set.text ?? ''}`);
-    const durationMs: number = Date.now() - start;
-
-    this.emitMockCostEvent('embedding-single', set.model, [ set.text ?? '' ], durationMs, set.issuer);
-
-    if (set.fullResponse) {
-      return this.toResponse([ vector ], set.model, [ set.text ?? '' ]);
-    }
-
-    return vector;
-  }
-
-  /**
-   * Determinisztikus batch-embedding: minden szöveghez a `(model, text)` seed-ből generál egy fix-
-   * dimenziós, l2-normalizált vektort. A `texts` sorrendje == a visszaadott `number[][]` sorrendje.
-   */
-  async createEmbeddings(
-    set: {
-      texts: string[];
-      model: string;
-      fullResponse?: boolean;
-      issuer: string;
-    }
-  ): Promise<number[][] | CreateEmbeddingResponse> {
-    const texts: string[] = set.texts ?? [];
-    const start: number = Date.now();
-    const vectors: number[][] = texts.map((text) => this.deterministicVector(`${set.model}::${text}`));
-    const durationMs: number = Date.now() - start;
-
-    this.emitMockCostEvent('embedding-batch', set.model, texts, durationMs, set.issuer);
-
-    if (set.fullResponse) {
-      return this.toResponse(vectors, set.model, texts);
-    }
-
-    return vectors;
-  }
-
-  /** Embedding model-info: provider `LocalAI`, model a megadott azonosító. */
-  getEmbeddingInfo(model: string): DyFM_DAI_EmbeddingInfo {
-    return {
-      provider: DyFM_AI_Provider.LocalAI,
-      model: model,
-    };
-  }
-
-  /** A mock mindig elérhető (nincs külső függőség). */
-  async testConnection(_issuer: string): Promise<boolean> {
-    return true;
-  }
-
-  // =========================================================================
-  // belső: determinisztikus vektor + cost-event + response-alak
-  // =========================================================================
-
-  /**
-   * Egy determinisztikus, l2-normalizált vektor a seed-ből. A SHA-256 hash bájtjait körkörösen
-   * használja a `dims` kitöltésére, [-1, 1) tartományra képzi, majd l2-normalizál (egységhossz a
-   * koszinuszhoz). Egy második hash-bájttal kever, hogy a hosszabb dimenziókon ne ismétlődjön a minta.
-   */
-  protected deterministicVector(seed: string): number[] {
-    const hash: Buffer = crypto.createHash('sha256').update(seed).digest();
-    const vector: number[] = [];
-
-    for (let i = 0; i < this.dims; i++) {
-      const byte: number = hash[i % hash.length];
-      const mix: number = hash[(i * 7 + 3) % hash.length];
-      const combined: number = (byte ^ mix) & 0xff;
-
-      vector.push((combined / 255) * 2 - 1);
-    }
-
-    return this.l2Normalize(vector);
-  }
-
-  /** L2-normalizálás (egységhossz). Nulla-vektor → változatlan (elkerüli a 0-osztást). */
-  protected l2Normalize(vector: number[]): number[] {
-    let sumSq: number = 0;
-
-    for (const value of vector) {
-      sumSq += value * value;
-    }
-    const norm: number = Math.sqrt(sumSq);
-
-    if (!norm) {
-      return vector;
-    }
-
-    return vector.map((value) => value / norm);
-  }
-
-  /** OpenAI-alakú válasz-objektum a vektorokból (a `fullResponse=true` ághoz). */
-  protected toResponse(vectors: number[][], model: string, texts: string[]): CreateEmbeddingResponse {
-    const tokens: number = this.estimateTokens(texts);
-
-    return {
-      object: 'list',
-      model: model,
-      data: vectors.map((embedding, index) => ({ object: 'embedding', embedding: embedding, index: index })),
-      usage: {
-        prompt_tokens: tokens,
-        total_tokens: tokens,
-      },
-    };
-  }
-
-  /** Cost-event emit (BFR-AM-007) fake tokennel (4 char ≈ 1 token), provider `'mock'`. */
-  protected emitMockCostEvent(
-    callType: 'embedding-single' | 'embedding-batch',
-    model: string,
-    texts: string[],
-    durationMs: number,
-    issuer: string,
-  ): void {
-    const tokens: number = this.estimateTokens(texts);
-
-    this.emitCostEvent({
-      callType: callType,
-      provider: this.costProvider,
-      model: model,
-      tokensUsed: {
-        input: tokens,
-        total: tokens,
-      },
-      durationMs: durationMs,
-      issuer: issuer,
-      timestamp: new Date(),
-      estimatedCostUsd: 0,
-    });
-  }
-
-  /** Becsült (fake) token-szám: 4 char ≈ 1 token. */
-  protected estimateTokens(texts: string[]): number {
-    let chars: number = 0;
-
-    for (const text of texts) {
-      chars += (text ?? '').length;
-    }
-
-    return Math.max(1, Math.ceil(chars / 4));
-  }
-}
+import * as crypto from 'crypto';
+import { CreateEmbeddingResponse } from 'openai/resources';
+
+import { DyFM_AI_Provider, DyFM_AI_ProviderCapabilities, DyFM_AI_Config } from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
+
+import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
+import { DyNTS_AI_Embedding_ServiceBase } from './ai-embedding.service-base';
+
+/** A mock-embedding default dimenziója (kicsi, hogy a teszt-pool gyors legyen, de elég a koszinuszhoz). */
+export const DyNTS_AI_MOCK_EMBEDDING_DIMS: number = 64;
+
+/**
+ * A mock embedding-service config-set-je. A `dims` a generált vektor dimenziója (default
+ * `DyNTS_AI_MOCK_EMBEDDING_DIMS`), az `onCostEvent` a per-call cost-event sink (FR-002 / BFR-AM-007).
+ */
+export interface DyNTS_AI_Embedding_MockSettings {
+  /** A generált vektor dimenziója (default `DyNTS_AI_MOCK_EMBEDDING_DIMS`). */
+  dims?: number;
+  /** Per-call cost-event callback (FR-002 / BFR-AM-007). Non-breaking: ha undefined, nincs emit. */
+  onCostEvent?: DyNTS_AI_CostEventCallback;
+}
+
+/**
+ * `DyNTS_AI_Embedding_MockService` (BFR-AM-008) — determinisztikus, hash-alapú, fix-dimenziós,
+ * l2-normalizált pszeudo-vektor a szövegből. Provider- és hálózat-mentes → a tesztek + a tsc-/offline-
+ * smoke valódi API-kulcs nélkül futnak. Azonos `(model, text)` → azonos vektor (idempotens), így a
+ * koszinusz-keresés determinisztikusan tesztelhető. A FAM `FAM_Mock_EmbeddingProvider` workaround-ját
+ * emeli bedrock-szintre, mint újrahasználható test-double.
+ *
+ * **Cost-event (BFR-AM-007):** minden call után `emitCostEvent`-tel jelez (fake token-fogyasztás,
+ * 4 char ≈ 1 token), provider `'mock'`, callType `embedding-single` / `embedding-batch`. Így a
+ * cost-aggregáló pipeline mock-providerrel is end-to-end tesztelhető.
+ */
+export class DyNTS_AI_Embedding_MockService extends DyNTS_AI_Embedding_ServiceBase {
+
+  /** A mock a `LocalAI` provider-enum alá tartozik (nincs külső hívás). */
+  readonly aiProvider: DyFM_AI_Provider = DyFM_AI_Provider.LocalAI;
+
+  /** A cost-event provider-string (a `DyNTS_AI_CostEvent.provider` szabad-string mezőjéhez). */
+  protected readonly costProvider: string = 'mock';
+
+  /** Mock capability-k: csak embedding (determinisztikus). */
+  readonly capabilities: DyFM_AI_ProviderCapabilities = {
+    chat: false,
+    embeddings: true,
+    imageGeneration: false,
+    vision: false,
+    audioGeneration: false,
+    audioAnalysis: false,
+    functionCalling: false,
+    streaming: false,
+    batchOperations: true,
+    supportedModelTypes: [],
+  };
+
+  /** A generált vektor dimenziója. */
+  protected dims: number;
+
+  /** @param set opcionális dims + onCostEvent. */
+  constructor(set?: DyNTS_AI_Embedding_MockSettings) {
+    super();
+    this.dims = set?.dims && set.dims > 0 ? set.dims : DyNTS_AI_MOCK_EMBEDDING_DIMS;
+
+    if (set?.onCostEvent) {
+      this.onCostEvent = set.onCostEvent;
+    }
+  }
+
+  /** A mock-nak nincs külső config-ja; a `setup` a dimenzió override-jára szolgál (config.dimensions). */
+  setup(config: DyFM_AI_Config): void {
+    const dims: unknown = Reflect.get(config ?? {}, 'dimensions');
+
+    if (typeof dims === 'number' && dims > 0) {
+      this.dims = dims;
+    }
+  }
+
+  /**
+   * Egy determinisztikus embedding. A `model`-t beleszövi a seed-be, hogy modell-váltás más vektort
+   * adjon (re-embed teszteléshez). `fullResponse=true` → OpenAI-alakú válasz-objektum.
+   */
+  async createEmbedding(
+    set: {
+      text: string;
+      model: string;
+      fullResponse?: boolean;
+      issuer: string;
+    }
+  ): Promise<number[] | CreateEmbeddingResponse> {
+    const start: number = Date.now();
+    const vector: number[] = this.deterministicVector(`${set.model}::${set.text ?? ''}`);
+    const durationMs: number = Date.now() - start;
+
+    this.emitMockCostEvent('embedding-single', set.model, [ set.text ?? '' ], durationMs, set.issuer);
+
+    if (set.fullResponse) {
+      return this.toResponse([ vector ], set.model, [ set.text ?? '' ]);
+    }
+
+    return vector;
+  }
+
+  /**
+   * Determinisztikus batch-embedding: minden szöveghez a `(model, text)` seed-ből generál egy fix-
+   * dimenziós, l2-normalizált vektort. A `texts` sorrendje == a visszaadott `number[][]` sorrendje.
+   */
+  async createEmbeddings(
+    set: {
+      texts: string[];
+      model: string;
+      fullResponse?: boolean;
+      issuer: string;
+    }
+  ): Promise<number[][] | CreateEmbeddingResponse> {
+    const texts: string[] = set.texts ?? [];
+    const start: number = Date.now();
+    const vectors: number[][] = texts.map((text) => this.deterministicVector(`${set.model}::${text}`));
+    const durationMs: number = Date.now() - start;
+
+    this.emitMockCostEvent('embedding-batch', set.model, texts, durationMs, set.issuer);
+
+    if (set.fullResponse) {
+      return this.toResponse(vectors, set.model, texts);
+    }
+
+    return vectors;
+  }
+
+  /** Embedding model-info: provider `LocalAI`, model a megadott azonosító. */
+  getEmbeddingInfo(model: string): DyFM_DAI_EmbeddingInfo {
+    return {
+      provider: DyFM_AI_Provider.LocalAI,
+      model: model,
+    };
+  }
+
+  /** A mock mindig elérhető (nincs külső függőség). */
+  async testConnection(_issuer: string): Promise<boolean> {
+    return true;
+  }
+
+  // =========================================================================
+  // belső: determinisztikus vektor + cost-event + response-alak
+  // =========================================================================
+
+  /**
+   * Egy determinisztikus, l2-normalizált vektor a seed-ből. A SHA-256 hash bájtjait körkörösen
+   * használja a `dims` kitöltésére, [-1, 1) tartományra képzi, majd l2-normalizál (egységhossz a
+   * koszinuszhoz). Egy második hash-bájttal kever, hogy a hosszabb dimenziókon ne ismétlődjön a minta.
+   */
+  protected deterministicVector(seed: string): number[] {
+    const hash: Buffer = crypto.createHash('sha256').update(seed).digest();
+    const vector: number[] = [];
+
+    for (let i = 0; i < this.dims; i++) {
+      const byte: number = hash[i % hash.length];
+      const mix: number = hash[(i * 7 + 3) % hash.length];
+      const combined: number = (byte ^ mix) & 0xff;
+
+      vector.push((combined / 255) * 2 - 1);
+    }
+
+    return this.l2Normalize(vector);
+  }
+
+  /** L2-normalizálás (egységhossz). Nulla-vektor → változatlan (elkerüli a 0-osztást). */
+  protected l2Normalize(vector: number[]): number[] {
+    let sumSq: number = 0;
+
+    for (const value of vector) {
+      sumSq += value * value;
+    }
+    const norm: number = Math.sqrt(sumSq);
+
+    if (!norm) {
+      return vector;
+    }
+
+    return vector.map((value) => value / norm);
+  }
+
+  /** OpenAI-alakú válasz-objektum a vektorokból (a `fullResponse=true` ághoz). */
+  protected toResponse(vectors: number[][], model: string, texts: string[]): CreateEmbeddingResponse {
+    const tokens: number = this.estimateTokens(texts);
+
+    return {
+      object: 'list',
+      model: model,
+      data: vectors.map((embedding, index) => ({ object: 'embedding', embedding: embedding, index: index })),
+      usage: {
+        prompt_tokens: tokens,
+        total_tokens: tokens,
+      },
+    };
+  }
+
+  /** Cost-event emit (BFR-AM-007) fake tokennel (4 char ≈ 1 token), provider `'mock'`. */
+  protected emitMockCostEvent(
+    callType: 'embedding-single' | 'embedding-batch',
+    model: string,
+    texts: string[],
+    durationMs: number,
+    issuer: string,
+  ): void {
+    const tokens: number = this.estimateTokens(texts);
+
+    this.emitCostEvent({
+      callType: callType,
+      provider: this.costProvider,
+      model: model,
+      tokensUsed: {
+        input: tokens,
+        total: tokens,
+      },
+      durationMs: durationMs,
+      issuer: issuer,
+      timestamp: new Date(),
+      estimatedCostUsd: 0,
+    });
+  }
+
+  /** Becsült (fake) token-szám: 4 char ≈ 1 token. */
+  protected estimateTokens(texts: string[]): number {
+    let chars: number = 0;
+
+    for (const text of texts) {
+      chars += (text ?? '').length;
+    }
+
+    return Math.max(1, Math.ceil(chars / 4));
+  }
+}