@qvac/skills 0.0.0 → 0.1.0

package/skills/word/references/read.md

@@ -0,0 +1,141 @@
+# Reading a Word Document to Answer in Chat
+
+When the user asks what an attached `.docx` _says_ — a summary, a question
+answered, specific content pulled out — the deliverable is your reply in the
+chat, not a file. This is a **read request**: exactly one `exec` call, staging
+the document in `inputs` and declaring **no `outputs`**, whose whole job is to
+print the document's text so you can read it in the result.
+
+## Staging the Document
+
+Stage the document **by its `attachmentId`**. The id comes from wherever the
+document entered the chat:
+
+- **Produced earlier in this chat** — the `attachmentId` is in that `exec` result.
+- **Uploaded by the user** — the `[Attached file …]` line on their message names
+  it, when the message carries one:
+
+  ```
+  [Attached file "report.docx" (application/vnd.openxmlformats-officedocument.wordprocessingml.document) — attachmentId: 4f9c2ab1]
+  ```
+
+Copy the id verbatim — never invent one, never stage a document id-less: an
+id-less input resolves to an uploaded _image_, so it can never reach a
+document. If no `attachmentId` for the document appears anywhere in the chat,
+say you cannot open that file and ask the user to attach it again — do not
+retry. An attachment from an earlier turn can be used when its attachment id
+is available in the conversation.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["python-docx==1.2.0"],
+  "inputs": [{ "attachmentId": "<id from the [Attached file …] line>", "path": "existing.docx" }],
+  "maxOutputChars": 24000,
+  "command": "..."
+}
+```
+
+- `packages` — `["python-docx==1.2.0"]` on every call. The PyPI package is
+  `python-docx` but the import is `docx`; never list `docx` as the package —
+  that resolves a different, abandoned library. This exact version ships with
+  the app and installs with no network.
+- `inputs` — the staged document lands in the working directory under the bare
+  `path` name; open `Document("existing.docx")` by that name only. The working
+  directory starts empty on every call.
+- No `outputs` — a read builds nothing.
+- `maxOutputChars` — stdout cap in characters (default 8192, max 65536). Set
+  it only on a read call, where the document text must fit in one result —
+  keep the sample's 24000. A build call prints one line and never needs it.
+- `command` — the multi-line Python source, with real newline characters.
+  Never collapse it to one line joined by `;` — a `for`/`if`/`with` after a
+  semicolon is a `SyntaxError`.
+
+## The Read Program
+
+The read program prints every paragraph under its style name — the style names
+are the document's structure — then every table:
+
+```python
+from docx import Document
+
+doc = Document("existing.docx")
+for p in doc.paragraphs:
+    text = p.text.replace("\n", " ").strip()
+    if text:
+        print(f"[{p.style.name}] {text}")
+for i, t in enumerate(doc.tables):
+    print(f"[Table {i + 1}]")
+    for row in t.rows:
+        print(" | ".join(c.text.replace("\n", " ") for c in row.cells))
+```
+
+The `replace` calls are load-bearing: a multi-paragraph cell and a soft line
+break both embed `"\n"` in `.text`, and an embedded newline would split one
+table row — or one paragraph — across two printed lines. Flattened, every line
+starts with its `[...]` marker and every table row is exactly one line.
+
+Tables print after the body text — python-docx does not expose their position
+between paragraphs. When that order matters to the answer, say the tables are
+listed separately. Note `p.style.name` in the sample: `paragraph.style` is a
+style object, not a string — go through `.name` to print or compare it.
+
+**You cannot summarize in the call that reads.** The words in `command` are
+fixed before the program runs, so one call cannot inform itself: any summary
+written into it was written blind — recalled or invented, not read. Python only
+_transports_ the text; the summarizing happens in your reply, after the result
+comes back.
+
+## Answering
+
+**A successful read ends tool use.** When the result prints the document, reply
+with the summary or the answer as chat text. **Scale the reply to the
+document**: a summary is much shorter than what it summarizes — a page or two
+of source earns three to five sentences, and only a long document earns
+sections. Restating the document near its full length is not a summary. Do
+**not**:
+
+- call `exec` again to "re-check", "read more", or read the same document a
+  second time;
+- build a summary `.docx` the user never asked for — an unrequested file is a
+  failed turn, not a bonus.
+
+If stdout ends with `… [truncated]`, the document is longer than the cap:
+answer from what came back and say the answer covers the document up to that
+point. Do not rerun the read — it prints the same beginning again.
+
+If the user asks for the summary **as a file**, that is a read followed by a
+build: the read call above first, then one build call that writes the new
+document from the text you actually read (load `references/create.md` for the
+build). The read still declares no `outputs`, delivers nothing, and does not
+count against the one successful build `exec` per document request — but it
+belongs before the build, never after it.
+
+## Errors
+
+- `PackageNotFoundError: Package not found at '…'` — the document was never
+  staged, or an id-less entry staged an image under a `.docx` path. Add
+  `inputs: [{ "attachmentId": "<id from the exec result or the [Attached file …]
+line>", "path": "existing.docx" }]` and open that exact path. If no id is
+  available, ask the user to attach the file again rather than guessing a name.
+- `attachment … not found in this chat` means `inputs` listed an id that is not
+  in this chat (often a copied placeholder like `att_doc`). Only stage real ids
+  from prior tool results or `[Attached file …]` lines; if none exists, ask the
+  user to re-attach.
+- `ModuleNotFoundError: No module named 'docx'` means `packages` was missing or
+  wrong — add `["python-docx==1.2.0"]` and rerun. Never try to install it, and
+  never "fix" it by importing `python_docx`; the import stays `docx`.
+- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
+  collapsed — restore multi-line newlines from the sample and rerun. Do not
+  switch to `python -c` or change the package pin.
+- A read result ending in `… [truncated]` means the document outgrew the cap:
+  answer from what came back and say the answer covers the document up to that
+  point. Do not rerun the read — it prints the same beginning again.
+
+## Finish
+
+When the read result prints the document, stop tool use and answer the user in
+the chat. Exactly one read `exec` per request; only a read call prints
+document text.

package/skills/word/references/replace.md

@@ -0,0 +1,86 @@
+# Replacing Paragraphs by Position (bundled scripts)
+
+"Replace the first 10 facts", "reword point 3", "swap these bullets for those",
+"change paragraph 7": two `exec` calls, both running a script bundled with this
+skill. **Write no Python.** Never put source in `command` for this job — pass
+`skill`, `script`, and `scriptArgs` exactly as shown, with `inputs` staging the
+document by its `attachmentId` (from the earlier `exec` result or the
+`[Attached file …]` line — copy it verbatim, never invent one).
+
+## Step 1 — list the paragraphs (no `outputs`)
+
+```json
+{
+  "language": "python",
+  "packages": ["python-docx==1.2.0"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
+  "skill": "word",
+  "script": "scripts/list_paragraphs.py",
+  "scriptArgs": ["existing.docx"]
+}
+```
+
+It prints one line per paragraph — `index`, style, text — then a count line.
+Pick the indexes to replace from that list:
+
+- Only body paragraphs (`Normal`, `List Bullet`, `List Number`) are facts,
+  points, or bullets. `Title`, `Heading N`, and an intro sentence are never
+  counted as one.
+- "The first 10 facts" = the first 10 body-paragraph indexes after the heading
+  that introduces them — not indexes 0–9.
+- Fewer facts in the document than asked for: replace the ones that exist and
+  say so in the reply.
+
+## Step 2 — replace exactly those paragraphs (one `outputs` entry)
+
+`scriptArgs` is: input name, output name, then `index, new text` pairs — one
+pair per replaced paragraph, as many pairs as facts requested. The output name
+keeps the input's stem plus `_revised`.
+
+Count the pairs before sending: "the first 10 facts" is 10 pairs — 20 strings
+after the two file names, 10 different sentences, the last index being
+start + 9.
+
+```json
+{
+  "language": "python",
+  "packages": ["python-docx==1.2.0"],
+  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
+  "outputs": ["existing_revised.docx"],
+  "skill": "word",
+  "script": "scripts/replace_paragraphs.py",
+  "scriptArgs": [
+    "existing.docx", "existing_revised.docx",
+    "3", "Dogs have about 1,700 taste buds.",
+    "4", "A dog's nose print is unique, like a fingerprint."
+  ]
+}
+```
+
+Each new text is one complete plain sentence, no markdown, each different. The
+script keeps each paragraph's paragraph style, refuses a heading index,
+refuses text that already reads the same, and prints
+`K of N paragraphs replaced`.
+
+## Finish
+
+`exitCode 0` plus an attachment = done. Reply with one line: the file name and
+the printed count line. Do not call `exec` again for this request.
+
+## Errors
+
+The script stops with a message that names the fix; correct the arguments and
+rerun the **same script** — never switch to writing Python.
+
+- `usage: replace_paragraphs.py …` — the pairs are incomplete: after the two
+  file names, arguments alternate `index`, `text`.
+- `index N is the heading '…'` — that paragraph is a heading, not a fact. Pick
+  body indexes from the Step 1 list.
+- `index N is outside the document's M paragraphs` — re-read the Step 1 list;
+  indexes run from 0 to M-1.
+- `index N already reads exactly that` — the new text equals the old one; write
+  a different sentence.
+- `output … must be a new name` — the output name equals the input's; use
+  `existing_revised.docx`.
+- `PackageNotFoundError` / `attachment … not found` — `inputs` is missing or
+  carries an invented id; stage the document by its real `attachmentId`.

package/skills/word/scripts/list_paragraphs.py

@@ -0,0 +1,19 @@
+"""List every paragraph in a Word document, headings included.
+
+Usage: list_paragraphs.py <input.docx>
+"""
+
+import sys
+
+from docx import Document
+
+if len(sys.argv) != 2:
+    sys.exit(f"usage: list_paragraphs.py <input.docx> — got {sys.argv[1:]}")
+
+source = sys.argv[1]
+doc = Document(source)
+
+for index, paragraph in enumerate(doc.paragraphs):
+    text = paragraph.text.replace("\n", " ")
+    print(f"{index}\t{paragraph.style.name}\t{text}")
+print(f"{len(doc.paragraphs)} paragraphs, {len(doc.tables)} table(s)")

package/skills/word/scripts/replace_paragraphs.py

@@ -0,0 +1,58 @@
+"""Replace selected body paragraphs in a Word document.
+
+Usage: replace_paragraphs.py <input.docx> <output.docx> <index> <new text> [<index> <new text> ...]
+"""
+
+import sys
+
+from docx import Document
+
+usage = "usage: replace_paragraphs.py <input.docx> <output.docx> <index> <new text> [<index> <new text> ...]"
+if len(sys.argv) < 5 or (len(sys.argv) - 3) % 2 != 0:
+    sys.exit(f"{usage} — got {sys.argv[1:]}")
+
+source, target = sys.argv[1], sys.argv[2]
+if source == target:
+    sys.exit(f"output {target} must be a new name, not the staged input")
+
+doc = Document(source)
+paragraphs = doc.paragraphs
+replacements = []
+seen = set()
+
+for position in range(3, len(sys.argv), 2):
+    index_raw, new_text = sys.argv[position], sys.argv[position + 1]
+    try:
+        index = int(index_raw)
+    except ValueError:
+        sys.exit(f"index must be an integer, got: {index_raw}")
+    if index < 0 or index >= len(paragraphs):
+        sys.exit(f"index {index} is outside the document's {len(paragraphs)} paragraphs")
+    if index in seen:
+        sys.exit(f"index {index} was provided more than once")
+    if not new_text:
+        sys.exit(f"new text for index {index} must not be empty")
+
+    paragraph = paragraphs[index]
+    style_name = paragraph.style.name
+    if style_name.startswith("Heading") or style_name == "Title":
+        sys.exit(
+            f"index {index} is the heading {paragraph.text!r} — headings are not facts/points; "
+            "pick body paragraph indexes from list_paragraphs.py"
+        )
+    if new_text == paragraph.text:
+        sys.exit(f"index {index} already reads exactly that")
+
+    seen.add(index)
+    replacements.append((index, new_text))
+
+before = len(paragraphs)
+for index, new_text in replacements:
+    paragraphs[index].text = new_text
+
+assert len(doc.paragraphs) == before
+for index, new_text in replacements:
+    assert doc.paragraphs[index].text == new_text
+
+doc.save(target)
+print(f"{len(replacements)} of {before} paragraphs replaced")