PPT Agent Public

Public-safe local setup for testing the PPT agent from a link, a cloned repo, an included Codex skill, or a thin MCP adapter. Telemetry, upload, private assets, Drive IDs, tokens, and private runtime access are off unless explicitly configured by the operator.

Fast Start

Link-only agent instruction: Give an agent this repo link and ask it to run the one-line setup below: https://github.com/Kdreammaker/ppt-agent-public

One-line PowerShell setup from a new PC:

$Root="$env:USERPROFILE\Downloads\ppt-maker"; git clone https://github.com/Kdreammaker/ppt-agent-public.git "$Root\ppt-agent-public"; Set-Location "$Root\ppt-agent-public"; python scripts\ppt_setup.py --workspace "$Root\workspace" --force

Already cloned setup from the repo root:

python scripts\ppt_setup.py --workspace "<workspace>" --force

To record a preferred setup intent without changing renderer behavior:

python scripts\ppt_setup.py --workspace "<workspace>" --force --output-intent editable_office

Included agent skill route: Use skills/ppt-agent/SKILL.md, then run python scripts\ppt_agent.py doctor and python scripts\ppt_agent.py make --mode assistant --prompt "<prompt>".

MCP/extension route: Run python scripts\ppt_agent_mcp_adapter.py --serve; Assistant planning artifacts are returned by default, and final build requires build_approved=true.

Install A Ready Workspace

The setup wrapper installs the workspace, activates an optional workspace code, configures the private connector when credentials are present, writes a diagnostic report, and prints the exact next ppt_make.py commands. It also writes outputs/reports/public_setup_summary.json and outputs/reports/public_setup_summary.md. These public-safe setup summaries explain output intent choices:

• design_visual: prioritize visual storytelling and infographic composition.
• editable_office: prioritize PowerPoint-native objects and editable chart/table data when that capability is available.
• balanced: the default; keep strong design while preserving native PPTX editability.

Users may choose one of these with --output-intent; the selected value is recorded in public_setup_summary.json and public_setup_summary.md as metadata only. The default remains balanced.

The summary also explains why one-slide review exists, what uploaded knowledge/asset counts mean, that PPTX is the native editable primary output, that HTML is a companion, and that chart/table readiness is metadata only. It does not change renderer behavior or enable native chart/table rendering. When a public-safe B49 asset request summary is available, setup may also show asset request counts and user actions with --b49-asset-request-summary "<path-to-b49-asset-request-summary.json>". Only public fields are shown: request id, slide number, state, asset type, required flag, user action, user message, and public-safe reason. Raw asset refs, slot IDs, private paths, Drive links, tokens, private prompts, raw payloads, source attachments, and unapproved asset records are not exposed.

When an internal Auto capability report has already been approved for public beta metadata, setup can show its public-safe status projection:

python scripts\ppt_setup.py --workspace "<workspace>" --force --auto-capability-metadata "<path-to-auto-capability-metadata.json>"

This exposes capability/status metadata only: selected output intent, current two-variant policy status, bounded renderer capability status, native chart/table supported counts, B54 guidance status, font materialization blocked status, and public-safe blocker categories. It does not expose raw internal renderer reports, package internals, private identifiers, private paths, Drive links, tokens, prompts, or unapproved asset details.

Entitled private production setup uses the same wrapper after the operator supplies a workspace code. If private repo access is available through GitHub auth, setup can use the default private runtime repo/ref and install it into the workspace:

python scripts\ppt_setup.py --workspace "<workspace>" --workspace-code "<workspace-code>" --enable-private --github-check

Advanced operators can override the private repo, ref, install root, or build command with --private-package-repo, --private-package-ref, --private-package-install-root, or --private-build-command-env. Most users should not need those switches.

User files uploaded in chat or selected from disk should be imported into the workspace before use:

python scripts\ppt_workspace_assets.py import --workspace "<workspace>" --file "<file>" --type image
python scripts\ppt_workspace_assets.py import --workspace "<workspace>" --file "<file>" --type font
python scripts\ppt_workspace_assets.py list --workspace "<workspace>"
python scripts\ppt_workspace_assets.py validate --workspace "<workspace>"

Workspace manifests live under .ppt-agent/ and may contain local paths for that user's machine. Do not commit workspace contents, uploaded assets, private connector files, generated reports, Drive IDs, approval records, or raw private asset payloads.

Make PPTs From Natural Language

Once setup is complete, users and AI agents can make decks through one natural-language command. The wrapper records a local intake, creates a deck plan first, builds the spec, then produces PPTX and HTML outputs:

python scripts\ppt_make.py "Make a 6 slide executive market review for AI launch priorities" --workspace "<workspace>" --mode assistant

The same metadata-only output intent can be recorded on make reports:

python scripts\ppt_make.py "Make a 6 slide executive market review for AI launch priorities" --workspace "<workspace>" --mode assistant --output-intent design_visual

