mlx-bun 0.0.9 → 0.0.11

package/src/web/src/quantize.ts

@@ -0,0 +1,167 @@
+// GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
+// §7/§9 Phase 2). Built into src/web/app.js by scripts/build-web.ts.
+//
+// QUANTIZE CONTROLLER — 4-step wizard. Behavior-identical port of the
+// original controllers.quantize IIFE in app.html.
+
+import { api, jobStream } from "./api";
+import type { ApiEnvelope } from "./protocol";
+import { $, el, toast, pushToHub, controllers } from "./shell";
+import { esc, renderSteps } from "./markdown";
+
+const STEPS = ["Source", "Configure", "Run", "Done"];
+
+// The File System Access API's showDirectoryPicker() isn't in lib.dom yet
+// in all TS configs; declare it loosely rather than widen the global Window
+// type project-wide.
+declare global {
+  interface Window {
+    showDirectoryPicker?: (opts?: { id?: string; mode?: string }) => Promise<{ name: string }>;
+  }
+}
+interface FileWithRelPath extends File {
+  webkitRelativePath: string;
+}
+
+export function createQuantizeController() {
+  let step = 0, bits = 4, gs = 64, mode: "uniform" | "mixed" = "uniform", bpw = 5, jobId: string | null = null, es: EventSource | null = null, log: string[] = [];
+
+  function show(n: number): void {
+    step = n;
+    document.querySelectorAll<HTMLElement>("[data-qstep]").forEach((d) => d.style.display = (+d.dataset.qstep! === n) ? "" : "none");
+    renderSteps($("q-steps"), STEPS, n);
+  }
+  function seg(container: HTMLElement, onPick: (v: string, b: HTMLButtonElement) => void): void {
+    container.querySelectorAll<HTMLButtonElement>("button").forEach((b) =>
+      b.addEventListener("click", () => {
+        container.querySelectorAll("button").forEach((x) => x.classList.remove("on"));
+        b.classList.add("on"); onPick(b.dataset.v || "", b);
+      }));
+  }
+
+  // --- OS folder picker / drag-drop -> real on-disk snapshot path ---
+  // The browser can't reveal an absolute path, and the HF cache uses symlinked
+  // snapshots over a blobs/ store — so we DON'T read any files. We only take the
+  // picked folder's NAME (which encodes the repo id) and let the server
+  // reconstruct the snapshot path it owns. No upload, no "config.json" hunt.
+  async function resolveByName(name: string, relPath?: string): Promise<void> {
+    if (!name && !relPath) return;
+    const out = $("q-inspect-out");
+    out.innerHTML = '<div class="flash"><span class="shimmer">locating on disk…</span></div>';
+    const d = await api("/api/quantize/resolve-folder", { method: "POST", body: { folder_name: name || "", rel_path: relPath || "" } })
+      .catch((): ApiEnvelope => ({ ok: false, error: "request failed" }));
+    if (!d.ok) { out.innerHTML = '<div class="flash err">' + esc(d.error || "could not locate this folder on the server") + "</div>"; return; }
+    ($("q-model") as HTMLInputElement).value = d.path as string;
+    inspect();
+  }
+  async function pickFolder(): Promise<void> {
+    // Native OS folder dialog with no "upload N files" prompt; we only read the
+    // folder's .name, never its contents.
+    if (window.showDirectoryPicker) {
+      try {
+        const handle = await window.showDirectoryPicker({ id: "mlx-models", mode: "read" });
+        return resolveByName(handle.name);
+      } catch { return; } // user cancelled / denied
+    }
+    $("q-folder").click(); // fallback for browsers without the File System Access API
+  }
+
+  async function inspect(): Promise<void> {
+    const id = ($("q-model") as HTMLInputElement).value.trim();
+    if (!id) { toast("Enter a model id or path first.", "err"); return; }
+    const out = $("q-inspect-out");
+    out.innerHTML = '<div class="flash"><span class="shimmer">inspecting…</span></div>';
+    const btn = $("q-inspect") as HTMLButtonElement; btn.disabled = true;
+    const d = await api("/api/quantize/inspect", { method: "POST", body: { model_id: id } }).catch((): ApiEnvelope => ({ ok: false, error: "request failed" }));
+    btn.disabled = false;
+    if (!d.ok) { out.innerHTML = '<div class="flash err">' + esc(d.error || "could not inspect this model") + "</div>"; return; }
+    // inspectModel returns support: boolean (src/quantize/job.ts); size_gb
+    // can be 0 when a direct path bypasses the registry — hide it then.
+    const supported = d.support === true;
+    const cls = supported ? "ok" : "err";
+    out.innerHTML =
+      '<div class="flash ' + cls + '"><strong>' + esc(d.arch || d.model_id || id) + "</strong>" +
+      (d.size_gb ? " · " + (+d.size_gb).toFixed(2) + " GB" : "") +
+      " · " + (supported ? "supported" : "not quantizable") + "</div>" +
+      '<div class="btnrow"><button class="btn primary" id="q-continue">Continue</button></div>';
+    ($("q-continue") as HTMLButtonElement).onclick = () => show(1);
+  }
+
+  async function submit(): Promise<void> {
+    const id = ($("q-model") as HTMLInputElement).value.trim();
+    const btn = $("q-submit") as HTMLButtonElement; btn.disabled = true;
+    const body: Record<string, unknown> = { model_id: id, bits, group_size: gs };
+    if (mode === "mixed") { body.target_bpw = bpw; body.candidate_bits = [4, 8]; }
+    const d = await api("/api/quantize/submit", { method: "POST", body })
+      .catch((): ApiEnvelope => ({ ok: false, error: "request failed" }));
+    btn.disabled = false;
+    if (!d.ok) { toast((d.error as string) || "could not start quantize", "err"); return; }
+    jobId = (d.job_id as string) || null;
+    $("q-push-panel").innerHTML = "";
+    $("q-out").textContent = (d.output_dir as string) || "";
+    log = []; $("q-log").textContent = ""; $("q-bar").style.width = "0%"; $("q-pct").textContent = "0%"; $("q-msg").textContent = "Starting…";
+    show(2);
+    attach(jobId!);
+  }
+
+  function attach(id: string): void {
+    if (es) es.close();
+    es = jobStream(id, {
+      log: (e) => { log.push(e.line); $("q-log").textContent = log.slice(-200).join("\n"); $("q-log").scrollTop = $("q-log").scrollHeight; },
+      stage: (e) => {
+        if (e.progress != null) { const p = Math.round(e.progress * 100); $("q-bar").style.width = p + "%"; $("q-pct").textContent = p + "%"; }
+        if (e.message) $("q-msg").textContent = e.message;
+        if (e.stage === "done") { if (e.output_dir) $("q-out").textContent = e.output_dir; finish(); }
+      },
+      done: () => finish(),
+      failed: (e) => { $("q-msg").textContent = "Failed: " + (e.error || "unknown error"); toast(e.error || "quantize failed", "err"); es && es.close(); },
+    });
+  }
+  function finish(): void {
+    $("q-bar").style.width = "100%"; $("q-pct").textContent = "100%"; es && es.close(); show(3);
+    // web-ui-pass-plan.md #3: the server invalidates its /library cache the
+    // instant this job completes (server.ts onComplete) — pull the fresh
+    // list right away instead of waiting for Status's own 15s poll.
+    if (controllers.status && controllers.status.refreshLibrary) (controllers.status.refreshLibrary as () => void)();
+  }
+
+  return {
+    init() {
+      show(0);
+      ($("q-inspect") as HTMLButtonElement).onclick = inspect;
+      $("q-model").addEventListener("keydown", (e) => { if ((e as KeyboardEvent).key === "Enter") inspect(); });
+      // OS folder dialog (native; resolves by folder name, no upload)
+      ($("q-browse") as HTMLButtonElement).onclick = pickFolder;
+      $("q-folder").addEventListener("change", (e) => {
+        const input = e.target as HTMLInputElement;
+        const f = input.files![0] as FileWithRelPath; input.value = "";
+        if (f) resolveByName((f.webkitRelativePath || f.name).split("/")[0]!, f.webkitRelativePath || "");
+      });
+      // drag a folder onto the box — use the directory entry's NAME (no read)
+      const drop = $("q-drop");
+      const hi = (on: boolean) => { drop.style.outline = on ? "2px dashed var(--blue)" : ""; drop.style.outlineOffset = on ? "4px" : ""; };
+      ["dragenter", "dragover"].forEach((ev) => drop.addEventListener(ev, (e) => { e.preventDefault(); hi(true); }));
+      ["dragleave", "drop"].forEach((ev) => drop.addEventListener(ev, (e) => {
+        e.preventDefault(); hi(false);
+        const de = e as DragEvent;
+        if (ev !== "drop" || !de.dataTransfer) return;
+        for (const it of [...(de.dataTransfer.items || [])]) {
+          const en = it.webkitGetAsEntry && it.webkitGetAsEntry();
+          if (en && en.isDirectory) return void resolveByName(en.name);
+        }
+        const f = de.dataTransfer.files && de.dataTransfer.files[0] as FileWithRelPath | undefined;
+        if (f) resolveByName((f.webkitRelativePath || f.name).split("/")[0]!);
+      }));
+      seg($("q-bits"), (v) => { bits = +v; $("q-bits-hint").textContent = v === "4"
+        ? "4-bit · ~4× smaller than bf16 · the recommended default for local serving."
+        : "8-bit · ~2× smaller than bf16 · highest fidelity quant."; });
+      seg($("q-gs"), (v) => { gs = +v; });
+      seg($("q-mode"), (v) => { mode = v as "uniform" | "mixed"; $("q-bpw-field").style.display = v === "mixed" ? "" : "none"; });
+      $("q-bpw").addEventListener("input", (e) => { bpw = +(e.target as HTMLInputElement).value; $("q-bpw-val").textContent = bpw.toFixed(1); });
+      document.querySelectorAll<HTMLButtonElement>("#s-quantize [data-qback]").forEach((b) => b.onclick = () => show(step - 1));
+      ($("q-submit") as HTMLButtonElement).onclick = submit;
+      ($("q-push") as HTMLButtonElement).onclick = () => pushToHub($("q-push-panel"), { kind: "quantize", job_id: jobId || undefined });
+      ($("q-again") as HTMLButtonElement).onclick = () => { $("q-inspect-out").innerHTML = ""; $("q-push-panel").innerHTML = ""; show(0); };
+    },
+  };
+}

