polyptych 0.1.0__tar.gz

polyptych-0.1.0/.claude/agents/prompt-consistency-reviewer.md

@@ -0,0 +1,66 @@
+---
+name: prompt-consistency-reviewer
+description: Read-only reviewer that detects drift between prompt task templates, provider best-practice docs, style-transfer presets, and the YAML config files (image-presets, pipeline-presets, model configs). Invoke after editing anything under prompts/ or the *-presets.yaml / *_config.yaml files, or when asked to audit prompt/config consistency.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+# Prompt & Config Consistency Reviewer
+
+You are a read-only auditor for this essay-to-visuals generation system. You never edit
+files — you report findings so the main agent (or the user) can act on them.
+
+## What you check
+
+The project keeps several sources of truth that must agree with each other:
+
+- `prompts/tasks/` — per-task prompt templates (task-01 … task-07,
+  task-i0 … task-i2, task-critique)
+- `prompts/providers/{gemini,openai,xai}-best-practices.md` — provider guidance
+- `prompts/style-transfer/<category>/*.md` — visual style presets (+ optional sibling
+  exemplar image)
+- `image-presets.yaml`, `pipeline-presets.yaml`, `model_config.yaml`,
+  `image_model_config.yaml`
+- `CLAUDE.md` and `docs/reference/cli-reference.md` — which document flags, presets,
+  pipelines, and task tables
+
+## Drift patterns to hunt for
+
+1. **Flag/option drift** — a flag or option named in a provider best-practices doc or a
+   task template that no longer exists in the CLI / config (or vice versa: a flag in
+   `CLAUDE.md` / cli-reference not honored by any template).
+2. **Preset references** — a `--image-preset` / `--pipeline-preset` name referenced in
+   docs, task templates, or the justfile that is missing from `image-presets.yaml` /
+   `pipeline-presets.yaml`, or a preset defined but referenced nowhere.
+3. **Style presets** — a style category or preset count claimed in `CLAUDE.md`
+   or the docs that disagrees with what's actually on disk under
+   `prompts/style-transfer/`. Count the real files.
+4. **Model/tier references** — task names in `model_config.yaml` that don't correspond to
+   a real task template, or templates with no model-tier entry.
+5. **Pipeline/task-table drift** — the pipeline list and per-task tables in `CLAUDE.md` /
+   cli-reference vs. the actual `task-*` templates present.
+6. **Cross-doc contradictions** — same fact stated two ways in CLAUDE.md vs.
+   cli-reference vs. a provider doc.
+
+## Method
+
+- Use `Glob`/`Grep` to enumerate the real files first, then compare against what the docs
+  and configs claim. **Verify counts and names against disk** — never trust a number
+  asserted in prose without checking it (this is a known failure mode in this repo).
+- Be specific: cite `file:line` for every finding and quote both sides of a mismatch.
+- Distinguish severity: `MISMATCH` (a concrete contradiction with disk/config) vs.
+  `STALE?` (likely outdated, needs human judgment) vs. `NOTE` (minor).
+
+## Output
+
+Return a compact report grouped by drift pattern. For each finding:
+
+```
+[MISMATCH] <one-line summary>
+  claim:   <file:line> — "<quoted text>"
+  reality: <file:line or disk fact> — "<quoted text / count>"
+  fix:     <smallest change that reconciles them>
+```
+
+End with a one-line verdict: `CONSISTENT` or `N findings (X mismatch, Y stale)`.
+If you found nothing, say so plainly — don't invent issues.

polyptych-0.1.0/.claude/hooks/block-sensitive-files.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# PreToolUse hook: block Edit/Write to secrets-bearing files (.env, .envrc, ...).
+# Receives the tool-call JSON on stdin; denies via exit code 2 + JSON decision.
+set -euo pipefail
+
+input=$(cat)
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+filename=$(basename "$file_path")
+
+# Block .env, .env.local, .envrc, etc. Allow .env.example templates through.
+if [[ "$filename" == .env* && "$filename" != ".env.example" ]]; then
+  jq -n --arg f "$filename" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: ("Refusing to edit secrets-bearing file: " + $f + ". Edit it manually if intended.")
+    }
+  }'
+  exit 2
+fi
+
+exit 0

