@futdevpro/nts-dynamo 1.15.157 → 1.15.163

package/src/_modules/discord-bot/index.ts

@@ -1,36 +0,0 @@
-
-
-
-
-/* try {
-  require.resolve('discord.js');
-} catch (error) {
-  console.log(
-    '❌ Discord.js package not found, please install it with: pnpm add discord.js'
-  );
-} */
-
-//
-// Discord Bot module
-//
-// This module is created to simplify the usage of Discord Bot
-// It creates universal solutions for the most common use cases
-//
-
-
-// COLLECTIONS
-export * from './_collections/dibo-default-commands.const';
-export * from './_collections/dibo-global-settings.conts';
-export * from './_collections/dibo-operations.util';
-
-// MODELS
-export * from './_models/dibo-command.interface';
-export * from './_models/dibo-last-mention-date.inteface';
-export * from './_models/dibo-last-message-date.interface';
-export * from './_models/dibo-global-settings.interface';
-
-// SERVICES
-export * from './_services/dibo-commands.control-service';
-export * from './_services/dibo-io.control-service';
-export * from './_services/dibo-main.control-service';
-export * from './_services/dibo-routines.control-service';

package/src/_modules/local-vector-search/_enums/lvs-search-mode.enum.ts

@@ -1,35 +0,0 @@
-/**
- * Vektor keresési mód enum
- * Meghatározza, hogy milyen metrikát használunk a vektorok közötti hasonlóság számításához
- */
-export enum LVS_Search_Mode {
-  /**
-   * Cosine similarity (koszinusz hasonlóság)
-   * 0 és 1 közötti érték, ahol 1 a legnagyobb hasonlóság
-   * Eredmények csökkenő sorrendben (legnagyobb hasonlóság először)
-   */
-  cosineSimilarity = 'cosine-similarity',
-  /**
-   * L2 distance (Euklideszi távolság)
-   * 0 vagy pozitív érték, ahol 0 a legkisebb távolság (legnagyobb hasonlóság)
-   * Eredmények növekvő sorrendben (legkisebb távolság először)
-   */
-  l2Distance = 'l2-distance',
-  /**
-   * Hybrid search: cosine similarity (vektor-fele) + BM25 (text-fele) score-merge.
-   *
-   * Hasznalat:
-   *  - `searchMode: LVS_Search_Mode.hybrid`
-   *  - `textSearchKey: keyof T` — KOTELEZO; melyik string property-n fut a BM25
-   *  - `hybridWeight?: { vector: number; text: number }` — default { vector: 0.5, text: 0.5 }
-   *
-   * BM25 min-max normalizalva [0,1] a candidate-szettre (cosine mar 0..1), igy
-   * a `weight` direkt linearis kombinacio. Ha minden BM25 score 0 (egyetlen
-   * query term sem matchel), a hybrid effektivan cosine-only-re degradalodik.
-   *
-   * L2+hybrid kombinacio NEM tamogatott — a hybrid mindig cosine-alapu
-   * vector-half-fel mukodik.
-   */
-  hybrid = 'hybrid',
-}
-

package/src/_modules/local-vector-search/_models/data-models/lvs-vector-persist.data-model.ts

