@introspection-ai/recipe-documents-docx 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @introspection-ai/recipe-documents-docx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Word (`.docx`) format for the Recipes [`documents` tool](../../../docs/documents.md):
+`read`, `propose_edits`, `comment`, `respond` and `remove_section`, on paper-docx.
+`render` is not registered.
+
+```json
+{ "pi": { "documents": [{ "format": "docx" }] } }
+```
+
+The helpers in `python/` run with the Recipe's `pi.runtime.python` environment, which must
+provide `paper-docx==0.2.0`. `python/uv.lock` pins what the tests run on.
+
+Licences: the anchoring and section removal follow RedlineBench's redline engine (MIT,
+Crosby Legal), see `python/recipe_documents_docx/LICENSE-redline-bench`. The rest is Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type DocumentAdapter, type DocumentAdapterContext, type DocumentCapabilities, type DocumentCommentInput, type DocumentProposeEditsInput, type DocumentReadInput, type DocumentRemoveSectionInput, type DocumentRespondInput, type DocumentReviseInput, type DocumentResult } from "@introspection-ai/recipes/documents";
+export { pythonExecutable, runHelper } from "./python.js";
+/** The helper entry point shipped in this package. */
+export declare const DOCX_HELPER: string;
+/**
+ * What Word supports. `render` is false: page images need a layout engine
+ * (LibreOffice or Word), which the runtime image does not carry, so the
+ * command is absent for .docx rather than failing.
+ */
+export declare const DOCX_DOCUMENT_CAPABILITIES: DocumentCapabilities;
+export declare class DocxDocumentAdapter implements DocumentAdapter {
+    private readonly env;
+    private readonly script;
+    readonly format = "docx";
+    readonly extensions: readonly [".docx"];
+    readonly capabilities: DocumentCapabilities;
+    constructor(env?: NodeJS.ProcessEnv, script?: string);
+    private call;
+    read(ctx: DocumentAdapterContext, input: DocumentReadInput): Promise<DocumentResult>;
+    revise(ctx: DocumentAdapterContext, input: DocumentReviseInput): Promise<DocumentResult>;
+    proposeEdits(ctx: DocumentAdapterContext, input: DocumentProposeEditsInput): Promise<DocumentResult>;
+    comment(ctx: DocumentAdapterContext, input: DocumentCommentInput): Promise<DocumentResult>;
+    respond(ctx: DocumentAdapterContext, input: DocumentRespondInput): Promise<DocumentResult>;
+    removeSection(ctx: DocumentAdapterContext, input: DocumentRemoveSectionInput): Promise<DocumentResult>;
+}
+/**
+ * Word as a document format.
+ *
+ * ```json
+ * { "pi": { "documents": [{ "format": "docx" }] } }
+ * ```
+ *
+ * ```yaml
+ * tools: [documents]
+ * ```
+ */
+export declare const docxDocumentFormatModule: import("@introspection-ai/recipes/documents").RecipeDocumentFormatModule;
+export default docxDocumentFormatModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACpB,MAAM,qCAAqC,CAAC;AAI7C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAAsE,CAAC;AAE/F;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,oBAQxC,CAAC;AAEF,qBAAa,mBAAoB,YAAW,eAAe;IAK7C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAmC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ1F,QAAQ,CAAC,MAAM,UAAU;IACzB,QAAQ,CAAC,UAAU,YAAI,OAAO,EAAW;IACzC,QAAQ,CAAC,YAAY,uBAA8B;IAEnD,YAA6B,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAmB,MAAM,SAAc,EAAI;IAE5G,OAAO,CAAC,IAAI;IAIZ,IAAI,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,iBAAiB,2BAEzD;IAED,MAAM,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,mBAAmB,2BAE7D;IAED,YAAY,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,yBAAyB,2BAEzE;IAED,OAAO,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,oBAAoB,2BAE/D;IAED,OAAO,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,oBAAoB,2BAE/D;IAED,aAAa,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,0BAA0B,2BAE3E;CACF;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,0EAKnC,CAAC;eAEY,wBAAwB"}