polyptych-0.1.0/.claude/hooks/ruff-format.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# PostToolUse hook: auto-format + lint-fix Python files after Claude edits them.
+# Receives the tool-call JSON on stdin; acts only on .py files.
+set -euo pipefail
+
+input=$(cat)
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+
+[[ "$file_path" == *.py ]] || exit 0
+[[ -f "$file_path" ]] || exit 0
+
+# Format only — idempotent, no semantic changes. Lint-fixing (e.g. removing
+# "unused" imports) is intentionally left to `just lint`, since on a per-edit
+# hook it would strip imports added in one edit before they're used in the next.
+uv run ruff format "$file_path" >/dev/null 2>&1 || true
+
+exit 0

polyptych-0.1.0/.claude/settings.json

@@ -0,0 +1,51 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)",
+      "Bash(just:*)",
+      "Bash(python3:*)",
+      "Bash(python:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git stash:*)",
+      "Bash(ffmpeg:*)",
+      "Bash(ffprobe:*)",
+      "Bash(ls:*)",
+      "Bash(wc:*)",
+      "WebSearch",
+      "WebFetch(domain:ai.google.dev)",
+      "WebFetch(domain:docs.cloud.google.com)",
+      "WebFetch(domain:docs.x.ai)",
+      "WebFetch(domain:github.com)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-sensitive-files.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/ruff-format.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