@@ -1,60 +0,0 @@
-
-import { DyFM_DataModel_Params, DyFM_Metadata, DyFM_Object } from '@futdevpro/fsm-dynamo';
-
-/**
- * `DyNTS_LVS_VectorPersist` (BFR-AM-001) — egy MongoDB-ben perzistált vektor-rekord, ami a
- * `LVS_VectorPool_ControlService` **in-memory** pool-jának tartós háttértára. A FAM (fdp-agent-memory)
- * workaround-ját generalizálja: a vektorok a SAJÁT Mongo-ban élnek, boot-kor a memória-pool-ba
- * hidratálódnak — **NEM** MongoDB Atlas Vector Search.
- *
- * Egy dokumentum = **egy vektor egy adott pool-ban**. A `collectionKey` particionálja a pool-okat
- * (egy fogyasztó több, logikailag elkülönített pool-t tarthat — pl. táranként). A `vectorId` a pool-on
- * belüli kulcs (a `pool.addVector(vectorId, embedding)` ezzel illeszt).
- *
- * `extends DyFM_Metadata`: az identitás/metadata (`_id`, `__created`, `__lastModified`, `_deleted`) az
- * ősből jön. A `metadata` `unknown` (Mongoose `Mixed`) — a fogyasztó tetszőleges kísérő-adatot tárolhat
- * (a séma NEM validál); az `embedding` `number[]` a perzistált nyers vektor.
- */
-export class DyNTS_LVS_VectorPersist extends DyFM_Metadata {
-
-  /** A pool-on belüli vektor-kulcs (a `pool.addVector(vectorId, ...)` ezzel illeszt). */
-  vectorId?: string;
-
-  /** Melyik (logikai) pool-hoz tartozik — a pool-particionálás kulcsa (hidratálás-szűrő). */
-  collectionKey?: string;
-
-  /** A perzistált NYERS vektor (a pool maga számolja a normalizált másolatot). */
-  embedding?: number[];
-
-  /** A vektor dimenziója (homogenitás-ellenőrzéshez + diagnosztikához tárolt). */
-  dimensions?: number;
-
-  /** Opcionális fogyasztó-specifikus kísérő-adat (Mongoose `Mixed`; a séma NEM validál). */
-  metadata?: unknown;
-
-  constructor(set?: Partial<DyNTS_LVS_VectorPersist>) {
-    super(set);
-
-    if (set) {
-      DyFM_Object.cleanAssign(this, set);
-    }
-  }
-}
-
-/**
- * MongoDB data-params a `dynts_lvs_vector` collection-höz (BFR-AM-001). Az `embedding` `number[]` a
- * perzistált nyers vektor; a `metadata` `type:'object'` (Mongoose `Mixed`) — a séma NEM validál. A
- * `vectorId` + `collectionKey` index-elt (a hidratálás `collectionKey`-re, az upsert/remove a
- * `vectorId`+`collectionKey` párra szűr).
- */
-export const DyNTS_lvsVectorPersist_dataParams: DyFM_DataModel_Params<DyNTS_LVS_VectorPersist> =
-  new DyFM_DataModel_Params<DyNTS_LVS_VectorPersist>({
-    dataName: 'dynts_lvs_vector',
-    properties: {
-      vectorId: { type: 'string', index: true, required: true },
-      collectionKey: { type: 'string', index: true, required: true },
-      embedding: { type: 'number[]' },
-      dimensions: { type: 'number' },
-      metadata: { type: 'object' },
-    },
-  });

package/src/_modules/local-vector-search/_models/lvs-search-result.interface.ts

@@ -1,17 +0,0 @@
-/**
- * Vektor keresési eredmény interface
- * Tartalmazza a találat ID-ját és a hasonlósági pontszámot
- */
-export interface LVS_SearchResult {
-  /**
-   * A találat egyedi azonosítója
-   */
-  id: string;
-  /**
-   * A hasonlósági pontszám
-   * Cosine similarity esetén: 0-1 közötti érték (1 = legnagyobb hasonlóság)
-   * L2 distance esetén: 0 vagy pozitív érték (0 = legkisebb távolság, legnagyobb hasonlóság)
-   */
-  score: number;
-}
-

package/src/_modules/local-vector-search/_services/lvs-bm25.util.spec.ts

