slotdeck 0.1.0 → 0.1.1

package/docs/chat-tools.md

@@ -0,0 +1,253 @@
+# Chat tools
+
+`presentationTools` packages the planner as four tools for a chat model ("function calling"). The chat model
+talks to the person; the tools do the work; the person approves a plan before anything is written.
+
+```ts
+import { presentationTools, TOOL_NAMES, storeKeys, memoryStore } from 'slotdeck';
+import { directoryStore } from 'slotdeck/node';
+```
+
+## The four tools
+
+| Tool name | What it does | Model calls inside |
+| --- | --- | --- |
+| `plan_presentation` | Decides the slides, the layout of each and the point each makes. Writes nothing yet. | 1 |
+| `edit_presentation_plan` | Changes a plan by instruction. Returns a new plan with a new id. | 1 |
+| `create_presentation` | Writes the approved plan's content, makes its pictures, renders the file. | 1, plus repairs, plus one per photo |
+| `edit_presentation` | Changes a created presentation by instruction. Returns a new presentation with a new id. | 1 or 2, plus repairs |
+
+The intended conversation:
+
+1. The person asks for a deck. The chat model calls `plan_presentation`.
+2. The chat model shows the plan. The person asks for changes; the chat model calls `edit_presentation_plan`
+   as often as needed.
+3. The person approves. The chat model calls `create_presentation`.
+4. The person asks for changes to the result. The chat model calls `edit_presentation`.
+
+## Setting up
+
+```ts
+const tools = presentationTools({
+  template,                                     // from loadTemplate
+  llm,                                          // LlmProvider used inside the tools
+  store: directoryStore('/mnt/presentations'),  // where plans, decks, pictures and files are kept
+  images,                                       // optional ImageProvider; without it decks have no generated photos
+  icons,                                        // optional IconDef[]
+  assets,                                       // optional AssetDef[]
+  layout: 'adaptive',                           // optional; default 'strict'
+  fields: { organizationDepartment: 'Acme  |  Operations' }, // optional deck-level values every deck gets
+  numberPatterns: 'from-brief',                 // optional
+  thumbnail: (patternId) => `/static/thumbnails/${patternId}.png`, // optional address of a picture of each layout
+  newId: (kind) => `${kind}_${crypto.randomUUID()}`, // optional; default is a short random id
+  onProgress: (event, tool) => console.log(tool, event.stage), // optional
+});
+```
+
+The `llm` here is the model the tools use to plan and write. It can be the same model as the chat model or a
+different one.
+
+## Giving the tools to the chat model
+
+`tools.definitions` is an array of `{ name, description, parameters }`, where `parameters` is a JSON Schema
+object. Wrap it in whatever shape your chat model's API expects:
+
+```ts
+// One common shape:
+const declarations = tools.definitions.map((tool) => ({ type: 'function', ...tool }));
+
+// Another:
+const declarations = tools.definitions.map((tool) => ({ type: 'function', function: tool }));
+```
+
+When the chat model calls a tool, pass the name and the parsed arguments to `tools.call`:
+
+```ts
+const result = await tools.call(call.name, call.arguments, { signal });
+// result.output  -> send this back to the chat model as the tool's result (JSON, small, no binary data)
+// result.plan    -> the DeckPlan, when the tool made or changed one (for your own UI)
+// result.deck    -> the DeckSpec, when the tool made or changed one
+// result.pptx    -> the file bytes, when one was rendered (offer it as a download)
+```
+
+`call` does not throw for expected failures. A missing id, an unknown tool or a model failure comes back as
+`{ output: { error: "..." } }`, in words the chat model can act on. It throws only when `signal` was aborted.
+
+## Arguments and results of each tool
+
+### `plan_presentation`
+
+Arguments:
+
+| Name | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `topic` | string | yes | What the presentation is about, with every fact, figure and name the person gave. Numbers not stated here will not appear on slides. |
+| `slide_count` | integer 1 to 30 | no | Number of slides, when the person asked for one. |
+| `language` | string | no | BCP 47 tag, such as `he` or `en`. Defaults to the template's language. |
+| `image_density` | `none`, `low`, `medium`, `high` | no | How many slides carry a photo. Default `medium`. Forced to `none` when no photos can be made. |
+| `text_size` | `normal`, `large`, `x-large` | no | Size of body text. Default `normal`. |
+| `instructions` | string | no | Audience, tone and anything else to respect. |
+
+Output:
+
+```json
+{
+  "plan_id": "plan_dc7cfffab9",
+  "title": "Adopting a Rescue Dog",
+  "language": "en",
+  "slides": [
+    {
+      "number": 1,
+      "layout": "cover",
+      "layout_description": "Opening slide with the presentation's title and a subtitle.",
+      "purpose": "Introduce the guide.",
+      "thumbnail": "/static/thumbnails/cover.png"
+    }
+  ],
+  "next": "Show this plan to the user. Use edit_presentation_plan for changes and create_presentation once they approve."
+}
+```
+
+`thumbnail` is present only when the `thumbnail` option returns an address.
+
+### `edit_presentation_plan`
+
+Arguments: `plan_id` (string, required), `instruction` (string, required: what to change, in the person's words,
+with any new facts they gave).
+
+Output: the same shape as `plan_presentation` with a new `plan_id`, plus:
+
+```json
+{ "summary": "Added a table slide comparing three options before the closing slide.", "previous_plan_id": "plan_dc7cfffab9" }
+```
+
+### `create_presentation`
+
+Arguments: `plan_id` (string, required: the approved plan).
+
+Output:
+
+```json
+{
+  "presentation_id": "deck_851fbb9677",
+  "title": "Adopting a Rescue Dog",
+  "file": "pptx/deck_851fbb9677.pptx",
+  "slides": [{ "number": 1, "layout": "cover", "title": "Welcome Home Guide" }],
+  "plan_id": "plan_7e890671a8",
+  "warnings": ["slide 4 body: text is 230 characters; the slot fits about 211"]
+}
+```
+
+`file` is the store key of the rendered pptx. `warnings` is present only when there are any.
+
+### `edit_presentation`
+
+Arguments: `presentation_id` (string, required), `instruction` (string, required).
+
+Output: the same shape as `create_presentation` with a new `presentation_id`, plus:
+
+```json
+{ "summary": "Shortened the body text on slide 2 and made the title punchier.", "rewritten_slides": [2], "previous_presentation_id": "deck_851fbb9677" }
+```
+
+### Errors
+
+```json
+{ "error": "There is no plan with id \"plan_x\"" }
+```
+
+Other messages: `"topic" is required`, `There is no presentation with id "..."`, `Unknown tool "..."`, and the
+messages of `PlanError` and `DeckValidationError` (see [generating.md](generating.md)).
+
+## The store
+
+The tools keep everything in a `BlobStore`, so the chat model only ever handles ids and short summaries.
+
+```ts
+interface BlobStore {
+  get(key: string): Promise<Uint8Array | undefined>;
+  set(key: string, data: Uint8Array): Promise<void>;
+}
+```
+
+| Key | Content | Typical size |
+| --- | --- | --- |
+| `plan/<id>.json` | A plan: the brief and the slide list | 1 KB |
+| `deck/<id>.json` | A deck: all text, and for each picture its id and description | 4 KB |
+| `asset/<id>` | One generated picture | tens of KB to 1 MB |
+| `pptx/<id>.pptx` | The rendered file | hundreds of KB and up |
+
+`storeKeys.plan(id)`, `storeKeys.deck(id)`, `storeKeys.asset(id)` and `storeKeys.pptx(id)` build these keys, so
+your app can read what the tools saved:
+
+```ts
+const pptx = await store.get(storeKeys.pptx(presentationId)); // to serve a download later
+```
+
+Why pictures are kept apart: the deck JSON stays a few kilobytes of text, which is all a model ever sees, and a
+pptx can be rebuilt from the JSON and the pictures at any time. Icons and supplied assets are not stored, since
+your app already has them.
+
+Every change makes a new plan or deck under a new id. Earlier versions stay, so "undo" is just using the previous
+id.
+
+### Stores that come with the package
+
+```ts
+const store = memoryStore();                       // in memory: tests and short-lived processes; store.keys() lists keys
+const store = directoryStore('/mnt/presentations'); // a folder, such as a mounted volume; keys become file paths under it
+```
+
+### Writing your own
+
+Any object with `get` and `set` works: a bucket, a database table, a key-value service.
+
+```ts
+const store: BlobStore = {
+  async get(key) {
+    const row = await db.query('select data from blobs where key = $1', [key]);
+    return row ? new Uint8Array(row.data) : undefined;
+  },
+  async set(key, data) {
+    await db.query('insert into blobs (key, data) values ($1, $2) on conflict (key) do update set data = $2', [key, Buffer.from(data)]);
+  },
+};
+```
+
+`get` must resolve with `undefined` for a key that does not exist, not throw.
+
+## Showing a plan visually
+
+A plan lists a layout per slide. To show layouts as pictures, render the template's slides to images once (with
+any tool you have), name each picture after the pattern made from that slide, and return its address from the
+`thumbnail` option. The address is passed through to the chat model's output and is not fetched by slotdeck.
+
+## A complete loop
+
+```ts
+async function runTurn(messages) {
+  let reply = await chatModel.send({ messages, tools: declarations });
+  while (reply.toolCalls?.length) {
+    for (const call of reply.toolCalls) {
+      const result = await tools.call(call.name, call.arguments);
+      if (result.pptx) offerDownload(result.output.presentation_id, result.pptx);
+      messages.push({ role: 'tool', toolCallId: call.id, content: JSON.stringify(result.output) });
+    }
+    reply = await chatModel.send({ messages, tools: declarations });
+  }
+  return reply.text;
+}
+```
+
+`chatModel`, `offerDownload` and the message shape are your application's; only `tools.definitions` and
+`tools.call` come from slotdeck.
+
+## Guidance for the chat model's system prompt
+
+The tool descriptions already tell the model the order to work in. It helps to add, in your own system prompt:
+
+- Put every fact, figure and name the person gave into `topic`. Numbers that are not in `topic` will not be used.
+- Show the plan and wait for approval before calling `create_presentation`.
+- For a change to a finished presentation, call `edit_presentation` with the person's words; do not plan again
+  from scratch.
+- Refer to presentations and plans by id only. Never ask for or produce deck JSON.