polyptych-0.1.0/.claude/skills/check-models/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: check-models
+description: Search the web for the latest AI model names and identifiers for a provider, then compare with model_config.yaml and image_model_config.yaml
+user-invocable: true
+args:
+  - name: provider
+    description: "Provider to check: gemini, openai, xai/grok, anthropic/claude, vertex, or 'all' to check every provider. Optional — defaults to 'all' when omitted."
+---
+
+# Check Latest AI Models for a Provider
+
+You are given a `provider` argument identifying which AI provider's models to look up. **If no argument is provided, default to `all`** (check every provider) rather than stopping to ask.
+
+## Provider Mapping
+
+Map the argument to a search scope. Each provider may appear in `model_config.yaml` (text/LLM tiers) and/or `image_model_config.yaml` (image model). Cover both.
+
+| Argument            | Text entries (`model_config.yaml`) | Image entries (`image_model_config.yaml`) | Search hints                                     |
+|---------------------|------------------------------------|-------------------------------------------|--------------------------------------------------|
+| `gemini`            | `providers.gemini`                 | `providers.gemini`, `providers.x_gemini`  | `site:ai.google.dev` Gemini models, API ids     |
+| `openai` / `gpt`    | `providers.openai`                 | `providers.openai`                        | `site:developers.openai.com` models, gpt-image (NOT `platform.openai.com` — that host blocks WebFetch with 403) |
+| `xai` / `grok`      | `providers.xai`                    | `providers.xai`                           | `site:docs.x.ai` Grok / grok-imagine models — pages are often skeletal; lean on WebSearch result snippets, not WebFetch |
+| `anthropic` / `claude` | `providers.anthropic`           | (none — no image gen)                     | `site:platform.claude.com` models (the old `docs.anthropic.com` URL 301-redirects to `platform.claude.com/docs/en/...`) |
+| `vertex`            | `providers.vertex`                 | `providers.vertex`                        | Vertex AI model garden — Gemini ids on Vertex   |
+| `all`               | all of the above                   | all of the above                          | run each provider in sequence                    |
+
+If no argument is given, treat it as `all`. If a non-empty argument doesn't match any of the above, tell the user the valid options and stop.
+
+## Steps
+
+1. **Read both config files** from the repository root:
+   - `model_config.yaml` — display the `fast` and `thinking` model ids for the matched provider(s) under `providers:`.
+   - `image_model_config.yaml` — display the matched provider's image model id (and `x_gemini` if relevant).
+
+   Show the current values so the user can see what's about to be compared.
+
+2. **Search the web** for the latest available models from that provider. Use targeted queries:
+   - Provider docs first: `site:ai.google.dev`, `site:developers.openai.com`, `site:platform.claude.com`, `site:docs.x.ai`, `site:cloud.google.com vertex ai`
+   - General fallback: `<provider> latest AI models 2026 API model id`
+   - For image entries, search specifically for image-generation model ids (e.g. `gpt-image-2 successor`, `gemini image preview latest`, `grok-imagine model id`).
+
+3. **Fetch the relevant documentation page(s)** with WebFetch to extract actual model identifiers — not marketing names. Look for:
+   - Stable model id strings (e.g. `gemini-3.1-pro`, `gpt-5.5`, `claude-opus-4-7`, `grok-4.20-reasoning`)
+   - Stable vs preview/experimental distinction (entries currently using `-preview` ids should stay on previews unless a stable replacement exists)
+   - Recommended / current vs deprecated status
+   - For Anthropic: prefer the current Sonnet/Opus/Haiku tier ids; verify whether dated suffixes are required.
+
+   **Known WebFetch-incompatible hosts — do not WebFetch these, use the alternative:**
+
+   | Don't fetch                           | Use instead                                              | Why                                            |
+   |---------------------------------------|----------------------------------------------------------|------------------------------------------------|
+   | `platform.openai.com/docs/...`        | `developers.openai.com/api/docs/models/<id>`             | `platform.openai.com` returns 403 to WebFetch  |
+   | `docs.anthropic.com/en/docs/...`      | `platform.claude.com/docs/en/docs/...` (after redirect)  | `docs.anthropic.com` 301s to `platform.claude.com`; fetch the redirect URL directly to save a round-trip |
+   | `docs.x.ai/developers/models`         | WebSearch result snippets + secondary sources (Vercel AI Gateway listings, OpenRouter, release-note aggregators) | The official models page often omits exact API ids in the rendered HTML WebFetch sees |
+
+   If a WebFetch returns 4xx, do **not** retry the same URL — switch to the alternative above (or fall back to WebSearch snippets) instead of burning more requests.
+
+4. **Compare** fetched ids against the config files. For each entry, determine:
+   - Is the current id still listed by the provider?
+   - Is there a newer stable or preview successor?
+   - Are there new tiers worth adding (e.g. a new "mini" / "nano" / "reasoning" model that fits `fast` or `thinking`)?
+
+5. **Present a summary table** to the user, separated by config file. Example:
+
+   ```
+   Provider: gemini
+
+   model_config.yaml
+   Tier      Current Identifier              Latest Available                 Status
+   ────      ──────────────────              ────────────────                 ──────
+   fast      gemini-3-flash-preview          gemini-3-flash                   ⚠ stable available
+   thinking  gemini-3.1-pro-preview          gemini-3.1-pro-preview           ✓ up to date
+
+   image_model_config.yaml
+   Entry      Current Identifier              Latest Available                 Status
+   ─────      ──────────────────              ────────────────                 ──────
+   gemini     gemini-3-pro-image-preview      gemini-3-pro-image-preview       ✓ up to date
+   x_gemini   gemini-3.1-flash-image-preview  gemini-3.1-flash-image-preview   ✓ up to date
+   ```
+
+   Status indicators:
+   - `✓ up to date` — current id is the latest recommended
+   - `⚠ update available` — a newer id exists (note: stable replacing preview is also `⚠`)
+   - `✗ deprecated` — current id is deprecated or removed
+   - `? unknown` — couldn't determine status
+
+6. **If updates are available**, show the exact YAML changes needed for the affected file(s) as a diff, but **do NOT apply them automatically**. Ask the user whether to apply.
+
+## Important Notes
+
+- `model_config.yaml` model ids are bare provider-native ids (no `provider:` prefix). Preserve that format when suggesting updates — don't introduce a routing prefix that doesn't exist in this repo.
+- The `vertex` provider in this repo runs Gemini models — its ids should match what Vertex AI exposes (which sometimes lags `ai.google.dev`). Don't blindly copy ai.google.dev ids into `vertex`; verify Vertex availability.
+- `x_gemini` is an experimental/secondary slot under image providers — treat it as the "next preview" line. If the main `gemini` image entry catches up, the `x_gemini` slot should point one step ahead (next preview), not the same id.
+- When uncertain whether a model is newer or just differently positioned (e.g. a "mini" sibling), flag it as `? check manually` rather than recommending a change.
+- The repo's resolution order is `--model` flag > `$POLYPTYCH_MODEL` env (deprecated alias `$SLIDE_GEN_MODEL`) > config tiers — config changes affect every task that didn't override, so call out high-impact swaps (especially `thinking`-tier moves) before applying.
+- Prefer stable/GA models over preview when one exists. If the current entry is on a `-preview` id and a stable successor has shipped, recommend the stable id but call out behaviour differences (preview models sometimes have different output formats / token limits).