If a B49 asset request summary exists for the project, the make report can also surface the same public-safe asset actions:

python scripts\ppt_make.py "Make a 6 slide executive market review for AI launch priorities" --workspace "<workspace>" --mode assistant --output-intent design_visual --b49-asset-request-summary "<path-to-b49-asset-request-summary.json>"

Make reports can also carry the same public-safe Auto capability projection when the approved metadata file is supplied:

python scripts\ppt_make.py "Make a 6 slide executive market review for AI launch priorities" --workspace "<workspace>" --mode assistant --output-intent design_visual --auto-capability-metadata "<path-to-auto-capability-metadata.json>"

Assistant Mode is a planning checkpoint by default. The command above writes review artifacts and returns status=waiting_for_approval; it does not create final PPTX/HTML until the user or agent approves the plan:

python scripts\ppt_make.py "Make a 6 slide executive market review for AI launch priorities" --workspace "<workspace>" --mode assistant --build-approved --output-intent design_visual

Each run writes a local design brief before or alongside outputs:

outputs/projects/<project_id>/plans/draft_design_brief.md

The brief includes the request, version/channel status, bounded source context, table of contents, slide-by-slide layout/content plan, style decisions, font/color policy, and reverse-engineering boundary. Local files or public URLs can be used as bounded planning context:

python scripts\ppt_make.py "Make a board update from this source" --workspace "<workspace>" --mode assistant --source-file ".\notes.md"
python scripts\ppt_make.py "Make a market brief" --workspace "<workspace>" --mode auto --source-url "https://example.com/report"

Auto Mode uses the same entrypoint:

python scripts\ppt_make.py "Make a 6 slide growth update for leadership" --workspace "<workspace>" --mode auto

Route Matrix

Route	Assistant Mode	Auto Mode
scripts\ppt_make.py	Natural-language first-run wrapper. Creates planning artifacts, draft_design_brief.md, and ppt_make_report.json; waits with status=waiting_for_approval. Final PPTX/HTML requires --build-approved or --continue-build.	Natural-language fast draft route. Builds immediately.
scripts\ppt_agent.py	Guide-packet/sparse-prompt agent route. Plans first by default; final files require --build-approved.	Builds two strategy-routed variants plus comparison/recommendation reports.
scripts\ppt_agent_mcp_adapter.py	deck_plan_compose returns planning artifacts unless build_approved=true.	two_variant_auto_build renders variants without an approval checkpoint.

If the private connector is ready and a production build is required:

python scripts\ppt_make.py "Make a production-ready executive growth review" --workspace "<workspace>" --mode assistant --production private --execute-private

By default, setup and make run a version/channel check and write a report such as outputs/reports/version_check.json or outputs/projects/<project_id>/reports/version_check.json. Use --skip-remote-version-check for offline installs, or --require-latest on ppt_make.py when stale public/private channels should block execution.

Default permission posture:

• local public PPTX/HTML build: enabled
• Auto/Assistant plan-first public-safe build: enabled
• user file import into the local workspace: enabled by explicit command only
• telemetry and automatic upload: disabled
• private connector/gateway: disabled until configured
• private runtime execution and private asset materialization: requires entitlement plus connector readiness

Guide Packet Agent Mode

The public-safe guide packet agent consumes guide-data.public.json as its primary machine input and writes local planning/QA artifacts before or during PPTX generation. Assistant mode is the default; Auto mode creates two strategy-routed variants with separate deck-plan.json and renderer-contract.json files.

python scripts\ppt_agent.py doctor
python scripts\ppt_agent.py make --mode assistant --guide-bundle data\fixtures\lumaloop_guide
python scripts\ppt_agent.py make --mode auto --guide-bundle data\fixtures\lumaloop_guide

Sparse requests can be normalized into public-safe machine-facing documents:

python scripts\ppt_agent.py make --mode assistant --prompt "파일인데 참고해서 공공기관 보고자료로 만들어줘" --source ".\input\memo.md"
python scripts\ppt_agent.py make --mode auto --prompt "이 제품 소개자료 자동으로 만들어줘"

This path writes request-intake.json, source-summary.json, intent-profile.json, and routing-report.json, then composes or validates a guide packet. The strategy router is bounded by config/deck_intent_taxonomy.json and config/variant_strategy_registry.json. HTML guide output is review evidence only and is never inserted into PPTX content as a screenshot.

Generic MCP clients can use the guide-packet adapter without replacing the existing public CLI MCP adapter:

python scripts\ppt_agent_mcp_adapter.py --serve

Public CLI And Private Runtime Path

This public repository is the installable CLI control plane. It installs runtime dependencies, initializes workspaces, runs public-safe smoke checks, and provides the connector that entitled users or operators use to install and call the private PPT runtime.

The private layer remains responsible for full template-library based high-quality PPT generation, private template binaries, private Design DNA, premium assets, real activation counters, revocation, rotation, audit, and signed private package or gateway responses. The public smoke deck is only a fallback and install check; the useful production flow is the private runtime build path.