package/docs/concepts.md

@@ -0,0 +1,126 @@
+# Concepts
+
+## Template
+
+An ordinary `.pptx` file: a deck of sample slides with filler text and sample pictures, as a designer hands it
+over. slotdeck never draws anything. It copies slides of the template and replaces the content of some of their
+shapes, so fonts, colours, backgrounds, logos and decorations are exactly the template's.
+
+A loaded template is `{ pkg, manifest }` (type `Template`), made by `loadTemplate(pptxBytes, manifest)`. Loading
+unzips the file once; keep the object and reuse it for every render.
+
+## Pattern
+
+One reusable slide layout. A pattern points at one slide of the template (`sourceSlide`, counted from 1) and has
+an `id` that decks use to ask for it. Several patterns may point at the same slide (see "derived patterns" in
+[layout-freedom.md](layout-freedom.md)).
+
+A slide of the template that is not named by any pattern is simply never used.
+
+## Slot
+
+One shape on a pattern's slide whose content a deck replaces. A slot has a `name` (what decks call it), the id of
+its shape, and a `kind`:
+
+| Kind | The shape on the template | A deck gives it |
+| --- | --- | --- |
+| `text` | A text box or a shape with text | A string, or an array with one string per paragraph |
+| `image` | A picture | `{ "asset": "<id>" }` naming picture bytes passed at render time |
+| `table` | A table | `{ "header": [...], "rows": [[...], ...] }` |
+| `chart` | A picture that stands where a chart goes | `{ "type", "categories", "series" }`, which becomes a native PowerPoint chart |
+
+Shapes that are not slots are copied untouched.
+
+## Manifest
+
+The JSON that lists a template's patterns and slots, with limits for each slot (how many characters fit, how
+many table columns). It is written once per template. Full reference: [manifest-format.md](manifest-format.md).
+
+The manifest is the contract between the template and everything else:
+
+- The renderer uses it to find shapes.
+- The validator uses it to check a deck.
+- The planner shows it to the language model, so the model can only choose patterns and slots that exist and
+  is told how much text each slot holds.
+
+## Deck
+
+The JSON that describes one presentation: an ordered list of slides, each naming a pattern and giving values for
+its slots. Full reference: [deck-format.md](deck-format.md).
+
+A deck is the source of truth. It holds no binary data, so it is small (a few kilobytes), safe to send to a
+model, and can be stored, compared, edited and rendered again at any time.
+
+## Deck fields
+
+Some text is the same on every slide, such as an organization or department line next to the logo. In the
+manifest such a slot has `deckField: "<field name>"`, and a deck gives the value once:
+
+```json
+{ "fields": { "organizationDepartment": "Acme  |  Operations" } }
+```
+
+A slide may still set that slot itself, which overrides the field for that slide.
+
+## Assets
+
+Pictures are passed to the renderer as a map from **asset id** to bytes (PNG, JPEG or GIF). A deck refers to a
+picture only by its id. There are three sources:
+
+| Source | Who provides it | Typical use |
+| --- | --- | --- |
+| Icons (`IconDef`) | Your app registers a set; the model picks by description | Pictograms on cards |
+| Supplied pictures (`AssetDef`) | Your app passes pictures it already has | A rendered diagram, a product photo, a chart image |
+| Generated pictures | An `ImageProvider` you plug in | Photos described by the model |
+
+A generated picture's reference keeps its description (`prompt`) in the deck, so the picture can be made again
+later, and its id is derived from that description, so the same description always maps to the same id.
+
+## Layout modes
+
+| Mode | Meaning |
+| --- | --- |
+| `strict` (default) | Every slot must have a value unless its policy says otherwise. Nothing on a slide disappears. |
+| `adaptive` | A slot marked optional (`"empty": "remove"`) may be left out, and its shape is then removed from the slide. |
+
+## What happens to a slot without a value
+
+Each slot has an `empty` policy in the manifest:
+
+| `empty` | Without a value |
+| --- | --- |
+| `error` (default) | The deck is invalid: the slot is required. |
+| `remove` | In `adaptive` layout the shape is removed. In `strict` layout the slot is required. |
+| `keep` | The template's own content stays. Use it for decoration that suits any content. |
+| `drop` | The shape is always removed, in any layout. Use it for decoration drawn for the sample content, such as a sticker on a sample photo. |
+
+A deck can also give `null` for a slot to leave it out explicitly; the shape is removed (allowed where the
+policy is `remove`, in `adaptive` layout).
+
+## Character budgets
+
+A text slot has `maxChars` (and optionally `maxParagraphs`). These are soft limits: text over the budget is
+reported as a **warning**, not an error, and is still rendered. The planner shows budgets to the model and sends
+a draft that exceeds them back for repair.
+
+A budget is an estimate of what fits the box. It cannot see line wrapping, so slots with several paragraphs
+should have budgets with room to spare.
+
+## Rows and grids of items
+
+A pattern can declare that some of its shapes form a row or a grid of like items (cards, figures, steps) and
+that a deck may choose how many there are. See [layout-freedom.md](layout-freedom.md).
+
+## Reading direction
+
+A template has a direction (`ltr` or `rtl`), and so has a deck. When they differ, text direction and alignment
+flip while shapes stay where they are. See [languages.md](languages.md).
+
+## Models are plugged in
+
+slotdeck defines two small interfaces and calls nothing else:
+
+- `LlmProvider.generateJson(request)` answers a prompt with JSON.
+- `ImageProvider.generateImage(request)` returns picture bytes.
+
+Adapters for Gemini are included. Anything else is a few lines: see [providers.md](providers.md).

