@futdevpro/fsm-dynamo 1.15.17 → 1.15.20

package/src/_modules/ai/_collections/ai-model-ref.util.ts

@@ -1,88 +1,88 @@
-import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
-
-/**
- * AI modell hivatkozas formatum: {provider}:{model}
- *
- * Peldak: "open-ai:gpt-4o", "anthropic:claude-3-5-sonnet-latest", "fdp-ai:fdp-base-1"
- * A provider resz a DyFM_AI_Provider enum erteke, a model resz a provider sajat modell azonositoja.
- */
-export class DyFM_AI_ModelRef_Util {
-  /** az elvlaszto karakter a provider es modell kozott */
-  private static readonly separator: string = ':';
-
-  /** az osszes ervenyes provider ertek gyorstarhely */
-  private static readonly validProviders: Set<string> = new Set(
-    Object.values(DyFM_AI_Provider)
-  );
-
-  /**
-   * Osszeallitas provider + model -bol
-   * @param provider - AI provider enum ertek
-   * @param model - provider-specifikus modell azonosito
-   */
-  static create(provider: DyFM_AI_Provider, model: string): string {
-    return `${provider}${DyFM_AI_ModelRef_Util.separator}${model}`;
-  }
-
-  /**
-   * Szetbontas provider + model -re
-   * @param modelRef - formatum: {provider}:{model}
-   */
-  static parse(modelRef: string): { provider: DyFM_AI_Provider; model: string } {
-    const separatorIndex: number = modelRef.indexOf(DyFM_AI_ModelRef_Util.separator);
-
-    if (separatorIndex < 0) {
-      throw new Error(`Ervenytelen modelRef formatum: "${modelRef}" -- hianyzik a "${DyFM_AI_ModelRef_Util.separator}" elvlaszto`);
-    }
-
-    const provider: string = modelRef.substring(0, separatorIndex);
-    const model: string = modelRef.substring(separatorIndex + 1);
-
-    if (!DyFM_AI_ModelRef_Util.validProviders.has(provider)) {
-      throw new Error(`Ismeretlen AI provider: "${provider}" a modelRef-ben: "${modelRef}"`);
-    }
-
-    if (!model) {
-      throw new Error(`Ures modell azonosito a modelRef-ben: "${modelRef}"`);
-    }
-
-    return { provider: provider as DyFM_AI_Provider, model: model };
-  }
-
-  /**
-   * Provider kinyerese a modelRef-bol
-   * @param modelRef - formatum: {provider}:{model}
-   */
-  static getProvider(modelRef: string): DyFM_AI_Provider {
-    return DyFM_AI_ModelRef_Util.parse(modelRef).provider;
-  }
-
-  /**
-   * Model kinyerese a modelRef-bol
-   * @param modelRef - formatum: {provider}:{model}
-   */
-  static getModel(modelRef: string): string {
-    return DyFM_AI_ModelRef_Util.parse(modelRef).model;
-  }
-
-  /**
-   * Validalas -- ellenorzi, hogy a modelRef megfelel-e a {provider}:{model} formatumnak
-   * @param modelRef - a vizsgalando string
-   */
-  static isValid(modelRef: string): boolean {
-    if (!modelRef) {
-      return false;
-    }
-
-    const separatorIndex: number = modelRef.indexOf(DyFM_AI_ModelRef_Util.separator);
-
-    if (separatorIndex < 0) {
-      return false;
-    }
-
-    const provider: string = modelRef.substring(0, separatorIndex);
-    const model: string = modelRef.substring(separatorIndex + 1);
-
-    return DyFM_AI_ModelRef_Util.validProviders.has(provider) && !!model;
-  }
-}
+import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
+
+/**
+ * AI modell hivatkozas formatum: {provider}:{model}
+ *
+ * Peldak: "open-ai:gpt-4o", "anthropic:claude-3-5-sonnet-latest", "fdp-ai:fdp-base-1"
+ * A provider resz a DyFM_AI_Provider enum erteke, a model resz a provider sajat modell azonositoja.
+ */
+export class DyFM_AI_ModelRef_Util {
+  /** az elvlaszto karakter a provider es modell kozott */
+  private static readonly separator: string = ':';
+
+  /** az osszes ervenyes provider ertek gyorstarhely */
+  private static readonly validProviders: Set<string> = new Set(
+    Object.values(DyFM_AI_Provider)
+  );
+
+  /**
+   * Osszeallitas provider + model -bol
+   * @param provider - AI provider enum ertek
+   * @param model - provider-specifikus modell azonosito
+   */
+  static create(provider: DyFM_AI_Provider, model: string): string {
+    return `${provider}${DyFM_AI_ModelRef_Util.separator}${model}`;
+  }
+
+  /**
+   * Szetbontas provider + model -re
+   * @param modelRef - formatum: {provider}:{model}
+   */
+  static parse(modelRef: string): { provider: DyFM_AI_Provider; model: string } {
+    const separatorIndex: number = modelRef.indexOf(DyFM_AI_ModelRef_Util.separator);
+
+    if (separatorIndex < 0) {
+      throw new Error(`Ervenytelen modelRef formatum: "${modelRef}" -- hianyzik a "${DyFM_AI_ModelRef_Util.separator}" elvlaszto`);
+    }
+
+    const provider: string = modelRef.substring(0, separatorIndex);
+    const model: string = modelRef.substring(separatorIndex + 1);
+
+    if (!DyFM_AI_ModelRef_Util.validProviders.has(provider)) {
+      throw new Error(`Ismeretlen AI provider: "${provider}" a modelRef-ben: "${modelRef}"`);
+    }
+
+    if (!model) {
+      throw new Error(`Ures modell azonosito a modelRef-ben: "${modelRef}"`);
+    }
+
+    return { provider: provider as DyFM_AI_Provider, model: model };
+  }
+
+  /**
+   * Provider kinyerese a modelRef-bol
+   * @param modelRef - formatum: {provider}:{model}
+   */
+  static getProvider(modelRef: string): DyFM_AI_Provider {
+    return DyFM_AI_ModelRef_Util.parse(modelRef).provider;
+  }
+
+  /**
+   * Model kinyerese a modelRef-bol
+   * @param modelRef - formatum: {provider}:{model}
+   */
+  static getModel(modelRef: string): string {
+    return DyFM_AI_ModelRef_Util.parse(modelRef).model;
+  }
+
+  /**
+   * Validalas -- ellenorzi, hogy a modelRef megfelel-e a {provider}:{model} formatumnak
+   * @param modelRef - a vizsgalando string
+   */
+  static isValid(modelRef: string): boolean {
+    if (!modelRef) {
+      return false;
+    }
+
+    const separatorIndex: number = modelRef.indexOf(DyFM_AI_ModelRef_Util.separator);
+
+    if (separatorIndex < 0) {
+      return false;
+    }
+
+    const provider: string = modelRef.substring(0, separatorIndex);
+    const model: string = modelRef.substring(separatorIndex + 1);
+
+    return DyFM_AI_ModelRef_Util.validProviders.has(provider) && !!model;
+  }
+}

