@futdevpro/nts-dynamo 1.15.56 → 1.15.58

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'.`,
+        );
+    }
+  }
+}

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

@@ -1,98 +1,98 @@
-
-import { DyNTS_AI_Embedding_ServiceBase } from './ai-embedding.service-base';
-import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
-
-class TestEmbeddingService extends DyNTS_AI_Embedding_ServiceBase {
-  readonly aiProvider: any = {} as any;
-  readonly capabilities: any = {} as any;
-  setup = (config: any): void => {};
-  testConnection = async (issuer: string): Promise<boolean> => true;
-  createEmbedding = async (set: { text: string; model: string; fullResponse?: boolean; issuer: string }): Promise<number[] | any> => {
-    return [0.1, 0.2, 0.3];
-  };
-
-  createEmbeddings = async (set: { texts: string[]; model: string; fullResponse?: boolean; issuer: string }): Promise<number[][] | any> => {
-    return [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]];
-  };
-
-  getEmbeddingInfo = (model: string): DyFM_DAI_EmbeddingInfo => {
-    return {
-      model: model,
-    } as any;
-  };
-
-  static getInstance(): TestEmbeddingService {
-    return TestEmbeddingService.getSingletonInstance();
-  }
-}
-
-describe('| DyNTS_AI_Embedding_ServiceBase', () => {
-  let service: TestEmbeddingService;
-
-  beforeEach(() => {
-    service = TestEmbeddingService.getInstance();
-  });
-
-  it('| should be a singleton instance', () => {
-    const instance1 = TestEmbeddingService.getInstance();
-    const instance2 = TestEmbeddingService.getInstance();
-
-    expect(instance1).toBe(instance2);
-    expect(instance1).toBeInstanceOf(TestEmbeddingService);
-  });
-
-  describe('| createEmbedding', () => {
-    it('| should create embedding for single text', async () => {
-      const result = await service.createEmbedding({
-        text: 'Test text',
-        model: 'test-model',
-        issuer: 'issuer-123',
-      });
-
-      expect(result).toEqual([0.1, 0.2, 0.3]);
-    });
-
-    it('| should accept fullResponse parameter', async () => {
-      const result = await service.createEmbedding({
-        text: 'Test text',
-        model: 'test-model',
-        fullResponse: true,
-        issuer: 'issuer-123',
-      });
-
-      expect(result).toBeDefined();
-    });
-  });
-
-  describe('| createEmbeddings', () => {
-    it('| should create embeddings for multiple texts', async () => {
-      const result = await service.createEmbeddings({
-        texts: ['Text 1', 'Text 2'],
-        model: 'test-model',
-        issuer: 'issuer-123',
-      });
-
-      expect(result).toEqual([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]);
-    });
-
-    it('| should accept fullResponse parameter', async () => {
-      const result = await service.createEmbeddings({
-        texts: ['Text 1'],
-        model: 'test-model',
-        fullResponse: true,
-        issuer: 'issuer-123',
-      });
-
-      expect(result).toBeDefined();
-    });
-  });
-
-  describe('| getEmbeddingInfo', () => {
-    it('| should return embedding info for model', () => {
-      const result = service.getEmbeddingInfo('test-model');
-
-      expect(result.model).toBe('test-model');
-    });
-  });
-});
-
+
+import { DyNTS_AI_Embedding_ServiceBase } from './ai-embedding.service-base';
+import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
+
+class TestEmbeddingService extends DyNTS_AI_Embedding_ServiceBase {
+  readonly aiProvider: any = {} as any;
+  readonly capabilities: any = {} as any;
+  setup = (config: any): void => {};
+  testConnection = async (issuer: string): Promise<boolean> => true;
+  createEmbedding = async (set: { text: string; model: string; fullResponse?: boolean; issuer: string }): Promise<number[] | any> => {
+    return [0.1, 0.2, 0.3];
+  };
+
+  createEmbeddings = async (set: { texts: string[]; model: string; fullResponse?: boolean; issuer: string }): Promise<number[][] | any> => {
+    return [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]];
+  };
+
+  getEmbeddingInfo = (model: string): DyFM_DAI_EmbeddingInfo => {
+    return {
+      model: model,
+    } as any;
+  };
+
+  static getInstance(): TestEmbeddingService {
+    return TestEmbeddingService.getSingletonInstance();
+  }
+}
+
+describe('| DyNTS_AI_Embedding_ServiceBase', () => {
+  let service: TestEmbeddingService;
+
+  beforeEach(() => {
+    service = TestEmbeddingService.getInstance();
+  });
+
+  it('| should be a singleton instance', () => {
+    const instance1 = TestEmbeddingService.getInstance();
+    const instance2 = TestEmbeddingService.getInstance();
+
+    expect(instance1).toBe(instance2);
+    expect(instance1).toBeInstanceOf(TestEmbeddingService);
+  });
+
+  describe('| createEmbedding', () => {
+    it('| should create embedding for single text', async () => {
+      const result = await service.createEmbedding({
+        text: 'Test text',
+        model: 'test-model',
+        issuer: 'issuer-123',
+      });
+
+      expect(result).toEqual([0.1, 0.2, 0.3]);
+    });
+
+    it('| should accept fullResponse parameter', async () => {
+      const result = await service.createEmbedding({
+        text: 'Test text',
+        model: 'test-model',
+        fullResponse: true,
+        issuer: 'issuer-123',
+      });
+
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('| createEmbeddings', () => {
+    it('| should create embeddings for multiple texts', async () => {
+      const result = await service.createEmbeddings({
+        texts: ['Text 1', 'Text 2'],
+        model: 'test-model',
+        issuer: 'issuer-123',
+      });
+
+      expect(result).toEqual([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]);
+    });
+
+    it('| should accept fullResponse parameter', async () => {
+      const result = await service.createEmbeddings({
+        texts: ['Text 1'],
+        model: 'test-model',
+        fullResponse: true,
+        issuer: 'issuer-123',
+      });
+
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('| getEmbeddingInfo', () => {
+    it('| should return embedding info for model', () => {
+      const result = service.getEmbeddingInfo('test-model');
+
+      expect(result.model).toBe('test-model');
+    });
+  });
+});
+

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

@@ -1,48 +1,48 @@
-import { CreateEmbeddingResponse } from 'openai/resources';
-import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
-import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
-
-/**
- * Abstract base class for embedding services
- * Defines the interface for AI providers that support embeddings
- */
-export abstract class DyNTS_AI_Embedding_ServiceBase extends DyNTS_AI_Provider_ServiceBase {
-  /**
-   * Create an embedding for a single text
-   * @param text - The text to embed
-   * @param model - The embedding model to use
-   * @param issuer - The issuer making the request
-   * @returns Promise<number[]> - The embedding vector
-   */
-  abstract createEmbedding(
-    set: {
-      text: string;
-      model: string;
-      fullResponse?: boolean;
-      issuer: string;
-    }
-  ): Promise<number[] | CreateEmbeddingResponse>;
-  
-  /**
-   * Create embeddings for multiple texts
-   * @param texts - Array of texts to embed
-   * @param model - The embedding model to use
-   * @param issuer - The issuer making the request
-   * @returns Promise<number[][]> - Array of embedding vectors
-   */
-  abstract createEmbeddings(
-    set: {
-      texts: string[];
-      model: string;
-      fullResponse?: boolean;
-      issuer: string;
-    }
-  ): Promise<number[][] | CreateEmbeddingResponse>;
-  
-  /**
-   * Get embedding information for a model
-   * @param model - The model name
-   * @returns DyFM_DAI_EmbeddingInfo - Information about the model
-   */
-  abstract getEmbeddingInfo(model: string): DyFM_DAI_EmbeddingInfo;
-}
+import { CreateEmbeddingResponse } from 'openai/resources';
+import { DyNTS_AI_Provider_ServiceBase } from './ai-provider.service-base';
+import { DyFM_DAI_EmbeddingInfo } from '@futdevpro/fsm-dynamo/ai/document-ai';
+
+/**
+ * Abstract base class for embedding services
+ * Defines the interface for AI providers that support embeddings
+ */
+export abstract class DyNTS_AI_Embedding_ServiceBase extends DyNTS_AI_Provider_ServiceBase {
+  /**
+   * Create an embedding for a single text
+   * @param text - The text to embed
+   * @param model - The embedding model to use
+   * @param issuer - The issuer making the request
+   * @returns Promise<number[]> - The embedding vector
+   */
+  abstract createEmbedding(
+    set: {
+      text: string;
+      model: string;
+      fullResponse?: boolean;
+      issuer: string;
+    }
+  ): Promise<number[] | CreateEmbeddingResponse>;
+  
+  /**
+   * Create embeddings for multiple texts
+   * @param texts - Array of texts to embed
+   * @param model - The embedding model to use
+   * @param issuer - The issuer making the request
+   * @returns Promise<number[][]> - Array of embedding vectors
+   */
+  abstract createEmbeddings(
+    set: {
+      texts: string[];
+      model: string;
+      fullResponse?: boolean;
+      issuer: string;
+    }
+  ): Promise<number[][] | CreateEmbeddingResponse>;
+  
+  /**
+   * Get embedding information for a model
+   * @param model - The model name
+   * @returns DyFM_DAI_EmbeddingInfo - Information about the model
+   */
+  abstract getEmbeddingInfo(model: string): DyFM_DAI_EmbeddingInfo;
+}