Files
TREK/server/src/nest/assistant/assistant-book-preview.ts
T
Maurice 5651c11803 feat(assistant): the book designer works from a brief, with archetype covers, lively spreads and stickers
- design_book takes a brief (energy, decoration, collages, theme), a cover
  archetype and a cover lockup, and pages.overrides that give single pages of
  the plan another beat or layout. Directives written before parse as they
  did, and a design asked for none of it is composed exactly as before.
- The engine composes the seven cover archetypes from the book's own photos,
  words, theme faces and colours, lockups, shapes and stickers, varied by the
  seed: spine band, poster pop, cut-out, illustrated postcard, grid and
  badge, minimal serif and stamp collage. A title the directives give a
  display tier is held to it, and the notes say when a band, a badge or a
  stamp holds it smaller or a cover leaves a layout out.
- A lively or loud book turns two in five hero and grid spreads into
  collages, script overlays, badge grids, stamp rows or two-tone splits, the
  first of them always, turns and frames the prints of its other pages, sets
  its cover title larger and takes one or two, or three to six, stickers of
  its theme's motifs a spread, never over words, a photo's detail or the
  fold. A calm book asked for collages gets them and nothing else.
- Every turn the engine gives a print or a sticker stays within what the
  brief's energy takes, a calm book's within its theme's own, so a design is
  never judged against its own brief.
- New checks name a flat cover, a page without a lead, colours or faces off
  the theme and, for a design made with a brief, a book livelier or calmer
  than it asked, on the pages the design made and on a page revised in the
  draft. Page edits answer with the art checks too, and the assistant's
  cards name them in every language.
- list_book_assets lists the shapes, faces, lockups, themes and patterns
  beside the stickers, and the Studio's shape groups and photo frames are one
  list the assistant reads too.
- The Studio prompt gains an index of themes, archetypes and faces and JSON
  recipes of the elements to add and style for each cover and three lively
  spreads, and a turn that designs the book may preview sixteen pages, still
  three images a request; a viewer is told of none of it.
2026-10-24 01:14:03 +00:00

149 lines
7.6 KiB
TypeScript