package/src/_modules/ai/_collections/ai-model-registry.util.spec.ts

@@ -1,37 +1,37 @@
-import { DyFM_AI_ModelRegistry_Util } from './ai-model-registry.util';
-import { DyFM_OAI_Models } from '../_modules/open-ai/_collections/oai-models.const';
-import { DyFM_OAI_Model } from '../_modules/open-ai/_enums/oai-model.enum';
-
-describe('| DyFM_AI_ModelRegistry_Util', (): void => {
-
-  describe('| findModelInfo', (): void => {
-    it('| should find a known model by id', (): void => {
-      const info = DyFM_AI_ModelRegistry_Util.findModelInfo(DyFM_OAI_Models, DyFM_OAI_Model.gpt55);
-
-      expect(info).toBeTruthy();
-      expect(info?.id).toBe(DyFM_OAI_Model.gpt55);
-    });
-
-    it('| should return undefined for an unknown id', (): void => {
-      const info = DyFM_AI_ModelRegistry_Util.findModelInfo(DyFM_OAI_Models, 'no-such-model');
-
-      expect(info).toBeUndefined();
-    });
-  });
-
-  describe('| modelSupportsTools', (): void => {
-    it('| should return true for a tool-capable chat model', (): void => {
-      expect(DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.gpt55)).toBe(true);
-    });
-
-    it('| should return false for an embedding model', (): void => {
-      expect(
-        DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.textEmbedding_3Small)
-      ).toBe(false);
-    });
-
-    it('| should return false for an unknown id (no assumption of tool support)', (): void => {
-      expect(DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, 'no-such-model')).toBe(false);
-    });
-  });
-});
+import { DyFM_AI_ModelRegistry_Util } from './ai-model-registry.util';
+import { DyFM_OAI_Models } from '../_modules/open-ai/_collections/oai-models.const';
+import { DyFM_OAI_Model } from '../_modules/open-ai/_enums/oai-model.enum';
+
+describe('| DyFM_AI_ModelRegistry_Util', (): void => {
+
+  describe('| findModelInfo', (): void => {
+    it('| should find a known model by id', (): void => {
+      const info = DyFM_AI_ModelRegistry_Util.findModelInfo(DyFM_OAI_Models, DyFM_OAI_Model.gpt55);
+
+      expect(info).toBeTruthy();
+      expect(info?.id).toBe(DyFM_OAI_Model.gpt55);
+    });
+
+    it('| should return undefined for an unknown id', (): void => {
+      const info = DyFM_AI_ModelRegistry_Util.findModelInfo(DyFM_OAI_Models, 'no-such-model');
+
+      expect(info).toBeUndefined();
+    });
+  });
+
+  describe('| modelSupportsTools', (): void => {
+    it('| should return true for a tool-capable chat model', (): void => {
+      expect(DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.gpt55)).toBe(true);
+    });
+
+    it('| should return false for an embedding model', (): void => {
+      expect(
+        DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, DyFM_OAI_Model.textEmbedding_3Small)
+      ).toBe(false);
+    });
+
+    it('| should return false for an unknown id (no assumption of tool support)', (): void => {
+      expect(DyFM_AI_ModelRegistry_Util.modelSupportsTools(DyFM_OAI_Models, 'no-such-model')).toBe(false);
+    });
+  });
+});