package/dist/index.js

@@ -0,0 +1,71 @@
+import { fileURLToPath } from "node:url";
+import { createDocumentFormatModule, } from "@introspection-ai/recipes/documents";
+import { runHelper } from "./python.js";
+export { pythonExecutable, runHelper } from "./python.js";
+/** The helper entry point shipped in this package. */
+export const DOCX_HELPER = fileURLToPath(new URL("../python/docx_helper.py", import.meta.url));
+/**
+ * What Word supports. `render` is false: page images need a layout engine
+ * (LibreOffice or Word), which the runtime image does not carry, so the
+ * command is absent for .docx rather than failing.
+ */
+export const DOCX_DOCUMENT_CAPABILITIES = {
+    read: true,
+    revise: true,
+    proposeEdits: true,
+    comment: true,
+    respond: true,
+    removeSection: true,
+    render: false,
+};
+export class DocxDocumentAdapter {
+    env;
+    script;
+    format = "docx";
+    extensions = [".docx"];
+    capabilities = DOCX_DOCUMENT_CAPABILITIES;
+    constructor(env = process.env, script = DOCX_HELPER) {
+        this.env = env;
+        this.script = script;
+    }
+    call(ctx, command, input) {
+        return runHelper(this.script, { command, ...input }, { env: this.env, cwd: ctx.cwd, signal: ctx.signal });
+    }
+    read(ctx, input) {
+        return this.call(ctx, "read", input);
+    }
+    revise(ctx, input) {
+        return this.call(ctx, "revise", input);
+    }
+    proposeEdits(ctx, input) {
+        return this.call(ctx, "propose_edits", input);
+    }
+    comment(ctx, input) {
+        return this.call(ctx, "comment", input);
+    }
+    respond(ctx, input) {
+        return this.call(ctx, "respond", input);
+    }
+    removeSection(ctx, input) {
+        return this.call(ctx, "remove_section", input);
+    }
+}
+/**
+ * Word as a document format.
+ *
+ * ```json
+ * { "pi": { "documents": [{ "format": "docx" }] } }
+ * ```
+ *
+ * ```yaml
+ * tools: [documents]
+ * ```
+ */
+export const docxDocumentFormatModule = createDocumentFormatModule({
+    format: "docx",
+    extensions: [".docx"],
+    capabilities: DOCX_DOCUMENT_CAPABILITIES,
+    createAdapter: ({ env }) => new DocxDocumentAdapter(env),
+});
+export default docxDocumentFormatModule;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EACL,0BAA0B,GAW3B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,sDAAsD;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,0BAA0B,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAyB;IAC9D,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,YAAY,EAAE,IAAI;IAClB,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,aAAa,EAAE,IAAI;IACnB,MAAM,EAAE,KAAK;CACd,CAAC;AAEF,MAAM,OAAO,mBAAmB;IAKD,GAAG;IAAoD,MAAM;IAJjF,MAAM,GAAG,MAAM,CAAC;IAChB,UAAU,GAAG,CAAC,OAAO,CAAU,CAAC;IAChC,YAAY,GAAG,0BAA0B,CAAC;IAEnD,YAA6B,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAmB,MAAM,GAAG,WAAW;mBAA3E,GAAG;sBAAoD,MAAM;IAAiB,CAAC;IAEpG,IAAI,CAAC,GAA2B,EAAE,OAAe,EAAE,KAAa;QACtE,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5G,CAAC;IAED,IAAI,CAAC,GAA2B,EAAE,KAAwB;QACxD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,GAA2B,EAAE,KAA0B;QAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,YAAY,CAAC,GAA2B,EAAE,KAAgC;QACxE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,GAA2B,EAAE,KAA2B;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,CAAC,GAA2B,EAAE,KAA2B;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,aAAa,CAAC,GAA2B,EAAE,KAAiC;QAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;IACjE,MAAM,EAAE,MAAM;IACd,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,YAAY,EAAE,0BAA0B;IACxC,aAAa,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC;CACzD,CAAC,CAAC;AAEH,eAAe,wBAAwB,CAAC"}