Public-safe local smoke, requiring no private template binaries, raw references, telemetry, upload, or gateway credentials:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python scripts\ppt_cli_workspace.py init --workspace outputs\public_smoke_workspace --force-readme
python scripts\ppt_cli_workspace.py healthcheck --workspace outputs\public_smoke_workspace
python scripts\build_deck.py data\specs\public_smoke_blank_spec.json

Expected PPTX:

outputs/decks/public_thin_smoke.pptx

Full template-library builds require private capabilities that are intentionally excluded from the public clean export.

Private runtime connection, for entitled users/operators:

python scripts\ppt_workspace_entitlement.py activate --workspace outputs\public_smoke_workspace --workspace-code <workspace-code>
python scripts\ppt_private_connector.py configure --workspace outputs\public_smoke_workspace --enable --private-package-repo-env PPT_AGENT_PRIVATE_PACKAGE_REPO --private-build-command-env PPT_AGENT_PRIVATE_BUILD_COMMAND_JSON
python scripts\ppt_private_connector.py status --workspace outputs\public_smoke_workspace --github-check
python scripts\ppt_private_connector.py install --workspace outputs\public_smoke_workspace
python scripts\ppt_private_connector.py build --workspace outputs\public_smoke_workspace --spec data\specs\business_growth_review_spec.json --execute

The connector writes local request summaries under .ppt-agent/gateway_requests/. It does not print tokens, store raw workspace codes, upload files, or include private templates in this repository. Real high-quality generation is performed by the private runtime command or gateway after entitlement, package access, and operator/user approval are in place.

Main Folders

• assets/slides/references
  • Raw reference PPTX files only. Files here are not used directly by generation.
• assets/slides/categorizing
  • Ignored working area for split PNG/PPTX slide review: png/{unlabeled,good_candidate,normal_candidate,weak_candidate} and pptx/{unlabeled,good_candidate,normal_candidate,weak_candidate}.
• assets/slides/library
  • Classified reference slide records under good, normal, and weak.
• assets/slides/templates
  • Promoted/analyzed template assets used by production catalogs and blueprints.
• config
  • Theme files, catalogs, schemas, and blueprints.
• data/specs
  • JSON deck specs.
• docs
  • System guides and workflow notes.
• scripts
  • Builders, catalog generators, renderers, and validators.
• system
  • Shared Python utilities.
• outputs/decks
  • Generated PPTX decks.
• outputs/projects
  • Writer-facing project bundles with deck, docs, assets, previews, reports, and manifest.
• outputs/previews/template_index
  • Human-browsable preview images and contact sheets.

Key Files

• config/template_library_catalog.json
  • Source-of-truth list for curated library builds.
• config/reference_catalog.json
  • Unified slide metadata for search and automatic selection.
• config/template_blueprints.json
  • Fillable slot definitions and header/footer/page zones.
• config/deck_spec.schema.json
  • JSON schema for deck specs.

Main Scripts

• scripts/build_template_libraries.py
  • Builds promoted template deck files from curated source definitions.
• scripts/build_reference_catalog.py
  • Generates the unified reference catalog and template blueprints.
• scripts/render_template_thumbnails.py
  • Renders or synthesizes slide preview images and contact sheets.
• scripts/validate_template_blueprints.py
  • Verifies that catalogs and blueprints match real slide assets.
• scripts/build_deck.py
  • Builds final decks from JSON specs using either direct template keys or purpose-based selection.
• scripts/ppt_system.py
  • Operator-facing wrapper for intake validation, deck builds, validation, run-scoped output, and project-scoped output.
• scripts/compose_deck_spec_from_intake.py
  • Deterministically composes a draft deck spec from a validated intake JSON file.
• scripts/compose_deck_plan_from_intake.py
  • Creates a reviewable deck plan before slide content is written or rendered.
• scripts/compose_deck_spec_from_plan.py
  • Converts the approved or recorded deck plan into a deck spec with plan traceability.

Suggested Workflow

1. Update config/template_library_catalog.json.
2. Run build_template_libraries.py.
3. Run build_reference_catalog.py.
4. Run render_template_thumbnails.py.
5. Run validate_template_blueprints.py.
6. Build a deck from a spec in data/specs.

To start from intake, compose the plan-first draft spec:

python scripts/ppt_system.py compose-spec data/intake/report_exec_briefing.json

The compatibility path is still available when needed:

python scripts/ppt_system.py compose-spec data/intake/report_exec_briefing.json --direct-intake

For writer-facing output, prefer the wrapper:

python scripts/ppt_system.py build data/specs/example.json --validate --auto-project

This preserves compatibility outputs under outputs/decks/ and outputs/reports/, then mirrors the deck, spec, docs, referenced images, rendered previews, and reports into outputs/projects/<project_id>/.