@futdevpro/fsm-dynamo 1.15.9 → 1.15.10

package/README.md

@@ -234,6 +234,9 @@ const config = {
 };
 ```
 
+**See also:**
+- [OpenAI-compatible providers how-to (LM Studio / Ollama / vLLM / LocalAI)](__documentations/2026-05-17-oai-compatible-providers-howto.md) — `DyFM_OAI_ClientOptions.baseURL`-override mintázattal lokál és self-hosted LLM-ek
+
 ### 3. Data Handler Module
 
 **Import:** `@futdevpro/fsm-dynamo/data-handler`

package/__documentations/2026-05-17-oai-compatible-providers-howto.md

@@ -0,0 +1,282 @@
+# 2026-05-17 — OpenAI-compatible providers (Hunglish how-to)
+
+**Spec:** `__agent/feature-requests/FR-005-oai-compat-provider-docs.md` (workspace root)
+**Scope:** docs-only, LOW priority. Nincs API-változás.
+
+---
+
+## Mire jó ez?
+
+A `DyFM_OAI_ClientOptions.baseURL` mező (`fsm-dynamo/_modules/ai/_modules/open-ai/_models/oai-client-options.interface.ts:25`) lehetővé teszi **tetszőleges OpenAI-API-kompatibilis endpoint** használatát az `openai` npm SDK-n keresztül — anélkül, hogy a Dynamo OAI service-eket (`DyFM_OAI_Settings`, downstream `DyNTS_OAI_Embedding_ControlService` / `DyNTS_OAI_LLM_ServiceBase`) bármi módon kellene módosítani.
+
+Tipikus use-case-ek:
+- **Lokál fejlesztés**: `OPENAI_API_KEY` nélkül, lokál LLM-mel (LM Studio, Ollama)
+- **Self-hosted production**: vLLM / LocalAI klaszter saját infrán
+- **Cost-control**: nyílt-súlyú modellek (Llama, Mistral, Qwen) drága API helyett
+
+A `baseURL`-override `openai` SDK-natív feature — Dynamo csak átadja a config-ot (`oai-llm.service-base.ts:91-98`):
+
+```typescript
+this.openai = new OpenAI(
+  set?.config ?? {
+    organization: DyNTS_global_settings.env_settings.openAi.organization,
+    apiKey: DyNTS_global_settings.env_settings.openAi.apiKey,
+    project: DyNTS_global_settings.env_settings.openAi.project,
+  }
+);
+```
+
+→ ha a `set.config.baseURL` ki van töltve, az SDK arra megy. Minden más változatlan.
+
+---
+
+## Általános minta
+
+```typescript
+import { DyFM_OAI_Settings, DyFM_OAI_CallSettings } from '@futdevpro/fsm-dynamo/ai/open-ai';
+import { DyNTS_OAI_LLM_ChatServiceBase } from '@futdevpro/dynamo-nts/ai/open-ai';
+
+const settings: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://<provider-host>:<port>/v1',
+    apiKey: '<placeholder-or-real>',
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: '<provider-specific-model-id>',
+  }),
+});
+
+// Use with any Dynamo OAI service:
+class MyChat extends DyNTS_OAI_LLM_ChatServiceBase {}
+const chat: MyChat = new MyChat(settings);
+```
+
+A kulcs: `config.baseURL` + `config.apiKey` + `defaultSettings.useModel`. A többi mező (organization, project) lokál provider-eknél figyelmen kívül marad.
+
+---
+
+## Provider-szekciók
+
+### 1. LM Studio — desktop GUI lokál LLM-hez
+
+[LM Studio](https://lmstudio.ai) Mac/Windows/Linux desktop app, beépített OAI-compat szerverrel. Default port: `1234`.
+
+**Beállítás**:
+1. LM Studio-ban betölteni egy modellt (pl. `nomic-embed-text-v1.5` embedding-hez, `llama-3.2-3b-instruct` chat-hez)
+2. "Local Server" tab → "Start Server"
+
+**Code**:
+```typescript
+const lmStudio: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localhost:1234/v1',
+    apiKey: 'lm-studio',  // tetszőleges placeholder — LM Studio ignorálja
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'nomic-embed-text-v1.5',  // ahogy a Local Server megjeleníti
+  }),
+});
+```
+
+**Tipikus jellemzők**:
+- ✅ GUI a modell-letöltéshez (HuggingFace integráció)
+- ✅ Streaming chat completion support
+- ⚠️ Embedding limit: a UI-n külön kell betölteni embedding modellt
+- ❌ Multi-tenant / production-flow nem támogatott
+
+---
+
+### 2. Ollama — CLI-driven lokál LLM (OAI-compat layer ≥ v0.1.14)
+
+[Ollama](https://ollama.com) parancssoros LLM-runner, OAI-compat layerrel. Default port: `11434`.
+
+**Beállítás**:
+```bash
+ollama pull llama3.2:3b
+ollama pull nomic-embed-text
+ollama serve  # vagy ha service-ként fut, már megy
+```
+
+**Code**:
+```typescript
+const ollama: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localhost:11434/v1',
+    apiKey: 'ollama',  // szintén placeholder — Ollama nem ellenőrzi
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'nomic-embed-text',
+  }),
+});
+```
+
+**Tipikus jellemzők**:
+- ✅ Multi-modell support (`ollama pull <name>` → azonnal elérhető endpointon)
+- ✅ Embedding endpoint OAI-compat formában működik (v0.1.14+ óta)
+- ✅ Streaming chat completion OK
+- ⚠️ `function_call` / `tools` API csak részben támogatott a tool-aware modelleknél (Llama-3 family OK; small instruct modellek may not)
+- ⚠️ Context-window provider-szintű limit (általában 2048-8192 tokens default-tal — `OLLAMA_NUM_CTX` env-var)
+
+---
+
+### 3. vLLM — production-grade GPU inference server
+
+[vLLM](https://docs.vllm.ai) Python alapú, batched + PagedAttention GPU-inference. OAI-compatible REST endpoint beépítve. Default port: `8000`.
+
+**Beállítás**:
+```bash
+pip install vllm
+python -m vllm.entrypoints.openai.api_server \
+  --model meta-llama/Meta-Llama-3-8B-Instruct \
+  --port 8000 \
+  --api-key local-secret-token
+```
+
+**Code**:
+```typescript
+const vllm: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://gpu-server:8000/v1',
+    apiKey: process.env.VLLM_API_KEY ?? 'local-secret-token',  // ha --api-key beállítva
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'meta-llama/Meta-Llama-3-8B-Instruct',  // a `--model` érték
+  }),
+});
+```
+
+**Tipikus jellemzők**:
+- ✅ Magas throughput (batched inference) — production scaling
+- ✅ Tool-calling support latest verziókban
+- ✅ Streaming OK
+- ⚠️ Egyszerre **egy** modell van memóriában (több modell = több instance)
+- ⚠️ Embedding endpoint NEM all modellnél — csak ha a model dedikált embedding (pl. `intfloat/e5-mistral-7b-instruct`)
+- ⚠️ GPU-szintű mem-management — OOM-ra dob, ha context-len túl nagy
+
+---
+
+### 4. LocalAI — REST-only multi-model platform
+
+[LocalAI](https://localai.io) Go-alapú, multi-backend (llama.cpp, whisper.cpp, stable-diffusion) REST szerver. OAI-compatible chat + embedding endpointokkal. Default port: `8080`.
+
+**Beállítás**:
+```bash
+docker run -p 8080:8080 \
+  -v $PWD/models:/build/models \
+  localai/localai:latest
+```
+
+Modellt vagy `models.yaml`-ban vagy runtime-on (`POST /models/apply`) lehet hozzáadni.
+
+**Code**:
+```typescript
+const localai: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localai:8080/v1',
+    apiKey: 'sk-local',  // placeholder
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'gpt-4',  // LocalAI alias → konfigban mapped a tényleges modellre
+  }),
+});
+```
+
+**Tipikus jellemzők**:
+- ✅ Egyszerre több modell loadolva — modell-aliasok
+- ✅ Multi-backend (LLM + Whisper transcribe + image-gen ugyanazon szerverről)
+- ✅ Streaming OK
+- ⚠️ A modell-aliasok kézi konfig kérdése — a `useModel` ID-nek pontosan match-elnie kell a `models.yaml`-ban definiálttal
+- ⚠️ Lassabb felpörgés gpu-acceleration nélkül (CPU-fallback default)
+
+---
+
+## Embedding modellek — provider-specifikus
+
+Az embedding-modell nevének **pontos egyezést** kell mutatnia a provider által regisztrált name-mel. Példák:
+
+| Provider | Embedding model ID | Megjegyzés |
+|---|---|---|
+| OpenAI (cloud) | `text-embedding-3-small`, `text-embedding-3-large` | Default |
+| LM Studio | `nomic-embed-text-v1.5`, `BAAI/bge-large-en-v1.5` | A betöltött modell ID-jét a Local Server tab írja ki |
+| Ollama | `nomic-embed-text`, `mxbai-embed-large` | `ollama list` mutatja |
+| vLLM | `intfloat/e5-mistral-7b-instruct` | Csak ha az indítási `--model` embedding-képes |
+| LocalAI | `text-embedding-ada-002` (aliasként) | A `models.yaml`-ban definiált alias |
+
+A `DyNTS_OAI_Embedding_ControlService` API-szintjén nem érzékeli a különbséget — a `useModel` field határoz meg mindent.
+
+---
+
+## Caveats — amire figyelni kell
+
+### Rate limits
+- **OpenAI**: tier-szintű, API-doc-ban
+- **LM Studio / Ollama / LocalAI**: nincs natív rate-limit — single-user dev tool
+- **vLLM**: konfigurálható (`--max-num-seqs` flag), default kvázi-unlimited
+
+### Max tokens / context window
+A `DyFM_OAI_CallSettings.maxTokens` provider-szintű limit alá kell hogy essen, különben az SDK 400/422-t kap:
+
+| Provider | Default context-window | Override |
+|---|---|---|
+| OpenAI gpt-4o | 128K | API tier-függő |
+| LM Studio | a betöltött modell native context-je | UI slider |
+| Ollama | 2048 (legacy default!) → `num_ctx` paraméter | `OLLAMA_NUM_CTX` env-var vagy `Modelfile` `PARAMETER num_ctx` |
+| vLLM | a modell native context-je | `--max-model-len` flag |
+| LocalAI | `models.yaml` `context_size` field | per-model konfig |
+
+### Error-handling különbségek
+- **OpenAI**: standard 400/401/403/429/500 + structured error body
+- **Lokál providerek**: gyakran **404 a modell-name-re** (ha rosszul ID-zed), **timeout** (modell-loadolás közben), **OOM** (vLLM)
+- **Ollama-specifikus**: ha a modell még nem `ollama pull`-olt, az endpoint csendben várakozik a pull-ig (lassú first-call)
+- **LocalAI**: model-name mismatch → 422-t dob OAI-szerű error-body-val
+
+### Function-calling / tool-use
+- **OpenAI**: teljes function-calling support
+- **Ollama**: model-függő — Llama-3.1+ és Mistral tool-aware modellek igen, kicsi instruct modellek nem
+- **vLLM**: support latest (v0.6+), de chat-template-mappel paraméterezni kell
+- **LM Studio / LocalAI**: parciális, model-függő
+
+### Streaming
+Mind a 4 provider támogat OAI-compat SSE streaming-et, **de**:
+- Ollama legacy verziók (< v0.1.20) `stream: false`-cal stabilabb
+- LocalAI streaming-rate alacsonyabb mint a token-emission
+
+---
+
+## Quick recipe — Dynamo-szintű váltás dev → cloud
+
+```typescript
+const isDev: boolean = process.env.NODE_ENV === 'development';
+
+const aiSettings: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: isDev
+    ? {
+        baseURL: 'http://localhost:11434/v1',  // Ollama
+        apiKey: 'dev',
+      }
+    : {
+        apiKey: process.env.OPENAI_API_KEY,
+        organization: process.env.OPENAI_ORG_ID,
+      },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: isDev ? 'llama3.2:3b' : 'gpt-4o',
+  }),
+});
+```
+
+A Dynamo OAI service-ek mindkét beállítással ugyanúgy működnek.
+
+---
+
+## Hivatkozott source-fájlok
+
+| Fájl | Mit ad |
+|---|---|
+| `fsm-dynamo/src/_modules/ai/_modules/open-ai/_models/oai-client-options.interface.ts` | `DyFM_OAI_ClientOptions.baseURL` mező |
+| `fsm-dynamo/src/_modules/ai/_modules/open-ai/_models/oai-settings.control-model.ts` | `DyFM_OAI_Settings` wrapper |
+| `dynamo-nts/src/_modules/ai/_modules/open-ai/_services/oai-llm.service-base.ts` | OpenAI SDK instantiation (config átadás) |
+| `dynamo-nts/src/_modules/ai/_modules/open-ai/_services/oai-embedding.control-service.ts` | Embedding endpoint usage |
+
+## Backward compatibility
+
+A `baseURL` mező mindig is létezett az OpenAI SDK-ban — a Dynamo egyetlen változtatása ehhez a docs-ot tisztázza, nem feature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "01.15.9",
+  "version": "01.15.10",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",