Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
test: prompt enhancer check script for macOS, Linux and 8 GB cards
Gabriele Lozuponed09ddca2b226
diff --git a/scripts/dev/enhancer-check.py b/scripts/dev/enhancer-check.pynew file mode 100644index 0000000..8149dc2--- /dev/null+++ b/scripts/dev/enhancer-check.py@@ -0,0 +1,496 @@+"""Prompt enhancer check on this computer (macOS, Linux, Windows). Standard library only, Python 3.9+.++Talks to Kokon's local API. Checks that the engine is Kokon's own (kokon-...) with text+generation, then runs text-to-image and an edit with the enhancer off and on (same seed) and+records the time the enhancer adds, its tokens/s and the peak memory.++Normal mode, against the running Kokon app (open Kokon first; jobs land in the gallery with+client "enhancer-check", so the records can be checked in the app afterwards):++ python3 scripts/dev/enhancer-check.py++8 GB card emulated on a bigger NVIDIA card (Windows; close Kokon first). Starts its own service+with a copy of your config (isolated data folder, free ports, 8gb preset) and holds the VRAM a+real 8 GB card does not have with vram-ballast.py:++ cargo build -p qls-service+ python scripts\\dev\\enhancer-check.py --card-mib 8188++Fallback check (engine without the prompt enhancer, e.g. an official sd-server started by hand+on Kokon's port before opening Kokon): a job with enhance on must still finish, with a note:++ python3 scripts/dev/enhancer-check.py --expect-no-enhancer++Results: <Desktop or home>/kokon-enhancer-check/<timestamp>/ (report.md, results.json, the+images are in Kokon's gallery). Paste report.md back in the chat.++Start Kokon from branch prompt-enhancer first:+ Mac: git pull && bash scripts/dev/mac-dev.sh+ Linux: git pull, then the quick run in docs/linux.md (npm run build && cargo build ...)++In the app, by hand, after the script:+ 1. At first start the engine update is offered (What's New / Setup): accept it before the script.+ 2. The Enhance pill is visible in the composer (text-to-image and edit).+ 3. Enhance on, a short prompt in Italian: the job card shows the prompt being written live.+ 4. The record (also the script's "enhancer-check" images) shows your prompt and the expanded one.+ 5. --expect-no-enhancer run only: the Enhance pill is hidden.+"""++import argparse+import datetime as dt+import json+import os+import platform+import re+import shutil+import socket+import subprocess+import sys+import threading+import time+import urllib.error+import urllib.request+from pathlib import Path++ROOT = Path(__file__).resolve().parents[2]+WANT_ENGINE = "kokon-992-dfaab76"+CLIENT = "enhancer-check"+T2I_PROMPT = "un gatto rosso che dorme su un davanzale, foto"+EDIT_PROMPT = "rendi il gatto nero e aggiungi un vaso di basilico accanto"+++# ---------------------------------------------------------------------------------------+# Kokon folders (same rules as crates/qls-core/src/config.rs)+# ---------------------------------------------------------------------------------------++def data_dir():+ if os.environ.get("QLS_DATA_DIR"):+ return Path(os.environ["QLS_DATA_DIR"])+ home = Path.home()+ if sys.platform == "win32":+ return Path(os.environ["LOCALAPPDATA"]) / "KokonData"+ if sys.platform == "darwin":+ return home / "Library" / "Application Support" / "KokonData"+ return Path(os.environ.get("XDG_DATA_HOME") or home / ".local" / "share") / "KokonData"+++def config_dir():+ if os.environ.get("QLS_CONFIG_DIR"):+ return Path(os.environ["QLS_CONFIG_DIR"])+ home = Path.home()+ if sys.platform == "win32":+ return Path(os.environ["APPDATA"]) / "Kokon"+ if sys.platform == "darwin":+ return home / "Library" / "Application Support" / "Kokon"+ return Path(os.environ.get("XDG_CONFIG_HOME") or home / ".config") / "Kokon"+++def free_port():+ with socket.socket() as s:+ s.bind(("127.0.0.1", 0))+ return s.getsockname()[1]+++# ---------------------------------------------------------------------------------------+# API+# ---------------------------------------------------------------------------------------++class Api:+ def __init__(self, port, token):+ self.base = "http://127.0.0.1:%d/api/v1" % port+ self.token = token++ def call(self, method, path, body=None, timeout=60):+ data = json.dumps(body).encode() if body is not None else None+ req = urllib.request.Request(self.base + path, data=data, method=method)+ req.add_header("Authorization", "Bearer " + self.token)+ if data is not None:+ req.add_header("Content-Type", "application/json")+ try:+ with urllib.request.urlopen(req, timeout=timeout) as r:+ return json.loads(r.read() or b"null")+ except urllib.error.HTTPError as e:+ raise RuntimeError("%s %s -> %s: %s" % (method, path, e.code, e.read().decode(errors="replace")[:600]))++ def get(self, path, timeout=60):+ return self.call("GET", path, timeout=timeout)++ def post(self, path, body=None, timeout=60):+ return self.call("POST", path, {} if body is None else body, timeout=timeout)+++def connect(ddir, wait_s=0):+ info_path = ddir / "service.json"+ deadline = time.time() + wait_s+ while True:+ try:+ info = json.loads(info_path.read_text(encoding="utf-8-sig"))+ api = Api(info["port"], info["token"])+ api.get("/status", timeout=5)+ return api+ except Exception as e:+ if time.time() >= deadline:+ raise SystemExit("Kokon's service is not reachable (%s: %s). Open Kokon first." % (info_path, e))+ time.sleep(0.5)+++# ---------------------------------------------------------------------------------------+# Memory sampler: whole GPU (nvidia-smi) and sd-server's process footprint (macOS) / RSS+# ---------------------------------------------------------------------------------------++def nvidia_used_mib():+ try:+ out = subprocess.run(["nvidia-smi", "--query-gpu=memory.used", "--format=csv,noheader,nounits"],+ capture_output=True, text=True, timeout=5).stdout+ return int(out.strip().splitlines()[0])+ except Exception:+ return None+++def process_mib(pid):+ if not pid or sys.platform == "win32":+ return None+ if sys.platform == "darwin" and shutil.which("footprint"):+ # phys_footprint counts Metal (unified) allocations too, unlike RSS.+ try:+ out = subprocess.run(["footprint", "-p", str(pid)], capture_output=True, text=True, timeout=10).stdout+ m = re.search(r"Footprint:\s*([\d.]+)\s*(KB|MB|GB)", out)+ if m:+ return float(m.group(1)) * {"KB": 1 / 1024, "MB": 1, "GB": 1024}[m.group(2)]+ except Exception:+ pass+ try:+ out = subprocess.run(["ps", "-o", "rss=", "-p", str(pid)], capture_output=True, text=True, timeout=5).stdout+ return int(out.strip()) / 1024+ except Exception:+ return None+++class Sampler:+ def __init__(self, pid_fn):+ self.pid_fn = pid_fn+ self.has_gpu = nvidia_used_mib() is not None+ self.lock = threading.Lock()+ self.gpu_peak = None+ self.proc_peak = None+ self.stop = False+ threading.Thread(target=self.run, daemon=True).start()++ def run(self):+ while not self.stop:+ g = nvidia_used_mib() if self.has_gpu else None+ p = process_mib(self.pid_fn())+ with self.lock:+ if g is not None:+ self.gpu_peak = max(self.gpu_peak or 0, g)+ if p is not None:+ self.proc_peak = max(self.proc_peak or 0, p)+ time.sleep(0.5)++ def reset(self):+ with self.lock:+ self.gpu_peak = nvidia_used_mib() if self.has_gpu else None+ self.proc_peak = None++ def peaks(self):+ with self.lock:+ return self.gpu_peak, self.proc_peak+++# ---------------------------------------------------------------------------------------+# Jobs+# ---------------------------------------------------------------------------------------++class LogReader:+ """New lines of the service log since the last call."""++ def __init__(self, path):+ self.path = path+ self.pos = path.stat().st_size if path.exists() else 0++ def new_lines(self):+ if not self.path.exists():+ return []+ with open(self.path, "rb") as f:+ f.seek(self.pos)+ data = f.read()+ self.pos += len(data)+ return data.decode(errors="replace").splitlines()+++def run_job(api, sampler, log, name, request, timeout_s):+ print(" %-22s ..." % name, end="", flush=True)+ log.new_lines()+ sampler.reset()+ t0 = time.time()+ job = api.post("/jobs", dict(request, client=CLIENT))+ partials = set()+ statuses = []+ while not job["status"] in ("done", "failed", "cancelled"):+ if time.time() - t0 > timeout_s:+ api.post("/jobs/%s/cancel" % job["id"])+ raise SystemExit("\n%s took more than %d s; cancelled." % (name, timeout_s))+ time.sleep(0.15)+ job = api.get("/jobs/" + job["id"])+ if not statuses or statuses[-1] != job["status"]:+ statuses.append(job["status"])+ if job["status"] == "enhancing_prompt" and job.get("enhanced_prompt"):+ partials.add(len(job["enhanced_prompt"]))+ wall = time.time() - t0+ gpu, proc = sampler.peaks()+ enh = None+ for line in log.new_lines():+ m = re.search(r"prompt enhancer: (\d+) tokens in ([\d.]+) s", line)+ if m:+ enh = (int(m.group(1)), float(m.group(2)))+ rec = job["results"][0] if job.get("results") else None+ r = {+ "name": name,+ "status": job["status"],+ "wall_s": round(wall, 1),+ "duration_s": round(rec["duration_ms"] / 1000, 1) if rec else None,+ "enhancer_tokens": enh[0] if enh else None,+ "enhancer_s": enh[1] if enh else None,+ "live_updates": len(partials),+ "statuses": statuses,+ "gpu_peak_mib": gpu,+ "proc_peak_mib": round(proc) if proc else None,+ "notes": job.get("notes") or [],+ "error": job.get("error"),+ "record_id": rec["id"] if rec else None,+ "record_prompt": rec["prompt"] if rec else None,+ "record_original_prompt": rec.get("original_prompt") if rec else None,+ "job_enhanced_prompt": job.get("enhanced_prompt"),+ "size": "%dx%d" % (rec["width"], rec["height"]) if rec else None,+ }+ extra = " enhancer %d tok / %.1f s" % enh if enh else ""+ print(" %s in %.1f s%s" % (job["status"], wall, extra))+ if job["status"] != "done":+ print(" error: %s" % json.dumps(job.get("error"))[:600])+ return r+++# ---------------------------------------------------------------------------------------+# Isolated service for the 8 GB emulation+# ---------------------------------------------------------------------------------------++def any_sd_server_running():+ if sys.platform == "win32":+ out = subprocess.run(["tasklist", "/fi", "imagename eq sd-server.exe", "/fo", "csv", "/nh"], capture_output=True, text=True).stdout+ return "sd-server.exe" in out+ return subprocess.run(["pgrep", "-x", "sd-server"], capture_output=True).returncode == 0+++def start_isolated(card_mib, out):+ if any_sd_server_running():+ raise SystemExit("sd-server is running. Close Kokon (and any sd-server) first: the GPU must be free.")+ exe = ROOT / "target" / "debug" / ("kokon-service.exe" if sys.platform == "win32" else "kokon-service")+ if not exe.exists():+ raise SystemExit("Build the service first: cargo build -p qls-service")+ real = json.loads((config_dir() / "config.json").read_text(encoding="utf-8-sig"))+ iso = out / "isolated"+ cdir, ddir, odir = iso / "config", iso / "data", iso / "output"+ for d in (cdir, ddir, odir):+ d.mkdir(parents=True, exist_ok=True)+ svc_port, srv_port = free_port(), free_port()+ cfg = dict(real)+ cfg.update({"servicePort": svc_port, "serverPort": srv_port, "outputDir": str(odir),+ "hardwarePreset": "8gb", "vramOverrideMib": card_mib, "setupComplete": True})+ cfg.setdefault("sdcppDir", str(data_dir() / "sdcpp"))+ (cdir / "config.json").write_text(json.dumps(cfg, indent=2), encoding="utf-8")+ sdcpp = cfg["sdcppDir"]++ procs = []+ blog = open(iso / "ballast.log", "w")+ ballast = subprocess.Popen([sys.executable, "-I", str(ROOT / "scripts" / "dev" / "vram-ballast.py"), "--card-mib", str(card_mib), "--sdcpp", sdcpp],+ stdout=blog, stderr=subprocess.STDOUT)+ procs.append(ballast)+ for _ in range(80):+ time.sleep(0.25)+ if "Holding" in (iso / "ballast.log").read_text(errors="replace") or ballast.poll() is not None:+ break+ if ballast.poll() is not None or "Holding" not in (iso / "ballast.log").read_text(errors="replace"):+ raise SystemExit("VRAM ballast failed:\n" + (iso / "ballast.log").read_text(errors="replace"))+ print((iso / "ballast.log").read_text(errors="replace").splitlines()[0])++ env = dict(os.environ, QLS_DATA_DIR=str(ddir), QLS_CONFIG_DIR=str(cdir))+ svc = subprocess.Popen([str(exe), "--port", str(svc_port), "--persistent"], env=env,+ stdout=open(iso / "service.out", "w"), stderr=subprocess.STDOUT)+ procs.append(svc)+ os.environ["QLS_DATA_DIR"] = str(ddir)+ return procs, ddir+++# ---------------------------------------------------------------------------------------+# Main+# ---------------------------------------------------------------------------------------++def system_info():+ info = {"platform": platform.platform(), "machine": platform.machine(), "python": platform.python_version()}+ if shutil.which("nvidia-smi"):+ info["gpu"] = subprocess.run(["nvidia-smi", "--query-gpu=name,memory.total,driver_version", "--format=csv,noheader"],+ capture_output=True, text=True).stdout.strip()+ if sys.platform == "darwin":+ info["cpu"] = subprocess.run(["sysctl", "-n", "machdep.cpu.brand_string"], capture_output=True, text=True).stdout.strip()+ info["memory_gb"] = int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True).stdout) // 2**30+ elif sys.platform.startswith("linux"):+ try:+ kb = int(re.search(r"MemTotal:\s+(\d+)", Path("/proc/meminfo").read_text()).group(1))+ info["memory_gb"] = round(kb / 2**20)+ except Exception:+ pass+ return info+++def engine_markers(sdcpp):+ found = []+ for p in Path(sdcpp).glob("**/kokon-engine.txt"):+ if "models" not in p.parts:+ found.append("%s: %s" % (p.parent.name, p.read_text().strip()))+ return found+++def main():+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("--card-mib", type=int, help="emulate a card with this much VRAM (8 GB: 8188); NVIDIA, Kokon closed")+ ap.add_argument("--expect-no-enhancer", action="store_true", help="fallback check on an engine without text generation")+ ap.add_argument("--quality", default="fast", choices=["fast", "balanced", "quality"])+ ap.add_argument("--timeout", type=int, default=1800, help="seconds per job (Macs are slow)")+ ap.add_argument("--out", help="results folder (default: Desktop or home / kokon-enhancer-check / <timestamp>)")+ a = ap.parse_args()++ stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")+ base = Path(a.out) if a.out else ((Path.home() / "Desktop") if (Path.home() / "Desktop").is_dir() else Path.home()) / "kokon-enhancer-check"+ out = base / stamp+ out.mkdir(parents=True, exist_ok=False)+ print("Results: %s" % out)++ procs = []+ try:+ if a.card_mib:+ procs, ddir = start_isolated(a.card_mib, out)+ api = connect(ddir, wait_s=30)+ else:+ ddir = data_dir()+ api = connect(ddir)+ checks = []++ def check(name, ok, detail=""):+ checks.append((name, bool(ok), detail))+ print(" [%s] %s %s" % ("PASS" if ok else "FAIL", name, detail))++ cfg = api.get("/config")+ sdcpp = cfg.get("sdcppDir") or cfg.get("sdcpp_dir") or str(ddir / "sdcpp")+ st = api.get("/status")+ print("\n1. Engine")+ release = st["engine"]["release"]+ markers = engine_markers(sdcpp)+ if st["engine"]["update_needed"]:+ check("engine installed = %s" % release, False, "update needed: open Kokon, accept the engine update (What's New / Setup), run again")+ raise SystemExit(1)+ check("app wants %s" % WANT_ENGINE, release == WANT_ENGINE, "(app: %s)" % release)+ check("engine folder marked %s" % WANT_ENGINE, any(WANT_ENGINE in m for m in markers), "; ".join(markers) or "no marker found")++ print("\n2. Inference server (first start loads the models: minutes on a Mac)")+ t0 = time.time()+ api.post("/backend/start", timeout=1800)+ st = api.get("/status")+ srv = st["server"]+ print(" ready in %.0f s, model %s, port %s" % (time.time() - t0, srv.get("model"), srv.get("port")))+ tg = srv.get("text_generation")+ if a.expect_no_enhancer:+ check("status.server.text_generation is false", tg is False, "(%r)" % tg)+ else:+ check("status.server.text_generation is true", tg is True, "(%r)" % tg)+ if tg is not True:+ raise SystemExit(1)++ sampler = Sampler(lambda: (api.get("/status").get("server") or {}).get("pid"))+ log = LogReader(ddir / "logs" / "service.log")+ q = a.quality+ t2i = {"prompt": T2I_PROMPT, "mode": "generate", "quality": q, "aspect_ratio": "1:1"}+ results = []++ print("\n3. Jobs (quality %s)" % q)+ if a.expect_no_enhancer:+ r = run_job(api, sampler, log, "t2i enhance=on", dict(t2i, seed=102, enhance=True), a.timeout)+ results.append(r)+ check("job finished", r["status"] == "done", r["status"])+ check("note says the engine has no enhancer", any("no prompt enhancer" in n for n in r["notes"]), "; ".join(r["notes"]))+ check("record keeps the user's prompt, no original_prompt", r["record_prompt"] == T2I_PROMPT and not r["record_original_prompt"])+ else:+ results.append(run_job(api, sampler, log, "warm-up (not counted)", dict(t2i, seed=100), a.timeout))+ results.append(run_job(api, sampler, log, "t2i enhance first use", dict(t2i, seed=101, enhance=True), a.timeout))+ off = run_job(api, sampler, log, "t2i off", dict(t2i, seed=102), a.timeout)+ on = run_job(api, sampler, log, "t2i on", dict(t2i, seed=102, enhance=True), a.timeout)+ results += [off, on]+ src = "gen:%s" % off["record_id"]+ edit = {"prompt": EDIT_PROMPT, "mode": "edit", "quality": q, "images": [src]}+ eoff = run_job(api, sampler, log, "edit off", dict(edit, seed=7), a.timeout)+ eon = run_job(api, sampler, log, "edit on", dict(edit, seed=7, enhance=True), a.timeout)+ results += [eoff, eon]++ print("\n4. Checks")+ for r in results:+ check("%s finished" % r["name"], r["status"] == "done", r["status"])+ for r in (results[1], on, eon):+ n = r["name"]+ check("%s: enhancing_prompt stage seen" % n, "enhancing_prompt" in r["statuses"], "->".join(r["statuses"]))+ check("%s: live text (>= 3 partial updates)" % n, r["live_updates"] >= 3, "%d updates" % r["live_updates"])+ check("%s: record has original + expanded prompt" % n,+ r["record_original_prompt"] == (EDIT_PROMPT if n.startswith("edit") else T2I_PROMPT)+ and r["record_prompt"] and r["record_prompt"] != r["record_original_prompt"])+ check("%s: no enhancer failure note" % n, not any("enhancer" in x for x in r["notes"]), "; ".join(r["notes"]))+ for r in (off, eoff):+ check("%s: no original_prompt (enhancer off)" % r["name"], not r["record_original_prompt"])++ (out / "results.json").write_text(json.dumps({"system": system_info(), "engine": release, "markers": markers,+ "status_server": srv, "checks": checks, "jobs": results}, indent=2), encoding="utf-8")+ write_report(out, a, system_info(), release, markers, srv, checks, results)+ failed = [c for c in checks if not c[1]]+ print("\n%d checks, %d failed. Report: %s" % (len(checks), len(failed), out / "report.md"))+ sampler.stop = True+ finally:+ for p in reversed(procs):+ if p.poll() is None:+ p.kill()+ if procs:+ # The isolated service's sd-server outlives the service when killed: stop it too.+ if sys.platform == "win32":+ subprocess.run(["taskkill", "/f", "/im", "sd-server.exe"], capture_output=True)+ else:+ subprocess.run(["pkill", "-x", "sd-server"], capture_output=True)+++def write_report(out, a, sysinfo, release, markers, srv, checks, results):+ L = ["# Prompt enhancer check %s" % out.name, ""]+ L += ["- System: %s" % ", ".join("%s %s" % (k, v) for k, v in sysinfo.items())]+ if a.card_mib:+ L += ["- Emulated card: %d MiB (VRAM ballast + 8gb preset, isolated service)" % a.card_mib]+ L += ["- Engine: %s; markers: %s" % (release, "; ".join(markers) or "none"),+ "- Server: model %s, text_generation %s" % (srv.get("model"), srv.get("text_generation")),+ "- Quality: %s" % a.quality, ""]+ L += ["## Checks", ""] + ["- %s %s %s" % ("PASS" if ok else "**FAIL**", n, d) for n, ok, d in checks] + [""]+ L += ["## Jobs", "",+ "| Job | Status | Wall s | Image s | Enhancer tok | Enhancer s | tok/s | Live updates | Peak GPU MiB (whole GPU) | Peak sd-server MiB | Size |",+ "|---|---|---|---|---|---|---|---|---|---|---|"]+ for r in results:+ tps = "%.0f" % (r["enhancer_tokens"] / r["enhancer_s"]) if r["enhancer_s"] else ""+ L.append("| %s | %s | %s | %s | %s | %s | %s | %s | %s | %s | %s |" % (+ r["name"], r["status"], r["wall_s"], r["duration_s"] or "", r["enhancer_tokens"] or "", r["enhancer_s"] or "",+ tps, r["live_updates"], r["gpu_peak_mib"] or "", r["proc_peak_mib"] or "", r["size"] or ""))+ by = {r["name"]: r for r in results}+ if "t2i on" in by:+ L += ["", "Added by the enhancer (same seed, wall time): text-to-image %+.1f s, edit %+.1f s." % (+ by["t2i on"]["wall_s"] - by["t2i off"]["wall_s"], by["edit on"]["wall_s"] - by["edit off"]["wall_s"])]+ L += ["", "## Prompts", ""]+ for r in results:+ if r["record_original_prompt"] or r["job_enhanced_prompt"]:+ L += ["**%s**" % r["name"], "", "- user: %s" % r["record_original_prompt"], "- sent to the model: %s" % r["record_prompt"], ""]+ if r["notes"]:+ L += ["- notes (%s): %s" % (r["name"], "; ".join(r["notes"])), ""]+ (out / "report.md").write_text("\n".join(L) + "\n", encoding="utf-8")+++if __name__ == "__main__":+ main()