@futdevpro/nts-dynamo 1.15.86 → 1.15.89

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

@@ -5,229 +5,229 @@ import { DyFM_AI_Provider, DyFM_AI_ProviderCapabilities, DyFM_AI_Config } from '
 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();
+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 {
+
+    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 ?? '' ]);
+
+    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 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();
+
+    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];
+
+    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);
+
+      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[] {
+
+    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;
-    }
+
+    for (const value of vector) {
+      sumSq += value * value;
+    }
     const norm: number = Math.sqrt(sumSq);
-
-    if (!norm) {
-      return vector;
+
+    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 {
+
+    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 {
+
+    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 {
+
+    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;
+
+    for (const text of texts) {
+      chars += (text ?? '').length;
     }
-
-    return Math.max(1, Math.ceil(chars / 4));
-  }
-}
+
+    return Math.max(1, Math.ceil(chars / 4));
+  }
+}

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

@@ -1,110 +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();
-    });
-  });
-});
+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();
+    });
+  });
+});