Cicero's Hoard

Interactive Routes

deck_navigation configures stable slide links, external URLs and next/previous/return actions on ordinary objects. The editor offers the same destination selector. HTML and live sessions restore nested branch origins and click stages; native PPTX uses editable slide relationships and last-slide-viewed return. Contracts.

Related MCP server: MakeSlates MCP Server

Motion, Media And Linked Data

Use deck_transitions for common screen/native transitions, stable-object morph and per-slide overrides. Use media_import and media_get for local or HTTP(S) audio/video, then add typed media blocks. deck_media_control operates playback on the current live slide. dataset_link, dataset_links, dataset_bind and dataset_link_control provide durable automatic local/URL data refresh, immutable snapshots, typed visual recipes and last-good recovery. The editor exposes the same features. The public catalogue now contains 67 tools. See live media and advanced authoring for contracts and format differences.

deck_design runs a model-driven create/render/correct loop using the configured global model, with real image content in vision mode. External image feedback is bound to a source revision, variant and PNG hash; runs support resumption, cancellation and selective undo. scene_model_import packages local GLB/glTF/ZIP resources offline, retaining textures, materials, lights and clips. deck_benchmark compares complete independently authored PPTX workflows using a common native rasterizer and a fixed blind rubric. Failures, ties and regressions remain in the report; selected cases cannot establish universal superiority.

A local workspace that turns a brief and source documents into an editable presentation. You give it an objective, an audience and the material; it proposes an outline, writes the slides with speaker notes, lets you review and approve each slide one by one, applies a theme and exports the result. It is meant for a person and for an assistant working together: everything is available as a REST API for the bundled UI and as MCP tools, built from the same code, so the two cannot disagree.

What it does

• Your PPTX templates: upload a reference deck on the Theme tab, or use template_inspect and deck_template over MCP. The editable PPTX keeps its dimensions, masters, layouts, backgrounds, logos and fonts. A saved snapshot survives changes to the original file. Notes and charts come from the new deck. Layout-to-source-slide bindings let an assistant choose precise title/body slots for unusual templates.

• Decks: title, brief, audience, tone, language (Spanish or English), number of slides (3 to 40) and theme. The status is derived, never typed: draft (nothing yet), outline (an outline exists), review (slides exist, some not approved), ready (every slide approved).

• Sources: paste text or add a .txt, .md, .pdf, .docx or .pptx file (text only; a scanned PDF is read by the family document service's OCR when that app is running). Sources are numbered and each slide can cite the sources it draws on.

• Outline: generated by the configured family model from the brief and numbered source excerpts, or written by hand. Each item has a title, a purpose, a few points and an optional layout hint.

• Slides: fifteen layouts including evidence, comparison and freeform composition, built from text, image, chart, diagram, metric, table and timeline blocks. Every slide has speaker notes.

• Per-slide review: approve or unapprove a slide, regenerate it with feedback, edit it by hand. Every change creates a revision; reverting restores an old revision as a new one. Generating slides again keeps approved slides and rewrites drafts.

• No invented numbers: the model may only use figures that appear in the sources. A chart is kept only when all its values appear in the sources, and deck_check lists every figure on a slide that no source contains. Number formats are compared across notations (1.234, 1,234, 1.234,5, 1,5).

• Automatic fitting: text is measured and the font is stepped down until it fits, in the preview, the HTML and the PPTX alike (the three are drawn from one geometry). Text that cannot fit even at the smallest size is reported by the check instead of being clipped silently.

• Themes: seven built-in themes (claro, oscuro, editorial, carmesi, pizarra, tecnico, oceano), all with a contrast of at least 4.5:1 for text, muted text and accents. Fonts are ones present on Windows. A design system from the family design-system app can become an eighth, custom theme (theme_from_tokens, or the "Theme from a design system" picker in the theme screen): its colours, fonts and corner radius are mapped, colours that would not read are pulled until they reach 4.5:1 (the changes are listed), and a font that is not on Windows is replaced by the closest one that is. Cards in a theme with a radius are drawn with rounded corners in the preview, the HTML and the PPTX.

• Exports:

  • PPTX with real text boxes, bullet paragraphs, speaker notes and native charts (editable in the office suite), 16:9 by default, or the attached template's size.

  • PDF, one page per slide, rendered by a local Chromium.

  • HTML, one self-contained file (styles, script and images inline) with arrow-key navigation. Speaker notes are left out on purpose because the file is meant to be shared.

  • Markdown, slides separated by ---, notes as comments, charts as tables.

• Images: upload your own, or ask the family's image studio (Prospero's Hoard) for a picture per slide. The studio is optional.