package/src/_modules/ai/_collections/ai-model-registry.util.ts

@@ -1,30 +1,30 @@
-import { DyFM_AI_ModelInfo } from '../_models/ai-model-info.interface';
-
-/**
- * Lookups over a per-provider model registry (`DyFM_OAI_Models`, `DyFM_AAI_Models`, …).
- *
- * The registry array is passed IN — this keeps the agnostic `./ai` core free of
- * any provider-submodule dependency (the execution-layer service supplies its own
- * provider's registry). The lookup is by exact API model `id`.
- */
-export class DyFM_AI_ModelRegistry_Util {
-
-  /**
-   * A modell-descriptor megkeresese id alapjan a megadott registry-ben.
-   * @param models - a provider registry tomb (pl. DyFM_OAI_Models)
-   * @param id - pontos API modell-azonosito (pl. 'gpt-5.5')
-   */
-  static findModelInfo(models: DyFM_AI_ModelInfo[], id: string): DyFM_AI_ModelInfo | undefined {
-    return models.find((model: DyFM_AI_ModelInfo) => model.id === id);
-  }
-
-  /**
-   * Tamogatja-e a modell a function calling-ot (tool use)?
-   * Ismeretlen id eseten `false` (honesty — soha ne feltetelezzunk tool-kepesseget).
-   * @param models - a provider registry tomb
-   * @param id - pontos API modell-azonosito
-   */
-  static modelSupportsTools(models: DyFM_AI_ModelInfo[], id: string): boolean {
-    return DyFM_AI_ModelRegistry_Util.findModelInfo(models, id)?.capabilities?.functionCalling ?? false;
-  }
-}
+import { DyFM_AI_ModelInfo } from '../_models/ai-model-info.interface';
+
+/**
+ * Lookups over a per-provider model registry (`DyFM_OAI_Models`, `DyFM_AAI_Models`, …).
+ *
+ * The registry array is passed IN — this keeps the agnostic `./ai` core free of
+ * any provider-submodule dependency (the execution-layer service supplies its own
+ * provider's registry). The lookup is by exact API model `id`.
+ */
+export class DyFM_AI_ModelRegistry_Util {
+
+  /**
+   * A modell-descriptor megkeresese id alapjan a megadott registry-ben.
+   * @param models - a provider registry tomb (pl. DyFM_OAI_Models)
+   * @param id - pontos API modell-azonosito (pl. 'gpt-5.5')
+   */
+  static findModelInfo(models: DyFM_AI_ModelInfo[], id: string): DyFM_AI_ModelInfo | undefined {
+    return models.find((model: DyFM_AI_ModelInfo) => model.id === id);
+  }
+
+  /**
+   * Tamogatja-e a modell a function calling-ot (tool use)?
+   * Ismeretlen id eseten `false` (honesty — soha ne feltetelezzunk tool-kepesseget).
+   * @param models - a provider registry tomb
+   * @param id - pontos API modell-azonosito
+   */
+  static modelSupportsTools(models: DyFM_AI_ModelInfo[], id: string): boolean {
+    return DyFM_AI_ModelRegistry_Util.findModelInfo(models, id)?.capabilities?.functionCalling ?? false;
+  }
+}

