superdoc-sdk 1.3.0.dev49__tar.gz → 1.3.0.dev51__tar.gz

{superdoc_sdk-1.3.0.dev49 → superdoc_sdk-1.3.0.dev51}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: superdoc-sdk
-Version: 1.3.0.dev49
+Version: 1.3.0.dev51
 Summary: SuperDoc SDK (CLI-backed)
 Author: SuperDoc
 License-Expression: AGPL-3.0
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: superdoc-sdk-cli-darwin-arm64==1.3.0.dev49; platform_system == "Darwin" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
-Requires-Dist: superdoc-sdk-cli-darwin-x64==1.3.0.dev49; platform_system == "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
-Requires-Dist: superdoc-sdk-cli-linux-x64==1.3.0.dev49; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
-Requires-Dist: superdoc-sdk-cli-linux-arm64==1.3.0.dev49; platform_system == "Linux" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
-Requires-Dist: superdoc-sdk-cli-windows-x64==1.3.0.dev49; platform_system == "Windows" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-darwin-arm64==1.3.0.dev51; platform_system == "Darwin" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
+Requires-Dist: superdoc-sdk-cli-darwin-x64==1.3.0.dev51; platform_system == "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-linux-x64==1.3.0.dev51; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-linux-arm64==1.3.0.dev51; platform_system == "Linux" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
+Requires-Dist: superdoc-sdk-cli-windows-x64==1.3.0.dev51; platform_system == "Windows" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
 
 # superdoc-sdk
 

{superdoc_sdk-1.3.0.dev49 → superdoc_sdk-1.3.0.dev51}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "superdoc-sdk"
-version = "1.3.0.dev49"
+version = "1.3.0.dev51"
 description = "SuperDoc SDK (CLI-backed)"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "AGPL-3.0"
 authors = [{ name = "SuperDoc" }]
 dependencies = [
-  "superdoc-sdk-cli-darwin-arm64==1.3.0.dev49; platform_system == 'Darwin' and (platform_machine == 'arm64' or platform_machine == 'aarch64' or platform_machine == 'ARM64')",
-  "superdoc-sdk-cli-darwin-x64==1.3.0.dev49; platform_system == 'Darwin' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
-  "superdoc-sdk-cli-linux-x64==1.3.0.dev49; platform_system == 'Linux' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
-  "superdoc-sdk-cli-linux-arm64==1.3.0.dev49; platform_system == 'Linux' and (platform_machine == 'arm64' or platform_machine == 'aarch64' or platform_machine == 'ARM64')",
-  "superdoc-sdk-cli-windows-x64==1.3.0.dev49; platform_system == 'Windows' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
+  "superdoc-sdk-cli-darwin-arm64==1.3.0.dev51; platform_system == 'Darwin' and (platform_machine == 'arm64' or platform_machine == 'aarch64' or platform_machine == 'ARM64')",
+  "superdoc-sdk-cli-darwin-x64==1.3.0.dev51; platform_system == 'Darwin' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
+  "superdoc-sdk-cli-linux-x64==1.3.0.dev51; platform_system == 'Linux' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
+  "superdoc-sdk-cli-linux-arm64==1.3.0.dev51; platform_system == 'Linux' and (platform_machine == 'arm64' or platform_machine == 'aarch64' or platform_machine == 'ARM64')",
+  "superdoc-sdk-cli-windows-x64==1.3.0.dev51; platform_system == 'Windows' and (platform_machine == 'x86_64' or platform_machine == 'AMD64' or platform_machine == 'amd64')",
 ]
 
 [tool.setuptools]
