A cited RAG endpoint over your Markdown wiki

#!/usr/bin/env node
// ask-wiki.mjs — retrieve-then-generate over a local embeddings index.
// Node 20+, zero dependencies. READ-ONLY: no write path, no index rebuild,
// no repository mutation — the only file operations here are reads.
//
//   GET  /health          -> revision, canonical_head, stale, counts
//   POST /ask  {question, k?}
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import http from 'node:http'

const PORT        = Number(process.env.ASK_PORT || 9113)
const INDEX_DIR   = process.env.INDEX_DIR || '/wiki-data/embeddings-index'
const GIT_DIR     = process.env.GIT_DIR   || '/wiki-data/git/.git'
const EMBED_HOSTS = (process.env.OLLAMA_HOSTS ||
  'http://10.0.0.65:11434,http://10.0.0.66:11434,http://10.0.0.67:11434').split(',')
const EMBED_MODEL = process.env.EMBED_MODEL || 'nomic-embed-text'
const API_KEY     = process.env.ANTHROPIC_API_KEY || ''  // from your secret store
const MODEL       = process.env.ASK_MODEL || 'claude-haiku-4-5'

const norm = (v) => Math.sqrt(v.reduce((s, x) => s + x * x, 0))

// ── index cache: reload only when the stamped revision changes ──────────
let cache = null
function index() {
  const revision = readFileSync(join(INDEX_DIR, '.canonical-revision'), 'utf8').trim()
  if (cache && cache.revision === revision) return cache
  const chunks = JSON.parse(readFileSync(join(INDEX_DIR, 'chunks.json'), 'utf8'))
  cache = {
    revision, chunks,
    norms: chunks.map((c) => norm(c.vector)),
    pages: new Set(chunks.map((c) => c.wiki_path)).size,
  }
  console.log(`index loaded: ${chunks.length} chunks @ ${revision.slice(0, 8)}`)
  return cache
}

// ── live revision, by reading .git refs directly ────────────────────────
// Shelling out to `git` fails here: it refuses to operate on a repository
// owned by another user ("dubious ownership") unless you add a
// safe.directory exception — a capability this service does not need.
function head() {
  try {
    const h = readFileSync(join(GIT_DIR, 'HEAD'), 'utf8').trim()
    if (!h.startsWith('ref: ')) return h            // detached HEAD
    const ref = h.slice(5)
    try { return readFileSync(join(GIT_DIR, ref), 'utf8').trim() } catch {}
    for (const line of readFileSync(join(GIT_DIR, 'packed-refs'), 'utf8').split('\n'))
      if (line.endsWith(' ' + ref)) return line.split(' ')[0]
  } catch {}
  return null
}

// ── retrieve ───────────────────────────────────────────────────────────
async function embed(text) {
  for (const host of EMBED_HOSTS) {
    try {
      const r = await fetch(`${host}/api/embed`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        // `search_query:` is REQUIRED by nomic-embed-text, and must differ
        // from the `search_document:` prefix used when building the index.
        // Getting this backwards degrades results silently — it never errors.
        body: JSON.stringify({
          model: EMBED_MODEL, input: `search_query: ${text}`, truncate: true,
        }),
        signal: AbortSignal.timeout(15_000),
      })
      const v = (await r.json()).embeddings?.[0]
      if (Array.isArray(v)) return v
    } catch { /* try the next host */ }
  }
  throw new Error('no Ollama host returned an embedding')
}

function topK(qv, k) {
  const qn = norm(qv)
  return cache.chunks
    .map((chunk, i) => {
      let dot = 0
      for (let j = 0; j < qv.length; j++) dot += qv[j] * chunk.vector[j]
      return { score: dot / (qn * cache.norms[i]), chunk }
    })
    .sort((a, b) => b.score - a.score)
    .slice(0, k)
}

// ── generate ───────────────────────────────────────────────────────────
const system = (rev, stale) =>
  `You answer questions about a homelab from numbered wiki excerpts.
Answer ONLY from the excerpts provided. Cite them inline as [1], [2].
If they do not contain the answer, say so plainly and name the closest excerpt.
Never repeat a value that looks like a secret, even if an excerpt contains one.
Excerpt revision: ${rev}${stale ? ' — WARNING: this index is STALE relative to the live wiki; tell the user answers may be out of date.' : ''}`

async function generate(question, excerpts, rev, stale) {
  const block = excerpts
    .map((e, i) => `[${i + 1}] ${e.wiki_path} — ${e.heading}\n${e.text}`)
    .join('\n\n')
  const r = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'anthropic-version': '2023-06-01',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      model: MODEL,
      max_tokens: 1024,
      system: system(rev, stale),
      messages: [{ role: 'user', content: `${block}\n\nQuestion: ${question}` }],
    }),
    signal: AbortSignal.timeout(90_000),
  })
  const j = await r.json().catch(() => ({}))
  if (!r.ok) throw new Error(`anthropic ${r.status}: ${j.error?.message || 'error'}`)
  return (j.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n').trim()
}

// ── HTTP ───────────────────────────────────────────────────────────────
const send = (res, code, obj) => {
  res.writeHead(code, { 'content-type': 'application/json' })
  res.end(JSON.stringify(obj, null, 2))
}

const readBody = (req, limit = 65_536) => new Promise((resolve, reject) => {
  let size = 0; const parts = []
  req.on('data', (d) => {
    size += d.length
    if (size > limit) { reject(new Error('body too large')); req.destroy() }
    else parts.push(d)
  })
  req.on('end', () => resolve(Buffer.concat(parts).toString('utf8')))
  req.on('error', reject)
})

const server = http.createServer(async (req, res) => {
  try {
    if (req.method === 'GET' && req.url === '/health') {
      const c = index(), live = head()
      return send(res, 200, {
        ok: true, revision: c.revision, canonical_head: live,
        stale: live ? live !== c.revision : null,
        chunks: c.chunks.length, pages: c.pages,
      })
    }
    if (req.method !== 'POST' || req.url !== '/ask')
      return send(res, 404, { error: 'routes: GET /health, POST /ask' })

    const body = JSON.parse((await readBody(req)) || '{}')
    const question = typeof body.question === 'string' ? body.question.trim() : ''
    if (!question || question.length > 2000)
      return send(res, 400, { error: 'question: non-empty string, max 2000 chars' })
    const k = Math.min(12, Math.max(1, Number.isInteger(body.k) ? body.k : 6))

    const c = index(), live = head()
    const stale = live ? live !== c.revision : null
    const excerpts = topK(await embed(question), k).map(({ score, chunk }) => ({
      wiki_path: chunk.wiki_path,
      heading: chunk.heading,
      score: Math.round(score * 1000) / 1000,
      text: String(chunk.text).slice(0, 4000),
    }))
    const answer = await generate(question, excerpts, c.revision, stale)
    send(res, 200, {
      answer,
      sources: excerpts.map(({ text, ...meta }, i) =>
        ({ n: i + 1, ...meta, snippet: text.slice(0, 240) })),
      revision: c.revision, canonical_head: live, stale,
    })
  } catch (e) {
    if (!res.headersSent) send(res, 500, { error: e.message })
  }
})

server.headersTimeout = 60_000
server.listen(PORT, '0.0.0.0', () => {
  index()
  console.log(`ask-wiki listening on :${PORT} (model=${MODEL})`)
})