@equinor/fusion-framework-cli-plugin-ai-index 2.0.0 → 2.1.0

package/src/schema.ts

@@ -0,0 +1,149 @@
+import type { z } from 'zod';
+import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
+
+/**
+ * Attribute map type used by {@link IndexSchemaConfig.prepareAttributes}.
+ *
+ * Combines the schema-declared field types (all optional, since
+ * attributes are built up incrementally) with a `Record<string, unknown>`
+ * base so non-promoted attributes are still accessible.
+ *
+ * @template T - Zod object schema from which attribute types are derived.
+ */
+export type SchemaAttributes<T extends z.ZodObject> = Partial<z.input<T>> & Record<string, unknown>;
+
+/**
+ * Configuration for a custom Azure AI Search index schema defined via a Zod
+ * object shape.
+ *
+ * Declares which metadata fields should be promoted to top-level Azure AI
+ * Search fields (instead of being stored in the generic `attributes` array)
+ * and how their values are resolved from each document.
+ *
+ * Promoted fields become filterable/facetable at the Azure Search level,
+ * eliminating the need for `any()` OData operators.
+ *
+ * @template T - Zod object schema type that defines the promoted field names and types.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineIndexSchema } from '@equinor/fusion-framework-cli-plugin-ai-index';
+ *
+ * const schema = defineIndexSchema({
+ *   shape: z.object({
+ *     pkg_name: z.string().optional(),
+ *     type: z.string(),
+ *     tags: z.array(z.string()).default([]),
+ *     source_dir: z.string(),
+ *   }),
+ *   prepareAttributes: (attrs, doc) => {
+ *     // attrs.tags is typed as string[] | undefined ✅
+ *     attrs.tags ??= [];
+ *     if (doc.metadata.source.includes('packages/')) {
+ *       attrs.tags.push('package');
+ *     }
+ *     return attrs;
+ *   },
+ *   resolve: (doc) => ({
+ *     pkg_name: doc.metadata.attributes?.pkg_name as string | undefined,
+ *     type: (doc.metadata.attributes?.type as string) ?? 'unknown',
+ *     tags: (doc.metadata.attributes?.tags as string[]) ?? [],
+ *     source_dir: doc.metadata.source.split('/')[0],
+ *   }),
+ * });
+ * ```
+ */
+export interface IndexSchemaConfig<T extends z.ZodObject = z.ZodObject> {
+  /**
+   * Zod object schema defining the promoted field names and their types.
+   *
+   * Each key becomes a top-level Azure AI Search field. The Zod type
+   * determines the Azure EDM field type:
+   * - `z.string()` → `Edm.String` (filterable, facetable)
+   * - `z.array(z.string())` → `Collection(Edm.String)` (filterable, facetable)
+   * - `z.number()` → `Edm.Double` (filterable, sortable)
+   * - `z.boolean()` → `Edm.Boolean` (filterable)
+   */
+  shape: T;
+
+  /**
+   * Type-safe attribute processor that enriches document attributes before
+   * the schema resolver runs.
+   *
+   * Runs in addition to the untyped `metadata.attributeProcessor` callback
+   * when a schema is defined. The `attributes` parameter is typed from the
+   * Zod shape so that schema-declared fields (e.g. `tags`, `pkg_name`)
+   * have proper types while non-schema attributes remain accessible via
+   * the `Record<string, unknown>` base.
+   *
+   * Runs after git and package metadata enrichment and after
+   * `metadata.attributeProcessor`, before
+   * {@link IndexSchemaConfig.resolve | resolve}.
+   *
+   * @param attributes - The accumulated attributes for the document, typed
+   *   from the schema shape. All schema fields are optional since they may
+   *   not be populated yet.
+   * @param document - The vector-store document being processed.
+   * @returns The enriched attributes map.
+   */
+  prepareAttributes?: (
+    attributes: SchemaAttributes<T>,
+    document: VectorStoreDocument,
+  ) => SchemaAttributes<T>;
+
+  /**
+   * Per-document resolver that extracts or computes promoted field values.
+   *
+   * Runs after {@link IndexSchemaConfig.prepareAttributes | prepareAttributes}
+   * and metadata enrichment (git, package), so all enriched attributes are
+   * available on the document.
+   *
+   * @param document - The fully enriched vector-store document.
+   * @returns An object matching the Zod shape with resolved field values.
+   */
+  resolve: (document: VectorStoreDocument) => z.output<T>;
+}
+
+/**
+ * Type-safe factory for creating an {@link IndexSchemaConfig}.
+ *
+ * Infers `T` from the Zod shape and constrains both the
+ * `prepareAttributes` parameter types and the `resolve` return type,
+ * providing compile-time safety that attribute processing and resolution
+ * match the declared schema.
+ *
+ * @template T - Zod object schema type, inferred from `config.shape`.
+ * @param config - Schema configuration with a Zod shape, optional typed
+ *   attribute processor, and a resolver function.
+ * @returns The same config object, narrowed to the inferred generic type.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineIndexSchema } from '@equinor/fusion-framework-cli-plugin-ai-index';
+ *
+ * const schema = defineIndexSchema({
+ *   shape: z.object({
+ *     tags: z.array(z.string()).default([]),
+ *     type: z.string(),
+ *   }),
+ *   prepareAttributes: (attrs, doc) => {
+ *     attrs.tags ??= []; // string[] | undefined — type-safe ✅
+ *     if (doc.metadata.source.includes('cookbooks/')) {
+ *       attrs.tags.push('cookbook');
+ *     }
+ *     return attrs;
+ *   },
+ *   resolve: (doc) => ({
+ *     tags: (doc.metadata.attributes?.tags as string[]) ?? [],
+ *     type: (doc.metadata.attributes?.type as string) ?? 'raw',
+ *   }),
+ * });
+ * ```
+ */
+export function defineIndexSchema<T extends z.ZodObject>(
+  config: IndexSchemaConfig<T>,
+): IndexSchemaConfig<T> {
+  return config;
+}