polyptych-0.1.0/.claude/skills/check-status/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: check-status
+description: Check the current state of a pipeline output directory — which tasks are done, what's next, and key summary info
+argument-hint: <output-directory>
+---
+
+# Pipeline Status — Situational Awareness
+
+## Role
+
+You are inspecting a pipeline output directory to understand its current state. Report what exists, what's valid, what's next, and key summary information.
+
+## Arguments
+
+- `$ARGUMENTS` = path to the output directory (e.g., `generated/my-project`)
+
+If no directory is provided, ask the user which output directory to check.
+
+## Process
+
+### Step 1: Run Schema Validation
+
+Run the validate command to check all task outputs:
+
+```bash
+uv run polyptych validate $ARGUMENTS --json
+```
+
+This will:
+- Auto-detect the pipeline type from files present
+- Validate each task YAML against its Pydantic schema
+- Run cross-task referential checks when 2+ task files exist (slide pipeline: dangling scene_beat_ids, slide-count mismatches across task3/4/6/7, out-of-range paragraph references, unknown source_sections, arc peaks at nonexistent slides; headline/quote word limits as warnings) — findings appear under `cross_task` in the JSON
+- Report the next step to run
+
+Surface any `cross_task` errors prominently in the status report — they indicate broken references between task files even when every file is schema-valid.
+
+If the directory doesn't exist or is empty, report that and stop.
+
+### Step 2: Read the Manifest
+
+If `$ARGUMENTS/manifest.yaml` exists, read it to extract:
+- Source file path
+- Style preset used
+- Image provider and model
+- Timestamp
+- `mode: local` — the directory was produced by a local skill run (`/run-local-pipeline`, `/run-local-task`, `/infographic`): text-task YAMLs were Claude-generated (`models: claude-local`), image settings are absent until a CLI image run overwrites the manifest, and `tasks_completed` lists the finished text tasks
+
+### Step 3: Detect Pipeline Type and Count Outputs
+
+Determine the pipeline type from which files are present:
+
+| Pipeline | Detection Signal | Image Pattern |
+|----------|-----------------|---------------|
+| **Slide** | `task1-genre.yaml` or `task4-content.yaml` | `slide-NN.{jpg,png}` |
+| **Infographic** | `task-i0-analysis.yaml` or `task-i1-design.yaml` | `infographic-vN.{jpg,png}` |
+
+Count images in `$ARGUMENTS/images/` and prompt files in `$ARGUMENTS/prompts/`.
+
+### Step 4: Summarize Key Outputs
+
+Read task YAML files to extract headline information. Be selective — only read what's present:
+
+| Task File | Key Info to Extract |
+|-----------|-------------------|
+| `task1-genre.yaml` | Genre classification, essay type |
+| `task3-structure.yaml` | Number of slides, structure type |
+| `task-i0-analysis.yaml` | Content analysis summary |
+
+Don't read entire files — use `yaml.safe_load()` and extract just the top-level keys.
+
+### Step 5: Report
+
+Present a concise status report:
+
+```
+Pipeline: infographic
+Source: essays/my-essay.md
+Style: semi-flat-vector
+Provider: gemini
+
+Tasks:
+  [OK] i0  task-i0-analysis.yaml
+  [OK] i1  task-i1-design.yaml
+  [---] i2  task-i2-prompts.yaml
+
+Next step: i2
+Images: 0 / 3 variants
+
+Key info:
+  - Content type: analytical essay
+  - Sections: 5
+```
+
+### Step 6: Suggest Next Action
+
+Based on the state, suggest what to do next:
+
+- If no outputs exist: "Run the full pipeline with `/run-pipeline` or start a local task with `/run-local-task`"
+- If partially complete: "Resume from `{next_step}` — run `/run-pipeline {pipeline} {source} {dir} --from {next_step}` or `/run-local-task {next_step} {dir}`"
+- If all text tasks done but no images: "Text pipeline complete. Run image generation with `/run-pipeline {pipeline} {source} {dir} --from images`"
+- If everything done: "Pipeline complete. Review images with `/review-regen {dir}`"

