@futdevpro/nts-dynamo 1.15.57 → 1.15.58

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

@@ -0,0 +1,115 @@
+import { CreateEmbeddingResponse } from 'openai/resources';
+import { DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
+
+import {
+  DyNTS_AI_Embedding_MockService,
+  DyNTS_AI_MOCK_EMBEDDING_DIMS,
+} from './ai-embedding-mock.service';
+import { DyNTS_AI_CostEvent } from '../_models/interfaces/dynts-ai-cost-event.interface';
+
+describe('| DyNTS_AI_Embedding_MockService', () => {
+
+  const issuer: string = 'test-issuer';
+
+  describe('| determinism', () => {
+    it('| should return the same vector for the same (model, text)', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      const first: number[][] = (await service.createEmbeddings({ texts: ['hello'], model: 'm', issuer: issuer })) as number[][];
+      const second: number[][] = (await service.createEmbeddings({ texts: ['hello'], model: 'm', issuer: issuer })) as number[][];
+      expect(first[0]).toEqual(second[0]);
+    });
+
+    it('| should return different vectors for different texts', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      const result: number[][] = (await service.createEmbeddings({ texts: ['hello', 'world'], model: 'm', issuer: issuer })) as number[][];
+      expect(result[0]).not.toEqual(result[1]);
+    });
+
+    it('| should return different vectors for different models (re-embed scenario)', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      const a: number[][] = (await service.createEmbeddings({ texts: ['hello'], model: 'model-a', issuer: issuer })) as number[][];
+      const b: number[][] = (await service.createEmbeddings({ texts: ['hello'], model: 'model-b', issuer: issuer })) as number[][];
+      expect(a[0]).not.toEqual(b[0]);
+    });
+  });
+
+  describe('| dimensions', () => {
+    it('| should default to DyNTS_AI_MOCK_EMBEDDING_DIMS', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      const result: number[][] = (await service.createEmbeddings({ texts: ['x'], model: 'm', issuer: issuer })) as number[][];
+      expect(result[0].length).toBe(DyNTS_AI_MOCK_EMBEDDING_DIMS);
+    });
+
+    it('| should honour a configured dims', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService({ dims: 16 });
+      const result: number[][] = (await service.createEmbeddings({ texts: ['x'], model: 'm', issuer: issuer })) as number[][];
+      expect(result[0].length).toBe(16);
+    });
+
+    it('| should produce an l2-normalized vector (unit length)', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService({ dims: 32 });
+      const result: number[][] = (await service.createEmbeddings({ texts: ['vector'], model: 'm', issuer: issuer })) as number[][];
+      const norm: number = Math.sqrt(result[0].reduce((sum: number, v: number) => sum + v * v, 0));
+      expect(norm).toBeCloseTo(1, 6);
+    });
+  });
+
+  describe('| createEmbedding (single)', () => {
+    it('| should match the batch vector for the same text', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      const single: number[] = (await service.createEmbedding({ text: 'hi', model: 'm', issuer: issuer })) as number[];
+      const batch: number[][] = (await service.createEmbeddings({ texts: ['hi'], model: 'm', issuer: issuer })) as number[][];
+      expect(single).toEqual(batch[0]);
+    });
+
+    it('| should return a full OpenAI-shaped response when fullResponse is true', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService({ dims: 8 });
+      const response: CreateEmbeddingResponse = (await service.createEmbedding({
+        text: 'hi',
+        model: 'm',
+        fullResponse: true,
+        issuer: issuer,
+      })) as CreateEmbeddingResponse;
+      expect(response.object).toBe('list');
+      expect(response.data[0].embedding.length).toBe(8);
+      expect(response.usage.total_tokens).toBeGreaterThan(0);
+    });
+  });
+
+  describe('| cost-event', () => {
+    it('| should emit an embedding-batch cost-event with provider mock', async () => {
+      const events: DyNTS_AI_CostEvent[] = [];
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService({
+        onCostEvent: (event: DyNTS_AI_CostEvent) => events.push(event),
+      });
+      await service.createEmbeddings({ texts: ['abcd', 'efgh'], model: 'm', issuer: issuer });
+      expect(events.length).toBe(1);
+      expect(events[0].callType).toBe('embedding-batch');
+      expect(events[0].provider).toBe('mock');
+      expect(events[0].estimatedCostUsd).toBe(0);
+      expect(events[0].tokensUsed.input).toBeGreaterThan(0);
+    });
+
+    it('| should emit an embedding-single cost-event', async () => {
+      const events: DyNTS_AI_CostEvent[] = [];
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService({
+        onCostEvent: (event: DyNTS_AI_CostEvent) => events.push(event),
+      });
+      await service.createEmbedding({ text: 'hi', model: 'm', issuer: issuer });
+      expect(events[0].callType).toBe('embedding-single');
+    });
+  });
+
+  describe('| provider info + availability', () => {
+    it('| should report the LocalAI provider', () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      expect(service.aiProvider).toBe(DyFM_AI_Provider.LocalAI);
+      expect(service.getEmbeddingInfo('m')).toEqual({ provider: DyFM_AI_Provider.LocalAI, model: 'm' });
+    });
+
+    it('| should always be available', async () => {
+      const service: DyNTS_AI_Embedding_MockService = new DyNTS_AI_Embedding_MockService();
+      expect(await service.testConnection(issuer)).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,219 @@
+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_Embedding_ServiceBase } from './ai-embedding.service-base';
+import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
+
+/** 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));
+  }
+}

package/src/_modules/ai/_services/ai-embedding-provider.registry.spec.ts

@@ -0,0 +1,110 @@
+import { DyNTS_AI_EmbeddingProvider_Registry } from './ai-embedding-provider.registry';
+import { DyNTS_LMStudio_Embedding_ControlService } from './lmstudio-embedding.control-service';
+import { DyNTS_AI_Embedding_MockService } from './ai-embedding-mock.service';
+import { DyNTS_OAI_Embedding_ControlService } from '../_modules/open-ai/_services/oai-embedding.control-service';
+
+describe('| DyNTS_AI_EmbeddingProvider_Registry', () => {
+
+  /** Az env-mező visszaállításához (a normalizeKey env-feloldás-ágához). */
+  let savedProviderEnv: string | undefined;
+  let savedBaseUrlEnv: string | undefined;
+
+  beforeEach(() => {
+    savedProviderEnv = process.env.AI_EMBEDDING_PROVIDER;
+    savedBaseUrlEnv = process.env.LMSTUDIO_BASE_URL;
+    delete process.env.AI_EMBEDDING_PROVIDER;
+    delete process.env.LMSTUDIO_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedProviderEnv === undefined) {
+      delete process.env.AI_EMBEDDING_PROVIDER;
+    } else {
+      process.env.AI_EMBEDDING_PROVIDER = savedProviderEnv;
+    }
+    if (savedBaseUrlEnv === undefined) {
+      delete process.env.LMSTUDIO_BASE_URL;
+    } else {
+      process.env.LMSTUDIO_BASE_URL = savedBaseUrlEnv;
+    }
+  });
+
+  describe('| normalizeKey', () => {
+    it('| should resolve openai aliases', () => {
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('openai')).toBe('openai');
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('OpenAI')).toBe('openai');
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('open-ai')).toBe('openai');
+    });
+
+    it('| should resolve lmstudio aliases', () => {
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('lmstudio')).toBe('lmstudio');
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('lm-studio')).toBe('lmstudio');
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('local-ai')).toBe('lmstudio');
+    });
+
+    it('| should resolve mock aliases', () => {
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('mock')).toBe('mock');
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('test')).toBe('mock');
+    });
+
+    it('| should default to openai when no provider and no env', () => {
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey()).toBe('openai');
+    });
+
+    it('| should fall back to the AI_EMBEDDING_PROVIDER env var', () => {
+      process.env.AI_EMBEDDING_PROVIDER = 'mock';
+      expect(DyNTS_AI_EmbeddingProvider_Registry.normalizeKey()).toBe('mock');
+    });
+
+    it('| should throw on an unknown provider', () => {
+      expect(() => DyNTS_AI_EmbeddingProvider_Registry.normalizeKey('gemini')).toThrow();
+    });
+  });
+
+  describe('| resolve', () => {
+    it('| should resolve the openai provider to DyNTS_OAI_Embedding_ControlService', () => {
+      const service = DyNTS_AI_EmbeddingProvider_Registry.resolve({
+        provider: 'openai',
+        openAiSettings: { config: { apiKey: 'test-key' } },
+      });
+      expect(service).toBeInstanceOf(DyNTS_OAI_Embedding_ControlService);
+    });
+
+    it('| should resolve the lmstudio provider to DyNTS_LMStudio_Embedding_ControlService', () => {
+      const service = DyNTS_AI_EmbeddingProvider_Registry.resolve({
+        provider: 'lmstudio',
+        lmStudioSettings: { baseUrl: 'http://localhost:1234/v1' },
+      });
+      expect(service).toBeInstanceOf(DyNTS_LMStudio_Embedding_ControlService);
+    });
+
+    it('| should resolve the lmstudio baseUrl from the LMSTUDIO_BASE_URL env var', () => {
+      process.env.LMSTUDIO_BASE_URL = 'http://localhost:5678/v1';
+      const service = DyNTS_AI_EmbeddingProvider_Registry.resolve({ provider: 'lmstudio' });
+      expect(service).toBeInstanceOf(DyNTS_LMStudio_Embedding_ControlService);
+    });
+
+    it('| should throw if lmstudio is selected without a baseUrl', () => {
+      expect(() => DyNTS_AI_EmbeddingProvider_Registry.resolve({ provider: 'lmstudio' })).toThrow();
+    });
+
+    it('| should resolve the mock provider to DyNTS_AI_Embedding_MockService', () => {
+      const service = DyNTS_AI_EmbeddingProvider_Registry.resolve({ provider: 'mock' });
+      expect(service).toBeInstanceOf(DyNTS_AI_Embedding_MockService);
+    });
+
+    it('| should pass the cost-event sink through to the mock provider', async () => {
+      const events: string[] = [];
+      const service = DyNTS_AI_EmbeddingProvider_Registry.resolve({
+        provider: 'mock',
+        onCostEvent: (event) => events.push(event.provider),
+      });
+      await service.createEmbeddings({ texts: ['x'], model: 'm', issuer: 'test' });
+      expect(events).toEqual(['mock']);
+    });
+
+    it('| should throw on an unknown provider in resolve', () => {
+      expect(() => DyNTS_AI_EmbeddingProvider_Registry.resolve({ provider: 'cohere' })).toThrow();
+    });
+  });
+});

