Skip to content

feat(codegen): generate embedder config reference for CLI docs #940

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pyramation merged 1 commit into from
Mar 31, 2026
Merged

feat(codegen): generate embedder config reference for CLI docs #940

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 120 additions & 0 deletions graphql/codegen/src/core/codegen/cli/docs-generator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,64 @@ export function generateSkills(
}),
});

// Embedder reference (generated once when any table has Vector fields)
const hasEmbeddings = tables.some((t) =>
categorizeSpecialFields(t, registry).some((g) => g.category === 'embedding'),
);
if (hasEmbeddings) {
referenceNames.push('embedder');
files.push({
fileName: `${skillName}/references/embedder.md`,
content: buildSkillReference({
title: 'Embedder Configuration',
description:
`Configure text-to-vector embedding for \`--auto-embed\` support in ${toolName}.\n\n` +
'When an embedder is configured, you can pass plain text to vector fields and ' +
'the CLI will automatically convert it to an embedding vector.\n\n' +
'**Supported providers:** ollama, openai\n\n' +
'**Configuration methods:** appstash config (persisted per-context) or environment variables',
usage: [
`# Configure via appstash config (persisted per-context)`,
`${toolName} config set embedder.provider <provider>`,
`${toolName} config set embedder.model <model>`,
`${toolName} config set embedder.baseUrl <url>`,
'',
`# Or configure via environment variables`,
`EMBEDDER_PROVIDER=<provider> EMBEDDER_MODEL=<model> EMBEDDER_BASE_URL=<url> ${toolName} <command>`,
],
examples: [
{
description: 'Ollama with nomic-embed-text (open-source, local)',
code: [
`# Start Ollama locally and pull the model`,
`ollama pull nomic-embed-text`,
'',
`# Register the embedder`,
`${toolName} config set embedder.provider ollama`,
`${toolName} config set embedder.model nomic-embed-text`,
`${toolName} config set embedder.baseUrl http://localhost:11434`,
'',
`# Now use --auto-embed with any vector field`,
`${toolName} ${toKebabCase(getTableNames(tables[0]).singularName)} search "my query" --auto-embed`,
],
},
{
description: 'OpenAI with an API key',
code: [
`# Register the embedder`,
`${toolName} config set embedder.provider openai`,
`${toolName} config set embedder.model text-embedding-3-small`,
`${toolName} config set embedder.apiKey sk-proj-...your-api-key`,
'',
`# Or use environment variables`,
`EMBEDDER_PROVIDER=openai EMBEDDER_MODEL=text-embedding-3-small EMBEDDER_API_KEY=sk-proj-...your-api-key ${toolName} ${toKebabCase(getTableNames(tables[0]).singularName)} search "my query" --auto-embed`,
],
},
],
}),
});
}

// Table references
for (const table of tables) {
const { singularName } = getTableNames(table);
Expand Down Expand Up @@ -989,6 +1047,68 @@ export function generateMultiTargetSkills(
}),
});

// Embedder reference (generated once when any target has tables with Vector fields)
const allTargetTables = targets.flatMap((t) => t.tables);
const hasEmbeddings = allTargetTables.some((t) =>
categorizeSpecialFields(t, registry).some((g) => g.category === 'embedding'),
);
if (hasEmbeddings) {
const firstTableName = allTargetTables.length > 0
? toKebabCase(getTableNames(allTargetTables[0]).singularName)
: 'model';
commonReferenceNames.push('embedder');
files.push({
fileName: `${commonSkillName}/references/embedder.md`,
content: buildSkillReference({
title: 'Embedder Configuration',
description:
`Configure text-to-vector embedding for \`--auto-embed\` support in ${toolName}.\n\n` +
'When an embedder is configured, you can pass plain text to vector fields and ' +
'the CLI will automatically convert it to an embedding vector.\n\n' +
'**Supported providers:** ollama, openai\n\n' +
'**Configuration methods:** appstash config (persisted per-context) or environment variables',
usage: [
`# Configure via appstash config (persisted per-context)`,
`${toolName} ${builtinNames.config} set embedder.provider <provider>`,
`${toolName} ${builtinNames.config} set embedder.model <model>`,
`${toolName} ${builtinNames.config} set embedder.baseUrl <url>`,
'',
`# Or configure via environment variables`,
`EMBEDDER_PROVIDER=<provider> EMBEDDER_MODEL=<model> EMBEDDER_BASE_URL=<url> ${toolName} <command>`,
],
examples: [
{
description: 'Ollama with nomic-embed-text (open-source, local)',
code: [
`# Start Ollama locally and pull the model`,
`ollama pull nomic-embed-text`,
'',
`# Register the embedder`,
`${toolName} ${builtinNames.config} set embedder.provider ollama`,
`${toolName} ${builtinNames.config} set embedder.model nomic-embed-text`,
`${toolName} ${builtinNames.config} set embedder.baseUrl http://localhost:11434`,
'',
`# Now use --auto-embed with any vector field`,
`${toolName} ${targets[0]?.name ? `${targets[0].name}:` : ''}${firstTableName} search "my query" --auto-embed`,
],
},
{
description: 'OpenAI with an API key',
code: [
`# Register the embedder`,
`${toolName} ${builtinNames.config} set embedder.provider openai`,
`${toolName} ${builtinNames.config} set embedder.model text-embedding-3-small`,
`${toolName} ${builtinNames.config} set embedder.apiKey sk-proj-...your-api-key`,
'',
`# Or use environment variables`,
`EMBEDDER_PROVIDER=openai EMBEDDER_MODEL=text-embedding-3-small EMBEDDER_API_KEY=sk-proj-...your-api-key ${toolName} ${targets[0]?.name ? `${targets[0].name}:` : ''}${firstTableName} search "my query" --auto-embed`,
],
},
],
}),
});
}

// Common SKILL.md
files.push({
fileName: `${commonSkillName}/SKILL.md`,
Expand Down
Loading