• Works without a model: when no model is reachable, the outline and the slides are built from the sources by fixed rules and the result says "generator": "fallback". Regenerating one slide with feedback needs a model and says so instead of pretending.

Visual workbench for agents

visual_catalog exposes versioned schemas for 14 chart types, diagrams, metrics and tables. slide_visual_update replaces or appends one block while preserving other blocks, citations and notes; use expected_revision to detect concurrent edits. slide_variants compares three compositions without changing content. deck_scene reports object geometry, font sizes and click stages. deck_present returns the local animated presentation URL. These use the same implementations as ordinary slide editing and export, and are available through the MCP catalogue. See the agent workflow and the portable agent-skill/SKILL.md entrypoint. npm run build packages the specialist runtimes inside the Python distribution; advanced rendering needs Node 22.13+, but not a separate dependency install at runtime. scripts/visual-gallery.py --output-dir <folder> creates a fictional-data capability gallery and, when available, native rendering evidence.

Charts support numeric X coordinates, gaps, colors, highlighted categories, units, annotations, reference lines, and interval bounds. The engines are ECharts for chart rendering, ELK for diagram placement, and reveal.js for local presentation playback. PPTX keeps native charts or editable evidence objects. Interval charts use filled regions in the browser and central/lower/upper curves in PPTX. Heatmaps export as colored tables; funnels as stage objects. Diagram nodes, connections, metric text and tables remain editable. Sources remain the authority for values.

Use build, effect and duration_ms on blocks for click stages. Diagram effect: stages builds nodes in order. The browser and standalone HTML retain individual objects, including with attached templates. The exported PPTX carries native slide animations and transitions written as OOXML, with no office engine needed: deck_animations (or GET|PUT|DELETE /api/decks/{id}/animations, .../animations/preview, /api/animations/catalogue) sets mode -- builds (only the click stages, the default), auto (cover zoom, title fade, chart and table wipe, picture zoom, cards and text fly in, then the click stages), mixed, none or any of the 203 native effects -- trigger (after-previous or on-click), duration, transition (none or any of 48, Morph included) and transition_duration, deck-wide or per slide. Footers and background shapes never animate. The animation and transition XML comes from PPT Master (MIT, vendored in cicero_hoard/vendor/ppt_master with its licence) and every export is read back with its validators. In the app, the Export tab sets the presentation-wide motion and the transitions in its transitions panel, gives each slide its own animation in «Animations per slide» and lists what the next PPTX will carry per slide with Check.

Before exporting, deck_visual_review (POST /api/decks/{id}/visual-review, PNGs at /api/decks/{id}/visual-review/slide-NN.png) renders every slide in the browser and measures what was laid out: objects off the slide, text whose lines leave their box, content objects covering each other, text contrast against what is really behind it (4.5:1, 3:1 for large text), pictures that do not load, and a missing title, chart or picture for the layout. Each finding says its fix; fix: true applies the one automatic fix the rules allow (minimum font size on the slides whose text overflows) and reviews again. PDF represents the complete static state. The user can share their local presentation window remotely; no publication is necessary. A text box that starts on the slide and only runs past the bottom grew with its text, so it counts as overflow. In the app, the Review tab runs the visual review, shows the capture of each flagged slide and offers the automatic fix.

Data And Live Presentation

• dataset_import: immutable CSV/TSV/XLSX sources, worksheets and explicit decimal profiles.

• dataset_get: paginated rows, missing/numeric profiles and import warnings.

• dataset_transform: reproducible filters, grouping, aggregates and mixed-type sorting.

• dataset_visual: typed chart/table mapping, preserving missing observations and source IDs.

• deck_live_start: separate presenter and audience URLs, support slides and a target duration.

• deck_live_state: audience-safe navigation and timer state, without speaker notes.

• deck_live_control: stages, slide jumps, blackout, timer and main-talk boundary.

The editor includes data import/mapping, editable staged timelines, normalized freeform composition and contain/cover image crop focus. Live sessions remain in local server memory; restart a session after deck edits. Offline HTML remains independent of live sessions. See data and presentation workflow and capability comparison for tested behavior and remaining gaps.

Responsible use

• Figures. A generated deck is a draft. The number check finds figures that are not in the sources; it cannot tell whether a source is right. Read the notes and the figures before presenting.

