@youweichen/pi-harness 1.0.0 → 1.2.0

package/dist/server/document-conversion/python/native_code.py

@@ -0,0 +1,149 @@
+"""Recover visible PDF code spacing only when native glyphs prove a fixed grid.
+
+PDF text APIs can collapse explicit spaces. We retain native Unicode characters
+and reconstruct their visible columns from glyph origins, never from code syntax.
+Ambiguous geometry remains unchanged and is reported for review.
+"""
+import ctypes
+import re
+
+
+_SIGNATURE = re.compile(r"^\s*(?:(?:async\s+)?def\s+[A-Za-z_]\w*\s*\(|(?:export\s+)?(?:async\s+)?function(?:\s+[A-Za-z_$][\w$]*)?\s*\(|(?:public\s+|private\s+|static\s+)*(?:void|int|bool|float|double|char|long)\s+[A-Za-z_]\w*\s*\()")
+
+
+def _compact(value):
+	return re.sub(r"\s+", "", value)
+
+
+def _native_region(page, textpage, bbox):
+	import pypdfium2 as pdfium
+	if page.get_rotation() != 0:
+		raise ValueError("rotated page")
+	if textpage.count_chars() > 100_000:
+		raise ValueError("native page exceeds the character inspection limit")
+	bounds = bbox.to_bottom_left_origin(page.get_height())
+	chars, pitches, font_heights = [], [], []
+	font_cache = {}
+	for index in range(textpage.count_chars()):
+		codepoint = pdfium.raw.FPDFText_GetUnicode(textpage.raw, index)
+		if codepoint in (10, 13):
+			continue
+		x, y = ctypes.c_double(), ctypes.c_double()
+		if not pdfium.raw.FPDFText_GetCharOrigin(textpage.raw, index, ctypes.byref(x), ctypes.byref(y)):
+			continue
+		left, bottom, right, top = textpage.get_charbox(index)
+		if not (bounds.l - 0.25 <= (left + right) / 2 <= bounds.r + 0.25 and bounds.b - 0.25 <= y.value <= bounds.t + 0.25):
+			continue
+		if pdfium.raw.FPDFText_IsGenerated(textpage.raw, index):
+			if codepoint == 32:
+				continue
+			raise ValueError("generated non-whitespace character")
+		if codepoint < 32 or codepoint > 0x10ffff or 0xd800 <= codepoint <= 0xdfff or pdfium.raw.FPDFText_HasUnicodeMapError(textpage.raw, index):
+			raise ValueError("unmapped or control character")
+		obj = textpage.get_textobj(index)
+		if obj is None:
+			raise ValueError("character has no native text object")
+		matrix = obj.get_matrix()
+		if abs(matrix.b) > 1e-5 or abs(matrix.c) > 1e-5 or matrix.a <= 0 or matrix.d <= 0 or abs(pdfium.raw.FPDFText_GetCharAngle(textpage.raw, index)) > 1e-5:
+			raise ValueError("rotated or skewed text")
+		if pdfium.raw.FPDFTextObj_GetTextRenderMode(obj.raw) in (3, 7):
+			raise ValueError("invisible text layer")
+		font, size = obj.get_font(), obj.get_font_size()
+		font_key = (ctypes.cast(font.raw, ctypes.c_void_p).value, size, matrix.a)
+		def width(character):
+			value = ctypes.c_float()
+			if not pdfium.raw.FPDFFont_GetGlyphWidth(font.raw, ord(character), size, ctypes.byref(value)):
+				raise ValueError("unavailable glyph advance")
+			return value.value * matrix.a
+		if font_key not in font_cache:
+			advances = [width(character) for character in " iMW0"]
+			if min(advances) <= 0 or max(advances) - min(advances) > max(0.01, advances[0] * 0.002):
+				raise ValueError("proportional font")
+			font_cache[font_key] = advances[0]
+		pitch = font_cache[font_key]
+		advance = width(chr(codepoint))
+		cells = round(advance / pitch)
+		if cells not in (1, 2) or abs(advance / pitch - cells) > 0.02:
+			raise ValueError("character advance is not an integral grid width")
+		chars.append({"index": index, "character": chr(codepoint), "x": x.value, "y": y.value, "cells": cells})
+		pitches.append(pitch)
+		font_heights.append(size * matrix.d)
+	if not chars:
+		raise ValueError("no visible native text in this region")
+	pitch = sum(pitches) / len(pitches)
+	if max(pitches) - min(pitches) > max(0.01, pitch * 0.002):
+		raise ValueError("mixed glyph advances")
+	rows = []
+	for char in sorted(chars, key=lambda value: (-value["y"], value["x"])):
+		if not rows or abs(rows[-1][0]["y"] - char["y"]) > 0.15:
+			rows.append([])
+		rows[-1].append(char)
+	gaps = [rows[i][0]["y"] - rows[i + 1][0]["y"] for i in range(len(rows) - 1)]
+	line_advance = min(gaps) if gaps else None
+	gap_cells = []
+	if line_advance is not None:
+		if line_advance < pitch or line_advance > 2 * min(font_heights):
+			raise ValueError("baseline spacing cannot establish a continuous line grid")
+		for gap in gaps:
+			cells = round(gap / line_advance)
+			if cells < 1 or cells > 8 or abs(gap / line_advance - cells) > 0.025:
+				raise ValueError("non-integral baseline gaps may contain significant blank lines")
+			gap_cells.append(cells)
+	origin = min(char["x"] for char in chars)
+	lines = []
+	for row_index, row in enumerate(rows):
+		if row_index:
+			# Empty rows preserve measured visual gaps, without interpreting syntax.
+			lines.extend([""] * (gap_cells[row_index - 1] - 1))
+		line, cursor = "", 0
+		for char in sorted(row, key=lambda value: value["x"]):
+			column = (char["x"] - origin) / pitch
+			cell = round(column)
+			if cell < cursor or cell > 2000 or abs(column - cell) > 0.025:
+				raise ValueError("overlapping or non-integral character positions")
+			line += " " * (cell - cursor) + char["character"]
+			cursor = cell + char["cells"]
+		lines.append(line.rstrip())
+	return "\n".join(lines), {"advance": pitch, "lineAdvance": line_advance, "rowPitch": line_advance, "baselineGaps": gaps, "gapRows": gap_cells, "originX": origin, "baselines": [row[0]["y"] for row in rows], "characters": chars}
+
+
+def recover_native_code(document, source):
+	"""Mutate qualified Docling text/code items; return auditable recovery metadata."""
+	import pypdfium2 as pdfium
+	from docling_core.types.doc import CodeItem
+	items = [item for item, _level in document.iterate_items() if str(getattr(item, "label", "")) in ("code", "text") and (str(item.label) == "code" or _SIGNATURE.match(getattr(item, "text", "")))]
+	result = {"recovered": 0, "warnings": [], "needs_review": False, "recoveries": []}
+	if not items:
+		return result
+	with pdfium.PdfDocument(source) as pdf:
+		for item in items:
+			try:
+				if len(item.prov) != 1:
+					raise ValueError("code spans multiple or unspecified regions")
+				prov = item.prov[0]
+				page = pdf[prov.page_no - 1]
+				try:
+					textpage = page.get_textpage()
+					try:
+						text, evidence = _native_region(page, textpage, prov.bbox)
+					finally:
+						textpage.close()
+				finally:
+					page.close()
+				if _compact(text) not in {_compact(item.text), _compact(item.orig)}:
+					raise ValueError("native characters differ from the recognized region")
+				if any(delimiter in text or delimiter in item.text for delimiter in ('"""', "'''", "`")):
+					raise ValueError("multiline string whitespace requires explicit review")
+				if str(item.label) != "code" and "\n" not in text:
+					continue
+				data = item.model_dump()
+				data.update(label="code", text=text, orig=text)
+				new_item = CodeItem(**data)
+				new_item.prov[0].charspan = (0, len(text))
+				document.replace_item(old_item=item, new_item=new_item)
+				result["recovered"] += 1
+				result["recoveries"].append({"id": new_item.self_ref, "page": prov.page_no, "bbox": prov.bbox.model_dump(mode="json"), "originalText": item.text, "text": text, **evidence})
+			except Exception as error:
+				result["needs_review"] = True
+				result["warnings"].append(f"Native code layout could not be verified for {item.self_ref}: {error}; recognized text was preserved for review.")
+	return result

