@gmickel/gno 0.3.5 → 0.4.0

package/README.md

@@ -16,6 +16,8 @@ GNO is a local knowledge engine for privacy-conscious developers and AI agents.
 - [Quick Start](#quick-start)
 - [Installation](#installation)
 - [Search Modes](#search-modes)
+- [Web UI](#web-ui)
+- [REST API](#rest-api)
 - [Agent Integration](#agent-integration)
 - [How It Works](#how-it-works)
 - [Features](#features)
@@ -113,6 +115,65 @@ Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
 
 ---
 
+## Web UI
+
+Visual dashboard for search, browsing, and AI answers—right in your browser.
+
+```bash
+gno serve                    # Start on port 3000
+gno serve --port 8080        # Custom port
+```
+
+Open `http://localhost:3000` to:
+
+- **Search** — BM25, vector, or hybrid modes with visual results
+- **Browse** — Paginated document list, filter by collection
+- **Ask** — AI-powered Q&A with citations
+- **Switch presets** — Change models live without restart
+
+Everything runs locally. No cloud, no accounts, no data leaving your machine.
+
+> **Detailed docs**: [Web UI Guide](https://gno.sh/docs/WEB-UI/)
+
+---
+
+## REST API
+
+Programmatic access to all GNO features via HTTP.
+
+```bash
+# Hybrid search
+curl -X POST http://localhost:3000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "authentication patterns", "limit": 10}'
+
+# AI answer
+curl -X POST http://localhost:3000/api/ask \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is our deployment process?"}'
+
+# Index status
+curl http://localhost:3000/api/status
+```
+
+| Endpoint | Method | Description |
+|:---------|:-------|:------------|
+| `/api/query` | POST | Hybrid search (recommended) |
+| `/api/search` | POST | BM25 keyword search |
+| `/api/ask` | POST | AI-powered Q&A |
+| `/api/docs` | GET | List documents |
+| `/api/doc` | GET | Get document content |
+| `/api/status` | GET | Index statistics |
+| `/api/presets` | GET/POST | Model preset management |
+| `/api/models/pull` | POST | Download models |
+| `/api/models/status` | GET | Download progress |
+
+No authentication. No rate limits. Build custom tools, automate workflows, integrate with any language.
+
+> **Full reference**: [API Documentation](https://gno.sh/docs/API/)
+
+---
+
 ## Agent Integration
 
 ### MCP Server
@@ -183,6 +244,8 @@ graph TD
 | Feature | Description |
 |:--------|:------------|
 | **Hybrid Search** | BM25 + vector + RRF fusion + cross-encoder reranking |
+| **Web UI** | Visual dashboard for search, browse, and AI Q&A |
+| **REST API** | HTTP API for custom tools and integrations |
 | **Multi-Format** | Markdown, PDF, DOCX, XLSX, PPTX, plain text |
 | **Local LLM** | AI answers via llama.cpp—no API keys |
 | **Privacy First** | 100% offline, zero telemetry, your data stays yours |
@@ -224,7 +287,7 @@ gno models pull --all
 
 ```
 ┌─────────────────────────────────────────────────┐
-│                 GNO CLI / MCP                   │
+│            GNO CLI / MCP / Web UI / API         │
 ├─────────────────────────────────────────────────┤
 │  Ports: Converter, Store, Embedding, Rerank    │
 ├─────────────────────────────────────────────────┤

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "search",
@@ -56,6 +56,8 @@
     "website:dev": "cd website && make serve",
     "website:build": "cd website && make build",
     "website:demos": "cd website/demos && ./build-demos.sh",
+    "serve": "bun src/index.ts serve",
+    "serve:dev": "NODE_ENV=development bun --hot src/index.ts serve",
     "version:patch": "npm version patch --no-git-tag-version",
     "version:minor": "npm version minor --no-git-tag-version",
     "version:major": "npm version major --no-git-tag-version",
@@ -65,18 +67,44 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "ai": "^6.0.5",
+    "bun-plugin-tailwind": "^0.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
     "commander": "^14.0.2",
+    "embla-carousel-react": "^8.6.0",
     "franc": "^6.2.0",
+    "lucide-react": "^0.562.0",
     "markitdown-ts": "^0.0.8",
+    "nanoid": "^5.1.6",
     "node-llama-cpp": "^3.14.5",
     "officeparser": "^5.2.2",
     "picocolors": "^1.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "shiki": "^3.20.0",
     "sqlite-vec": "^0.1.7-alpha.2",
+    "streamdown": "^1.6.10",
+    "tailwind-merge": "^3.4.0",
+    "use-stick-to-bottom": "^1.1.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.10",
     "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@typescript/native-preview": "^7.0.0-dev.20251215.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -87,6 +115,7 @@
     "oxlint-tsgolint": "^0.10.0",
     "pdf-lib": "^1.17.1",
     "pptxgenjs": "^4.0.1",
+    "tailwindcss": "^4.1.18",
     "ultracite": "^6.5.0"
   },
   "peerDependencies": {

package/src/cli/commands/ask.ts

@@ -12,13 +12,12 @@ import type {
   GenerationPort,
   RerankPort,
 } from '../../llm/types';
+import {
+  generateGroundedAnswer,
+  processAnswerResult,
+} from '../../pipeline/answer';
 import { type HybridSearchDeps, searchHybrid } from '../../pipeline/hybrid';
-import type {
-  AskOptions,
-  AskResult,
-  Citation,
-  SearchResult,
-} from '../../pipeline/types';
+import type { AskOptions, AskResult, Citation } from '../../pipeline/types';
 import {
   createVectorIndexPort,
   type VectorIndexPort,
@@ -50,163 +49,6 @@ export type AskCommandResult =
   | { success: true; data: AskResult }
   | { success: false; error: string };
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Grounded Answer Generation
-// ─────────────────────────────────────────────────────────────────────────────
-
-const ANSWER_PROMPT = `You are answering a question using ONLY the provided context blocks.
-
-Rules you MUST follow:
-1) Use ONLY facts stated in the context blocks. Do NOT use outside knowledge.
-2) Every factual statement must include an inline citation like [1] or [2] referring to a context block.
-3) If the context does not contain enough information to answer, reply EXACTLY:
-   "I don't have enough information in the provided sources to answer this question."
-4) Do not cite sources you did not use. Do not invent citation numbers.
-
-Question: {query}
-
-Context blocks:
-{context}
-
-Write a concise answer (1-3 paragraphs).`;
-
-/** Abstention message when LLM cannot ground answer */
-const ABSTENTION_MESSAGE =
-  "I don't have enough information in the provided sources to answer this question.";
-
-// Max characters per snippet to avoid blowing up prompt size
-const MAX_SNIPPET_CHARS = 1500;
-// Max number of sources to include in context
-const MAX_CONTEXT_SOURCES = 5;
-
-/**
- * Extract VALID citation numbers from answer text.
- * Only returns numbers in range [1, maxCitation].
- * @param answer Answer text to parse
- * @param maxCitation Maximum valid citation number
- * @returns Sorted unique valid citation numbers (1-indexed)
- */
-function extractValidCitationNumbers(
-  answer: string,
-  maxCitation: number
-): number[] {
-  const nums = new Set<number>();
-  // Use fresh regex to avoid lastIndex issues
-  const re = /\[(\d+)\]/g;
-  const matches = answer.matchAll(re);
-  for (const match of matches) {
-    const n = Number(match[1]);
-    // Only accept valid citation numbers in range [1, maxCitation]
-    if (Number.isInteger(n) && n >= 1 && n <= maxCitation) {
-      nums.add(n);
-    }
-  }
-  return [...nums].sort((a, b) => a - b);
-}
-
-/**
- * Filter citations to only those actually referenced in the answer.
- * @param citations All citations provided to LLM
- * @param validUsedNumbers Valid 1-indexed citation numbers from answer
- */
-function filterCitationsByUse(
-  citations: Citation[],
-  validUsedNumbers: number[]
-): Citation[] {
-  const usedSet = new Set(validUsedNumbers);
-  return citations.filter((_, idx) => usedSet.has(idx + 1));
-}
-
-/**
- * Renumber citations in answer text to match filtered citations.
- * E.g., if answer uses [2] and [5], renumber to [1] and [2].
- * Invalid citations (not in validUsedNumbers) are removed.
- */
-function renumberAnswerCitations(
-  answer: string,
-  validUsedNumbers: number[]
-): string {
-  // Build mapping: old number -> new number (1-indexed)
-  const mapping = new Map<number, number>();
-  for (let i = 0; i < validUsedNumbers.length; i++) {
-    const oldNum = validUsedNumbers[i];
-    if (oldNum !== undefined) {
-      mapping.set(oldNum, i + 1);
-    }
-  }
-
-  // Use fresh regex to avoid lastIndex issues
-  const re = /\[(\d+)\]/g;
-  // Replace valid [n] with renumbered [m], remove invalid citations
-  const replaced = answer.replace(re, (_match, numStr: string) => {
-    const oldNum = Number(numStr);
-    const newNum = mapping.get(oldNum);
-    // If not in mapping, remove the citation entirely
-    return newNum !== undefined ? `[${newNum}]` : '';
-  });
-
-  // Clean up whitespace artifacts from removed citations
-  // e.g., "See [99] for" → "See  for" → "See for"
-  return replaced.replace(/ {2,}/g, ' ').trim();
-}
-
-async function generateGroundedAnswer(
-  genPort: GenerationPort,
-  query: string,
-  results: SearchResult[],
-  maxTokens: number
-): Promise<{ answer: string; citations: Citation[] } | null> {
-  // Build context from top results with bounded snippet sizes
-  const contextParts: string[] = [];
-  const citations: Citation[] = [];
-
-  // Track citation index separately to ensure it matches context blocks exactly
-  let citationIndex = 0;
-
-  for (const r of results.slice(0, MAX_CONTEXT_SOURCES)) {
-    // Skip results with empty snippets
-    if (!r.snippet || r.snippet.trim().length === 0) {
-      continue;
-    }
-
-    // Cap snippet length to avoid prompt blowup
-    const snippet =
-      r.snippet.length > MAX_SNIPPET_CHARS
-        ? `${r.snippet.slice(0, MAX_SNIPPET_CHARS)}...`
-        : r.snippet;
-
-    citationIndex += 1;
-    contextParts.push(`[${citationIndex}] ${snippet}`);
-    citations.push({
-      docid: r.docid,
-      uri: r.uri,
-      startLine: r.snippetRange?.startLine,
-      endLine: r.snippetRange?.endLine,
-    });
-  }
-
-  // If no valid context, can't generate answer
-  if (contextParts.length === 0) {
-    return null;
-  }
-
-  const prompt = ANSWER_PROMPT.replace('{query}', query).replace(
-    '{context}',
-    contextParts.join('\n\n')
-  );
-
-  const result = await genPort.generate(prompt, {
-    temperature: 0,
-    maxTokens,
-  });
-
-  if (!result.ok) {
-    return null;
-  }
-
-  return { answer: result.value, citations };
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -327,7 +169,7 @@ export async function ask(
 
     if (shouldGenerateAnswer && genPort) {
       const maxTokens = options.maxAnswerTokens ?? 512;
-      const answerResult = await generateGroundedAnswer(
+      const rawResult = await generateGroundedAnswer(
         genPort,
         query,
         results,
@@ -335,7 +177,7 @@ export async function ask(
       );
 
       // Fail loudly if generation was requested but failed
-      if (!answerResult) {
+      if (!rawResult) {
         return {
           success: false,
           error:
@@ -343,27 +185,10 @@ export async function ask(
         };
       }
 
-      // Extract only VALID citation numbers (in range 1..citations.length)
-      const maxCitation = answerResult.citations.length;
-      const validUsedNums = extractValidCitationNumbers(
-        answerResult.answer,
-        maxCitation
-      );
-      const filteredCitations = filterCitationsByUse(
-        answerResult.citations,
-        validUsedNums
-      );
-
-      // Abstention guard: if no valid citations, LLM didn't ground the answer
-      if (validUsedNums.length === 0 || filteredCitations.length === 0) {
-        answer = ABSTENTION_MESSAGE;
-        citations = [];
-      } else {
-        // Renumber citations in answer to match filtered list (e.g., [2],[5] -> [1],[2])
-        // Invalid citations are removed from the answer text
-        answer = renumberAnswerCitations(answerResult.answer, validUsedNums);
-        citations = filteredCitations;
-      }
+      // Process answer: extract valid citations, filter, renumber
+      const processed = processAnswerResult(rawResult);
+      answer = processed.answer;
+      citations = processed.citations;
       answerGenerated = true;
     }
 

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

@@ -18,6 +18,8 @@ import type { DownloadProgress, ModelType } from '../../../llm/types';
 export interface ModelsPullOptions {
   /** Override config path */
   configPath?: string;
+  /** Override config object (takes precedence over configPath) */
+  config?: import('../../../config/types').Config;
   /** Pull all models */
   all?: boolean;
   /** Pull embedding model */
@@ -81,10 +83,13 @@ function getTypesToPull(options: ModelsPullOptions): ModelType[] {
 export async function modelsPull(
   options: ModelsPullOptions = {}
 ): Promise<ModelsPullResult> {
-  // Load config (use defaults if not initialized)
-  const { createDefaultConfig } = await import('../../../config');
-  const configResult = await loadConfig(options.configPath);
-  const config = configResult.ok ? configResult.value : createDefaultConfig();
+  // Use provided config, or load from disk (use defaults if not initialized)
+  let config = options.config;
+  if (!config) {
+    const { createDefaultConfig } = await import('../../../config');
+    const configResult = await loadConfig(options.configPath);
+    config = configResult.ok ? configResult.value : createDefaultConfig();
+  }
 
   const preset = getActivePreset(config);
   const cache = new ModelCache(getModelsCachePath());

package/src/cli/commands/serve.ts

@@ -0,0 +1,19 @@
+/**
+ * gno serve command implementation.
+ * Start web UI server.
+ *
+ * @module src/cli/commands/serve
+ */
+
+export type { ServeOptions, ServeResult } from '../../serve';
+
+/**
+ * Execute gno serve command.
+ * Server runs until SIGINT/SIGTERM.
+ */
+export async function serve(
+  options: import('../../serve').ServeOptions = {}
+): Promise<import('../../serve').ServeResult> {
+  const { startServer } = await import('../../serve');
+  return startServer(options);
+}

package/src/cli/program.ts

@@ -149,6 +149,7 @@ export function createProgram(): Command {
   wireRetrievalCommands(program);
   wireMcpCommand(program);
   wireSkillCommands(program);
+  wireServeCommand(program);
 
   // Add docs/support links to help footer
   program.addHelpText(
@@ -1328,3 +1329,30 @@ function wireSkillCommands(program: Command): void {
       });
     });
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Serve Command (web UI)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function wireServeCommand(program: Command): void {
+  program
+    .command('serve')
+    .description('Start web UI server')
+    .option('-p, --port <num>', 'port to listen on', '3000')
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const port = parsePositiveInt('port', cmdOpts.port);
+
+      const { serve } = await import('./commands/serve.js');
+      const result = await serve({
+        port,
+        configPath: globals.config,
+        index: globals.index,
+      });
+
+      if (!result.success) {
+        throw new CliError('RUNTIME', result.error ?? 'Server failed to start');
+      }
+      // Server runs until SIGINT/SIGTERM - no output needed here
+    });
+}

package/src/llm/registry.ts

@@ -19,7 +19,9 @@ import type { ModelType } from './types';
 export function getModelConfig(config: Config): ModelConfig {
   return {
     activePreset: config.models?.activePreset ?? 'balanced',
-    presets: config.models?.presets ?? DEFAULT_MODEL_PRESETS,
+    presets: config.models?.presets?.length
+      ? config.models.presets
+      : DEFAULT_MODEL_PRESETS,
     loadTimeout: config.models?.loadTimeout ?? 60_000,
     inferenceTimeout: config.models?.inferenceTimeout ?? 30_000,
     warmModelTtl: config.models?.warmModelTtl ?? 300_000,

package/src/pipeline/answer.ts

@@ -0,0 +1,191 @@
+/**
+ * Grounded answer generation.
+ * Shared between CLI ask command and web API.
+ *
+ * @module src/pipeline/answer
+ */
+
+import type { GenerationPort } from '../llm/types';
+import type { Citation, SearchResult } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ANSWER_PROMPT = `You are answering a question using ONLY the provided context blocks.
+
+Rules you MUST follow:
+1) Use ONLY facts stated in the context blocks. Do NOT use outside knowledge.
+2) Every factual statement must include an inline citation like [1] or [2] referring to a context block.
+3) If the context does not contain enough information to answer, reply EXACTLY:
+   "I don't have enough information in the provided sources to answer this question."
+4) Do not cite sources you did not use. Do not invent citation numbers.
+
+Question: {query}
+
+Context blocks:
+{context}
+
+Write a concise answer (1-3 paragraphs).`;
+
+/** Abstention message when LLM cannot ground answer */
+export const ABSTENTION_MESSAGE =
+  "I don't have enough information in the provided sources to answer this question.";
+
+/** Max characters per snippet to avoid blowing up prompt size */
+const MAX_SNIPPET_CHARS = 1500;
+
+/** Max number of sources to include in context */
+const MAX_CONTEXT_SOURCES = 5;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Citation Processing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract VALID citation numbers from answer text.
+ * Only returns numbers in range [1, maxCitation].
+ */
+export function extractValidCitationNumbers(
+  answer: string,
+  maxCitation: number
+): number[] {
+  const nums = new Set<number>();
+  const re = /\[(\d+)\]/g;
+  const matches = answer.matchAll(re);
+  for (const match of matches) {
+    const n = Number(match[1]);
+    if (Number.isInteger(n) && n >= 1 && n <= maxCitation) {
+      nums.add(n);
+    }
+  }
+  return [...nums].sort((a, b) => a - b);
+}
+
+/**
+ * Filter citations to only those actually referenced in the answer.
+ */
+export function filterCitationsByUse(
+  citations: Citation[],
+  validUsedNumbers: number[]
+): Citation[] {
+  const usedSet = new Set(validUsedNumbers);
+  return citations.filter((_, idx) => usedSet.has(idx + 1));
+}
+
+/**
+ * Renumber citations in answer text to match filtered citations.
+ * E.g., if answer uses [2] and [5], renumber to [1] and [2].
+ * Invalid citations (not in validUsedNumbers) are removed.
+ */
+export function renumberAnswerCitations(
+  answer: string,
+  validUsedNumbers: number[]
+): string {
+  const mapping = new Map<number, number>();
+  for (let i = 0; i < validUsedNumbers.length; i++) {
+    const oldNum = validUsedNumbers[i];
+    if (oldNum !== undefined) {
+      mapping.set(oldNum, i + 1);
+    }
+  }
+
+  const re = /\[(\d+)\]/g;
+  const replaced = answer.replace(re, (_match, numStr: string) => {
+    const oldNum = Number(numStr);
+    const newNum = mapping.get(oldNum);
+    return newNum !== undefined ? `[${newNum}]` : '';
+  });
+
+  return replaced.replace(/ {2,}/g, ' ').trim();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Answer Generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AnswerGenerationResult {
+  answer: string;
+  citations: Citation[];
+}
+
+/**
+ * Generate a grounded answer from search results.
+ * Returns null if no valid context or generation fails.
+ */
+export async function generateGroundedAnswer(
+  genPort: GenerationPort,
+  query: string,
+  results: SearchResult[],
+  maxTokens: number
+): Promise<AnswerGenerationResult | null> {
+  const contextParts: string[] = [];
+  const citations: Citation[] = [];
+  let citationIndex = 0;
+
+  for (const r of results.slice(0, MAX_CONTEXT_SOURCES)) {
+    if (!r.snippet || r.snippet.trim().length === 0) {
+      continue;
+    }
+
+    const snippet =
+      r.snippet.length > MAX_SNIPPET_CHARS
+        ? `${r.snippet.slice(0, MAX_SNIPPET_CHARS)}...`
+        : r.snippet;
+
+    citationIndex += 1;
+    contextParts.push(`[${citationIndex}] ${snippet}`);
+    citations.push({
+      docid: r.docid,
+      uri: r.uri,
+      startLine: r.snippetRange?.startLine,
+      endLine: r.snippetRange?.endLine,
+    });
+  }
+
+  if (contextParts.length === 0) {
+    return null;
+  }
+
+  const prompt = ANSWER_PROMPT.replace('{query}', query).replace(
+    '{context}',
+    contextParts.join('\n\n')
+  );
+
+  const result = await genPort.generate(prompt, {
+    temperature: 0,
+    maxTokens,
+  });
+
+  if (!result.ok) {
+    return null;
+  }
+
+  return { answer: result.value, citations };
+}
+
+/**
+ * Process raw answer result into final answer with cleaned citations.
+ * Extracts valid citations, filters unused ones, and renumbers.
+ */
+export function processAnswerResult(rawResult: AnswerGenerationResult): {
+  answer: string;
+  citations: Citation[];
+} {
+  const maxCitation = rawResult.citations.length;
+  const validUsedNums = extractValidCitationNumbers(
+    rawResult.answer,
+    maxCitation
+  );
+  const filteredCitations = filterCitationsByUse(
+    rawResult.citations,
+    validUsedNums
+  );
+
+  if (validUsedNums.length === 0 || filteredCitations.length === 0) {
+    return { answer: ABSTENTION_MESSAGE, citations: [] };
+  }
+
+  const answer = renumberAnswerCitations(rawResult.answer, validUsedNums);
+  return { answer, citations: filteredCitations };
+}