@gmickel/gno 0.22.6 → 0.25.0

package/README.md

@@ -24,6 +24,7 @@ GNO is a local knowledge engine that turns your documents into a searchable, con
 - [Agent Integration](#agent-integration)
 - [Web UI](#web-ui)
 - [REST API](#rest-api)
+- [SDK](#sdk)
 - [How It Works](#how-it-works)
 - [Features](#features)
 - [Local Models](#local-models)
@@ -33,7 +34,20 @@ GNO is a local knowledge engine that turns your documents into a searchable, con
 
 ---
 
-## What's New in v0.22
+## What's New in v0.24
+
+- **Structured Query Documents**: first-class multi-line query syntax using `term:`, `intent:`, and `hyde:`
+- **Cross-Surface Rollout**: works across CLI, API, MCP, SDK, and Web Search/Ask
+- **Portable Retrieval Prompts**: save/share advanced retrieval intent as one text payload instead of repeated flags or JSON arrays
+
+### v0.23
+
+- **SDK / Library Mode**: package-root importable SDK with `createGnoClient(...)` for direct retrieval, document access, and indexing flows
+- **Inline Config Support**: embed GNO in another app without writing YAML config files
+- **Programmatic Indexing**: call `update`, `embed`, and `index` directly from Bun/TypeScript
+- **Docs & Website**: dedicated SDK guide, feature page, homepage section, and architecture docs
+
+### v0.22
 
 - **Promoted Slim Retrieval Model**: published `slim-retrieval-v1` on Hugging Face for direct `hf:` installation in GNO
 - **Fine-Tuning Workflow**: local MLX LoRA training, portable GGUF export, automatic checkpoint selection, promotion bundles, and repeatable benchmark comparisons
@@ -47,16 +61,18 @@ models:
   activePreset: slim-tuned
   presets:
     - id: slim-tuned
-      name: GNO Slim Retrieval v1
+      name: GNO Slim Tuned
       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
-      gen: hf:guiltylemon/gno-expansion-slim-retrieval-v1/gno-expansion-auto-entity-lock-default-mix-lr95-f16.gguf
+      expand: hf:guiltylemon/gno-expansion-slim-retrieval-v1/gno-expansion-auto-entity-lock-default-mix-lr95-f16.gguf
+      gen: hf:unsloth/Qwen3-4B-Instruct-2507-GGUF/Qwen3-4B-Instruct-2507-Q4_K_M.gguf
 ```
 
 Then:
 
 ```bash
 gno models use slim-tuned
+gno models pull --expand
 gno models pull --gen
 gno query "ECONNREFUSED 127.0.0.1:5432" --thorough
 ```
@@ -187,6 +203,58 @@ gno skill install --target all       # Both Claude + Codex
 
 ---
 
+## SDK
+
+Embed GNO directly in another Bun or TypeScript app. No CLI subprocesses. No local server required.
+
+```ts
+import { createDefaultConfig, createGnoClient } from "@gmickel/gno";
+
+const config = createDefaultConfig();
+config.collections = [
+  {
+    name: "notes",
+    path: "/Users/me/notes",
+    pattern: "**/*",
+    include: [],
+    exclude: [],
+  },
+];
+
+const client = await createGnoClient({
+  config,
+  dbPath: "/tmp/gno-sdk.sqlite",
+});
+
+await client.index({ noEmbed: true });
+
+const results = await client.query("JWT token flow", {
+  noExpand: true,
+  noRerank: true,
+});
+
+console.log(results.results[0]?.uri);
+await client.close();
+```
+
+Core SDK surface:
+
+- `createGnoClient({ config | configPath, dbPath? })`
+- `search`, `vsearch`, `query`, `ask`
+- `get`, `multiGet`, `list`, `status`
+- `update`, `embed`, `index`
+- `close`
+
+Install in an app:
+
+```bash
+bun add @gmickel/gno
+```
+
+Full guide: [SDK docs](https://gno.sh/docs/SDK/)
+
+---
+
 ## Search Modes
 
 | Command            | Mode                | Best For                                  |
@@ -228,11 +296,15 @@ gno query "auth flow" \
   --query-mode intent:"how refresh token rotation works" \
   --query-mode hyde:"Refresh tokens rotate on each use and previous tokens are revoked." \
   --explain
+
+# Multi-line structured query document
+gno query $'auth flow\nterm: "refresh token" -oauth1\nintent: how refresh token rotation works\nhyde: Refresh tokens rotate on each use and previous tokens are revoked.' --fast
 ```
 
 - Modes: `term` (BM25-focused), `intent` (semantic-focused), `hyde` (single hypothetical passage)
 - Explain includes stage timings, fallback/cache counters, and per-result score components
 - `gno ask --json` includes `meta.answerContext` for adaptive source selection traces
+- Search and Ask web text boxes also accept multi-line structured query documents with `Shift+Enter`
 
 ---
 
@@ -509,6 +581,7 @@ models:
       name: Remote GPU Server
       embed: "http://192.168.1.100:8081/v1/embeddings#bge-m3"
       rerank: "http://192.168.1.100:8082/v1/completions#reranker"
+      expand: "http://192.168.1.100:8083/v1/chat/completions#gno-expand"
       gen: "http://192.168.1.100:8083/v1/chat/completions#qwen3-4b"
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.22.6",
+  "version": "0.25.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -33,7 +33,19 @@
     "vendor"
   ],
   "type": "module",
-  "module": "src/index.ts",
+  "main": "src/sdk/index.ts",
+  "module": "src/sdk/index.ts",
+  "types": "src/sdk/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/sdk/index.ts",
+      "default": "./src/sdk/index.ts"
+    },
+    "./cli": {
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/cli/AGENTS.md

@@ -81,7 +81,8 @@ interface CliContext {
   store: SqliteAdapter;
   config: Config;
   embedPort?: EmbeddingPort;
-  genPort?: GenerationPort;
+  expandPort?: GenerationPort;
+  answerPort?: GenerationPort;
   rerankPort?: RerankPort;
 }
 ```

package/src/cli/CLAUDE.md

@@ -81,7 +81,8 @@ interface CliContext {
   store: SqliteAdapter;
   config: Config;
   embedPort?: EmbeddingPort;
-  genPort?: GenerationPort;
+  expandPort?: GenerationPort;
+  answerPort?: GenerationPort;
   rerankPort?: RerankPort;
 }
 ```

package/src/cli/commands/ask.ts

@@ -40,7 +40,9 @@ export type AskCommandOptions = AskOptions & {
   configPath?: string;
   /** Override embedding model */
   embedModel?: string;
-  /** Override generation model */
+  /** Override expansion model */
+  expandModel?: string;
+  /** Override answer generation model */
   genModel?: string;
   /** Override rerank model */
   rerankModel?: string;
@@ -82,7 +84,8 @@ export async function ask(
   const { store, config } = initResult;
 
   let embedPort: EmbeddingPort | null = null;
-  let genPort: GenerationPort | null = null;
+  let expandPort: GenerationPort | null = null;
+  let answerPort: GenerationPort | null = null;
   let rerankPort: RerankPort | null = null;
 
   try {
@@ -113,10 +116,23 @@ export async function ask(
       embedPort = embedResult.value;
     }
 
-    // Create generation port (for expansion and/or answer)
-    // Need genPort if: expansion enabled (!noExpand) OR answer requested
-    const needsGen = !options.noExpand || options.answer;
-    if (needsGen) {
+    // Create expansion port when expansion is enabled.
+    if (!options.noExpand && !options.queryModes?.length) {
+      const expandUri =
+        options.expandModel ?? options.genModel ?? preset.expand;
+      const genResult = await llm.createExpansionPort(expandUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress("expand", progress)
+          : undefined,
+      });
+      if (genResult.ok) {
+        expandPort = genResult.value;
+      }
+    }
+
+    // Create answer generation port when answers are requested.
+    if (options.answer) {
       const genUri = options.genModel ?? preset.gen;
       const genResult = await llm.createGenerationPort(genUri, {
         policy,
@@ -125,7 +141,7 @@ export async function ask(
           : undefined,
       });
       if (genResult.ok) {
-        genPort = genResult.value;
+        answerPort = genResult.value;
       }
     }
 
@@ -170,7 +186,7 @@ export async function ask(
       config,
       vectorIndex,
       embedPort,
-      genPort,
+      expandPort,
       rerankPort,
     };
 
@@ -178,7 +194,7 @@ export async function ask(
     const answerRequested = options.answer && !options.noAnswer;
 
     // Fail early if --answer is requested but no generation model available
-    if (answerRequested && genPort === null) {
+    if (answerRequested && answerPort === null) {
       return {
         success: false,
         error:
@@ -223,12 +239,12 @@ export async function ask(
     // 2. --no-answer was not set
     // 3. We have results to ground on (no point generating from nothing)
     const shouldGenerateAnswer =
-      answerRequested && genPort !== null && results.length > 0;
+      answerRequested && answerPort !== null && results.length > 0;
 
-    if (shouldGenerateAnswer && genPort) {
+    if (shouldGenerateAnswer && answerPort) {
       const maxTokens = options.maxAnswerTokens ?? 512;
       const rawResult = await generateGroundedAnswer(
-        { genPort, store },
+        { genPort: answerPort, store },
         query,
         results,
         maxTokens
@@ -277,8 +293,11 @@ export async function ask(
     if (embedPort) {
       await embedPort.dispose();
     }
-    if (genPort) {
-      await genPort.dispose();
+    if (expandPort) {
+      await expandPort.dispose();
+    }
+    if (answerPort) {
+      await answerPort.dispose();
     }
     if (rerankPort) {
       await rerankPort.dispose();

package/src/cli/commands/models/clear.ts

@@ -21,6 +21,8 @@ export interface ModelsClearOptions {
   embed?: boolean;
   /** Clear reranker model */
   rerank?: boolean;
+  /** Clear expansion model */
+  expand?: boolean;
   /** Clear generation model */
   gen?: boolean;
   /** Skip confirmation */
@@ -50,7 +52,7 @@ export async function modelsClear(
 
   if (options.all) {
     types = undefined; // Clear all
-  } else if (options.embed || options.rerank || options.gen) {
+  } else if (options.embed || options.rerank || options.expand || options.gen) {
     types = [];
     if (options.embed) {
       types.push("embed");
@@ -58,6 +60,9 @@ export async function modelsClear(
     if (options.rerank) {
       types.push("rerank");
     }
+    if (options.expand) {
+      types.push("expand");
+    }
     if (options.gen) {
       types.push("gen");
     }
@@ -71,7 +76,7 @@ export async function modelsClear(
   const sizeAfter = await cache.totalSize();
 
   return {
-    cleared: types ?? ["embed", "rerank", "gen"],
+    cleared: types ?? ["embed", "rerank", "expand", "gen"],
     sizeBefore,
     sizeAfter,
   };
@@ -96,8 +101,10 @@ function formatBytes(bytes: number): string {
  */
 export function formatModelsClear(result: ModelsClearResult): string {
   const lines: string[] = [];
+  const label = (type: ModelType) =>
+    type === "gen" ? "answer" : type === "expand" ? "expand" : type;
 
-  lines.push(`Cleared: ${result.cleared.join(", ")}`);
+  lines.push(`Cleared: ${result.cleared.map(label).join(", ")}`);
   lines.push(`Freed: ${formatBytes(result.sizeBefore - result.sizeAfter)}`);
 
   return lines.join("\n");

package/src/cli/commands/models/list.ts

@@ -36,6 +36,7 @@ export interface ModelsListResult {
   presets: PresetInfo[];
   embed: ModelStatus;
   rerank: ModelStatus;
+  expand: ModelStatus;
   gen: ModelStatus;
   cacheDir: string;
   totalSize: number;
@@ -84,9 +85,10 @@ export async function modelsList(
   const preset = getActivePreset(config);
   const cache = new ModelCache(getModelsCachePath());
 
-  const [embed, rerank, gen] = await Promise.all([
+  const [embed, rerank, expand, gen] = await Promise.all([
     getModelStatus(cache, preset.embed),
     getModelStatus(cache, preset.rerank),
+    getModelStatus(cache, preset.expand ?? preset.gen),
     getModelStatus(cache, preset.gen),
   ]);
 
@@ -99,6 +101,7 @@ export async function modelsList(
     })),
     embed,
     rerank,
+    expand,
     gen,
     cacheDir: cache.dir,
     totalSize: await cache.totalSize(),
@@ -147,7 +150,11 @@ function formatTerminal(result: ModelsListResult): string {
       (result.rerank.size ? ` (${formatBytes(result.rerank.size)})` : "")
   );
   lines.push(
-    `  gen:    ${statusIcon(result.gen)} ${result.gen.uri}` +
+    `  expand: ${statusIcon(result.expand)} ${result.expand.uri}` +
+      (result.expand.size ? ` (${formatBytes(result.expand.size)})` : "")
+  );
+  lines.push(
+    `  answer: ${statusIcon(result.gen)} ${result.gen.uri}` +
       (result.gen.size ? ` (${formatBytes(result.gen.size)})` : "")
   );
 
@@ -156,7 +163,10 @@ function formatTerminal(result: ModelsListResult): string {
   lines.push(`Total size: ${formatBytes(result.totalSize)}`);
 
   const allCached =
-    result.embed.cached && result.rerank.cached && result.gen.cached;
+    result.embed.cached &&
+    result.rerank.cached &&
+    result.expand.cached &&
+    result.gen.cached;
   if (!allCached) {
     lines.push("");
     lines.push("Run: gno models pull --all");
@@ -186,7 +196,10 @@ function formatMarkdown(result: ModelsListResult): string {
     `| rerank | ${result.rerank.uri} | ${status(result.rerank)} | ${size(result.rerank)} |`
   );
   lines.push(
-    `| gen | ${result.gen.uri} | ${status(result.gen)} | ${size(result.gen)} |`
+    `| expand | ${result.expand.uri} | ${status(result.expand)} | ${size(result.expand)} |`
+  );
+  lines.push(
+    `| answer | ${result.gen.uri} | ${status(result.gen)} | ${size(result.gen)} |`
   );
 
   lines.push("");

package/src/cli/commands/models/pull.ts

@@ -27,6 +27,8 @@ export interface ModelsPullOptions {
   embed?: boolean;
   /** Pull reranker model */
   rerank?: boolean;
+  /** Pull expansion model */
+  expand?: boolean;
   /** Pull generation model */
   gen?: boolean;
   /** Force re-download */
@@ -59,9 +61,9 @@ export interface ModelsPullResult {
  */
 function getTypesToPull(options: ModelsPullOptions): ModelType[] {
   if (options.all) {
-    return ["embed", "rerank", "gen"];
+    return ["embed", "rerank", "expand", "gen"];
   }
-  if (options.embed || options.rerank || options.gen) {
+  if (options.embed || options.rerank || options.expand || options.gen) {
     const types: ModelType[] = [];
     if (options.embed) {
       types.push("embed");
@@ -69,13 +71,16 @@ function getTypesToPull(options: ModelsPullOptions): ModelType[] {
     if (options.rerank) {
       types.push("rerank");
     }
+    if (options.expand) {
+      types.push("expand");
+    }
     if (options.gen) {
       types.push("gen");
     }
     return types;
   }
   // Default: pull all
-  return ["embed", "rerank", "gen"];
+  return ["embed", "rerank", "expand", "gen"];
 }
 
 /**
@@ -101,7 +106,8 @@ export async function modelsPull(
   let skipped = 0;
 
   for (const type of types) {
-    const uri = preset[type];
+    const uri =
+      type === "expand" ? (preset.expand ?? preset.gen) : preset[type];
 
     // Check if already cached (skip unless --force)
     if (!options.force) {
@@ -160,16 +166,18 @@ export async function modelsPull(
  */
 export function formatModelsPull(result: ModelsPullResult): string {
   const lines: string[] = [];
+  const label = (type: ModelType) =>
+    type === "gen" ? "answer" : type === "expand" ? "expand" : type;
 
   for (const r of result.results) {
     if (r.ok) {
       if (r.skipped) {
-        lines.push(`${r.type}: skipped (already cached)`);
+        lines.push(`${label(r.type)}: skipped (already cached)`);
       } else {
-        lines.push(`${r.type}: downloaded`);
+        lines.push(`${label(r.type)}: downloaded`);
       }
     } else {
-      lines.push(`${r.type}: failed - ${r.error}`);
+      lines.push(`${label(r.type)}: failed - ${r.error}`);
     }
   }
 

package/src/cli/commands/query.ts

@@ -36,7 +36,9 @@ export type QueryCommandOptions = HybridSearchOptions & {
   configPath?: string;
   /** Override embedding model */
   embedModel?: string;
-  /** Override generation model */
+  /** Override expansion model */
+  expandModel?: string;
+  /** Deprecated alias for expansion model */
   genModel?: string;
   /** Override rerank model */
   rerankModel?: string;
@@ -90,7 +92,7 @@ export async function query(
   const { store, config } = initResult;
 
   let embedPort: EmbeddingPort | null = null;
-  let genPort: GenerationPort | null = null;
+  let expandPort: GenerationPort | null = null;
   let rerankPort: RerankPort | null = null;
 
   try {
@@ -121,18 +123,19 @@ export async function query(
       embedPort = embedResult.value;
     }
 
-    // Create generation port (for expansion) - optional.
+    // Create expansion port - optional.
     // Skip when structured query modes are provided.
     if (!options.noExpand && !options.queryModes?.length) {
-      const genUri = options.genModel ?? preset.gen;
-      const genResult = await llm.createGenerationPort(genUri, {
+      const expandUri =
+        options.expandModel ?? options.genModel ?? preset.expand;
+      const genResult = await llm.createExpansionPort(expandUri, {
         policy,
         onProgress: downloadProgress
-          ? (progress) => downloadProgress("gen", progress)
+          ? (progress) => downloadProgress("expand", progress)
           : undefined,
       });
       if (genResult.ok) {
-        genPort = genResult.value;
+        expandPort = genResult.value;
       }
     }
 
@@ -177,7 +180,7 @@ export async function query(
       config,
       vectorIndex,
       embedPort,
-      genPort,
+      expandPort,
       rerankPort,
     };
 
@@ -195,8 +198,8 @@ export async function query(
     if (embedPort) {
       await embedPort.dispose();
     }
-    if (genPort) {
-      await genPort.dispose();
+    if (expandPort) {
+      await expandPort.dispose();
     }
     if (rerankPort) {
       await rerankPort.dispose();