package/src/_modules/ai/_services/ai-embedding-provider.registry.ts

@@ -0,0 +1,110 @@
+import { DyFM_OAI_Settings } from '@futdevpro/fsm-dynamo/ai/open-ai';
+
+import { DyNTS_AI_Embedding_ServiceBase } from './ai-embedding.service-base';
+import { DyNTS_OAI_Embedding_ControlService } from '../_modules/open-ai/_services/oai-embedding.control-service';
+import { DyNTS_LMStudio_Embedding_ControlService, DyNTS_LMStudio_Embedding_Settings } from './lmstudio-embedding.control-service';
+import { DyNTS_AI_Embedding_MockService, DyNTS_AI_Embedding_MockSettings } from './ai-embedding-mock.service';
+import { DyNTS_AI_CostEventCallback } from '../_models/interfaces/dynts-ai-cost-event-callback.interface';
+
+/**
+ * Az embedding-provider kulcsa (BFR-AM-002). String-union, NEM enum (a cost-event provider-stringekkel
+ * konzisztens): `'openai'` (SDK reuse), `'lmstudio'` (lokális OpenAI-kompatibilis HTTP), `'mock'`
+ * (determinisztikus test-double). Az env-feloldás kis-/nagybetűt és a `lm-studio` alias-t is elfogad.
+ */
+export type DyNTS_AI_EmbeddingProviderKey = 'openai' | 'lmstudio' | 'mock';
+
+/**
+ * A provider-feloldás opciói. A `provider` explicit kulcsot ad; ha hiányzik, az env-ből oldjuk fel
+ * (`AI_EMBEDDING_PROVIDER`, default `openai`). A többi mező a megfelelő provider config-ját adja át.
+ */
+export interface DyNTS_AI_EmbeddingResolveOptions {
+  /** Explicit provider-kulcs; ha hiányzik → env-feloldás. */
+  provider?: DyNTS_AI_EmbeddingProviderKey | string;
+  /** Per-call cost-event sink (FR-002 / BFR-AM-007) — mind a 3 providernek átadva. */
+  onCostEvent?: DyNTS_AI_CostEventCallback;
+  /** OpenAI-specifikus config (apiKey/org/project/defaultSettings) — `openai` providerhez. */
+  openAiSettings?: DyFM_OAI_Settings;
+  /** LM Studio config (baseUrl/apiKey) — `lmstudio` providerhez; baseUrl hiány → env (`LMSTUDIO_BASE_URL`). */
+  lmStudioSettings?: Partial<DyNTS_LMStudio_Embedding_Settings>;
+  /** Mock config (dims) — `mock` providerhez. */
+  mockSettings?: DyNTS_AI_Embedding_MockSettings;
+}
+
+/**
+ * `DyNTS_AI_EmbeddingProvider_Registry` (BFR-AM-002) — provider-dispatch resolver. A provider-kulcs
+ * (`openai` | `lmstudio` | `mock`) alapján a megfelelő `DyNTS_AI_Embedding_ServiceBase` példányt adja
+ * vissza, így a hívók egységes embedding-felületet látnak a konkrét provider-impl mögött (a FAM
+ * `FAM_Embedding_ControlService.buildProvider` dispatch-ét emeli bedrock-szintre, generikusan).
+ *
+ * Static util (nincs állapota): minden hívás friss példányt épít (env/secret a hívás-időpontban
+ * érvényes — memory: `dynts_dataservice_eager_resolve`-konzisztens, nincs élő singleton-állapot).
+ */
+export class DyNTS_AI_EmbeddingProvider_Registry {
+
+  /**
+   * A megadott (vagy env-ből feloldott) provider-kulcs alapján egy embedding-service példányt épít.
+   * - `openai` → `DyNTS_OAI_Embedding_ControlService` (SDK reuse, cost-event sink-kel),
+   * - `lmstudio` → `DyNTS_LMStudio_Embedding_ControlService` (HTTP; baseUrl a config vagy env),
+   * - `mock` → `DyNTS_AI_Embedding_MockService` (determinisztikus),
+   * - ismeretlen → `Error` (provider nincs konfigurálva — nem néma).
+   */
+  static resolve(options?: DyNTS_AI_EmbeddingResolveOptions): DyNTS_AI_Embedding_ServiceBase {
+    const key: DyNTS_AI_EmbeddingProviderKey = DyNTS_AI_EmbeddingProvider_Registry.normalizeKey(options?.provider);
+    const onCostEvent: DyNTS_AI_CostEventCallback | undefined = options?.onCostEvent;
+
+    switch (key) {
+      case 'openai':
+        return new DyNTS_OAI_Embedding_ControlService({
+          ...(options?.openAiSettings ?? {}),
+          onCostEvent: onCostEvent,
+        });
+      case 'lmstudio': {
+        const baseUrl: string | undefined = options?.lmStudioSettings?.baseUrl ?? process.env.LMSTUDIO_BASE_URL;
+        if (!baseUrl) {
+          throw new Error(
+            'DyNTS_AI_EmbeddingProvider_Registry: the lmstudio provider was selected but no baseUrl '
+            + 'was provided (set lmStudioSettings.baseUrl or the LMSTUDIO_BASE_URL env var).',
+          );
+        }
+        return new DyNTS_LMStudio_Embedding_ControlService({
+          baseUrl: baseUrl,
+          apiKey: options?.lmStudioSettings?.apiKey ?? process.env.LMSTUDIO_API_KEY,
+          onCostEvent: onCostEvent,
+        });
+      }
+      case 'mock':
+        return new DyNTS_AI_Embedding_MockService({
+          ...(options?.mockSettings ?? {}),
+          onCostEvent: onCostEvent,
+        });
+    }
+  }
+
+  /**
+   * A provider-kulcs normalizálása: kis-/nagybetű-független, a `lm-studio` / `local-ai` alias-t
+   * `lmstudio`-ra képzi. Hiány → env (`AI_EMBEDDING_PROVIDER`) → default `openai`. Ismeretlen → `Error`.
+   */
+  static normalizeKey(provider?: string): DyNTS_AI_EmbeddingProviderKey {
+    const raw: string = (provider ?? process.env.AI_EMBEDDING_PROVIDER ?? 'openai').trim().toLowerCase();
+    switch (raw) {
+      case 'openai':
+      case 'open-ai':
+      case 'oai':
+        return 'openai';
+      case 'lmstudio':
+      case 'lm-studio':
+      case 'local-ai':
+      case 'localai':
+        return 'lmstudio';
+      case 'mock':
+      case 'fake':
+      case 'test':
+        return 'mock';
+      default:
+        throw new Error(
+          `DyNTS_AI_EmbeddingProvider_Registry: unknown embedding provider '${raw}'. `
+          + `Available: 'openai' | 'lmstudio' | 'mock'.`,
+        );
+    }
+  }
+}