package/src/_modules/ai/_enums/ai-message-role.enum.ts

@@ -1,7 +1,7 @@
-export enum DyFM_AI_MessageRole {
-  system = 'system',
-  user = 'user',
-  assistant = 'assistant',
-  /** Tool-result message (function calling). Provider translators map this to their native shape. */
-  tool = 'tool',
-}
+export enum DyFM_AI_MessageRole {
+  system = 'system',
+  user = 'user',
+  assistant = 'assistant',
+  /** Tool-result message (function calling). Provider translators map this to their native shape. */
+  tool = 'tool',
+}

package/src/_modules/ai/_enums/ai-model-type.enum.ts

@@ -1,7 +1,7 @@
-export enum DyFM_AI_ModelType {
-  LLM = 'llm',
-  Embedding = 'embedding',
-  Chat = 'chat',
-  Image = 'image',
-  Audio = 'audio',
-}
+export enum DyFM_AI_ModelType {
+  LLM = 'llm',
+  Embedding = 'embedding',
+  Chat = 'chat',
+  Image = 'image',
+  Audio = 'audio',
+}

package/src/_modules/ai/_enums/ai-provider.enum.ts

@@ -1,7 +1,7 @@
-export enum DyFM_AI_Provider {
-  OpenAI = 'open-ai',
-  Anthropic = 'anthropic',
-  Google = 'google',
-  LocalAI = 'local-ai',
-  FdpAI = 'fdp-ai',
-}
+export enum DyFM_AI_Provider {
+  OpenAI = 'open-ai',
+  Anthropic = 'anthropic',
+  Google = 'google',
+  LocalAI = 'local-ai',
+  FdpAI = 'fdp-ai',
+}

package/src/_modules/ai/_models/ai-call-settings.interface.ts

