@qvac/skills 0.0.0 → 0.1.0

package/skills/excel/references/create.md

@@ -0,0 +1,374 @@
+# Creating a Workbook (openpyxl)
+
+Create a new `.xlsx` from scratch by running Python through the `exec` tool.
+A new workbook needs **no** `inputs` — do not invent attachment ids. **Exactly
+one** `exec` call per user request when that call succeeds.
+
+**A workbook that already exists in this chat is never rebuilt here.** "Add a
+row", "change a cell", "extend the sheet" — any request that starts from an
+existing `.xlsx` is an EDIT: load `references/edit.md` and stage the workbook
+by its `attachmentId`. Building a fresh workbook for an edit request throws
+away everything the user already has.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["openpyxl==3.1.5"],
+  "outputs": ["report.xlsx"],
+  "command": "..."
+}
+```
+
+- `packages` — `["openpyxl==3.1.5"]` on every call. Pin the version; this exact
+  version ships with the app and installs with no network; any other version
+  has to be downloaded, which fails on a device that is offline. A workbook that
+  embeds an image also needs `"pillow"`, **deliberately unpinned** — the runtime owns
+  its version and `"pillow==12.2.0"` matches nothing, which sends openpyxl to PyPI
+  with it. `["openpyxl==3.1.5", "pillow"]` ships whole and installs offline.
+- `outputs` — `["report.xlsx"]`. `wb.save("report.xlsx")` must match the
+  declared output name. `.xlsx` and `.csv` are allowed; `.xlsm` is not. Never
+  pass an absolute path to `save()`.
+- `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`.
+- No `inputs` key at all — **except** to embed an image, the one file a create
+  call stages. See Embedding an Image.
+
+## The Recipe
+
+Start from this. It is a complete, working workbook — bold headers, data rows,
+number formats, column widths — saved under the declared output name. Copy it
+and change the content; do not assemble a workbook from memory.
+
+**Write the program flat — no `def`, no helper functions, no classes.** Top-level
+statements only, in the order the sample shows. Every real failure of this skill
+has come from a model writing a generator function and then wiring it up wrong: a
+list filled inside a function and read outside it (`NameError: name 'data' is not
+defined`), or a function that was never called, which saves an empty sheet and
+delivers a blank file to the user.
+
+**Type the data out as literal rows, however long the series.** Ten years is ten
+tuples — write them. Never build periods with `datetime`/`timedelta` arithmetic
+and never increment a month by hand: `month + 1` past December raises
+`ValueError: month must be in 1..12, not 13`. A year is the plain number `2016`
+and a month is the plain string `"2016-03"` — neither needs a date object.
+
+**Give the granularity the user asked for.** "Prices from 2016-2025" is one row
+per year — ten rows. Do not expand it into 120 monthly rows they did not ask for.
+
+**Import once, then use that exact name.** After
+`from openpyxl import Workbook` the constructor is `Workbook()` — writing
+`openpyxl.Workbook()` raises `NameError: name 'openpyxl' is not defined`, because
+that import never binds the module. Copy the sample's import block as-is.
+
+**Keep every underscore in API names.** `load_workbook`, `create_sheet`,
+`number_format`, `column_dimensions`, `column_letter`, `iter_rows`, `max_row`,
+`merge_cells` — stripping them to `loadworkbook` / `createsheet` fails.
+
+**Fill the template in — do not rewrite it.** The block below is the whole
+program. Change only its named slots: `SHEET_TITLE`, `HEADERS`, `ROWS`,
+`MONEY_COLUMNS`, and `OUTPUT` (which must match the declared output). Every other
+line stays character for character. In practice every failed run has come from
+code invented *around* this template — an extra per-row styling loop, a
+hand-built summary row, a second unpack of the same data — not from the template
+itself. If a row needs a number format, put its column letter in
+`MONEY_COLUMNS`; that is the only knob.
+
+Nothing goes after `print(...)`, and no comparison, `sorted`, `min`/`max` or
+running total goes between the lines. Values that need working out are worked out
+as you type `ROWS`, and anything the user should notice about the numbers belongs
+in your chat reply, not in more Python. Comparing a year to a label is where the
+last run died: `TypeError: '<=' not supported between instances of 'int' and 'str'`.
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font
+
+SHEET_TITLE = "Q1 Sales"
+HEADERS = ["Region", "Units", "Unit Price", "Revenue"]
+ROWS = [                             # every tuple already complete, one per row
+    ("North", 120, 9.99, 1198.80),
+    ("South", 80, 12.50, 1000.00),
+    ("East", 200, 7.25, 1450.00),
+]
+MONEY_COLUMNS = ["C", "D"]           # money-formatted columns; [] for none
+OUTPUT = "report.xlsx"               # must match the declared output exactly
+
+wb = Workbook()
+ws = wb.active                       # a new workbook already has one sheet
+ws.title = SHEET_TITLE
+
+ws.append(HEADERS)
+for cell in ws[1]:                   # ws[N] is row NUMBER N — never ws[a_list]
+    cell.font = Font(bold=True)
+    ws.column_dimensions[cell.column_letter].width = 14
+ws.freeze_panes = "A2"               # header stays visible while scrolling
+
+for row in ROWS:                     # append whole rows — never unpack them
+    ws.append(list(row))
+
+for letter in MONEY_COLUMNS:
+    for cell in ws[letter][1:]:      # ws["C"] is a column; [1:] skips its header
+        cell.number_format = '#,##0.00'
+
+assert ws.max_row > 1, "no data rows — fix the code, never deliver an empty sheet"
+wb.save(OUTPUT)
+print(f"{len(wb.sheetnames)} sheets, {ws.max_row} rows")
+```
+
+Compute derived columns while writing `ROWS`, not in a loop over them: the
+revenue above is typed into each tuple. Unpacking rows to build other rows
+(`for a, b in ROWS:`) is what raises
+`ValueError: not enough values to unpack` the moment one tuple is a different
+length.
+
+Only when the user wants a **live** total, append this after the loop — nothing
+else changes:
+
+```python
+last_data_row = ws.max_row           # capture BEFORE appending the total row
+ws.append(["Total", None, None, f"=SUM(D2:D{last_data_row})"])
+```
+
+Capture `ws.max_row` **before** appending a row whose formula refers to the data —
+`max_row` grows with every append, so building the range afterwards produces a
+formula that includes its own cell (a circular reference the user sees as an error
+in Excel). Remember this runtime computes nothing: the formula cell looks empty
+in the chat preview, so say in the reply that the total shows up once the file
+is opened in a spreadsheet app.
+
+Every data table gets the three lines the sample shows — bold header row,
+`ws.freeze_panes = "A2"`, and column widths. Without them the user opens a wall
+of `####` columns and loses the header the moment they scroll.
+
+When the user asks for made-up, sample, or random data, generate it so it holds
+together: a high is above its close, a low is below it, dates run in order,
+percentages sum to about 100. Drawing each cell independently from a random range
+puts a low of 64,000 next to a high of 21,000 in the same row, and the user reads
+that as a broken file rather than as placeholder data.
+
+Number formats are strings on the cell: `'#,##0.00'` for money-style decimals,
+`'0.0%'` for percentages (store the fraction, e.g. `0.31`, not `31`), `'yyyy-mm-dd'`
+for dates.
+
+## Dates
+
+Only when the user needs real date sorting or filtering — a year or a month label
+is a plain number or string, and needs none of this. Copy both lines together;
+the import is the half that gets forgotten:
+
+```python
+from datetime import date     # NOT `import datetime`, NOT `from datetime import datetime`
+
+ws["A2"] = date(2016, 1, 1)   # a bare date(...) call — never datetime.date(...)
+ws["A2"].number_format = 'yyyy-mm-dd'
+```
+
+`datetime.date(2016, 1, 1)` after `from datetime import datetime` raises
+`TypeError: descriptor 'date' for 'datetime.datetime' objects doesn't apply to a
+'int' object`, and with no import at all it raises `NameError`. Both mean the same
+thing: use the two lines above exactly as written.
+
+## Several Sheets
+
+When the user asks for N sheets — "a tab per region", "ten sheets of facts" — write
+**one flat list of rows** and let the code group it. Each row names its own sheet as
+its first value, exactly like `ROWS` above, so there are no nested lists to author:
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Font
+
+HEADERS = ["#", "Fact"]              # the columns AFTER the sheet name
+WIDTHS = [6, 70]                     # one width per header column
+ROWS = [                             # (sheet, then one value per header column)
+    ("Vision", 1, "Parrots see ultraviolet light that humans cannot."),
+    ("Vision", 2, "Their color vision uses four cone types, not three."),
+    ("Vision", 3, "UV patterns on feathers help them choose mates."),
+    ("Speech", 1, "Parrots mimic sound with a syrinx, not vocal cords."),
+    ("Speech", 2, "African greys can attach meaning to words."),
+    ("Speech", 3, "Wild flocks carry regional dialects."),
+]
+OUTPUT = "facts.xlsx"
+
+wb = Workbook()
+spare = wb.active                    # removed at the end; every sheet is created below
+written = {}
+for row in ROWS:
+    title = row[0]
+    if title in written:
+        ws = wb[title]
+    else:
+        ws = wb.create_sheet(title)
+        ws.append(HEADERS)
+        for cell in ws[1]:
+            cell.font = Font(bold=True)
+            ws.column_dimensions[cell.column_letter].width = WIDTHS[cell.column - 1]
+        ws.freeze_panes = "A2"
+        written[title] = 0
+    ws.append(list(row[1:]))         # row[1:] drops the sheet name — never append row
+    written[title] += len(row) - 1
+    ws.cell(row=ws.max_row, column=len(HEADERS)).alignment = Alignment(wrap_text=True)
+
+wb.remove(spare)
+assert written, "no rows were written"
+for title in written:
+    rows_written = written[title] // len(HEADERS)
+    assert rows_written >= 3, f"sheet {title} holds {rows_written} row(s) — write at least 3"
+wb.save(OUTPUT)
+print(f"{len(wb.sheetnames)} sheets: " + ", ".join(f"{t}={written[t]}v" for t in written))
+```
+
+**Append `list(row[1:])`, never `row` and never `[row]`.** `row` still carries the
+sheet name, and `[row]` puts the whole tuple in one cell — that is what
+`ValueError: Cannot convert (1, 'Parrots see …') to Excel` means. The slice is the
+only unpacking this program does; do not add `for a, b in ROWS` loops of your own,
+which raise `ValueError: too many values to unpack`.
+
+A formula that references a sheet whose name contains a space must quote it:
+`=SUM('Raw Data'!B1:B2)`.
+
+**Do not invent a nested shape.** A list of `(title, [rows…])` pairs is the single
+most common way this call fails: the inner list reaches a cell and openpyxl refuses
+it. One flat list, sheet name first.
+
+The count printed per sheet is **written values**, not rows. A row count proves
+nothing: `ws.max_row` grows when a cell is merely styled, so a sheet that got
+alignment but no values still reports four rows while holding nothing.
+
+## Embedding an Image
+
+**The image must be staged in `inputs` in the same `exec` call.** The working
+directory starts empty, so a file name that is not in `inputs` does not exist.
+`XLImage("photo.png")` without an `inputs` entry whose `path` is `photo.png` raises
+`FileNotFoundError`, and rerunning the same command fails the same way.
+
+**`path` is a name you choose, not a name you derive.** It has nothing to do with
+the attachment id: `photo.png` is a fine `path` for an attachment whose id is
+`9f2c4ab1…`. Two mistakes to never make:
+
+- Turning an id into a file name — `XLImage("9f2c4ab1….png")`, or opening the bare
+  id. An id goes in `attachmentId`, never in a path and never in the Python.
+- Opening a name that merely appeared in the conversation. A `generate_image` result
+  carries a `fileName` — what the picture was called when it was made, not a file on
+  disk. Take the `attachmentId` from that result and ignore the rest; nothing is
+  readable until an `inputs` entry stages it under a `path` you chose.
+
+**A `generate_image` result anywhere in the conversation IS the image the user
+means.** "Add this image" points at the picture this chat already produced, in an
+earlier turn as much as this one; the user's own message carries no attachment and
+does not need to. Stage that id and build. Do not ask for an image the conversation
+already has, and never generate a replacement to embed in its place.
+
+An image the user **uploaded** has no id to copy. Stage it with `path` only and no
+`attachmentId` key; the first id-less entry is the first image of their latest
+message.
+
+```json
+{
+  "language": "python",
+  "packages": ["openpyxl==3.1.5", "pillow"],
+  "inputs": [{ "attachmentId": "<id from the generate_image result>", "path": "photo.png" }],
+  "outputs": ["report.xlsx"],
+  "command": "..."
+}
+```
+
+The class lives in `openpyxl.drawing.image` and collides with PIL's `Image`, so
+alias it. `add_image` anchors the picture's top-left corner at one cell:
+
+```python
+from openpyxl.drawing.image import Image as XLImage
+
+img = XLImage("photo.png")           # the path from inputs, nothing else
+img.width, img.height = 320, 320     # pixels
+ws.add_image(img, "A1")              # A1 is the top-left corner, not a range
+```
+
+`add_image` is a **worksheet** method — `wb.add_image(...)` raises `AttributeError`.
+The picture floats above the grid rather than filling a cell, so leave the rows it
+covers empty.
+
+**One `add_image` call, on one sheet.** "Add this image" means the workbook carries
+the picture once — put it on the first sheet, or on a sheet of its own. Calling
+`add_image` inside the loop that builds the sheets embeds a fresh copy per sheet.
+
+**Check the call before sending it.** Every image file name in `command` must also
+be the `path` of an `inputs` entry in that same call, and `packages` must include
+`"pillow"`. The reverse holds too: if `inputs` stages an image, `command` must call
+`add_image`. Never wrap `XLImage` or the import in a `try`/`except` that saves
+anyway, and never draw a substitute with PIL — the image already exists.
+
+Merged cells: after `ws.merge_cells("A1:C1")` only the top-left anchor is
+writable — `ws["A1"] = "Title"` works, while writing `B1` or `C1` raises
+`AttributeError: 'MergedCell' object attribute 'value' is read-only`. Write the
+anchor, always.
+
+## Errors
+
+- Never print the workbook's bytes or base64 — stdout is capped and the file
+  travels through `outputs`. A build call prints only a short summary line
+  (e.g. `2 sheets, 5 rows`).
+- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
+  collapsed — restore multi-line newlines from the sample and rerun. Underscores
+  in names (`load_workbook`, not `loadworkbook`) must stay. Do not switch to
+  `python -c` or change the package pin.
+- `ModuleNotFoundError: No module named 'openpyxl'` means `packages` was missing
+  or wrong — add `["openpyxl==3.1.5"]` and rerun. Never try to install it.
+- `attachment … not found in this chat` means `inputs` listed an id that is not in
+  this chat (often a copied placeholder). For a new workbook, omit `inputs`
+  entirely and rerun.
+- `ValueError: Cannot convert [...] to Excel` means a list or tuple reached a cell:
+  the code appended `row` or `[row]` instead of `list(row[1:])`, or invented a
+  nested `(title, [rows…])` shape. Flatten it — see Several Sheets.
+- `ImportError: You must install Pillow to fetch image objects` means an image was
+  embedded without `"pillow"` in `packages` — openpyxl does not install it. Add it
+  and rerun.
+- `ModuleNotFoundError: No module named 'PIL'` means the code imported PIL itself,
+  usually to draw a picture that already exists as an attachment. Stage the
+  attachment through `inputs` instead.
+- `AttributeError: 'Workbook' object has no attribute 'add_image'` — `add_image` is
+  a worksheet method: `ws.add_image(img, "A1")`.
+- `FileNotFoundError` on a 32-character hex name means an attachment id was opened
+  as a path. The id belongs in `attachmentId`; open the `path` you chose.
+- A delivered workbook with no picture in it, when the user asked for one, means the
+  image was never staged or `add_image` was never called. Rebuild it in one call.
+- `ImportError: cannot import name 'NumberFormat' from 'openpyxl.styles'` — there
+  is no such class. A number format is a plain string on the cell:
+  `cell.number_format = '#,##0.00'`. The only names to import from
+  `openpyxl.styles` are `Font`, `Alignment`, `PatternFill`, `Border`, `Side`.
+- `TypeError: expected string or bytes-like object, got 'list'` means a worksheet
+  was indexed with a list — `ws[row]` where `row` holds the values just appended.
+  `ws[...]` takes a row number (`ws[1]`) or a range string (`ws["A1:C1"]`). To
+  style the row you just appended, index it by number: `ws[ws.max_row]`.
+- `NameError: name 'openpyxl' is not defined` means the code called
+  `openpyxl.Workbook()` after `from openpyxl import Workbook` — call `Workbook()`.
+- `NameError` on any other name means a variable was defined inside a `def` and
+  read outside it. Delete the function and inline its body at top level.
+- `ValueError: month must be in 1..12, not 13` means the code did month
+  arithmetic. Type the periods out as literal values instead.
+- `AssertionError: sheet <name> holds N row(s) — write at least 3` means a sheet got
+  fewer facts than the request implies. Add rows to that sheet and rerun; do not lower
+  the assert. **Row counts do not prove content**: `ws.max_row` counts a cell that was
+  merely styled, and is 1 on a truly empty sheet and never 0, so a header-only sheet
+  can report `4 rows` while holding nothing. Append values before styling anything.
+- A bare `Sheet` among the sheet names is the untouched default sheet, left as a
+  blank first tab in front of the data. Either is a failed turn even at `exitCode 0`
+  — the user gets a blank or near-blank workbook. Rebuild it with literal rows.
+- On an `AttributeError` from openpyxl the API name is wrong, and on a `TypeError`
+  about missing positional arguments a required argument was left out — fix either
+  against this file's examples. Do not retry the same call, and do not switch to a
+  shell.
+- `'MergedCell' object attribute 'value' is read-only` means the write hit a merged
+  non-anchor cell — write the range's top-left cell instead.
+- A formula cell that reads `None` or shows empty in a preview is not a bug —
+  this runtime computes nothing; the value appears when the user opens the file.
+  Do not rewrite the workbook to "fix" it.
+
+## Finish
+
+When `exitCode` is `0` and `attachments` lists the `.xlsx`, stop tool use and
+answer with one line: file name + the sheet/row summary from stdout. Exactly one
+successful `exec` per request.