@futdevpro/fsm-dynamo 1.20.9 → 1.20.10

package/src/_models/types/db-filter.type.ts

@@ -1,110 +0,0 @@
-
-/**
- * @example 
- * // by email: 
- * { email: email }
- * //
- * @example 
- * // or by id that is in list:
- * { userIds: { $in: this.userId } }
- * //
- * @example 
- * // or by userIds:
- * { userId: { $in: userIds } }
- * //
- * @example 
- * // or by number or Date that is Greater Than AND Less Than:
- * { points: { $gt: 2, $lt: 14 } }
- * // further tools (syntax matches with $gt):
- * $eq:  // Matches values that are EQual to a specified value.
- * $gte: // Matches values that are Greater Than OR Equal to a specified value.
- * $lte: // Matches values that are Less Than or Equal to a specified value.
- * $ne:  // Matches all values that are Not Equal to a specified value.
- * $nin: // Matches None of the values specified IN an array.
- * //
- * @returns {T} data: T
- */
-export type DyFM_DBFilter<T> = 
-  DyFM_DBFilterSimple<T> | 
-  DyFM_DBFilterOR<T> |
-  DyFM_DBFilterNOR<T>;
-
-/**
- * A simple filter for a DynamoDB query.
- */
-export type DyFM_DBFilterSimple<T> = {
-  [K in keyof T]?: T[K] | DyFM_DBFilterExpressions<T[K] | boolean>;
-} & {
-  [path: string]: any;
-};
-
-export type DyFM_DBFilterExpressions<T> = { 
-  /**
-   * Matches values that are includes the value; This works only when T[K] is an array!
-   */
-  $in?: T | T[] | any,
-  /**
-   * Matches values that are EQual to a specified value.
-   */
-  $eq?: T,
-  /**
-   * Matches values that are Greater Than a specified value.
-   */
-  $gt?: number | Date,
-  /**
-   * Matches values that are Greater Than OR Equal to a specified value.
-   */
-  $gte?: number | Date,
-  /**
-   * Matches values that are Less Than a specified value.
-   */
-  $lt?: number | Date,
-  /**
-   * Matches values that are Less Than or Equal to a specified value.
-   */
-  $lte?: number | Date,
-  /**
-   * Matches all values that are Not Equal to a specified value.
-   */
-  $ne?: any,
-  /**
-   * Matches None of the values specified IN an array.
-   */
-  $nin?: T | T[] | any,
-  /**
-   * Inverts the effect of a query expression and returns documents that do not match the query expression.
-   */
-  $not?: T | {
-    $regex?: RegExp | string,
-  },
-  /**
-   * Performs a regular expression on the field's value, and selects documents that match the regular expression.
-   */
-  $exists?: boolean,
-  /**
-   * Selects documents if a field is of the specified type.
-   */
-  $type?: string,
-};
-
-/**
- * Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.
- */
-export type DyFM_DBFilterNOR<T> = {
-  /**
-   * Joins query clauses with a logical NOR returns all documents that fail to match both clauses.
-   */
-  $nor: DyFM_DBFilterSimple<T>[];
-}
-
-/**
- * Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.
- */
-export type DyFM_DBFilterOR<T> = {
-  /**
-   * Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
-   */
-  $or: DyFM_DBFilterSimple<T>[];
-}
-
-

package/src/_models/types/db-sort.type.ts

@@ -1,5 +0,0 @@
-
-
-export type DyFM_DBSort<T> = {
-  [K in keyof T]?: 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
-}

package/src/_models/types/ds-filter.type.ts

@@ -1,68 +0,0 @@
-
-
-import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
-import { DyFM_RangeValue } from '../control-models/range-value.control-model';
-import { DyFM_DBFilterExpressions } from './db-filter.type';
-
-/**
- * A filter for a DynamoDB queries.
- * 
- * it should be the value, a range or an array of the searching values
- */
-export type DyFM_DSFilter<T> = {
-  [K in keyof T]?:  DyFM_DSFilterProperty<T, K>;
-};
-export type DyFM_DSFilterProperty<T, K extends keyof T> =  T[K] | 
-                                                            T[K][] | 
-                                                            DyFM_RangeValue<T[K]> | 
-                                                            DyFM_SpecialSearch<T[K]> | 
-                                                            DyFM_SpecialNestSearch |
-                                                            DyFM_DBFilterExpressions<T[K]>;
-
-export interface DyFM_SpecialSearch<T> {
-  isSpecialSearch: true;
-  searchValue: T | T[];
-  type: DyFM_SpecialSearch_Type;
-}
-
-/**
- * searches for a nested properties in the object
- */
-export interface DyFM_SpecialNestSearch {
-  isSpecialNestSearch: true;
-  nestedPropertySearches: DyFM_NestPropertySearch<any>[];
-}
-
-/**
- * can search for nested properties in arrays as well with the following syntax used in key:
- * nestKeys: [ 'arrayProperty', '*', 'nestedPropertySearch' ]
- */
-export interface DyFM_NestPropertySearch<T> {
-  nestKeys: string[];
-  valueType: DyFM_BasicProperty_Type;
-  search: T | 
-          T[] | 
-          DyFM_RangeValue<T> |
-          DyFM_SpecialSearch<T>;
-}
-
-export enum DyFM_SpecialSearch_Type {
-  /** 
-   * searches each word in the string, returns true if ANY word is found in ANY order
-   * */
-  stringListSearchAny = 'stringListSearchAny',
-  /** 
-   * searches each word in the string, returns true if ALL words are found in ANY order
-   * */
-  stringListSearch = 'stringListSearch',
-  /** 
-   * searches each word in the string, returns true if ALL words are found in the SAME order
-   * */
-  stringListSearchOrdered = 'stringListSearchOrdered',
-}
-
-
-
-
-
-