• Sources stay local. Documents are read on this computer. Only short numbered excerpts are sent to the model, through Hoard Link, to whatever backend you configured (a local one by default).

• Local files. Adding a file by path only accepts document types (.txt, .md, .pdf, .docx, .pptx) and can be limited to folders with CICERO_FILE_ROOTS.

• Quotes. A quote block should reproduce a quote that appears in a source. The check does not verify quotations.

• Deletes (a deck, a slide, a source) need an explicit confirmation, also over MCP.

Install

Requirements: Python 3.11+ (Windows target 3.13), Node.js 22+ only to rebuild the client.

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m playwright install chromium     # only for the PDF export
python -m cicero_hoard            # http://127.0.0.1:5194

The built client is committed under cicero_hoard/static, so npm is only needed to change the UI (npm install, npm run build). During UI work python scripts/dev.py starts the API and the Vite dev server together, and python scripts/launch.py starts the app and opens it in the browser.

The model comes from Hoard Link (data/backend.json or the Hoard environment variables); the model name can also be chosen in Settings.

Shared Hoard Link code

The plumbing is the shared commons of Hoard Link (vendored in cicero_hoard/hoard_link/): the launcher (one instance per port, logs in data/logs/), the request guard, the error envelope, the stable mcp-token, the SQLite layer, ULID ids (decks made with older versions keep their 12-character ids), the agent catalogue with the 20 KB result cap, the Word and text readers with the zip-bomb guard, the chunker, the browser launcher for the PDF export and the MCP bridge.

MCP

mcp_server.py is the shared Hoard Link stdio bridge. It never opens the database: it reads data/mcp-token, fetches the tool list from the running app and forwards each call. When the app is not running it starts it (CICERO_BRIDGE_AUTOSTART=0 turns that off; the slow tools publish how long the bridge waits for them). Register it in any MCP client:

{"mcpServers": {"cicero": {"command": "python", "args": ["/path/to/cicero/mcp_server.py"],
  "env": {"CICERO_URL": "http://127.0.0.1:5194", "CICERO_TOKEN_FILE": "/path/to/cicero/data/mcp-token"}}}}

faustus-plugin.json describes the same setup for the Faustus workspace.

Tools

Results sent to an assistant are trimmed to about 20 KB with a hint to narrow the request. Approving a slide is the person's decision: an assistant should not approve slides on its own.

Agent sessions, reasons and undo

Every write an assistant makes through the MCP bridge (or POST /api/agent/call) is accountable. The web interface is not an agent and is exempt from all of this.

• Who. The bridge sends the agent name and session it reads from HOARD_AGENT_ID / HOARD_AGENT_SESSION (headers X-Agent-Id / X-Agent-Session; a body caller / _session also works). A scoped token fixes the agent name whatever the headers say.

• Why. Every tool that is not read-only needs a reason argument of 3 to 300 characters (400 reason_required with a hint otherwise). Reading tools need none.

• What. Each write is a line of data/agent_journal.jsonl (tool, agent, session, reason, a digest and a masked summary of the arguments, the ids it returned, time, ok or error); the file rotates at about 5 MB. GET /api/agent/journal?session=&agent=&limit= (Bearer token) reads it, and the event agent.write goes to the family.

• Undo a whole session. POST /api/agent/undo {"session": "...", "dry_run": true} says what would be taken back; with {"confirm": true, "reason": "..."} it does it, newest write first. It reverses presentation creation, presentation fields and theme, the outline, adding and removing sources, every slide edit (text, image, regenerate, approve, revert), adding, deleting and reordering slides, slides_add batches (their receipt too, so the same batch key can be used again) and slides_generate. It reports what it could not undo: tools without a way back (deck_delete, deck_export, asset_import, slide_image, deck_template, theme_from_tokens, the VectorCraft and DesignCraft tools) and anything changed afterwards. It never touches another session's writes: if another session, or the person in the interface, edited the same slide later, that write is reported as a conflict and left as it is.

• Profiles. python -m hoard_link.tokens mint --app-data-dir data --agent drafter --profile drafts prints a token (shown once; the file data/agent_tokens.json keeps only hashes). Profiles: read_only (reading tools), drafts (also the tools that create or edit drafts: deck_create, deck_update, deck_theme, source_add, slide_add, slides_add, slide_update, slide_edit_text, slide_set_image, slide_regenerate, slide_image, asset_import, slides_reorder, theme_from_tokens; never deleting, approving, exporting or generating a whole deck) and all. A blocked call answers 403 profile_forbidden. The Hub tab "Sesiones de agente" shows the sessions of every app and undoes them, and mints and revokes tokens.

