@futdevpro/fsm-dynamo 1.15.15 → 1.15.17

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

@@ -0,0 +1,63 @@
+import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelCapabilities } from './ai-model-capabilities.interface';
+import { DyFM_AI_ModelSettingsSchema } from './ai-model-settings-schema.interface';
+
+/**
+ * Lifecycle status of a model in the provider's catalogue.
+ *
+ * `ga` — generally available, recommended for new work.
+ * `preview` — available but pre-GA (API/behaviour may change).
+ * `deprecated` — still callable but on a sunset path; prefer {@link DyFM_AI_ModelInfo.successorId}.
+ */
+export type DyFM_AI_ModelStatus = 'ga' | 'preview' | 'deprecated';
+
+/**
+ * Single-model descriptor for the provider model registry.
+ *
+ * The provider registries (`DyFM_OAI_Models`, `DyFM_AAI_Models`, …) are arrays
+ * of these — an SDK-free, data-only source of truth for which models exist and
+ * what each can do. The bare model enums (`DyFM_OAI_Model`, …) remain the typed
+ * id keys; a registry entry's `id` references one of those values.
+ *
+ * Note: model line-ups churn fast (see the 2026-06 research) — keep the registry
+ * current and rely on `status`/`successorId` rather than silently breaking on a
+ * retired id.
+ */
+export interface DyFM_AI_ModelInfo {
+  /** Exact API model string (e.g. 'gpt-5.5', 'claude-opus-4-8', 'gemini-3.5-flash'). */
+  id: string;
+  /** The provider that serves this model. */
+  provider: DyFM_AI_Provider;
+  /** The kind of model (chat / embedding / image / audio). */
+  modelType: DyFM_AI_ModelType;
+  /** What this specific model can DO (feature gates). */
+  capabilities: DyFM_AI_ModelCapabilities;
+  /**
+   * RESERVED (FR-048) — which tuning PARAMETERS this model accepts/rejects.
+   *
+   * Sibling of {@link capabilities}. NOT populated by FR-047 and NOT yet
+   * consumed by any reconciler — reserved space for the future per-model
+   * agnostic settings system. Each model accepts a different settings surface
+   * (e.g. Opus 4.7+ rejects temperature/topP/topK; reasoning models add
+   * reasoningEffort), and that knowledge must be curated continuously like the
+   * model registry itself.
+   *
+   * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
+   */
+  settingsSchema?: DyFM_AI_ModelSettingsSchema;
+  /** Input context window in tokens, if applicable. */
+  contextWindow?: number;
+  /** Maximum output tokens, if applicable. */
+  maxOutputTokens?: number;
+  /** Lifecycle status; defaults to `ga` when omitted. */
+  status?: DyFM_AI_ModelStatus;
+  /** When `deprecated`/sunsetting, the recommended replacement model id. */
+  successorId?: string;
+  /** When `deprecated`, the earliest known shutdown date (ISO yyyy-mm-dd). */
+  sunsetDate?: string;
+  /** Human-readable name for UI (e.g. 'GPT-5.5', 'Claude Opus 4.8'). */
+  displayName?: string;
+  /** Provider-specific tier label (e.g. 'flagship', 'mini', 'Opus', 'Sonnet', 'Haiku'). */
+  tier?: string;
+}

package/src/_modules/ai/_models/ai-model-settings-schema.interface.ts

