@equinor/fusion-framework-cli-plugin-ai-base 2.0.1 → 4.0.0

package/src/options/schema.ts

@@ -1,77 +1,28 @@
-/**
- * Zod validation schema and inferred type for AI command options.
- *
- * @packageDocumentation
- */
-
 import z from 'zod';
 
 /**
- * Base Zod schema for AI-related command options.
+ * Base Zod schema for Fusion AI command options.
  *
- * This schema defines the validation rules for all AI options. Other AI plugins
- * can extend this schema to add their own command-specific options.
+ * All fields are optional — when omitted the service URL and token are
+ * resolved automatically from Fusion service discovery and MSAL auth.
  *
  * @example
  * ```ts
- * import { AiOptionsSchema } from '@equinor/fusion-framework-cli-plugin-ai-base';
- * import { z } from 'zod';
- *
- * const MyCommandOptionsSchema = AiOptionsSchema.extend({
- *   myOption: z.string(),
- * });
+ * import { AiOptionsSchema } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
+ * const MySchema = AiOptionsSchema.extend({ extra: z.string() });
  * ```
  */
 export const AiOptionsSchema = z
   .object({
-    // Required AI options
-    openaiApiKey: z
-      .string({ message: 'Azure OpenAI API key is required and must be a non-empty string.' })
-      .min(1, 'API key must be a non-empty string.')
-      .describe('Azure OpenAI API key for authentication'),
-    openaiApiVersion: z
-      .string({ message: 'Azure OpenAI API version is required and must be a non-empty string.' })
-      .min(1, 'API version must be a non-empty string.')
-      .describe('Azure OpenAI API version'),
-    openaiInstance: z
-      .string({ message: 'Azure OpenAI instance name is required and must be a non-empty string.' })
-      .min(1, 'Instance name must be a non-empty string.')
-      .describe('Azure OpenAI instance name'),
-
-    // Optional AI options
-    openaiChatDeployment: z
-      .string()
-      .min(1, 'Chat deployment name must be a non-empty string.')
-      .optional()
-      .describe('Azure OpenAI chat deployment name'),
-    openaiEmbeddingDeployment: z
-      .string()
-      .min(1, 'Embedding deployment name must be a non-empty string.')
-      .optional()
-      .describe('Azure OpenAI embedding deployment name'),
-    azureSearchEndpoint: z
-      .string()
-      .url('Azure Search endpoint must be a valid URL.')
-      .min(1, 'Azure Search endpoint must be a non-empty string.')
-      .optional()
-      .describe('Azure Search endpoint URL'),
-    azureSearchApiKey: z
-      .string()
-      .min(1, 'Azure Search API key must be a non-empty string.')
-      .optional()
-      .describe('Azure Search API key'),
-    azureSearchIndexName: z
-      .string()
-      .min(1, 'Azure Search index name must be a non-empty string.')
-      .optional()
-      .describe('Azure Search index name'),
+    env: z.string().optional(),
+    token: z.string().optional(),
+    tenantId: z.string().optional(),
+    clientId: z.string().optional(),
+    chatModel: z.string().min(1).optional(),
+    embedModel: z.string().min(1).optional(),
+    indexName: z.string().min(1).optional(),
+    debug: z.coerce.boolean().default(false),
   })
-  .describe('Base AI-related command options');
+  .describe('Base Fusion AI command options');
 
-/**
- * Type representing the validated AI options.
- *
- * This type is inferred from the Zod schema and should be used throughout AI plugins
- * to ensure type safety and consistency with the schema.
- */
 export type AiOptionsType = z.infer<typeof AiOptionsSchema>;

package/src/options/types.ts