polyptych-0.1.0/.claude/skills/clean-source/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: clean-source
+description: Clean PDF-converted markdown files by removing page numbers, footnotes, TOC, broken images, and escaped characters
+argument-hint: <input-file> [--output <file>] [--keep-footnotes] [--keep-toc]
+---
+
+# Clean Source — PDF Markdown Cleanup
+
+## Role
+
+You clean PDF-to-markdown conversion artifacts from source files before they are fed into pipelines.
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **input-file** (required): Path to the markdown file to clean
+- Optional flags: `--output`, `--keep-toc`, `--keep-images`, `--keep-footnotes`, `--keep-page-numbers`, `--keep-escapes`, `--dry-run`
+
+If the input file is missing, ask the user.
+
+## Process
+
+1. **Verify file exists** — check the input file path
+2. **Run cleaning** — execute `uv run polyptych clean-source <file> [flags]`
+3. **Report results** — show the cleaning statistics (lines removed, artifacts found)
+4. **Suggest next step** — recommend running a pipeline with the cleaned file, e.g.:
+   - `/run-local-pipeline slide <cleaned-file>`
+   - `/run-pipeline slide <cleaned-file> <output-dir>`
+
+## Tips
+
+- Use `--dry-run` first to preview what will be removed without writing
+- Use `--keep-footnotes` if the source uses inline citations that should be preserved
+- The default output is `<stem>-clean.md` in the same directory as the input

