KitchenSink4PPT

Batch editor: many edits, one lock, one backup, one atomic save. Each edit is {"op": name, ...params} addressed by a view "anchor" (from get_presentation_view) or explicit {"slide", "shape"/"table"} keys. Ops: set_text, set_shape (graphics pack), set_table_cells (tables-charts pack), search_and_replace, set_placeholder_text, format_text (graphics pack), delete_shape (graphics pack). Every location is resolved BEFORE anything mutates; any stale anchor refuses the whole batch listing every failed index, and result.changed maps op index to outcome. These ops EDIT existing content; nothing here inserts shapes, tables, or slides. Creation tools live in the packs (enable_tools). atomic must stay True: v1 has no partial-apply mode. Saves atomically with two-slot backup; backup=False skips rotation. Use this when a change needs two or more edits; for a single edit use the standalone tool (set_shape, format_text, set_table_cells, set_placeholder_text, search_and_replace, delete_shape).

Copy a deck byte-for-byte, e.g. to a working copy before heavy edits (create_snapshot names a DTG-stamped copy for you; this tool takes an explicit dest_path). Refuses an existing dest_path unless overwrite=True; an overwritten destination's previous content rotates into its .ks4p-backups prev slot first, so the overwrite is undoable via manage_backups restore. The source file is never modified.

Save a DTG-stamped permanent copy: YYYYMMDD_HHMM_<name>.pptx (an existing leading DTG in the name is replaced, not stacked), plus an optional short label. Snapshots are the PERMANENT keepers alongside the automatic prev/anchor slots: slots rotate on every mutation, snapshots are never auto-pruned and manage_backups never touches them. Never overwrites (collisions get a numeric suffix). The source file is not modified. Take one before any large or risky editing pass.

Delete a slide and garbage-collect everything only it used: notes, charts, embeddings, comments, custom-show references, section membership; jump links to it are neutered. slide: 0-based index or {"slide_id": N}. Prefer set_slide_hidden (design pack) when it might come back. Saves atomically with two-slot backup; backup=False skips rotation. live='auto' edits the open PowerPoint copy when the file is locked by it (UNSAVED until live_save, com pack); 'force' targets the open session; 'off' refuses locked files.

Self-check for this environment and, optionally, one file. Reports export engine availability (PowerPoint COM vs LibreOffice), sandbox state, KS4P mode/policy env, and the current pack surface with token costs. With file_path: existence, size, PowerPoint lock state, whether the package opens, and slide count, WITHOUT mutating anything. Output is PASTE-SAFE by default: no absolute paths, so it can go straight into a bug report; verbose=True adds the sandbox roots, engine locations, and full file path for local troubleshooting. Run it first when any tool refuses unexpectedly or an export engine seems missing. Reports the update-check state; the only place the check runs. The validate tool (assembly-export pack) does the real opens-clean check in PowerPoint.

Switch pack tools back off to shrink the tool surface (the lite core always stays on). Takes the same pack names as enable_tools, or 'everything'. Idempotent: already-disabled packs are reported, not errors. Nothing about the presentation files changes; this only trims what this session's client has to carry. Reports the approx token cost removed and the remaining active surface.

Deep-copy a slide: notes, charts with their embedded workbooks, and embeddings are cloned and retargeted; layout and media stay shared by design; creation GUIDs are regenerated (duplicates corrupt). slide: 0-based index or {"slide_id": N}. position: 0-based final index for the copy, default right after the original. The design pack adds move and hide: enable_tools(packs=['design']). Saves atomically with two-slot backup; backup=False skips rotation.

Switch on optional tool packs mid-session; the tool list grows and your client is notified to re-fetch it. Packs: 'graphics' (shapes, connectors, groups, align, z-order, SVG to native editable shapes, diagram generators, images, video/audio, text boxes, run formatting, bullets, format painter, LaTeX equations); 'tables-charts' (tables: create, bulk cells, merge, row/column surgery, borders, styles, CSV/JSON; bar/line/pie/scatter/combo charts, formatting, data readback); 'design' (create FROM template, apply layouts, theme colors/fonts read AND write, brand extract/apply, layout guardrails, slide size, hide/move, autofit report, slide/master backgrounds, master and layout editing, accessibility audit/repair); 'assembly-export' (notes, sections, footers, PDF/PNG/handout export, validation, text extraction, cross-deck copy, deck merge/split, agenda slides, statistics, document properties, anonymize, custom shows, slide transitions and entrance animations); 'review-sweeps' (threaded comments, compare_decks, deck-wide font/color/language/logo sweeps, compress); 'com' (PowerPoint status, zombie check, and editing the deck OPEN in PowerPoint); 'everything' (all). The v1.0 names transitions-animations, review, sweeps, and com-live still resolve to their new homes. Idempotent; reports approx token cost added and the active surface. disable_tools reverses.