@@ -1,42 +1,24 @@
 /**
- * Hand-authored TypeScript interface for AI CLI command options.
+ * Base options for all Fusion AI CLI commands.
  *
- * @remarks
- * Use {@link AiOptions} when you need a lightweight type without pulling in Zod.
- * For runtime validation prefer {@link AiOptionsSchema} from the schema module.
- *
- * @packageDocumentation
- */
-
-/**
- * Configuration options for AI-related CLI commands.
- *
- * This interface defines all available options for configuring Azure OpenAI services
- * and Azure Cognitive Search integration. Required fields must be provided either
- * via command-line arguments or environment variables. Optional fields enable
- * specific features (chat, embeddings, vector search) when provided.
- *
- * @remarks
- * - All required fields (apiKey, apiVersion, instance) must be provided for any AI operation
- * - Chat operations require `openaiChatDeployment`
- * - Embedding operations require `openaiEmbeddingDeployment`
- * - Vector search requires all three Azure Search fields plus `openaiEmbeddingDeployment`
+ * The service URL and token are resolved automatically from Fusion
+ * service discovery using the provided environment and authentication options.
  */
 export interface AiOptions {
-  /** Azure OpenAI API key for authentication with Azure OpenAI services */
-  openaiApiKey: string;
-  /** Azure OpenAI API version (e.g., '2024-02-15-preview') */
-  openaiApiVersion: string;
-  /** Azure OpenAI instance name (the resource name in Azure) */
-  openaiInstance: string;
-  /** Azure OpenAI chat model deployment name. Required for chat operations */
-  openaiChatDeployment?: string;
-  /** Azure OpenAI embedding model deployment name. Required for embedding and vector search operations */
-  openaiEmbeddingDeployment?: string;
-  /** Azure Cognitive Search endpoint URL. Required for vector search operations */
-  azureSearchEndpoint?: string;
-  /** Azure Cognitive Search API key. Required for vector search operations */
-  azureSearchApiKey?: string;
-  /** Azure Cognitive Search index name. Required for vector search operations */
-  azureSearchIndexName?: string;
+  /** Fusion environment used for service discovery (e.g. `ci`, `fprd`). */
+  env?: string;
+  /** Bearer token passed directly to the auth module (overrides clientId/tenantId). */
+  token?: string;
+  /** Azure AD tenant ID for MSAL silent authentication. */
+  tenantId?: string;
+  /** Azure AD client ID for MSAL silent authentication. */
+  clientId?: string;
+  /** Azure OpenAI chat model deployment name. Required for chat operations. */
+  chatModel?: string;
+  /** Azure OpenAI embedding model deployment name. Required for embedding and index operations. */
+  embedModel?: string;
+  /** Azure AI Search index name. Required for vector search / indexing operations. */
+  indexName?: string;
+  /** Enable debug mode for verbose logging. */
+  debug?: boolean;
 }

package/src/options/with-options.ts

