Skip to content

siril9/presentation-skill / plugins/presentation-skill/skills/presentation-skill

presentation-skill

Flagged

Build, edit, redesign, render, and verify content-led, structurally diverse, clean, editable, reproducible PowerPoint `.pptx` decks. Use for scientific, lab, clinical, consulting, board, investor, editorial, policy, and operational presentations where alignment, readability, contrast, and balanced density matter.

FileKindSize
DESIGN.mdmarkdown13.7 KB
DISCOVERY.mdmarkdown6.6 KB
LICENSEother1.0 KB
SKILL.mdskill md14.7 KB
agents/discovery.jsonconfig8.2 KB
agents/openai.yamlconfig309 B
examples/outline.jsonconfig3.4 KB
package-lock.jsonmanifest22.0 KB
package.jsonmanifest1.8 KB
references/agent_picker.mdmarkdown1.9 KB
references/alignment_and_coherence.mdmarkdown2.1 KB
references/assets/visual_references/editorial_chart.jpgbinary53.2 KB
references/assets/visual_references/editorial_decision.jpgbinary100.4 KB
references/assets/visual_references/editorial_focal_metric.jpgbinary45.4 KB
references/assets/visual_references/editorial_pilot.jpgbinary62.0 KB
references/assets/visual_references/lab-native-method.jpgbinary53.9 KB
references/assets/visual_references/lab-residual-panels.jpgbinary64.8 KB
references/assets/visual_references/lab_cover.jpgbinary39.8 KB
references/assets/visual_references/lab_endpoints.jpgbinary70.8 KB
references/assets/visual_references/lab_evidence_gate.jpgbinary67.3 KB
references/assets/visual_references/lab_trend.jpgbinary60.5 KB
references/assets/visual_references/operations_handoffs.jpgbinary87.2 KB
references/assets/visual_references/operations_owner_register.jpgbinary87.2 KB
references/assets/visual_references/operations_queue.jpgbinary81.8 KB
references/assets/visual_references/operations_tradeoff.jpgbinary99.9 KB
references/benchmark_protocol.mdmarkdown12.1 KB
references/codex_guardrails.mdmarkdown10.3 KB
references/composition_grammar_catalog.mdmarkdown4.0 KB
references/deck_creation.mdmarkdown1.4 KB
references/deck_workspace_mode.mdmarkdown34.4 KB
references/design_philosophy.mdmarkdown5.5 KB
references/dynamic_design_and_subagents.mdmarkdown12.3 KB
references/editing.mdmarkdown12.4 KB
references/external_best_practices.mdmarkdown1.7 KB
references/large_style_corpus_sources.jsonconfig22.7 KB
references/model_adaptive_workflow.mdmarkdown6.6 KB
references/outline_schema.mdmarkdown44.8 KB
references/planning_schema.mdmarkdown54.8 KB
references/pptxgenjs.mdmarkdown7.6 KB
references/preview_extension.mdmarkdown1.7 KB
references/reference_script_patterns.mdmarkdown13.5 KB
references/renderer_role_contracts_v2.jsonconfig38.2 KB
references/reproducible_workflow.mdmarkdown5.1 KB
references/speed_and_rendering.mdmarkdown4.6 KB
references/style_grammar_index.jsonconfig364.2 KB
references/style_inspiration_corpus.jsonconfig32.9 KB
references/style_reference_catalog.mdmarkdown23.9 KB
references/style_reference_sources.jsonconfig35.8 KB
references/style_token_atlas.jsonconfig174.7 KB
references/subagent_patterns.mdmarkdown10.2 KB
references/visual_qa_prompt.mdmarkdown4.9 KB
references/visual_reference_catalog.jsonconfig26.6 KB
references/visual_reference_catalog.mdmarkdown6.0 KB
schemas/deck_ir.schema.jsonconfig9.5 KB
schemas/renderer_capabilities_v2.jsonconfig701 B
scripts/accessibility_qa.pyscript24.8 KB
scripts/action_registry.pyscript12.5 KB
scripts/add_slide.pyscript8.6 KB
scripts/advance_delivery.pyscript88.2 KB
scripts/advance_workspace.pyscript150.3 KB
scripts/apply_artifact_manifest_bindings.pyscript54.1 KB
scripts/apply_atom_composition.pyscript8.2 KB
scripts/apply_data_analysis_handoff.pyscript67.0 KB
scripts/apply_deck_intake_answers.pyscript35.6 KB
scripts/apply_design_contract.pyscript71.7 KB
scripts/apply_outline_authoring_handoff.pyscript23.7 KB
scripts/apply_pptx_style_fragment.pyscript19.7 KB
scripts/asset_stage.pyscript24.6 KB
scripts/audition_styles.pyscript8.7 KB
scripts/benchmark_decks.pyexecutablescript45.4 KB
scripts/build_deck.pyexecutablescript173.6 KB
scripts/build_deck_pptxgenjs.jsexecutablescript72.7 KB
scripts/build_large_style_corpus_contact_sheets.pyscript18.1 KB
scripts/build_workspace.pyscript126.2 KB
scripts/clean_unpacked.pyscript12.9 KB
scripts/compact_source_footers.pyscript17.8 KB
scripts/composition_grammar_catalog.pyscript30.3 KB
scripts/deck_benchmark.pyscript71.1 KB
scripts/deck_intake.pyscript6.9 KB
scripts/deck_ir.pyscript47.5 KB
scripts/design_catalog_selector.pyscript17.4 KB
scripts/design_rules_qa.pyscript24.8 KB
scripts/design_tokens.pyscript20.3 KB
scripts/edit_deck.pyscript8.4 KB
scripts/emit_content_research.pyscript4.6 KB
scripts/emit_data_analysis_prompt.pyscript30.1 KB
scripts/emit_deck_intake_prompt.pyexecutablescript19.9 KB
scripts/emit_deck_start_packet.pyscript97.1 KB
scripts/emit_design_contract_prompt.pyscript66.2 KB
scripts/emit_outline_authoring_prompt.pyscript35.4 KB
scripts/emit_outline_critique.pyscript11.6 KB
scripts/emit_style_content_router.pyscript49.6 KB
scripts/extract_outline.pyexecutablescript4.1 KB
scripts/extract_pptx_style.pyscript33.2 KB
scripts/fetch_wikimedia_cc.pyscript8.6 KB
scripts/finalize_quick_deck.pyscript17.6 KB
scripts/generate_openai_image.pyscript5.6 KB
scripts/init_deck_workspace.pyscript74.4 KB
scripts/inspect_artifact_manifest.pyscript29.8 KB
scripts/inventory.pyscript10.6 KB
scripts/iterate_deck.pyexecutablescript10.2 KB
scripts/layout_lint.pyscript40.4 KB
scripts/log_skill_telemetry.pyscript6.9 KB
scripts/model_adaptive_workflow.pyscript28.0 KB
scripts/office_package_hash.pyscript1.6 KB
scripts/pack_pptx.pyscript5.7 KB
scripts/palette_from_topic.pyscript4.1 KB
scripts/plan_research_assets.pyscript13.1 KB
scripts/preflight.pyscript136.9 KB
scripts/present.pyscript9.6 KB
scripts/python_runtime.pyscript787 B
scripts/qa_gate.pyexecutablescript27.4 KB
scripts/qa_visual_gate.pyexecutablescript8.5 KB
scripts/reference_deck.pyscript12.7 KB
scripts/render_cache.pyscript3.9 KB
scripts/render_mermaid.pyscript8.9 KB
scripts/render_slides.pyexecutablescript19.4 KB
scripts/repair_packet.pyscript14.7 KB
scripts/report_delivery_readiness.pyscript107.6 KB
scripts/report_workspace_readiness.pyscript244.6 KB
scripts/requirements-runtime.txtmarkdown472 B
scripts/role_layout_contracts.pyscript10.6 KB
scripts/runtime_doctor.pyscript6.3 KB
scripts/scaffold_figure_artifacts.pyscript92.3 KB
scripts/source_fidelity.pyscript30.5 KB
scripts/structural_diversity_v2.pyscript32.5 KB
scripts/style_atom_router.pyscript14.5 KB
scripts/style_inspiration_corpus.pyscript15.1 KB
scripts/style_reference_catalog.pyscript142.8 KB
scripts/style_reference_sources.pyscript12.7 KB
scripts/style_treatment_profiles.pyscript26.0 KB
scripts/summarize_skill_log.pyscript7.0 KB
scripts/taste_grammar_catalog.pyscript27.0 KB
scripts/test_structural_diversity_v2.pyscript4.9 KB
scripts/text_fit.pyscript23.6 KB
scripts/thumbnail.pyscript9.2 KB
scripts/trim_image_whitespace.pyexecutablescript5.4 KB
scripts/unpack_pptx.pyscript8.3 KB
scripts/upgrade_renderer_role_contracts_v2.pyscript7.3 KB
scripts/validate_planning.pyscript169.2 KB
scripts/verify_narration.pyscript10.6 KB
scripts/visual_qa.pyscript7.7 KB
scripts/visual_review.pyscript41.1 KB
scripts/visual_review_receipt.pyscript8.3 KB
scripts/workflow_atom_context.pyscript17.3 KB
templates/pptxgenjs/README.mdmarkdown8.4 KB
templates/pptxgenjs/presets.jsscript5.6 KB
templates/pptxgenjs/readable_role_layouts.jsscript17.5 KB
templates/pptxgenjs/render_plan.jsscript12.6 KB
templates/pptxgenjs/role_layout_contracts.jsscript4.7 KB
templates/pptxgenjs/slides.jsscript451.0 KB
templates/pptxgenjs/space_allocation.jsscript1.6 KB