@@ -1,159 +0,0 @@
-import {
-  DyNTS_LVS_BM25_Corpus,
-  DyNTS_LVS_BM25_DocScore,
-  dyNTS_LVS_BM25_minMaxNormalize,
-} from './lvs-bm25.util';
-
-
-describe('| DyNTS_LVS_BM25_Corpus.tokenize', (): void => {
-  it('| lowercase + split on \\w+ boundaries', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('Hello, World!')).toEqual(['hello', 'world']);
-  });
-
-  it('| identifier marad egy tokenkent (PascalCase)', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('UserController')).toEqual(['usercontroller']);
-  });
-
-  it('| hyphenated nev ket tokenre esik', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('auth-flow')).toEqual(['auth', 'flow']);
-  });
-
-  it('| ures string → ures array', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('')).toEqual([]);
-  });
-
-  it('| csak whitespace/punctuation → ures array', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('   ,.!  ')).toEqual([]);
-  });
-
-  it('| underscore megmarad (snake_case is egy token)', (): void => {
-    expect(DyNTS_LVS_BM25_Corpus.tokenize('user_controller')).toEqual(['user_controller']);
-  });
-});
-
-
-describe('| DyNTS_LVS_BM25_Corpus.score', (): void => {
-  it('| ures corpus → ures array', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([]);
-    expect(corpus.size()).toBe(0);
-    expect(corpus.score('anything')).toEqual([]);
-  });
-
-  it('| ures query → minden doc 0 score-t kap', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'foo bar' },
-      { id: 'b', text: 'baz' },
-    ]);
-    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('');
-    expect(out.length).toBe(2);
-    expect(out.every((s: DyNTS_LVS_BM25_DocScore) => s.score === 0)).toBe(true);
-  });
-
-  it('| query NEM matchelo termmel → minden score 0', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'foo bar' },
-      { id: 'b', text: 'baz' },
-    ]);
-    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('xyz');
-    expect(out.every((s: DyNTS_LVS_BM25_DocScore) => s.score === 0)).toBe(true);
-  });
-
-  it('| relevant doc magasabb score-t kap mint nem-relevant', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'the UserController handles authentication' },
-      { id: 'b', text: 'cooking recipes for desserts' },
-      { id: 'c', text: 'database setup guide' },
-    ]);
-    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('UserController');
-    const a: DyNTS_LVS_BM25_DocScore = out.find((s) => s.id === 'a')!;
-    const b: DyNTS_LVS_BM25_DocScore = out.find((s) => s.id === 'b')!;
-    expect(a.score).toBeGreaterThan(0);
-    expect(b.score).toBe(0);
-    expect(a.score).toBeGreaterThan(b.score);
-  });
-
-  it('| rarer term (alacsonyabb df) magasabb IDF-et ad → magasabb score', (): void => {
-    // 'common' minden docban → alacsony IDF; 'rare' csak az 'a' docban → magas IDF
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'common rare' },
-      { id: 'b', text: 'common' },
-      { id: 'c', text: 'common' },
-      { id: 'd', text: 'common' },
-    ]);
-    const commonOut: DyNTS_LVS_BM25_DocScore[] = corpus.score('common');
-    const rareOut: DyNTS_LVS_BM25_DocScore[] = corpus.score('rare');
-    const aCommon: number = commonOut.find((s) => s.id === 'a')!.score;
-    const aRare: number = rareOut.find((s) => s.id === 'a')!.score;
-    expect(aRare).toBeGreaterThan(aCommon);
-  });
-
-  it('| query-term ismetles NEM no monotonan a score-on (term saturation k1)', (): void => {
-    // 'a' egy 'foo'-t tartalmaz, 'b' tobbet
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'foo bar baz qux' },
-      { id: 'b', text: 'foo foo foo foo bar baz qux' },
-    ]);
-    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('foo');
-    const a: number = out.find((s) => s.id === 'a')!.score;
-    const b: number = out.find((s) => s.id === 'b')!.score;
-    // b > a, de NEM 4x a-szor (saturation)
-    expect(b).toBeGreaterThan(a);
-    expect(b).toBeLessThan(4 * a);
-  });
-
-  it('| case-insensitive — uppercase query matchel lowercase doc-ot', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'usercontroller is great' },
-    ]);
-    const out: DyNTS_LVS_BM25_DocScore[] = corpus.score('USERCONTROLLER');
-    expect(out[0].score).toBeGreaterThan(0);
-  });
-
-  it('| ket query term aggregalja az IDF-eket additivan', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'auth flow handler' },
-      { id: 'b', text: 'auth only' },
-      { id: 'c', text: 'flow only' },
-    ]);
-    const both: number = corpus.score('auth flow').find((s) => s.id === 'a')!.score;
-    const authOnly: number = corpus.score('auth').find((s) => s.id === 'a')!.score;
-    expect(both).toBeGreaterThan(authOnly);
-  });
-
-  it('| invalid input doc (null/missing id/text) silently skipd', (): void => {
-    const corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus([
-      { id: 'a', text: 'hello' },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      null as any,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      { id: 'b' } as any,
-    ]);
-    expect(corpus.size()).toBe(1);
-  });
-});
-
-
-describe('| dyNTS_LVS_BM25_minMaxNormalize', (): void => {
-  it('| ures input → ures array', (): void => {
-    expect(dyNTS_LVS_BM25_minMaxNormalize([])).toEqual([]);
-  });
-
-  it('| min 0, max 10 → normalizalva [0..1]', (): void => {
-    const out: DyNTS_LVS_BM25_DocScore[] = dyNTS_LVS_BM25_minMaxNormalize([
-      { id: 'a', score: 0 },
-      { id: 'b', score: 5 },
-      { id: 'c', score: 10 },
-    ]);
-    expect(out.find((s) => s.id === 'a')!.score).toBeCloseTo(0, 5);
-    expect(out.find((s) => s.id === 'b')!.score).toBeCloseTo(0.5, 5);
-    expect(out.find((s) => s.id === 'c')!.score).toBeCloseTo(1, 5);
-  });
-
-  it('| azonos score → minden 0 (NEM 0.5, nincs jel diszkriminaciora)', (): void => {
-    const out: DyNTS_LVS_BM25_DocScore[] = dyNTS_LVS_BM25_minMaxNormalize([
-      { id: 'a', score: 3 },
-      { id: 'b', score: 3 },
-    ]);
-    expect(out.every((s) => s.score === 0)).toBe(true);
-  });
-});