Family

Cicero works alone. Decks are addressable as hoard://cicero/deck/<id>. It emits cicero.deck.created, cicero.deck.deleted, cicero.outline.generated, cicero.slides.generated and cicero.deck.exported on the hub bus (ids and short titles only). Themes made from a design system emit cicero.theme.created and are linked to the design system (hoard://cicero/theme/<id> derived from hoard://vitruvius/tokens/<id>); the design system is read through the hub (tokens_list and tokens_get of the design-system app), so the hub and that app must be running, and asking for the same design system in the same state again gives back the same theme. Pictures come from Prospero's Hoard when it runs: the studio is looked up through CICERO_IMAGE_STUDIO_URL, the hub's app list, or its default local port (8815), and is used through its local REST API, which needs no token. Slide pictures go into a studio project named "Cicero's Hoard slides" (reused, or created the first time); each request submits one 16:9 render, waits for it and stores the resulting image in the deck. Only loopback addresses are ever contacted.

Development

pip install -r requirements.txt
python -m pytest -q      # no network: the model and the image studio are faked

The PDF tests run only when a Chromium is available. Documentation of the HTTP API is in docs/API.md.

A real run

On a Windows PC with a local 27B model served by llama.cpp: a seven-slide sales plan for a fictional shop, from a brief and one pasted report. The outline took 155 s; with slides written one after another each took about 75 s, which is why they are now written three at a time. The model used only the report's figures: a bar chart of the four quarters, the customer figures in two columns, and, after the feedback "remove the gross-margin sentence, it is not in the report; show the 70,000 EUR breakdown as a bar chart", a slide with that exact breakdown and without the sentence. The check reported no unsourced figure. PPTX and PDF exports were opened: native charts, speaker notes, the theme's fonts embedded in the PDF. The image studio drew a 16:9 picture for one slide in 79 s. An assistant connected over MCP listed the decks, ran the check and exported the PDF in four rounds. Four faults found in that run are fixed and covered by tests: theme fonts lost in the HTML, bare thousands on native charts, a bridge that called a running app stopped when it could not read its token, and an image call to a tool the studio does not have.

Limits

• With an attached template, preview and HTML place interactive objects over the source branding, whose background is rendered by an installed local office slide engine on Windows. PDF is the native PPTX rendering. HTML is self-contained with click stages. Without that engine, template PDF/HTML and preview report pdf_unavailable. A rendered preview is cached by deck state. deck_check then reports native text bounds that exceed their frames; a check before rendering reports that native review is still needed. Source animations and transitions are not copied; authored click stages are added. Automatic slot selection is a starting point; use the inspected shape IDs and explicit bindings for complex reference decks.

Template bindings also accept title_frame, subtitle_frame (CSS pixel coordinates), title_font_points and chart_font_points. These controls retain the original master and branding while fitting longer titles and setting readable chart labels. Explicit line breaks count during text fitting.

• A picture takes as long as the studio needs to render it; the request waits up to CICERO_IMAGE_TIMEOUT seconds. If that time passes the render keeps running in the studio and is not submitted again. Only one image is taken per request, from a studio on this machine; images over 15 MB or not PNG, JPEG or WEBP are refused.

• The PDF export needs Chromium (python -m playwright install chromium, or a system Edge or Chrome). Without it, exporting pdf fails with the code pdf_unavailable and the other formats keep working.

• Fonts are those of the theme; a machine without them substitutes another and lines may wrap differently. The fitting leaves a small safety margin for that.

• Text fitting is an estimate from character widths, not a font-metrics measurement.

• Charts: bar, line and pie; one or several series (a pie uses the first).

• Speaker notes are not included in the HTML export.

• Scanned PDFs have no text and are refused with a message.

License

See LICENSE.

Draft batches for large presentations

slides_add(deck_id, batch_key, slides) appends several draft slides, with their notes, charts and source IDs, in one transaction. Retry the same key and content after an interrupted response to recover the original slide IDs. A reused key with different content is rejected. Existing slides and approvals are preserved; the batch does not approve slides. The whole batch rolls back if any slide fails validation.

When a slide cites specific sources, deck_check checks its figures against those sources. Example numbers in another source or in the brief do not count as evidence for that slide. This checks numeric presence, not the meaning of a claim; factual review remains necessary.

