slotdeck 0.1.0 → 0.1.2

package/docs/changelog.md

@@ -0,0 +1,107 @@
+# Changelog
+
+What changed in each version, newest first, with what to do when upgrading. The version you have installed is
+in `node_modules/slotdeck/package.json`.
+
+## 0.1.2
+
+### Added
+
+- **Text-only decks.** `textOnly: true` on a brief, or `text_only: true` in the `plan_presentation` tool, plans
+  every slide as plain text: a title with paragraphs or a list, and no pictures, icons, cards, figures, tables
+  or charts. The planner is then offered only the template's plain text patterns, so no other kind can be
+  chosen. See "Asking for a kind of slide" in [generating.md](generating.md).
+- **Wishes about the kind of slides are honoured.** A wish stated in words in the brief or in an edit
+  instruction ("text only", "no tables", "only cards") now decides which patterns may be used and comes before
+  variety. It works when planning, when changing a plan, and when changing a finished deck. The pattern list
+  the model reads marks each plain text pattern with "Plain text.".
+- **`isPlainText(pattern)`** tells whether a pattern is plain text, for an app that wants to show or check
+  which layouts a text-only deck can use.
+- **Larger body text for a whole template.** `textScale` on the manifest enlarges the body text of every deck
+  made from the template (`1.3` turns 9 pt into about 12 pt). Budgets shrink to match in validation, in what
+  the planner shows the model, and in `sampleDeck`. Set it by hand or with
+  `changeManifest(template, [{ op: 'setManifest', textScale: 1.3 }])`; `editManifest` understands requests such
+  as "make body text 20 percent larger". See "Larger text for a whole template" in
+  [layout-freedom.md](layout-freedom.md).
+- **`maxOutputTokens` on requests to the model.** The planner passes a ceiling for each answer with every
+  request it makes. See "Runaway answers" in [providers.md](providers.md).
+- **`effort: 'low'` on planning requests.** Calls that choose and arrange rather than write (the outline, a
+  change to a plan, the first step of an edit) ask for light reasoning.
+
+### Changed
+
+- **Table text and chart labels follow the text scale**, where the manifest states their size
+  (`bodyText.size`, `headerText.size`, `text.size`). This applies to a deck's own text size (`textScale`,
+  `textSize`, `text_size`) as well as to the new template scale, and a table cell then holds fewer characters.
+  Before, tables and charts kept their size when a deck asked for larger text.
+- **The Gemini adapter limits the output of every request.** The limit is the request's estimate plus 8,192
+  tokens for reasoning, or 24,576 when the request has none, or the adapter's `maxOutputTokens` when set.
+  Before, a request had no limit unless `maxOutputTokens` was set.
+- **The Gemini adapter sends a request once more** when the answer was cut off at the limit, after a server
+  error (500 to 504), and when the service's recitation filter blocks an ordinary answer. A bad key, a quota or
+  a bad request is not repeated.
+- **The Gemini adapter uses thinking level `low` for requests with `effort: 'low'`**, unless `thinkingLevel`
+  is set on the adapter. Planning calls became several times faster: a plan takes about 5 seconds.
+- The per-slide sentence of a plan is asked for as "a single sentence of at most 25 words".
+
+### Fixed
+
+- **A request for a text-only presentation gave cards and tables.** The planner was told to vary the layouts
+  and nothing said that a wish about the kind of slides comes first; and "no pictures" was the most that
+  reached it. Fixed by the two additions above.
+- **A model call could hang for minutes.** With its default reasoning the model sometimes ran away inside one
+  text field of a planning answer and wrote tens of thousands of tokens. Measured on a text-only plan: 6 of 24
+  calls with default reasoning, none of 18 with light reasoning. Planning calls now use light reasoning, every
+  call has an output limit, and a cut-off answer is asked for once more.
+
+### Upgrading from 0.1.1
+
+No code has to change. To benefit:
+
+- **Chat assistants:** `plan_presentation` has a new optional argument, `text_only`. It is in
+  `tools.definitions`, so it reaches the chat model when the definitions are passed as before. If your system
+  prompt lists the tool's arguments, add it, and tell the model that "no pictures" (`image_density: "none"`)
+  still allows cards, tables and charts.
+- **Small body text:** if decks from your template have body text that is too small, add `"textScale": 1.3`
+  (or another factor) to the manifest, render `sampleDeck` once to see that everything still fits, and keep the
+  manifest. A manifest with `textScale` is ignored by 0.1.1 and earlier, which show the designed size.
+- **Your own `LlmProvider`:** requests now carry two optional fields, `maxOutputTokens` and `effort`. A provider
+  that ignores them keeps working. To get the protection and the speed, pass `maxOutputTokens` on as your
+  model's output limit (adding room for reasoning tokens if your model counts them in the same limit), use
+  light reasoning when `effort` is `'low'`, and retry once when an answer is cut off. See "Runaway answers" in
+  [providers.md](providers.md).
+- **Tables with larger text:** a deck that asks for larger text now enlarges table text too, where the
+  manifest states its size, and gives cells a smaller budget. A deck stored with `textScale` renders with
+  larger table text than before.
+
+## 0.1.1
+
+### Added
+
+- **Documentation inside the package.** The `docs/` folder ships with the npm package
+  (`node_modules/slotdeck/docs/`), in plain Markdown with no links to the internet, so it can be read where
+  there is no network access. Start at [README.md](README.md).
+
+### Changed
+
+- **Unknown chart format.** `validateDeck` warns about a chart `format` other than `"number"` or `"percent"`
+  (`chart format "x" is not known and is ignored`). Before, it was ignored silently.
+
+### Upgrading from 0.1.0
+
+Nothing to change.
+
+## 0.1.0
+
+First release.
+
+- **Renderer:** `loadTemplate`, `renderDeck`, `validateDeck`, `extractAssets`. Text, pictures, tables and
+  native charts; rows and grids with a variable number of items; larger text on request; derived patterns.
+- **Planner and editor:** `generateDeck`, `planDeck`, `planOutline`, `editPlan`, `writeDeck`, `editDeck`,
+  `planEdit`, `resolveAssets`, with any model through `LlmProvider` and `ImageProvider`.
+- **Chat tools:** `presentationTools` with `plan_presentation`, `edit_presentation_plan`,
+  `create_presentation` and `edit_presentation`, and stores (`memoryStore`, `directoryStore`).
+- **Gemini adapters:** `gemini`, `geminiImages`, `vertexEndpoint`.
+- **Reading direction:** right-to-left decks on left-to-right templates and the reverse.
+- **Template studio:** `draftManifest`, `checkManifest`, `sampleDeck`, `changeManifest`, `editManifest`,
+  `studioView`, `describeManifest`, `inspectTemplate`.

package/docs/chat-tools.md

@@ -0,0 +1,257 @@
+# 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`. |
+| `text_only` | boolean | no | `true` when the person asks for a presentation of text only. Every slide is then plain text: a title with paragraphs or a list, with no pictures, icons, cards, figures, tables or charts. Only the template's plain text layouts are used. |
+| `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.
+- Pass wishes about the kind of slides on, in the person's words ("no tables", "only cards"), in `topic` or
+  `instructions`. For a presentation of text only, set `text_only: true`: "no pictures" alone
+  (`image_density: "none"`) still allows cards, tables and charts.
+- 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).