polyptych-0.1.0/.claude/skills/edit-output/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: edit-output
+description: Modify a pipeline task YAML output, validate it, and identify downstream tasks that need re-running
+argument-hint: <output-dir> <task-name> <change-description>
+---
+
+# Edit Pipeline Output — Modify and Resume
+
+## Role
+
+You modify intermediate pipeline task outputs (YAML files), validate the changes against the Pydantic schema, and identify which downstream tasks need to be re-run.
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **output-dir**: Path to the output directory
+- **task-name**: Which task output to edit (e.g., `task1`, `i0`, `i2`)
+- **change-description**: Natural language description of what to change (e.g., "change slide 3's headline to...", "tighten the i1 color palette", "drop section 4 from the infographic")
+
+If arguments are missing, ask the user.
+
+## Task Output Files
+
+| Task | Output File | Model Class |
+|------|-------------|-------------|
+| task1 | `task1-genre.yaml` | `Task1Output` |
+| task2 | `task2-analysis.yaml` | `Task2Output` |
+| task3 | `task3-structure.yaml` | `Task3Output` |
+| task4 | `task4-content.yaml` | `Task4Output` |
+| task5 | `task5-design.yaml` | `Task5Output` |
+| task6 | `task6-slides.yaml` | `Task6Output` |
+| task7 | `task7-prompts.yaml` | `Task7Output` |
+| i0 | `task-i0-analysis.yaml` | `TaskI0Output` |
+| i1 | `task-i1-design.yaml` | `TaskI1Output` |
+| i2 | `task-i2-prompts.yaml` | `TaskI2Output` |
+
+## Dependency Graph
+
+Tasks that depend on the edited task will need re-running. Here are the downstream dependencies:
+
+### Slide Pipeline
+```
+task1 → task2, task3, task4, task5, task6, task7
+task2 → task3, task4, task5, task6
+task3 → task4, task6
+task4 → task5, task6
+task5 → task6, task7
+task6 → task7
+task7 → images
+```
+
+### Infographic Pipeline
+```
+i0 → i1, i2, images
+i1 → i2, images
+i2 → images
+```
+
+## Process
+
+### Step 1: Read Current Output
+
+Read the task YAML file from `$OUTPUT_DIR/<output-file>`.
+
+If the file doesn't exist, report it and stop.
+
+### Step 2: Read the Pydantic Model
+
+Read the model class definition from `src/polyptych/models.py` to understand the schema constraints:
+- Required fields and types
+- Nested model structures
+- Value constraints (min/max, enums, list lengths)
+
+### Step 3: Apply Changes
+
+Based on the change description, modify the YAML data. Common edit patterns:
+
+- **Change a field value**: Update the specific field
+- **Add an item to a list**: Append with all required fields filled
+- **Remove an item**: Delete from the list (may need to renumber)
+- **Modify nested data**: Navigate to the correct nesting level
+- **Bulk changes**: Apply the same change across multiple items
+
+Preserve all fields that aren't being changed. Don't reformat or restructure unchanged data.
+
+### Step 4: Validate
+
+Run schema validation:
+
+```bash
+uv run polyptych validate $OUTPUT_DIR $TASK_NAME
+```
+
+If validation fails:
+- Read the error message
+- Fix the issue (missing required field, wrong type, constraint violation)
+- Re-validate
+
+After saving, also run directory-level validation (`uv run polyptych validate $OUTPUT_DIR --json`): with 2+ task files present it performs cross-task checks (dangling scene_beat_ids, slide-set mismatches, out-of-range paragraph references, ...), which catch edits that broke references *between* files — e.g. removing a scene beat that a task4 allocation still cites.
+
+### Step 5: Save
+
+Write the modified YAML back to the output file, overwriting the original.
+
+### Step 6: Identify Downstream Impact
+
+Using the dependency graph above, list all downstream tasks that may need re-running because they depend on the edited task.
+
+Categorize them:
+- **Direct dependents**: Tasks that directly read this task's output
+- **Transitive dependents**: Tasks that depend on direct dependents
+
+### Step 7: Suggest Resume Command
+
+Build the command to re-run downstream tasks. The earliest downstream step is where to resume:
+
+```
+To re-run affected downstream tasks:
+  just <target> SOURCE OUTPUT STYLE --from <earliest-affected-step>
+
+Or selectively re-run specific tasks:
+  /run-local-task <task-name> <output-dir>
+  /run-pipeline <pipeline> <source> <output-dir> --from <step> --to <step>
+```
+
+If only the images step is affected (e.g., editing image prompts in task7/i2), suggest:
+```
+  /run-pipeline <pipeline> <source> <output-dir> --from images
+```
+
+## Notes
+
+- Always back up the original file mentally — if the edit goes wrong, the user can recover from git
+- For large edits (e.g., restructuring all slides), consider whether `/run-local-task` to regenerate the entire task would be faster than manual editing
+- When editing list items (slides, scenes, beats), be careful about maintaining consistent numbering and cross-references
+- If the change affects counts (e.g., adding slides), downstream tasks that reference the count may produce inconsistent output — flag this