package/dist/server/document-conversion/runtime.js

@@ -0,0 +1,321 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, access, writeFile, stat, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import lockfile from "proper-lockfile";
+import { killPidTree } from "../process-utils.js";
+import { documentDataDir, getDocumentSettings } from "./settings.js";
+export const DOCLING_VERSION = "2.136.0";
+export const CONVERSION_PROFILE = "docling-cpu-zh-v1";
+const ownedChildren = new Set();
+let shuttingDown = false;
+function trackChild(child) { ownedChildren.add(child); child.once("close", () => ownedChildren.delete(child)); }
+export async function shutdownDocumentRuntime() {
+    shuttingDown = true;
+    if (worker)
+        closeWorker(worker);
+    await Promise.all([...ownedChildren].map(child => new Promise(resolve => {
+        const done = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(done, 5000);
+        child.once("close", done);
+        if (child.pid)
+            killPidTree(child.pid);
+        else
+            done();
+    })));
+}
+export async function waitDocumentQueue(previous, signal) {
+    signal?.throwIfAborted();
+    if (!signal)
+        return previous;
+    await new Promise((resolve, reject) => {
+        const abort = () => reject(new DOMException("Document operation canceled", "AbortError"));
+        signal.addEventListener("abort", abort, { once: true });
+        previous.then(() => { signal.removeEventListener("abort", abort); resolve(); }, error => { signal.removeEventListener("abort", abort); reject(error); });
+    });
+}
+export function runtimeDirectory() {
+    return getDocumentSettings().runtimePath ?? join(documentDataDir(), "runtimes", CONVERSION_PROFILE);
+}
+export function runtimePython() {
+    return join(runtimeDirectory(), "venv", process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+}
+export function bridgePath() { return fileURLToPath(new URL("./python/bridge.py", import.meta.url)); }
+/** A separate process group lets cancellation remove only this conversion's children. */
+export async function runDocumentProcess(command, args, options = {}) {
+    if (shuttingDown)
+        throw new Error("Document runtime is shutting down");
+    options.signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide: true,
+            env: { ...process.env, PYTHONUNBUFFERED: "1", PYTHONUTF8: "1", ...(options.offline ? { HF_HUB_OFFLINE: "1", TRANSFORMERS_OFFLINE: "1", HF_DATASETS_OFFLINE: "1", HF_HUB_DISABLE_TELEMETRY: "1" } : {}) },
+        });
+        trackChild(child);
+        let stdout = "", stderr = "", pending = "", failure, lastProgress = 0;
+        const stop = (error) => { failure = error; if (child.pid)
+            killPidTree(child.pid); };
+        const abort = () => stop(new DOMException("Document operation canceled", "AbortError"));
+        const timer = setTimeout(() => stop(new Error("Document operation timed out")), options.timeout ?? 30 * 60_000);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (stdout.length > 4 * 1024 * 1024)
+                stop(new Error("Parser response exceeds 4 MiB"));
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString("utf8");
+            stderr = (stderr + text).slice(-32_768);
+            pending += text;
+            const lines = pending.split(/\r\n|\r|\n/);
+            pending = lines.pop() ?? "";
+            const latest = lines.map(line => line.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "").trim()).filter(Boolean).at(-1);
+            if (latest && Date.now() - lastProgress >= 400) {
+                options.onProgress?.(latest.slice(0, 1000));
+                lastProgress = Date.now();
+            }
+            if (pending.length > 2000)
+                pending = pending.slice(-2000);
+        });
+        child.on("error", error => { failure = error; });
+        child.on("close", code => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+            if (failure)
+                reject(failure);
+            else if (code !== 0)
+                reject(new Error(`Document process failed (${code}): ${stderr.trim().slice(-6000)}`));
+            else
+                resolve(stdout.trim());
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(options.input === undefined ? undefined : JSON.stringify(options.input));
+        if (options.signal?.aborted)
+            abort();
+    });
+}
+export async function doctorRuntime(options = {}) {
+    const pythonPath = runtimePython();
+    try {
+        await access(pythonPath);
+        const result = JSON.parse(await runDocumentProcess(pythonPath, [bridgePath(), "doctor", runtimeDirectory()], { ...options, timeout: 60_000, offline: true }));
+        return { ...result, pythonPath };
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        return { ready: false, pythonPath, missing: [error instanceof Error ? error.message : String(error)], warnings: [] };
+    }
+}
+let qualification;
+async function qualificationSignature(root) {
+    const receipt = await readFile(join(root, "ready.json"), "utf8");
+    const parsed = JSON.parse(receipt);
+    const assets = (await readdir(dirname(bridgePath()))).filter(name => name.endsWith(".py")).sort().map(name => join(dirname(bridgePath()), name));
+    const paths = [join(root, "ready.json"), join(root, "requirements.lock"), runtimePython(), ...assets, ...Object.keys(parsed.models ?? {}).sort().map(path => join(root, "models", path))];
+    const identities = await Promise.all(paths.map(async (path) => { const value = await stat(path); return [path, value.dev, value.ino, value.size, value.mtimeMs, value.ctimeMs]; }));
+    return JSON.stringify([receipt, identities]);
+}
+/** Explicit doctor always hashes models; conversions reuse a successful check
+ * until the receipt, dependency lock, Python executable or model files change. */
+export async function ensureRuntimeReady(options = {}) {
+    options.signal?.throwIfAborted();
+    const root = runtimeDirectory();
+    let signature;
+    try {
+        signature = await qualificationSignature(root);
+    }
+    catch { /* Doctor gives actionable missing-runtime details. */ }
+    if (signature !== undefined && qualification?.root === root && qualification.signature === signature)
+        return qualification.result;
+    const result = await doctorRuntime(options);
+    if (result.ready && signature !== undefined)
+        qualification = { root, signature, result };
+    else
+        qualification = undefined;
+    return result;
+}
+let setupPromise;
+export async function setupRuntime(options = {}) {
+    if (setupPromise)
+        throw new Error("Document runtime setup is already running");
+    setupPromise = performSetup(options);
+    try {
+        return await setupPromise;
+    }
+    finally {
+        setupPromise = undefined;
+    }
+}
+async function performSetup(options) {
+    if (process.platform === "darwin" && process.arch === "x64")
+        throw new Error("The current local Docling profile has not been qualified on Intel macOS. A separately tested runtime is required.");
+    const root = runtimeDirectory(), pythonPath = runtimePython();
+    await mkdir(root, { recursive: true });
+    const release = await lockfile.lock(root, { realpath: false, stale: 120_000, retries: 0 });
+    try {
+        const existing = await doctorRuntime(options);
+        if (existing.ready) {
+            options.onProgress?.("The isolated document runtime is already qualified");
+            return existing;
+        }
+        if (worker?.root === root)
+            closeWorker(worker);
+        try {
+            await access(pythonPath);
+        }
+        catch {
+            const configured = getDocumentSettings().pythonPath;
+            if (configured) {
+                const version = await runDocumentProcess(configured, ["-c", "import sys; print('.'.join(map(str,sys.version_info[:2])))"], options);
+                if (version !== "3.12")
+                    throw new Error(`Python 3.12 is required for this profile; found ${version}`);
+                await runDocumentProcess(configured, ["-m", "venv", join(root, "venv")], options);
+            }
+            else {
+                options.onProgress?.("Creating the isolated Python 3.12 runtime with uv");
+                try {
+                    await runDocumentProcess("uv", ["venv", "--seed", "--python", "3.12", join(root, "venv")], options);
+                }
+                catch (error) {
+                    throw new Error(`Install uv or configure an absolute Python 3.12 executable path. ${error instanceof Error ? error.message : error}`);
+                }
+            }
+        }
+        options.onProgress?.(`Installing Docling ${DOCLING_VERSION} in the isolated runtime`);
+        const lockPath = join(root, "requirements.lock");
+        // The CPU Transformers backend is already a standard dependency. The broad
+        // vlm extra additionally installs unrelated MLX/audio backends on Apple Silicon.
+        let install = [`docling[rapidocr]==${DOCLING_VERSION}`, "transformers==5.19.0", "rapidocr==3.9.1"];
+        try {
+            const locked = await readFile(lockPath, "utf8");
+            if (!locked.trim().split(/\r?\n/).every(line => /^[A-Za-z0-9_.-]+==[A-Za-z0-9_.+!-]+$/.test(line)))
+                throw new Error("Invalid document runtime dependency lock");
+            install = ["-r", lockPath];
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        try {
+            await runDocumentProcess("uv", ["pip", "install", "--python", pythonPath, "--index-url", "https://pypi.org/simple", ...install], { ...options, timeout: 45 * 60_000 });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await runDocumentProcess(pythonPath, ["-m", "pip", "install", "--index-url", "https://pypi.org/simple", ...install], { ...options, timeout: 45 * 60_000 });
+        }
+        const freeze = await runDocumentProcess(pythonPath, ["-m", "pip", "freeze"], options);
+        if (!freeze.split(/\r?\n/).every(line => /^[A-Za-z0-9_.-]+==[A-Za-z0-9_.+!-]+$/.test(line)))
+            throw new Error("Installed dependencies contain unexpected non-registry references");
+        await writeFile(lockPath, freeze + "\n");
+        options.onProgress?.("Downloading local models and verifying the offline conversion profile");
+        await runDocumentProcess(pythonPath, [bridgePath(), "setup", root], { ...options, timeout: 60 * 60_000 });
+        return doctorRuntime(options);
+    }
+    finally {
+        await release();
+    }
+}
+export async function runtimeFingerprint() {
+    return readFile(join(runtimeDirectory(), "ready.json"), "utf8");
+}
+let worker;
+let workerQueue = Promise.resolve();
+function closeWorker(active) {
+    if (active.idle)
+        clearTimeout(active.idle);
+    if (active.child.pid)
+        killPidTree(active.child.pid);
+    if (worker === active)
+        worker = undefined;
+}
+function parserWorker() {
+    if (shuttingDown)
+        throw new Error("Document runtime is shutting down");
+    const root = runtimeDirectory();
+    if (worker?.root === root) {
+        if (worker.idle)
+            clearTimeout(worker.idle);
+        return worker;
+    }
+    if (worker)
+        closeWorker(worker);
+    const child = spawn(runtimePython(), [bridgePath(), "serve", root], { stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide: true, env: { ...process.env, PYTHONUNBUFFERED: "1", PYTHONUTF8: "1", HF_HUB_OFFLINE: "1", TRANSFORMERS_OFFLINE: "1", HF_HUB_DISABLE_TELEMETRY: "1" } });
+    trackChild(child);
+    const active = { child, root, stdout: "" };
+    worker = active;
+    child.stdout.on("data", (chunk) => {
+        active.stdout += chunk.toString("utf8");
+        if (active.stdout.length > 4 * 1024 * 1024) {
+            active.pending?.reject(new Error("Parser response exceeds 4 MiB"));
+            closeWorker(active);
+            return;
+        }
+        let end;
+        while ((end = active.stdout.indexOf("\n")) >= 0) {
+            const line = active.stdout.slice(0, end);
+            active.stdout = active.stdout.slice(end + 1);
+            try {
+                const response = JSON.parse(line);
+                if (response.error)
+                    active.pending?.reject(new Error(response.error));
+                else
+                    active.pending?.resolve(response);
+            }
+            catch {
+                active.pending?.reject(new Error("Invalid parser response"));
+                closeWorker(active);
+            }
+        }
+    });
+    let errorTail = "";
+    child.stderr.on("data", (chunk) => { const text = chunk.toString("utf8"); errorTail = (errorTail + text).slice(-6000); for (const line of text.split(/\r?\n/))
+        if (line.trim())
+            active.pending?.progress?.(line.slice(0, 1000)); });
+    child.on("error", error => { active.pending?.reject(error); if (worker === active)
+        worker = undefined; });
+    child.on("close", code => { active.pending?.reject(new Error(`Document worker exited (${code}): ${errorTail}`)); if (worker === active)
+        worker = undefined; });
+    child.stdin.on("error", error => active.pending?.reject(error));
+    return active;
+}
+/** One queued local worker keeps model weights warm without parallel RAM spikes. */
+export async function runConversionWorker(input, options) {
+    const previous = workerQueue;
+    let release;
+    const gate = new Promise(done => { release = done; });
+    workerQueue = previous.then(() => gate);
+    try {
+        await waitDocumentQueue(previous, options.signal);
+        options.signal?.throwIfAborted();
+        const active = parserWorker();
+        return await new Promise((resolve, reject) => {
+            const finish = (error, response) => {
+                if (!active.pending)
+                    return;
+                active.pending = undefined;
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", abort);
+                if (error) {
+                    closeWorker(active);
+                    reject(error);
+                }
+                else {
+                    active.idle = setTimeout(() => closeWorker(active), 10_000);
+                    active.idle.unref();
+                    resolve(response);
+                }
+            };
+            const abort = () => finish(new DOMException("Document operation canceled", "AbortError"));
+            const timer = setTimeout(() => finish(new Error("Document conversion exceeded 30 minutes")), 30 * 60_000);
+            active.pending = { resolve: response => finish(undefined, response), reject: error => finish(error), progress: options.onProgress };
+            options.signal?.addEventListener("abort", abort, { once: true });
+            active.child.stdin.write(JSON.stringify(input) + "\n");
+            if (options.signal?.aborted)
+                abort();
+        });
+    }
+    finally {
+        release();
+    }
+}