@tiens.nguyen/gonext-cli 1.0.350

package/gonext_mlx_embed.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+GoNext MLX embeddings server — an OpenAI-compatible /v1/embeddings endpoint for MLX
+embedding models (e.g. Qwen3-Embedding-8B), which `mlx_lm.server` does NOT provide.
+
+The GoNext worker's RAG tools call `POST {url}/v1/embeddings` first, so pointing the
+"RAG embedding server URL" (web Settings → Agent → RAG) at this server makes MLX
+embeddings work with no other changes.
+
+Run:
+    python3 gonext_mlx_embed.py --model ~/mlx-models/Qwen3-Embedding-8B-4bit-DWQ --port 8085
+
+Then set the RAG embedding server URL to http://127.0.0.1:8085
+
+Endpoints:
+    POST /v1/embeddings   {"model": <ignored>, "input": "text" | ["t1","t2",...]}
+                          → {"object":"list","data":[{"object":"embedding","index":i,
+                             "embedding":[...]}], "model": <name>, "usage": {...}}
+    GET  /v1/models       → the single loaded model
+    GET  /health          → {"status":"ok"}
+
+Pooling: last-token hidden state (Qwen3-Embedding convention), L2-normalized.
+Requires: mlx, mlx_lm (already used by the worker). No extra deps.
+"""
+import argparse
+import json
+import os
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import mlx.core as mx
+from mlx_lm import load
+
+# Cap tokens per input so a pathologically long chunk can't OOM / stall the GPU.
+MAX_TOKENS = 8192
+
+_model = None
+_tok = None
+_inner = None            # the transformer body that returns hidden states
+_model_name = "mlx-embedding"
+_lock = threading.Lock()  # MLX eval isn't guaranteed thread-safe; serialize inference
+
+
+def _load(model_path: str) -> None:
+    global _model, _tok, _inner, _model_name
+    print(f"[gonext-mlx-embed] loading {model_path} …", flush=True)
+    _model, _tok = load(model_path)
+    # mlx_lm wraps the transformer body as `.model` (returns hidden states); `_model(x)`
+    # would return logits from the LM head, which we do NOT want.
+    _inner = getattr(_model, "model", None) or getattr(_model, "language_model", None)
+    if _inner is None:
+        raise RuntimeError("Could not find the transformer body on the loaded model.")
+    _model_name = os.path.basename(os.path.normpath(model_path))
+    # Warm + sanity-check the embedding path so a bad model fails fast at startup.
+    v = _embed_one("warmup")
+    print(f"[gonext-mlx-embed] ready — {_model_name}, dim={len(v)}", flush=True)
+
+
+def _embed_one(text: str) -> list:
+    ids = _tok.encode(text or " ")
+    if not ids:
+        ids = _tok.encode(" ")
+    if len(ids) > MAX_TOKENS:
+        ids = ids[:MAX_TOKENS]
+    h = _inner(mx.array([ids]))          # (1, seq, hidden)
+    v = h[0, -1, :]                       # last-token pooling
+    v = v / mx.maximum(mx.linalg.norm(v), 1e-9)   # L2 normalize
+    mx.eval(v)
+    return [float(x) for x in v.tolist()]
+
+
+def _embed_batch(texts: list) -> list:
+    with _lock:
+        out = [_embed_one(t) for t in texts]
+    return out
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *a):  # quieter logs
+        pass
+
+    def _send(self, code: int, obj: dict) -> None:
+        body = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send(200, {"status": "ok", "model": _model_name})
+        elif self.path in ("/v1/models", "/models"):
+            self._send(200, {"object": "list", "data": [
+                {"id": _model_name, "object": "model", "owned_by": "gonext-mlx-embed"}
+            ]})
+        else:
+            self._send(404, {"error": {"message": f"unknown path {self.path}"}})
+
+    def do_POST(self):
+        if self.path not in ("/v1/embeddings", "/embeddings"):
+            self._send(404, {"error": {"message": f"unknown path {self.path}"}})
+            return
+        try:
+            n = int(self.headers.get("Content-Length", 0) or 0)
+            payload = json.loads(self.rfile.read(n) or b"{}")
+        except Exception as e:  # noqa: BLE001
+            self._send(400, {"error": {"message": f"bad JSON: {e}"}})
+            return
+        inp = payload.get("input")
+        if inp is None:
+            self._send(400, {"error": {"message": "missing 'input'"}})
+            return
+        texts = [inp] if isinstance(inp, str) else list(inp)
+        if not all(isinstance(t, str) for t in texts):
+            self._send(400, {"error": {"message": "'input' must be a string or list of strings"}})
+            return
+        try:
+            vecs = _embed_batch(texts)
+        except Exception as e:  # noqa: BLE001
+            self._send(500, {"error": {"message": f"embedding failed: {type(e).__name__}: {e}"}})
+            return
+        total_tokens = sum(len(_tok.encode(t or " ")) for t in texts)
+        self._send(200, {
+            "object": "list",
+            "data": [
+                {"object": "embedding", "index": i, "embedding": v}
+                for i, v in enumerate(vecs)
+            ],
+            "model": payload.get("model") or _model_name,
+            "usage": {"prompt_tokens": total_tokens, "total_tokens": total_tokens},
+        })
+
+
+def main():
+    ap = argparse.ArgumentParser(description="OpenAI-compatible MLX embeddings server.")
+    ap.add_argument("--model", required=True, help="Path to the MLX embedding model dir.")
+    ap.add_argument("--port", type=int, default=8085)
+    ap.add_argument("--host", default="127.0.0.1")
+    args = ap.parse_args()
+    _load(os.path.expanduser(args.model))
+    srv = ThreadingHTTPServer((args.host, args.port), Handler)
+    print(f"[gonext-mlx-embed] serving /v1/embeddings on http://{args.host}:{args.port}", flush=True)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[gonext-mlx-embed] shutting down", flush=True)
+        srv.shutdown()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/gonext_probe_agent.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+gonext probe agent (agentic mode for the gonext local worker).
+
+Reads a JSON probe config on stdin and writes a single JSON object on stdout:
+
+  in:  {"request": {"method","url"},
+        "measurement": {"status","statusText","latencyMs","headers",
+                        "bodySnippet","bodyBytes"} | null,
+        "category": str, "error": str | null,
+        "agentBaseURL","agentApiKey","agentModelId"}
+  out: {"agentSummary": str, "error": str | null}
+
+The worker performs the authoritative HTTP measurement (reliable TLS via Node
+fetch) and passes it here; this script drives a smolagents agent on the selected
+local model to produce the natural-language health assessment. The agent's
+`send_request` tool returns the already-measured result, so there is exactly one
+network call (the worker's) and the measured status stays the source of truth.
+
+smolagents/rich writes its console UI to stdout, so we redirect stdout to stderr
+during the agent run and only emit our JSON result on stdout.
+
+See docs/plans/smolagents-local-worker-http-probe.md.
+"""
+import contextlib
+import json
+import sys
+
+
+def describe(measurement, category, error):
+    if not measurement or error:
+        return f"The request did not get a response ({category}): {error or 'unknown error'}."
+    return (
+        f"HTTP {measurement.get('status')} {measurement.get('statusText', '')} "
+        f"({category}) in {measurement.get('latencyMs')} ms. "
+        f"Body preview: {str(measurement.get('bodySnippet', ''))[:400]}"
+    )
+
+
+def run_agent_summary(cfg):
+    """Returns (summary, error). Never raises."""
+    try:
+        from smolagents import CodeAgent, OpenAIServerModel, tool
+    except Exception as e:  # noqa: BLE001
+        return "", f"smolagents not installed ({e})"
+
+    request = cfg.get("request") or {}
+    method = (request.get("method") or "GET").upper()
+    url = request.get("url") or ""
+    measurement = cfg.get("measurement")
+    category = cfg.get("category") or ""
+    error = cfg.get("error")
+    measured_text = describe(measurement, category, error)
+
+    @tool
+    def send_request() -> str:
+        """Send the configured HTTP request to the target endpoint and return its
+        status code and a short body preview."""
+        return measured_text
+
+    try:
+        model = OpenAIServerModel(
+            model_id=cfg.get("agentModelId") or "",
+            api_base=cfg.get("agentBaseURL") or "",
+            api_key=cfg.get("agentApiKey") or "local",
+        )
+        agent = CodeAgent(tools=[send_request], model=model, max_steps=4)
+        task = (
+            f"Use send_request to call {method} {url}. Then report the HTTP status "
+            "code, classify it (2xx success, 3xx redirect, 4xx client error, 5xx "
+            "server error, or network failure), and give a one-sentence health "
+            "assessment of the endpoint."
+        )
+        # smolagents/rich logs to stdout; keep stdout clean for our JSON result.
+        with contextlib.redirect_stdout(sys.stderr):
+            summary = str(agent.run(task)).strip()
+        return summary, None
+    except Exception as e:  # noqa: BLE001
+        return "", f"agent run failed ({e})"
+
+
+def main():
+    try:
+        cfg = json.load(sys.stdin)
+    except Exception as e:  # noqa: BLE001
+        json.dump({"agentSummary": "", "error": f"invalid input: {e}"}, sys.stdout)
+        return
+    summary, agent_error = run_agent_summary(cfg)
+    json.dump({"agentSummary": summary, "error": agent_error}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/gonext_transcribe.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Voice transcription for the GoNext local worker (Audio support, task #21).
+
+Reads a JSON job on stdin: {"audioPath": str, "model": str, "language": str?}.
+Transcribes with mlx-whisper and prints {"text": "..."} on stdout.
+
+Design notes:
+- The browser sends a 16 kHz mono 16-bit PCM WAV, so we decode it with the
+  stdlib `wave` module + numpy and hand mlx-whisper a float32 array. Passing an
+  array (not a file path) skips mlx-whisper's ffmpeg-based loader, so NO ffmpeg
+  install is required on the worker.
+- The model is resolved by HF repo id ("mlx-community/<model>") from the HF hub
+  cache (~/.cache/huggingface/hub, honoring HF_HOME/HF_HUB_CACHE). This is the
+  same location the wizard installs to and the readiness probe checks.
+- On failure we exit non-zero and print a machine-parseable reason token as the
+  first stderr line: "lib-missing" | "model-missing" | "audio-error" | "error".
+"""
+
+import json
+import sys
+import wave
+
+
+TARGET_SR = 16000
+
+
+def fail(reason: str, detail: str = "") -> None:
+    sys.stderr.write(reason + "\n")
+    if detail:
+        sys.stderr.write(detail + "\n")
+    sys.exit(1)
+
+
+def load_wav_mono_16k(path: str):
+    """Decode a PCM WAV to a float32 mono array at 16 kHz without ffmpeg."""
+    import numpy as np
+
+    with wave.open(path, "rb") as w:
+        n_channels = w.getnchannels()
+        sampwidth = w.getsampwidth()
+        framerate = w.getframerate()
+        n_frames = w.getnframes()
+        raw = w.readframes(n_frames)
+
+    if sampwidth == 2:
+        audio = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+    elif sampwidth == 4:
+        audio = np.frombuffer(raw, dtype=np.int32).astype(np.float32) / 2147483648.0
+    elif sampwidth == 1:
+        audio = (np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 128.0) / 128.0
+    else:
+        raise ValueError(f"unsupported WAV sample width: {sampwidth} bytes")
+
+    if n_channels > 1:
+        audio = audio.reshape(-1, n_channels).mean(axis=1)
+
+    if framerate != TARGET_SR and audio.size > 0:
+        # Linear resample; the browser already sends 16 kHz so this is a safety net.
+        duration = audio.size / float(framerate)
+        target_len = int(round(duration * TARGET_SR))
+        if target_len > 0:
+            src_x = np.linspace(0.0, 1.0, num=audio.size, endpoint=False)
+            dst_x = np.linspace(0.0, 1.0, num=target_len, endpoint=False)
+            audio = np.interp(dst_x, src_x, audio).astype(np.float32)
+
+    return np.ascontiguousarray(audio, dtype=np.float32)
+
+
+def main() -> None:
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except Exception as e:  # noqa: BLE001
+        fail("error", f"invalid job json: {e}")
+        return
+
+    audio_path = str(payload.get("audioPath") or "").strip()
+    model = str(payload.get("model") or "whisper-large-v3-turbo").strip()
+    language = str(payload.get("language") or "").strip() or None
+    if not audio_path:
+        fail("error", "missing audioPath")
+        return
+
+    try:
+        import mlx_whisper  # noqa: F401
+    except Exception as e:  # noqa: BLE001
+        fail("lib-missing", str(e))
+        return
+
+    try:
+        audio = load_wav_mono_16k(audio_path)
+    except Exception as e:  # noqa: BLE001
+        fail("audio-error", str(e))
+        return
+
+    repo = f"mlx-community/{model}"
+    try:
+        result = mlx_whisper.transcribe(
+            audio,
+            path_or_hf_repo=repo,
+            task="transcribe",
+            language=language,
+        )
+    except Exception as e:  # noqa: BLE001
+        msg = str(e).lower()
+        if any(
+            token in msg
+            for token in (
+                "not found",
+                "repository",
+                "couldn't find",
+                "could not find",
+                "no such file",
+                "connection",
+                "offline",
+                "resolve",
+                "404",
+            )
+        ):
+            fail("model-missing", str(e))
+        else:
+            fail("error", str(e))
+        return
+
+    text = str(result.get("text", "")).strip() if isinstance(result, dict) else ""
+    sys.stdout.write(json.dumps({"text": text}))
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()