package/src/search-command.ts

@@ -2,11 +2,12 @@ import { createCommand, createOption } from 'commander';
 import type { Document } from '@langchain/core/documents';
 import { inspect } from 'node:util';
 
-import { setupFramework } from '@equinor/fusion-framework-cli-plugin-ai-base';
+import { loadFusionAIConfig, setupFramework } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import {
   withOptions as withAiOptions,
   type AiOptions,
 } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
+import type { FusionAIConfigWithIndex } from './config.js';
 import type { RetrieverOptions } from '@equinor/fusion-framework-module-ai/lib';
 
 /**
@@ -107,6 +108,7 @@ const normalizeMetadata = (metadata: Record<string, unknown>): Record<string, un
  */
 const _command = createCommand('search')
   .description('Search the vector store to validate embeddings and retrieve relevant documents')
+  .addOption(createOption('--config <config>', 'Path to a config file').default('fusion-ai.config'))
   .addOption(
     createOption('--limit <number>', 'Maximum number of results to return')
       .default(10)
@@ -124,6 +126,21 @@ const _command = createCommand('search')
   .addOption(createOption('--raw', 'Output raw metadata without normalization').default(false))
   .addOption(createOption('--verbose', 'Enable verbose output').default(false))
   .argument('<query>', 'Search query string')
+  .hook('preAction', async (thisCommand) => {
+    const opts = thisCommand.opts();
+    const config = await loadFusionAIConfig<FusionAIConfigWithIndex>(
+      (opts.config as string) ?? 'fusion-ai.config',
+      { baseDir: process.cwd() },
+    );
+    const indexConfig = config.index ?? {};
+
+    if (indexConfig.name && !opts.indexName?.trim()) {
+      thisCommand.setOptionValue('indexName', indexConfig.name);
+    }
+    if (indexConfig.model && !opts.embedModel?.trim()) {
+      thisCommand.setOptionValue('embedModel', indexConfig.model);
+    }
+  })
   .action(async (query: string, options: CommandOptions) => {
     if (options.verbose) {
       console.log('🔍 Initializing framework...');
@@ -131,13 +148,13 @@ const _command = createCommand('search')
 
     const framework = await setupFramework(options);
 
-    if (!options.azureSearchIndexName) {
-      throw new Error('Azure Search index name is required');
+    if (!options.indexName) {
+      throw new Error('Index name is required');
     }
 
     if (options.verbose) {
       console.log('✅ Framework initialized successfully');
-      console.log(`📇 Index: ${options.azureSearchIndexName}`);
+      console.log(`📇 Index: ${options.indexName}`);
       console.log(`🔎 Searching for: "${query}"`);
       console.log(`📊 Limit: ${options.limit}`);
       console.log(`🔍 Search type: ${options.searchType}`);
@@ -147,7 +164,7 @@ const _command = createCommand('search')
       console.log('');
     }
 
-    const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+    const vectorStoreService = framework.ai.useIndex(options.indexName);
 
     try {
       const filter = options.filter ? { filterExpression: options.filter } : undefined;

package/src/utils/embedding-dimensions.ts

@@ -0,0 +1,39 @@
+/**
+ * Known OpenAI embedding model names and their output vector dimensions.
+ *
+ * Used by the `ffc ai index create` command to set the `dimensions`
+ * property on the `content_vector` field in the Azure AI Search schema.
+ *
+ * @see https://platform.openai.com/docs/guides/embeddings
+ */
+const KNOWN_MODEL_DIMENSIONS: ReadonlyMap<string, number> = new Map([
+  ['text-embedding-3-large', 3072],
+  ['text-embedding-3-small', 1536],
+  ['text-embedding-ada-002', 1536],
+]);
+
+/**
+ * Resolve the embedding vector dimensions for a given model name.
+ *
+ * Checks the known model→dimensions map first. Falls back to an explicit
+ * `dimensions` override from the config. Throws if neither is available.
+ *
+ * @param model - The embedding model name (e.g. `'text-embedding-3-large'`).
+ * @param configDimensions - Optional explicit dimensions from config, used
+ *   when the model is not in the known map.
+ * @returns The number of dimensions for the embedding vector.
+ * @throws {Error} When the model is unknown and no explicit dimensions are configured.
+ */
+export function resolveEmbeddingDimensions(model: string, configDimensions?: number): number {
+  const known = KNOWN_MODEL_DIMENSIONS.get(model);
+  if (known !== undefined) return known;
+
+  if (configDimensions !== undefined) return configDimensions;
+
+  const knownModels = [...KNOWN_MODEL_DIMENSIONS.keys()].join(', ');
+  throw new Error(
+    `Unknown embedding model "${model}". ` +
+      `Known models: ${knownModels}. ` +
+      'For custom models, set `index.embedding.dimensions` in the config.',
+  );
+}

package/src/utils/zod-to-azure-fields.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+
+import { zodToAzureFields } from './zod-to-azure-fields.js';
+
+describe('zodToAzureFields', () => {
+  it('maps z.string() to Edm.String with filterable + facetable', () => {
+    const schema = z.object({ pkg_name: z.string() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields).toEqual([
+      {
+        name: 'pkg_name',
+        type: 'Edm.String',
+        filterable: true,
+        sortable: false,
+        facetable: true,
+        searchable: false,
+      },
+    ]);
+  });
+
+  it('maps z.number() to Edm.Double with filterable + sortable', () => {
+    const schema = z.object({ score: z.number() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields).toEqual([
+      {
+        name: 'score',
+        type: 'Edm.Double',
+        filterable: true,
+        sortable: true,
+        facetable: false,
+        searchable: false,
+      },
+    ]);
+  });
+
+  it('maps z.boolean() to Edm.Boolean with filterable', () => {
+    const schema = z.object({ active: z.boolean() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields).toEqual([
+      {
+        name: 'active',
+        type: 'Edm.Boolean',
+        filterable: true,
+        sortable: false,
+        facetable: false,
+        searchable: false,
+      },
+    ]);
+  });
+
+  it('maps z.array(z.string()) to Collection(Edm.String) with filterable + facetable', () => {
+    const schema = z.object({ tags: z.array(z.string()) });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields).toEqual([
+      {
+        name: 'tags',
+        type: 'Collection(Edm.String)',
+        filterable: true,
+        sortable: false,
+        facetable: true,
+        searchable: false,
+      },
+    ]);
+  });
+
+  it('maps z.enum() to Edm.String', () => {
+    const schema = z.object({ status: z.enum(['draft', 'published']) });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields[0]).toMatchObject({ name: 'status', type: 'Edm.String' });
+  });
+
+  it('unwraps z.optional() to the inner type', () => {
+    const schema = z.object({ pkg_name: z.string().optional() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields[0]).toMatchObject({ name: 'pkg_name', type: 'Edm.String' });
+  });
+
+  it('unwraps z.default() to the inner type', () => {
+    const schema = z.object({ tags: z.array(z.string()).default([]) });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields[0]).toMatchObject({ name: 'tags', type: 'Collection(Edm.String)' });
+  });
+
+  it('unwraps z.nullable() to the inner type', () => {
+    const schema = z.object({ name: z.string().nullable() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields[0]).toMatchObject({ name: 'name', type: 'Edm.String' });
+  });
+
+  it('unwraps nested wrappers (optional + default)', () => {
+    const schema = z.object({ tags: z.array(z.string()).default([]).optional() });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields[0]).toMatchObject({ name: 'tags', type: 'Collection(Edm.String)' });
+  });
+
+  it('handles multiple fields in a single schema', () => {
+    const schema = z.object({
+      pkg_name: z.string().optional(),
+      type: z.string(),
+      tags: z.array(z.string()).default([]),
+      source_dir: z.string(),
+    });
+    const fields = zodToAzureFields(schema);
+
+    expect(fields).toHaveLength(4);
+    expect(fields.map((f) => f.name)).toEqual(['pkg_name', 'type', 'tags', 'source_dir']);
+    expect(fields.map((f) => f.type)).toEqual([
+      'Edm.String',
+      'Edm.String',
+      'Collection(Edm.String)',
+      'Edm.String',
+    ]);
+  });
+
+  it('throws for unsupported Zod types (z.object)', () => {
+    const schema = z.object({ nested: z.object({ a: z.string() }) });
+
+    expect(() => zodToAzureFields(schema)).toThrow(/Unsupported Zod type/);
+  });
+
+  it('throws for unsupported array element types (z.array(z.number()))', () => {
+    const schema = z.object({ nums: z.array(z.number()) });
+
+    expect(() => zodToAzureFields(schema)).toThrow(/Unsupported array element type/);
+  });
+});

package/src/utils/zod-to-azure-fields.ts

@@ -0,0 +1,177 @@
+import {
+  type z,
+  ZodString,
+  ZodNumber,
+  ZodBoolean,
+  ZodArray,
+  ZodEnum,
+  ZodOptional,
+  ZodDefault,
+  ZodNullable,
+  type ZodType,
+} from 'zod';
+
+/**
+ * Azure AI Search EDM (Entity Data Model) type identifiers used in
+ * index field definitions.
+ */
+type AzureEdmType =
+  | 'Edm.String'
+  | 'Edm.Int32'
+  | 'Edm.Int64'
+  | 'Edm.Double'
+  | 'Edm.Boolean'
+  | 'Collection(Edm.String)';
+
+/**
+ * Azure AI Search field definition matching the REST API schema for
+ * index creation.
+ *
+ * @see https://learn.microsoft.com/en-us/rest/api/searchservice/indexes/create
+ */
+export interface AzureSearchField {
+  /** Field name as it appears in the index schema. */
+  name: string;
+  /** Azure EDM type for the field. */
+  type: AzureEdmType;
+  /** Whether the field can be used in `$filter` expressions. */
+  filterable: boolean;
+  /** Whether the field can be used in `$orderby` expressions. */
+  sortable: boolean;
+  /** Whether the field supports faceted navigation. */
+  facetable: boolean;
+  /** Whether the field is included in full-text search. */
+  searchable: boolean;
+}
+
+/**
+ * Unwrap wrapper types (optional, default, nullable) to reach the
+ * underlying concrete Zod type.
+ *
+ * Uses public `instanceof` checks and `unwrap()` methods to avoid
+ * reliance on Zod's private `_zod.def` internals.
+ *
+ * @param schema - A Zod schema node, possibly wrapped.
+ * @returns The innermost non-wrapper schema.
+ */
+function unwrapSchema(schema: ZodType): ZodType {
+  let current: ZodType = schema;
+  // Walk through wrapper layers until we reach a concrete type
+  while (
+    current instanceof ZodOptional ||
+    current instanceof ZodDefault ||
+    current instanceof ZodNullable
+  ) {
+    current = current.unwrap() as ZodType;
+  }
+  return current;
+}
+
+/**
+ * Map a concrete (unwrapped) Zod schema to its Azure EDM field type.
+ *
+ * Uses public `instanceof` checks against Zod's exported class hierarchy
+ * for forward-compatible type mapping.
+ *
+ * @param schema - The unwrapped Zod schema node.
+ * @returns The corresponding Azure EDM type string.
+ * @throws {Error} When the Zod type cannot be mapped to an Azure EDM type.
+ */
+function zodToEdmType(schema: ZodType): AzureEdmType {
+  if (schema instanceof ZodString || schema instanceof ZodEnum) {
+    return 'Edm.String';
+  }
+  if (schema instanceof ZodNumber) {
+    return 'Edm.Double';
+  }
+  if (schema instanceof ZodBoolean) {
+    return 'Edm.Boolean';
+  }
+  if (schema instanceof ZodArray) {
+    const elementSchema = unwrapSchema(schema.element as ZodType);
+    if (elementSchema instanceof ZodString || elementSchema instanceof ZodEnum) {
+      return 'Collection(Edm.String)';
+    }
+    throw new Error(
+      `Unsupported array element type "${elementSchema.constructor.name}". Only string arrays are supported for Azure Search fields.`,
+    );
+  }
+  throw new Error(
+    `Unsupported Zod type "${schema.constructor.name}" for Azure Search field mapping. ` +
+      'Supported types: ZodString, ZodNumber, ZodBoolean, ZodEnum, ZodArray(ZodString).',
+  );
+}
+
+/**
+ * Derive default field capabilities from an Azure EDM type.
+ *
+ * All promoted fields are filterable. Strings and string collections are
+ * also facetable. Numbers are sortable.
+ *
+ * @param edmType - The Azure EDM type of the field.
+ * @returns Default capability flags for the field.
+ */
+function defaultCapabilities(
+  edmType: AzureEdmType,
+): Pick<AzureSearchField, 'filterable' | 'sortable' | 'facetable' | 'searchable'> {
+  switch (edmType) {
+    case 'Edm.String':
+      return { filterable: true, sortable: false, facetable: true, searchable: false };
+    case 'Collection(Edm.String)':
+      return { filterable: true, sortable: false, facetable: true, searchable: false };
+    case 'Edm.Double':
+    case 'Edm.Int32':
+    case 'Edm.Int64':
+      return { filterable: true, sortable: true, facetable: false, searchable: false };
+    case 'Edm.Boolean':
+      return { filterable: true, sortable: false, facetable: false, searchable: false };
+    default:
+      return { filterable: true, sortable: false, facetable: false, searchable: false };
+  }
+}
+
+/**
+ * Convert a Zod object schema into an array of Azure AI Search field
+ * definitions.
+ *
+ * Walks the Zod shape, maps each field to its Azure EDM type, and assigns
+ * default capabilities (filterable, facetable, sortable). Used by the
+ * `ffc ai index create` command to generate the index schema.
+ *
+ * Uses public `instanceof` checks and `unwrap()` methods to avoid
+ * reliance on Zod's private `_zod.def` internals, ensuring compatibility
+ * across Zod versions.
+ *
+ * @param schema - A Zod object schema whose keys define the promoted fields.
+ * @returns An array of Azure AI Search field definitions.
+ * @throws {Error} When a field type cannot be mapped to an Azure EDM type.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { zodToAzureFields } from './zod-to-azure-fields.js';
+ *
+ * const fields = zodToAzureFields(
+ *   z.object({
+ *     pkg_name: z.string().optional(),
+ *     tags: z.array(z.string()).default([]),
+ *   }),
+ * );
+ * // [
+ * //   { name: 'pkg_name', type: 'Edm.String', filterable: true, facetable: true, ... },
+ * //   { name: 'tags', type: 'Collection(Edm.String)', filterable: true, facetable: true, ... },
+ * // ]
+ * ```
+ */
+export function zodToAzureFields(schema: z.ZodObject): AzureSearchField[] {
+  const shape = schema.shape as Record<string, ZodType>;
+
+  return Object.entries(shape).map(([name, fieldSchema]) => {
+    // Unwrap wrapper types to reach the concrete type
+    const innerSchema = unwrapSchema(fieldSchema);
+    const edmType = zodToEdmType(innerSchema);
+    const capabilities = defaultCapabilities(edmType);
+
+    return { name, type: edmType, ...capabilities };
+  });
+}

package/src/version.ts

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