@gmickel/gno 0.22.6 → 0.25.0

package/src/cli/program.ts

@@ -14,6 +14,7 @@ import {
   PRODUCT_NAME,
   VERSION,
 } from "../app/constants";
+import { resolveDepthPolicy } from "../core/depth-policy";
 import { parseAndValidateTagFilter } from "../core/tags";
 import { setColorsEnabled } from "./colors";
 import {
@@ -455,7 +456,10 @@ function wireSearchCommands(program: Command): void {
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--fast", "skip expansion and reranking (fastest, ~0.7s)")
-    .option("--thorough", "enable query expansion (slower, ~5-8s)")
+    .option(
+      "--thorough",
+      "use expansion with a wider rerank pool (slowest, best recall)"
+    )
     .option("--no-expand", "disable query expansion")
     .option("--no-rerank", "disable reranking")
     .option(
@@ -474,6 +478,7 @@ function wireSearchCommands(program: Command): void {
     .action(async (queryText: string, cmdOpts: Record<string, unknown>) => {
       const format = getFormat(cmdOpts);
       assertFormatSupported(CMD.query, format);
+      const globals = getGlobals();
 
       // Validate empty query
       if (!queryText.trim()) {
@@ -497,6 +502,21 @@ function wireSearchCommands(program: Command): void {
         queryModes = parsed.value;
       }
 
+      const { normalizeStructuredQueryInput } =
+        await import("../core/structured-query");
+      const normalizedInput = normalizeStructuredQueryInput(
+        queryText,
+        queryModes ?? []
+      );
+      if (!normalizedInput.ok) {
+        throw new CliError("VALIDATION", normalizedInput.error.message);
+      }
+      queryText = normalizedInput.value.query;
+      queryModes =
+        normalizedInput.value.queryModes.length > 0
+          ? normalizedInput.value.queryModes
+          : undefined;
+
       // Parse and validate tag filters
       let tagsAll: string[] | undefined;
       let tagsAny: string[] | undefined;
@@ -517,35 +537,26 @@ function wireSearchCommands(program: Command): void {
       const limit = cmdOpts.limit
         ? parsePositiveInt("limit", cmdOpts.limit)
         : getDefaultLimit(format);
+      const { loadConfig } = await import("../config");
+      const { getActivePreset } = await import("../llm/registry");
+      const configResult = await loadConfig(globals.config);
+      const activePresetId = configResult.ok
+        ? getActivePreset(configResult.value).id
+        : "slim";
       const candidateLimit = cmdOpts.candidateLimit
         ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
         : undefined;
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
 
-      // Determine expansion/rerank settings based on flags
-      // Priority: --fast > --thorough > --no-expand/--no-rerank > default
-      // Default: skip expansion (balanced mode ~2-3s)
-      let noExpand = true; // Default: skip expansion
-      let noRerank = false; // Default: with reranking
-
-      if (cmdOpts.fast) {
-        // --fast: skip both (~0.7s)
-        noExpand = true;
-        noRerank = true;
-      } else if (cmdOpts.thorough) {
-        // --thorough: full pipeline (~5-8s)
-        noExpand = false;
-        noRerank = false;
-      } else {
-        // Check individual flags (override defaults)
-        if (cmdOpts.expand === false) {
-          noExpand = true;
-        }
-        if (cmdOpts.rerank === false) {
-          noRerank = true;
-        }
-      }
+      const depthPolicy = resolveDepthPolicy({
+        presetId: activePresetId,
+        fast: Boolean(cmdOpts.fast),
+        thorough: Boolean(cmdOpts.thorough),
+        expand: cmdOpts.expand === false ? false : undefined,
+        rerank: cmdOpts.rerank === false ? false : undefined,
+        candidateLimit,
+      });
 
       const { query, formatQuery } = await import("./commands/query");
       const result = await query(queryText, {
@@ -563,9 +574,9 @@ function wireSearchCommands(program: Command): void {
         tagsAny,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
-        noExpand,
-        noRerank,
-        candidateLimit,
+        noExpand: depthPolicy.noExpand,
+        noRerank: depthPolicy.noRerank,
+        candidateLimit: depthPolicy.candidateLimit,
         queryModes,
         explain: Boolean(cmdOpts.explain),
         json: format === "json",
@@ -615,7 +626,10 @@ function wireSearchCommands(program: Command): void {
       []
     )
     .option("--fast", "skip expansion and reranking (fastest)")
-    .option("--thorough", "enable query expansion (slower)")
+    .option(
+      "--thorough",
+      "use expansion with a wider rerank pool (slowest, best recall)"
+    )
     .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
     .option("--answer", "generate short grounded answer")
     .option("--no-answer", "force retrieval-only output")
@@ -626,6 +640,7 @@ function wireSearchCommands(program: Command): void {
     .action(async (queryText: string, cmdOpts: Record<string, unknown>) => {
       const format = getFormat(cmdOpts);
       assertFormatSupported(CMD.ask, format);
+      const globals = getGlobals();
 
       // Validate empty query
       if (!queryText.trim()) {
@@ -635,6 +650,12 @@ function wireSearchCommands(program: Command): void {
       const limit = cmdOpts.limit
         ? parsePositiveInt("limit", cmdOpts.limit)
         : getDefaultLimit(format);
+      const { loadConfig } = await import("../config");
+      const { getActivePreset } = await import("../llm/registry");
+      const configResult = await loadConfig(globals.config);
+      const activePresetId = configResult.ok
+        ? getActivePreset(configResult.value).id
+        : "slim";
       const candidateLimit = cmdOpts.candidateLimit
         ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
         : undefined;
@@ -656,18 +677,28 @@ function wireSearchCommands(program: Command): void {
         queryModes = parsed.value;
       }
 
-      // Determine expansion/rerank settings based on flags
-      // Default: skip expansion (balanced mode)
-      let noExpand = true;
-      let noRerank = false;
-
-      if (cmdOpts.fast) {
-        noExpand = true;
-        noRerank = true;
-      } else if (cmdOpts.thorough) {
-        noExpand = false;
-        noRerank = false;
+      const { normalizeStructuredQueryInput } =
+        await import("../core/structured-query");
+      const normalizedInput = normalizeStructuredQueryInput(
+        queryText,
+        queryModes ?? []
+      );
+      if (!normalizedInput.ok) {
+        throw new CliError("VALIDATION", normalizedInput.error.message);
       }
+      queryText = normalizedInput.value.query;
+      queryModes =
+        normalizedInput.value.queryModes.length > 0
+          ? normalizedInput.value.queryModes
+          : undefined;
+
+      const depthPolicy = resolveDepthPolicy({
+        presetId: activePresetId,
+        fast: Boolean(cmdOpts.fast),
+        thorough: Boolean(cmdOpts.thorough),
+        candidateLimit,
+        hasStructuredModes: Boolean(queryModes?.length),
+      });
 
       const { ask, formatAsk } = await import("./commands/ask");
       const showSources = Boolean(cmdOpts.showSources);
@@ -682,9 +713,9 @@ function wireSearchCommands(program: Command): void {
         intent: cmdOpts.intent as string | undefined,
         exclude,
         queryModes,
-        noExpand,
-        noRerank,
-        candidateLimit,
+        noExpand: depthPolicy.noExpand,
+        noRerank: depthPolicy.noRerank,
+        candidateLimit: depthPolicy.candidateLimit,
         // Per spec: --answer defaults to false, --no-answer forces retrieval-only
         // Commander creates separate cmdOpts.noAnswer for --no-answer flag
         answer: Boolean(cmdOpts.answer),
@@ -1328,7 +1359,8 @@ function wireManagementCommands(program: Command): void {
     .option("--all", "download all configured models")
     .option("--embed", "download embedding model")
     .option("--rerank", "download reranker model")
-    .option("--gen", "download generation model")
+    .option("--expand", "download expansion model")
+    .option("--gen", "download answer generation model")
     .option("--force", "force re-download")
     .option("--no-progress", "disable download progress")
     .action(async (cmdOpts: Record<string, unknown>) => {
@@ -1347,6 +1379,7 @@ function wireManagementCommands(program: Command): void {
         all: Boolean(cmdOpts.all),
         embed: Boolean(cmdOpts.embed),
         rerank: Boolean(cmdOpts.rerank),
+        expand: Boolean(cmdOpts.expand),
         gen: Boolean(cmdOpts.gen),
         force: Boolean(cmdOpts.force),
         onProgress: showProgress ? createProgressRenderer() : undefined,

package/src/config/types.ts

@@ -166,7 +166,9 @@ export const ModelPresetSchema = z.object({
   embed: z.string().min(1),
   /** Reranker model URI */
   rerank: z.string().min(1),
-  /** Generation model URI */
+  /** Query expansion model URI (defaults to gen for older configs) */
+  expand: z.string().min(1).optional(),
+  /** Answer generation model URI */
   gen: z.string().min(1),
 });
 
@@ -180,6 +182,7 @@ export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
     embed: "hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf",
     rerank:
       "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf",
+    expand: "hf:unsloth/Qwen3-1.7B-GGUF/Qwen3-1.7B-Q4_K_M.gguf",
     gen: "hf:unsloth/Qwen3-1.7B-GGUF/Qwen3-1.7B-Q4_K_M.gguf",
   },
   {
@@ -188,6 +191,8 @@ export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
     embed: "hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf",
     rerank:
       "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf",
+    expand:
+      "hf:bartowski/Qwen2.5-3B-Instruct-GGUF/Qwen2.5-3B-Instruct-Q4_K_M.gguf",
     gen: "hf:bartowski/Qwen2.5-3B-Instruct-GGUF/Qwen2.5-3B-Instruct-Q4_K_M.gguf",
   },
   {
@@ -196,6 +201,8 @@ export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
     embed: "hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf",
     rerank:
       "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf",
+    expand:
+      "hf:unsloth/Qwen3-4B-Instruct-2507-GGUF/Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
     gen: "hf:unsloth/Qwen3-4B-Instruct-2507-GGUF/Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
   },
 ];

package/src/core/depth-policy.ts

@@ -0,0 +1,78 @@
+export type RetrievalDepth = "fast" | "balanced" | "thorough";
+
+export interface ResolveDepthPolicyInput {
+  presetId?: string;
+  fast?: boolean;
+  thorough?: boolean;
+  expand?: boolean;
+  rerank?: boolean;
+  candidateLimit?: number;
+  hasStructuredModes?: boolean;
+}
+
+export interface ResolvedDepthPolicy {
+  depth: RetrievalDepth;
+  noExpand: boolean;
+  noRerank: boolean;
+  candidateLimit?: number;
+  balancedExpansionEnabled: boolean;
+}
+
+export const DEFAULT_THOROUGH_CANDIDATE_LIMIT = 40;
+
+function normalizePresetId(presetId?: string): string {
+  return presetId?.trim().toLowerCase() || "slim";
+}
+
+export function balancedUsesExpansion(presetId?: string): boolean {
+  const normalized = normalizePresetId(presetId);
+  return normalized === "slim" || normalized === "slim-tuned";
+}
+
+export function resolveDepthPolicy(
+  input: ResolveDepthPolicyInput
+): ResolvedDepthPolicy {
+  const balancedExpansionEnabled = balancedUsesExpansion(input.presetId);
+  let depth: RetrievalDepth = "balanced";
+  let noExpand = !balancedExpansionEnabled;
+  let noRerank = false;
+  let candidateLimit = input.candidateLimit;
+
+  if (input.fast) {
+    depth = "fast";
+    noExpand = true;
+    noRerank = true;
+  } else if (input.thorough) {
+    depth = "thorough";
+    noExpand = false;
+    noRerank = false;
+    candidateLimit ??= DEFAULT_THOROUGH_CANDIDATE_LIMIT;
+  } else {
+    if (input.expand === true) {
+      noExpand = false;
+    }
+    if (input.expand === false) {
+      noExpand = true;
+    }
+    if (input.rerank === true) {
+      noRerank = false;
+    }
+    if (input.rerank === false) {
+      noRerank = true;
+    }
+  }
+
+  // Structured query modes supply explicit expansions and should not trigger
+  // an additional generated expansion step.
+  if (input.hasStructuredModes) {
+    noExpand = true;
+  }
+
+  return {
+    depth,
+    noExpand,
+    noRerank,
+    candidateLimit,
+    balancedExpansionEnabled,
+  };
+}

package/src/core/structured-query.ts

@@ -0,0 +1,198 @@
+/**
+ * Structured multi-line query document parsing.
+ *
+ * Pure parser used across CLI, API, MCP, SDK, and Web.
+ *
+ * @module src/core/structured-query
+ */
+
+import type { QueryModeInput } from "../pipeline/types";
+
+export interface StructuredQueryError {
+  line: number | null;
+  message: string;
+}
+
+export interface StructuredQueryNormalization {
+  query: string;
+  queryModes: QueryModeInput[];
+  usedStructuredQuerySyntax: boolean;
+  derivedQuery: boolean;
+}
+
+export type StructuredQueryResult =
+  | { ok: true; value: StructuredQueryNormalization }
+  | { ok: false; error: StructuredQueryError };
+
+const RECOGNIZED_MODE_PREFIXES = new Set(["term", "intent", "hyde"]);
+const ANY_PREFIX_PATTERN = /^\s*([a-z][a-z0-9_-]*)\s*:\s*(.*)$/i;
+const RECOGNIZED_PREFIX_PATTERN = /^\s*(term|intent|hyde)\s*:\s*(.*)$/i;
+
+function buildError(
+  message: string,
+  line: number | null
+): StructuredQueryResult {
+  return { ok: false, error: { message, line } };
+}
+
+function trimNonBlankLines(query: string): string[] {
+  return query.split(/\r?\n/).filter((line) => line.trim().length > 0);
+}
+
+/**
+ * Parse multi-line structured query syntax.
+ *
+ * Rules:
+ * - single-line queries remain unchanged
+ * - blank lines are ignored
+ * - recognized typed lines: term:, intent:, hyde:
+ * - if structured syntax is used, unknown prefix lines like foo:bar are rejected
+ * - untyped lines contribute to the base query text
+ * - if no untyped lines exist, base query is derived from term lines first, then intent lines
+ * - hyde-only documents are rejected
+ */
+export function normalizeStructuredQueryInput(
+  query: string,
+  explicitQueryModes: QueryModeInput[] = []
+): StructuredQueryResult {
+  if (!query.includes("\n")) {
+    return {
+      ok: true,
+      value: {
+        query,
+        queryModes: explicitQueryModes,
+        usedStructuredQuerySyntax: false,
+        derivedQuery: false,
+      },
+    };
+  }
+
+  const lines = trimNonBlankLines(query);
+  if (lines.length === 0) {
+    return {
+      ok: true,
+      value: {
+        query,
+        queryModes: explicitQueryModes,
+        usedStructuredQuerySyntax: false,
+        derivedQuery: false,
+      },
+    };
+  }
+
+  const hasRecognizedTypedLine = lines.some((line) => {
+    const match = line.match(RECOGNIZED_PREFIX_PATTERN);
+    return Boolean(match?.[1]);
+  });
+
+  if (!hasRecognizedTypedLine) {
+    return {
+      ok: true,
+      value: {
+        query,
+        queryModes: explicitQueryModes,
+        usedStructuredQuerySyntax: false,
+        derivedQuery: false,
+      },
+    };
+  }
+
+  const queryModes: QueryModeInput[] = [];
+  const bodyLines: string[] = [];
+  let hydeCount = 0;
+
+  for (const [index, line] of query.split(/\r?\n/).entries()) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    const recognized = trimmed.match(RECOGNIZED_PREFIX_PATTERN);
+    if (recognized) {
+      const mode = recognized[1]?.toLowerCase() as QueryModeInput["mode"];
+      const text = recognized[2]?.trim() ?? "";
+      if (text.length === 0) {
+        return buildError(
+          `Structured query line ${index + 1} must contain non-empty text after ${mode}:`,
+          index + 1
+        );
+      }
+      if (mode === "hyde") {
+        hydeCount += 1;
+        if (hydeCount > 1) {
+          return buildError(
+            "Only one hyde line is allowed in a structured query document.",
+            index + 1
+          );
+        }
+      }
+      queryModes.push({ mode, text });
+      continue;
+    }
+
+    const prefixed = trimmed.match(ANY_PREFIX_PATTERN);
+    if (prefixed?.[1]) {
+      const prefix = prefixed[1].toLowerCase();
+      if (!RECOGNIZED_MODE_PREFIXES.has(prefix)) {
+        return buildError(
+          `Unknown structured query line prefix "${prefix}:" on line ${index + 1}. Expected term:, intent:, or hyde:.`,
+          index + 1
+        );
+      }
+    }
+
+    bodyLines.push(trimmed);
+  }
+
+  const combinedQueryModes = [...queryModes, ...explicitQueryModes];
+  const totalHydeCount = combinedQueryModes.filter(
+    (entry) => entry.mode === "hyde"
+  ).length;
+  if (totalHydeCount > 1) {
+    return buildError(
+      "Only one hyde entry is allowed across structured query syntax and explicit query modes.",
+      null
+    );
+  }
+
+  let normalizedQuery = bodyLines.join(" ").trim();
+  let derivedQuery = false;
+
+  if (!normalizedQuery) {
+    const termQuery = queryModes
+      .filter((entry) => entry.mode === "term")
+      .map((entry) => entry.text)
+      .join(" ")
+      .trim();
+    const intentQuery = queryModes
+      .filter((entry) => entry.mode === "intent")
+      .map((entry) => entry.text)
+      .join(" ")
+      .trim();
+
+    normalizedQuery = termQuery || intentQuery;
+    derivedQuery = normalizedQuery.length > 0;
+  }
+
+  if (!normalizedQuery) {
+    return buildError(
+      "Structured query documents must include at least one plain query line, term line, or intent line. hyde-only documents are not allowed.",
+      null
+    );
+  }
+
+  return {
+    ok: true,
+    value: {
+      query: normalizedQuery,
+      queryModes: combinedQueryModes,
+      usedStructuredQuerySyntax: true,
+      derivedQuery,
+    },
+  };
+}
+
+export function hasStructuredQuerySyntax(query: string): boolean {
+  const result = normalizeStructuredQueryInput(query);
+  return result.ok && result.value.usedStructuredQuerySyntax;
+}

package/src/llm/errors.ts

@@ -121,7 +121,7 @@ export function modelNotFoundError(uri: string, details?: string): LlmError {
 
 export function modelNotCachedError(
   uri: string,
-  modelType: "embed" | "rerank" | "gen"
+  modelType: "embed" | "rerank" | "expand" | "gen"
 ): LlmError {
   return llmError("MODEL_NOT_CACHED", {
     message: `${modelType} model not cached`,

package/src/llm/nodeLlamaCpp/adapter.ts

@@ -19,7 +19,12 @@ import { ModelCache } from "../cache";
 import { HttpEmbedding, isHttpModelUri } from "../httpEmbedding";
 import { HttpGeneration, isHttpGenUri } from "../httpGeneration";
 import { HttpRerank, isHttpRerankUri } from "../httpRerank";
-import { getActivePreset, getModelConfig } from "../registry";
+import {
+  getActivePreset,
+  getAnswerModelUri,
+  getExpandModelUri,
+  getModelConfig,
+} from "../registry";
 import { NodeLlamaCppEmbedding } from "./embedding";
 import { NodeLlamaCppGeneration } from "./generation";
 import { getModelManager, type ModelManager } from "./lifecycle";
@@ -105,8 +110,7 @@ export class LlmAdapter {
     modelUri?: string,
     options?: CreatePortOptions
   ): Promise<LlmResult<GenerationPort>> {
-    const preset = getActivePreset(this.config);
-    const uri = modelUri ?? preset.gen;
+    const uri = getAnswerModelUri(this.config, modelUri);
     const policy = options?.policy ?? DEFAULT_POLICY;
 
     // Use HTTP generation for remote endpoints
@@ -132,6 +136,38 @@ export class LlmAdapter {
     };
   }
 
+  /**
+   * Create a generation port dedicated to query expansion.
+   * Uses preset.expand when configured, else falls back to preset.gen.
+   */
+  async createExpansionPort(
+    modelUri?: string,
+    options?: CreatePortOptions
+  ): Promise<LlmResult<GenerationPort>> {
+    const uri = getExpandModelUri(this.config, modelUri);
+    const policy = options?.policy ?? DEFAULT_POLICY;
+
+    if (isHttpGenUri(uri)) {
+      const httpGen = new HttpGeneration(uri);
+      return { ok: true, value: httpGen };
+    }
+
+    const resolved = await this.cache.ensureModel(
+      uri,
+      "expand",
+      policy,
+      options?.onProgress
+    );
+    if (!resolved.ok) {
+      return resolved;
+    }
+
+    return {
+      ok: true,
+      value: new NodeLlamaCppGeneration(this.manager, uri, resolved.value),
+    };
+  }
+
   /**
    * Create a rerank port.
    * Supports HTTP endpoints for remote reranking models.

package/src/llm/registry.ts

@@ -57,6 +57,24 @@ export function getActivePreset(config: Config): ModelPreset {
   return builtIn;
 }
 
+export function getExpandModelUri(config: Config, override?: string): string {
+  if (override) {
+    return override;
+  }
+
+  const preset = getActivePreset(config);
+  return preset.expand ?? preset.gen;
+}
+
+export function getAnswerModelUri(config: Config, override?: string): string {
+  if (override) {
+    return override;
+  }
+
+  const preset = getActivePreset(config);
+  return preset.gen;
+}
+
 /**
  * Resolve a model URI for a given type.
  * Uses override if provided, otherwise from active preset.
@@ -70,6 +88,9 @@ export function resolveModelUri(
     return override;
   }
   const preset = getActivePreset(config);
+  if (type === "expand") {
+    return preset.expand ?? preset.gen;
+  }
   return preset[type];
 }
 

package/src/llm/types.ts

@@ -19,7 +19,7 @@ export type LlmResult<T> =
 // Model Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type ModelType = "embed" | "rerank" | "gen";
+export type ModelType = "embed" | "rerank" | "expand" | "gen";
 
 /** Model URI format: hf:org/repo/file.gguf or file:/path */
 export type ModelUri = string;

package/src/mcp/tools/index.ts

@@ -149,8 +149,8 @@ export const queryInputSchema = z.object({
     .optional(),
   fast: z.boolean().default(false),
   thorough: z.boolean().default(false),
-  expand: z.boolean().default(false), // Default: skip expansion
-  rerank: z.boolean().default(true),
+  expand: z.boolean().optional(),
+  rerank: z.boolean().optional(),
   tagsAll: z.array(z.string()).optional(),
   tagsAny: z.array(z.string()).optional(),
 });