@@ -1,84 +1,84 @@
-/**
- * Agnostic LLM call settings — the provider-neutral tuning bag.
- *
- * The typed fields below are the common, broadly-supported knobs. The
- * `[key: string]: any` escape hatch carries provider/model-specific params
- * until they are first-classed.
- *
- * IMPORTANT — per-model variance (FR-048, reserved): NOT every model accepts
- * every field here, and sending an unsupported param can hard-fail the call
- * (e.g. Anthropic Opus 4.7+ rejects `temperature`/`topP`/`topK` with HTTP 400;
- * reasoning models take an extra `reasoningEffort`; pro models drop streaming).
- * This flat bag intentionally does NOT encode those constraints — the future
- * per-model settings system ({@link DyFM_AI_ModelSettingsSchema} on the model
- * registry + a reconciler in `DyNTS_AI_LLM_ServiceBase`) will validate, clamp,
- * and drop params against what each model actually accepts. Until then,
- * provider translators drop model-rejected params locally (see FR-047 Phase 4
- * Anthropic). Do not assume a field here is universally accepted.
- *
- * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
- *      `documentations/guidelines/development/ai-per-model-settings.md`
- */
-export class DyFM_AI_CallSettings {
-  systemPrompt?: string = '';
-  useModel?: string;
-  project?: string;
-  debugLog?: boolean;
-  
-  /**
-   * This parameter controls the randomness and creativity of the generated output.   
-   *   
-   * Lower values (e.g., 0.2) produce more focused, predictable results,   
-   * while higher values (e.g., 0.8) introduce more variation and unexpected outputs,   
-   * making the model more creative and exploratory.     
-   *   
-   * Adjust this setting to balance between creativity and consistency.  
-   */
-  temperature?: number = 0;
-  /**
-   * Defines the upper limit of tokens (words or parts of words)   
-   * the model can generate in a single response.   
-   *   
-   * The total token count includes both the input (prompt) and the output (response).   
-   *   
-   * You can allocate up to 4096 tokens per request, but be mindful of prompt length,   
-   * as it affects how many tokens remain for the response.
-   */
-  maxTokens?: number = 2000;
-  /**
-   * This parameter adjusts the diversity of the output using nucleus sampling,   
-   * where the model considers tokens based on cumulative probability.   
-   *   
-   * A value of 0.5 ensures that only the most likely half of all possible tokens   
-   * are considered, while increasing the value (up to 1)   
-   * allows for a broader range of token options, leading to more varied responses.
-   */
-  topP?: number = 0.75;
-  /**
-   * This setting penalizes tokens that have already appeared frequently in the generated text,   
-   * discouraging repetition and encouraging the model to introduce new content.    
-   *   
-   * Higher values result in less repetition, making the output more diverse.   
-   */
-  frequencyPenalty?: number = 0;
-  /**
-   * This parameter influences the model by penalizing tokens based on   
-   * their presence in the text so far.   
-   *   
-   * It encourages the introduction of new topics or ideas by reducing the likelihood of   
-   * generating tokens that have already appeared,   
-   * helping to keep the conversation or text more varied and engaging.
-   */
-  presencePenalty?: number = 0;
-
-  // Allow provider-specific fields
-  [key: string]: any;
-
-  constructor(
-    set?: DyFM_AI_CallSettings
-  ) {
-    if (set) {
-      Object.assign(this, set);
-    }
-  }
-}
+/**
+ * Agnostic LLM call settings — the provider-neutral tuning bag.
+ *
+ * The typed fields below are the common, broadly-supported knobs. The
+ * `[key: string]: any` escape hatch carries provider/model-specific params
+ * until they are first-classed.
+ *
+ * IMPORTANT — per-model variance (FR-048, reserved): NOT every model accepts
+ * every field here, and sending an unsupported param can hard-fail the call
+ * (e.g. Anthropic Opus 4.7+ rejects `temperature`/`topP`/`topK` with HTTP 400;
+ * reasoning models take an extra `reasoningEffort`; pro models drop streaming).
+ * This flat bag intentionally does NOT encode those constraints — the future
+ * per-model settings system ({@link DyFM_AI_ModelSettingsSchema} on the model
+ * registry + a reconciler in `DyNTS_AI_LLM_ServiceBase`) will validate, clamp,
+ * and drop params against what each model actually accepts. Until then,
+ * provider translators drop model-rejected params locally (see FR-047 Phase 4
+ * Anthropic). Do not assume a field here is universally accepted.
+ *
+ * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
+ *      `documentations/guidelines/development/ai-per-model-settings.md`
+ */
+export class DyFM_AI_CallSettings {
+  systemPrompt?: string = '';
+  useModel?: string;
+  project?: string;
+  debugLog?: boolean;
+  
+  /**
+   * This parameter controls the randomness and creativity of the generated output.   
+   *   
+   * Lower values (e.g., 0.2) produce more focused, predictable results,   
+   * while higher values (e.g., 0.8) introduce more variation and unexpected outputs,   
+   * making the model more creative and exploratory.     
+   *   
+   * Adjust this setting to balance between creativity and consistency.  
+   */
+  temperature?: number = 0;
+  /**
+   * Defines the upper limit of tokens (words or parts of words)   
+   * the model can generate in a single response.   
+   *   
+   * The total token count includes both the input (prompt) and the output (response).   
+   *   
+   * You can allocate up to 4096 tokens per request, but be mindful of prompt length,   
+   * as it affects how many tokens remain for the response.
+   */
+  maxTokens?: number = 2000;
+  /**
+   * This parameter adjusts the diversity of the output using nucleus sampling,   
+   * where the model considers tokens based on cumulative probability.   
+   *   
+   * A value of 0.5 ensures that only the most likely half of all possible tokens   
+   * are considered, while increasing the value (up to 1)   
+   * allows for a broader range of token options, leading to more varied responses.
+   */
+  topP?: number = 0.75;
+  /**
+   * This setting penalizes tokens that have already appeared frequently in the generated text,   
+   * discouraging repetition and encouraging the model to introduce new content.    
+   *   
+   * Higher values result in less repetition, making the output more diverse.   
+   */
+  frequencyPenalty?: number = 0;
+  /**
+   * This parameter influences the model by penalizing tokens based on   
+   * their presence in the text so far.   
+   *   
+   * It encourages the introduction of new topics or ideas by reducing the likelihood of   
+   * generating tokens that have already appeared,   
+   * helping to keep the conversation or text more varied and engaging.
+   */
+  presencePenalty?: number = 0;
+
+  // Allow provider-specific fields
+  [key: string]: any;
+
+  constructor(
+    set?: DyFM_AI_CallSettings
+  ) {
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}

package/src/_modules/ai/_models/ai-embedding-request.interface.ts

@@ -1,20 +1,20 @@
-/**
- * Generic embedding request structure
- * Used by all AI providers for embedding operations
- */
-export interface DyFM_AI_Embedding_Request {
-  text: string;
-  model: string;
-  issuer: string;
-  debugLog?: boolean;
-}
-
-/**
- * Batch embedding request for multiple texts
- */
-export interface DyFM_AI_Embedding_Batch_Request {
-  texts: string[];
-  model: string;
-  issuer: string;
-  debugLog?: boolean;
-}
+/**
+ * Generic embedding request structure
+ * Used by all AI providers for embedding operations
+ */
+export interface DyFM_AI_Embedding_Request {
+  text: string;
+  model: string;
+  issuer: string;
+  debugLog?: boolean;
+}
+
+/**
+ * Batch embedding request for multiple texts
+ */
+export interface DyFM_AI_Embedding_Batch_Request {
+  texts: string[];
+  model: string;
+  issuer: string;
+  debugLog?: boolean;
+}

package/src/_modules/ai/_models/ai-embedding-response.interface.ts

@@ -1,26 +1,26 @@
-/**
- * Generic embedding response structure
- * Used by all AI providers for embedding operations
- */
-export interface DyFM_AI_Embedding_Response {
-  embedding: number[];
-  model: string;
-  usage?: {
-    promptTokens: number;
-    totalTokens: number;
-  };
-  rawResponse?: any; // Provider-specific raw response
-}
-
-/**
- * Batch embedding response for multiple texts
- */
-export interface DyFM_AI_Embedding_Batch_Response {
-  embeddings: number[][];
-  model: string;
-  usage?: {
-    promptTokens: number;
-    totalTokens: number;
-  };
-  rawResponse?: any; // Provider-specific raw response
-}
+/**
+ * Generic embedding response structure
+ * Used by all AI providers for embedding operations
+ */
+export interface DyFM_AI_Embedding_Response {
+  embedding: number[];
+  model: string;
+  usage?: {
+    promptTokens: number;
+    totalTokens: number;
+  };
+  rawResponse?: any; // Provider-specific raw response
+}
+
+/**
+ * Batch embedding response for multiple texts
+ */
+export interface DyFM_AI_Embedding_Batch_Response {
+  embeddings: number[][];
+  model: string;
+  usage?: {
+    promptTokens: number;
+    totalTokens: number;
+  };
+  rawResponse?: any; // Provider-specific raw response
+}