@equinor/fusion-framework-cli-plugin-ai-base 1.0.0

package/src/options/types.ts

@@ -0,0 +1,32 @@
+/**
+ * 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`
+ */
+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;
+}

package/src/options/with-options.ts

@@ -0,0 +1,161 @@
+import { type Command, InvalidOptionArgumentError } from 'commander';
+import {
+  apiInstanceOption,
+  apiKeyOption,
+  apiVersionOption,
+  azureSearchApiKeyOption,
+  azureSearchEndpointOption,
+  azureSearchIndexNameOption,
+  chatDeploymentOption,
+  embeddingDeploymentOption,
+} from './options.js';
+
+/**
+ * Enhances a Commander command with AI-related 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.
+ *
+ * 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)
+ *
+ * @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 });
+ * ```
+ */
+export const withOptions = (
+  command: Command,
+  args?: Partial<{
+    includeEmbedding: boolean;
+    includeChat: 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);
+  }
+
+  if (args?.includeEmbedding === true) {
+    command.addOption(embeddingDeploymentOption);
+  }
+
+  // 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();
+
+    // Validate API key
+    if (
+      !options.openaiApiKey ||
+      typeof options.openaiApiKey !== 'string' ||
+      options.openaiApiKey.trim() === ''
+    ) {
+      throw new InvalidOptionArgumentError('API key is required and must be a non-empty string.');
+    }
+
+    // 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() === ''
+    ) {
+      throw new InvalidOptionArgumentError(
+        'API instance name is required and must be a non-empty string.',
+      );
+    }
+
+    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(
+          'Embedding deployment name is required and must be a non-empty string.',
+        );
+      }
+    }
+
+    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 and must be a non-empty string.',
+        );
+      }
+
+      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.',
+        );
+      }
+    }
+  });
+
+  return command;
+};
+
+export default withOptions;

package/src/register.ts

@@ -0,0 +1,38 @@
+import type { Command } from 'commander';
+import { createCommand } from 'commander';
+
+/**
+ * Registers an AI plugin command with the CLI program.
+ *
+ * This function ensures the 'ai' command group exists in the CLI program and adds
+ * the provided command as a subcommand. If the 'ai' group doesn't exist, it creates
+ * it with a standard description. This allows multiple AI-related plugins to register
+ * their commands under a common namespace.
+ *
+ * @param program - The Commander program instance to register commands with
+ * @param command - The command to add to the 'ai' command group
+ * @returns void
+ *
+ * @example
+ * ```ts
+ * const myAiCommand = createCommand('chat')
+ *   .description('Start an AI chat session')
+ *   .action(() => { ... });
+ *
+ * registerAiPlugin(program, myAiCommand);
+ * // Results in: fusion-cli ai chat
+ * ```
+ */
+export function registerAiPlugin(program: Command, command: Command): void {
+  // Create 'ai' command group if it doesn't exist
+  let aiCommand = program.commands.find((cmd) => cmd.name() === 'ai');
+  if (!aiCommand) {
+    aiCommand = createCommand('ai').description(
+      'Commands for interacting with AI models and Azure OpenAI services',
+    );
+    program.addCommand(aiCommand);
+  }
+  aiCommand.addCommand(command);
+}
+
+export default registerAiPlugin;

package/src/setup-framework.ts

@@ -0,0 +1,107 @@
+import { enableAI, type IAIConfigurator, type AIModule } from '@equinor/fusion-framework-module-ai';
+
+import {
+  AzureOpenAiEmbed,
+  AzureOpenAIModel,
+  AzureVectorStore,
+} from '@equinor/fusion-framework-module-ai/azure';
+
+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]>;
+
+/**
+ * Initializes and configures the Fusion Framework with AI module capabilities.
+ *
+ * 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.
+ *
+ * @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
+ */
+export const setupFramework = async (options: AiOptions): Promise<FrameworkInstance> => {
+  // Create a new module configurator for the framework
+  const configurator = new ModulesConfigurator<[AIModule]>();
+
+  // 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,
+        }),
+      );
+    }
+
+    // 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,
+        }),
+      );
+    }
+
+    // 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');
+      }
+
+      // 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);
+
+      // Check that the embedding service was successfully retrieved
+      if (!embeddingService) {
+        throw new Error(
+          `Embedding service '${options.openaiEmbeddingDeployment}' not found for vector store configuration`,
+        );
+      }
+
+      aiConfig.setVectorStore(
+        options.azureSearchIndexName,
+        new AzureVectorStore(embeddingService, {
+          endpoint: options.azureSearchEndpoint,
+          key: options.azureSearchApiKey,
+          indexName: options.azureSearchIndexName,
+        }),
+      );
+    }
+  });
+
+  // Initialize the framework with all configured modules
+  const framework = await configurator.initialize();
+  return framework;
+};
+
+export default setupFramework;

package/src/version.ts

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

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declarationDir": "./dist/types",
+    "baseUrl": "."
+  },
+  "references": [
+    {
+      "path": "../../modules/ai"
+    },
+    {
+      "path": "../../modules/module"
+    }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}