scripts/structural_diversity_v2.py

View on GitHub
#!/usr/bin/env python3
"""Human-aligned, role-aware structural diversity evaluation for PPTX decks.

The evaluator deliberately ignores paint (color, fill, stroke) and shapes that
do not carry semantic content. Rendered pixels are used only for an edge-hash
diagnostic and for contact-sheet/skeleton proof artifacts.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import math
import re
from dataclasses import asdict, dataclass
from itertools import combinations
from pathlib import Path
from typing import Any, Iterable, Mapping, Sequence

from PIL import Image, ImageDraw, ImageFilter, ImageFont, ImageOps
from pptx import Presentation
from pptx.enum.shapes import MSO_SHAPE_TYPE


GRID_COLUMNS = 6
GRID_ROWS = 4
WHITESPACE_COLUMNS = 4
WHITESPACE_ROWS = 3
EDGE_HASH_SIZE = (24, 14)
GEOMETRY_QUANTUM = 1.0 / 48.0
FEATURE_GROUP_WEIGHTS = {
    "semantic_occupancy": 0.28,
    "topology": 0.22,
    "anchor_geometry": 0.23,
    "hierarchy_reading_order": 0.17,
    "whitespace_zoning": 0.10,
}


@dataclass(frozen=True)
class RolePolicy:
    distance_threshold: float
    minimum_clusters: int
    maximum_cluster_size: int
    maximum_largest_cluster_ratio: float
    minimum_normalized_entropy: float


DEFAULT_ROLE_POLICIES: dict[str, RolePolicy] = {
    "title": RolePolicy(0.060, 8, 2, 0.16, 0.78),
    "section": RolePolicy(0.060, 8, 2, 0.16, 0.78),
    "evidence": RolePolicy(0.020, 8, 2, 0.16, 0.78),
    "comparison": RolePolicy(0.010, 8, 2, 0.16, 0.78),
    "chart": RolePolicy(0.010, 8, 2, 0.16, 0.78),
    "table": RolePolicy(0.017, 8, 2, 0.16, 0.78),
    "decision": RolePolicy(0.018, 8, 2, 0.16, 0.78),
    "references": RolePolicy(0.005, 8, 2, 0.16, 0.78),
    "dense_title_evidence": RolePolicy(0.010, 8, 2, 0.16, 0.78),
}
DEFAULT_POLICY = RolePolicy(0.020, 8, 2, 0.16, 0.78)


@dataclass
class SemanticShape:
    kind: str
    x: float
    y: float
    w: float
    h: float
    font_size: float
    text_length: int
    placeholder: str
    name: str

    @property
    def area(self) -> float:
        return max(0.0, self.w) * max(0.0, self.h)

    @property
    def cx(self) -> float:
        return self.x + self.w / 2.0

    @property
    def cy(self) -> float:
        return self.y + self.h / 2.0


def _clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
    return min(high, max(low, value))


def _quantize(value: float, quantum: float = GEOMETRY_QUANTUM) -> float:
    return round(_clamp(value) / quantum) * quantum


def _meaningful_text(value: str) -> str:
    return " ".join(str(value or "").split())


def _font_size(shape: Any) -> float:
    if not bool(getattr(shape, "has_text_frame", False)):
        return 0.0
    sizes: list[float] = []
    for paragraph in shape.text_frame.paragraphs:
        if paragraph.font.size:
            sizes.append(float(paragraph.font.size.pt))
        for run in paragraph.runs:
            if run.font.size:
                sizes.append(float(run.font.size.pt))
    return max(sizes, default=0.0)


def _placeholder_name(shape: Any) -> str:
    if not bool(getattr(shape, "is_placeholder", False)):
        return ""
    try:
        return str(shape.placeholder_format.type).split(".")[-1].upper()
    except (AttributeError, ValueError):
        return ""


def _group_has_semantics(shape: Any) -> bool:
    for child in getattr(shape, "shapes", []):
        if bool(getattr(child, "has_chart", False)) or bool(getattr(child, "has_table", False)):
            return True
        if getattr(child, "shape_type", None) == MSO_SHAPE_TYPE.PICTURE:
            return True
        if _meaningful_text(getattr(child, "text", "")):
            return True
    return False


def _base_kind(shape: Any, text: str, x: float, y: float, w: float, h: float) -> str:
    area = w * h
    placeholder = _placeholder_name(shape)
    if any(token in placeholder for token in ("FOOTER", "DATE", "SLIDE_NUMBER")):
        return ""
    if bool(getattr(shape, "has_chart", False)):
        return "chart"
    if bool(getattr(shape, "has_table", False)):
        return "table"
    shape_type = getattr(shape, "shape_type", None)
    if shape_type == MSO_SHAPE_TYPE.PICTURE:
        if area < 0.008 or area > 0.92:
            return ""
        return "image"
    if shape_type == MSO_SHAPE_TYPE.GROUP:
        return "group" if area >= 0.008 and _group_has_semantics(shape) else ""
    if not text or not re.search(r"[A-Za-z0-9]", text):
        return ""
    if y >= 0.925 and h <= 0.075:
        return ""
    if area < 0.0015 or (len(text) <= 2 and re.fullmatch(r"\d+", text)):
        return ""
    return "text"


def extract_semantic_shapes(slide: Any, slide_width: int, slide_height: int) -> list[SemanticShape]:
    """Return normalized semantic shapes, excluding paint-only decoration."""
    records: list[SemanticShape] = []
    for shape in slide.shapes:
        try:
            x = _clamp(float(shape.left) / float(slide_width))
            y = _clamp(float(shape.top) / float(slide_height))
            w = _clamp(float(shape.width) / float(slide_width), 0.0, 1.0 - x)
            h = _clamp(float(shape.height) / float(slide_height), 0.0, 1.0 - y)
        except (AttributeError, TypeError, ValueError, ZeroDivisionError):
            continue
        text = _meaningful_text(getattr(shape, "text", ""))
        kind = _base_kind(shape, text, x, y, w, h)
        if not kind:
            continue
        records.append(
            SemanticShape(
                kind=kind,
                x=_quantize(x),
                y=_quantize(y),
                w=_quantize(w),
                h=_quantize(h),
                font_size=_font_size(shape),
                text_length=len(text),
                placeholder=_placeholder_name(shape),
                name=str(getattr(shape, "name", "")),
            )
        )

    text_records = [record for record in records if record.kind == "text"]
    maximum_font = max((record.font_size for record in text_records), default=0.0)
    for record in text_records:
        title_placeholder = any(token in record.placeholder for token in ("TITLE", "CENTER_TITLE"))
        prominent_top_text = (
            maximum_font > 0
            and record.font_size >= maximum_font * 0.78
            and record.y <= 0.36
        )
        if title_placeholder or prominent_top_text:
            record.kind = "title"
    records.sort(key=lambda item: (item.y, item.x, -item.area, item.kind, item.name))
    return records


def _cell_coverage(shapes: Sequence[SemanticShape], columns: int, rows: int) -> list[float]:
    coverage: list[float] = []
    cell_w = 1.0 / columns
    cell_h = 1.0 / rows
    cell_area = cell_w * cell_h
    for row in range(rows):
        top = row * cell_h
        bottom = top + cell_h
        for column in range(columns):
            left = column * cell_w
            right = left + cell_w
            occupied = 0.0
            for shape in shapes:
                overlap_w = max(0.0, min(right, shape.x + shape.w) - max(left, shape.x))
                overlap_h = max(0.0, min(bottom, shape.y + shape.h) - max(top, shape.y))
                occupied += overlap_w * overlap_h
            coverage.append(round(_clamp(occupied / cell_area), 6))
    return coverage


def _cluster_axis(values: Sequence[float], tolerance: float = 0.10) -> int:
    if not values:
        return 0
    groups = [sorted(values)[0]]
    for value in sorted(values)[1:]:
        if abs(value - groups[-1]) > tolerance:
            groups.append(value)
        else:
            groups[-1] = (groups[-1] + value) / 2.0
    return len(groups)


def _rect_overlap(left: SemanticShape, right: SemanticShape) -> float:
    overlap_w = max(0.0, min(left.x + left.w, right.x + right.w) - max(left.x, right.x))
    overlap_h = max(0.0, min(left.y + left.h, right.y + right.h) - max(left.y, right.y))
    overlap = overlap_w * overlap_h
    denominator = min(left.area, right.area)
    return overlap / denominator if denominator else 0.0


def _rect_vector(shape: SemanticShape | None) -> list[float]:
    if shape is None:
        return [0.0, 0.0, 0.0, 0.0]
    return [shape.x, shape.y, shape.w, shape.h]


def _reading_order_vector(shapes: Sequence[SemanticShape]) -> list[float]:
    kind_codes = {
        "title": 0.0,
        "text": 0.2,
        "image": 0.4,
        "chart": 0.6,
        "table": 0.8,
        "group": 1.0,
    }
    text_sizes = sorted({round(shape.font_size, 1) for shape in shapes if shape.font_size > 0}, reverse=True)
    vector: list[float] = []
    for shape in list(shapes)[:6]:
        x_zone = min(2, int(shape.cx * 3)) / 2.0
        kind_code = kind_codes.get(shape.kind, 1.0)
        if shape.font_size > 0 and text_sizes:
            rank = text_sizes.index(round(shape.font_size, 1))
            size_rank = 1.0 - min(rank, 3) / 3.0
        else:
            size_rank = 0.0
        vector.extend((x_zone, kind_code, size_rank))
    while len(vector) < 18:
        vector.extend((0.0, 0.0, 0.0))
    return vector[:18]


def measure_slide(slide: Any, slide_width: int, slide_height: int) -> dict[str, Any]:
    shapes = extract_semantic_shapes(slide, slide_width, slide_height)
    occupancy = _cell_coverage(shapes, GRID_COLUMNS, GRID_ROWS)
    whitespace_occupancy = _cell_coverage(shapes, WHITESPACE_COLUMNS, WHITESPACE_ROWS)
    kinds = ("title", "text", "image", "chart", "table", "group")
    kind_areas = [min(1.0, sum(shape.area for shape in shapes if shape.kind == kind)) for kind in kinds]
    union_proxy = sum(1.0 for value in occupancy if value >= 0.25) / len(occupancy)
    title = max((shape for shape in shapes if shape.kind == "title"), key=lambda item: item.area, default=None)
    non_titles = [shape for shape in shapes if shape.kind != "title"]
    primary = max(non_titles, key=lambda item: item.area, default=None)
    if shapes:
        left = min(shape.x for shape in shapes)
        top = min(shape.y for shape in shapes)
        right = max(shape.x + shape.w for shape in shapes)
        bottom = max(shape.y + shape.h for shape in shapes)
        total_area = sum(shape.area for shape in shapes) or 1.0
        centroid_x = sum(shape.cx * shape.area for shape in shapes) / total_area
        centroid_y = sum(shape.cy * shape.area for shape in shapes) / total_area
    else:
        left = top = right = bottom = centroid_x = centroid_y = 0.0

    pairs = list(combinations(shapes, 2))
    horizontal_aligned = sum(abs(left_shape.cy - right_shape.cy) <= 0.065 for left_shape, right_shape in pairs)
    vertical_aligned = sum(abs(left_shape.cx - right_shape.cx) <= 0.065 for left_shape, right_shape in pairs)
    overlapping = sum(_rect_overlap(left_shape, right_shape) >= 0.08 for left_shape, right_shape in pairs)
    pair_count = max(1, len(pairs))
    left_area = sum(shape.area for shape in shapes if shape.cx < 0.5)
    right_area = sum(shape.area for shape in shapes if shape.cx >= 0.5)
    top_area = sum(shape.area for shape in shapes if shape.cy < 0.5)
    bottom_area = sum(shape.area for shape in shapes if shape.cy >= 0.5)
    area_sum = max(1e-9, left_area + right_area)
    vertical_area_sum = max(1e-9, top_area + bottom_area)

    text_shapes = [shape for shape in shapes if shape.kind in {"title", "text"}]
    font_levels = len({round(shape.font_size / 4.0) for shape in text_shapes if shape.font_size > 0})
    title_area = sum(shape.area for shape in shapes if shape.kind == "title")
    body_area = sum(shape.area for shape in shapes if shape.kind == "text")
    first_anchor_index = next(
        (index for index, shape in enumerate(shapes) if shape.kind in {"image", "chart", "table", "group"}),
        len(shapes),
    )

    groups = {
        "semantic_occupancy": occupancy + kind_areas + [union_proxy],
        "topology": [
            min(len(shapes), 16) / 16.0,
            min(_cluster_axis([shape.cx for shape in shapes]), 6) / 6.0,
            min(_cluster_axis([shape.cy for shape in shapes]), 6) / 6.0,
            horizontal_aligned / pair_count,
            vertical_aligned / pair_count,
            overlapping / pair_count,
            left_area / area_sum,
            right_area / area_sum,
            top_area / vertical_area_sum,
            bottom_area / vertical_area_sum,
        ],
        "anchor_geometry": (
            _rect_vector(title)
            + _rect_vector(primary)
            + [left, top, max(0.0, right - left), max(0.0, bottom - top), centroid_x, centroid_y]
        ),
        "hierarchy_reading_order": [
            min(font_levels, 5) / 5.0,
            title_area / max(1e-9, title_area + body_area),
            min(len(text_shapes), 12) / 12.0,
            min(first_anchor_index, 8) / 8.0,
        ] + _reading_order_vector(shapes),
        "whitespace_zoning": [round(1.0 - value, 6) for value in whitespace_occupancy]
        + [left, 1.0 - right, top, 1.0 - bottom],
    }
    return {
        "semantic_shape_count": len(shapes),
        "semantic_shapes": [asdict(shape) for shape in shapes],
        "feature_groups": {key: [round(float(value), 6) for value in values] for key, values in groups.items()},
        "feature_vector": [
            round(float(value), 6)
            for key in FEATURE_GROUP_WEIGHTS
            for value in groups[key]
        ],
    }


def _group_distance(left: Sequence[float], right: Sequence[float]) -> float:
    if len(left) != len(right):
        raise ValueError(f"Feature lengths differ: {len(left)} != {len(right)}")
    if not left:
        return 0.0
    return sum(abs(float(a) - float(b)) for a, b in zip(left, right)) / len(left)


def structural_distance(left: Mapping[str, Any], right: Mapping[str, Any]) -> tuple[float, dict[str, float]]:
    left_groups = left.get("feature_groups") or {}
    right_groups = right.get("feature_groups") or {}
    group_distances = {
        key: _group_distance(left_groups.get(key, []), right_groups.get(key, []))
        for key in FEATURE_GROUP_WEIGHTS
    }
    distance = sum(group_distances[key] * FEATURE_GROUP_WEIGHTS[key] for key in FEATURE_GROUP_WEIGHTS)
    return round(distance, 6), {key: round(value, 6) for key, value in group_distances.items()}


def _average_link_distance(
    left_cluster: Sequence[str],
    right_cluster: Sequence[str],
    distances: Mapping[tuple[str, str], float],
) -> float:
    values = []
    for left in left_cluster:
        for right in right_cluster:
            key = tuple(sorted((left, right)))
            values.append(float(distances[key]))
    return sum(values) / len(values)


def deterministic_clusters(ids: Sequence[str], distances: Mapping[tuple[str, str], float], threshold: float) -> list[list[str]]:
    """Agglomerative average-link clustering with stable lexical tie-breaking."""
    clusters = [[item] for item in sorted(ids)]
    while True:
        candidate: tuple[float, tuple[str, ...], int, int] | None = None
        for left_index in range(len(clusters)):
            for right_index in range(left_index + 1, len(clusters)):
                distance = _average_link_distance(clusters[left_index], clusters[right_index], distances)
                lexical = tuple(sorted(clusters[left_index] + clusters[right_index]))
                value = (round(distance, 12), lexical, left_index, right_index)
                if distance <= threshold and (candidate is None or value < candidate):
                    candidate = value
        if candidate is None:
            break
        _, _, left_index, right_index = candidate
        merged = sorted(clusters[left_index] + clusters[right_index])
        clusters = [cluster for index, cluster in enumerate(clusters) if index not in {left_index, right_index}]
        clusters.append(merged)
        clusters.sort(key=lambda cluster: tuple(cluster))
    return sorted(clusters, key=lambda cluster: (-len(cluster), tuple(cluster)))


def normalized_cluster_entropy(clusters: Sequence[Sequence[str]], population: int) -> float:
    if population <= 1:
        return 1.0
    entropy = 0.0
    for cluster in clusters:
        probability = len(cluster) / population
        if probability > 0:
            entropy -= probability * math.log2(probability)
    return entropy / math.log2(population)


def _edge_hash(path: Path) -> tuple[str, int]:
    with Image.open(path) as raw:
        gray = ImageOps.autocontrast(raw.convert("L"))
        edge = ImageOps.autocontrast(gray.filter(ImageFilter.FIND_EDGES))
        thumb = edge.resize(EDGE_HASH_SIZE, Image.Resampling.LANCZOS)
        values = [int(value) for value in thumb.getdata()]
    threshold = sum(values) / max(1, len(values))
    bits = "".join("1" if value >= threshold else "0" for value in values)
    return hex(int(bits, 2))[2:].zfill((len(bits) + 3) // 4), len(bits)


def _edge_hash_distance(left: str, right: str, bit_count: int) -> float:
    if not bit_count:
        return 0.0
    return bin(int(left, 16) ^ int(right, 16)).count("1") / bit_count


def _font(size: int, bold: bool = False) -> ImageFont.ImageFont:
    candidates = [
        "/System/Library/Fonts/Supplemental/Arial Bold.ttf" if bold else "/System/Library/Fonts/Supplemental/Arial.ttf",
        "/System/Library/Fonts/Supplemental/Helvetica.ttc",
    ]
    for candidate in candidates:
        try:
            return ImageFont.truetype(candidate, size=size)
        except OSError:
            continue
    return ImageFont.load_default()


def _skeleton_overlay(measurement: Mapping[str, Any], render_path: Path | None, output: Path, label: str) -> None:
    if render_path and render_path.is_file():
        with Image.open(render_path) as raw:
            canvas = raw.convert("RGB")
    else:
        canvas = Image.new("RGB", (1280, 720), "white")
    draw = ImageDraw.Draw(canvas)
    colors = {
        "title": "#d62728",
        "text": "#2563eb",
        "image": "#16a34a",
        "chart": "#9333ea",
        "table": "#ea580c",
        "group": "#0891b2",
    }
    width, height = canvas.size
    for shape in measurement.get("semantic_shapes") or []:
        x0 = int(float(shape["x"]) * width)
        y0 = int(float(shape["y"]) * height)
        x1 = int((float(shape["x"]) + float(shape["w"])) * width)
        y1 = int((float(shape["y"]) + float(shape["h"])) * height)
        color = colors.get(str(shape.get("kind")), "#111827")
        draw.rectangle((x0, y0, x1, y1), outline=color, width=max(2, width // 500))
        draw.text((x0 + 4, y0 + 3), str(shape.get("kind")), fill=color, font=_font(max(11, width // 90), True))
    draw.rectangle((0, 0, width, max(28, height // 20)), fill="white")
    draw.text((8, 5), label, fill="#111827", font=_font(max(14, width // 65), True))
    output.parent.mkdir(parents=True, exist_ok=True)
    canvas.save(output)


def _contact_sheet(items: Sequence[tuple[str, Path]], output: Path, title: str) -> None:
    if not items:
        return
    columns = min(4, len(items))
    tile_w, tile_h, label_h, gap, heading_h = 320, 180, 34, 14, 62
    rows = math.ceil(len(items) / columns)
    canvas = Image.new(
        "RGB",
        (
            columns * tile_w + (columns + 1) * gap,
            heading_h + rows * (tile_h + label_h + gap) + gap,
        ),
        "white",
    )
    draw = ImageDraw.Draw(canvas)
    draw.text((gap, 14), title, fill="#111827", font=_font(26, True))
    for index, (label, path) in enumerate(items):
        row, column = divmod(index, columns)
        x = gap + column * (tile_w + gap)
        y = heading_h + row * (tile_h + label_h + gap)
        draw.text((x, y), label, fill="#111827", font=_font(16, True))
        with Image.open(path) as raw:
            tile = ImageOps.fit(raw.convert("RGB"), (tile_w, tile_h), method=Image.Resampling.LANCZOS)
        canvas.paste(tile, (x, y + label_h))
    output.parent.mkdir(parents=True, exist_ok=True)
    canvas.save(output)


def _resolve_path(base: Path, value: str | Path | None) -> Path | None:
    if not value:
        return None
    path = Path(value)
    return path if path.is_absolute() else (base / path).resolve()


def _policy_for(role: str, overrides: Mapping[str, Any]) -> RolePolicy:
    default = DEFAULT_ROLE_POLICIES.get(role, DEFAULT_POLICY)
    raw = overrides.get(role) if isinstance(overrides.get(role), Mapping) else {}
    return RolePolicy(
        distance_threshold=float(raw.get("distance_threshold", default.distance_threshold)),
        minimum_clusters=int(raw.get("minimum_clusters", default.minimum_clusters)),
        maximum_cluster_size=int(raw.get("maximum_cluster_size", default.maximum_cluster_size)),
        maximum_largest_cluster_ratio=float(
            raw.get("maximum_largest_cluster_ratio", default.maximum_largest_cluster_ratio)
        ),
        minimum_normalized_entropy=float(
            raw.get("minimum_normalized_entropy", default.minimum_normalized_entropy)
        ),
    )


def evaluate_manifest(
    manifest: Mapping[str, Any],
    *,
    manifest_base: Path,
    artifacts_dir: Path | None = None,
    repeated_pair_role_limit: int = 5,
) -> dict[str, Any]:
    deck_specs = manifest.get("decks")
    if not isinstance(deck_specs, list) or len(deck_specs) < 2:
        raise ValueError("manifest.decks must contain at least two deck entries")
    policies = manifest.get("role_policies") if isinstance(manifest.get("role_policies"), Mapping) else {}
    coherent_groups = (
        manifest.get("coherent_groups")
        if isinstance(manifest.get("coherent_groups"), Mapping)
        else {}
    )
    measurements_by_role: dict[str, dict[str, dict[str, Any]]] = {}
    render_paths: dict[tuple[str, str], Path] = {}
    source_records: list[dict[str, Any]] = []

    for deck_spec in deck_specs:
        if not isinstance(deck_spec, Mapping):
            raise ValueError("Each deck entry must be an object")
        deck_id = str(deck_spec.get("id") or "").strip()
        pptx_path = _resolve_path(manifest_base, deck_spec.get("pptx"))
        slide_specs = deck_spec.get("slides")
        if not deck_id or pptx_path is None or not pptx_path.is_file():
            raise ValueError(f"Invalid deck entry for {deck_id or '<missing id>'}: PPTX not found")
        if not isinstance(slide_specs, list) or not slide_specs:
            raise ValueError(f"Deck {deck_id} has no slide-role mappings")
        presentation = Presentation(str(pptx_path))
        seen_roles: set[str] = set()
        for slide_spec in slide_specs:
            if not isinstance(slide_spec, Mapping):
                raise ValueError(f"Deck {deck_id} has a non-object slide mapping")
            role = str(slide_spec.get("role") or "").strip()
            slide_index = int(slide_spec.get("index") or 0)
            if not role or role in seen_roles:
                raise ValueError(f"Deck {deck_id} has a missing or duplicate role: {role!r}")
            if slide_index < 1 or slide_index > len(presentation.slides):
                raise ValueError(f"Deck {deck_id} role {role} has invalid one-based slide index {slide_index}")
            seen_roles.add(role)
            measurement = measure_slide(
                presentation.slides[slide_index - 1], presentation.slide_width, presentation.slide_height
            )
            measurement["slide_index"] = slide_index
            measurements_by_role.setdefault(role, {})[deck_id] = measurement
            render_path = _resolve_path(manifest_base, slide_spec.get("render"))
            if render_path and render_path.is_file():
                render_paths[(deck_id, role)] = render_path
        source_records.append({"id": deck_id, "pptx": str(pptx_path), "roles": sorted(seen_roles)})

    expected_roles = set(measurements_by_role)
    deck_ids = sorted(record["id"] for record in source_records)
    for record in source_records:
        missing = sorted(expected_roles - set(record["roles"]))
        if missing:
            raise ValueError(f"Deck {record['id']} is missing roles: {', '.join(missing)}")

    failures: list[dict[str, Any]] = []
    role_reports: dict[str, Any] = {}
    co_clustered_counts: dict[tuple[str, str], list[str]] = {}
    edge_hashes: dict[tuple[str, str], tuple[str, int]] = {}
    for key, path in render_paths.items():
        edge_hashes[key] = _edge_hash(path)

    for role in sorted(expected_roles):
        role_measurements = measurements_by_role[role]
        structural_pairs: list[dict[str, Any]] = []
        distance_lookup: dict[tuple[str, str], float] = {}
        edge_pairs: list[dict[str, Any]] = []
        for left_id, right_id in combinations(deck_ids, 2):
            distance, group_distances = structural_distance(role_measurements[left_id], role_measurements[right_id])
            key = (left_id, right_id)
            distance_lookup[key] = distance
            structural_pairs.append(
                {
                    "left": left_id,
                    "right": right_id,
                    "distance": distance,
                    "group_distances": group_distances,
                }
            )
            if (left_id, role) in edge_hashes and (right_id, role) in edge_hashes:
                left_hash, bit_count = edge_hashes[(left_id, role)]
                right_hash, _ = edge_hashes[(right_id, role)]
                edge_pairs.append(
                    {
                        "left": left_id,
                        "right": right_id,
                        "normalized_distance": round(_edge_hash_distance(left_hash, right_hash, bit_count), 6),
                    }
                )
        structural_pairs.sort(key=lambda item: (item["distance"], item["left"], item["right"]))
        edge_pairs.sort(key=lambda item: (item["normalized_distance"], item["left"], item["right"]))
        policy = _policy_for(role, policies)
        clusters = deterministic_clusters(deck_ids, distance_lookup, policy.distance_threshold)
        entropy = normalized_cluster_entropy(clusters, len(deck_ids))
        largest_cluster = max((len(cluster) for cluster in clusters), default=0)
        largest_ratio = largest_cluster / len(deck_ids)
        role_failures: list[str] = []
        if len(clusters) < policy.minimum_clusters:
            role_failures.append(f"cluster_count={len(clusters)} below={policy.minimum_clusters}")
        if largest_ratio > policy.maximum_largest_cluster_ratio:
            role_failures.append(
                f"largest_cluster_ratio={largest_ratio:.4f} above={policy.maximum_largest_cluster_ratio:.4f}"
            )
        if largest_cluster > policy.maximum_cluster_size:
            role_failures.append(
                f"largest_cluster_size={largest_cluster} above={policy.maximum_cluster_size}"
            )
        if entropy < policy.minimum_normalized_entropy:
            role_failures.append(
                f"normalized_entropy={entropy:.4f} below={policy.minimum_normalized_entropy:.4f}"
            )
        cross_grammar_clusters: list[dict[str, Any]] = []
        if coherent_groups:
            for cluster in clusters:
                groups = sorted(
                    {
                        str(coherent_groups.get(deck_id) or "").strip()
                        for deck_id in cluster
                        if str(coherent_groups.get(deck_id) or "").strip()
                    }
                )
                if len(groups) > 1:
                    cross_grammar_clusters.append(
                        {"members": sorted(cluster), "coherent_groups": groups}
                    )
            if cross_grammar_clusters:
                role_failures.append(
                    f"cross_grammar_cluster_count={len(cross_grammar_clusters)}"
                )
        if role_failures:
            failures.append({"type": "role_policy", "role": role, "reasons": role_failures})
        for cluster in cross_grammar_clusters:
            failures.append({"type": "cross_grammar_cluster", "role": role, **cluster})
        for cluster in clusters:
            for pair in combinations(sorted(cluster), 2):
                co_clustered_counts.setdefault(pair, []).append(role)
        role_reports[role] = {
            "passed": not role_failures,
            "policy": asdict(policy),
            "cluster_count": len(clusters),
            "largest_cluster_size": largest_cluster,
            "largest_cluster_ratio": round(largest_ratio, 6),
            "normalized_entropy": round(entropy, 6),
            "clusters": [{"cluster_id": index + 1, "members": members} for index, members in enumerate(clusters)],
            "cross_grammar_clusters": cross_grammar_clusters,
            "pairwise_distances": structural_pairs,
            "edge_hash_diagnostic": {
                "used_for_gate": False,
                "hashes": {
                    deck_id: edge_hashes[(deck_id, role)][0]
                    for deck_id in deck_ids
                    if (deck_id, role) in edge_hashes
                },
                "pairwise_distances": edge_pairs,
            },
            "features": role_measurements,
            "failures": role_failures,
        }

    repeated_pairs = []
    for pair, roles in sorted(co_clustered_counts.items(), key=lambda item: (-len(item[1]), item[0])):
        same_coherent_group = bool(
            coherent_groups.get(pair[0])
            and coherent_groups.get(pair[0]) == coherent_groups.get(pair[1])
        )
        record = {
            "left": pair[0],
            "right": pair[1],
            "role_count": len(roles),
            "roles": sorted(roles),
            "same_coherent_group": same_coherent_group,
            "coherent_group": coherent_groups.get(pair[0]) if same_coherent_group else "",
        }
        repeated_pairs.append(record)
        if len(roles) >= repeated_pair_role_limit and not same_coherent_group:
            failures.append({"type": "repeated_pair", **record, "limit": repeated_pair_role_limit})

    artifacts: dict[str, Any] = {"skeleton_overlays": {}, "contact_sheets": {}}
    if artifacts_dir is not None:
        artifacts_dir.mkdir(parents=True, exist_ok=True)
        for role in sorted(expected_roles):
            contact_items: list[tuple[str, Path]] = []
            for deck_id in deck_ids:
                overlay = artifacts_dir / "skeletons" / role / f"{deck_id}.png"
                _skeleton_overlay(
                    measurements_by_role[role][deck_id],
                    render_paths.get((deck_id, role)),
                    overlay,
                    f"{deck_id} | {role}",
                )
                artifacts["skeleton_overlays"].setdefault(role, {})[deck_id] = str(overlay)
                contact_items.append((deck_id, overlay))
            contact = artifacts_dir / "contact_sheets" / f"{role}.jpg"
            _contact_sheet(contact_items, contact, f"Structural skeletons | {role}")
            artifacts["contact_sheets"][role] = str(contact)

    canonical_features = json.dumps(
        {role: role_reports[role]["features"] for role in sorted(role_reports)},
        sort_keys=True,
        separators=(",", ":"),
    ).encode("utf-8")
    return {
        "schema_version": "structural-diversity-v2",
        "passed": not failures,
        "deck_count": len(deck_ids),
        "roles": sorted(expected_roles),
        "feature_groups": FEATURE_GROUP_WEIGHTS,
        "paint_features_ignored": ["color", "fill", "stroke", "decorative_only_shapes"],
        "clustering": {
            "algorithm": "deterministic_agglomerative_average_link",
            "repeated_pair_role_limit": repeated_pair_role_limit,
            "coherent_group_pair_exemption": bool(coherent_groups),
        },
        "feature_digest": hashlib.sha256(canonical_features).hexdigest(),
        "decks": source_records,
        "role_reports": role_reports,
        "repeated_co_clustered_pairs": repeated_pairs,
        "artifacts": artifacts,
        "failures": failures,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--manifest", type=Path, required=True)
    parser.add_argument("--report", type=Path, required=True)
    parser.add_argument("--artifacts-dir", type=Path)
    parser.add_argument("--repeated-pair-role-limit", type=int, default=5)
    args = parser.parse_args()
    manifest_path = args.manifest.resolve()
    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
    report = evaluate_manifest(
        manifest,
        manifest_base=manifest_path.parent,
        artifacts_dir=args.artifacts_dir.resolve() if args.artifacts_dir else None,
        repeated_pair_role_limit=args.repeated_pair_role_limit,
    )
    args.report.parent.mkdir(parents=True, exist_ok=True)
    args.report.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
    summary = {
        "passed": report["passed"],
        "report": str(args.report.resolve()),
        "deck_count": report["deck_count"],
        "roles": report["roles"],
        "role_clusters": {
            role: report["role_reports"][role]["cluster_count"] for role in report["roles"]
        },
        "failure_count": len(report["failures"]),
    }
    print(json.dumps(summary, indent=2))
    return 0 if report["passed"] else 1


if __name__ == "__main__":
    raise SystemExit(main())
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall