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

package/README.md

@@ -1,3 +1,57 @@
-# 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.
+
+## With and without a profile
+
+The tool is the same either way: the same commands, the same checks, and the original
+is never changed. A profile only adds guidance the agent reads.
+
+**Without a profile** — any Word work: editing a policy, filling a template, marking up
+a memo, answering comments.
+
+```json
+{ "pi": { "documents": [{ "format": "docx" }] } }
+```
+
+The agent gets the core `documents` skill: which command fits which change, how to quote
+text so an edit lands, and what to do when an edit fails. It says nothing about any one
+kind of work, so the Recipe's own skills decide how changes should read.
+
+**With `legal-redlining-en-US`** — contract redlines, and responses to the other side's
+redline.
+
+```json
+{ "pi": { "documents": [{ "format": "docx", "profile": "legal-redlining-en-US" }] } }
+```
+
+The agent also gets `profiles/legal-redlining-en-us/SKILL.md`, which covers:
+
+- planning a first markup by what moves a right, an obligation or a risk;
+- making the changes in `revise` batches, one rationale comment per change;
+- removing a clause with `remove_section`, leaving `Reserved.` so numbering still lines up;
+- answering the other side's changes with counters and replies, so the discussion stays
+  visible, rather than accepting or rejecting;
+- writing each rationale as the reason, in your side's voice, never narrating the edit.
+
+The profile is generic legal practice. A firm's own positions, playbook and comment
+style belong in the Recipe's skills, beside it.
+
+**Your own profile** — for another kind of work with its own way of using the tool,
+write a profile in the Recipe: a folder holding a `SKILL.md` whose frontmatter `name` is
+the folder's name, and point `profile` at it.
+
+```json
+{ "pi": { "documents": [{ "format": "docx", "profile": "./profiles/house-style-en-gb" }] } }
+```
+
+[Write your own profile](../../../docs/documents.md#write-your-own-profile) has the
+contract, what a profile should say, and a complete example.
+
+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,44 @@
+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]
+ * ```
+ */
+/**
+ * Contract redlining in US English: how to plan a first markup and answer the
+ * other side's redline. A Recipe selects it with `"profile": "legal-redlining-en-US"`.
+ */
+export declare const LEGAL_REDLINING_EN_US: string;
+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;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAwF,CAAC;AAE3H,eAAO,MAAM,wBAAwB,0EAMnC,CAAC;eAEY,wBAAwB"}

package/dist/index.js

@@ -0,0 +1,77 @@
+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]
+ * ```
+ */
+/**
+ * Contract redlining in US English: how to plan a first markup and answer the
+ * other side's redline. A Recipe selects it with `"profile": "legal-redlining-en-US"`.
+ */
+export const LEGAL_REDLINING_EN_US = fileURLToPath(new URL("../profiles/legal-redlining-en-us/SKILL.md", import.meta.url));
+export const docxDocumentFormatModule = createDocumentFormatModule({
+    format: "docx",
+    extensions: [".docx"],
+    capabilities: DOCX_DOCUMENT_CAPABILITIES,
+    profiles: { "legal-redlining-en-US": LEGAL_REDLINING_EN_US },
+    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":"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"}

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,51 @@
 {
   "name": "@introspection-ai/recipe-documents-docx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+    "profiles",
+    "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/profiles/legal-redlining-en-us/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: legal-redlining-en-us
+description: How to use the documents tool for a contract redline, or a response to the other side's redline (profile legal-redlining-en-US). Read it with the documents skill before changing a contract.
+---
+
+# Documents for legal redlining
+
+This profile layers on the core `documents` skill. Every change is a tracked change with
+its rationale as a margin comment, written for the other side's lawyer to read.
+
+## A first markup
+
+1. `read` the brief and the whole contract, every part.
+2. Plan by priority before editing: what moves a right, an obligation or a risk. Leave
+   drafting preferences alone unless the brief asks for them.
+3. Make the changes in one `revise` batch, or as few as possible, in document order. For
+   each paragraph give its `paragraph` id, its full revised `text` (copy the current text
+   from `read` and change only what must move) and the `rationale`.
+4. Revise table cells by their ids (`p-105.r2c3`); a short rationale is fine for the cells
+   of a row that share a reason.
+5. Use `propose_edits` for a small fix after a batch, such as one figure, quoted from a
+   fresh `read`.
+6. Remove a whole numbered clause with `remove_section`: it strikes `from`..`through` and
+   leaves `Reserved.` after `keep` (the heading), so the numbering after it still lines
+   up. Strike a clause's words with `revise` only when the clause stays.
+
+## A response turn
+
+Tracked changes and comments in a file aren't always the other side's. Sort them by
+author first: some can be your own side's earlier turn, or your own edits from this
+session. Treat it as a response turn only when the request says the file came back from
+the other side, or the authors show it did. Then, for the other side's markup:
+
+- Leave their changes in place and layer yours on top, so they see what you did.
+- `respond` with `counter` answers one of their changes with your own tracked change,
+  inside their language, with the rationale on its `thread` when the point has one.
+  Prefer it to rejecting: a counter keeps the discussion visible.
+- Agree with `respond` `{action: "reply", thread, text: "Accepted."}`. Accept or reject
+  only when the request asks to resolve changes for good, such as cleaning a draft
+  before it goes out; those leave no trace.
+- Changes the tool says it can't accept or reject here are for the lawyer to resolve in
+  Word: list them in the open decisions.
+
+## Rationale
+
+Write each rationale as the reason, in one or two sentences, in your side's voice: what
+the change protects and why the original doesn't work for you. Never narrate the edit
+("Changed thirty to sixty"); the tracked change already shows it.
+
+## When an edit fails
+
+Fix that edit from its reason and the closest text, and resubmit only it. An edit that
+fails twice is skipped: list it under "Edits not applied" in the open decisions, and never
+retry it by widening it to more text. Read the redline back once before you finish and
+check every change has its rationale.

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."""