package/docs/deck-format.md

@@ -0,0 +1,225 @@
+# Deck format
+
+A deck is a JSON object of type `DeckSpec`. It describes one presentation and contains no binary data.
+
+```ts
+import type { DeckSpec, SlideSpec, SlotValue, ImageRef, TableValue, ChartValue } from 'slotdeck';
+```
+
+## Complete example
+
+```json
+{
+  "version": 1,
+  "title": "A year of Riverbend Bike Share",
+  "language": "en",
+  "direction": "ltr",
+  "fields": { "organizationDepartment": "Riverbend Bike Share  |  Season review" },
+  "slides": [
+    {
+      "pattern": "cover",
+      "slots": { "title": "A year of Riverbend Bike Share", "subtitle": "What the 2025 season taught us" }
+    },
+    {
+      "pattern": "text-and-photo",
+      "slots": {
+        "title": "Bikes became part of the daily commute",
+        "body": ["Most rides used to be weekend outings.", "This year the busiest hour is eight on a weekday morning."],
+        "photo": { "asset": "photo-commute", "alt": "A commuter on a river path" }
+      }
+    },
+    {
+      "pattern": "icon-cards",
+      "items": 3,
+      "slots": {
+        "title": "Three changes for next season",
+        "card1Icon": { "asset": "clock" },
+        "card1Heading": "Longer hours",
+        "card1Text": "Bikes unlock from five in the morning.",
+        "card2Icon": { "asset": "shield" },
+        "card2Heading": "Safer docks",
+        "card2Text": "Every station gets lighting and a camera.",
+        "card3Icon": { "asset": "people" },
+        "card3Heading": "Group passes",
+        "card3Text": "One pass for up to five riders."
+      }
+    },
+    {
+      "pattern": "table",
+      "slots": {
+        "title": "The busiest stations",
+        "table": {
+          "header": ["Station", "Docks", "Rides a day"],
+          "rows": [["Tram Square", "24", "410"], ["River Gate", "18", "365"]]
+        }
+      }
+    },
+    {
+      "pattern": "chart-native",
+      "slots": {
+        "title": "Rides grew through the summer",
+        "chart": {
+          "type": "column",
+          "categories": ["Apr-May", "Jun-Jul", "Aug-Sep"],
+          "series": [
+            { "name": "2024", "values": [5, 9, 11] },
+            { "name": "2025", "values": [7, 15, 19] }
+          ]
+        },
+        "chartDescription": "Rides in thousands for each part of the season."
+      }
+    },
+    { "pattern": "closing", "slots": { "title": "Thank you" } }
+  ]
+}
+```
+
+The pattern ids and slot names in this example come from the demo template's manifest. Yours come from your own
+manifest.
+
+## `DeckSpec`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `version` | `1` | yes | Always the number 1. |
+| `slides` | `SlideSpec[]` | yes | The slides in order. Must not be empty. |
+| `title` | string | no | A name for the deck. Not placed on any slide by itself. |
+| `brief` | string | no | The request the deck was written from. `editDeck` uses it as background. |
+| `language` | string | no | BCP 47 tag of the deck's text, such as `en` or `he`. |
+| `direction` | `"ltr"` or `"rtl"` | no | Reading direction. Defaults to the template's. See [languages.md](languages.md). |
+| `fields` | object of strings | no | Values shared by every slide, by field name. See "Deck fields" below. |
+| `textScale` | number | no | Size of body text as a factor on the template's: `1` as designed, `1.25` large, `1.5` extra large. See [layout-freedom.md](layout-freedom.md). |
+
+## `SlideSpec`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `pattern` | string | yes | The `id` of a pattern in the manifest. |
+| `slots` | object | yes | Slot name to value. |
+| `items` | integer | no | Only for a pattern with a row or grid of items: how many items this slide has. Defaults to the number drawn on the template slide. Must be within the pattern's range. |
+
+## Slot values
+
+The value depends on the slot's kind in the manifest.
+
+### Text slot
+
+A string, or an array of strings with one entry per paragraph.
+
+```json
+"title": "Deliveries are faster"
+"body": ["First paragraph.", "Second paragraph."]
+"body": "First paragraph.\nSecond paragraph."
+```
+
+- A newline inside a string starts a new paragraph, so the last two lines above mean the same.
+- Empty paragraphs are dropped.
+- Each paragraph takes its formatting (font, size, colour, bullet) from the template paragraph in the same
+  position. When there are more paragraphs than the template slot has, the last template paragraph's formatting
+  is reused. This is how a bulleted list works: the template shape has bulleted paragraphs, and the deck gives
+  one string per bullet.
+- Do not put bullet characters, numbering or Markdown in the text. The text is used literally.
+- Limits: `maxChars` counts all characters of all paragraphs together; `maxParagraphs` counts paragraphs. Both
+  are soft (a warning, not an error).
+
+### Image slot
+
+An `ImageRef`:
+
+```json
+"photo": { "asset": "photo-commute", "alt": "A commuter on a river path" }
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `asset` | string | yes | The id of the picture. The bytes are passed to `renderDeck` in `options.assets` under this id. |
+| `alt` | string | no | Alternative text for screen readers, stored on the picture. |
+| `prompt` | string | no | A description the picture can be generated from. Written by the planner for photos; lets the picture be made again later. |
+
+How the picture is placed depends on the slot (`fit` in the manifest):
+
+- `cover` (the default for photos): the picture fills the frame and is cropped at the edges, keeping its
+  proportions. The frame's shape (rounded corners, a circle) is kept.
+- `contain` (the default for icons and graphics): the whole picture is shown, centred, inside the frame's
+  area, keeping its proportions.
+
+Supported formats are PNG, JPEG and GIF.
+
+### Table slot
+
+A `TableValue`:
+
+```json
+"table": { "header": ["Station", "Docks"], "rows": [["Tram Square", "24"], ["River Gate", "18"]] }
+```
+
+- `header` sets the number of columns. Every row must have exactly that many cells, or the deck is invalid.
+- Cells are strings. Numbers must be written as strings (`"24"`).
+- The template table's first row supplies the header style and its following rows supply the body styles in
+  turn (so banding is kept). Columns share the table's width equally.
+- Limits (`maxColumns`, `maxRows`, `maxCellChars`) are soft.
+
+### Chart slot
+
+A `ChartValue`, which becomes a native PowerPoint chart that can be changed with Edit Data:
+
+```json
+"chart": {
+  "type": "column",
+  "categories": ["Q1", "Q2", "Q3"],
+  "series": [{ "name": "Revenue", "values": [12, 15, 19] }],
+  "format": "number"
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `type` | `"column"`, `"bar"`, `"line"` or `"pie"` | yes | `column` has vertical bars, `bar` horizontal ones. |
+| `categories` | string[] | yes | Labels along the axis, or the names of the pie slices. At least one. |
+| `series` | `{ name, values }[]` | yes | At least one. Each `values` array must have exactly one number per category. A pie takes exactly one series. |
+| `format` | `"number"` or `"percent"` | no | `percent` shows values with a percent sign (45 is shown as 45%). Any other value is ignored with a warning. |
+
+Bars start at zero. Colours and fonts come from the manifest.
+
+### Leaving a slot out
+
+- Omit the slot, or give an empty string: the slot has no value, and its `empty` policy decides what happens
+  (see [concepts.md](concepts.md)).
+- Give `null`: the slot is explicitly left out and its shape is removed. This needs `layout: 'adaptive'` and a
+  slot that is not required.
+
+A name in `slots` that the pattern does not have is ignored with a warning.
+
+## Deck fields
+
+A text slot whose manifest entry has `"deckField": "x"` takes its value from `deck.fields.x` when the slide does
+not give that slot a value itself. Use it for text that repeats on every slide.
+
+```json
+{ "fields": { "organizationDepartment": "Acme  |  Operations" }, "slides": [ ... ] }
+```
+
+If a required slot depends on a field that the deck does not give, validation reports `this slot is required`
+for that slot on every slide that has it.
+
+## Items of a row or grid
+
+For a pattern with a row or grid of items, `items` says how many. The slots of each item are numbered:
+`card1Heading`, `card2Heading`, and so on. With `"items": 3`, give slots for items 1 to 3 only. With more items
+than the template slide draws, the extra items are copies of the last one and have the next numbers
+(`card5Heading`, ...).
+
+The first item is the first in the deck's reading direction. In a right-to-left deck on a left-to-right
+template, `card1...` appears at the right.
+
+## Checking a deck
+
+```ts
+import { validateDeck } from 'slotdeck';
+
+const issues = validateDeck(manifest, deck, { layout: 'adaptive', assets: ['photo-commute', 'clock'] });
+// [{ severity: 'error' | 'warning', slide?: number, slot?: string, message: string }]
+```
+
+Errors make `renderDeck` throw. Warnings do not. Every message is listed in
+[troubleshooting.md](troubleshooting.md).