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

package/dist/types/config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Base configuration interface for Fusion AI operations.
+ *
+ * This interface serves as the base type for all Fusion AI configuration objects.
+ * Implementations should extend this interface with specific configuration properties
+ * relevant to their use case. The configuration is typically created using
+ * `configureFusionAI` and loaded via `loadFusionAIConfig`.
+ */
+export interface FusionAIConfig {
+    [key: string]: unknown;
+}
+/**
+ * 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 declare const configureFusionAI: <T extends FusionAIConfig>(fn: () => Promise<T> | T) => () => Promise<T> | T;
+/**
+ * Options for loading Fusion AI configuration
+ */
+export interface LoadFusionAIConfigOptions {
+    /** Base directory to resolve the config file from (default: process.cwd()) */
+    baseDir?: string;
+    /** File extensions to consider when resolving the config file (default: ['.ts', '.mjs', '.js', '.json']) */
+    extensions?: string[];
+}
+/**
+ * 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 declare function loadFusionAIConfig<T extends FusionAIConfig = FusionAIConfig>(configPath?: string, options?: LoadFusionAIConfigOptions): Promise<T>;
+export default loadFusionAIConfig;

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { type FusionAIConfig, type LoadFusionAIConfigOptions, configureFusionAI, loadFusionAIConfig, } from './config.js';
+export { setupFramework, FrameworkInstance } from './setup-framework.js';
+export { registerAiPlugin } from './register.js';

package/dist/types/options/index.d.ts

@@ -0,0 +1,4 @@
+export { default as options } from './options.js';
+export { withOptions } from './with-options.js';
+export { AiOptionsSchema, type AiOptionsType } from './schema.js';
+export type { AiOptions } from './types.js';

package/dist/types/options/options.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Option for specifying the Azure OpenAI API key.
+ * Required for authentication with Azure OpenAI services.
+ */
+export declare const apiKeyOption: import("commander").Option;
+/**
+ * Option for specifying the Azure OpenAI API version.
+ * Defaults to the latest stable version if not provided.
+ */
+export declare const apiVersionOption: import("commander").Option;
+/**
+ * Option for specifying the Azure OpenAI instance name.
+ * Required for Azure OpenAI service endpoint construction.
+ */
+export declare const apiInstanceOption: import("commander").Option;
+/**
+ * Option for specifying the Azure OpenAI deployment name for chat models.
+ * Required for chat completions API calls.
+ */
+export declare const chatDeploymentOption: import("commander").Option;
+/**
+ * Option for specifying the Azure OpenAI deployment name for embedding models.
+ * Required for embeddings API calls.
+ */
+export declare const embeddingDeploymentOption: import("commander").Option;
+/**
+ * Option for specifying the Azure Search endpoint URL.
+ * Required for Azure Cognitive Search operations.
+ */
+export declare const azureSearchEndpointOption: import("commander").Option;
+/**
+ * Option for specifying the Azure Search API key.
+ * Required for authentication with Azure Cognitive Search.
+ */
+export declare const azureSearchApiKeyOption: import("commander").Option;
+/**
+ * Option for specifying the Azure Search index name.
+ * Required for search operations on a specific index.
+ */
+export declare const azureSearchIndexNameOption: import("commander").Option;
+/**
+ * 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.
+ */
+declare const _default: {
+    apiKeyOption: import("commander").Option;
+    apiVersionOption: import("commander").Option;
+    apiInstanceOption: import("commander").Option;
+    chatDeploymentOption: import("commander").Option;
+    embeddingDeploymentOption: import("commander").Option;
+    azureSearchEndpointOption: import("commander").Option;
+    azureSearchApiKeyOption: import("commander").Option;
+    azureSearchIndexNameOption: import("commander").Option;
+};
+export default _default;

package/dist/types/options/schema.d.ts