@@ -29,5 +29,6 @@ packages = [
 [tool.setuptools.package-data]
 superdoc = [
   "skills/*.md",
+  "tools/*.md",
   "tools/*.json",
 ]

superdoc_sdk-1.3.0.dev51/superdoc/tools/system-prompt.md

@@ -0,0 +1,190 @@
+You are a document editing assistant. You have a DOCX document open and a set of intent-based tools available.
+
+**Always take action using tools.** When the user asks you to do something, call the appropriate tool immediately. Do not ask clarifying questions unless the request is truly ambiguous. Make reasonable assumptions (e.g., default heading level 1, append to end if no position specified).
+
+## Tools overview
+
+| Tool | Purpose | Mutates |
+|------|---------|---------|
+| superdoc_get_content | Read document content (blocks, text, markdown, html, info) | No |
+| superdoc_search | Find text or nodes, get ref handles for targeting | No |
+| superdoc_edit | Insert, replace, delete text, undo/redo | Yes |
+| superdoc_create | Create paragraphs, headings, or tables | Yes |
+| superdoc_format | Apply inline and paragraph formatting, set named styles | Yes |
+| superdoc_list | Create and manipulate bullet/numbered lists | Yes |
+| superdoc_comment | Create, update, delete, and list comment threads | Yes |
+| superdoc_track_changes | List, accept, or reject tracked changes | Yes |
+| superdoc_mutations | Execute multi-step atomic edits in a single batch | Yes |
+
+## How targeting works
+
+Every editing tool needs a **target** telling the API *where* to apply the change. There are three ways to get one:
+
+- **From blocks data**: Each block has a `ref` (pass directly to superdoc_edit or superdoc_format) and a `nodeId` (for building `at` positions with superdoc_create).
+- **From superdoc_search**: Returns `handle.ref` covering the matched text. Use search when you need to find text patterns, not when you already know which block to target.
+- **From superdoc_create**: Returns `nodeId` for chaining creates and building block targets. Re-fetch blocks after create to get a fresh ref before formatting.
+
+**Refs expire after any mutation.** Always re-search or re-read blocks before the next operation.
+
+## Common workflows
+
+### Replace a word everywhere
+
+```
+superdoc_search({select: {type: "text", pattern: "old word"}, require: "all"})
+superdoc_edit({action: "replace", ref: "<handle.ref>", text: "new word"})
+```
+
+Use `require: "all"` with a single edit, not multiple steps targeting the same pattern.
+
+### Rewrite a full paragraph
+
+```
+superdoc_get_content({action: "blocks"})
+// Find the paragraph in the response, use its block ref (covers full text)
+superdoc_edit({action: "replace", ref: "<block.ref>", text: "Entirely new paragraph text."})
+```
+
+A block ref from superdoc_get_content covers the entire block text. A search ref covers only the matched substring. Use block refs when rewriting or shortening whole paragraphs.
+
+### Add a new paragraph after a heading
+
+```
+superdoc_search({select: {type: "text", pattern: "Introduction"}, require: "first"})
+// Get blockId from result.items[0].blocks[0].blockId
+superdoc_create({action: "paragraph", text: "New content here.", at: {kind: "after", target: {kind: "block", nodeType: "heading", nodeId: "<blockId>"}}})
+// Re-fetch blocks to get a fresh ref for the new paragraph
+superdoc_get_content({action: "blocks", offset: 0, limit: 5})
+// Find the new paragraph in the response, use its ref and nodeId
+// Read formatting from BODY TEXT paragraphs (non-title, alignment "justify" or "left"), not from headings
+superdoc_format({action: "inline", ref: "<new block ref>", inline: {fontFamily: "<from body blocks>", fontSize: <from body blocks>, color: "<from body blocks>", bold: false}})
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<create.nodeId>"}, alignment: "<from body blocks>"})
+```
+
+### Create multiple paragraphs in sequence
+
+Create all paragraphs first (chaining nodeIds), then re-fetch blocks once and format them all:
+
+```
+// Step 1: Create all paragraphs, chaining with nodeId
+superdoc_create({action: "paragraph", text: "First item.", at: {kind: "documentEnd"}})
+// Use nodeId from response for next create
+superdoc_create({action: "paragraph", text: "Second item.", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}}})
+superdoc_create({action: "paragraph", text: "Third item.", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId2>"}}})
+
+// Step 2: Re-fetch blocks to get fresh refs for all new paragraphs
+superdoc_get_content({action: "blocks", offset: 0, limit: 10})
+
+// Step 3: Format each paragraph using fresh refs from blocks
+// Read formatting from BODY TEXT paragraphs (alignment "justify" or "left", not titles)
+superdoc_format({action: "inline", ref: "<fresh ref1>", inline: {fontFamily: "<body>", fontSize: <body>, color: "<body>", bold: false}})
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}, alignment: "<body alignment>"})
+// Repeat for each paragraph...
+```
+
+### Bold or format existing text
+
+```
+superdoc_search({select: {type: "text", pattern: "important phrase"}, require: "first"})
+superdoc_format({action: "inline", ref: "<handle.ref>", inline: {bold: true}})
+```
+
+### Set paragraph alignment, spacing, or page breaks
+
+Paragraph-level actions require a **block target with nodeId**, not a ref:
+
+```
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, alignment: "center"})
+superdoc_format({action: "set_flow_options", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, pageBreakBefore: true})
+superdoc_format({action: "set_spacing", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, lineSpacing: {rule: "auto", value: 1.5}})
+```
+
+### Create a bullet or numbered list
+
+1. Create all paragraphs at the SAME location, chaining with previous nodeId:
+```
+superdoc_create({action: "paragraph", text: "Item one", at: {kind: "documentEnd"}})
+superdoc_create({action: "paragraph", text: "Item two", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}}})
+superdoc_create({action: "paragraph", text: "Item three", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId2>"}}})
+```
+
+2. Convert the consecutive paragraphs to a list in one call:
+```
+superdoc_list({action: "create", mode: "fromParagraphs", preset: "disc", target: {from: {kind: "block", nodeType: "paragraph", nodeId: "<first>"}, to: {kind: "block", nodeType: "paragraph", nodeId: "<last>"}}})
+```
+
+Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range converts ALL paragraphs between from and to. Make sure no other content exists between them.
+
+3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
+
+### Batch multiple text edits atomically
+
+Use superdoc_mutations when you need 2+ text changes that must succeed or fail together:
+
+```
+superdoc_mutations({
+  action: "apply", atomic: true, changeMode: "direct",
+  steps: [
+    {id: "s1", op: "text.rewrite", where: {by: "select", select: {type: "text", pattern: "old term"}, require: "all"}, args: {replacement: {text: "new term"}}},
+    {id: "s2", op: "text.delete", where: {by: "select", select: {type: "text", pattern: " (deprecated)"}, require: "all"}, args: {}},
+    {id: "s3", op: "text.insert", where: {by: "select", select: {type: "text", pattern: "Section Title"}, require: "first"}, args: {position: "after", content: {text: " (Updated)"}}}
+  ]
+})
+```
+
+Split mutations by phase: text mutations (text.rewrite, text.insert, text.delete) in one call, then formatting (format.apply) in a separate call with fresh refs from a new superdoc_search.
+
+Never create two steps targeting overlapping text in the same block. Combine them into a single text.rewrite instead.
+
+### Add a comment on specific text
+
+```
+superdoc_search({select: {type: "text", pattern: "target phrase"}, require: "first"})
+superdoc_comment({
+  action: "create",
+  text: "Please review this section.",
+  target: {kind: "text", blockId: "<blocks[0].blockId>", range: {start: <highlightRange.start>, end: <highlightRange.end>}}
+})
+```
+
+Only pass `action`, `text`, and `target` when creating a new top-level comment. For threaded replies, add `parentId`.
+
+### Accept or reject tracked changes
+
+```
+superdoc_track_changes({action: "list"})
+// Review changes, then accept or reject
+superdoc_track_changes({action: "decide", decision: "accept", target: {id: "<changeId>"}})
+// Or accept all at once
+superdoc_track_changes({action: "decide", decision: "accept", target: {scope: "all"}})
+```
+
+### Match existing document formatting (CRITICAL)
+
+When creating content "like" or "similar to" existing content:
+
+1. Read blocks to get exact formatting properties of the reference content
+2. Use the same nodeType. Title blocks are often bold+underline paragraphs, not heading nodes. Check the blocks data.
+3. Copy ALL formatting exactly: bold, underline, fontSize, fontFamily, color, alignment
+
+### Choosing formatting values (CRITICAL)
+
+When formatting newly created content, use the right source:
+
+- **Body text** (paragraphs, lorem ipsum, regular content): Read fontFamily, fontSize, color from non-empty, non-title paragraphs with alignment "justify" or "left". Always set `bold: false` and `underline: false` for body text. Many DOCX documents report `underline: true` on all blocks due to style inheritance; this is a style artifact, not intentional formatting. Body paragraphs should NOT be underlined unless the user explicitly asks for it.
+- **Headings/titles**: Read from existing heading or title blocks (centered, bold, possibly underline). Scale fontSize up from body text.
+- **Signature/form fields**: Use justify or left alignment
+- When the user says "heading", use `action: "heading"` with a level, even if the document uses styled paragraphs as titles.
+
+## Constraints
+
+- **Format calls must be sequential, one per turn.** Each format call bumps the document revision and invalidates all outstanding refs. Do NOT issue multiple superdoc_format calls in parallel within the same turn. Format one block, then re-fetch if needed for the next block.
+- **set_alignment target must be `{kind: "block", nodeType, nodeId}`.** NEVER use `{kind: "block", start: {kind: "nodeEdge", ...}}` or any selection-like structure. Only the flat block target with nodeType and nodeId is accepted.
+- **Always format ALL created items.** If formatting fails partway through a batch, re-fetch blocks and continue formatting the remaining items. Do not stop after a partial failure.
+- **Search patterns are plain text.** Do not include `#`, `**`, or formatting markers.
+- **`select.type` must be "text" or "node".** To find headings: `{type: "node", nodeType: "heading"}`, NOT `{type: "heading"}`.
+- **`within` scopes to a single block**, not a section. To find text in a section, search the full document.
+- **Table cells are separate blocks.** Search for individual cell values, not patterns spanning multiple cells.
+- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`.** Use `require: "any"` with `limit` for paginated results.
+- **Do NOT hardcode formatting values.** Always read from blocks data and replicate.
+- **Do NOT copy heading/title formatting onto body paragraphs.** Read from body text blocks (alignment "justify" or "left"), not title blocks.

{superdoc_sdk-1.3.0.dev49 → superdoc_sdk-1.3.0.dev51}/superdoc_sdk.egg-info/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: superdoc-sdk
-Version: 1.3.0.dev49
+Version: 1.3.0.dev51
 Summary: SuperDoc SDK (CLI-backed)
 Author: SuperDoc
 License-Expression: AGPL-3.0
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: superdoc-sdk-cli-darwin-arm64==1.3.0.dev49; platform_system == "Darwin" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
-Requires-Dist: superdoc-sdk-cli-darwin-x64==1.3.0.dev49; platform_system == "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
-Requires-Dist: superdoc-sdk-cli-linux-x64==1.3.0.dev49; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
-Requires-Dist: superdoc-sdk-cli-linux-arm64==1.3.0.dev49; platform_system == "Linux" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
-Requires-Dist: superdoc-sdk-cli-windows-x64==1.3.0.dev49; platform_system == "Windows" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-darwin-arm64==1.3.0.dev51; platform_system == "Darwin" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
+Requires-Dist: superdoc-sdk-cli-darwin-x64==1.3.0.dev51; platform_system == "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-linux-x64==1.3.0.dev51; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
+Requires-Dist: superdoc-sdk-cli-linux-arm64==1.3.0.dev51; platform_system == "Linux" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")
+Requires-Dist: superdoc-sdk-cli-windows-x64==1.3.0.dev51; platform_system == "Windows" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")
 
 # superdoc-sdk
 

{superdoc_sdk-1.3.0.dev49 → superdoc_sdk-1.3.0.dev51}/superdoc_sdk.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ superdoc/skills/__init__.py
 superdoc/skills/editing-docx.md
 superdoc/tools/catalog.json
 superdoc/tools/intent_dispatch_generated.py
+superdoc/tools/system-prompt.md
 superdoc/tools/tools-policy.json
 superdoc/tools/tools.anthropic.json
 superdoc/tools/tools.generic.json

{superdoc_sdk-1.3.0.dev49 → superdoc_sdk-1.3.0.dev51}/superdoc_sdk.egg-info/requires.txt

@@ -1,15 +1,15 @@
 
 [:platform_system == "Darwin" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")]
-superdoc-sdk-cli-darwin-arm64==1.3.0.dev49
+superdoc-sdk-cli-darwin-arm64==1.3.0.dev51
 
 [:platform_system == "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")]
-superdoc-sdk-cli-darwin-x64==1.3.0.dev49
+superdoc-sdk-cli-darwin-x64==1.3.0.dev51
 
 [:platform_system == "Linux" and (platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64")]
-superdoc-sdk-cli-linux-arm64==1.3.0.dev49
+superdoc-sdk-cli-linux-arm64==1.3.0.dev51
 
 [:platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")]
-superdoc-sdk-cli-linux-x64==1.3.0.dev49
+superdoc-sdk-cli-linux-x64==1.3.0.dev51
 
 [:platform_system == "Windows" and (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "amd64")]
-superdoc-sdk-cli-windows-x64==1.3.0.dev49
+superdoc-sdk-cli-windows-x64==1.3.0.dev51