package/src/_models/types/ds-sort.type.ts

@@ -1,21 +0,0 @@
-import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
-
-
-
-export type DyFM_DSSort = DyFM_DSPropertySort | DyFM_DSNestedPropertySort;
-export interface DyFM_DSPropertySort {
-  key: string;
-  order: 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
-}
-
-export interface DyFM_DSNestedPropertySort {
-  isNestedPropertySort: true;
-  /** 
-   * the key to sort by   
-   * (can be an array that is used for sorting by nested properties)
-   */
-  nestKeys: string[];
-  valueType: DyFM_BasicProperty_Type;
-  order: 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
-}
-

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

@@ -1,88 +0,0 @@
-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 +0,0 @@
-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 +0,0 @@
-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 +0,0 @@
-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 +0,0 @@
-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 +0,0 @@
-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 +0,0 @@
-/**
- * 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`
- *      `fdp-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-config.interface.ts

@@ -1,14 +0,0 @@
-export interface DyFM_AI_Config {
-  apiKey?: string; // Made optional to match OpenAI structure
-  organization?: string;
-  project?: string;
-  baseURL?: string;
-  timeout?: number;
-  httpAgent?: any;
-  fetch?: any;
-  maxRetries?: number;
-  defaultHeaders?: any;
-  defaultQuery?: any;
-  dangerouslyAllowBrowser?: boolean;
-  [key: string]: any; // Allow provider-specific options
-}

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

@@ -1,20 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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
-}

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

@@ -1,24 +0,0 @@
-import { DyFM_AI_Message } from './ai-message.interface';
-import { DyFM_AI_CallSettings } from './ai-call-settings.interface';
-
-/**
- * Generic LLM request structure
- * Used by all AI providers for LLM operations
- */
-export interface DyFM_AI_LLM_Request {
-  messages: DyFM_AI_Message[];
-  settings?: DyFM_AI_CallSettings;
-  issuer: string;
-  debugLog?: boolean;
-}
-
-/**
- * Simple LLM request with system and user messages
- */
-export interface DyFM_AI_LLM_Simple_Request {
-  systemMessage: string;
-  userMessage: string;
-  settings?: DyFM_AI_CallSettings;
-  issuer: string;
-  debugLog?: boolean;
-}

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

@@ -1,30 +0,0 @@
-import { DyFM_AI_Message } from './ai-message.interface';
-import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
-
-/**
- * Generic LLM response structure
- * Used by all AI providers for LLM operations
- */
-export interface DyFM_AI_LLM_Response {
-  content: string;
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-  model?: string;
-  finishReason?: string;
-  /** Present when the model requested tool calls (function calling); normalized across providers. */
-  toolCalls?: DyFM_AI_ToolCall[];
-  /** Normalized stop reason (e.g. 'tool_use', 'stop', 'length'). */
-  stopReason?: string;
-  rawResponse?: any; // Provider-specific raw response
-}
-
-/**
- * Raw LLM response with full provider details
- */
-export interface DyFM_AI_LLM_Raw_Response extends DyFM_AI_LLM_Response {
-  messages: DyFM_AI_Message[];
-  rawResponse: any;
-}

package/src/_modules/ai/_models/ai-message.interface.ts

@@ -1,12 +0,0 @@
-import { DyFM_AI_MessageRole } from '../_enums/ai-message-role.enum';
-import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
-
-export interface DyFM_AI_Message {
-  role: DyFM_AI_MessageRole;
-  content: string;
-  /** Present on an assistant turn that requested tool calls (function calling). */
-  toolCalls?: DyFM_AI_ToolCall[];
-  /** Present on a `tool`-role message — which {@link DyFM_AI_ToolCall.id} this result answers. */
-  toolCallId?: string;
-}
-

package/src/_modules/ai/_models/ai-model-capabilities.interface.ts

@@ -1,35 +0,0 @@
-/**
- * Per-model capability flags.
- *
- * Where {@link DyFM_AI_ProviderCapabilities} describes what a PROVIDER can do
- * in aggregate, this describes what a single concrete MODEL supports. This is
- * the honest source of truth for feature-gating: e.g. an embedding model has
- * functionCalling=false, a reasoning chat model has functionCalling=true, a
- * local generic model may have functionCalling decided at runtime.
- */
-export interface DyFM_AI_ModelCapabilities {
-  /** Native function calling / tool use. The driver for the tool-calling feature. */
-  functionCalling: boolean;
-  /** Image input (vision). */
-  vision: boolean;
-  /** Streaming responses. */
-  streaming: boolean;
-  /** Structured output / JSON mode (OpenAI structured outputs, Gemini responseSchema, etc.). */
-  jsonMode: boolean;
-  /** Audio input (speech-to-text / audio understanding). */
-  audioInput: boolean;
-  /** Audio output (text-to-speech / speech generation). */
-  audioOutput: boolean;
-  /** Image generation (the model produces images). */
-  imageGeneration: boolean;
-  /** Embedding generation (vector output). */
-  embeddings: boolean;
-  /**
-   * Can generate adult / uncensored / NSFW content (no content-policy refusal on
-   * mature themes). Mainstream cloud models (OpenAI, Anthropic, Google) are filtered
-   * → false. Uncensored / local models may set true. Used for content-routing and
-   * age-gating (e.g. Adventor mature mode). For generic local models this is
-   * model-dependent — confirm per loaded model rather than assume.
-   */
-  adultContent: boolean;
-}