feat(codegen): pluggable embedding system with --auto-embed flag

Adds a pluggable text-to-vector embedding system for CLI search commands:

- New embedder.ts template using @agentic-kit/ollama for Ollama provider
- resolveEmbedder() resolves from env vars or appstash config
- autoEmbedWhere() converts text values to vector embeddings in where clauses
- --auto-embed flag on list and search commands for tables with vector fields
- Embedder module conditionally generated when tables have embedding fields
- Updated docs-generator with --auto-embed examples for vector fields
- CLI e2e tests for embedder: error without provider, real Ollama integration

Author: pyramation

graphql/codegen/src/core/codegen/cli/index.ts

@@ -14,7 +14,7 @@ import {
   generateMultiTargetContextCommand,
 } from './infra-generator';
 import { generateTableCommand } from './table-command-generator';
-import { generateUtilsFile, generateNodeFetchFile, generateEntryPointFile } from './utils-generator';
+import { generateUtilsFile, generateNodeFetchFile, generateEntryPointFile, generateEmbedderFile } from './utils-generator';
 
 export interface GenerateCliOptions {
   tables: Table[];
@@ -59,6 +59,14 @@ export function generateCli(options: GenerateCliOptions): GenerateCliResult {
   const utilsFile = generateUtilsFile();
   files.push(utilsFile);
 
+  // Generate embedder module if any table has vector embedding fields
+  const hasAnyEmbeddings = tables.some((t) =>
+    t.fields.some((f) => f.type.gqlType === 'Vector' || f.type.gqlType === '[Float]'),
+  );
+  if (hasAnyEmbeddings) {
+    files.push(generateEmbedderFile());
+  }
+
   // Generate node HTTP adapter if configured (for *.localhost subdomain routing)
   if (useNodeHttpAdapter) {
     files.push(generateNodeFetchFile());
@@ -180,6 +188,16 @@ export function generateMultiTargetCli(
   const utilsFile = generateUtilsFile();
   files.push(utilsFile);
 
+  // Generate embedder module if any target has tables with vector embedding fields
+  const hasAnyMtEmbeddings = targets.some((tgt) =>
+    tgt.tables.some((t) =>
+      t.fields.some((f) => f.type.gqlType === 'Vector' || f.type.gqlType === '[Float]'),
+    ),
+  );
+  if (hasAnyMtEmbeddings) {
+    files.push(generateEmbedderFile());
+  }
+
   // Generate node HTTP adapter if configured (for *.localhost subdomain routing)
   if (options.nodeHttpAdapter) {
     files.push(generateNodeFetchFile());
@@ -299,5 +317,5 @@ export {
 export type { MultiTargetDocsInput } from './docs-generator';
 export { resolveDocsConfig } from '../docs-utils';
 export type { GeneratedDocFile } from '../docs-utils';
-export { generateUtilsFile, generateEntryPointFile } from './utils-generator';
+export { generateUtilsFile, generateEntryPointFile, generateEmbedderFile } from './utils-generator';
 export type { GeneratedFile, MultiTargetExecutorInput } from './executor-generator';

graphql/codegen/src/core/codegen/cli/table-command-generator.ts

@@ -311,7 +311,103 @@ function buildSubcommandSwitch(
   return t.switchStatement(t.identifier('subcommand'), cases);
 }
 
-function buildListHandler(table: Table, targetName?: string, typeRegistry?: TypeRegistry): t.FunctionDeclaration {
+/**
+ * Build an auto-embed block that resolves the embedder and converts text
+ * values in the where clause to vector embeddings.
+ *
+ * Generates code equivalent to:
+ *   if (argv['auto-embed']) {
+ *     const embedder = resolveEmbedder();
+ *     if (!embedder) {
+ *       console.error('--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama');
+ *       process.exit(1);
+ *     }
+ *     await autoEmbedWhere(findManyArgs.where ?? {}, ['fieldA', 'fieldB'], embedder);
+ *   }
+ *
+ * @param whereExpr - The expression to access the where clause (e.g. findManyArgs.where, searchWhere)
+ * @param vectorFieldNames - Names of vector embedding fields detected at codegen time
+ * @param assignBack - If true, assigns the result back to findManyArgs.where
+ */
+function buildAutoEmbedBlock(
+  whereExpr: t.Expression,
+  vectorFieldNames: string[],
+  assignBack: boolean = false,
+): t.IfStatement {
+  const fieldNamesArray = t.arrayExpression(
+    vectorFieldNames.map((n) => t.stringLiteral(n)),
+  );
+
+  const embedderDecl = t.variableDeclaration('const', [
+    t.variableDeclarator(
+      t.identifier('embedder'),
+      t.callExpression(t.identifier('resolveEmbedder'), []),
+    ),
+  ]);
+
+  const noEmbedderCheck = t.ifStatement(
+    t.unaryExpression('!', t.identifier('embedder')),
+    t.blockStatement([
+      t.expressionStatement(
+        t.callExpression(
+          t.memberExpression(t.identifier('console'), t.identifier('error')),
+          [
+            t.stringLiteral(
+              '--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama (and optionally EMBEDDER_MODEL, EMBEDDER_BASE_URL).',
+            ),
+          ],
+        ),
+      ),
+      t.expressionStatement(
+        t.callExpression(
+          t.memberExpression(t.identifier('process'), t.identifier('exit')),
+          [t.numericLiteral(1)],
+        ),
+      ),
+    ]),
+  );
+
+  const autoEmbedCall = t.awaitExpression(
+    t.callExpression(t.identifier('autoEmbedWhere'), [
+      t.logicalExpression(
+        '??',
+        whereExpr,
+        t.objectExpression([]),
+      ),
+      fieldNamesArray,
+      t.identifier('embedder'),
+    ]),
+  );
+
+  const bodyStatements: t.Statement[] = [embedderDecl, noEmbedderCheck];
+
+  if (assignBack) {
+    // findManyArgs.where = await autoEmbedWhere(findManyArgs.where ?? {}, [...], embedder);
+    bodyStatements.push(
+      t.expressionStatement(
+        t.assignmentExpression(
+          '=',
+          t.memberExpression(t.identifier('findManyArgs'), t.identifier('where')),
+          autoEmbedCall,
+        ),
+      ),
+    );
+  } else {
+    // await autoEmbedWhere(searchWhere, [...], embedder);
+    bodyStatements.push(t.expressionStatement(autoEmbedCall));
+  }
+
+  return t.ifStatement(
+    t.memberExpression(
+      t.identifier('argv'),
+      t.stringLiteral('auto-embed'),
+      true,
+    ),
+    t.blockStatement(bodyStatements),
+  );
+}
+
+function buildListHandler(table: Table, vectorFieldNames: string[], targetName?: string, typeRegistry?: TypeRegistry): t.FunctionDeclaration {
   const { singularName } = getTableNames(table);
   const defaultSelectObj = buildSelectObject(table, typeRegistry);
 
@@ -338,6 +434,17 @@ function buildListHandler(table: Table, targetName?: string, typeRegistry?: Type
     ]),
   );
 
+  // Auto-embed vector fields in the where clause when --auto-embed is passed
+  if (vectorFieldNames.length > 0) {
+    tryBody.push(
+      buildAutoEmbedBlock(
+        t.memberExpression(t.identifier('findManyArgs'), t.identifier('where')),
+        vectorFieldNames,
+        true,
+      ),
+    );
+  }
+
   tryBody.push(buildGetClientStatement(targetName));
 
   // const result = await client.<singular>.findMany(findManyArgs).execute();
@@ -479,6 +586,7 @@ function buildFindFirstHandler(table: Table, targetName?: string, typeRegistry?:
 function buildSearchHandler(
   table: Table,
   specialGroups: SpecialFieldGroup[],
+  vectorFieldNames: string[],
   targetName?: string,
   typeRegistry?: TypeRegistry,
 ): t.FunctionDeclaration {
@@ -543,7 +651,7 @@ function buildSearchHandler(
   );
 
   // Build the where clause properties from detected search fields
-  // e.g. { tsvContent: { query }, bm25Body: { query }, trgmTitle: { value: query, threshold: 0.3 }, vectorEmbedding: { value: query } }
+  // e.g. { tsvContent: { query }, bm25Body: { query }, trgmTitle: { value: query, threshold: 0.3 }, vectorEmbedding: { vector: query } }
   const whereProps: t.ObjectProperty[] = [];
   for (const group of specialGroups) {
     for (const field of group.fields) {
@@ -585,12 +693,13 @@ function buildSearchHandler(
           ),
         );
       } else if (group.category === 'embedding') {
-        // Vector embedding field: { value: query }
+        // Vector embedding field: { vector: query }
+        // When --auto-embed is used, autoEmbedWhere will convert the text to a vector
         whereProps.push(
           t.objectProperty(
             t.identifier(field.name),
             t.objectExpression([
-              t.objectProperty(t.identifier('value'), t.identifier('query')),
+              t.objectProperty(t.identifier('vector'), t.identifier('query')),
             ]),
           ),
         );
@@ -608,6 +717,17 @@ function buildSearchHandler(
     ]),
   );
 
+  // Auto-embed vector fields in the where clause when --auto-embed is passed
+  if (vectorFieldNames.length > 0) {
+    tryBody.push(
+      buildAutoEmbedBlock(
+        t.identifier('searchWhere'),
+        vectorFieldNames,
+        false,
+      ),
+    );
+  }
+
   // const defaultSelect = { ... };
   tryBody.push(
     t.variableDeclaration('const', [
@@ -1122,6 +1242,25 @@ export function generateTableCommand(table: Table, options?: TableCommandOptions
     (g) => g.category === 'search' || g.category === 'embedding',
   );
 
+  // Collect vector embedding field names for --auto-embed support
+  const vectorFieldNames: string[] = [];
+  for (const group of specialGroups) {
+    if (group.category === 'embedding') {
+      for (const field of group.fields) {
+        vectorFieldNames.push(field.name);
+      }
+    }
+  }
+  const hasEmbeddings = vectorFieldNames.length > 0;
+
+  // Import embedder functions when table has vector embedding fields
+  if (hasEmbeddings) {
+    const embedderPath = options?.targetName ? '../../embedder' : '../embedder';
+    statements.push(
+      createImportDeclaration(embedderPath, ['resolveEmbedder', 'autoEmbedWhere']),
+    );
+  }
+
   const subcommands: string[] = ['list', 'find-first'];
   if (hasSearchFields) subcommands.push('search');
   if (hasGet) subcommands.push('get');
@@ -1169,6 +1308,20 @@ export function generateTableCommand(table: Table, options?: TableCommandOptions
       '  --offset <n>          Number of records to skip',
       '  --fields <fields>     Comma-separated list of fields to return',
       '  --orderBy <values>    Comma-separated list of ordering values',
+    );
+    if (hasEmbeddings) {
+      usageLines.push(
+        '  --auto-embed          Convert text queries to vectors via configured embedder',
+      );
+    }
+    usageLines.push('');
+  }
+  if (hasEmbeddings) {
+    usageLines.push(
+      'Embedding Options (for --auto-embed):',
+      '  Set EMBEDDER_PROVIDER=ollama to enable text-to-vector embedding.',
+      '  Optional: EMBEDDER_MODEL (default: nomic-embed-text)',
+      '  Optional: EMBEDDER_BASE_URL (default: http://localhost:11434)',
       '',
     );
   }
@@ -1339,9 +1492,9 @@ export function generateTableCommand(table: Table, options?: TableCommandOptions
 
   const tn = options?.targetName;
   const ormTypes = { createInputTypeName, patchTypeName, innerFieldName };
-  statements.push(buildListHandler(table, tn, options?.typeRegistry));
+  statements.push(buildListHandler(table, vectorFieldNames, tn, options?.typeRegistry));
   statements.push(buildFindFirstHandler(table, tn, options?.typeRegistry));
-  if (hasSearchFields) statements.push(buildSearchHandler(table, specialGroups, tn, options?.typeRegistry));
+  if (hasSearchFields) statements.push(buildSearchHandler(table, specialGroups, vectorFieldNames, tn, options?.typeRegistry));
   if (hasGet) statements.push(buildGetHandler(table, tn, options?.typeRegistry));
   statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry, ormTypes));
   if (hasUpdate) statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry, ormTypes));

graphql/codegen/src/core/codegen/cli/utils-generator.ts

@@ -94,3 +94,20 @@ export function generateEntryPointFile(): GeneratedFile {
     ),
   };
 }
+
+/**
+ * Generate an embedder.ts file with pluggable text-to-vector embedding.
+ *
+ * Provides a runtime embedder registry using @agentic-kit/ollama so that
+ * CLI search and list commands can convert text queries into vector arrays
+ * for pgvector similarity search when --auto-embed is passed.
+ */
+export function generateEmbedderFile(): GeneratedFile {
+  return {
+    fileName: 'embedder.ts',
+    content: readTemplateFile(
+      'embedder.ts',
+      'CLI embedder — pluggable text-to-vector embedding for search commands',
+    ),
+  };
+}

graphql/codegen/src/core/codegen/docs-utils.ts

@@ -359,15 +359,23 @@ export function buildSearchExamples(
         scoreFields.push(field.name);
       }
 
-      // pgvector embedding — uses column name, note about CLI limitation
+      // pgvector embedding — uses column name, with --auto-embed for text-to-vector
       if (group.category === 'embedding') {
         examples.push({
-          description: `Vector similarity search via \`${field.name}\` (requires JSON array)`,
+          description: `Vector similarity search via \`${field.name}\` (manual vector)`,
           code: [
-            `# Note: vector arrays must be passed as JSON strings via dot-notation`,
+            `# Pass a pre-computed vector array via dot-notation`,
             `${toolName} ${cmd} list --where.${field.name}.vector '[0.1,0.2,0.3]' --where.${field.name}.distance 1.0 --fields title,${field.name}VectorDistance`,
           ],
         });
+        examples.push({
+          description: `Vector semantic search via \`${field.name}\` with --auto-embed`,
+          code: [
+            `# --auto-embed converts text to vectors using the configured embedder (e.g. Ollama nomic-embed-text)`,
+            `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} search "semantic query" --auto-embed --fields title,${field.name}VectorDistance`,
+            `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} list --where.${field.name}.vector "semantic query" --auto-embed --fields title,${field.name}VectorDistance`,
+          ],
+        });
       }
 
       // searchScore — composite blend field, useful for ordering