Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Reading clerum__generate_pptx arguments into slide specs.
*
* Everything the renderer draws passes through here first, so a malformed
* argument becomes a message naming the field and the fix rather than a
* JavaScript TypeError, a slide with an error printed on it, or an empty slide
* reported as success. Repairs (rows sent as records read by header, text
* shortened to its length limit) are made here and reported as warnings.
*/
import { type EmbeddableImage, loadEmbeddableImage } from './embeddedImages'
import { inlineSpans } from './inlineMarkup'
import { ChartSpecError, type NativeChart, readNativeChart } from './pptxCharts'
import { SLIDE_LAYOUTS, STATUSES } from './pptxVocabulary'
import { headerText, normalizeTableRows } from './tableRows'
/** An argument the deck cannot be built from; the message names the field. */
export class PptxInputError extends Error {}
export type SlideLayout = (typeof SLIDE_LAYOUTS)[number]
export type Status = (typeof STATUSES)[number]
const DELTA_DIRECTIONS = ['up', 'down', 'neutral'] as const
/** Longest text each field keeps, so a runaway model cannot bloat the archive. */
export const TEXT_LIMITS = {
title: 200,
eyebrow: 100,
subtitle: 400,
bullet: 1000,
header: 200,
cell: 500,
label: 120,
value: 80,
delta: 80,
note: 1000,
caption: 400,
quote: 2000,
attribution: 200,
narrative: 4000,
notes: 8000,
}
export interface PptxKpi {
/** Argument path of the card, for messages. */
where: string
/** Argument path of `note`, when it is not `${where}.note`. */
notePath?: string
label?: string
value: string
delta?: string
deltaDirection?: (typeof DELTA_DIRECTIONS)[number]
/** A longer explanation under the value. */
note?: string
}
export interface PptxTable {
headers: string[]
rows: string[][]
}
export interface PptxPicture {
image: EmbeddableImage
caption?: string
/** Requested size in inches; the other side follows the image's proportions. */
width?: number
height?: number
}
export interface PptxChart {
title?: string
caption?: string
picture?: EmbeddableImage
native?: NativeChart
}
export interface PptxColumn {
bullets?: string[]
text?: string
picture?: PptxPicture
}
/** What a slide of any layout may carry besides its content. */
interface SlideCommon {
/** Where the slide came from, as the model wrote it: "slides[2]", or "data" for a template. */
where: string
title?: string
eyebrow?: string
subtitle?: string
status?: Status
notes?: string
/** Argument paths of fields that did not come from `${where}.<field>`, for messages. */
paths?: Record<string, string>
}
/** A slide: its layout and the content that layout draws, which it always has. */
export type PptxSlide = SlideCommon &
(
| { layout: 'cover' }
| { layout: 'section' }
| { layout: 'title-bullets'; bullets: string[] }
| { layout: 'title-chart'; chart: PptxChart }
| { layout: 'title-table'; table: PptxTable }
| {
layout: 'kpis'
kpis: PptxKpi[]
/** People cards: the name large, the role under it. */
kpiStyle?: 'people'
}
| { layout: 'two-column'; columns: { left: PptxColumn; right: PptxColumn } }
| {
layout: 'image'
/** Absent when the image could not be embedded: the slide shows its title, and a warning says why. */
picture?: PptxPicture
}
| { layout: 'quote'; quote: { text: string; attribution?: string } }
)
/** The slide of `layout`. */
export type SlideOf<L extends SlideLayout> = Extract<PptxSlide, { layout: L }>
/** Argument path of one of a slide's fields, as messages name it. */
export function fieldPath(slide: PptxSlide, field: string): string {
return slide.paths?.[field] ?? `${slide.where}.${field}`
}
export interface ReadContext {
outputDir: string
warnings: string[]
/** Undeclared argument paths taken under another name (InternalToolResult.aliasedArguments). */
aliased?: string[]
/** Set once a text field holding markup has been reported. */
markupNoted?: boolean
}
/**
* Whether `text` holds markdown or HTML a slide would print as written: the
* PDF and DOCX tools, which read it, would print something else. A single
* asterisk is left out, since 2*3*4 is ordinary text on a slide.
*/
function holdsMarkup(text: string): boolean {
const t = text.replace(/(?<!\*)\*(?!\*)/g, '\u2217')
return (
inlineSpans(t)
.map(span => span.text)
.join('') !== t
)
}
export function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
}
function describe(value: unknown): string {
if (value === null) return 'null'
if (Array.isArray(value)) return 'a list'
return typeof value === 'object' ? 'an object' : `a ${typeof value}`
}
/** `text` shortened to `max` characters at a word, ending in an ellipsis. */
export function shorten(text: string, max: number): string {
const chars = Array.from(text)
if (chars.length <= max) return text
let kept = chars.slice(0, max - 1).join('')
const space = kept.lastIndexOf(' ')
if (space > kept.length * 0.8) kept = kept.slice(0, space)
return `${kept.trimEnd()}…`
}
/** Optional text. Numbers and booleans are written as they print. */
export function readText(
value: unknown,
where: string,
max: number,
ctx: ReadContext
): string | undefined {
if (value === undefined || value === null) return undefined
const raw = typeof value === 'number' || typeof value === 'boolean' ? String(value) : value
if (typeof raw !== 'string') {
throw new PptxInputError(`${where} must be text; received ${describe(value)}.`)
}
const text = raw.trim()
if (!text) return undefined
if (!ctx.markupNoted && holdsMarkup(text)) {
ctx.markupNoted = true
ctx.warnings.push(
`${where} holds markdown or HTML, which slides print as written; PPTX text is plain, ` +
'so send it without **bold**, `code`, [label](url) or tags.'
)
}
if (Array.from(text).length > max) {
ctx.warnings.push(`${where} is longer than ${max} characters and was shortened.`)
return shorten(text, max)
}
return text
}
/** A Markdown list marker, which the slide's own bullet would print twice. */
const LIST_MARKER = /^[-*+•]\s+/
/** A numbered list marker; the slide's bullet replaces it and the order stays. */
const ORDERED_MARKER = /^\d{1,9}[.)]\s+/
/** A list item set in from the left: a bullet nested under the one above. */
const NESTED_ITEM = /^[ \t]+(?:[-*+•]|\d{1,9}[.)])\s/
/**
* The number of a numbered list marker, when it could count an item of a list
* this long: "2024. A record year" in a short list is a year, not a position.
*/
function countsItem(text: string, items: number): boolean {
const n = /^(\d{1,9})[.)]\s/.exec(text)
return !!n && Number(n[1]) <= items
}
/**
* A list of text items. One string is read as one item per line. Slides show
* one level of bullets, so a nested item joins the first level, and the result
* says so. Numbers are taken off the first level only when every item is a
* list item and every number could count one of them, and off a nested item
* when its number could: a lone "2024. A record year", or two years in a row,
* keep their years.
*/
export function readStringList(
value: unknown,
where: string,
max: number,
ctx: ReadContext
): string[] | undefined {
if (value === undefined || value === null) return undefined
let raw: unknown[]
let at: (i: number) => string
if (typeof value === 'string') {
raw = value.split('\n')
at = i => `${where} line ${i + 1}`
} else if (Array.isArray(value)) {
raw = value
at = i => `${where}[${i}]`
} else {
throw new PptxInputError(`${where} must be a list of text items; received ${describe(value)}.`)
}
const nested = raw.map(item => typeof item === 'string' && NESTED_ITEM.test(item))
const items = raw
.map((item, i) => ({ text: readText(item, at(i), max, ctx), nested: nested[i] }))
.filter((item): item is { text: string; nested: boolean } => !!item.text)
const marked = (text: string) => LIST_MARKER.test(text) || ORDERED_MARKER.test(text)
const bareOf = (text: string) => text.replace(LIST_MARKER, '')
const counts = (text: string) => countsItem(bareOf(text), items.length)
const numbered =
items.length > 1 &&
items.every(item => marked(item.text)) &&
items.every(item => item.nested || !ORDERED_MARKER.test(bareOf(item.text)) || counts(item.text))
const first = nested.indexOf(true)
if (first >= 0) {
ctx.warnings.push(
`${at(first)} is a nested bullet; slides show one level of bullets, so it was set at the ` +
'first level with the others. Put the detail on its own slide or in the item it belongs to.'
)
}
return items
.map(({ text, nested }) => {
const bare = bareOf(text)
return (nested ? counts(text) : numbered) ? bare.replace(ORDERED_MARKER, '') : bare
})
.filter(Boolean)
}
export function readEnum<T extends string>(
value: unknown,
where: string,
allowed: readonly T[]
): T | undefined {
if (value === undefined || value === null || value === '') return undefined
if (!(allowed as readonly unknown[]).includes(value)) {
throw new PptxInputError(
`${where} must be one of ${allowed.join(', ')}; received ${JSON.stringify(value)}.`
)
}
return value as T
}
function requireList(value: unknown, where: string): unknown[] {
if (!Array.isArray(value)) {
throw new PptxInputError(`${where} must be a list; received ${describe(value)}.`)
}
return value
}
export function readKpis(value: unknown, where: string, ctx: ReadContext): PptxKpi[] {
return requireList(value, where).map((item, i) => {
const at = `${where}[${i}]`
if (!isRecord(item)) {
throw new PptxInputError(
`${at} must be an object such as {"label": "Revenue", "value": "$1.2M"}; received ${describe(item)}.`
)
}
const value = readText(item.value, `${at}.value`, TEXT_LIMITS.value, ctx)
if (value === undefined) {
throw new PptxInputError(
`${at}.value is missing: give the figure to show, e.g. "$1.2M" or 48.`
)
}
const kpi: PptxKpi = { where: at, value }
kpi.label = readText(item.label, `${at}.label`, TEXT_LIMITS.label, ctx)
kpi.delta = readText(item.delta, `${at}.delta`, TEXT_LIMITS.delta, ctx)
kpi.deltaDirection = readEnum(item.deltaDirection, `${at}.deltaDirection`, DELTA_DIRECTIONS)
return kpi
})
}
function cellText(value: unknown, where: string, ctx: ReadContext): string {
if (value === undefined || value === null) return ''
if (typeof value === 'object') {
throw new PptxInputError(`${where} is ${describe(value)}; a cell holds text or a number.`)
}
return readText(value, where, TEXT_LIMITS.cell, ctx) ?? ''
}
export function readTable(value: unknown, where: string, ctx: ReadContext): PptxTable {
if (!isRecord(value)) {
throw new PptxInputError(
`${where} must be an object with headers and rows; received ${describe(value)}.`
)
}
if (!Array.isArray(value.headers) || value.headers.length === 0) {
throw new PptxInputError(`${where}.headers must list the column headings, left to right.`)
}
const headers = value.headers.map(
(h, i) => readText(headerText(h), `${where}.headers[${i}]`, TEXT_LIMITS.header, ctx) ?? ''
)
if (value.rows !== undefined && !Array.isArray(value.rows)) {
throw new PptxInputError(
`${where}.rows must be a list of rows, each a list of cells in header order.`
)
}
const rows = normalizeTableRows(value.rows, value.headers, where, ctx.warnings)
let cut = 0
const cells = rows.map((row, r) => {
if (row.length > headers.length) cut++
return headers.map((_, c) => cellText(row[c], `${where}.rows[${r}][${c}]`, ctx))
})
if (cut > 0) {
ctx.warnings.push(
`${where}: ${cut} row(s) had more cells than the ${headers.length} headers; the extra cells were left out.`
)
}
if (cells.length === 0) {
ctx.warnings.push(
`${where} has no rows, so the table shows only its headings; add rows, or leave the ` +
'slide out.'
)
}
return { headers, rows: cells }
}
/**
* Load an image argument. A missing or unreadable file is a warning and
* returns undefined; a path escaping the output folder fails the call, as it
* does in every generator.
*/
export function readPicture(
value: unknown,
where: string,
ctx: ReadContext
): PptxPicture | undefined {
if (value !== undefined && typeof value !== 'string' && !isRecord(value)) {
throw new PptxInputError(
`${where} must be a file name such as 'sales.png' or {"path": "sales.png"}; received ${describe(value)}.`
)
}
const pathField = typeof value === 'string' ? where : `${where}.path`
const local: string[] = []
let image: EmbeddableImage | undefined
try {
image = loadEmbeddableImage(value, ctx.outputDir, local, pathField)
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
throw new PptxInputError(
`${pathField}: ${message}. Pass the file name in the output folder, as ` +
"clerum__generate_chart returns it (e.g. 'sales.png')."
)
}
for (const w of local) ctx.warnings.push(w.startsWith(pathField) ? w : `${pathField}: ${w}`)
if (!image) {
if (isRecord(value) && typeof value.caption === 'string' && value.caption.trim()) {
ctx.warnings.push(`${where}.caption was left out with the image it describes.`)
}
return undefined
}
const picture: PptxPicture = { image }
if (isRecord(value)) {
picture.caption = readText(value.caption, `${where}.caption`, TEXT_LIMITS.caption, ctx)
for (const side of ['width', 'height'] as const) {
const n = value[side]
if (n === undefined || n === null) continue
if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) {
throw new PptxInputError(`${where}.${side} must be a positive number of inches.`)
}
picture[side] = n
}
}
return picture
}
export function readChart(value: unknown, where: string, ctx: ReadContext): PptxChart {
if (!isRecord(value)) {
throw new PptxInputError(
`${where} must be an object: {"path": "sales.png"} for a chart image from ` +
'clerum__generate_chart, or {"type", "labels", "datasets"} for a native chart.'
)
}
const chart: PptxChart = {
title: readText(value.title, `${where}.title`, TEXT_LIMITS.title, ctx),
caption: readText(value.caption, `${where}.caption`, TEXT_LIMITS.caption, ctx),
}
// Chart.js nests labels and datasets under data; they are read there too.
if (isRecord(value.data)) ctx.aliased?.push(`${where}.data`)
try {
chart.native = readNativeChart(value, where, ctx.warnings)
} catch (err) {
if (err instanceof ChartSpecError) throw new PptxInputError(err.message)
throw err
}
if (value.path !== undefined && value.path !== null && value.path !== '') {
chart.picture = readPicture(value.path, `${where}.path`, ctx)?.image
if (chart.picture) chart.native = undefined
else if (chart.native) {
ctx.warnings.push(
`${where}: the image could not be used, so the chart was drawn from its data.`
)
}
} else if (!chart.native) {
throw new PptxInputError(
`${where} has nothing to draw: pass path with the file name clerum__generate_chart ` +
'returned, or type, labels and datasets for a native chart.'
)
}
return chart
}
function readColumn(value: unknown, where: string, ctx: ReadContext): PptxColumn {
if (!isRecord(value)) {
throw new PptxInputError(
`${where} must be an object such as {"type": "bullets", "bullets": ["..."]}.`
)
}
const type =
value.type ??
(value.bullets !== undefined ? 'bullets' : value.image !== undefined ? 'image' : 'narrative')
if (type === 'bullets') {
const bullets = readStringList(value.bullets, `${where}.bullets`, TEXT_LIMITS.bullet, ctx)
if (!bullets?.length) throw new PptxInputError(`${where}.bullets needs at least one bullet.`)
return { bullets }
}
if (type === 'narrative') {
const text = readText(value.text, `${where}.text`, TEXT_LIMITS.narrative, ctx)
if (!text) throw new PptxInputError(`${where}.text is missing for a narrative column.`)
return { text }
}
if (type === 'image') {
if (value.image === undefined) {
throw new PptxInputError(`${where}.image is missing for an image column.`)
}
return { picture: readPicture(value.image, `${where}.image`, ctx) }
}
throw new PptxInputError(
`${where}.type must be one of bullets, narrative, image; received ${JSON.stringify(type)}.`
)
}
/** What each layout draws. Anything else on the slide is reported as left out. */
const LAYOUT_FIELDS: Record<SlideLayout, string[]> = {
cover: ['title', 'subtitle', 'status'],
section: ['title', 'eyebrow', 'subtitle'],
'title-bullets': ['title', 'bullets'],
'title-chart': ['title', 'chart'],
'title-table': ['title', 'table'],
kpis: ['title', 'kpis'],
'two-column': ['title', 'columns'],
image: ['title', 'image'],
quote: ['quote'],
}
/** The layout for the content a slide carries, to suggest when it names another. */
const CONTENT_LAYOUT: Record<string, SlideLayout> = {
bullets: 'title-bullets',
chart: 'title-chart',
table: 'title-table',
kpis: 'kpis',
columns: 'two-column',
image: 'image',
quote: 'quote',
}
function missing(where: string, layout: SlideLayout, field: string, shape: string): never {
throw new PptxInputError(
`${where} uses layout "${layout}" but has no ${field}; add ${field}: ${shape}, or pick the ` +
'layout that matches what the slide carries.'
)
}
function readSlide(raw: unknown, index: number, ctx: ReadContext): PptxSlide {
const where = `slides[${index}]`
if (!isRecord(raw)) {
throw new PptxInputError(`${where} must be an object with a layout; received ${describe(raw)}.`)
}
if (!(SLIDE_LAYOUTS as readonly unknown[]).includes(raw.layout)) {
const hint = Object.keys(CONTENT_LAYOUT).find(k => raw[k] !== undefined)
throw new PptxInputError(
`${where}.layout ${JSON.stringify(raw.layout)} is not a layout. Use one of ` +
`${SLIDE_LAYOUTS.join(', ')}` +
(hint ? `; a slide with ${hint} uses "${CONTENT_LAYOUT[hint]}".` : '.')
)
}
const layout = raw.layout as SlideLayout
const common: SlideCommon = {
where,
title: readText(raw.title, `${where}.title`, TEXT_LIMITS.title, ctx),
notes: readText(raw.notes, `${where}.notes`, TEXT_LIMITS.notes, ctx),
}
const used = LAYOUT_FIELDS[layout]
if (used.includes('eyebrow')) {
common.eyebrow = readText(raw.eyebrow, `${where}.eyebrow`, TEXT_LIMITS.eyebrow, ctx)
}
if (used.includes('subtitle')) {
common.subtitle = readText(raw.subtitle, `${where}.subtitle`, TEXT_LIMITS.subtitle, ctx)
}
if (used.includes('status')) common.status = readEnum(raw.status, `${where}.status`, STATUSES)
let slide: PptxSlide
switch (layout) {
case 'cover':
case 'section':
if (!common.title) missing(where, layout, 'title', '"..."')
slide = { ...common, layout }
break
case 'title-bullets': {
const bullets = readStringList(raw.bullets, `${where}.bullets`, TEXT_LIMITS.bullet, ctx)
if (!bullets?.length) missing(where, layout, 'bullets', '["...", "..."]')
slide = { ...common, layout, bullets }
break
}
case 'title-chart':
if (raw.chart === undefined) missing(where, layout, 'chart', '{"path": "sales.png"}')
slide = { ...common, layout, chart: readChart(raw.chart, `${where}.chart`, ctx) }
break
case 'title-table':
if (raw.table === undefined)
missing(where, layout, 'table', '{"headers": [...], "rows": [[...]]}')
slide = { ...common, layout, table: readTable(raw.table, `${where}.table`, ctx) }
break
case 'kpis': {
if (raw.kpis === undefined)
missing(where, layout, 'kpis', '[{"label": "...", "value": "..."}]')
const kpis = readKpis(raw.kpis, `${where}.kpis`, ctx)
if (kpis.length === 0) missing(where, layout, 'kpis', '[{"label": "...", "value": "..."}]')
slide = { ...common, layout, kpis }
break
}
case 'two-column': {
const cols = raw.columns
if (!isRecord(cols) || cols.left === undefined || cols.right === undefined) {
missing(where, layout, 'columns', '{"left": {...}, "right": {...}}')
}
slide = {
...common,
layout,
columns: {
left: readColumn(cols.left, `${where}.columns.left`, ctx),
right: readColumn(cols.right, `${where}.columns.right`, ctx),
},
}
break
}
case 'image':
if (raw.image === undefined) missing(where, layout, 'image', '{"path": "photo.png"}')
slide = { ...common, layout, picture: readPicture(raw.image, `${where}.image`, ctx) }
break
case 'quote': {
const q = typeof raw.quote === 'string' ? { text: raw.quote } : raw.quote
const text = isRecord(q)
? readText(q.text, `${where}.quote.text`, TEXT_LIMITS.quote, ctx)
: undefined
if (!isRecord(q) || !text) missing(where, layout, 'quote', '{"text": "..."}')
slide = {
...common,
layout,
quote: {
text,
attribution: readText(
q.attribution,
`${where}.quote.attribution`,
TEXT_LIMITS.attribution,
ctx
),
},
}
break
}
}
const ignored = ['title', 'eyebrow', 'subtitle', 'status', ...Object.keys(CONTENT_LAYOUT)].filter(
k => !used.includes(k) && raw[k] !== undefined && raw[k] !== null && raw[k] !== ''
)
if (ignored.length > 0) {
ctx.warnings.push(
`${where}: ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not shown on a "${layout}" ` +
'slide and was left out; put it on a slide whose layout draws it.'
)
}
return slide
}
export function readSlides(value: unknown, ctx: ReadContext): PptxSlide[] {
if (!Array.isArray(value) || value.length === 0) {
throw new PptxInputError(
'slides must be a non-empty list of slides, each with a layout, or pass template and data ' +
'to have the slides built for you.'
)
}
return value.map((raw, i) => readSlide(raw, i, ctx))
}