@gmickel/gno 0.3.4 → 0.4.0

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 };
+}

package/src/serve/CLAUDE.md

@@ -0,0 +1,91 @@
+# Web UI (gno serve)
+
+Local web server for GNO search and document browsing.
+
+## Architecture
+
+Uses same **"Ports without DI"** pattern as CLI/MCP (see root CLAUDE.md):
+- Adapters instantiated directly in `context.ts`
+- Pipeline code receives port interfaces
+- No dependency injection
+
+```
+src/serve/
+├── server.ts          # Bun.serve() entry point
+├── context.ts         # ServerContext with LLM ports
+├── routes/
+│   └── api.ts         # REST API handlers
+└── public/            # React frontend (Bun HTML imports)
+    ├── App.tsx        # Router
+    ├── pages/         # Page components
+    ├── components/    # UI components (ShadCN + AI Elements)
+    └── hooks/         # Custom hooks (useApi, etc.)
+```
+
+## Key Patterns
+
+### Ports (interfaces)
+- `EmbeddingPort` - vector embeddings
+- `GenerationPort` - LLM text generation
+- `RerankPort` - cross-encoder reranking
+- `VectorIndexPort` - vector search
+
+### ServerContext
+Created at startup, holds all LLM ports and capabilities:
+```typescript
+interface ServerContext {
+  store: SqliteAdapter;
+  config: Config;
+  vectorIndex: VectorIndexPort | null;
+  embedPort: EmbeddingPort | null;
+  genPort: GenerationPort | null;
+  rerankPort: RerankPort | null;
+  capabilities: { bm25, vector, hybrid, answer };
+}
+```
+
+### Shared Pipeline Code
+Answer generation uses shared module to stay in sync with CLI:
+- `src/pipeline/answer.ts` - generateGroundedAnswer, processAnswerResult
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Health check |
+| `/api/status` | GET | Index stats, collections |
+| `/api/capabilities` | GET | Available features |
+| `/api/collections` | GET | List collections |
+| `/api/docs` | GET | List documents |
+| `/api/doc` | GET | Get document content |
+| `/api/search` | POST | BM25 search |
+| `/api/query` | POST | Hybrid search |
+| `/api/ask` | POST | AI answer with citations |
+| `/api/presets` | GET | List model presets |
+| `/api/presets` | POST | Switch preset (hot-reload) |
+| `/api/models/status` | GET | Download progress |
+| `/api/models/pull` | POST | Start model download |
+
+## Frontend
+
+- **Framework**: React (via Bun HTML imports)
+- **Styling**: Tailwind CSS + ShadCN components
+- **AI Elements**: Conversation, Message, Sources, CodeBlock, Loader
+- **Routing**: Simple hash-free SPA routing in App.tsx
+
+## Development
+
+```bash
+# Start dev server with HMR
+bun run src/serve/index.ts
+
+# Or via CLI
+gno serve --port 3000
+```
+
+## Security
+
+- Binds to `127.0.0.1` only (no LAN exposure)
+- CSP headers on all responses
+- CORS protection on POST endpoints
+- No external font/script loading

package/src/serve/bunfig.toml

@@ -0,0 +1,2 @@
+[serve.static]
+plugins = ["bun-plugin-tailwind"]