package/src/_modules/local-vector-search/_services/lvs-bm25.util.ts

@@ -1,206 +0,0 @@
-/**
- * BM25 text-search ranking util a LVS hybrid search-hez (FR-004).
- *
- * Pure TypeScript, dependency-free. In-memory corpus alapjan szamol score-okat,
- * NEM perzisztal indexet (a hybrid hivasonkent ujraepiti a corpus-t a candidate
- * dokumentumokon — kis (~100..10000 dokumentum) LVS-corpus eseten ez gyors es
- * egyszeru).
- *
- * Canonical params: k1=1.2, b=0.75 (industry standard a "lucene-szeru"
- * implementaciokban). NEM expose-oltak — ha kell, FR-002 kovetkezo iteracioban
- * tehetjuk parameterizalhatova.
- *
- * Tokenizer: `text.toLowerCase().match(/\w+/g) || []`. Case-insensitive,
- * alphanumeric+underscore boundary-k. `UserController` egy token marad (jo az
- * identifier match-re), `auth-flow` ket tokenre esik (auth + flow).
- *
- * IDF formula (BM25+): `log((N - df + 0.5) / (df + 0.5) + 1)`. A +1 a logon
- * belul garantalja, hogy a kozos szavak is pozitiv (kicsi) IDF-et kapjanak,
- * NEM negativ-t — fontos a hybrid score-merge-nel hogy ne huzzon le dokumentumot
- * ahol kozos szo szerepel.
- */
-
-
-/** BM25 k1 parameter (term saturation control). Canonical default. */
-const BM25_K1: number = 1.2;
-
-/** BM25 b parameter (length normalization weight, 0=off, 1=full). Canonical default. */
-const BM25_B: number = 0.75;
-
-/** Token regex — alphanumeric + underscore. */
-const TOKEN_REGEX: RegExp = /\w+/g;
-
-
-/**
- * Egy dokumentum BM25-score-ja egy query ellen, egy elore-felepitett corpus
- * konteztusaban.
- */
-export interface DyNTS_LVS_BM25_DocScore {
-  /** Dokumentum azonosito (mint az LVS_SearchResult `id`-jaben). */
-  id: string;
-  /** Nyers BM25 score (0..∞). NEM normalizalt. */
-  score: number;
-}
-
-
-/**
- * Felepitett BM25 corpus — egy adott dokumentumhalmaz indexe. A `score()` az
- * indexen kerdez le egy query-t es minden dokumentumra ad egy score-t.
- *
- * Egy corpus egyszer-hasznalatos a hybrid search hivasban — NEM kell cache-elni,
- * a felepites O(N * |doc|) ami pici N-re elhanyagolhato.
- */
-export class DyNTS_LVS_BM25_Corpus {
-
-  /** Tokenizalt dokumentumok: id -> tokens. */
-  private readonly docTokens: Map<string, string[]> = new Map<string, string[]>();
-  /** Doc-length: id -> token count. */
-  private readonly docLengths: Map<string, number> = new Map<string, number>();
-  /** Term -> doc-frequency (hany docban szerepel az adott term, legalabb 1x). */
-  private readonly termDocFreq: Map<string, number> = new Map<string, number>();
-  /** Term -> id -> term-frequency a docban. */
-  private readonly termFreqByDoc: Map<string, Map<string, number>> = new Map<string, Map<string, number>>();
-  /** Atlagos dokumentum-hossz (token count). */
-  private avgDocLength: number = 0;
-  /** Total doc count. */
-  private docCount: number = 0;
-
-  /**
-   * Letrehoz egy uj corpus-t a megadott id->text parok-bol.
-   * NEM dob hibat ures input-ra — ures corpus ervenyes (minden score = 0).
-   */
-  constructor(docs: { id: string; text: string }[]) {
-    if (!Array.isArray(docs) || docs.length === 0) { return; }
-
-    let totalLength: number = 0;
-    for (const doc of docs) {
-      if (!doc || typeof doc.id !== 'string' || typeof doc.text !== 'string') { continue; }
-      const tokens: string[] = DyNTS_LVS_BM25_Corpus.tokenize(doc.text);
-      this.docTokens.set(doc.id, tokens);
-      this.docLengths.set(doc.id, tokens.length);
-      totalLength += tokens.length;
-
-      // Term-frequency a docban
-      const localTf: Map<string, number> = new Map<string, number>();
-      for (const tok of tokens) {
-        localTf.set(tok, (localTf.get(tok) ?? 0) + 1);
-      }
-
-      for (const [term, tf] of localTf) {
-        // Doc-frequency: +1 per term, per doc
-        this.termDocFreq.set(term, (this.termDocFreq.get(term) ?? 0) + 1);
-        // Term-freq-by-doc reverse index
-        let perDoc: Map<string, number> | undefined = this.termFreqByDoc.get(term);
-        if (!perDoc) {
-          perDoc = new Map<string, number>();
-          this.termFreqByDoc.set(term, perDoc);
-        }
-        perDoc.set(doc.id, tf);
-      }
-    }
-
-    this.docCount = this.docTokens.size;
-    this.avgDocLength = this.docCount > 0 ? totalLength / this.docCount : 0;
-  }
-
-
-  /**
-   * Public tokenizer — exportalt, hogy spec-ek + hivok ugyanazt a normalizalast
-   * tudjak hasznalni mint a corpus.
-   */
-  static tokenize(text: string): string[] {
-    if (typeof text !== 'string' || text.length === 0) { return []; }
-    return text.toLowerCase().match(TOKEN_REGEX) ?? [];
-  }
-
-
-  /**
-   * Visszaadja a corpus dokumentum-szamat (NEM-ures docok).
-   */
-  size(): number {
-    return this.docCount;
-  }
-
-
-  /**
-   * BM25 score minden dokumentumra a query-re.
-   *
-   * Ures query → minden score 0 (degenerate case; a hivo kezelje ha kell).
-   * Ures corpus → ures array.
-   */
-  score(query: string): DyNTS_LVS_BM25_DocScore[] {
-    if (this.docCount === 0) { return []; }
-    const queryTokens: string[] = DyNTS_LVS_BM25_Corpus.tokenize(query);
-    if (queryTokens.length === 0) {
-      // Minden doc 0 score-t kap
-      const results: DyNTS_LVS_BM25_DocScore[] = [];
-      for (const id of this.docTokens.keys()) {
-        results.push({ id: id, score: 0 });
-      }
-      return results;
-    }
-
-    // Egyedi query-termek halmaza (ismetlodes nem ad nagyobb IDF-et)
-    const uniqueTerms: string[] = Array.from(new Set<string>(queryTokens));
-
-    // Pre-compute IDF a query-termekre
-    const idfMap: Map<string, number> = new Map<string, number>();
-    for (const term of uniqueTerms) {
-      const df: number = this.termDocFreq.get(term) ?? 0;
-      // BM25+ IDF: log((N - df + 0.5) / (df + 0.5) + 1)
-      const idf: number = Math.log((this.docCount - df + 0.5) / (df + 0.5) + 1);
-      idfMap.set(term, idf);
-    }
-
-    // Per-doc BM25 score
-    const results: DyNTS_LVS_BM25_DocScore[] = [];
-    for (const [docId, docLen] of this.docLengths) {
-      let score: number = 0;
-      for (const term of uniqueTerms) {
-        const tf: number = this.termFreqByDoc.get(term)?.get(docId) ?? 0;
-        if (tf === 0) { continue; }
-        const idf: number = idfMap.get(term) ?? 0;
-        const norm: number = 1 - BM25_B + BM25_B * (docLen / (this.avgDocLength || 1));
-        score += idf * (tf * (BM25_K1 + 1)) / (tf + BM25_K1 * norm);
-      }
-      results.push({ id: docId, score: score });
-    }
-
-    return results;
-  }
-}
-
-
-/**
- * Min-max normalizalas [0,1] tartomanyra. A hybrid score-merge-hez kell a BM25
- * score-okat a candidate-szetten 0..1 sav-ba hozni (a cosine mar 0..1).
- *
- * Edge case-ek:
- *  - Ures array → [].
- *  - Minden score azonos (max-min === 0) → minden 0.0 (NEM 0.5 vagy 1.0; ha
- *    nincs diszkriminacio, ne tegyunk hozza signal-t).
- *  - Negativ score-ok (BM25+IDF garantal pozitivat, de defensive): a min-max
- *    ugyanugy mukodik.
- */
-export function dyNTS_LVS_BM25_minMaxNormalize(
-  scores: DyNTS_LVS_BM25_DocScore[],
-): DyNTS_LVS_BM25_DocScore[] {
-  if (!Array.isArray(scores) || scores.length === 0) { return []; }
-  let min: number = Infinity;
-  let max: number = -Infinity;
-  for (const s of scores) {
-    if (s.score < min) { min = s.score; }
-    if (s.score > max) { max = s.score; }
-  }
-  const range: number = max - min;
-  if (range === 0) {
-    // Nincs diszkriminacio — minden 0.0 (NEM huzzon le, NEM huzzon fel)
-    return scores.map((s: DyNTS_LVS_BM25_DocScore): DyNTS_LVS_BM25_DocScore => ({
-      id: s.id, score: 0,
-    }));
-  }
-  return scores.map((s: DyNTS_LVS_BM25_DocScore): DyNTS_LVS_BM25_DocScore => ({
-    id: s.id,
-    score: (s.score - min) / range,
-  }));
-}