Search the deck's text. Returns every match with slide index, shape id, paragraph index, and character offsets, exactly the addresses format_text (graphics pack) and apply_edits consume. regex=True treats query as a regular expression (guarded against catastrophic backtracking). Matches text as displayed, not raw XML, so search for & rather than &amp;. count is always the true total; a "page" block gives the omitted count and next offset when more matched than the budget fits. compact=True returns matches as a fields header plus one array each. Formatting-aware replacement lives in the graphics pack: enable_tools(packs=['graphics']). Use this to locate text; to read it in order, use get_text.

Shrink overflowing text to fit: estimates the largest uniform font scale (floor min_size pt) via an average-glyph-width heuristic, rewrites explicit run sizes (or writes a normAutofit fontScale when sizes are inherited), and enables normAutofit. shape=None fits every overflowing text shape on the slide; one that cannot fit at min_size reports still_overflowing. An ESTIMATE (no font metrics): verify with export_slide_images (assembly-export pack). Saves atomically with two-slot backup; backup=False skips rotation.

Deck-level facts in one call: slide count and size, slide order with durable ids and titles, masters and layouts, section list, and notes presence. The cheap first look before get_presentation_view. To enumerate one kind of element, use list_elements. Rendering, validation, and PDF export live in the assembly-export pack: enable_tools(packs=['assembly-export']).

The anchored markdown projection of a deck, THE cheap way to read it: slide headers with durable [s:id] anchors, one block per shape with a stable [a:hex] anchor, tables as pipe tables with t:hex:rNcN cell addresses (1-based there; table tools take 0-based row/col), notes as quoted blocks. Feed the anchors to apply_edits. scope: None for all slides, an index, {"slide_id": N}, or a list. detail: "outline", "text" (default), or "full" (geometry too). Budgeted: a deck too large to render whole returns whole slides plus a "page" block giving the omitted count and the offset that continues; limit/offset page in slides. Shape and diagram editing: enable_tools(packs=['graphics']).

Report the KitchenSink4PPT server build: product and PyPI package name, the version a client is connected to, the landing page, the sibling servers in the KitchenSink4AI suite, the registered and lite tool totals, the released test count, the active pack surface and its token bill, and the host platform and Python. A read-only orient call that needs no deck and touches no file, and the only tool that answers WHAT you are connected to. diagnose covers the environment.

One slide in depth: durable slide_id, layout, hidden flag, notes presence, and every shape with id, name, kind, geometry in inches, placeholder type, and text preview. Shape ids here are the addresses every editing tool takes; edit what it lists via the graphics pack. slide: 0-based index or {"slide_id": N}. Budgeted: a crowded slide returns a "page" block with the omitted count and next offset. All slides: get_presentation_view. live='auto' edits the open PowerPoint copy when the file is locked by it (UNSAVED until live_save, com pack); 'force' targets the open session; 'off' refuses locked files.

Plain text of the deck in reading order: shapes in spTree order, table cells tab-joined, fields rendering their cached text. scope: None for all slides, a 0-based index, {"slide_id": N}, or a list; include_notes=True appends speaker notes. Budgeted, paging in whole slides: slide_count stays the deck's true total and a "page" block gives the omitted count and the next offset; limit/offset page explicitly. Rendered-appearance checks live in the assembly-export pack. live='auto' edits the open PowerPoint copy when the file is locked by it (UNSAVED until live_save, com pack); 'force' targets the open session; 'off' refuses locked files. For edit anchors, use get_presentation_view.

Step-by-step recipes for the common jobs, each naming the packs it needs and the exact tool order: build-a-diagram, one-call-diagram, equation-authoring (graphics), build-a-table-report (tables-charts), template-deck-setup, master-restyle, accessibility-pass (design), render-and-review, cross-deck-assembly, deck-merge, animate-a-build (assembly-export), batch-edit-from-view (lite, the cheap loop), review-cycle (review-sweeps), rebrand-pipeline (review-sweeps + design), live-session (com). Call with no task for the index, with a task name for full steps. Read the matching recipe before your first deck edit of a session; it prevents most wrong-tool detours.

