@123toto/ai-app-assistant-server 0.2.0 → 0.2.2

package/README.md

@@ -44,6 +44,7 @@ import { createManagedAiAppAssistantServer } from "@123toto/ai-app-assistant-ser
 
 const aiAppAssistant = createManagedAiAppAssistantServer({
   configuration: {
+    enabled: process.env.AI_APP_ASSISTANT_LLM_ENABLED === "true",
     storage: { type: "redis", client: redis },
     encryptionKey: process.env.AI_APP_ASSISTANT_SECRET_ENCRYPTION_KEY!,
     defaultConfiguration: {
@@ -63,6 +64,26 @@ const aiAppAssistant = createManagedAiAppAssistantServer({
 await aiAppAssistant.initialize();
 ```
 
+For deployments exposing one provider at a time, the library maps generic
+runtime values without requiring provider-specific environment variables:
+
+```ts
+const deployment = createAiAppAssistantDeploymentDefaults({
+  enabled: env.AI_APP_ASSISTANT_LLM_ENABLED,
+  provider: env.AI_APP_ASSISTANT_PROVIDER,
+  model: env.AI_APP_ASSISTANT_LLM_MODEL,
+  apiKey: env.AI_APP_ASSISTANT_API_KEY,
+  baseURL: env.AI_APP_ASSISTANT_LOCAL_LLM_BASE_URL
+});
+```
+
+`baseURL` is required for the local `ollama` provider. API keys and encryption
+keys must come from a runtime secret store; they must never be committed or
+embedded in an application image.
+
+`enabled: false` disables every provider operation while keeping the host
+application and the read-only administration endpoints available.
+
 Documents may also be loaded after application bootstrap with `aiAppAssistant.setDocuments(documents)`.
 
 ## Framework connectors

package/dist/express.d.cts

@@ -1,4 +1,4 @@
-import { M as ManagedAiAppAssistantServer } from './managed-server-CthTKEQ6.cjs';
+import { M as ManagedAiAppAssistantServer } from './managed-server-wXfu_9rp.cjs';
 import './ai-sdk-qU3KgNu-.cjs';
 import 'ai';
 import '@123toto/ai-app-assistant-contracts';

package/dist/express.d.ts

@@ -1,4 +1,4 @@
-import { M as ManagedAiAppAssistantServer } from './managed-server-BGQ-1jkx.js';
+import { M as ManagedAiAppAssistantServer } from './managed-server-CusQWWBB.js';
 import './ai-sdk-qU3KgNu-.js';
 import 'ai';
 import '@123toto/ai-app-assistant-contracts';

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AI_APP_ASSISTANT_PROVIDERS: () => AI_APP_ASSISTANT_PROVIDERS,
   AiAppAssistantConfigurationConflictError: () => AiAppAssistantConfigurationConflictError,
   AiAppAssistantConfigurationManager: () => AiAppAssistantConfigurationManager,
   AiAppAssistantManagementError: () => AiAppAssistantManagementError,
@@ -1464,6 +1465,7 @@ function quotaResult(count, resetAt, maxRequests, now) {
 }
 
 // src/provider-catalog.ts
+var AI_APP_ASSISTANT_PROVIDERS = ["anthropic", "google", "mistral", "ollama", "openai"];
 var PROVIDERS = Object.freeze([
   { id: "anthropic", label: "Anthropic", requiresApiKey: true, supportsModelDiscovery: true },
   { id: "google", label: "Google Gemini", requiresApiKey: true, supportsModelDiscovery: true },
@@ -1609,12 +1611,17 @@ var AiAppAssistantConfigurationManager = class {
     this.#repository = options.repository;
     this.#quotaStore = options.quotaStore ?? createMemoryAiAppAssistantQuotaStore();
   }
+  /** Returns the current state of the host-controlled global kill switch. */
+  isEnabled() {
+    return typeof this.#options.enabled === "function" ? this.#options.enabled() : this.#options.enabled ?? true;
+  }
   /** Returns the built-in provider catalogue; no credentials are exposed. */
   listProviders() {
     return listAiProviders();
   }
   /** Discovers models with an explicit key or the currently configured secret. */
   async listModels(input) {
+    this.assertEnabled();
     const apiKey = await this.resolveApiKey(input.provider, input.apiKey);
     if (this.#options.listModels) {
       return this.#options.listModels({ ...input, ...apiKey ? { apiKey } : {} });
@@ -1640,7 +1647,10 @@ var AiAppAssistantConfigurationManager = class {
         let connected = event.connectionValidated;
         if (event.reloadRequired) {
           this.#recentConnectionValidation = void 0;
-          if (connected) {
+          if (!this.isEnabled()) {
+            connected = false;
+            this.#runtimeConnection = { status: "disabled", checkedAt: this.now() };
+          } else if (connected) {
             const configuration = await this.getRuntimeConfiguration();
             this.#runtimeConnection = configuration ? {
               status: "connected",
@@ -1670,6 +1680,7 @@ var AiAppAssistantConfigurationManager = class {
   }
   /** Tests credentials and briefly caches a successful result for the next save. */
   async testConnection(input) {
+    this.assertEnabled();
     const apiKey = await this.resolveApiKey(input.provider, input.apiKey);
     const connection = this.#options.testConnection ? await this.#options.testConnection({ ...input, ...apiKey ? { apiKey } : {} }) : await testAiSdkConnection({
       model: `${input.provider}:${input.model}`,
@@ -1698,6 +1709,10 @@ var AiAppAssistantConfigurationManager = class {
   /** Checks the effective stored/deployment connection used by live questions. */
   async validateRuntimeConnection() {
     this.#lastReconnectAttempt = Date.now();
+    if (!this.isEnabled()) {
+      this.#runtimeConnection = { status: "disabled", checkedAt: this.now() };
+      return false;
+    }
     const configuration = await this.getRuntimeConfiguration();
     if (!configuration || configuration.provider !== "ollama" && !configuration.apiKey) {
       this.#runtimeConnection = {
@@ -1740,6 +1755,7 @@ var AiAppAssistantConfigurationManager = class {
     const initialActive = this.effectiveConfiguration(initial);
     const initialApiKey = input.apiKey ?? (initialActive?.provider === input.provider ? initialActive.apiKey : void 0) ?? this.resolveDefaultApiKey(input.provider);
     const initialConnectionChanged = connectionChanged(initialActive, input);
+    if (!this.isEnabled() && initialConnectionChanged) throw disabled();
     let connection = initialConnectionChanged ? await this.validateConnectionForSave(input, initialApiKey) : this.lastKnownConnection(input.provider, input.model);
     if (initialConnectionChanged && !connection.success) {
       return { saved: false, connection, reloadRequired: false };
@@ -1968,6 +1984,7 @@ var AiAppAssistantConfigurationManager = class {
   }
   /** Combines configuration, provider health and application access rules. */
   async canUse(identity) {
+    if (!this.isEnabled()) return false;
     const configuration = await this.getRuntimeConfiguration();
     if (!configuration || configuration.provider !== "ollama" && !configuration.apiKey) return false;
     if (!await this.ensureRuntimeConnection()) return false;
@@ -1986,6 +2003,7 @@ var AiAppAssistantConfigurationManager = class {
   }
   /** Enforces access and quota immediately before any model call. */
   async assertCanAsk(identity) {
+    this.assertEnabled();
     if (!await this.canUse(identity)) {
       throw forbidden("AI assistant access is not enabled for this user");
     }
@@ -2001,6 +2019,7 @@ var AiAppAssistantConfigurationManager = class {
   }
   /** Retries a failed provider lazily, with a shared backoff across requests. */
   async ensureRuntimeConnection() {
+    if (!this.isEnabled()) return false;
     if (this.#runtimeConnection.status === "connected") return true;
     const intervalMs = Math.max(1e3, this.#options.reconnectIntervalMs ?? 3e4);
     if (Date.now() - this.#lastReconnectAttempt < intervalMs) return false;
@@ -2108,6 +2127,9 @@ var AiAppAssistantConfigurationManager = class {
   now() {
     return (this.#options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
   }
+  assertEnabled() {
+    if (!this.isEnabled()) throw disabled();
+  }
   async publishAndEmit(event) {
     await this.#options.synchronizer?.publish(event);
     await this.emit(event);
@@ -2231,6 +2253,13 @@ function configurationChanges(previous, input, allowModelChangesByOthers) {
 function forbidden(message) {
   return new AiAppAssistantManagementError(403, "forbidden", message);
 }
+function disabled() {
+  return new AiAppAssistantManagementError(
+    503,
+    "assistant_disabled",
+    "AI assistant is disabled"
+  );
+}
 
 // src/telemetry.ts
 function createMemoryAiAppAssistantTelemetryStore(options) {
@@ -2400,6 +2429,11 @@ function createManagedAiAppAssistantRuntime(options) {
     return reloadQueue;
   });
   const rebuild = async (event) => {
+    if (!options.configuration.isEnabled()) {
+      assistant = void 0;
+      activeGenerator = void 0;
+      return;
+    }
     const connected = event.connectionValidated || await options.configuration.validateRuntimeConnection();
     const configuration = await options.configuration.getRuntimeConfiguration();
     if (!connected || !configuration) {
@@ -2786,21 +2820,38 @@ function createAiAppAssistantDeploymentDefaults(options) {
   const apiKeys = Object.fromEntries(
     Object.entries(options.apiKeys ?? {}).map(([provider2, value]) => [provider2, value?.trim() || void 0])
   );
-  const resolveApiKey2 = (provider2) => apiKeys[provider2];
+  const selectedProvider = options.provider;
+  const selectedApiKey = options.apiKey?.trim() || void 0;
+  const resolveApiKey2 = (provider2) => provider2 === selectedProvider ? selectedApiKey ?? apiKeys[provider2] : apiKeys[provider2];
   if (!options.enabled || !options.model?.trim()) return { resolveApiKey: resolveApiKey2 };
-  const match = options.model.trim().match(/^([^:/]+)[:/](.+)$/);
-  if (!match) throw new TypeError(`Invalid AI App Assistant model identifier: ${options.model}`);
-  const provider = match[1] === "gemini" ? "google" : match[1];
+  const rawModel = options.model.trim();
+  const legacyMatch = selectedProvider ? void 0 : rawModel.match(/^([^:/]+)[:/](.+)$/);
+  const explicitMatch = selectedProvider ? rawModel.match(/^([^:]+):(.+)$/) : void 0;
+  if (!selectedProvider && !legacyMatch) {
+    throw new TypeError(`Invalid AI App Assistant model identifier: ${options.model}`);
+  }
+  const parsedProvider = legacyMatch?.[1] ?? explicitMatch?.[1];
+  const modelProvider = parsedProvider === "gemini" ? "google" : parsedProvider ?? selectedProvider;
+  const provider = modelProvider;
   if (!listAiProviders().some((candidate) => candidate.id === provider)) {
-    throw new TypeError(`Unsupported AI App Assistant provider: ${match[1]}`);
+    throw new TypeError(`Unsupported AI App Assistant provider: ${modelProvider}`);
   }
+  if (selectedProvider && explicitMatch && provider !== selectedProvider) {
+    throw new TypeError(
+      `AI App Assistant provider '${selectedProvider}' does not match model identifier '${options.model}'`
+    );
+  }
+  const model = legacyMatch?.[2]?.trim() ?? explicitMatch?.[2]?.trim() ?? rawModel;
   const apiKey = resolveApiKey2(provider);
-  const baseURL = options.baseURLs?.[provider]?.trim() || void 0;
+  const baseURL = (provider === selectedProvider ? options.baseURL?.trim() : void 0) || options.baseURLs?.[provider]?.trim() || void 0;
+  if (provider === "ollama" && !baseURL) {
+    throw new TypeError("AI App Assistant local provider 'ollama' requires a base URL");
+  }
   return {
     resolveApiKey: resolveApiKey2,
     configuration: {
       provider,
-      model: match[2].trim(),
+      model,
       connectionSource: "environment",
       ...apiKey ? { apiKey } : {},
       ...baseURL ? { baseURL } : {},
@@ -3010,6 +3061,7 @@ function clampInteger3(value, minimum, maximum) {
 var import_ai_app_assistant_contracts6 = require("@123toto/ai-app-assistant-contracts");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AI_APP_ASSISTANT_PROVIDERS,
   AiAppAssistantConfigurationConflictError,
   AiAppAssistantConfigurationManager,
   AiAppAssistantManagementError,