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

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# @equinor/fusion-framework-cli-plugin-ai-base
+
+## 1.0.0
+
+### Major Changes
+
+- [`e2d2a76`](https://github.com/equinor/fusion-framework/commit/e2d2a76d08b86c3a9d8783fed1606551df9d5633) Thanks [@odinr](https://github.com/odinr)! - Add new base plugin package for AI CLI plugins providing shared utilities and configuration.
+
+  This package provides shared utilities and options used across multiple AI CLI plugins including framework setup, AI configuration, and command option handling.
+
+  **Features:**
+
+  - Shared AI options and configuration schema
+  - Framework setup utilities
+  - Common command option handling
+  - Type-safe AI configuration interfaces
+
+  **Quick Usage:**
+
+  ```typescript
+  import { createCommand } from "commander";
+  import {
+    withOptions,
+    type AiOptions,
+  } from "@equinor/fusion-framework-cli-plugin-ai-base/command-options";
+  import { setupFramework } from "@equinor/fusion-framework-cli-plugin-ai-base";
+
+  const command = createCommand("my-ai-command").description("My AI command");
+
+  // Add AI options to the command
+  const enhancedCommand = withOptions(command, {
+    includeChat: true,
+    includeEmbedding: true,
+    includeSearch: true,
+  });
+
+  enhancedCommand.action(async (options: AiOptions) => {
+    // Initialize framework with AI module
+    const framework = await setupFramework(options);
+
+    // Use framework.modules.ai for AI operations
+    const aiService = framework.modules.ai;
+    // ... your command logic
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`e2d2a76`](https://github.com/equinor/fusion-framework/commit/e2d2a76d08b86c3a9d8783fed1606551df9d5633), [`e2d2a76`](https://github.com/equinor/fusion-framework/commit/e2d2a76d08b86c3a9d8783fed1606551df9d5633)]:
+  - @equinor/fusion-framework-cli@13.0.0
+  - @equinor/fusion-framework-module-ai@2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Equinor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# AI Base Plugin Package
+
+> [!DANGER]
+> **⚠️ INTERNAL USE ONLY**  
+> This package provides shared utilities and options for AI CLI plugins within Equinor's Fusion Framework ecosystem. External consumers should use the higher-level AI CLI plugins instead.
+
+## Purpose
+
+Provides common functionality for AI CLI plugins to avoid code duplication:
+- Shared AI command options (model, temperature, tokens, etc.)
+- Fusion Framework setup with AI module configuration
+- Configuration file loading and validation
+- Type definitions for AI options and configuration
+
+Used by:
+- `@equinor/fusion-framework-cli-plugin-ai-chat`
+- `@equinor/fusion-framework-cli-plugin-ai-search`
+- `@equinor/fusion-framework-cli-plugin-ai-index`
+
+Changes here affect all consuming plugins, so coordinate updates carefully.
+
+## Usage in Consuming Plugins
+
+### Install as Dependency
+
+**For monorepo packages:**
+```json
+{
+  "dependencies": {
+    "@equinor/fusion-framework-cli-plugin-ai-base": "workspace:*"
+  }
+}
+```
+
+### Import from Base Package
+
+```typescript
+// Import AI options from command-options export
+import { withOptions, type AiOptions, AiOptionsSchema } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
+
+// Import framework utilities from main export
+import { setupFramework, registerAiPlugin, loadFusionAIConfig } from '@equinor/fusion-framework-cli-plugin-ai-base';
+
+// Or import everything from main export
+import { 
+  setupFramework, 
+  registerAiPlugin, 
+  loadFusionAIConfig,
+  type FrameworkInstance,
+  type FusionAIConfig 
+} from '@equinor/fusion-framework-cli-plugin-ai-base';
+```
+
+## Exports
+
+- `./command-options` - AI command options, validation schemas, and option helpers
+  - `withOptions` - Function to add AI options to a Commander command
+  - `options` - Default export containing all option definitions
+  - `AiOptionsSchema` - Zod schema for validating AI options
+  - `AiOptionsType` - Type inferred from the schema
+  - `AiOptions` - TypeScript interface for AI options
+- `.` - Main export containing:
+  - `setupFramework` - Initialize and configure Fusion Framework with AI module
+  - `registerAiPlugin` - Register AI plugin commands with CLI program
+  - `loadFusionAIConfig` - Load Fusion AI configuration from file
+  - `configureFusionAI` - Configuration factory function
+  - `FrameworkInstance` - Type for initialized framework instance
+  - `FusionAIConfig` - Base configuration interface
+  - `LoadFusionAIConfigOptions` - Options for loading configuration
+
+## Development
+
+- Build: `pnpm build` (type checking only, no bundling needed)
+- Changesets should be created for versioning and changelog tracking
+- Breaking changes affect all consuming plugins, so coordinate updates carefully
+

package/dist/esm/config.js

@@ -0,0 +1,58 @@
+import { importConfig } from '@equinor/fusion-imports';
+/**
+ * Configuration factory function for Fusion AI operations.
+ *
+ * This helper function provides type safety and consistency for creating AI configuration
+ * functions. It accepts a function that returns configuration (either synchronously or
+ * asynchronously) and returns it unchanged, providing a typed interface for consumers.
+ *
+ * @param fn - Function that returns Fusion AI configuration (sync or async)
+ * @returns The same configuration function, typed for use with loadFusionAIConfig
+ *
+ * @example
+ * ```ts
+ * // fusion-ai.config.ts
+ * export default configureFusionAI(async () => ({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   deployment: 'gpt-4',
+ * }));
+ * ```
+ */
+export const configureFusionAI = (fn) => fn;
+/**
+ * Loads and resolves Fusion AI configuration from a file.
+ *
+ * The config file should export a function (via `configureFusionAI`) that returns
+ * the configuration object. The function can be synchronous or asynchronous.
+ *
+ * @param configPath - Path to the config file without extension (default: 'fusion-ai.config')
+ * @param options - Optional parameters for loading the configuration
+ * @returns Promise resolving to the loaded and executed configuration
+ * @throws {Error} If the config file cannot be found or loaded
+ * @throws {Error} If the config file does not export a valid configuration function
+ *
+ * @example
+ * ```ts
+ * const config = await loadFusionAIConfig('fusion-ai.config', {
+ *   baseDir: process.cwd(),
+ *   extensions: ['.ts', '.js'],
+ * });
+ * ```
+ */
+export async function loadFusionAIConfig(configPath = 'fusion-ai.config', options = {}) {
+    const { baseDir = process.cwd(), extensions } = options;
+    // Load configuration - config file exports a function for dynamic configuration
+    const result = await importConfig(configPath, {
+        baseDir,
+        extensions,
+    });
+    // Execute the configuration function (handles both sync and async)
+    const configFn = result.config;
+    if (typeof configFn === 'function') {
+        return await configFn();
+    }
+    // If config is not a function, treat it as the config object directly
+    return configFn;
+}
+export default loadFusionAIConfig;
+//# sourceMappingURL=config.js.map

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAcvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAA2B,EAAwB,EAAE,EAAE,CAAC,EAAE,CAAC;AAY5F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,aAAqB,kBAAkB,EACvC,UAAqC,EAAE;IAEvC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAExD,gFAAgF;IAChF,MAAM,MAAM,GAAG,MAAM,YAAY,CAAuB,UAAU,EAAE;QAClE,OAAO;QACP,UAAU;KACX,CAAC,CAAC;IAEH,mEAAmE;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO,MAAM,QAAQ,EAAE,CAAC;IAC1B,CAAC;IACD,sEAAsE;IACtE,OAAO,QAAa,CAAC;AACvB,CAAC;AAED,eAAe,kBAAkB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,14 @@
+/**
+ * Base AI plugin package for Fusion Framework CLI
+ *
+ * @remarks
+ * This package provides shared utilities and configuration for AI-related CLI plugins.
+ * It is an internal base package and should not be used standalone. Consuming plugins
+ * should import from this package as a dependency.
+ *
+ * @packageDocumentation
+ */
+export { configureFusionAI, loadFusionAIConfig, } from './config.js';
+export { setupFramework } from './setup-framework.js';
+export { registerAiPlugin } from './register.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAqB,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/options/index.js

@@ -0,0 +1,4 @@
+export { default as options } from './options.js';
+export { withOptions } from './with-options.js';
+export { AiOptionsSchema } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/options/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/options/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAsB,MAAM,aAAa,CAAC"}

package/dist/esm/options/options.js

@@ -0,0 +1,60 @@
+import { createOption } from 'commander';
+/**
+ * Option for specifying the Azure OpenAI API key.
+ * Required for authentication with Azure OpenAI services.
+ */
+export const apiKeyOption = createOption('--openai-api-key <key>', 'API key for Azure OpenAI services').env('AZURE_OPENAI_API_KEY');
+/**
+ * Option for specifying the Azure OpenAI API version.
+ * Defaults to the latest stable version if not provided.
+ */
+export const apiVersionOption = createOption('--openai-api-version <version>', 'Azure OpenAI API version')
+    .env('AZURE_OPENAI_API_VERSION')
+    .default('2024-02-15-preview');
+/**
+ * Option for specifying the Azure OpenAI instance name.
+ * Required for Azure OpenAI service endpoint construction.
+ */
+export const apiInstanceOption = createOption('--openai-instance <name>', 'Azure OpenAI instance name').env('AZURE_OPENAI_INSTANCE_NAME');
+/**
+ * Option for specifying the Azure OpenAI deployment name for chat models.
+ * Required for chat completions API calls.
+ */
+export const chatDeploymentOption = createOption('--openai-chat-deployment <name>', 'Azure OpenAI chat deployment name').env('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME');
+/**
+ * Option for specifying the Azure OpenAI deployment name for embedding models.
+ * Required for embeddings API calls.
+ */
+export const embeddingDeploymentOption = createOption('--openai-embedding-deployment <name>', 'Azure OpenAI embedding deployment name').env('AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME');
+/**
+ * Option for specifying the Azure Search endpoint URL.
+ * Required for Azure Cognitive Search operations.
+ */
+export const azureSearchEndpointOption = createOption('--azure-search-endpoint <url>', 'Azure Search endpoint URL').env('AZURE_SEARCH_ENDPOINT');
+/**
+ * Option for specifying the Azure Search API key.
+ * Required for authentication with Azure Cognitive Search.
+ */
+export const azureSearchApiKeyOption = createOption('--azure-search-api-key <key>', 'Azure Search API key').env('AZURE_SEARCH_API_KEY');
+/**
+ * Option for specifying the Azure Search index name.
+ * Required for search operations on a specific index.
+ */
+export const azureSearchIndexNameOption = createOption('--azure-search-index-name <name>', 'Azure Search index name').env('AZURE_SEARCH_INDEX_NAME');
+/**
+ * Default export containing all AI-related command options.
+ *
+ * Provides convenient access to all option definitions for use in CLI commands.
+ * Each option can also be imported individually for more granular control.
+ */
+export default {
+    apiKeyOption,
+    apiVersionOption,
+    apiInstanceOption,
+    chatDeploymentOption,
+    embeddingDeploymentOption,
+    azureSearchEndpointOption,
+    azureSearchApiKeyOption,
+    azureSearchIndexNameOption,
+};
+//# sourceMappingURL=options.js.map

package/dist/esm/options/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/options/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CACtC,wBAAwB,EACxB,mCAAmC,CACpC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAC1C,gCAAgC,EAChC,0BAA0B,CAC3B;KACE,GAAG,CAAC,0BAA0B,CAAC;KAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEjC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAC3C,0BAA0B,EAC1B,4BAA4B,CAC7B,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAC9C,iCAAiC,EACjC,mCAAmC,CACpC,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CACnD,sCAAsC,EACtC,wCAAwC,CACzC,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CACnD,+BAA+B,EAC/B,2BAA2B,CAC5B,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CACjD,8BAA8B,EAC9B,sBAAsB,CACvB,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,YAAY,CACpD,kCAAkC,EAClC,yBAAyB,CAC1B,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,eAAe;IACb,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,oBAAoB;IACpB,yBAAyB;IACzB,yBAAyB;IACzB,uBAAuB;IACvB,0BAA0B;CAC3B,CAAC"}

package/dist/esm/options/schema.js

@@ -0,0 +1,62 @@
+import z from 'zod';
+/**
+ * Base Zod schema for AI-related 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.
+ *
+ * @example
+ * ```ts
+ * import { AiOptionsSchema } from '@equinor/fusion-framework-cli-plugin-ai-base';
+ * import { z } from 'zod';
+ *
+ * const MyCommandOptionsSchema = AiOptionsSchema.extend({
+ *   myOption: 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'),
+})
+    .describe('Base AI-related command options');
+//# sourceMappingURL=schema.js.map

package/dist/esm/options/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/options/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,sBAAsB;IACtB,YAAY,EAAE,CAAC;SACZ,MAAM,CAAC,EAAE,OAAO,EAAE,kEAAkE,EAAE,CAAC;SACvF,GAAG,CAAC,CAAC,EAAE,qCAAqC,CAAC;SAC7C,QAAQ,CAAC,yCAAyC,CAAC;IACtD,gBAAgB,EAAE,CAAC;SAChB,MAAM,CAAC,EAAE,OAAO,EAAE,sEAAsE,EAAE,CAAC;SAC3F,GAAG,CAAC,CAAC,EAAE,yCAAyC,CAAC;SACjD,QAAQ,CAAC,0BAA0B,CAAC;IACvC,cAAc,EAAE,CAAC;SACd,MAAM,CAAC,EAAE,OAAO,EAAE,wEAAwE,EAAE,CAAC;SAC7F,GAAG,CAAC,CAAC,EAAE,2CAA2C,CAAC;SACnD,QAAQ,CAAC,4BAA4B,CAAC;IAEzC,sBAAsB;IACtB,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,kDAAkD,CAAC;SAC1D,QAAQ,EAAE;SACV,QAAQ,CAAC,mCAAmC,CAAC;IAChD,yBAAyB,EAAE,CAAC;SACzB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,uDAAuD,CAAC;SAC/D,QAAQ,EAAE;SACV,QAAQ,CAAC,wCAAwC,CAAC;IACrD,mBAAmB,EAAE,CAAC;SACnB,MAAM,EAAE;SACR,GAAG,CAAC,4CAA4C,CAAC;SACjD,GAAG,CAAC,CAAC,EAAE,mDAAmD,CAAC;SAC3D,QAAQ,EAAE;SACV,QAAQ,CAAC,2BAA2B,CAAC;IACxC,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,kDAAkD,CAAC;SAC1D,QAAQ,EAAE;SACV,QAAQ,CAAC,sBAAsB,CAAC;IACnC,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,qDAAqD,CAAC;SAC7D,QAAQ,EAAE;SACV,QAAQ,CAAC,yBAAyB,CAAC;CACvC,CAAC;KACD,QAAQ,CAAC,iCAAiC,CAAC,CAAC"}

package/dist/esm/options/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/options/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/options/types.ts"],"names":[],"mappings":""}

package/dist/esm/options/with-options.js

@@ -0,0 +1,105 @@
+import { 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, args) => {
+    // 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;
+//# sourceMappingURL=with-options.js.map

package/dist/esm/options/with-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-options.js","sourceRoot":"","sources":["../../../src/options/with-options.ts"],"names":[],"mappings":"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"}

package/dist/esm/register.js

@@ -0,0 +1,34 @@
+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) {
+    // 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;
+//# sourceMappingURL=register.js.map

package/dist/esm/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,OAAgB;IACjE,gDAAgD;IAChD,IAAI,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC;IACpE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,WAAW,CACzC,mEAAmE,CACpE,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IACD,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/esm/setup-framework.js

@@ -0,0 +1,72 @@
+import { enableAI } from '@equinor/fusion-framework-module-ai';
+import { AzureOpenAiEmbed, AzureOpenAIModel, AzureVectorStore, } from '@equinor/fusion-framework-module-ai/azure';
+import { ModulesConfigurator } from '@equinor/fusion-framework-module';
+/**
+ * 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) => {
+    // Create a new module configurator for the framework
+    const configurator = new ModulesConfigurator();
+    // Configure AI module with provided options
+    enableAI(configurator, (aiConfig) => {
+        // 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;
+//# sourceMappingURL=setup-framework.js.map

package/dist/esm/setup-framework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-framework.js","sourceRoot":"","sources":["../../src/setup-framework.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuC,MAAM,qCAAqC,CAAC;AAEpG,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,2CAA2C,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAwB,MAAM,kCAAkC,CAAC;AAW7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,OAAkB,EAA8B,EAAE;IACrF,qDAAqD;IACrD,MAAM,YAAY,GAAG,IAAI,mBAAmB,EAAc,CAAC;IAE3D,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAyB,EAAE,EAAE;QACnD,sDAAsD;QACtD,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;YACjC,QAAQ,CAAC,QAAQ,CACf,OAAO,CAAC,oBAAoB,EAC5B,IAAI,gBAAgB,CAAC;gBACnB,iBAAiB,EAAE,OAAO,CAAC,YAAY;gBACvC,4BAA4B,EAAE,OAAO,CAAC,oBAAoB;gBAC1D,0BAA0B,EAAE,OAAO,CAAC,cAAc;gBAClD,qBAAqB,EAAE,OAAO,CAAC,gBAAgB;aAChD,CAAC,CACH,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC;YACtC,QAAQ,CAAC,YAAY,CACnB,OAAO,CAAC,yBAAyB,EACjC,IAAI,gBAAgB,CAAC;gBACnB,iBAAiB,EAAE,OAAO,CAAC,YAAY;gBACvC,4BAA4B,EAAE,OAAO,CAAC,yBAAyB;gBAC/D,0BAA0B,EAAE,OAAO,CAAC,cAAc;gBAClD,qBAAqB,EAAE,OAAO,CAAC,gBAAgB;aAChD,CAAC,CACH,CAAC;QACJ,CAAC;QAED,8DAA8D;QAC9D,kFAAkF;QAClF,IAAI,OAAO,CAAC,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAC7F,IAAI,CAAC,OAAO,CAAC,yBAAyB,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;YACpF,CAAC;YAED,6DAA6D;YAC7D,iEAAiE;YACjE,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;YAE9F,8DAA8D;YAC9D,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CACb,sBAAsB,OAAO,CAAC,yBAAyB,4CAA4C,CACpG,CAAC;YACJ,CAAC;YAED,QAAQ,CAAC,cAAc,CACrB,OAAO,CAAC,oBAAoB,EAC5B,IAAI,gBAAgB,CAAC,gBAAgB,EAAE;gBACrC,QAAQ,EAAE,OAAO,CAAC,mBAAmB;gBACrC,GAAG,EAAE,OAAO,CAAC,iBAAiB;gBAC9B,SAAS,EAAE,OAAO,CAAC,oBAAoB;aACxC,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,uDAAuD;IACvD,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,UAAU,EAAE,CAAC;IAClD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/esm/version.js

@@ -0,0 +1,3 @@
+// Generated by genversion.
+export const version = '1.0.0';
+//# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}