import type { AiToolSpec } from '../ai-connections/ai-chat-client.interface';
import type { AgentToolPort, AgentToolRun } from './assistant-agent';
import { PREVIEW_BOOK_PAGE_TOOL } from './assistant-tools.constants';
import type { TurnVision } from './assistant-vision';
import { ASSISTANT_PAGE_IMAGE, previewBookPageRequestSchema } from '@trek/shared';
/**
* `preview_book_page`, offered in every Studio turn beside the session's own
* tools (journey-studio.md 4.3, step 2): a read that answers one page in words
* with its findings, as it stands or as an `edit_book_page` with the given
* ops would leave it, and for a model that reads images the page as the
* Studio draws it (AssistantVision). Nothing is saved; the change itself is
* proposed afterwards like any other.
*
* Its `ops` take exactly the schema `edit_book_page` takes in this session,
* so a preview and the edit it checks are one shape. A session without that
* tool (a viewer's) previews pages as they stand. Previews are capped per
* step and per turn, since each can wait seconds for the Studio and costs a
* model an image; a turn that designs the whole book (design_book or
* revise_book_design came back with a draft, or a draft was looked at) may
* look at twice as many. Only a session that edits the book designs it.
*/
const EDIT_TOOL = 'edit_book_page';
/** What a look answers, whoever looks. */
const SEES =
'its elements, its findings (overlaps, words past their frame, empty frames, low resolution, content in the ' +
'fold) and, when your model reads images, the page as the Studio draws it, with photos of other contributors ' +
'left as empty frames.';
const CAPS =
`At most ${ASSISTANT_PAGE_IMAGE.previewsPerStep} previews per step and ${ASSISTANT_PAGE_IMAGE.previewsPerTurn} ` +
'per turn.';
/** An editor's caps: a turn that designs the book may look at more pages. A viewer is offered none of those tools. */
const DESIGN_CAPS =
`At most ${ASSISTANT_PAGE_IMAGE.previewsPerStep} previews per step and ${ASSISTANT_PAGE_IMAGE.previewsPerTurn} ` +
`per turn, ${ASSISTANT_PAGE_IMAGE.previewsPerDesignTurn} in a turn that designs the book (design_book, ` +
'revise_book_design or a draft looked at).';
/** The tools that put a whole-book design in play for the rest of the turn, and with it the larger preview budget. */
const DESIGN_TOOLS: ReadonlySet<string> = new Set(['design_book', 'revise_book_design']);
/** For a session that may change the book: a proposed edit and a design draft can be looked at too. */
const EDITOR_DESCRIPTION =
`Look at one page of the book before you change it or after: ${SEES} With ops (the same ops edit_book_page ` +
'takes) you see the page as that edit would leave it, without saving anything. Preview a page once before you ' +
'propose an edit of it, fix what the findings or the image show, then propose the edit. With designId (from ' +
`design_book) you see the page of that design draft instead of the book. ${DESIGN_CAPS}`;
/** For a session without edit_book_page (a viewer's): the page as it stands, nothing it could not ask for. */
const READER_DESCRIPTION = `Look at one page of the book as it stands: ${SEES} ${CAPS}`;
/** The draft a preview may look at instead of the book, by design_book's design_id. */
const DESIGN_ID = { type: 'string', pattern: '^[\\w-]{1,40}$', description: 'A design draft, by its design_id.' };
const TOO_MANY =
`Too many previews: at most ${ASSISTANT_PAGE_IMAGE.previewsPerStep} in one step and ` +
`${ASSISTANT_PAGE_IMAGE.previewsPerTurn} in one turn. Propose the edit and let its card show the findings.`;
/** The same for an editor, whose turn may have a book design in play. */
const TOO_MANY_DESIGN =
`Too many previews: at most ${ASSISTANT_PAGE_IMAGE.previewsPerStep} in one step and ` +
`${ASSISTANT_PAGE_IMAGE.previewsPerTurn} in one turn (${ASSISTANT_PAGE_IMAGE.previewsPerDesignTurn} while a book ` +
'design is in play). Propose the edit and let its card show the findings.';
/** The session's `edit_book_page` ops schema, when it has that tool. */
function editOps(specs: readonly AiToolSpec[]): unknown {
const edit = specs.find((spec) => spec.name === EDIT_TOOL);
return ((edit?.parameters.properties ?? {}) as Record<string, unknown>).ops;
}
/** The preview's spec, its ops taken from the session's `edit_book_page` when it has that tool. */
function previewSpec(specs: readonly AiToolSpec[]): AiToolSpec {
const edit = specs.find((spec) => spec.name === EDIT_TOOL);
const ops = editOps(specs);
// Shared parts the ops point at, where the schema keeps them apart.
const shared: Record<string, unknown> = {};
for (const key of ['$defs', 'definitions']) if (edit?.parameters[key]) shared[key] = edit.parameters[key];
return {
name: PREVIEW_BOOK_PAGE_TOOL,
description: ops ? EDITOR_DESCRIPTION : READER_DESCRIPTION,
parameters: {
type: 'object',
properties: {
spreadId: { type: 'string', pattern: '^[\\w-]{1,40}$', description: 'The page, by its id from get_book.' },
// A design draft is an editor's: a session without the edit tool previews the book only.
...(ops ? { ops, designId: DESIGN_ID } : {}),
},
required: ['spreadId'],
additionalProperties: false,
...(ops ? shared : {}),
},
};
}
/** The session's tools with the preview beside them, answered through the turn's vision. */
export function withPagePreview(tools: AgentToolPort, vision: TurnVision): AgentToolPort {
let inStep = 0;
let inTurn = 0;
// Only a session that may change the book designs it; a viewer keeps the plain budget whatever it passes.
let edits = false;
// Once the turn designs the book, it may look at more pages: a design is judged on many.
let designing = false;
const preview = async (args: Record<string, unknown>): Promise<AgentToolRun> => {
const perTurn = designing ? ASSISTANT_PAGE_IMAGE.previewsPerDesignTurn : ASSISTANT_PAGE_IMAGE.previewsPerTurn;
if (inStep >= ASSISTANT_PAGE_IMAGE.previewsPerStep || inTurn >= perTurn) {
return { ok: false, value: edits ? TOO_MANY_DESIGN : TOO_MANY };
}
const parsed = previewBookPageRequestSchema.safeParse(args);
if (!parsed.success) {
const issue = parsed.error.issues[0];
const detail = issue ? [issue.path.join('.'), issue.message].join(' ') : '';
return { ok: false, value: `Invalid arguments: ${detail}` };
}
inStep += 1;
inTurn += 1;
const { spreadId, ops, designId } = parsed.data;
const run = await (designId ? vision.look(spreadId, ops, designId) : vision.look(spreadId, ops));
// A draft looked at puts the design in play, once the look found it.
if (edits && designId && run.ok) designing = true;
return run;
};
return {
// The loop asks for the specs once at the start of every step: a new step may preview again.
specs: () => {
inStep = 0;
const listed = tools.specs();
edits = editOps(listed) !== undefined;
return [...listed, previewSpec(listed)];
},
kindOf: (name) => (name === PREVIEW_BOOK_PAGE_TOOL ? 'read' : tools.kindOf(name)),
pinArgs: (name, args) => {
if (name !== PREVIEW_BOOK_PAGE_TOOL) return tools.pinArgs(name, args);
// The journey is the conversation's; the preview takes no other argument for it.
const { journeyId: _journeyId, ...rest } = args;
return { args: rest };
},
call: async (name, args) => {
if (name === PREVIEW_BOOK_PAGE_TOOL) return preview(args);
const run = await tools.call(name, args);
// A design tool puts the design in play once its run came back with a draft.
if (edits && run.ok && DESIGN_TOOLS.has(name)) designing = true;
return run;
},
};
}