@@ -0,0 +1,52 @@
+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 declare const AiOptionsSchema: z.ZodObject<{
+    openaiApiKey: z.ZodString;
+    openaiApiVersion: z.ZodString;
+    openaiInstance: z.ZodString;
+    openaiChatDeployment: z.ZodOptional<z.ZodString>;
+    openaiEmbeddingDeployment: z.ZodOptional<z.ZodString>;
+    azureSearchEndpoint: z.ZodOptional<z.ZodString>;
+    azureSearchApiKey: z.ZodOptional<z.ZodString>;
+    azureSearchIndexName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    openaiApiKey: string;
+    openaiApiVersion: string;
+    openaiInstance: string;
+    openaiChatDeployment?: string | undefined;
+    openaiEmbeddingDeployment?: string | undefined;
+    azureSearchEndpoint?: string | undefined;
+    azureSearchApiKey?: string | undefined;
+    azureSearchIndexName?: string | undefined;
+}, {
+    openaiApiKey: string;
+    openaiApiVersion: string;
+    openaiInstance: string;
+    openaiChatDeployment?: string | undefined;
+    openaiEmbeddingDeployment?: string | undefined;
+    azureSearchEndpoint?: string | undefined;
+    azureSearchApiKey?: string | undefined;
+    azureSearchIndexName?: string | undefined;
+}>;
+/**
+ * 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/dist/types/options/types.d.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/dist/types/options/with-options.d.ts

@@ -0,0 +1,37 @@
+import { type Command } from 'commander';
+/**
+ * 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 declare const withOptions: (command: Command, args?: Partial<{
+    includeEmbedding: boolean;
+    includeChat: boolean;
+    includeSearch: boolean;
+}>) => Command;
+export default withOptions;

package/dist/types/register.d.ts

@@ -0,0 +1,25 @@
+import type { Command } 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 declare function registerAiPlugin(program: Command, command: Command): void;
+export default registerAiPlugin;

package/dist/types/setup-framework.d.ts

@@ -0,0 +1,33 @@
+import { type AIModule } from '@equinor/fusion-framework-module-ai';
+import type { AiOptions } from './options/index.js';
+import { 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 declare const setupFramework: (options: AiOptions) => Promise<FrameworkInstance>;
+export default setupFramework;

package/dist/types/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "1.0.0";

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@equinor/fusion-framework-cli-plugin-ai-base",
+  "version": "1.0.0",
+  "description": "Base AI plugin package for Fusion Framework CLI",
+  "type": "module",
+  "main": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./command-options": {
+      "import": "./dist/esm/options/index.js",
+      "types": "./dist/types/options/index.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "dist/types/index.d.ts"
+      ],
+      "./command-options": [
+        "dist/types/options/index.d.ts"
+      ]
+    }
+  },
+  "keywords": [
+    "fusion-framework",
+    "cli",
+    "plugin",
+    "llm",
+    "ai"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/equinor/fusion-framework.git",
+    "directory": "packages/cli-plugins/ai-base"
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "zod": "^3.23.8",
+    "@equinor/fusion-framework-module-ai": "2.0.0",
+    "@equinor/fusion-framework-module": "5.0.5",
+    "@equinor/fusion-imports": "1.1.8"
+  },
+  "peerDependencies": {
+    "@equinor/fusion-framework-cli": "13.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "build:types": "tsc -b",
+    "test": "vitest"
+  }
+}

package/src/config.ts

@@ -0,0 +1,87 @@
+import { importConfig } from '@equinor/fusion-imports';
+
+/**
+ * Base configuration interface for Fusion AI operations.
+ *
+ * This interface serves as the base type for all Fusion AI configuration objects.
+ * Implementations should extend this interface with specific configuration properties
+ * relevant to their use case. The configuration is typically created using
+ * `configureFusionAI` and loaded via `loadFusionAIConfig`.
+ */
+export interface FusionAIConfig {
+  [key: string]: unknown;
+}
+
+/**
+ * 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 = <T extends FusionAIConfig>(fn: () => Promise<T> | T) => fn;
+
+/**
+ * Options for loading Fusion AI configuration
+ */
+export interface LoadFusionAIConfigOptions {
+  /** Base directory to resolve the config file from (default: process.cwd()) */
+  baseDir?: string;
+  /** File extensions to consider when resolving the config file (default: ['.ts', '.mjs', '.js', '.json']) */
+  extensions?: string[];
+}
+
+/**
+ * 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<T extends FusionAIConfig = FusionAIConfig>(
+  configPath: string = 'fusion-ai.config',
+  options: LoadFusionAIConfigOptions = {},
+): Promise<T> {
+  const { baseDir = process.cwd(), extensions } = options;
+
+  // Load configuration - config file exports a function for dynamic configuration
+  const result = await importConfig<() => Promise<T> | T>(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 as T;
+}
+
+export default loadFusionAIConfig;

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 {
+  type FusionAIConfig,
+  type LoadFusionAIConfigOptions,
+  configureFusionAI,
+  loadFusionAIConfig,
+} from './config.js';
+export { setupFramework, FrameworkInstance } from './setup-framework.js';
+export { registerAiPlugin } from './register.js';

package/src/options/index.ts

@@ -0,0 +1,4 @@
+export { default as options } from './options.js';
+export { withOptions } from './with-options.js';
+export { AiOptionsSchema, type AiOptionsType } from './schema.js';
+export type { AiOptions } from './types.js';

package/src/options/options.ts

@@ -0,0 +1,92 @@
+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,
+};

package/src/options/schema.ts

@@ -0,0 +1,71 @@
+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');
+
+/**
+ * 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>;