@@ -1,159 +1,67 @@
 import { type Command, InvalidOptionArgumentError } from 'commander';
 import {
-  apiInstanceOption,
-  apiKeyOption,
-  apiVersionOption,
-  azureSearchApiKeyOption,
-  azureSearchEndpointOption,
-  azureSearchIndexNameOption,
-  chatDeploymentOption,
-  embeddingDeploymentOption,
+  chatModelOption,
+  clientIdOption,
+  debugOption,
+  embedModelOption,
+  envOption,
+  indexNameOption,
+  tenantIdOption,
+  tokenOption,
 } from './options.js';
 
 /**
- * Enhances a Commander command with AI-related options and validation.
+ * Enhances a Commander command with Fusion AI options and validation.
  *
- * This function adds Azure OpenAI and Azure Cognitive Search options to the provided
- * command, along with pre-action validation hooks to ensure required options are provided.
- * The function allows selective inclusion of chat, embedding, and search capabilities
- * based on the command's requirements.
+ * Core auth options (`--env`, `--token`, `--tenant-id`, `--client-id`) are always
+ * added.  When no explicit `--token` is provided, the framework will authenticate
+ * via MSAL and resolve the AI service endpoint from Fusion service discovery.
  *
- * Options added:
- * - Core: `openaiApiKey`, `openaiApiVersion`, `openaiInstance` (always included)
- * - Chat: `openaiChatDeployment` (if includeChat is true)
- * - Embedding: `openaiEmbeddingDeployment` (if includeEmbedding is true)
- * - Search: `azureSearchEndpoint`, `azureSearchApiKey`, `azureSearchIndexName` (if includeSearch is true)
+ * Pass flags to include optional chat, embed, or index options and make
+ * them required at runtime via the `preAction` validation hook.
  *
- * @param command - The Commander command instance to enhance with AI options
- * @param args - Optional configuration object for selective feature inclusion
- * @param args.includeEmbedding - Whether to include and require embedding deployment option (default: false)
- * @param args.includeChat - Whether to include and require chat deployment option (default: false)
- * @param args.includeSearch - Whether to include and require Azure Search options (default: false)
- * @returns The enhanced command with AI options and validation hooks attached
- * @throws {InvalidOptionArgumentError} During command execution if required options are missing or invalid
- *
- * @example
- * ```ts
- * const chatCommand = createCommand('chat')
- *   .description('Start a chat session');
- *
- * withOptions(chatCommand, { includeChat: true });
- * ```
+ * @param command - The Commander command to decorate with options.
+ * @param args - Feature flags controlling which optional options to add.
+ * @param args.includeChat - Add `--chat-model` and validate it at runtime.
+ * @param args.includeEmbedding - Add `--embed-model` and validate it at runtime.
+ * @param args.includeSearch - Add `--index-name` and validate it at runtime.
+ * @returns The decorated command.
  */
 export const withOptions = (
   command: Command,
   args?: Partial<{
-    includeEmbedding: boolean;
     includeChat: boolean;
+    includeEmbedding: boolean;
     includeSearch: boolean;
   }>,
 ): Command => {
-  // Core authentication options
-  command.addOption(apiKeyOption);
-  command.addOption(apiVersionOption);
-  command.addOption(apiInstanceOption);
-
-  // Deployment options
-  if (args?.includeChat === true) {
-    command.addOption(chatDeploymentOption);
-  }
+  command.addOption(envOption);
+  command.addOption(tokenOption);
+  command.addOption(tenantIdOption);
+  command.addOption(clientIdOption);
+  command.addOption(debugOption);
 
-  if (args?.includeEmbedding === true) {
-    command.addOption(embeddingDeploymentOption);
-  }
+  if (args?.includeChat) command.addOption(chatModelOption);
+  if (args?.includeEmbedding) command.addOption(embedModelOption);
+  if (args?.includeSearch) command.addOption(indexNameOption);
 
-  // Azure Search options
-  if (args?.includeSearch === true) {
-    command.addOption(azureSearchEndpointOption);
-    command.addOption(azureSearchApiKeyOption);
-    command.addOption(azureSearchIndexNameOption);
-  }
-
-  // Validation hook
   command.hook('preAction', (thisCommand) => {
-    const options = thisCommand.opts();
+    const opts = thisCommand.opts();
 
-    // Validate API key
-    if (
-      !options.openaiApiKey ||
-      typeof options.openaiApiKey !== 'string' ||
-      options.openaiApiKey.trim() === ''
-    ) {
+    if (args?.includeChat && !opts.chatModel?.trim()) {
       throw new InvalidOptionArgumentError(
-        'Azure OpenAI API key is required. Provide it via --openai-api-key option or AZURE_OPENAI_API_KEY environment variable.',
+        'Chat model name is required. Provide --chat-model or set FUSION_AI_CHAT_MODEL.',
       );
     }
-
-    // Validate API version
-    if (!options.openaiApiVersion || typeof options.openaiApiVersion !== 'string') {
-      throw new InvalidOptionArgumentError('API version must be a non-empty string.');
-    }
-
-    // Validate instance name
-    if (
-      !options.openaiInstance ||
-      typeof options.openaiInstance !== 'string' ||
-      options.openaiInstance.trim() === ''
-    ) {
+    if (args?.includeEmbedding && !opts.embedModel?.trim()) {
       throw new InvalidOptionArgumentError(
-        'Azure OpenAI instance name is required. Provide it via --openai-instance option or AZURE_OPENAI_INSTANCE_NAME environment variable.',
+        'Embedding model name is required. Provide --embed-model or set FUSION_AI_EMBED_MODEL.',
       );
     }
-
-    if (args?.includeChat === true) {
-      if (
-        !options.openaiChatDeployment ||
-        typeof options.openaiChatDeployment !== 'string' ||
-        options.openaiChatDeployment.trim() === ''
-      ) {
-        throw new InvalidOptionArgumentError(
-          'Chat deployment name is required and must be a non-empty string.',
-        );
-      }
-    }
-
-    if (args?.includeEmbedding === true) {
-      if (
-        !options.openaiEmbeddingDeployment ||
-        typeof options.openaiEmbeddingDeployment !== 'string' ||
-        options.openaiEmbeddingDeployment.trim() === ''
-      ) {
-        throw new InvalidOptionArgumentError(
-          'Azure OpenAI embedding deployment name is required. Provide it via --openai-embedding-deployment option or AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME environment variable.',
-        );
-      }
-    }
-
-    if (args?.includeSearch === true) {
-      if (
-        !options.azureSearchEndpoint ||
-        typeof options.azureSearchEndpoint !== 'string' ||
-        options.azureSearchEndpoint.trim() === ''
-      ) {
-        throw new InvalidOptionArgumentError(
-          'Azure Search endpoint is required and must be a non-empty string.',
-        );
-      }
-
-      if (
-        !options.azureSearchApiKey ||
-        typeof options.azureSearchApiKey !== 'string' ||
-        options.azureSearchApiKey.trim() === ''
-      ) {
-        throw new InvalidOptionArgumentError(
-          'Azure Search API key is required. Provide it via --azure-search-api-key option or AZURE_SEARCH_API_KEY environment variable.',
-        );
-      }
-
-      if (
-        !options.azureSearchIndexName ||
-        typeof options.azureSearchIndexName !== 'string' ||
-        options.azureSearchIndexName.trim() === ''
-      ) {
-        throw new InvalidOptionArgumentError(
-          'Azure Search index name is required and must be a non-empty string.',
-        );
-      }
+    if (args?.includeSearch && !opts.indexName?.trim()) {
+      throw new InvalidOptionArgumentError(
+        'Index name is required. Provide --index-name or set FUSION_AI_INDEX_NAME.',
+      );
     }
   });
 

package/src/setup-framework.ts

@@ -1,107 +1,71 @@
-import { enableAI, type IAIConfigurator, type AIModule } from '@equinor/fusion-framework-module-ai';
-
-import {
-  AzureOpenAiEmbed,
-  AzureOpenAIModel,
-  AzureVectorStore,
-} from '@equinor/fusion-framework-module-ai/azure';
+import { enableAI } from '@equinor/fusion-framework-module-ai';
+import type { AIModule } from '@equinor/fusion-framework-module-ai';
 
+import { initializeFramework, FusionEnv } from '@equinor/fusion-framework-cli/bin';
+import type { FusionFrameworkSettings, FusionFramework } from '@equinor/fusion-framework-cli/bin';
 import type { AiOptions } from './options/index.js';
-import { ModulesConfigurator, type ModulesInstance } from '@equinor/fusion-framework-module';
 
-/**
- * Framework instance with AI module capabilities.
- *
- * This type represents an initialized Fusion Framework instance that includes
- * the AI module, providing access to chat models, embedding services, and
- * vector stores configured via the setup process.
- */
-export type FrameworkInstance = ModulesInstance<[AIModule]>;
+/** Initialized framework instance with the AI module. */
+export type FrameworkInstance = FusionFramework<[AIModule]>;
 
 /**
- * Initializes and configures the Fusion Framework with AI module capabilities.
+ * Creates a Fusion Framework instance with the AI module enabled.
  *
- * Sets up the framework with Azure OpenAI chat models, embedding services, and
- * optionally Azure Cognitive Search vector stores. The function handles the complete
- * initialization process including service registration and dependency injection.
+ * Uses Azure Identity's `DefaultAzureCredential` by default, which resolves
+ * credentials from the environment (OIDC, managed identity, Azure CLI, etc.).
+ * When an explicit token is provided via `--token` or `FUSION_TOKEN`, that
+ * token is used directly instead.
  *
- * @param options - AI configuration options
- * @param options.openaiApiKey - Azure OpenAI API key for authentication
- * @param options.openaiApiVersion - Azure OpenAI API version (e.g., '2024-02-15-preview')
- * @param options.openaiInstance - Azure OpenAI instance name
- * @param options.openaiChatDeployment - Optional chat model deployment name
- * @param options.openaiEmbeddingDeployment - Optional embedding model deployment name
- * @param options.azureSearchEndpoint - Optional Azure Search service endpoint URL
- * @param options.azureSearchApiKey - Optional Azure Search API key
- * @param options.azureSearchIndexName - Optional Azure Search index name
- * @returns Promise resolving to an initialized framework instance with AI module configured
- * @throws {Error} If embedding deployment is required but not provided when configuring vector store
- * @throws {Error} If embedding service cannot be retrieved for vector store configuration
+ * @param options - CLI options resolved by {@link withOptions}.
+ * @returns A fully initialised framework instance with the AI module.
+ * @throws {Error} When authentication fails after the interactive retry.
  */
-export const setupFramework = async (options: AiOptions): Promise<FrameworkInstance> => {
-  // Create a new module configurator for the framework
-  const configurator = new ModulesConfigurator<[AIModule]>();
+export const setupFramework = async (options: AiOptions): Promise<FusionFramework<[AIModule]>> => {
+  const debug = options.debug ?? false;
 
-  // Configure AI module with provided options
-  enableAI(configurator, (aiConfig: IAIConfigurator) => {
-    // Configure chat model if deployment name is provided
-    if (options.openaiChatDeployment) {
-      aiConfig.setModel(
-        options.openaiChatDeployment,
-        new AzureOpenAIModel({
-          azureOpenAIApiKey: options.openaiApiKey,
-          azureOpenAIApiDeploymentName: options.openaiChatDeployment,
-          azureOpenAIApiInstanceName: options.openaiInstance,
-          azureOpenAIApiVersion: options.openaiApiVersion,
-        }),
-      );
-    }
+  // Auth strategy:
+  // 1. Explicit token (--token / FUSION_TOKEN) → direct token passthrough
+  // 2. Everything else → Azure Identity (DefaultAzureCredential)
+  const auth: FusionFrameworkSettings['auth'] = options.token
+    ? { token: options.token }
+    : { defaultCredential: true };
 
-    // Configure embedding model if deployment name is provided
-    if (options.openaiEmbeddingDeployment) {
-      aiConfig.setEmbedding(
-        options.openaiEmbeddingDeployment,
-        new AzureOpenAiEmbed({
-          azureOpenAIApiKey: options.openaiApiKey,
-          azureOpenAIApiDeploymentName: options.openaiEmbeddingDeployment,
-          azureOpenAIApiInstanceName: options.openaiInstance,
-          azureOpenAIApiVersion: options.openaiApiVersion,
-        }),
-      );
-    }
+  const env = (options.env as FusionEnv) ?? FusionEnv.ContinuesIntegration;
+
+  if (debug) {
+    console.debug('[debug] Environment:', env);
+    console.debug('[debug] Auth mode:', options.token ? 'static-token' : 'azure-identity');
+  }
 
-    // Configure vector store if Azure Search options are provided
-    // Vector store requires an embedding service to generate embeddings for documents
-    if (options.azureSearchEndpoint && options.azureSearchApiKey && options.azureSearchIndexName) {
-      if (!options.openaiEmbeddingDeployment) {
-        throw new Error('Embedding deployment is required to configure the vector store');
-      }
+  /** Initialise the framework, resolve the AI service, and pre-cache tokens. */
+  const initAndSetup = async (): Promise<FusionFramework<[AIModule]>> => {
+    if (debug) console.debug('[debug] Initializing framework with AI module…');
 
-      // Retrieve the embedding service to pass to the vector store
-      // The vector store uses embeddings to index and search documents
-      const embeddingService = aiConfig.getService('embeddings', options.openaiEmbeddingDeployment);
+    const framework = await initializeFramework<[AIModule]>({ env, auth }, (configurator) => {
+      enableAI(configurator);
+    });
 
-      // Check that the embedding service was successfully retrieved
-      if (!embeddingService) {
-        throw new Error(
-          `Embedding service '${options.openaiEmbeddingDeployment}' not found for vector store configuration`,
-        );
-      }
+    // resolveService makes an authenticated HTTP call — will throw
+    // NoAccountsError if the user has never logged in.
+    const service = await framework.serviceDiscovery.resolveService('ai');
+    const scopes = service.scopes ?? service.defaultScopes ?? [];
 
-      aiConfig.setVectorStore(
-        options.azureSearchIndexName,
-        new AzureVectorStore(embeddingService, {
-          endpoint: options.azureSearchEndpoint,
-          key: options.azureSearchApiKey,
-          indexName: options.azureSearchIndexName,
-        }),
-      );
+    if (debug) {
+      console.debug('[debug] AI service URL:', service.uri);
+      console.debug('[debug] AI service scopes:', scopes);
     }
-  });
 
-  // Initialize the framework with all configured modules
-  const framework = await configurator.initialize();
-  return framework;
+    // Pre-cache a token for the AI service scopes so strategy callbacks
+    // don't attempt (and fail) a silent acquisition later.
+    const token = await framework.auth.acquireAccessToken({ request: { scopes } });
+    if (!token) throw new Error('Failed to acquire access token for the AI service.');
+
+    if (debug) console.debug('[debug] Token acquired successfully');
+
+    return framework;
+  };
+
+  return await initAndSetup();
 };
 
 export default setupFramework;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '2.0.1';
+export const version = '4.0.0';

package/tsconfig.json

@@ -9,6 +9,9 @@
     "baseUrl": "."
   },
   "references": [
+    {
+      "path": "../../cli"
+    },
     {
       "path": "../../modules/ai"
     },