slide_edit_text changes one title, subtitle, note or bullet item without rebuilding the other blocks. Editing a bullet uses zero-based block/item indices; charts and other bullets remain intact, and the edit creates a normal draft revision.

For an existing figure, use asset_import, then slide_set_image(deck_id, slide_id, asset_id, caption?). The first image is selected by default; image_index counts only image blocks, and an index equal to the image count appends. Omitted captions stay unchanged; explicit null clears one. Other blocks, notes, title, sources and layout are preserved. An identical retry creates no extra image or revision. Changes create draft revisions and can be undone with slide_revert. Optional expected_revision detects a concurrent edit (409 conflict); read the slide again before retrying.

Timed rehearsal planning

deck_rehearsal(deck_id, duration_minutes, words_per_minute, pause_seconds, main_slides) creates a per-slide schedule from speaker notes. main_slides selects the leading slides of the talk; the rest are listed as support. The slots sum exactly to the target, while a separate estimate reports whether the notes fit at the chosen pace, including pauses. Missing notes leave the total estimate unknown. Planning never claims an oral rehearsal has been measured and does not modify notes, revisions or approvals.

Local VectorCraft and DesignCraft

Set CICERO_VECTORCRAFT_CLI and CICERO_DESIGNCRAFT_CLI to the installed portable executable paths. Cicero starts each app as a local headless MCP server and places its app data under Cicero's own data/craft-runs folder. The current real artifact tests use the verified VectorCraft 0.3.1 and DesignCraft 0.2.1 portable builds; other compatible releases are discovered at runtime. No account or remote service is required.

craft_discover(app) returns the full native MCP tool list and input schemas. craft_call(app, calls) dispatches native tools by their original names and arguments, in order, and returns the complete text or image content. This keeps the apps' existing MCP surface available through Cicero.

Tool names: craft_discover, craft_call, vector_figure_create, and deck_handout_designcraft. Discovery includes native tools, prompts, resources, and resource templates when the installed app exposes them. Dispatch accepts kind: "tool", "prompt", or "resource"; a server which does not implement an optional MCP method reports an empty inventory for that method.

vector_figure_create(deck_id, slide_id, title, shape, fill, stroke, replace_block_index?) creates an editable VectorCraft document, SVG, and PNG preview, stores a managed copy, and adds it to the slide as a figure. To correct an existing figure, pass its returned block_index as replace_block_index; the other blocks, title and notes remain intact. PPTX contains the SVG picture and a PNG compatibility image. The generated .vectorcraft, .svg, and .png files live in the deck's assets; source files are not edited.

As an alternative to environment variables, store executable paths in the local, untracked data/craft-engines.json: {"vectorcraft":{"executable":"..."},"designcraft":{"executable":"..."}}. Each craft_call batch opens a fresh native process. Keep dependent commands in one batch and save the native document before returning; selection and undo history do not persist between batches. Gutenberg provides persistent editorial sessions for longer publishing workflows.

The vector source is editable in VectorCraft. PPTX embeds the SVG as a picture with PNG fallback, not native shape geometry of a presentation file; the tool reports this distinction. Handouts embed placed raster frames (including PNG fallbacks for SVG assets), while chart blocks contribute text values rather than native charts.

deck_handout_designcraft(deck_id) creates one editable A4 DesignCraft page per slide with separate heading and body frames, then renders a PNG preview for every page. Text, speaker notes and image captions are carried over; charts contribute their values. Raster images become placed graphic frames, and VectorCraft SVG assets use their stored PNG fallback in the handout. The native project is copied and reopened before rendering, so the downloadable .designcraft is verified to retain its embedded images without Cicero asset links. Text that overflows fails with a clear error instead of returning an incomplete handout. The .designcraft file and each PNG are downloadable from the deck's export list. SVG source remains in Cicero's asset and presentation workflows; this handout does not claim editable vector content, PDF export or branded layout parity with the source deck.

Shared Faustus assistant

The Faustus button mounts the common panel served by the configured Faustus service. Conversation storage, model choice, streaming, recovery and project memory live in Faustus. Cicero supplies its data-space identity, deck, selected slide/revision, editor selection and unsaved slide draft. Its 67 native domain tools and slide revisions remain available. Existing decks, notes, sources and manual unsaved edits are preserved. Configure CICERO_FAUSTUS_URL or the existing backend.json Faustus connection. This requires a reachable Faustus service with the shared copilot contract; no private chat/model fallback is created.