@objectstack/service-ai 6.5.1 → 6.7.0

package/dist/index.d.cts

@@ -293,7 +293,7 @@ interface AIServiceConfig {
  * the {@link AIServicePlugin}.
  */
 declare class AIService implements IAIService {
-    private readonly adapter;
+    private adapter;
     private readonly logger;
     readonly toolRegistry: ToolRegistry;
     readonly conversationService: IAIConversationService;
@@ -311,6 +311,13 @@ declare class AIService implements IAIService {
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
+    /**
+     * Hot-swap the LLM adapter. Used by AIServicePlugin when the `ai`
+     * settings namespace changes (provider/key/model edited via Setup UI).
+     * In-flight requests bound to the previous adapter complete normally;
+     * subsequent calls go through the new adapter.
+     */
+    setAdapter(next: LLMAdapter): void;
     /**
      * Best-effort persistence of a single chat message to the conversation
      * store. Failures are logged at warn level and swallowed — chat requests
@@ -451,6 +458,14 @@ interface AIServicePluginOptions {
      * until an operator explicitly enables this routing).
      */
     enableActionApproval?: boolean;
+    /**
+     * Bind to the `ai` settings namespace and rebuild the LLM adapter on
+     * every `settings:changed` event. When enabled (default), operators
+     * can edit provider/credentials/model via the Setup app and the
+     * change applies live without restart. Disable to lock the adapter
+     * to whatever was resolved at boot (constructor option or env var).
+     */
+    bindToSettings?: boolean;
 }
 /**
  * AIServicePlugin — Kernel plugin for the unified AI capability service.
@@ -483,6 +498,25 @@ declare class AIServicePlugin implements Plugin {
     private service?;
     private readonly options;
     constructor(options?: AIServicePluginOptions);
+    /**
+     * Build an LLM adapter from a provider/key/model triple. Used both
+     * by the boot-time auto-detect path and by the live `settings:changed`
+     * rebuild path. Returns `null` if the requested provider cannot be
+     * loaded or required credentials are missing.
+     */
+    private buildAdapterFromValues;
+    /**
+     * Build an `IEmbedder` instance from embedder settings values
+     * (`embedder_provider`, `embedder_api_key`, …) by dynamically
+     * importing `@objectstack/embedder-openai`. Returns `null` for
+     * `none` (embedder disabled) or when required credentials are
+     * missing / the package isn't installed.
+     *
+     * The OpenAI-compatible plugin covers OpenAI, Azure, 阿里通义,
+     * 智谱, 硅基流动, 火山 Doubao, MiniMax, Ollama, and any custom
+     * OpenAI-shape endpoint via `embedder_base_url`.
+     */
+    private buildEmbedderFromValues;
     /**
      * Auto-detect LLM provider from environment variables.
      *
@@ -498,6 +532,12 @@ declare class AIServicePlugin implements Plugin {
     private detectAdapter;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * Resolve the `settings` service, apply any persisted `ai` values,
+     * subscribe to changes, and register the live `ai/test` action
+     * (overrides the manifest's fallback stub).
+     */
+    private bindSettings;
     destroy(): Promise<void>;
 }
 

package/dist/index.d.ts

@@ -293,7 +293,7 @@ interface AIServiceConfig {
  * the {@link AIServicePlugin}.
  */
 declare class AIService implements IAIService {
-    private readonly adapter;
+    private adapter;
     private readonly logger;
     readonly toolRegistry: ToolRegistry;
     readonly conversationService: IAIConversationService;
@@ -311,6 +311,13 @@ declare class AIService implements IAIService {
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
+    /**
+     * Hot-swap the LLM adapter. Used by AIServicePlugin when the `ai`
+     * settings namespace changes (provider/key/model edited via Setup UI).
+     * In-flight requests bound to the previous adapter complete normally;
+     * subsequent calls go through the new adapter.
+     */
+    setAdapter(next: LLMAdapter): void;
     /**
      * Best-effort persistence of a single chat message to the conversation
      * store. Failures are logged at warn level and swallowed — chat requests
@@ -451,6 +458,14 @@ interface AIServicePluginOptions {
      * until an operator explicitly enables this routing).
      */
     enableActionApproval?: boolean;
+    /**
+     * Bind to the `ai` settings namespace and rebuild the LLM adapter on
+     * every `settings:changed` event. When enabled (default), operators
+     * can edit provider/credentials/model via the Setup app and the
+     * change applies live without restart. Disable to lock the adapter
+     * to whatever was resolved at boot (constructor option or env var).
+     */
+    bindToSettings?: boolean;
 }
 /**
  * AIServicePlugin — Kernel plugin for the unified AI capability service.
@@ -483,6 +498,25 @@ declare class AIServicePlugin implements Plugin {
     private service?;
     private readonly options;
     constructor(options?: AIServicePluginOptions);
+    /**
+     * Build an LLM adapter from a provider/key/model triple. Used both
+     * by the boot-time auto-detect path and by the live `settings:changed`
+     * rebuild path. Returns `null` if the requested provider cannot be
+     * loaded or required credentials are missing.
+     */
+    private buildAdapterFromValues;
+    /**
+     * Build an `IEmbedder` instance from embedder settings values
+     * (`embedder_provider`, `embedder_api_key`, …) by dynamically
+     * importing `@objectstack/embedder-openai`. Returns `null` for
+     * `none` (embedder disabled) or when required credentials are
+     * missing / the package isn't installed.
+     *
+     * The OpenAI-compatible plugin covers OpenAI, Azure, 阿里通义,
+     * 智谱, 硅基流动, 火山 Doubao, MiniMax, Ollama, and any custom
+     * OpenAI-shape endpoint via `embedder_base_url`.
+     */
+    private buildEmbedderFromValues;
     /**
      * Auto-detect LLM provider from environment variables.
      *
@@ -498,6 +532,12 @@ declare class AIServicePlugin implements Plugin {
     private detectAdapter;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * Resolve the `settings` service, apply any persisted `ai` values,
+     * subscribe to changes, and register the live `ai/test` action
+     * (overrides the manifest's fallback stub).
+     */
+    private bindSettings;
     destroy(): Promise<void>;
 }
 

package/dist/index.js

@@ -1443,6 +1443,19 @@ var _AIService = class _AIService {
   get adapterName() {
     return this.adapter.name;
   }
+  /**
+   * Hot-swap the LLM adapter. Used by AIServicePlugin when the `ai`
+   * settings namespace changes (provider/key/model edited via Setup UI).
+   * In-flight requests bound to the previous adapter complete normally;
+   * subsequent calls go through the new adapter.
+   */
+  setAdapter(next) {
+    const prev = this.adapter.name;
+    this.adapter = next;
+    if (prev !== next.name) {
+      this.logger.info(`[AI] LLM adapter swapped: ${prev} \u2192 ${next.name}`);
+    }
+  }
   /**
    * Best-effort persistence of a single chat message to the conversation
    * store. Failures are logged at warn level and swallowed — chat requests
@@ -1934,6 +1947,9 @@ function cryptoRandomId() {
   return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+// src/plugin.ts
+import { EMBEDDER_SERVICE } from "@objectstack/spec/contracts";
+
 // src/stream/vercel-stream-encoder.ts
 function sse(data) {
   return `data: ${JSON.stringify(data)}
@@ -5349,6 +5365,136 @@ var AIServicePlugin = class {
     this.dependencies = ["com.objectstack.engine.objectql"];
     this.options = options;
   }
+  /**
+   * Build an LLM adapter from a provider/key/model triple. Used both
+   * by the boot-time auto-detect path and by the live `settings:changed`
+   * rebuild path. Returns `null` if the requested provider cannot be
+   * loaded or required credentials are missing.
+   */
+  async buildAdapterFromValues(ctx, values) {
+    const provider = String(values.provider ?? "memory");
+    if (provider === "memory") {
+      return { adapter: new MemoryLLMAdapter(), description: "MemoryLLMAdapter (echo mode)" };
+    }
+    if (provider === "gateway") {
+      const gatewayModel = String(values.gateway_model ?? "").trim();
+      if (!gatewayModel) return null;
+      try {
+        const gatewayPkg = "@ai-sdk/gateway";
+        const { gateway } = await import(
+          /* webpackIgnore: true */
+          gatewayPkg
+        );
+        return {
+          adapter: new VercelLLMAdapter({ model: gateway(gatewayModel) }),
+          description: `Vercel AI Gateway (model: ${gatewayModel})`
+        };
+      } catch (err) {
+        ctx.logger.warn(
+          `[AI] Failed to load @ai-sdk/gateway for provider=gateway`,
+          err instanceof Error ? { error: err.message } : void 0
+        );
+        return null;
+      }
+    }
+    const providerSpecs = {
+      openai: { pkg: "@ai-sdk/openai", factory: "openai", defaultModel: "gpt-4o", displayName: "OpenAI" },
+      anthropic: { pkg: "@ai-sdk/anthropic", factory: "anthropic", defaultModel: "claude-sonnet-4-20250514", displayName: "Anthropic" },
+      google: { pkg: "@ai-sdk/google", factory: "google", defaultModel: "gemini-2.0-flash", displayName: "Google" }
+    };
+    const spec = providerSpecs[provider];
+    if (!spec) return null;
+    const apiKey = String(values[`${provider}_api_key`] ?? "").trim();
+    if (!apiKey) return null;
+    const envKey = provider === "openai" ? "OPENAI_API_KEY" : provider === "anthropic" ? "ANTHROPIC_API_KEY" : "GOOGLE_GENERATIVE_AI_API_KEY";
+    process.env[envKey] = apiKey;
+    try {
+      const mod = await import(
+        /* webpackIgnore: true */
+        spec.pkg
+      );
+      const factory = mod[spec.factory] ?? mod.default;
+      if (typeof factory !== "function") return null;
+      const modelId = String(values[`${provider}_model`] ?? "").trim() || spec.defaultModel;
+      const useChatApi = provider === "openai" && typeof factory.chat === "function";
+      const model = useChatApi ? factory.chat(modelId) : factory(modelId);
+      const apiSuffix = useChatApi ? " [chat-completions]" : "";
+      return {
+        adapter: new VercelLLMAdapter({ model }),
+        description: `${spec.displayName} (model: ${modelId})${apiSuffix}`
+      };
+    } catch (err) {
+      ctx.logger.warn(
+        `[AI] Failed to load ${spec.pkg} for provider=${provider}`,
+        err instanceof Error ? { error: err.message } : void 0
+      );
+      return null;
+    }
+  }
+  /**
+   * Build an `IEmbedder` instance from embedder settings values
+   * (`embedder_provider`, `embedder_api_key`, …) by dynamically
+   * importing `@objectstack/embedder-openai`. Returns `null` for
+   * `none` (embedder disabled) or when required credentials are
+   * missing / the package isn't installed.
+   *
+   * The OpenAI-compatible plugin covers OpenAI, Azure, 阿里通义,
+   * 智谱, 硅基流动, 火山 Doubao, MiniMax, Ollama, and any custom
+   * OpenAI-shape endpoint via `embedder_base_url`.
+   */
+  async buildEmbedderFromValues(ctx, values) {
+    const provider = String(values.embedder_provider ?? "none").trim();
+    if (!provider || provider === "none") return null;
+    const apiKey = String(values.embedder_api_key ?? "").trim();
+    const model = String(values.embedder_model ?? "").trim() || void 0;
+    const baseUrlOverride = String(values.embedder_base_url ?? "").trim() || void 0;
+    const dimensions = values.embedder_dimensions != null && values.embedder_dimensions !== "" ? Number(values.embedder_dimensions) : void 0;
+    if (!apiKey && provider !== "ollama") {
+      ctx.logger.warn(
+        `[AI] Embedder provider=${provider} requires embedder_api_key \u2014 embedder unchanged.`
+      );
+      return null;
+    }
+    if ((provider === "custom" || provider === "azure") && !baseUrlOverride) {
+      ctx.logger.warn(
+        `[AI] Embedder provider=${provider} requires embedder_base_url \u2014 embedder unchanged.`
+      );
+      return null;
+    }
+    try {
+      const pkg = "@objectstack/embedder-openai";
+      const mod = await import(
+        /* webpackIgnore: true */
+        pkg
+      );
+      const create = mod.createOpenAIEmbedder ?? mod.default?.createOpenAIEmbedder;
+      if (typeof create !== "function") {
+        ctx.logger.warn(
+          `[AI] ${pkg} did not export createOpenAIEmbedder \u2014 embedder unchanged.`
+        );
+        return null;
+      }
+      const embedder = create({
+        preset: provider === "custom" ? void 0 : provider,
+        baseUrl: baseUrlOverride,
+        apiKey: apiKey || "ollama",
+        model,
+        dimensions: Number.isFinite(dimensions) ? dimensions : void 0,
+        id: provider
+      });
+      const dimsLabel = embedder.dimensions ? `dims=${embedder.dimensions}` : "dims=?";
+      return {
+        embedder,
+        description: `OpenAI-compatible embedder (provider=${provider}${model ? `, model=${model}` : ""}, ${dimsLabel})`
+      };
+    } catch (err) {
+      ctx.logger.warn(
+        `[AI] Failed to load @objectstack/embedder-openai for embedder provider=${provider}`,
+        err instanceof Error ? { error: err.message } : void 0
+      );
+      return null;
+    }
+  }
   /**
    * Auto-detect LLM provider from environment variables.
    *
@@ -5768,6 +5914,179 @@ var AIServicePlugin = class {
     ctx.logger.info(
       `[AI] Service started \u2014 adapter="${this.service.adapterName}", tools=${this.service.toolRegistry.size}, routes=${routes.length}`
     );
+    if (this.options.bindToSettings !== false) {
+      ctx.hook("kernel:ready", async () => {
+        await this.bindSettings(ctx);
+      });
+    }
+  }
+  /**
+   * Resolve the `settings` service, apply any persisted `ai` values,
+   * subscribe to changes, and register the live `ai/test` action
+   * (overrides the manifest's fallback stub).
+   */
+  async bindSettings(ctx) {
+    if (!this.service) return;
+    let settings;
+    try {
+      settings = ctx.getService("settings");
+    } catch {
+      return;
+    }
+    if (!settings || typeof settings.getNamespace !== "function") return;
+    const applySettings = async () => {
+      if (!this.service) return;
+      try {
+        const payload = await settings.getNamespace("ai");
+        const values = {};
+        for (const [k, v] of Object.entries(payload.values)) {
+          values[k] = v?.value;
+        }
+        const provider = String(values.provider ?? "memory");
+        if (provider === "memory") return;
+        const built = await this.buildAdapterFromValues(ctx, values);
+        if (!built) {
+          ctx.logger.warn(
+            `[AI] Settings provider=${provider} could not be applied (missing credentials or package). Adapter unchanged (current="${this.service.adapterName}").`
+          );
+          return;
+        }
+        this.service.setAdapter(built.adapter);
+        ctx.logger.info(`[AI] Adapter rebuilt from settings: ${built.description}`);
+      } catch (err) {
+        ctx.logger.warn("[AI] Failed to apply ai settings: " + (err?.message ?? err));
+      }
+    };
+    await applySettings();
+    if (typeof settings.subscribe === "function") {
+      settings.subscribe("ai", () => {
+        void applySettings();
+      });
+      ctx.logger.info("[AI] Bound to settings:changed for namespace=ai");
+    }
+    let currentEmbedderId = null;
+    const applyEmbedder = async () => {
+      try {
+        const payload = await settings.getNamespace("ai");
+        const values = {};
+        for (const [k, v] of Object.entries(payload.values)) {
+          values[k] = v?.value;
+        }
+        const built = await this.buildEmbedderFromValues(ctx, values);
+        if (!built) {
+          if (currentEmbedderId !== null) {
+            ctx.logger.info("[AI] Embedder disabled by settings; kernel embedder service unset.");
+            currentEmbedderId = null;
+          }
+          return;
+        }
+        const replace = ctx.replaceService ?? ctx.registerService;
+        replace.call(ctx, EMBEDDER_SERVICE, built.embedder);
+        currentEmbedderId = built.embedder.id;
+        ctx.logger.info(`[AI] Embedder registered from settings: ${built.description}`);
+      } catch (err) {
+        ctx.logger.warn("[AI] Failed to apply embedder settings: " + (err?.message ?? err));
+      }
+    };
+    await applyEmbedder();
+    if (typeof settings.subscribe === "function") {
+      settings.subscribe("ai", () => {
+        void applyEmbedder();
+      });
+    }
+    if (typeof settings.registerAction === "function") {
+      settings.registerAction("ai", "test_embedder", async ({ values, payload }) => {
+        const overrides = payload && typeof payload === "object" && payload !== null && "values" in payload ? payload.values ?? {} : {};
+        const merged = { ...values ?? {}, ...overrides };
+        const provider = String(merged.embedder_provider ?? "none");
+        if (provider === "none") {
+          return {
+            ok: false,
+            severity: "warning",
+            message: "Embedder disabled (provider=none). Select a provider to enable knowledge search."
+          };
+        }
+        let built;
+        try {
+          built = await this.buildEmbedderFromValues(ctx, merged);
+        } catch (err) {
+          return { ok: false, severity: "error", message: err?.message ?? String(err) };
+        }
+        if (!built) {
+          return {
+            ok: false,
+            severity: "error",
+            message: `Could not build embedder for provider=${provider}. Check api key, base URL, and that @objectstack/embedder-openai is installed.`
+          };
+        }
+        const started = Date.now();
+        try {
+          const vectors = await built.embedder.embed(["ping"]);
+          const latency = Date.now() - started;
+          const dim = vectors[0]?.length ?? 0;
+          return {
+            ok: true,
+            severity: "info",
+            message: `${built.description} responded in ${latency}ms (vector dims=${dim}).`
+          };
+        } catch (err) {
+          return {
+            ok: false,
+            severity: "error",
+            message: `${built.description} request failed: ${err?.message ?? String(err)}`
+          };
+        }
+      });
+      ctx.logger.info("[AI] Registered live settings action ai/test_embedder");
+    }
+    if (typeof settings.registerAction === "function") {
+      settings.registerAction("ai", "test", async ({ values, payload }) => {
+        const overrides = payload && typeof payload === "object" && payload !== null && "values" in payload ? payload.values ?? {} : {};
+        const merged = { ...values ?? {}, ...overrides };
+        const provider = String(merged.provider ?? "memory");
+        if (provider === "memory") {
+          return {
+            ok: true,
+            severity: "warning",
+            message: "Memory provider is an echo stub \u2014 no external call to validate. Switch to a real provider for production."
+          };
+        }
+        let built;
+        try {
+          built = await this.buildAdapterFromValues(ctx, merged);
+        } catch (err) {
+          return { ok: false, severity: "error", message: err?.message ?? String(err) };
+        }
+        if (!built) {
+          return {
+            ok: false,
+            severity: "error",
+            message: `Could not build adapter for provider=${provider}. Check API key and that the provider SDK package is installed.`
+          };
+        }
+        const started = Date.now();
+        try {
+          const result = await built.adapter.chat(
+            [{ role: "user", content: "ping" }],
+            { maxTokens: 8 }
+          );
+          const latency = Date.now() - started;
+          const preview = String(result?.text ?? "").slice(0, 60);
+          return {
+            ok: true,
+            severity: "info",
+            message: `${built.description} responded in ${latency}ms${preview ? ` \u2014 "${preview}"` : ""}.`
+          };
+        } catch (err) {
+          return {
+            ok: false,
+            severity: "error",
+            message: `${built.description} request failed: ${err?.message ?? String(err)}`
+          };
+        }
+      });
+      ctx.logger.info("[AI] Registered live settings action ai/test");
+    }
   }
   async destroy() {
     this.service = void 0;