@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/embedding/_services/fam-embedding.control-service.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Embedding_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_embedding_cost_control_service_1 = require("./fam-embedding-cost.control-service");
+const fam_lmstudio_embedding_provider_1 = require("./fam-lmstudio-embedding.provider");
+const fam_mock_embedding_provider_1 = require("./fam-mock-embedding.provider");
+const fam_openai_embedding_provider_1 = require("./fam-openai-embedding.provider");
+/**
+ * `FAM_Embedding_ControlService` (SP-2.1, dsgn-006 §2) — az embedding-réteg EGYETLEN belső kapuja.
+ * Singleton. A config-precedencián (`scope > table > global > env-default`) feloldja a providert +
+ * modellt, dispatch-el a megfelelő `FAM_EmbeddingProvider`-hez (OpenAI reuse / LM Studio adapter /
+ * mock), alkalmazza a cost-cap-et (SP-2.4), és aggregálja a költséget (BFR-AM-007).
+ *
+ * **Provider-csere boundary (dsgn-006 §1):** a hívók CSAK az `embedTexts`/`embedOne`/`resolveProvider`
+ * API-t látják — a path mögötti impl (LM Studio HTTP / mock) workaround, a bedrock-csere (MP-15)
+ * non-breaking. A provider-példányokat lazy építjük (env/secret a hívás-időpontban érvényes).
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt; a config
+ * a `FAM_Config_ControlService.getInstance()` singleton-on át oldódik fel.
+ */
+class FAM_Embedding_ControlService {
+    static _instance;
+    /** Default issuer (a hibák / cost-event issuer-éhez). */
+    issuer = 'FAM_Embedding_ControlService';
+    static getInstance() {
+        if (!FAM_Embedding_ControlService._instance) {
+            FAM_Embedding_ControlService._instance = new FAM_Embedding_ControlService();
+        }
+        return FAM_Embedding_ControlService._instance;
+    }
+    // =========================================================================
+    // RESOLVE PROVIDER (dsgn-006 §2 / SP-2.1 + SP-2.3 override)
+    // =========================================================================
+    /**
+     * A provider-konfiguráció feloldása a config-precedencián (dsgn-007 §3). A `embedding.provider` /
+     * `embedding.model` / `embedding.dimensions` / `embedding.batchSize` a `scope > table > global >
+     * builtin` precedencián; az env-default (a `seedDefaultsFromEnv` által GLOBAL-ba seedelt érték) így
+     * automatikusan a global-szinten szerepel. Az LM Studio `baseUrl` az ENV-ből jön (titok-szerű, nem DB).
+     */
+    async resolveProvider(context) {
+        const config = config_control_service_1.FAM_Config_ControlService.getInstance();
+        const resolveCtx = { table: context?.table, scopePath: context?.scopePath };
+        const providerValue = (await config.resolve('embedding.provider', resolveCtx)).value;
+        const provider = typeof providerValue === 'string' ? providerValue : 'openai';
+        const modelValue = (await config.resolve('embedding.model', resolveCtx)).value;
+        const modelId = typeof modelValue === 'string' ? modelValue : this.defaultModelForProvider(provider);
+        const dimsValue = (await config.resolve('embedding.dimensions', resolveCtx)).value;
+        const dims = typeof dimsValue === 'number' ? dimsValue : null;
+        const batchValue = (await config.resolve('embedding.batchSize', resolveCtx)).value;
+        const batchSize = typeof batchValue === 'number' ? batchValue : 64;
+        return {
+            provider: provider,
+            modelId: modelId,
+            dims: dims,
+            batchSize: batchSize,
+            baseUrl: provider === 'lmstudio' ? this.lmStudioBaseUrl() : undefined,
+        };
+    }
+    // =========================================================================
+    // EMBED (dsgn-006 §2 batch / single)
+    // =========================================================================
+    /**
+     * Batch-embedding (CCAP `Rag_Embedding_Client.embedTexts` mintára): a `texts` sorrendjében ad
+     * `number[][]`-t. A flow: resolveProvider → cost-cap precheck (block-before-overrun + warn) →
+     * batch-elt provider-dispatch (`embedding.batchSize`) → cost-aggregálás. Provider-hiba kanonikus
+     * `FAM-EMB-*` hibává alakul (MP-8 factory) — soha nem néma.
+     */
+    async embedTexts(set) {
+        if (!set.texts.length) {
+            return [];
+        }
+        const issuer = set.issuer ?? this.issuer;
+        const callType = set.callType ?? 'embed-write';
+        const resolved = await this.resolveProvider({ table: set.table, scopePath: set.scopePath });
+        // Cost-cap precheck (SP-2.4) — a hívás ELŐTT (block-before-overrun).
+        const decision = await fam_embedding_cost_control_service_1.FAM_EmbeddingCost_ControlService.getInstance().precheck({
+            callType: callType,
+            provider: resolved.provider,
+            modelId: resolved.modelId,
+            texts: set.texts,
+            table: set.table,
+            scopePath: set.scopePath,
+        });
+        if (decision.blocked) {
+            throw this.costCapError(decision.reason, issuer);
+        }
+        if (decision.warn) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM embedding cost-warn] ${decision.reason}`);
+        }
+        const provider = this.buildProvider(resolved, issuer);
+        // Batch-elt dispatch (token-/rate-limit védelem; dsgn-007 embedding.batchSize).
+        const allVectors = [];
+        for (let i = 0; i < set.texts.length; i += resolved.batchSize) {
+            const batch = set.texts.slice(i, i + resolved.batchSize);
+            try {
+                const vectors = await provider.embedTexts({ texts: batch, model: resolved.modelId, issuer: issuer });
+                this.assertDimensions(vectors, resolved, issuer);
+                allVectors.push(...vectors);
+            }
+            catch (error) {
+                throw this.providerError(resolved.provider, resolved.modelId, error, issuer);
+            }
+        }
+        // Cost-aggregálás (SP-2.4, BFR-AM-007): a becsült tokenből (a pontos cost-event a bedrock-szinten).
+        fam_embedding_cost_control_service_1.FAM_EmbeddingCost_ControlService.getInstance().recordActual({
+            callType: callType,
+            provider: resolved.provider,
+            modelId: resolved.modelId,
+            tokens: fam_embedding_cost_control_service_1.FAM_EmbeddingCost_ControlService.getInstance().estimateTokens(set.texts),
+        });
+        return allVectors;
+    }
+    /** Egy-szöveg embedding (a `embedTexts` egyelemű alakja). */
+    async embedOne(set) {
+        const vectors = await this.embedTexts({ texts: [set.text], ...this.stripText(set) });
+        return vectors[0] ?? [];
+    }
+    // =========================================================================
+    // PROVIDER-elérhetőség (test_embedding_provider capability — dsgn-003)
+    // =========================================================================
+    /**
+     * A jelenleg feloldott provider elérhetőség-próbája (a `test_embedding_provider` / `get_embedding_config`
+     * capability — dsgn-003 — alapja). `false` / hiba esetén bootstrap-skip jelzés (dsgn-006 §4.1) — nem néma.
+     */
+    async testProvider(context) {
+        const resolved = await this.resolveProvider(context);
+        try {
+            const provider = this.buildProvider(resolved, this.issuer);
+            const available = await provider.isAvailable({ model: resolved.modelId, issuer: this.issuer });
+            return { available: available, resolved: resolved };
+        }
+        catch {
+            return { available: false, resolved: resolved };
+        }
+    }
+    // =========================================================================
+    // provider-építés + dispatch + hiba-konverzió
+    // =========================================================================
+    /**
+     * A feloldott config alapján a konkrét provider-példány. Lazy (env/secret a hívás-időpontban):
+     * - `openai` → `FAM_OpenAI_EmbeddingProvider` (REUSE, cost-event sink-kel),
+     * - `lmstudio` → `FAM_LMStudio_EmbeddingProvider` (BFR-AM-002 HTTP; `baseUrl` kötelező),
+     * - `mock` → `FAM_Mock_EmbeddingProvider` (BFR-AM-008 determinisztikus, dimenzió a config dims-ből),
+     * - ismeretlen → `FAM-EMB-PROVIDER-001` (provider nincs konfigurálva, bootstrap-skip).
+     */
+    buildProvider(resolved, issuer) {
+        switch (resolved.provider) {
+            case 'openai':
+                return new fam_openai_embedding_provider_1.FAM_OpenAI_EmbeddingProvider((event) => this.onCostEvent(event));
+            case 'lmstudio':
+                if (!resolved.baseUrl) {
+                    throw fam_error_factory_util_1.FAM_Error_Util.create({
+                        errorCode: error_codes_const_1.FAM_ERROR_CODES.embProviderNotConfigured,
+                        message: 'Az LM Studio provider választva, de a LMSTUDIO_BASE_URL nincs beállítva (env).',
+                        issuer: issuer,
+                        context: { operation: 'build-provider', provider: 'lmstudio' },
+                    });
+                }
+                return new fam_lmstudio_embedding_provider_1.FAM_LMStudio_EmbeddingProvider(resolved.baseUrl, this.lmStudioApiKey());
+            case 'mock':
+                return new fam_mock_embedding_provider_1.FAM_Mock_EmbeddingProvider(resolved.dims ?? undefined);
+            default:
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.embProviderNotConfigured,
+                    message: `Ismeretlen embedding-provider: '${resolved.provider}'. `
+                        + `Elérhető: 'openai' | 'lmstudio' | 'mock'.`,
+                    issuer: issuer,
+                    context: { operation: 'build-provider', provider: resolved.provider },
+                });
+        }
+    }
+    /**
+     * Dimenzió-konzisztencia ellenőrzés (dsgn-006 §6.2 / acceptance #6): ha a config explicit `dims`-et
+     * deklarál, a kapott vektoroknak ezzel egyezniük kell — eltérés → `FAM-EMB-PROVIDER-003` (nem néma,
+     * NEM kever eltérő dimenziójú vektort egy tár pool-jába). `dims=null` → a modell natív dimenziója (skip).
+     */
+    assertDimensions(vectors, resolved, issuer) {
+        if (resolved.dims === null || !vectors.length) {
+            return;
+        }
+        const actual = vectors[0].length;
+        if (actual !== resolved.dims) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.embProviderDimensionMismatch,
+                message: `Az embedding dimenzió-eltérés: a(z) '${resolved.modelId}' modell ${actual}-dimenziós `
+                    + `vektort adott, de a config ${resolved.dims}-et deklarál. Re-embed szükséges (dsgn-006 §5/§6.2).`,
+                issuer: issuer,
+                context: { operation: 'assert-dimensions', provider: resolved.provider },
+            });
+        }
+    }
+    /** Provider-hiba kanonikus `FAM-EMB-PROVIDER-002`-vé (elérhetetlen / API-hiba). */
+    providerError(provider, modelId, cause, issuer) {
+        // Ha már kanonikus FAM error (pl. dimenzió-mismatch a batch-en belül), nem csomagoljuk újra.
+        if (cause instanceof fsm_dynamo_1.DyFM_Error) {
+            return cause;
+        }
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.embProviderUnreachable,
+            message: `Az embedding-provider ('${provider}', modell '${modelId}') elérhetetlen vagy hibát adott.`,
+            issuer: issuer,
+            cause: cause,
+            context: { operation: 'embed', provider: provider },
+        });
+    }
+    /** Cost-cap blokk → `FAM-EMB-COSTCAP-001` (block-before-overrun; dsgn-006 §7 / dsgn-008). */
+    costCapError(reason, issuer) {
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.embCostCap,
+            message: `Embedding cost-cap: a hívás blokkolva a túllépés előtt. ${reason}`,
+            issuer: issuer,
+            context: { operation: 'cost-cap' },
+        });
+    }
+    /** A cost-event sink (a provider per-call token-fogyasztását aggregálja — BFR-AM-007). */
+    onCostEvent(event) {
+        // A pontos token-fogyasztás a cost-event-ből; a call-type a `recordActual`-ban becsült úton is
+        // beíródik, ezért itt CSAK telemetria-log (a dupla-számolás elkerülése végett nem aggregálunk).
+        fsm_dynamo_1.DyFM_Log.log(`[FAM embedding cost-event] ${event.provider}/${event.model} tokens=${event.tokensUsed.total}`);
+    }
+    // =========================================================================
+    // env + default helpers
+    // =========================================================================
+    /** A default modell egy providerhez (ha a config nem ad modellt). */
+    defaultModelForProvider(provider) {
+        if (provider === 'lmstudio') {
+            return process.env.LMSTUDIO_EMBEDDING_MODEL || 'nomic-embed-text-v1.5';
+        }
+        return process.env.OPENAI_EMBEDDING_MODEL || 'text-embedding-3-large';
+    }
+    /** Az LM Studio base URL az ENV-ből (titok-szerű, nem DB; dsgn-006 §8). */
+    lmStudioBaseUrl() {
+        return process.env.LMSTUDIO_BASE_URL;
+    }
+    /** Opcionális LM Studio API-kulcs (default-ban nem kell). */
+    lmStudioApiKey() {
+        return process.env.LMSTUDIO_API_KEY;
+    }
+    /** A `embedOne` set-jéből a `text`-et kihagyó opció-objektum (a `embedTexts`-nek átadva). */
+    stripText(set) {
+        return {
+            table: set.table,
+            scopePath: set.scopePath,
+            callType: set.callType,
+            issuer: set.issuer,
+        };
+    }
+}
+exports.FAM_Embedding_ControlService = FAM_Embedding_ControlService;

package/build/src/_modules/embedding/_services/fam-entry.data-service.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Entry_DataService = void 0;
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_entry_data_model_1 = require("../../../_models/data-models/fam-entry.data-model");
+/**
+ * `FAM_Entry_DataService` (SP-2.2) — egy GENERIKUS, tár-paraméteres entry-CRUD a vektor-rétegnek.
+ * A `dataParams`-ot a `FAM_STORE_REGISTRY`-ből kapja (per-tár), így EGY data-service-osztály szolgálja
+ * ki mind a 6 fő tárat a vektor-persist + hidratálás során — a közös `FAM_Entry` bázis-mezőkre (a
+ * vektor-réteg CSAK a `content`/`contentVector`/`embeddingStatus`/`scopePath`/`tags`/`kind`/`weight`
+ * mezőket olvassa).
+ *
+ * **Atomikus vektor-write (memory: reference_mongoose_mixed_atomic_write):** a `contentVector` egy
+ * `number[]` Mixed-szerű mező — a `findOne→mutate→save` SILENT-DROP-ot ad; ezért a vektor-frissítés
+ * `updateData` (`$set`) úton megy (lásd `setVector`). NEM `saveData`-val a teljes instance-en.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a base-ctor eager `getDBService`-t hív, ezért
+ * a control-service-ek NEM tartanak élő példányt mezőként — minden művelet előtt lazy `new`.
+ */
+class FAM_Entry_DataService extends nts_dynamo_1.DyNTS_DataService {
+    constructor(set) {
+        super(new fam_entry_data_model_1.FAM_Entry(), set.dataParams, set.issuer);
+    }
+    /**
+     * A move-to-archive soft-delete (dsgn-001 §8) archív-collection service-e: a base `deleteData`
+     * (a 6 fő tár `addArchive:true`) ezt hívja, hogy a törölt entry-t a `<tár>_archived` tárba
+     * mozgassa. A `DyNTS_DataService` base default-ja DOB (nincs ökoszisztéma-implementáció) — ezért
+     * az explicit override (a `DyNTS_ArchiveDataService` a `dataParams.addArchive`-ból oldja az
+     * archív-nevet; a per-tár `dataParams` itt is a `this.dataParams`).
+     */
+    getArchiveDataService() {
+        return new nts_dynamo_1.DyNTS_ArchiveDataService(new fam_entry_data_model_1.FAM_Entry(), this.dataParams, this.issuer);
+    }
+    /**
+     * A completed-embeddingű, nem-törölt entry-k egy lapja a hidratáláshoz (SP-2.2 boot-hidratálás).
+     * A lapozás `skip`/`limit`-tel (a base `findDataList` egyszerű filter-rel; a `_deleted` undefined =
+     * aktív). A `findDataList` a soft-delete-elteket alapból kihagyja (a Dynamo-konvenció szerint).
+     */
+    async findHydratableList(filter) {
+        return this.findDataList(filter);
+    }
+    /**
+     * Egy entry vektor-mezőinek ATOMIKUS frissítése (`$set`) — a Mixed silent-drop ellen. A
+     * `contentVector` + `embeddingModel` + `embeddingStatus` + opc. `contentHash` egy lépésben.
+     */
+    async setVector(set) {
+        const setBlock = {
+            contentVector: set.contentVector,
+            embeddingModel: set.embeddingModel,
+            embeddingStatus: set.embeddingStatus,
+        };
+        if (set.contentHash !== undefined) {
+            setBlock.contentHash = set.contentHash;
+        }
+        const update = { $set: setBlock };
+        await this.updateData({ filterBy: { _id: set.id }, update: update });
+    }
+    /** Csak az `embeddingStatus` atomikus frissítése (pl. `pending` a re-embed elején). */
+    async setEmbeddingStatus(id, status) {
+        const update = { $set: { embeddingStatus: status } };
+        await this.updateData({ filterBy: { _id: id }, update: update });
+    }
+}
+exports.FAM_Entry_DataService = FAM_Entry_DataService;

package/build/src/_modules/embedding/_services/fam-lmstudio-embedding.provider.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_LMStudio_EmbeddingProvider = void 0;
+/**
+ * `FAM_LMStudio_EmbeddingProvider` (SP-2.1) — **BFR-AM-002 projekt-lokális workaround**: OpenAI-
+ * kompatibilis lokális embedding-endpoint (`${baseUrl}/embeddings`), a CCAP
+ * `Rag_OpenAiCompatible_RagEmbedding_Client` mintájára. `baseUrl` + `modelId` (+ opc. `apiKey`).
+ * Lokális futás → nincs USD-költség (dsgn-006 §7, csak telemetria). Node 20 global `fetch`-et használ
+ * (függőség-mentes), így a core NEM hoz be provider-specifikus SDK-t (boundary, dsgn-006 §1).
+ *
+ * **Csere-pont (MP-15):** amikor a bedrock `DyNTS_LMStudio_Embedding_ControlService` landol, ez az
+ * osztály lecserélhető anélkül, hogy a `FAM_EmbeddingProvider` interfész-hívók törnének.
+ */
+class FAM_LMStudio_EmbeddingProvider {
+    baseUrl;
+    apiKey;
+    providerId = 'lmstudio';
+    /**
+     * @param baseUrl OpenAI-kompatibilis lokális endpoint (pl. `http://localhost:1234/v1`).
+     * @param apiKey opcionális Bearer token (LM Studio default-ban nem kér).
+     */
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    /**
+     * Batch-embedding az OpenAI-kompatibilis `/embeddings` végpontra. A `texts` sorrendje == a
+     * visszaadott `number[][]` sorrendje. HTTP-/parse-hiba deskriptív üzenettel dobódik (a
+     * `FAM_Embedding_ControlService` `FAM-EMB-PROVIDER-002`-vé alakítja — dsgn-008).
+     */
+    async embedTexts(set) {
+        const url = `${this.trimTrailingSlashes(this.baseUrl)}/embeddings`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey && this.apiKey.trim().length) {
+            headers.Authorization = `Bearer ${this.apiKey.trim()}`;
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: headers,
+            body: JSON.stringify({ model: set.model, input: set.texts }),
+        });
+        const rawText = await response.text();
+        if (!response.ok) {
+            throw new Error(`LM Studio (OpenAI-compatible) embeddings HTTP ${response.status} | url=${url} | `
+                + `model=${set.model} | body=${this.snapshot(rawText)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch {
+            throw new Error(`LM Studio embeddings: nem JSON válasz | url=${url} | model=${set.model} | `
+                + `body=${this.snapshot(rawText)}`);
+        }
+        return this.parseEmbeddingDataArray(parsed, set.texts.length, url, set.model);
+    }
+    /**
+     * Provider-elérhetőség: egy minimál embedding-próba (egy üres-szöveg helyett rövid token). Ha a
+     * hívás dob (endpoint down / model hiányzik), `false` (a `test_embedding_provider` capability így
+     * jelez bootstrap-skip-et, dsgn-006 §4.1). Soha nem propagál hibát (try/catch → false).
+     */
+    async isAvailable(set) {
+        try {
+            const vectors = await this.embedTexts({ texts: ['ping'], model: set.model, issuer: set.issuer });
+            return vectors.length === 1 && vectors[0].length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Trailing `/`-ek levágása (kettős slash elkerülése a `/embeddings` join-nál). */
+    trimTrailingSlashes(value) {
+        return value.replace(/\/+$/, '');
+    }
+    /** Rövid, biztonságos válasz-snapshot a hiba-üzenethez (max 300 char). */
+    snapshot(value) {
+        const trimmed = (value ?? '').slice(0, 300);
+        return trimmed.length === 300 ? `${trimmed}…` : trimmed;
+    }
+    /**
+     * A `data[].embedding` típusbiztos kiolvasása (CCAP-minta). Hibás/hiányzó mező → deskriptív hiba
+     * a teljes válasz-snapshottal. A darabszám-egyezés ellenőrzött (a `texts` és a vektorok 1:1).
+     */
+    parseEmbeddingDataArray(json, expectedCount, url, modelId) {
+        if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+            throw new Error(`LM Studio embeddings: érvénytelen válasz-objektum | url=${url} | model=${modelId}`);
+        }
+        const dataRaw = Reflect.get(json, 'data');
+        if (!Array.isArray(dataRaw)) {
+            throw new Error(`LM Studio embeddings: hiányzó data tömb | url=${url} | model=${modelId}`);
+        }
+        const out = [];
+        for (const item of dataRaw) {
+            if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+                continue;
+            }
+            const embRaw = Reflect.get(item, 'embedding');
+            if (!Array.isArray(embRaw)) {
+                continue;
+            }
+            const vec = embRaw.filter((x) => typeof x === 'number' && Number.isFinite(x));
+            if (vec.length) {
+                out.push(vec);
+            }
+        }
+        if (out.length !== expectedCount) {
+            throw new Error(`LM Studio embeddings: várt ${expectedCount} vektor, kaptunk ${out.length} | url=${url} | model=${modelId}`);
+        }
+        return out;
+    }
+}
+exports.FAM_LMStudio_EmbeddingProvider = FAM_LMStudio_EmbeddingProvider;

package/build/src/_modules/embedding/_services/fam-mock-embedding.provider.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Mock_EmbeddingProvider = exports.FAM_MOCK_EMBEDDING_DIMS = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+/** A mock-provider default dimenziója (kicsi, hogy a teszt-pool gyors legyen, de elég a koszinuszhoz). */
+exports.FAM_MOCK_EMBEDDING_DIMS = 64;
+/**
+ * `FAM_Mock_EmbeddingProvider` (SP-2.1) — **BFR-AM-008 projekt-lokális workaround**: determinisztikus,
+ * hash-alapú, fix-dimenziós, l2-normalizált pszeudo-vektor a szövegből (dsgn-006 §9). Provider- és
+ * hálózat-mentes → a tesztek (MP-13) + a tsc-/offline-smoke valódi kulcs nélkül futnak. Azonos szöveg
+ * → azonos vektor (idempotens), és a koszinusz-keresés VALÓDI LVS-pool-on tesztelhető.
+ *
+ * **Csere-pont (MP-15):** amikor a bedrock `DyNTS_AI_Embedding_MockService` landol, ez lecserélhető.
+ */
+class FAM_Mock_EmbeddingProvider {
+    dims;
+    providerId = 'mock';
+    /** @param dims a generált vektor dimenziója (default `FAM_MOCK_EMBEDDING_DIMS`). */
+    constructor(dims = exports.FAM_MOCK_EMBEDDING_DIMS) {
+        this.dims = dims;
+    }
+    /**
+     * Determinisztikus batch-embedding: minden szöveghez a SHA-256 hash bájtjaiból generál egy fix-
+     * dimenziós, l2-normalizált vektort. A `model` paramétert beleszövi a seed-be, hogy modell-váltás
+     * más vektort adjon (re-embed teszteléshez, dsgn-006 §5).
+     */
+    async embedTexts(set) {
+        return set.texts.map((text) => this.deterministicVector(`${set.model}::${text}`));
+    }
+    /** A mock mindig elérhető (nincs külső függőség). */
+    async isAvailable(_set) {
+        return true;
+    }
+    /**
+     * Egy determinisztikus, l2-normalizált vektor a seed-ből. A 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).
+     */
+    deterministicVector(seed) {
+        const hash = crypto.createHash('sha256').update(seed).digest();
+        const vector = [];
+        for (let i = 0; i < this.dims; i++) {
+            const byte = hash[i % hash.length];
+            // Egy második hash-bájttal keverünk a hosszabb dimenziókhoz, hogy ne ismétlődjön a minta.
+            const mix = hash[(i * 7 + 3) % hash.length];
+            const combined = (byte ^ mix) & 0xff;
+            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). */
+    l2Normalize(vector) {
+        let sumSq = 0;
+        for (const value of vector) {
+            sumSq += value * value;
+        }
+        const norm = Math.sqrt(sumSq);
+        if (!norm) {
+            return vector;
+        }
+        return vector.map((value) => value / norm);
+    }
+}
+exports.FAM_Mock_EmbeddingProvider = FAM_Mock_EmbeddingProvider;

package/build/src/_modules/embedding/_services/fam-openai-embedding.provider.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_OpenAI_EmbeddingProvider = void 0;
+const ai_1 = require("@futdevpro/fsm-dynamo/ai");
+const open_ai_1 = require("@futdevpro/nts-dynamo/ai/open-ai");
+/**
+ * `FAM_OpenAI_EmbeddingProvider` (SP-2.1) — az OpenAI embedding path. **REUSE ([A], dsgn-006 §2):**
+ * a bedrock `DyNTS_OAI_Embedding_ControlService`-t használja (`createEmbeddings` batch). A secret
+ * (`OPENAI_API_KEY`) + base URL az OpenAI-client default env-feloldásából jön (`DyFM_OAI_ClientOptions`),
+ * a modell a config-precedencián feloldva érkezik (`embedTexts.model`).
+ *
+ * **LM Studio reuse-pont:** a `DyNTS_OAI_Embedding_ControlService` OpenAI-kliense `baseURL`-lel
+ * átirányítható egy OpenAI-kompatibilis lokális endpointra — de a FAM az LM Studio-t a `fetch`-alapú
+ * `FAM_LMStudio_EmbeddingProvider`-rel kezeli (explicit, függőség-mentes; BFR-AM-002 workaround),
+ * hogy a két path egyértelműen elkülönüljön és a bedrock-csere (MP-15) tiszta legyen.
+ *
+ * **Cost-event (dsgn-006 §7):** a base `onCostEvent` callback-en kapjuk az emittált token-fogyasztást;
+ * a `FAM_Embedding_ControlService` regisztrálja a sink-et és aggregál (BFR-AM-007 workaround).
+ */
+class FAM_OpenAI_EmbeddingProvider {
+    providerId = 'openai';
+    /** A bedrock OpenAI embedding control-service (REUSE). Az `onCostEvent` a constructor-ban köthető. */
+    embedding_CS;
+    /**
+     * @param onCostEvent opcionális cost-event sink (a `FAM_Embedding_ControlService` adja át, hogy a
+     *   token-fogyasztást aggregálja — BFR-AM-007). Non-breaking: ha undefined, nincs aggregáció.
+     */
+    constructor(onCostEvent) {
+        this.embedding_CS = new open_ai_1.DyNTS_OAI_Embedding_ControlService({ onCostEvent: onCostEvent });
+    }
+    /**
+     * Batch-embedding az OpenAI-n (REUSE). A `fullResponse=false` → tiszta `number[][]`. A model a
+     * config-precedencián feloldott azonosító. Dimenzió-eltérés / API-hiba a base-en dobódik; a
+     * `FAM_Embedding_ControlService` kanonikus `FAM-EMB-*` hibává alakítja (dsgn-008).
+     */
+    async embedTexts(set) {
+        // `fullResponse=false` → a base `number[][]`-t ad. A return-type union a `CreateEmbeddingResponse`-t
+        // is tartalmazza (openai típus), de NEM importáljuk explicit (a csomag `openai` peer-függőség
+        // nélkül buildel; skipLibCheck) — strukturálisan szűkítünk.
+        const result = await this.embedding_CS.createEmbeddings({
+            texts: set.texts,
+            model: set.model,
+            fullResponse: false,
+            issuer: set.issuer,
+        });
+        if (Array.isArray(result)) {
+            return result;
+        }
+        // Defenzív fallback: ha valamiért a full response érkezne, a `data[].embedding`-et emeljük ki.
+        return result.data.map((item) => item.embedding);
+    }
+    /**
+     * Provider-elérhetőség: a base `testConnection` (OpenAI API ping). A `model` itt nem releváns a
+     * connection-próbához, de a szerződés egységessége miatt megtartjuk. A `DyFM_AI_Provider.OpenAI`
+     * konzisztencia-jelölés a diagnosztikához.
+     */
+    async isAvailable(set) {
+        const _provider = ai_1.DyFM_AI_Provider.OpenAI;
+        void _provider;
+        void set.model;
+        return this.embedding_CS.testConnection(set.issuer);
+    }
+}
+exports.FAM_OpenAI_EmbeddingProvider = FAM_OpenAI_EmbeddingProvider;