package/dist/python.d.ts

@@ -0,0 +1,26 @@
+/**
+ * How the helpers run: the Recipe's own Python environment.
+ *
+ * The runtime activates `pi.runtime.python` as VIRTUAL_ENV, and that
+ * environment must provide paper-docx. A package-level Python environment
+ * is a follow-up; until then the Recipe declares the dependency.
+ * `RECIPE_DOCUMENTS_PYTHON` overrides the interpreter (tests, custom hosts).
+ */
+export declare function pythonExecutable(env?: NodeJS.ProcessEnv): string;
+export interface HelperResult {
+    text: string;
+    details?: Record<string, unknown>;
+    images?: Array<{
+        label: string;
+        data: string;
+        mimeType: string;
+    }>;
+}
+/** Run one helper request: JSON on stdin, JSON on stdout. A helper error becomes the tool call's error. */
+export declare function runHelper(script: string, request: Record<string, unknown>, options: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<HelperResult>;
+//# sourceMappingURL=python.d.ts.map

package/dist/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../src/python.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAI7E;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,2GAA2G;AAC3G,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACzF,OAAO,CAAC,YAAY,CAAC,CAmCvB"}

package/dist/python.js

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+/**
+ * How the helpers run: the Recipe's own Python environment.
+ *
+ * The runtime activates `pi.runtime.python` as VIRTUAL_ENV, and that
+ * environment must provide paper-docx. A package-level Python environment
+ * is a follow-up; until then the Recipe declares the dependency.
+ * `RECIPE_DOCUMENTS_PYTHON` overrides the interpreter (tests, custom hosts).
+ */
+export function pythonExecutable(env = process.env) {
+    if (env.RECIPE_DOCUMENTS_PYTHON)
+        return env.RECIPE_DOCUMENTS_PYTHON;
+    if (env.VIRTUAL_ENV)
+        return resolve(env.VIRTUAL_ENV, "bin", "python");
+    return "python3";
+}
+/** Run one helper request: JSON on stdin, JSON on stdout. A helper error becomes the tool call's error. */
+export function runHelper(script, request, options) {
+    const started = performance.now();
+    return new Promise((resolvePromise, reject) => {
+        const child = execFile(pythonExecutable(options.env), ["-I", script], {
+            cwd: options.cwd,
+            env: { ...options.env, PYTHONDONTWRITEBYTECODE: "1", PYTHONIOENCODING: "utf-8" },
+            timeout: options.timeoutMs ?? 300_000,
+            maxBuffer: 64 << 20,
+            signal: options.signal,
+        }, (error, stdout, stderr) => {
+            let output;
+            try {
+                output = JSON.parse(String(stdout || "null"));
+            }
+            catch {
+                output = undefined;
+            }
+            if (output && typeof output.error === "string")
+                return reject(new Error(output.error));
+            if (!output || typeof output.text !== "string") {
+                const detail = String(stderr || error?.message || "no output").slice(-600);
+                return reject(new Error(`document helper failed: ${detail}`));
+            }
+            const timing = (output.details?.timing ?? {});
+            output.details = {
+                ...output.details,
+                timing: { ...timing, call_ms: Math.round(performance.now() - started) },
+            };
+            resolvePromise(output);
+        });
+        child.stdin?.end(JSON.stringify(request));
+    });
+}
+//# sourceMappingURL=python.js.map

package/dist/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../src/python.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IACnE,IAAI,GAAG,CAAC,uBAAuB;QAAE,OAAO,GAAG,CAAC,uBAAuB,CAAC;IACpE,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtE,OAAO,SAAS,CAAC;AACnB,CAAC;AAQD,2GAA2G;AAC3G,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,OAAgC,EAChC,OAA0F;IAE1F,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE;QAC5C,MAAM,KAAK,GAAG,QAAQ,CACpB,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,EAC7B,CAAC,IAAI,EAAE,MAAM,CAAC,EACd;YACE,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,uBAAuB,EAAE,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE;YAChF,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO;YACrC,SAAS,EAAE,EAAE,IAAI,EAAE;YACnB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,MAAuD,CAAC;YAC5D,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC;YAChD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC;YACD,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;gBAAE,OAAO,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvF,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,KAAK,EAAE,OAAO,IAAI,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC3E,OAAO,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAA2B,CAAC;YACxE,MAAM,CAAC,OAAO,GAAG;gBACf,GAAG,MAAM,CAAC,OAAO;gBACjB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,EAAE;aACxE,CAAC;YACF,cAAc,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC,CACF,CAAC;QACF,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@introspection-ai/recipe-documents-docx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Word (.docx) format for the Introspection Recipes documents tool: tracked edits, comments and responses on paper-docx.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "python/*.py",
+    "python/recipe_documents_docx/*.py",
+    "python/recipe_documents_docx/LICENSE-redline-bench",
+    "python/pyproject.toml",
+    "python/uv.lock",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/introspection-org/recipes.git",
+    "directory": "packages/documents/docx"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@introspection-ai/recipes": ">=0.37.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@introspection-ai/recipes": ">=0.37.0",
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "pack:check": "pnpm pack --dry-run --json | node ../../../scripts/check-npm-pack.mjs"
+  }
 }

