Draw on
diff --git a/public/js/myResources.js b/public/js/myResources.js
index f5f41b6a..33ef64e9 100644
--- a/public/js/myResources.js
+++ b/public/js/myResources.js
@@ -170,6 +170,31 @@
}
if (themeRow) themeRow.hidden = themes.length < 2;
+ // The shape of the session. "Free" is the default: the model lays the
+ // deck out as it sees fit, which is what every deck was until now.
+ var formatSelect = document.getElementById('mr-format');
+ var formatRow = document.getElementById('mr-format-row');
+ var formats = Array.isArray(data.formats) ? data.formats : [];
+ if (formatSelect && formats.length) {
+ var chosenFormat = formatSelect.value;
+ formatSelect.textContent = '';
+ var free = document.createElement('option');
+ free.value = ''; free.textContent = 'Free — let the model choose';
+ formatSelect.appendChild(free);
+ formats.forEach(function (f) {
+ var option = document.createElement('option');
+ option.value = f.id;
+ option.textContent = f.name + (f.length ? ' · ' + f.length : '');
+ formatSelect.appendChild(option);
+ });
+ if (chosenFormat && formats.some(function (f) { return f.id === chosenFormat; })) {
+ formatSelect.value = chosenFormat;
+ }
+ describeFormat(formats);
+ formatSelect.onchange = function () { describeFormat(formats); };
+ }
+ if (formatRow) formatRow.hidden = !formats.length;
+
// Hidden entirely unless an administrator enabled it, so an option
// never appears that someone could tick and then be refused. Both
// groups are driven from the same answer: Generate and Modify offer
@@ -240,6 +265,17 @@
box.hidden = false;
}
+ // Says who the chosen format is for and how long it runs.
+ function describeFormat(formats) {
+ var select = document.getElementById('mr-format');
+ var hint = document.getElementById('mr-format-hint');
+ if (!select || !hint) return;
+ var chosen = formats.filter(function (f) { return f.id === select.value; })[0];
+ hint.textContent = chosen
+ ? [chosen.audience ? 'For ' + chosen.audience : '', chosen.description || ''].filter(Boolean).join('. ')
+ : 'The layouts are chosen slide by slide with no fixed order of parts.';
+ }
+
// Says what the chosen theme is for, which is the part a name cannot carry.
function describeTheme(themes) {
var select = document.getElementById('mr-theme');
@@ -281,6 +317,7 @@
useCorpus: corpusBox && corpusBox.checked === false ? 'false' : 'true',
model: (document.getElementById('mr-model') || {}).value || '',
theme: (document.getElementById('mr-theme') || {}).value || '',
+ format: (document.getElementById('mr-format') || {}).value || '',
withImages: (document.getElementById('mr-with-images') || {}).checked ? 'true' : 'false',
withWebSearch: (document.getElementById('mr-web-search') || {}).checked ? 'true' : 'false',
withPubmed: (document.getElementById('mr-pubmed') || {}).checked ? 'true' : 'false'
diff --git a/src/routes/myResources.js b/src/routes/myResources.js
index c37805a8..4b7c8592 100644
--- a/src/routes/myResources.js
+++ b/src/routes/myResources.js
@@ -24,6 +24,7 @@ var { callAI } = require('../utils/ai');
var learningRetrieval = require('../utils/learningRetrieval');
var resourceImages = require('../utils/resourceImages');
var deckSchema = require('../utils/deckSchema');
+var deckFormats = require('../utils/deckFormats');
var deckSample = require('../utils/deckSample');
var deckBuild = require('../utils/deckBuild');
var deckReview = require('../utils/deckReview');
@@ -165,6 +166,10 @@ function buildPrompt(opts) {
'audience (pediatrics / primary care).\n\nTOPIC: ' + opts.topic + '\n' + detailsBlock(opts) +
grounding + findings + '\n' +
deckSchema.instructions(opts.slideCount, opts.figureCount) +
+ // The shape of the session, after the vocabulary it is built from: a
+ // journal club and a board review are not the same deck with different
+ // colours, and without this the model writes one lecture shape for both.
+ (opts.format ? '\n\n' + deckFormats.instructions(opts.format) : '') +
(opts.refinement ? '\n\nAdditional instructions: ' + opts.refinement + '\n' : '') +
figures;
}
@@ -253,6 +258,9 @@ router.get('/my-resources/options', async function (req, res) {
themes: deckSchema.themes().map(function (t) {
return { id: t.id, name: t.name, description: t.description || '' };
}),
+ // The shape of the session — journal club, morning report, board
+ // review — as distinct from its look.
+ formats: deckFormats.catalogue(),
webSearchAvailable: await webSearch.isAvailable(),
pubmedAvailable: await pubmedSearch.isAvailable()
});
@@ -346,6 +354,7 @@ router.post('/my-resources/generate', async function (req, res) {
literature: sources.literature, webFindings: sources.webFindings,
searchedAndFoundNothing: sources.searchedAndFoundNothing,
wantsImages: wantsImages, deckMode: deckMode,
+ format: deckMode ? deckFormats.formatId(req.body.format) : '',
figureCount: wantsImages ? (resourceImages.requestedCount(refinement) || 0) : 0,
slideCount: clampInt(req.body.slideCount, 3, 30, 8),
wordCount: clampInt(req.body.wordCount, 200, 3000, 800)
@@ -399,6 +408,9 @@ router.post('/my-resources/generate', async function (req, res) {
// Chosen by the author, not the model: a theme is a look, and the person
// making the deck is the one who knows the room it will be shown in.
if (deck) deck.theme = deckSchema.themeId(req.body.theme);
+ // The format travels with the deck so a later revision keeps the shape it
+ // was written in.
+ if (deck) deck.format = deckFormats.formatId(req.body.format);
reportVocabularyGaps(vocabularyGaps, topic);
// Why a deck became plain slides, when it did. Reported to the caller as
// well as logged: the fallback produces a usable but plainer deck, and
@@ -997,6 +1009,7 @@ router.post('/my-resources/:id/refine', async function (req, res) {
'INSTRUCTION: ' + instructions + illustration + material + sight +
'\n\nThe layouts available are:\n' + deckSchema.instructions(
(existingDeck.slides || []).length, 0) +
+ (existingDeck.format ? '\n\n' + deckFormats.instructions(existingDeck.format) : '') +
'\n\nDECK JSON:\n' + JSON.stringify({ slides: existingDeck.slides })
: 'Revise the following Pandoc markdown according to the instruction. ' +
'Return ONLY the complete revised markdown, no commentary, no code fences. ' +
@@ -1045,6 +1058,8 @@ router.post('/my-resources/:id/refine', async function (req, res) {
// The look is the author's, not the model's: a modification never
// resets the theme. The column keeps it too, but the two should agree.
revisedDeck.theme = existingDeck.theme || existing.theme || revisedDeck.theme;
+ // And the shape it was written in.
+ revisedDeck.format = existingDeck.format || revisedDeck.format;
// Draw whatever the revised deck asked for, the same way generating does,
// so each new figure belongs to the slide that wanted it.
if (sources.wantsImages) {
diff --git a/src/utils/deckFormats.js b/src/utils/deckFormats.js
new file mode 100644
index 00000000..a8003210
--- /dev/null
+++ b/src/utils/deckFormats.js
@@ -0,0 +1,88 @@
+// ============================================================
+// DECK FORMATS
+// ============================================================
+// The shape of a teaching session, as distinct from its look.
+//
+// A theme says what a deck looks like; the slide vocabulary says what one slide
+// can be. Neither says what a journal club *is* — a PICO question, then the
+// methods, then the appraisal, then the bottom line — or that a board-review
+// session runs in cycles of case, question, answer. Left to itself the model
+// writes the same lecture shape for everything, however the layouts vary.
+//
+// A format is that sequence, read from `assets/deck-formats.json`, distilled
+// from how real departments run each session. Its parts name the layouts they
+// are usually drawn with, from the same vocabulary the schema offers, and a
+// part marked repeatable may be used as many times as the material needs — the
+// format is a recipe, not a slide count. The model still writes the deck in
+// the same JSON the renderer reads; the format only tells it what order the
+// parts come in and what good looks like at each.
+// ============================================================
+
+var fs = require('fs');
+var path = require('path');
+
+var cache = null;
+function formats() {
+ if (cache) return cache;
+ try {
+ var file = path.join(__dirname, '..', '..', 'assets', 'deck-formats.json');
+ cache = JSON.parse(fs.readFileSync(file, 'utf8')).formats || [];
+ } catch (e) { cache = []; }
+ return cache;
+}
+
+// An id the catalogue knows, or '' — a deck must never claim a format that
+// does not exist.
+function formatId(value) {
+ var id = String(value || '').trim();
+ if (!id) return '';
+ return formats().some(function (f) { return f.id === id; }) ? id : '';
+}
+
+function byId(id) {
+ return formats().filter(function (f) { return f.id === id; })[0] || null;
+}
+
+// The block given to the model, after the layout vocabulary. Prose, for the
+// same reason the vocabulary is prose: the failure to avoid is a dull deck
+// that follows the letter of a schema.
+function instructions(id) {
+ var format = byId(formatId(id));
+ if (!format) return '';
+ var lines = [
+ 'FORMAT: this is a ' + format.name + (format.audience ? ' for ' + format.audience : '') + '.',
+ format.length ? 'Typical length: ' + format.length + '.' : '',
+ 'Its parts, in this order:'
+ ];
+ (format.sequence || []).forEach(function (part, i) {
+ var layouts = Array.isArray(part.layouts) && part.layouts.length
+ ? ' Usually "' + part.layouts.join('" or "') + '" slides.' : '';
+ lines.push(' ' + (i + 1) + '. ' + part.part + (part.purpose ? ' — ' + part.purpose : '') + '.' +
+ layouts + (part.guidance ? ' ' + part.guidance : '') +
+ (part.repeat ? ' (repeatable)' : ''));
+ });
+ lines.push('A part marked repeatable may be used more than once — once per case, event or question —');
+ lines.push('and a run of repeatable parts repeats as a unit, as many times as the material needs.');
+ lines.push('Leave out a part the material does not have. Keep the order between parts.');
+ lines.push('Every slide is still one of the types above.');
+ if (Array.isArray(format.pitfalls) && format.pitfalls.length) {
+ lines.push('What this format goes wrong on: ' + format.pitfalls.join('; ') + '.');
+ }
+ return lines.filter(Boolean).join('\n');
+}
+
+// What the picker shows: never the sequence itself, which is the model's
+// brief, only what the format is for.
+function catalogue() {
+ return formats().map(function (f) {
+ return {
+ id: f.id,
+ name: f.name,
+ audience: f.audience || '',
+ description: f.description || '',
+ length: f.length || ''
+ };
+ });
+}
+
+module.exports = { formats: formats, formatId: formatId, instructions: instructions, catalogue: catalogue };
diff --git a/src/utils/deckSchema.js b/src/utils/deckSchema.js
index c631a878..84779746 100644
--- a/src/utils/deckSchema.js
+++ b/src/utils/deckSchema.js
@@ -226,6 +226,9 @@ function normalise(raw, gaps) {
// does not know would silently fall back, and a stored deck would then
// claim a theme it never had.
theme: themeId(deck.theme),
+ // The shape it was written in, kept the same way and for the same reason:
+ // a revision must not lose it, and it must name a format that exists.
+ format: require('./deckFormats').formatId(deck.format),
slides: slides
};
}
diff --git a/test/deck-formats.test.js b/test/deck-formats.test.js
new file mode 100644
index 00000000..2a29baed
--- /dev/null
+++ b/test/deck-formats.test.js
@@ -0,0 +1,70 @@
+// A deck has a shape as well as a look: a journal club runs PICO → methods →
+// appraisal → bottom line, a board review runs in case → question → answer
+// cycles. The format is a recipe the model follows and may repeat, never a
+// slide type of its own.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const read = f => fs.readFileSync(path.join(__dirname, '..', f), 'utf8');
+const deckFormats = require('../src/utils/deckFormats');
+const deckSchema = require('../src/utils/deckSchema');
+const catalogue = JSON.parse(read('assets/deck-formats.json')).formats;
+const LAYOUTS = ['title', 'section', 'bullets', 'two', 'compare', 'table', 'callout', 'question', 'figure', 'image', 'flow', 'custom'];
+
+test('every format is complete and speaks only the slide vocabulary', () => {
+ assert.ok(catalogue.length >= 5, 'a picker of a few is not a choice');
+ for (const format of catalogue) {
+ for (const key of ['id', 'name', 'audience', 'description', 'sequence']) {
+ assert.ok(format[key], format.id + ' is missing ' + key);
+ }
+ assert.ok(format.sequence.length >= 3, format.id + ' has too few parts');
+ for (const part of format.sequence) {
+ assert.ok(part.part && part.purpose, format.id + ' has a part without a name or purpose');
+ for (const layout of part.layouts || []) {
+ assert.ok(LAYOUTS.includes(layout), format.id + ' names a layout the renderer cannot draw: ' + layout);
+ }
+ }
+ assert.ok(format.sequence.some(p => p.repeat), format.id + ' has no part the model may reuse');
+ }
+ const ids = catalogue.map(f => f.id);
+ assert.equal(ids.length, new Set(ids).size, 'format ids must be unique');
+});
+
+test('the brief lists the parts in order, says which repeat, and never invents a slide type', () => {
+ const format = catalogue[0];
+ const brief = deckFormats.instructions(format.id);
+ assert.match(brief, new RegExp('FORMAT: this is a ' + format.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+ format.sequence.forEach((part, i) => {
+ assert.ok(brief.indexOf((i + 1) + '. ' + part.part) !== -1, 'part ' + part.part + ' is listed in order');
+ });
+ assert.match(brief, /\(repeatable\)/);
+ assert.match(brief, /may be used more than once/);
+ assert.match(brief, /Every slide is still one of the types above/);
+ assert.equal(deckFormats.instructions('not-a-format'), '');
+ assert.equal(deckFormats.instructions(''), '');
+});
+
+test('an unknown format is dropped rather than stored, and a known one survives normalisation', () => {
+ const slides = [{ type: 'bullets', heading: 'x', bullets: ['a'] }];
+ assert.equal(deckSchema.normalise({ format: catalogue[0].id, slides }).format, catalogue[0].id);
+ assert.equal(deckSchema.normalise({ format: 'not-a-format', slides }).format, '');
+ assert.equal(deckSchema.normalise({ slides }).format, '');
+});
+
+test('the format reaches the model after the layouts, on generation and on revision', () => {
+ const route = read('src/routes/myResources.js');
+ assert.match(route, /deckSchema\.instructions\(opts\.slideCount, opts\.figureCount\) \+[\s\S]{0,400}deckFormats\.instructions\(opts\.format\)/);
+ assert.match(route, /deckFormats\.instructions\(existingDeck\.format\)/);
+ assert.match(route, /revisedDeck\.format = existingDeck\.format/);
+ assert.match(route, /formats: deckFormats\.catalogue\(\)/);
+ const ui = read('public/js/myResources.js');
+ assert.match(ui, /format: \(document\.getElementById\('mr-format'\) \|\| \{\}\)\.value/);
+});
+
+test('the picker is told what a format is for, never the recipe itself', () => {
+ for (const entry of deckFormats.catalogue()) {
+ assert.deepEqual(Object.keys(entry).sort(), ['audience', 'description', 'id', 'length', 'name']);
+ }
+});
diff --git a/test/my-resources-refine.test.js b/test/my-resources-refine.test.js
index 7d507f4a..29e5bd3a 100644
--- a/test/my-resources-refine.test.js
+++ b/test/my-resources-refine.test.js
@@ -70,6 +70,7 @@ function router(t, overrides = {}) {
},
'../utils/deckBuild': deckBuild,
'../utils/deckSchema': require('../src/utils/deckSchema'),
+ '../utils/deckFormats': require('../src/utils/deckFormats'),
'../utils/deckSample': require('../src/utils/deckSample'),
'../utils/deckReview': {
slideImages: async () => (overrides.slideImages || []),