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

package/src/search.ts

@@ -0,0 +1,284 @@
+import { createCommand, createOption } from 'commander';
+import type { Document } from '@langchain/core/documents';
+import { withAiOptions, type AiOptions } from './options/ai.js';
+
+import { setupFramework } from './utils/setup-framework.js';
+import { inspect } from 'node:util';
+import type { RetrieverOptions } from '@equinor/fusion-framework-module-ai/lib';
+
+/**
+ * Command options for the search command
+ */
+type CommandOptions = AiOptions & {
+  /** Maximum number of search results to return */
+  limit: number;
+  /** Enable verbose output for debugging */
+  verbose: boolean;
+  /** OData filter expression for metadata-based filtering */
+  filter?: string;
+  /** Output results as JSON for programmatic use */
+  json: boolean;
+  /** Output raw metadata without normalization */
+  raw: boolean;
+  /** Search type: 'mmr' for Maximum Marginal Relevance or 'similarity' for similarity search */
+  searchType: 'mmr' | 'similarity';
+};
+
+/**
+ * Normalizes metadata attributes from Azure Search format to a flat object
+ * Azure Search returns metadata attributes as an array of {key, value} pairs,
+ * which this function converts to a simple key-value object for easier access
+ * @param metadata - Raw metadata object that may contain attributes array
+ * @returns Normalized metadata with attributes flattened into the root object
+ */
+const normalizeMetadata = (metadata: Record<string, unknown>): Record<string, unknown> => {
+  const normalized = { ...metadata };
+
+  // Azure Search returns attributes as an array of {key, value} pairs
+  // Convert this to a flat object structure for easier access
+  if (Array.isArray(normalized.attributes)) {
+    const attributesObj: Record<string, unknown> = {};
+    for (const attr of normalized.attributes) {
+      // Validate attribute structure before processing
+      if (
+        typeof attr === 'object' &&
+        attr !== null &&
+        'key' in attr &&
+        'value' in attr &&
+        typeof attr.key === 'string'
+      ) {
+        // Try to parse JSON values (Azure Search stores complex values as JSON strings)
+        // Fall back to raw value if parsing fails (for string values)
+        try {
+          attributesObj[attr.key] = JSON.parse(attr.value as string);
+        } catch {
+          attributesObj[attr.key] = attr.value;
+        }
+      }
+    }
+    // Merge flattened attributes into the root metadata object
+    Object.assign(normalized, attributesObj);
+    // Remove the original attributes array to avoid duplication
+    delete normalized.attributes;
+  }
+
+  return normalized;
+};
+
+/**
+ * CLI command: `ai search`
+ *
+ * Search the vector store to validate embeddings and retrieve relevant documents.
+ *
+ * Features:
+ * - Semantic search using vector embeddings
+ * - Configurable result limits
+ * - Filter support for metadata-based filtering
+ * - JSON output option for programmatic use
+ * - Detailed result display with scores and metadata
+ *
+ * Usage:
+ *   $ ffc ai search <query> [options]
+ *
+ * Options:
+ *   --limit <number>                    Maximum number of results to return (default: 10)
+ *   --search-type <type>                Search type: 'mmr' or 'similarity' (default: similarity)
+ *   --filter <expression>               OData filter expression for metadata filtering
+ *   --json                              Output results as JSON
+ *   --raw                               Output raw metadata without normalization
+ *   --verbose                           Enable verbose output
+ *   --openai-api-key <key>              API key for Azure OpenAI
+ *   --openai-api-version <version>      API version (default: 2024-02-15-preview)
+ *   --openai-instance <name>            Azure OpenAI instance name
+ *   --openai-embedding-deployment <name> Azure OpenAI embedding deployment name
+ *   --azure-search-endpoint <url>       Azure Search endpoint URL
+ *   --azure-search-api-key <key>        Azure Search API key
+ *   --azure-search-index-name <name>    Azure Search index name
+ *
+ * Environment Variables:
+ *   AZURE_OPENAI_API_KEY                    API key for Azure OpenAI
+ *   AZURE_OPENAI_API_VERSION                API version
+ *   AZURE_OPENAI_INSTANCE_NAME              Instance name
+ *   AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME  Embedding deployment name
+ *   AZURE_SEARCH_ENDPOINT                   Azure Search endpoint
+ *   AZURE_SEARCH_API_KEY                    Azure Search API key
+ *   AZURE_SEARCH_INDEX_NAME                 Azure Search index name
+ *
+ * Examples:
+ *   $ ffc ai search "how to use the framework"
+ *   $ ffc ai search "authentication" --limit 5
+ *   $ ffc ai search "typescript" --filter "metadata/source eq 'src/index.ts'"
+ *   $ ffc ai search "documentation" --search-type similarity
+ *   $ ffc ai search "documentation" --json
+ *   $ ffc ai search "documentation" --json --raw
+ *   $ ffc ai search "API reference" --verbose
+ */
+export const command = withAiOptions(
+  createCommand('search')
+    .description('Search the vector store to validate embeddings and retrieve relevant documents')
+    .addOption(
+      createOption('--limit <number>', 'Maximum number of results to return')
+        .default(10)
+        .argParser(parseInt),
+    )
+    .addOption(
+      createOption('--search-type <type>', 'Search type: mmr or similarity')
+        .choices(['mmr', 'similarity'])
+        .default('similarity'),
+    )
+    .addOption(
+      createOption('--filter <expression>', 'OData filter expression for metadata filtering'),
+    )
+    .addOption(createOption('--json', 'Output results as JSON').default(false))
+    .addOption(createOption('--raw', 'Output raw metadata without normalization').default(false))
+    .addOption(createOption('--verbose', 'Enable verbose output').default(false))
+    .argument('<query>', 'Search query string')
+    .action(async (query: string, options: CommandOptions) => {
+      if (options.verbose) {
+        console.log('🔍 Initializing framework...');
+      }
+
+      const framework = await setupFramework(options);
+
+      if (!options.azureSearchIndexName) {
+        throw new Error('Azure Search index name is required');
+      }
+
+      if (options.verbose) {
+        console.log('✅ Framework initialized successfully');
+        console.log(`🔎 Searching for: "${query}"`);
+        console.log(`📊 Limit: ${options.limit}`);
+        console.log(`🔍 Search type: ${options.searchType}`);
+        if (options.filter) {
+          console.log(`🔧 Filter: ${options.filter}`);
+        }
+        console.log('');
+      }
+
+      const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+
+      try {
+        // Configure retriever options for semantic search
+        // The retriever provides more control over search parameters than direct vector store queries
+        // RetrieverOptions is a discriminated union, so we construct it based on search type
+        const filter = options.filter
+          ? {
+              filterExpression: options.filter,
+            }
+          : undefined;
+
+        // Construct retriever options based on search type
+        // MMR search requires additional parameters for diversity optimization
+        // Similarity search doesn't need these parameters
+        const retrieverOptions: RetrieverOptions =
+          options.searchType === 'mmr'
+            ? {
+                k: options.limit,
+                searchType: 'mmr',
+                ...(filter && { filter: filter as Record<string, unknown> }),
+              }
+            : {
+                k: options.limit,
+                searchType: 'similarity',
+                ...(filter && { filter: filter as Record<string, unknown> }),
+              };
+
+        // Create retriever and execute search query
+        const retriever = vectorStoreService.asRetriever(retrieverOptions);
+        const results = await retriever.invoke(query);
+
+        // Validate that results is an array
+        if (!results || !Array.isArray(results)) {
+          throw new Error(
+            `Invalid search results: expected array but got ${results === null ? 'null' : typeof results}`,
+          );
+        }
+
+        if (options.json) {
+          // Output as JSON for programmatic use (e.g., piping to other tools)
+          for (const doc of results) {
+            if (options.raw) {
+              // Output raw document structure with full depth inspection
+              console.log(inspect(doc, { depth: null, colors: true }));
+            } else {
+              // Output normalized metadata for cleaner JSON structure
+              const metadata = normalizeMetadata(doc.metadata as Record<string, unknown>);
+              console.log({
+                content: doc.pageContent,
+                metadata,
+                score: (metadata as { score?: number })?.score,
+              });
+            }
+          }
+        } else {
+          // Format results for human-readable output
+          if (results.length === 0) {
+            console.log('❌ No results found');
+            return;
+          }
+
+          console.log(`✅ Found ${results.length} result${results.length !== 1 ? 's' : ''}:\n`);
+
+          results.forEach((doc: Document, index: number) => {
+            // Normalize metadata to flatten attributes array unless --raw flag is set
+            // Raw mode preserves Azure Search's original metadata structure
+            const processedMetadata = options.raw
+              ? (doc.metadata as Record<string, unknown>)
+              : normalizeMetadata(doc.metadata as Record<string, unknown>);
+            const metadata = processedMetadata as {
+              source?: string;
+              score?: number;
+              [key: string]: unknown;
+            };
+            const score = metadata.score;
+            const source = metadata.source || 'Unknown source';
+
+            // Display result header with score if available
+            console.log(`${'─'.repeat(80)}`);
+            console.log(
+              `Result ${index + 1}${score !== undefined ? ` (Score: ${score.toFixed(4)})` : ''}`,
+            );
+            console.log(`Source: ${source}`);
+
+            // Display additional metadata fields if verbose mode is enabled
+            // Exclude source and score from additional metadata to avoid duplication
+            if (options.verbose) {
+              const { source: _, score: __, ...otherMetadata } = metadata;
+              if (Object.keys(otherMetadata).length > 0) {
+                console.log(`Metadata:`, JSON.stringify(otherMetadata, null, 2));
+              }
+            }
+            console.log('');
+
+            // Truncate content if too long to keep output readable
+            // Full content is still available in JSON mode
+            const content = doc.pageContent;
+            const maxLength = 500;
+            if (content.length > maxLength) {
+              console.log(`${content.substring(0, maxLength)}...`);
+              console.log(`\n[Content truncated - ${content.length} characters total]`);
+            } else {
+              console.log(content);
+            }
+            console.log('');
+          });
+
+          console.log(`${'─'.repeat(80)}`);
+        }
+      } catch (error) {
+        console.error(
+          `❌ Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+        if (options.verbose && error instanceof Error && error.stack) {
+          console.error(error.stack);
+        }
+        process.exit(1);
+      }
+    }),
+  {
+    includeEmbedding: true,
+    includeSearch: true,
+  },
+);
+
+export default command;

package/src/utils/setup-framework.ts

@@ -0,0 +1,75 @@
+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/ai.js';
+import { ModulesConfigurator, type ModulesInstance } from '@equinor/fusion-framework-module';
+
+/**
+ * Initializes and configures the Fusion Framework with AI module capabilities
+ * @param options - AI configuration options including API keys, deployments, and vector store settings
+ * @returns Promise resolving to an initialized framework instance with AI module
+ * @throws {Error} If embedding deployment is required but not provided when configuring vector store
+ */
+export const setupFramework = async (options: AiOptions): Promise<ModulesInstance<[AIModule]>> => {
+  // 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);
+
+      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;
+};

package/src/version.ts

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

package/tsconfig.json

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