@@ -0,0 +1,52 @@
+/**
+ * RESERVED — per-model settings schema (FR-048; NOT implemented by FR-047).
+ *
+ * Sibling of {@link DyFM_AI_ModelCapabilities}: capabilities describe what a
+ * model can DO; this describes which tuning PARAMETERS it accepts, their
+ * bounds, and which it REJECTS. A flat {@link DyFM_AI_CallSettings} bag cannot
+ * express this, yet sending an unsupported param can hard-fail a call (e.g.
+ * Anthropic Opus 4.7+ rejects `temperature`/`top_p`/`top_k` with HTTP 400).
+ *
+ * This type reserves the architectural space and documents intent. The
+ * registry consts do NOT populate `settingsSchema` yet, and no reconciler
+ * consumes it yet — both are FR-048 work. The exact shape may evolve when
+ * FR-048 is built; treat this as a forward placeholder, not a frozen contract.
+ *
+ * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
+ *      `documentations/guidelines/development/ai-per-model-settings.md`
+ */
+export interface DyFM_AI_ModelSettingsSchema {
+  /** Agnostic setting keys this model ACCEPTS (e.g. 'temperature','topP','maxTokens','reasoningEffort'). */
+  supported?: string[];
+  /**
+   * Agnostic setting keys this model REJECTS — sending them errors.
+   * Example: Opus 4.7+ → ['temperature','topP','topK'] (HTTP 400 on non-default).
+   * The future reconciler drops these (debug-log, never silently).
+   */
+  unsupported?: string[];
+  /** Per-key value constraints (range / enum / default). */
+  constraints?: Record<string, DyFM_AI_SettingConstraint>;
+  /**
+   * Provider/model-specific knobs NOT present on the agnostic CallSettings
+   * (e.g. OpenAI 'reasoningEffort', Gemini 'thinkingConfig'). The provider
+   * translator maps these to the native param.
+   */
+  extraParams?: string[];
+}
+
+/**
+ * RESERVED (FR-048) — value constraint for a single tuning parameter.
+ * Forward placeholder; shape may evolve when FR-048 is built.
+ */
+export interface DyFM_AI_SettingConstraint {
+  /** Minimum numeric value (inclusive), if applicable. */
+  min?: number;
+  /** Maximum numeric value (inclusive), if applicable. */
+  max?: number;
+  /** Default value the provider applies when omitted. */
+  default?: unknown;
+  /** Allowed discrete values (enum-like params, e.g. reasoningEffort). */
+  allowed?: unknown[];
+  /** Free-text note (Hunglish ok) — e.g. provider quirk, version gate. */
+  note?: string;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * A normalized tool invocation requested by the model.
+ *
+ * Each provider's native shape is normalized into this at the translator boundary:
+ *  - OpenAI:    message.tool_calls[] → { id, name, arguments: JSON.parse(function.arguments) }
+ *  - Anthropic: content[] { type:'tool_use', id, name, input } → { id, name, arguments: input }
+ *  - Gemini:    parts[].functionCall { id, name, args } → { id, name, arguments: args }
+ *
+ * `arguments` is ALWAYS a parsed object (OpenAI's JSON string is parsed at the boundary).
+ */
+export interface DyFM_AI_ToolCall {
+  /** Provider call id — echoed back when returning the result. */
+  id: string;
+  /** The invoked tool's name. */
+  name: string;
+  /** Parsed arguments object. */
+  arguments: Record<string, unknown>;
+}

package/src/_modules/ai/_models/ai-tool-handler.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Handler for a single function-calling tool — receives the parsed arguments
+ * (JSON already parsed) and returns the tool result as a string (which is fed
+ * back to the model). Generalized from the proven legacy `FDPNTS_GPT_ToolHandler`.
+ */
+export type DyFM_AI_ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
+
+/**
+ * Tool-name → handler registration for the `requestWithTools` agent-loop.
+ */
+export type DyFM_AI_ToolHandlers = Record<string, DyFM_AI_ToolHandler>;

package/src/_modules/ai/_models/ai-tool-result.interface.ts

@@ -0,0 +1,16 @@
+/**
+ * The result of executing a tool, fed back to the model.
+ *
+ * Translated per provider:
+ *  - OpenAI:    { role:'tool', tool_call_id: toolCallId, content }
+ *  - Anthropic: content block { type:'tool_result', tool_use_id: toolCallId, content, is_error: isError }
+ *  - Gemini:    part { functionResponse: { id: toolCallId, name, response: { result: content } } }
+ */
+export interface DyFM_AI_ToolResult {
+  /** Must echo the originating {@link DyFM_AI_ToolCall.id}. */
+  toolCallId: string;
+  /** The tool's output (or an error message — see {@link isError}). */
+  content: string;
+  /** True when the tool failed; the model is told so it can correct. */
+  isError?: boolean;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Provider-neutral tool (function) definition for native function calling.
+ *
+ * One agnostic shape, translated per provider by the execution layer:
+ *  - OpenAI-wire: → { type:'function', function:{ name, description, parameters } }
+ *  - Anthropic:   → { name, description, input_schema: parameters }
+ *  - Gemini:      → tools:[{ functionDeclarations:[{ name, description, parameters }] }]
+ */
+export interface DyFM_AI_Tool {
+  /** Function name. No spaces / special chars (Gemini constraint). */
+  name: string;
+  /** What the tool does — the model uses this to decide when to call it. */
+  description: string;
+  /** JSON Schema (object schema) describing the arguments. Translated to each provider's param shape. */
+  parameters: object;
+}

package/src/_modules/ai/_modules/anthropic/_collections/aai-models.const.ts

@@ -0,0 +1,78 @@
+import { DyFM_AI_Provider } from '../../../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../../../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelInfo } from '../../../_models/ai-model-info.interface';
+import { DyFM_AAI_Model } from '../_enums/aai-model.enum';
+
+/**
+ * Anthropic Claude model registry — verified 2026-06-01 against platform.claude.com docs.
+ *
+ * All Claude models are chat (Messages API) models — Anthropic has NO embeddings API.
+ * Tool use is universal (content-block `tool_use` / `tool_result` wire format).
+ * Anthropic has no dedicated JSON-mode flag (structured output is done via tools),
+ * so `jsonMode` is false across the board.
+ *
+ * Param note (translator): Opus 4.7+ reject `temperature`/`top_p`/`top_k` with 400 —
+ * not modelled here, handled in the Anthropic call translator.
+ */
+export const DyFM_AAI_Models: DyFM_AI_ModelInfo[] = [
+  {
+    id: DyFM_AAI_Model.claude_opus_4_8,
+    provider: DyFM_AI_Provider.Anthropic,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Claude Opus 4.8',
+    tier: 'Opus',
+    status: 'ga',
+    contextWindow: 1_000_000,
+    maxOutputTokens: 128_000,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_AAI_Model.claude_sonnet_4_6,
+    provider: DyFM_AI_Provider.Anthropic,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Claude Sonnet 4.6',
+    tier: 'Sonnet',
+    status: 'ga',
+    contextWindow: 1_000_000,
+    maxOutputTokens: 64_000,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_AAI_Model.claude_haiku_4_5,
+    provider: DyFM_AI_Provider.Anthropic,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Claude Haiku 4.5',
+    tier: 'Haiku',
+    status: 'ga',
+    contextWindow: 200_000,
+    maxOutputTokens: 64_000,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+];

package/src/_modules/ai/_modules/anthropic/_enums/aai-model.enum.ts

@@ -1,5 +1,13 @@
 // Based on @anthropic-ai/sdk model identifiers
 export enum DyFM_AAI_Model {
+  // Current GA (verified 2026-06). From the 4.6 generation the ids are
+  // dateless-but-pinned snapshots — there is NO `-latest` alias for these.
+  claude_opus_4_8 = 'claude-opus-4-8',
+  claude_sonnet_4_6 = 'claude-sonnet-4-6',
+  claude_haiku_4_5 = 'claude-haiku-4-5',
+  claude_haiku_4_5_20251001 = 'claude-haiku-4-5-20251001',
+
+  // Legacy / retired (kept for back-compat; NOT in the active registry)
   claude_3_5_sonnet_latest = 'claude-3-5-sonnet-latest',
   claude_3_5_sonnet_20241022 = 'claude-3-5-sonnet-20241022',
   claude_3_5_haiku_latest = 'claude-3-5-haiku-latest',

package/src/_modules/ai/_modules/anthropic/index.ts

@@ -1,3 +1,6 @@
+// COLLECTIONS
+export * from './_collections/aai-models.const';
+
 // ENUMS
 export * from './_enums/aai-model.enum';
 

package/src/_modules/ai/_modules/fdp-ai/_collections/fdpai-models.const.ts

@@ -0,0 +1,33 @@
+import { DyFM_AI_Provider } from '../../../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../../../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelInfo } from '../../../_models/ai-model-info.interface';
+import { DyFM_FdpAI_Model } from '../_enums/fdpai-model.enum';
+
+/**
+ * FDP-AI model registry.
+ *
+ * FDP-AI is an internal, OpenAI-wire-compatible HTTP gateway (`/chat/completions`),
+ * so tool calling follows the OpenAI format. Capabilities ultimately depend on the
+ * backing gateway/model — `functionCalling` is declared true on the assumption the
+ * gateway forwards OpenAI-style tools; confirm against the live FDP-AI deployment.
+ * Context window is gateway-defined and therefore left unset.
+ */
+export const DyFM_FdpAI_Models: DyFM_AI_ModelInfo[] = [
+  {
+    id: DyFM_FdpAI_Model.fdpBase1,
+    provider: DyFM_AI_Provider.FdpAI,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'FDP Base 1',
+    status: 'ga',
+    capabilities: {
+      functionCalling: true, // OpenAI-wire compatible — verify against the live gateway
+      vision: false,
+      streaming: true,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+];

package/src/_modules/ai/_modules/fdp-ai/index.ts

@@ -1,3 +1,6 @@
+// COLLECTIONS
+export * from './_collections/fdpai-models.const';
+
 // ENUMS
 export * from './_enums/fdpai-model.enum';
 

package/src/_modules/ai/_modules/google-ai/_collections/gai-models.const.ts

@@ -0,0 +1,95 @@
+import { DyFM_AI_Provider } from '../../../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../../../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelInfo } from '../../../_models/ai-model-info.interface';
+import { DyFM_GAI_Model } from '../_enums/gai-model.enum';
+
+/**
+ * Google Gemini model registry — verified 2026-06-01 against ai.google.dev docs.
+ *
+ * SDK note: depend on `@google/genai` (the old `@google/generative-ai` was sunset
+ * 2025-11-30). Tool use via `functionDeclarations`; tool results are returned under
+ * a `user`-role `functionResponse` part (no dedicated tool role).
+ *
+ * Video input is a real Gemini capability but is not yet modelled in
+ * {@link DyFM_AI_ModelCapabilities} — `vision` covers image input only.
+ */
+export const DyFM_GAI_Models: DyFM_AI_ModelInfo[] = [
+  {
+    id: DyFM_GAI_Model.gemini_3_5_flash,
+    provider: DyFM_AI_Provider.Google,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Gemini 3.5 Flash',
+    tier: 'flash',
+    status: 'ga',
+    contextWindow: 1_048_576,
+    maxOutputTokens: 65_536,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: true,
+      audioInput: true,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_GAI_Model.gemini_3_1_pro_preview,
+    provider: DyFM_AI_Provider.Google,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Gemini 3.1 Pro (preview)',
+    tier: 'pro',
+    status: 'preview',
+    contextWindow: 1_048_576,
+    maxOutputTokens: 65_536,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: true,
+      audioInput: true,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_GAI_Model.gemini_3_1_flash_lite,
+    provider: DyFM_AI_Provider.Google,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Gemini 3.1 Flash-Lite',
+    tier: 'flash-lite',
+    status: 'ga',
+    contextWindow: 1_048_576,
+    maxOutputTokens: 65_536,
+    capabilities: {
+      functionCalling: true,
+      vision: true,
+      streaming: true,
+      jsonMode: true,
+      audioInput: true,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_GAI_Model.gemini_embedding_2,
+    provider: DyFM_AI_Provider.Google,
+    modelType: DyFM_AI_ModelType.Embedding,
+    displayName: 'Gemini Embedding 2',
+    status: 'ga',
+    contextWindow: 8_192,
+    capabilities: {
+      functionCalling: false,
+      vision: true, // multimodal embedding (text / image / audio)
+      streaming: false,
+      jsonMode: false,
+      audioInput: true,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: true,
+    },
+  },
+];

package/src/_modules/ai/_modules/google-ai/_enums/gai-model.enum.ts

@@ -1,5 +1,13 @@
-// Based on @google/generative-ai model identifiers
+// Based on the @google/genai SDK model identifiers
+// (the older @google/generative-ai SDK was sunset 2025-11-30).
 export enum DyFM_GAI_Model {
+  // Current (verified 2026-06)
+  gemini_3_5_flash = 'gemini-3.5-flash',
+  gemini_3_1_pro_preview = 'gemini-3.1-pro-preview',
+  gemini_3_1_flash_lite = 'gemini-3.1-flash-lite',
+  gemini_embedding_2 = 'gemini-embedding-2',
+
+  // Legacy (deprecated / removed from the active line-up)
   gemini_1_5_pro_latest = 'gemini-1.5-pro-latest',
   gemini_1_5_flash_latest = 'gemini-1.5-flash-latest',
   text_embedding_004 = 'text-embedding-004',

package/src/_modules/ai/_modules/google-ai/index.ts

@@ -1,3 +1,6 @@
+// COLLECTIONS
+export * from './_collections/gai-models.const';
+
 // ENUMS
 export * from './_enums/gai-model.enum';
 

package/src/_modules/ai/_modules/local-ai/_collections/lai-models.const.ts

@@ -0,0 +1,51 @@
+import { DyFM_AI_Provider } from '../../../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../../../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelInfo } from '../../../_models/ai-model-info.interface';
+import { DyFM_LAI_Model } from '../_enums/lai-model.enum';
+
+/**
+ * Local-AI model registry.
+ *
+ * Local models are served by a self-hosted, OpenAI-wire-compatible server
+ * (lm-studio / ollama / vllm). These are GENERIC descriptors — the real
+ * capabilities depend entirely on the model the user has loaded at runtime.
+ * In particular `functionCalling` is left FALSE here because many local models
+ * do not support tool calling; it must be confirmed per loaded model rather than
+ * assumed. Context window is model-defined and therefore left unset.
+ */
+export const DyFM_LAI_Models: DyFM_AI_ModelInfo[] = [
+  {
+    id: DyFM_LAI_Model.generic_llm,
+    provider: DyFM_AI_Provider.LocalAI,
+    modelType: DyFM_AI_ModelType.Chat,
+    displayName: 'Local generic LLM',
+    status: 'ga',
+    capabilities: {
+      functionCalling: false, // runtime/model-dependent — confirm per loaded model
+      vision: false,
+      streaming: true,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: false,
+    },
+  },
+  {
+    id: DyFM_LAI_Model.text_embedding,
+    provider: DyFM_AI_Provider.LocalAI,
+    modelType: DyFM_AI_ModelType.Embedding,
+    displayName: 'Local text embedding',
+    status: 'ga',
+    capabilities: {
+      functionCalling: false,
+      vision: false,
+      streaming: false,
+      jsonMode: false,
+      audioInput: false,
+      audioOutput: false,
+      imageGeneration: false,
+      embeddings: true,
+    },
+  },
+];

package/src/_modules/ai/_modules/local-ai/index.ts

@@ -1,3 +1,6 @@
+// COLLECTIONS
+export * from './_collections/lai-models.const';
+
 // ENUMS
 export * from './_enums/lai-model.enum';