@gmickel/gno 0.22.6 → 0.24.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
@@ -187,6 +201,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 +294,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`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.22.6",
+  "version": "0.24.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/program.ts

@@ -497,6 +497,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;
@@ -656,6 +671,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;
+
       // Determine expansion/rerank settings based on flags
       // Default: skip expansion (balanced mode)
       let noExpand = true;

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/mcp/tools/query.ts

@@ -20,6 +20,7 @@ import type { ToolContext } from "../server";
 
 import { parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { normalizeStructuredQueryInput } from "../../core/structured-query";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { getActivePreset } from "../../llm/registry";
@@ -143,6 +144,19 @@ export function handleQuery(
         }
       }
 
+      const normalizedInput = normalizeStructuredQueryInput(
+        args.query,
+        args.queryModes ?? []
+      );
+      if (!normalizedInput.ok) {
+        throw new Error(normalizedInput.error.message);
+      }
+      const queryText = normalizedInput.value.query;
+      const queryModes =
+        normalizedInput.value.queryModes.length > 0
+          ? normalizedInput.value.queryModes
+          : undefined;
+
       const preset = getActivePreset(ctx.config);
       const llm = new LlmAdapter(ctx.config);
 
@@ -170,7 +184,7 @@ export function handleQuery(
         // Determine noExpand/noRerank based on mode flags
         // Priority: fast > thorough > expand/rerank params > defaults
         // Default: noExpand=true (skip expansion), noRerank=false (with reranking)
-        const hasStructuredModes = Boolean(args.queryModes?.length);
+        const hasStructuredModes = Boolean(queryModes?.length);
         let noExpand = true;
         let noRerank = false;
 
@@ -245,7 +259,7 @@ export function handleQuery(
         // Note: per spec, lang is a "hint" for query, not a filter
         // Pass as queryLanguageHint to affect expansion prompt selection
         // but NOT retrieval filtering (that would be options.lang)
-        const result = await searchHybrid(deps, args.query, {
+        const result = await searchHybrid(deps, queryText, {
           limit: args.limit ?? 5,
           minScore: args.minScore,
           collection: args.collection,
@@ -259,7 +273,7 @@ export function handleQuery(
           author: args.author,
           noExpand,
           noRerank,
-          queryModes: args.queryModes,
+          queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),
           tagsAny: normalizeTagFilters(args.tagsAny),
         });

package/src/pipeline/query-modes.ts

@@ -46,26 +46,31 @@ export function parseQueryModeSpecs(
   specs: string[]
 ): StoreResult<QueryModeInput[]> {
   const parsed: QueryModeInput[] = [];
-  let hydeCount = 0;
-
   for (const spec of specs) {
     const entry = parseQueryModeSpec(spec);
     if (!entry.ok) {
       return entry;
     }
-    if (entry.value.mode === "hyde") {
-      hydeCount += 1;
-      if (hydeCount > 1) {
-        return err(
-          "INVALID_INPUT",
-          "Only one hyde mode is allowed in structured query input."
-        );
-      }
-    }
     parsed.push(entry.value);
   }
 
-  return ok(parsed);
+  return validateQueryModes(parsed);
+}
+
+/**
+ * Validate normalized query mode objects.
+ */
+export function validateQueryModes(
+  queryModes: QueryModeInput[]
+): StoreResult<QueryModeInput[]> {
+  const hydeCount = queryModes.filter((entry) => entry.mode === "hyde").length;
+  if (hydeCount > 1) {
+    return err(
+      "INVALID_INPUT",
+      "Only one hyde mode is allowed in structured query input."
+    );
+  }
+  return ok(queryModes);
 }
 
 /**