@introspection-ai/recipe-documents-docx 0.1.0 → 0.3.0

package/README.md

@@ -4,12 +4,68 @@ The Word (`.docx`) format for the Recipes [`documents` tool](../../../docs/docum
 `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 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.
+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.
+
+## Python
+
+The helpers in `python/` run in this package's own Python environment. The package
+declares it in `package.json#pi.runtime.python` (`python/pyproject.toml`, locked by
+`python/uv.lock`, with paper-docx), and the host prepares it with uv beside the Recipe and
+passes its interpreter to the adapter. A Recipe declares no Python for Word: it needs none
+of its own, and one it does declare is its agent's shell environment, which the helpers
+don't use. This needs `@introspection-ai/recipes` 0.39.0 or later.
+
+The interpreter is the first of:
+
+1. `RECIPE_DOCUMENTS_PYTHON`, an explicit override;
+2. the package environment's interpreter, from the host;
+3. `VIRTUAL_ENV` (`bin/python`, or `Scripts\python.exe` on Windows), for a host that
+   prepares no package environment;
+4. `python3` on `PATH`.
 
 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

@@ -1,5 +1,5 @@
 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";
+export { documentPythonExecutable as pythonExecutable, runDocumentHelper as runHelper, } from "@introspection-ai/recipes/documents";
 /** The helper entry point shipped in this package. */
 export declare const DOCX_HELPER: string;
 /**
@@ -11,10 +11,15 @@ export declare const DOCX_DOCUMENT_CAPABILITIES: DocumentCapabilities;
 export declare class DocxDocumentAdapter implements DocumentAdapter {
     private readonly env;
     private readonly script;
+    private readonly python?;
     readonly format = "docx";
     readonly extensions: readonly [".docx"];
     readonly capabilities: DocumentCapabilities;
-    constructor(env?: NodeJS.ProcessEnv, script?: string);
+    /**
+     * `python` is the interpreter of this package's environment, which the host
+     * prepares from its `pi.runtime.python`; see `pythonExecutable` for the order.
+     */
+    constructor(env?: NodeJS.ProcessEnv, script?: string, python?: string | undefined);
     private call;
     read(ctx: DocumentAdapterContext, input: DocumentReadInput): Promise<DocumentResult>;
     revise(ctx: DocumentAdapterContext, input: DocumentReviseInput): Promise<DocumentResult>;
@@ -34,6 +39,11 @@ export declare class DocxDocumentAdapter implements DocumentAdapter {
  * 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,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;AAE7C,OAAO,EACL,wBAAwB,IAAI,gBAAgB,EAC5C,iBAAiB,IAAI,SAAS,GAC/B,MAAM,qCAAqC,CAAC;AAE7C,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAAsE,CAAC;AAE/F;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,oBAQxC,CAAC;AAEF,qBAAa,mBAAoB,YAAW,eAAe;IAUvD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAX1B,QAAQ,CAAC,MAAM,UAAU;IACzB,QAAQ,CAAC,UAAU,YAAI,OAAO,EAAW;IACzC,QAAQ,CAAC,YAAY,uBAA8B;IAEnD;;;OAGG;IACH,YACmB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,SAAc,EACpB,MAAM,CAAC,EAAE,MAAM,YAAA,EAC9B;IAEJ,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

@@ -1,7 +1,6 @@
 import { fileURLToPath } from "node:url";
-import { createDocumentFormatModule, } from "@introspection-ai/recipes/documents";
-import { runHelper } from "./python.js";
-export { pythonExecutable, runHelper } from "./python.js";
+import { createDocumentFormatModule, runDocumentHelper, } from "@introspection-ai/recipes/documents";
+export { documentPythonExecutable as pythonExecutable, runDocumentHelper as runHelper, } from "@introspection-ai/recipes/documents";
 /** The helper entry point shipped in this package. */
 export const DOCX_HELPER = fileURLToPath(new URL("../python/docx_helper.py", import.meta.url));
 /**
@@ -21,15 +20,21 @@ export const DOCX_DOCUMENT_CAPABILITIES = {
 export class DocxDocumentAdapter {
     env;
     script;
+    python;
     format = "docx";
     extensions = [".docx"];
     capabilities = DOCX_DOCUMENT_CAPABILITIES;
-    constructor(env = process.env, script = DOCX_HELPER) {
+    /**
+     * `python` is the interpreter of this package's environment, which the host
+     * prepares from its `pi.runtime.python`; see `pythonExecutable` for the order.
+     */
+    constructor(env = process.env, script = DOCX_HELPER, python) {
         this.env = env;
         this.script = script;
+        this.python = python;
     }
     call(ctx, command, input) {
-        return runHelper(this.script, { command, ...input }, { env: this.env, cwd: ctx.cwd, signal: ctx.signal });
+        return runDocumentHelper(this.script, { command, ...input }, { env: this.env, cwd: ctx.cwd, python: this.python, signal: ctx.signal });
     }
     read(ctx, input) {
         return this.call(ctx, "read", input);
@@ -61,11 +66,17 @@ export class DocxDocumentAdapter {
  * 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,
-    createAdapter: ({ env }) => new DocxDocumentAdapter(env),
+    profiles: { "legal-redlining-en-US": LEGAL_REDLINING_EN_US },
+    createAdapter: ({ env, python }) => new DocxDocumentAdapter(env, DOCX_HELPER, python),
 });
 export default docxDocumentFormatModule;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/recipe-documents-docx",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "profiles",
     "python/*.py",
     "python/recipe_documents_docx/*.py",
     "python/recipe_documents_docx/LICENSE-redline-bench",
@@ -30,11 +31,25 @@
     },
     "./package.json": "./package.json"
   },
+  "pi": {
+    "runtime": {
+      "python": {
+        "project": "python",
+        "lockfile": "python/uv.lock",
+        "version": ">=3.12,<3.15",
+        "imports": [
+          "docx"
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "@introspection-ai/recipes": ">=0.39.0"
+  },
   "peerDependencies": {
-    "@introspection-ai/recipes": ">=0.37.0 <1.0.0"
+    "@introspection-ai/recipes": ">=0.39.0"
   },
   "devDependencies": {
-    "@introspection-ai/recipes": ">=0.37.0",
     "@types/node": "^26.1.2",
     "typescript": "^7.0.2"
   },

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/pyproject.toml

@@ -1,7 +1,7 @@
 [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."
+description = "Python helpers the @introspection-ai/recipe-documents-docx adapter runs, in the environment the host prepares from the package's pi.runtime.python."
 requires-python = ">=3.12,<3.15"
 dependencies = ["paper-docx==0.2.0"]
 

package/dist/python.d.ts

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,52 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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"}