package/python/docx_helper.py

@@ -0,0 +1,55 @@
+"""Entry point the Node adapter runs: one JSON request on stdin, one JSON result on stdout.
+
+python -I docx_helper.py < request.json   ->   {"text": ..., "details": ...} or {"error": ...}
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+
+STARTED = time.perf_counter()
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def main() -> int:
+    try:
+        request = json.load(sys.stdin)
+        import docx
+
+        from recipe_documents_docx.ops import COMMANDS
+
+        imported = time.perf_counter()
+        opening = [0.0]
+        original_open = docx.Document
+
+        def timed_open(*args, **kwargs):
+            began = time.perf_counter()
+            try:
+                return original_open(*args, **kwargs)
+            finally:
+                opening[0] += time.perf_counter() - began
+
+        docx.Document = timed_open
+        command = COMMANDS.get(request.get("command"))
+        if command is None:
+            raise ValueError(f"the Word adapter has no command {request.get('command')!r}")
+        result = command(request)
+        result.setdefault("details", {})["timing"] = {
+            "import_ms": round((imported - STARTED) * 1000, 1),
+            "open_ms": round(opening[0] * 1000, 1),
+            "python_ms": round((time.perf_counter() - STARTED) * 1000, 1),
+        }
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+    except ModuleNotFoundError as error:
+        print(json.dumps({"error": f"This Recipe's Python has no {error.name}: the Word adapter needs paper-docx"}))
+        return 1
+    except Exception as error:  # the tool reports it as the call's error
+        print(json.dumps({"error": f"{type(error).__name__}: {error}"}))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "recipe-documents-docx"
+version = "0.1.0"
+description = "Python helpers the @introspection-ai/recipe-documents-docx adapter runs. For its tests; a Recipe brings its own environment with paper-docx."
+requires-python = ">=3.12,<3.15"
+dependencies = ["paper-docx==0.2.0"]
+
+[tool.uv]
+package = false
+constraint-dependencies = ["python-docx<0"]

package/python/recipe_documents_docx/LICENSE-redline-bench

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Crosby Legal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The benchmark dataset (the contracts, grounding documents, rubrics, and golden
+attorney redlines hosted at https://huggingface.co/datasets/crosbylegal/RedlineBench)
+is licensed separately under Creative Commons Attribution 4.0 International
+(CC-BY-4.0): https://creativecommons.org/licenses/by/4.0/

package/python/recipe_documents_docx/__init__.py

@@ -0,0 +1 @@
+"""Word helpers for the Recipes `documents` tool, on paper-docx."""

package/python/recipe_documents_docx/anchors.py

@@ -0,0 +1,186 @@
+"""Resolve a quoted anchor to one place in one paragraph, or say precisely why not.
+
+The folding table, the paragraph-scoped search and the structured failure follow RedlineBench's
+redline_engine/anchoring.py and references/anchors.md (https://github.com/crosbylegal/redline-bench,
+commit b29d1113af5d98e2d577f4f17673ebb72834f107, MIT License, Copyright (c) 2026 Crosby Legal; see
+LICENSE-redline-bench). Changes: offsets are mapped back to the raw text so the edit lands on the
+original runs; soft hyphens and zero-width characters are dropped; a leading list number is
+ignored when the quote only matches without it; a failure lists the closest paragraphs.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from difflib import SequenceMatcher
+
+from .model import Unit
+
+FOLD = {
+    "‘": "'", "’": "'", "‚": "'", "‛": "'", "′": "'",
+    "“": '"', "”": '"', "„": '"', "‟": '"', "″": '"',
+    "‐": "-", "‑": "-", "‒": "-", "–": "-", "—": "-", "―": "-", "−": "-",
+    " ": " ", " ": " ", " ": " ", " ": " ", " ": " ", "\t": " ",
+}
+DROP = {"­", "​", "‌", "‍", "⁠", ""}
+NUMBER_PREFIX = re.compile(
+    r"^\s*(?:(?:section|article|clause|schedule|exhibit|annex)\s+)?"
+    r"(?:\(?[0-9]{1,3}[a-z]?\)?(?:\.[0-9]{1,3})*\.?|\([a-z]{1,4}\)|[a-z]{1,4}[.)]|[ivxlc]{1,6}[.)])\s+",
+    re.IGNORECASE,
+)
+
+
+def fold(text: str, casefold: bool = False) -> tuple[str, list[int]]:
+    """Text normalized for matching, and for each folded character the raw index it came from."""
+    out: list[str] = []
+    index: list[int] = []
+    space = False
+    for i, ch in enumerate(text):
+        if ch in DROP:
+            continue
+        ch = FOLD.get(ch, ch)
+        if ch.isspace():
+            if space:
+                continue
+            ch, space = " ", True
+        else:
+            space = False
+            if casefold:
+                lower = ch.lower()
+                ch = lower if len(lower) == 1 else ch
+        out.append(ch)
+        index.append(i)
+    return "".join(out), index
+
+
+@dataclass
+class Located:
+    unit: Unit
+    start: int  # raw offsets into unit.text
+    end: int
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def text(self) -> str:
+        return self.unit.text[self.start:self.end]
+
+
+class AnchorFailure(Exception):
+    def __init__(self, reason: str, message: str, candidates: list[dict] | None = None):
+        super().__init__(message)
+        self.reason = reason
+        self.candidates = candidates or []
+
+    def as_dict(self) -> dict:
+        found = {"reason": self.reason, "message": str(self)}
+        if self.candidates:
+            found["candidates"] = self.candidates
+        return found
+
+
+def occurrences(unit: Unit, needle: str, casefold: bool) -> list[tuple[int, int]]:
+    hay, index = fold(unit.text, casefold)
+    found = []
+    start = hay.find(needle)
+    while start != -1 and needle:
+        end = start + len(needle)
+        found.append((index[start], index[end - 1] + 1))
+        start = hay.find(needle, end)
+    return found
+
+
+def snippet(text: str, limit: int = 160) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def closest(units: list[Unit], quote: str, limit: int = 3) -> list[dict]:
+    """The paragraphs whose text is most like the quote, with the most similar stretch of each."""
+    needle, _ = fold(quote.strip(), casefold=True)
+    if not needle:
+        return []
+    scored = []
+    for unit in units:
+        hay, index = fold(unit.text, casefold=True)
+        if len(hay) < 3:
+            continue
+        matcher = SequenceMatcher(None, needle, hay, autojunk=False)
+        block = matcher.find_longest_match(0, len(needle), 0, len(hay))
+        if block.size < min(6, len(needle)):
+            continue
+        start = max(0, block.b - block.a)
+        end = min(len(hay), start + len(needle))
+        ratio = SequenceMatcher(None, needle, hay[start:end], autojunk=False).ratio()
+        if ratio >= 0.45:
+            raw = unit.text[index[start]: index[end - 1] + 1]
+            scored.append((ratio, unit.id, raw))
+    scored.sort(key=lambda item: -item[0])
+    return [{"paragraph": pid, "text": snippet(raw), "similarity": round(r, 2)} for r, pid, raw in scored[:limit]]
+
+
+def locate(units: list[Unit], quote: str, paragraph: str | None = None, near: str | None = None,
+           occurrence: int | None = None) -> Located:
+    """One place for the quote, or an AnchorFailure naming the reason and the closest candidates."""
+    if not quote or not quote.strip():
+        raise AnchorFailure("empty_quote", "quote is empty")
+    pool = units
+    if paragraph:
+        pool = [u for u in units if u.id == paragraph or u.id.startswith(f"{paragraph}.")]
+        if not pool:
+            raise AnchorFailure("paragraph_not_found", f"there is no paragraph {paragraph}: use an id from read")
+
+    attempts: list[tuple[str, bool, str | None]] = []
+    folded, _ = fold(quote.strip())
+    attempts.append((folded, False, None))
+    attempts.append((fold(quote.strip(), True)[0], True, "matched ignoring case"))
+    stripped = NUMBER_PREFIX.sub("", quote.strip(), count=1)
+    if stripped and stripped != quote.strip() and len(stripped) >= 4:
+        note = f"ignored the list number {quote.strip()[: len(quote.strip()) - len(stripped)].strip()!r}"
+        attempts.append((fold(stripped)[0], False, note))
+        attempts.append((fold(stripped, True)[0], True, note + ", matched ignoring case"))
+
+    for needle, casefold, note in attempts:
+        matches = [(u, s, e) for u in pool for s, e in occurrences(u, needle, casefold)]
+        if not matches:
+            continue
+        notes = [note] if note else []
+        if near and len(matches) > 1:
+            near_folded = fold(near.strip(), True)[0]
+            ranked = []
+            for u, s, e in matches:
+                hay, index = fold(u.text, True)
+                positions = [index[m.start()] for m in re.finditer(re.escape(near_folded), hay)] if near_folded else []
+                if positions:
+                    ranked.append((min(abs(p - s) for p in positions), u, s, e))
+            if ranked:
+                ranked.sort(key=lambda item: item[0])
+                best = [item for item in ranked if item[0] == ranked[0][0]]
+                if len(best) == 1:
+                    _, u, s, e = best[0]
+                    return Located(u, s, e, notes)
+                matches = [(u, s, e) for _, u, s, e in best]
+        if occurrence:
+            if occurrence > len(matches):
+                raise AnchorFailure(
+                    "occurrence_out_of_range",
+                    f"the quote matches {len(matches)} time(s); occurrence {occurrence} doesn't exist",
+                    [{"paragraph": u.id, "text": snippet(u.text[max(0, s - 40): e + 40])} for u, s, e in matches[:5]],
+                )
+            u, s, e = matches[occurrence - 1]
+            return Located(u, s, e, notes)
+        if len(matches) > 1:
+            raise AnchorFailure(
+                "ambiguous",
+                f"the quote matches {len(matches)} places: add paragraph, near or occurrence",
+                [{"paragraph": u.id, "text": snippet(u.text[max(0, s - 40): e + 40])} for u, s, e in matches[:5]],
+            )
+        u, s, e = matches[0]
+        return Located(u, s, e, notes)
+
+    where = f"paragraph {paragraph}" if paragraph else "the document"
+    raise AnchorFailure(
+        "not_found",
+        f"the quote isn't in {where} (after forgiving whitespace, quotes, dashes and case): copy it from the "
+        "current text in read; it may already include an earlier edit",
+        closest(units, quote),
+    )