package/src/web/src/rag.ts

@@ -0,0 +1,274 @@
+// GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
+// §9 Phase 3, beat matrix Axis 5 — "chat-with-files RAG v1"). Built into
+// src/web/app.js by scripts/build-web.ts.
+//
+// A small, dependency-free, pure BM25 retriever over attached-file text —
+// matching optiq Lab's shipped v1 shape (the task's explicit target): chunk
+// per-file, tokenize, score chunks against the outgoing message, return the
+// top-K with enough metadata (filename + char range) for composer.ts to
+// build a cited context block and chat.ts to render a Sources panel.
+//
+// No network, no embeddings, no external deps — this is the "dependency-
+// free BM25 proves the v1 needs no vector infra" bet from the beat matrix.
+// A later vector upgrade (src/embed.ts) is explicitly out of scope here
+// (Phase 5).
+
+/* ────────────────────────────────────────────────────────────────────
+   Chunking
+   ──────────────────────────────────────────────────────────────────── */
+
+/** One retrievable unit: a slice of one attached file's text, with the
+ *  original [start,end) char offsets so the Sources panel can show a
+ *  meaningful "filename + range" citation. */
+export interface Chunk {
+  fileId: number;
+  fileName: string;
+  start: number;
+  end: number;
+  text: string;
+}
+
+const CHUNK_TARGET = 1200;
+
+/** Split one file's text into ~CHUNK_TARGET-char chunks, preferring to break
+ *  on paragraph boundaries (blank lines) so a chunk doesn't slice through
+ *  the middle of a paragraph when a nearby boundary is available. Pure:
+ *  takes text in, returns chunks with byte-accurate offsets into that same
+ *  text (no trimming of the returned `text` field's positions — leading/
+ *  trailing whitespace inside a chunk is fine, it's still exactly
+ *  text.slice(start, end)).
+ *
+ *  Algorithm: walk paragraph boundaries (split on /\n\s*\n/, keeping track
+ *  of each paragraph's offset in the original string) and greedily pack
+ *  paragraphs into a chunk until adding the next one would exceed
+ *  CHUNK_TARGET *and* the chunk already has content — mirroring a standard
+ *  greedy bin-packing chunker. A single paragraph longer than CHUNK_TARGET
+ *  becomes its own oversized chunk rather than being split mid-word (never
+ *  produce an empty chunk, never lose text). */
+export function chunkText(fileId: number, fileName: string, text: string): Chunk[] {
+  if (!text) return [];
+  const chunks: Chunk[] = [];
+  // Split on blank-line paragraph boundaries, tracking each paragraph's
+  // [start,end) in the ORIGINAL string (not the split pieces' own indices).
+  const paraRe = /\n\s*\n/g;
+  const paras: { start: number; end: number }[] = [];
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = paraRe.exec(text))) {
+    paras.push({ start: last, end: m.index });
+    last = m.index + m[0].length;
+  }
+  paras.push({ start: last, end: text.length });
+
+  let curStart = -1, curEnd = -1;
+  const flush = () => {
+    if (curStart < 0 || curEnd <= curStart) return;
+    chunks.push({ fileId, fileName, start: curStart, end: curEnd, text: text.slice(curStart, curEnd) });
+    curStart = -1; curEnd = -1;
+  };
+  for (const p of paras) {
+    if (p.end <= p.start) continue; // blank paragraph (consecutive blank lines) — nothing to add
+    const paraLen = p.end - p.start;
+    if (curStart < 0) {
+      // Starting a fresh chunk with this paragraph.
+      curStart = p.start; curEnd = p.end;
+      if (paraLen >= CHUNK_TARGET) flush(); // oversized single paragraph -> its own chunk immediately
+      continue;
+    }
+    const curLen = curEnd - curStart;
+    if (curLen + paraLen > CHUNK_TARGET) {
+      // Adding this paragraph would overflow the target — close the current
+      // chunk at the last paragraph boundary and start a new one with this
+      // paragraph (paragraph-boundary-preferring: we never split a paragraph
+      // in half to hit the target exactly).
+      flush();
+      curStart = p.start; curEnd = p.end;
+      if (paraLen >= CHUNK_TARGET) flush();
+    } else {
+      curEnd = p.end;
+    }
+  }
+  flush();
+  return chunks;
+}
+
+/** Chunk every attached text file (name/text pairs) into one flat list,
+ *  independently per file (chunks never span files) — the shape composer.ts
+ *  feeds from ComposerState.attachments. */
+export function chunkFiles(files: { id: number; name: string; text: string }[]): Chunk[] {
+  const out: Chunk[] = [];
+  for (const f of files) out.push(...chunkText(f.id, f.name, f.text));
+  return out;
+}
+
+/* ────────────────────────────────────────────────────────────────────
+   Tokenizer
+   ──────────────────────────────────────────────────────────────────── */
+
+/** Lowercase, alnum-run tokenizer. Pure and deliberately simple — no
+ *  stemming/stopwords, matching the "dependency-free" bar; BM25's own
+ *  length-normalization and IDF weighting do most of the useful work even
+ *  over a raw token stream. */
+export function tokenize(text: string): string[] {
+  const m = text.toLowerCase().match(/[a-z0-9]+/g);
+  return m || [];
+}
+
+/* ────────────────────────────────────────────────────────────────────
+   BM25 index + scoring
+   ──────────────────────────────────────────────────────────────────── */
+
+// BM25 standard formula (Robertson/Sparck Jones), as in Manning/Raghavan/
+// Schütze "Introduction to Information Retrieval" §11.4.3:
+//
+//   score(D,Q) = Σ_{t∈Q} IDF(t) · ( f(t,D)·(k1+1) ) / ( f(t,D) + k1·(1-b+b·|D|/avgdl) )
+//
+// with IDF(t) = ln( (N - n(t) + 0.5) / (n(t) + 0.5) + 1 )  (the "+1" variant
+// that keeps IDF non-negative for terms present in every document, per the
+// same reference). k1=1.5, b=0.75 are the conventional defaults used there.
+const K1 = 1.5;
+const B = 0.75;
+
+interface IndexedChunk {
+  chunk: Chunk;
+  termCounts: Map<string, number>;
+  length: number;
+}
+
+/** A BM25 index over a fixed chunk set. Built lazily (see buildIndex) and
+ *  meant to be rebuilt whenever the attachment set changes — indexing a
+ *  few dozen small chunks is cheap enough that no incremental-update path
+ *  is warranted. */
+export interface Bm25Index {
+  chunks: IndexedChunk[];
+  df: Map<string, number>; // document frequency per term
+  avgLength: number;
+  n: number;
+}
+
+export function buildIndex(chunks: Chunk[]): Bm25Index {
+  const indexed: IndexedChunk[] = [];
+  const df = new Map<string, number>();
+  let totalLen = 0;
+  for (const chunk of chunks) {
+    const toks = tokenize(chunk.text);
+    const termCounts = new Map<string, number>();
+    for (const t of toks) termCounts.set(t, (termCounts.get(t) || 0) + 1);
+    for (const t of termCounts.keys()) df.set(t, (df.get(t) || 0) + 1);
+    totalLen += toks.length;
+    indexed.push({ chunk, termCounts, length: toks.length });
+  }
+  return {
+    chunks: indexed,
+    df,
+    avgLength: indexed.length ? totalLen / indexed.length : 0,
+    n: indexed.length,
+  };
+}
+
+function idf(index: Bm25Index, term: string): number {
+  const n = index.df.get(term) || 0;
+  return Math.log((index.n - n + 0.5) / (n + 0.5) + 1);
+}
+
+export interface ScoredChunk {
+  chunk: Chunk;
+  score: number;
+}
+
+/** Score every chunk in `index` against `query`, returning the top `k` by
+ *  descending BM25 score (ties broken by original chunk order, stable).
+ *  Chunks that score 0 (no query term present at all) are excluded — a
+ *  zero-overlap chunk is never a useful citation regardless of how few
+ *  chunks exist. */
+export function bm25TopK(index: Bm25Index, query: string, k: number): ScoredChunk[] {
+  const qTerms = tokenize(query);
+  if (!qTerms.length || !index.n) return [];
+  // Dedupe query terms but keep per-term query frequency out of the score
+  // (standard BM25 as written above weights by document term frequency
+  // only; query-term repetition isn't part of the classic formula).
+  const uniqueTerms = [...new Set(qTerms)];
+  const scored: ScoredChunk[] = [];
+  for (const ic of index.chunks) {
+    let score = 0;
+    for (const term of uniqueTerms) {
+      const f = ic.termCounts.get(term);
+      if (!f) continue;
+      const numer = f * (K1 + 1);
+      const denom = f + K1 * (1 - B + (B * ic.length) / (index.avgLength || 1));
+      score += idf(index, term) * (numer / denom);
+    }
+    if (score > 0) scored.push({ chunk: ic.chunk, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, k);
+}
+
+/* ────────────────────────────────────────────────────────────────────
+   Inline-vs-RAG decision + context-block assembly
+   ──────────────────────────────────────────────────────────────────── */
+
+/** Above this total attached-text size, switch from "inline everything"
+ *  to "retrieve top-K chunks" — LM Studio's transparent dual-mode
+ *  threshold (beat matrix Axis 5), tuned so ordinary small attachments
+ *  (READMEs, short notes) never change behavior at all. */
+export const INLINE_THRESHOLD_CHARS = 8000;
+
+export const TOP_K = 6;
+
+/** Pure: does this total attached-text length trigger retrieval mode? */
+export function shouldRetrieve(totalChars: number): boolean {
+  return totalChars > INLINE_THRESHOLD_CHARS;
+}
+
+/** One numbered citation as composer.ts will inject it and chat.ts will
+ *  reference by index — `n` is the 1-based [n] marker shown to the model
+ *  and rendered back to the user. */
+export interface Citation {
+  n: number;
+  fileName: string;
+  start: number;
+  end: number;
+  text: string;
+}
+
+/** Build the numbered [1]..[K] citation list from a scored top-K result.
+ *  Pure — shared by composer.ts (building the outgoing context block) and
+ *  chat.ts/tests (rendering the Sources panel from the same shape). */
+export function toCitations(top: ScoredChunk[]): Citation[] {
+  return top.map((s, i) => ({
+    n: i + 1,
+    fileName: s.chunk.fileName,
+    start: s.chunk.start,
+    end: s.chunk.end,
+    text: s.chunk.text,
+  }));
+}
+
+/** Render the framed context block injected ahead of the user's message
+ *  when in retrieval mode: each citation numbered [n] with filename+range,
+ *  then ONE instruction line asking the model to cite sources with [n]
+ *  markers when used. Plain text (this goes into the outgoing prompt, not
+ *  HTML) — chat.ts/markdown.ts handle rendering [n] markers back as links
+ *  separately, from the citation map, not from parsing this block. */
+export function buildContextBlock(citations: Citation[]): string {
+  if (!citations.length) return "";
+  let out = "Context from attached files (retrieved by relevance to your message):\n\n";
+  for (const c of citations) {
+    out += `[${c.n}] ${c.fileName} (chars ${c.start}-${c.end}):\n${c.text}\n\n`;
+  }
+  out += "When you use information from the context above, cite it inline with the matching [n] marker.\n\n";
+  return out;
+}
+
+/** Full retrieval pipeline for one outgoing message: chunk the attached
+ *  text files, index them, score against `queryText`, and return the
+ *  top-K as citations ready for buildContextBlock. Returns [] if there's
+ *  nothing to retrieve (no text files, or no query overlap at all). */
+export function retrieve(files: { id: number; name: string; text: string }[], queryText: string, k = TOP_K): Citation[] {
+  const chunks = chunkFiles(files);
+  if (!chunks.length) return [];
+  const index = buildIndex(chunks);
+  const top = bm25TopK(index, queryText, k);
+  return toCitations(top);
+}