Add a slide built from a layout (name, or 0-based global index; list_elements kind='layouts' lists them), carrying the layout's placeholder skeleton so inheritance binds. position: 0-based final index, default end. Whole decks start via create_presentation (design pack). Saves atomically with two-slot backup; backup=False skips rotation. live='auto' edits the open PowerPoint copy when the file is locked by it (UNSAVED until live_save, com pack); 'force' targets the open session; 'off' refuses locked files.

THE multiplex enumerator, one kind per call: slides, shapes, placeholders, tables, charts, images, diagrams (SmartArt frames with their editable nodes), notes, sections, layouts, masters. Returns a flat item list with ids and locations; slide-scoped kinds honor scope (None = all slides, a selector, or a list). count is always the true number found; a deck with more elements than fit the per-call output budget returns a "page" block naming how many were held back and the offset that continues, so nothing goes missing quietly. limit/offset page explicitly, and compact=True returns a fields header plus one array per item, about a third the size on large decks. Use it to find layout names for insert_slide and shape ids for editing. The packs (enable_tools) hold the tools that edit what this lists. For one slide in depth, use get_slide_info; for edit anchors, use get_presentation_view.

Every hyperlink in scope (default all slides): external URLs and jump-to-slide links, on shapes and on text runs, with broken-target detection (missing rels, rels to deleted slides, empty URLs). The addresses reported are exactly what set_hyperlink and remove_hyperlink take. Media playback controls (insert_video/insert_audio, graphics pack) are not hyperlinks and are not listed. Read-only; the file is never modified.

The automatic backups under .ks4p-backups/ next to each mutated deck: prev (state before the last mutation) and anchor (session start). action='list': slots for one file_path or a whole directory, plus orphaned folders. action='restore': overwrite file_path from source ('prev', 'anchor', or a .pptx path); current content rotates into prev FIRST so the restore is undoable, and the payload is validated before the atomic replace. action='purge': scope 'orphans' or 'slots'; dry_run=True (default) reports only, dry_run=False deletes.

Remove hyperlinks from a shape or text range. target: a shape id (removes the shape-level link AND every run-level link inside the shape) or {"shape_id": N, "paragraph": P, "start"?: S, "end"?: E} for the covered runs only. Orphaned link rels are dropped; media playback affordances (graphics pack av inserts) are left alone. Saves atomically with two-slot backup; backup=False skips rotation.

Rearrange the whole deck in one call. order: every current 0-based slide index exactly once, in the desired new sequence (a permutation; partial lists refuse). Durable slide_ids and view anchors survive reordering, plain indices do not. For moving ONE slide, move_slide in the design pack is simpler: enable_tools(packs=['design']). Saves atomically with two-slot backup; backup=False skips rotation.

Deck-wide find and replace, safe across fragmented runs (each replacement keeps the first run's formatting), SmartArt node text included. regex=True enables capture groups (refused live); matches overlapping slide-number/date fields are skipped. Bulk cell rewrites: set_table_cells (tables-charts pack). Saves atomically with two-slot backup. live='auto' edits the open PowerPoint copy of a locked file; 'force' targets the open session; 'off' refuses locked files. Batches: apply_edits.

Set a hyperlink on a shape or text range, replacing any link already there. target: a shape id, or {"shape_id": N, "paragraph": P, "start"?: S, "end"?: E} for a text range. Exactly one destination: url (external) or to_slide (a jump by index or {"slide_id": N}, the structure delete_slide knows how to neuter). tooltip sets hover text. Navigation buttons pair with insert_shape (graphics pack). Saves atomically with two-slot backup; backup=False skips rotation.

Fill a layout placeholder (styling inherits from the layout). placeholder: "title", "subtitle", "body"/"content" (each matches both body and obj placeholders; exact type wins), a raw ph type, or an idx int (idx/paragraphs= file-mode only). text: newline = paragraph, leading tabs = levels; or paragraphs=[{"text": str, "level": 0..8}]. Free text boxes: graphics pack. Saves atomically with two-slot backup; backup=False skips rotation. live='auto' edits the open PowerPoint copy of a locked file. Batches: apply_edits.