pictovap 0.2.1__tar.gz

pictovap-0.2.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kemal Kaya — yoldaolmak.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

pictovap-0.2.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: pictovap
+Version: 0.2.1
+Summary: Open-source visual finishing engine for content publishers.
+Author-email: Pictovap Contributors <hello@yoldaolmak.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yoldaolmak/Pictovap
+Project-URL: Documentation, https://github.com/yoldaolmak/Pictovap/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/yoldaolmak/Pictovap.git
+Keywords: wordpress,image automation,llm,vision,seo,cms,unsplash
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: providers
+Requires-Dist: anthropic>=0.3.0; extra == "providers"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Dynamic: license-file
+
+# Pictovap
+
+[![CI](https://github.com/yoldaolmak/Pictovap/actions/workflows/ci.yml/badge.svg)](https://github.com/yoldaolmak/Pictovap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Pictovap is an open-source visual finishing engine for content publishers.**
+It turns a finished article into a visually complete, rights-aware,
+publish-ready CMS page — and shows its work at every step.
+
+## The Problem
+
+Every publisher runs the same manual routine before an article can go live:
+find images that actually fit the section they're going into, check whether
+the license permits the intended use, resize and convert them to the site's
+format, write alt text and a caption for each one, and place them at the
+right point in the CMS. None of this is hard, individually. It is, however,
+*repetitive*, *easy to get wrong under deadline pressure*, and it *scales
+linearly with how much a publisher writes*. Skipped alt text quietly erodes
+accessibility and SEO. Untracked image provenance is a license or attribution
+problem waiting to surface later, when it's expensive to fix. None of this
+shows up in a style guide — it shows up as an hour of an editor's afternoon,
+per article, forever.
+
+Point solutions exist for pieces of this: stock photo plugins, DAM systems,
+generic AI image generators. What's largely missing is the connective layer
+— something that reads what the article actually needs, evaluates candidates
+against that need with a visible, auditable reason for every accept and
+reject, and hands a CMS a placement plan it can execute without a human
+re-deriving the same context from scratch.
+
+## The Solution
+
+Pictovap is that connective layer, built as an open, adapter-based pipeline
+rather than a closed SaaS product:
+
+```
+Article Input → Visual Brief → Candidate Images → Fit Score
+              → Provenance Pack → CMS Placement → Editor Report
+```
+
+- **Visual Brief** — a structured read of what imagery the article actually
+  needs, derived from its heading structure and content, not from a generic
+  "insert 3 images" rule.
+- **Fit Score** — every candidate is scored against the brief with a
+  transparent, deterministic reason attached (`selected`, `rejected`, or
+  `needs_review`, plus why). No black-box relevance number.
+- **Provenance Pack** — a persistent audit trail for every selected image:
+  source, license status, attribution, a content hash, and the exact
+  processing actions applied. This is what makes "where did this image come
+  from and are we allowed to use it" answerable six months later.
+- **CMS Placement** — a CMS-agnostic plan describing where and how each image
+  should be placed, independent of whether the destination is WordPress,
+  Ghost, Strapi, or something a contributor writes an adapter for tomorrow.
+- **Editor Report** — a human-readable Markdown review surface, so an editor
+  signs off on a report, not raw JSON, before anything reaches production.
+
+What makes this radical isn't any single stage — it's that the whole pipeline
+is a public, inspectable contract instead of a hosted black box, and that it
+is honest about its own workings by default: the credential-free demo below
+runs the entire pipeline end-to-end, with zero API keys and zero network
+calls, so you can read exactly what it does before you ever hand it a real
+site.
+
+Pictovap is not a stock photo search tool, a DAM, a generic AI image
+generator, or a WordPress-only plugin. It has no graphical interface yet — it
+is a CLI-first, adapter-based core, with the editor report as the intended
+human review surface and CMS adapters as the machine-facing execution layer.
+
+## Quickstart
+
+```bash
+git clone https://github.com/yoldaolmak/Pictovap.git
+cd Pictovap
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+Run the credential-free demo:
+
+```bash
+pictovap demo
+```
+
+```text
+  Brief:      4 slots from 3 sections
+  Evaluated:  5 candidates
+  Selected:   3 images
+  Rejected:   4 candidates
+  Placements: 3 instructions
+```
+
+No `.env` file, no API keys, no network calls — every candidate and score
+above comes from deterministic mock data, on purpose. This is the demo's
+guarantee, not just its default state.
+
+## Try Your Own Article
+
+```bash
+pictovap plan \
+  --article path/to/your/article.md \
+  --profile examples/profiles/sample-publisher.yaml \
+  --output my-plan.json \
+  --report my-report.md
+```
+
+`my-plan.json` is the canonical, machine-readable artifact for adapters and
+automation. `my-report.md` is the same plan, rendered for a human editor to
+review before anything gets published.
+
+## Adapters
+
+Pictovap connects to the outside world only through adapters — the core
+pipeline has no hardcoded dependency on any specific image provider or CMS.
+
+**Image sources:** local folder, Unsplash, DepositPhotos, Openverse (no key
+required), and Pexels are implemented. Pixabay and Wikimedia Commons are
+open contribution opportunities — see
+[Good First Issues](docs/contributing/good-first-issues.md). See
+[Image Source Adapters](docs/adapters/image-sources.md).
+
+**CMS placement:** WordPress (production-tested), Ghost and Strapi (reference
+implementations, real but with documented limitations). See
+[CMS Adapters](docs/adapters/cms-adapters.md).
+
+Every adapter degrades gracefully when unconfigured — a missing API key
+produces an empty result, not a crash, so a partially configured profile
+still runs. Writing a new adapter means implementing one method
+(`search_candidates` or `place`) against a documented `Protocol`; see the
+[Adapter Overview](docs/adapters/overview.md).
+
+## Multi-Language by Design
+
+Pictovap's own code, comments, and documentation are English. What it
+*generates* — alt text, captions, titles — is not tied to any one language.
+Article language is detected automatically (or set explicitly via the
+publisher profile), and generated metadata follows it: a Turkish article
+gets Turkish alt text, a French one gets French, and so on. This isn't a
+localization afterthought bolted onto an English-only tool; it's a parameter
+of the pipeline from the start.
+
+## Current Status and Limitations
+
+Pictovap is early open-source infrastructure. It has a genuinely
+credential-free local demo, documented core primitives, a real test suite,
+and a working adapter model — it does not yet claim broad ecosystem adoption
+or a large external contributor base.
+
+Specifically:
+
+- Only the WordPress CMS adapter is production-hardened; Ghost and Strapi are
+  real, tested reference implementations with documented gaps (see
+  [CMS Adapters](docs/adapters/cms-adapters.md)).
+- The credential-free demo always uses deterministic mock candidates by
+  design, regardless of what's configured in `.env` — `pictovap plan` is
+  where real, credentialed sources are used.
+- Deterministic structural extraction (the rule-based, non-AI language and
+  section detection) is reliable for English and Turkish; other languages
+  are untested.
+
+## Compatibility Note
+
+Product name: Pictovap. The Python package, import name, and console-script
+entry point may remain `pictova` for backward compatibility — see
+[Brand & Naming](docs/architecture/naming.md).
+
+## Contributing
+
+See the [Documentation Portal](docs/README.md) for architecture, concepts,
+and adapter-writing guides, and [DEVELOPER.md](docs/DEVELOPER.md) for the
+contribution workflow. Pull requests that add a new image source or CMS
+adapter, improve test coverage, or fix documentation are all welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pictovap-0.2.1/README.md

@@ -0,0 +1,177 @@
+# Pictovap
+
+[![CI](https://github.com/yoldaolmak/Pictovap/actions/workflows/ci.yml/badge.svg)](https://github.com/yoldaolmak/Pictovap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Pictovap is an open-source visual finishing engine for content publishers.**
+It turns a finished article into a visually complete, rights-aware,
+publish-ready CMS page — and shows its work at every step.
+
+## The Problem
+
+Every publisher runs the same manual routine before an article can go live:
+find images that actually fit the section they're going into, check whether
+the license permits the intended use, resize and convert them to the site's
+format, write alt text and a caption for each one, and place them at the
+right point in the CMS. None of this is hard, individually. It is, however,
+*repetitive*, *easy to get wrong under deadline pressure*, and it *scales
+linearly with how much a publisher writes*. Skipped alt text quietly erodes
+accessibility and SEO. Untracked image provenance is a license or attribution
+problem waiting to surface later, when it's expensive to fix. None of this
+shows up in a style guide — it shows up as an hour of an editor's afternoon,
+per article, forever.
+
+Point solutions exist for pieces of this: stock photo plugins, DAM systems,
+generic AI image generators. What's largely missing is the connective layer
+— something that reads what the article actually needs, evaluates candidates
+against that need with a visible, auditable reason for every accept and
+reject, and hands a CMS a placement plan it can execute without a human
+re-deriving the same context from scratch.
+
+## The Solution
+
+Pictovap is that connective layer, built as an open, adapter-based pipeline
+rather than a closed SaaS product:
+
+```
+Article Input → Visual Brief → Candidate Images → Fit Score
+              → Provenance Pack → CMS Placement → Editor Report
+```
+
+- **Visual Brief** — a structured read of what imagery the article actually
+  needs, derived from its heading structure and content, not from a generic
+  "insert 3 images" rule.
+- **Fit Score** — every candidate is scored against the brief with a
+  transparent, deterministic reason attached (`selected`, `rejected`, or
+  `needs_review`, plus why). No black-box relevance number.
+- **Provenance Pack** — a persistent audit trail for every selected image:
+  source, license status, attribution, a content hash, and the exact
+  processing actions applied. This is what makes "where did this image come
+  from and are we allowed to use it" answerable six months later.
+- **CMS Placement** — a CMS-agnostic plan describing where and how each image
+  should be placed, independent of whether the destination is WordPress,
+  Ghost, Strapi, or something a contributor writes an adapter for tomorrow.
+- **Editor Report** — a human-readable Markdown review surface, so an editor
+  signs off on a report, not raw JSON, before anything reaches production.
+
+What makes this radical isn't any single stage — it's that the whole pipeline
+is a public, inspectable contract instead of a hosted black box, and that it
+is honest about its own workings by default: the credential-free demo below
+runs the entire pipeline end-to-end, with zero API keys and zero network
+calls, so you can read exactly what it does before you ever hand it a real
+site.
+
+Pictovap is not a stock photo search tool, a DAM, a generic AI image
+generator, or a WordPress-only plugin. It has no graphical interface yet — it
+is a CLI-first, adapter-based core, with the editor report as the intended
+human review surface and CMS adapters as the machine-facing execution layer.
+
+## Quickstart
+
+```bash
+git clone https://github.com/yoldaolmak/Pictovap.git
+cd Pictovap
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+Run the credential-free demo:
+
+```bash
+pictovap demo
+```
+
+```text
+  Brief:      4 slots from 3 sections
+  Evaluated:  5 candidates
+  Selected:   3 images
+  Rejected:   4 candidates
+  Placements: 3 instructions
+```
+
+No `.env` file, no API keys, no network calls — every candidate and score
+above comes from deterministic mock data, on purpose. This is the demo's
+guarantee, not just its default state.
+
+## Try Your Own Article
+
+```bash
+pictovap plan \
+  --article path/to/your/article.md \
+  --profile examples/profiles/sample-publisher.yaml \
+  --output my-plan.json \
+  --report my-report.md
+```
+
+`my-plan.json` is the canonical, machine-readable artifact for adapters and
+automation. `my-report.md` is the same plan, rendered for a human editor to
+review before anything gets published.
+
+## Adapters
+
+Pictovap connects to the outside world only through adapters — the core
+pipeline has no hardcoded dependency on any specific image provider or CMS.
+
+**Image sources:** local folder, Unsplash, DepositPhotos, Openverse (no key
+required), and Pexels are implemented. Pixabay and Wikimedia Commons are
+open contribution opportunities — see
+[Good First Issues](docs/contributing/good-first-issues.md). See
+[Image Source Adapters](docs/adapters/image-sources.md).
+
+**CMS placement:** WordPress (production-tested), Ghost and Strapi (reference
+implementations, real but with documented limitations). See
+[CMS Adapters](docs/adapters/cms-adapters.md).
+
+Every adapter degrades gracefully when unconfigured — a missing API key
+produces an empty result, not a crash, so a partially configured profile
+still runs. Writing a new adapter means implementing one method
+(`search_candidates` or `place`) against a documented `Protocol`; see the
+[Adapter Overview](docs/adapters/overview.md).
+
+## Multi-Language by Design
+
+Pictovap's own code, comments, and documentation are English. What it
+*generates* — alt text, captions, titles — is not tied to any one language.
+Article language is detected automatically (or set explicitly via the
+publisher profile), and generated metadata follows it: a Turkish article
+gets Turkish alt text, a French one gets French, and so on. This isn't a
+localization afterthought bolted onto an English-only tool; it's a parameter
+of the pipeline from the start.
+
+## Current Status and Limitations
+
+Pictovap is early open-source infrastructure. It has a genuinely
+credential-free local demo, documented core primitives, a real test suite,
+and a working adapter model — it does not yet claim broad ecosystem adoption
+or a large external contributor base.
+
+Specifically:
+
+- Only the WordPress CMS adapter is production-hardened; Ghost and Strapi are
+  real, tested reference implementations with documented gaps (see
+  [CMS Adapters](docs/adapters/cms-adapters.md)).
+- The credential-free demo always uses deterministic mock candidates by
+  design, regardless of what's configured in `.env` — `pictovap plan` is
+  where real, credentialed sources are used.
+- Deterministic structural extraction (the rule-based, non-AI language and
+  section detection) is reliable for English and Turkish; other languages
+  are untested.
+
+## Compatibility Note
+
+Product name: Pictovap. The Python package, import name, and console-script
+entry point may remain `pictova` for backward compatibility — see
+[Brand & Naming](docs/architecture/naming.md).
+
+## Contributing
+
+See the [Documentation Portal](docs/README.md) for architecture, concepts,
+and adapter-writing guides, and [DEVELOPER.md](docs/DEVELOPER.md) for the
+contribution workflow. Pull requests that add a new image source or CMS
+adapter, improve test coverage, or fix documentation are all welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pictovap-0.2.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pictovap"
+version = "0.2.1"
+description = "Open-source visual finishing engine for content publishers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Pictovap Contributors", email = "hello@yoldaolmak.com"}
+]
+keywords = [
+    "wordpress", "image automation", "llm", "vision", "seo", "cms", "unsplash"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "Pillow>=9.0.0",
+    "requests>=2.25.0",
+    "numpy>=1.20.0",
+]
+
+[project.optional-dependencies]
+providers = [
+    "anthropic>=0.3.0",
+]
+test = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yoldaolmak/Pictovap"
+Documentation = "https://github.com/yoldaolmak/Pictovap/blob/main/docs/README.md"
+Repository = "https://github.com/yoldaolmak/Pictovap.git"
+
+[project.scripts]
+pictova = "pictova.app.cli:main"
+pictovap = "pictova.app.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = false
+
+[tool.setuptools.package-data]
+"pictova.data" = ["*.md"]

pictovap-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pictovap-0.2.1/src/pictova/__init__.py

@@ -0,0 +1,39 @@
+"""
+Pictovap — Open-source visual finishing engine for content publishers.
+
+This package provides modules to select, process, generate metadata for, and
+publish images across various CMS platforms.
+"""
+
+__version__ = "0.2.0"
+
+# Public library API — the framework entry point.
+from .demo import create_visual_plan
+
+# Adapter contracts
+from .core.adapters import ImageSourceAdapter, CMSAdapter, ReportRenderer
+
+# Vision template system
+from .vision_templates import (
+    VisionTemplate,
+    TRAVEL_BLOG,
+    TECHNICAL,
+    MINIMAL,
+    ECOMMERCE,
+    get_template,
+    register_template,
+)
+
+__all__ = [
+    "create_visual_plan",
+    "ImageSourceAdapter",
+    "CMSAdapter",
+    "ReportRenderer",
+    "VisionTemplate",
+    "TRAVEL_BLOG",
+    "TECHNICAL",
+    "MINIMAL",
+    "ECOMMERCE",
+    "get_template",
+    "register_template",
+]

pictovap-0.2.1/src/pictova/app/__init__.py

@@ -0,0 +1 @@
+"""Application surface for VIL."""

pictovap-0.2.1/src/pictova/app/cli.py

@@ -0,0 +1,81 @@
+"""Pictovap CLI entrypoint.
+
+Three commands, matching the public library API 1:1:
+    demo    - run the credential-free example pipeline
+    plan    - create a visual plan for a real article (pictova.create_visual_plan)
+    report  - render an existing JSON plan as a Markdown editor report
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict
+
+from pictova.demo import create_visual_plan, generate_report_from_file, run_demo
+
+
+def _print_json(payload: Dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pictovap")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("demo", help="Run the built-in credential-free example")
+
+    plan = sub.add_parser("plan", help="Create a visual plan for a Markdown article")
+    plan.add_argument("--article", required=True, help="Path to a Markdown article")
+    plan.add_argument("--profile", help="Path to a Publisher Profile YAML")
+    plan.add_argument("--output", help="Path to write the JSON output plan")
+    plan.add_argument("--report", help="Path to write the Markdown report")
+
+    report = sub.add_parser("report", help="Generate an editor-readable Markdown report from a plan")
+    report.add_argument("--plan", required=True, help="Path to visual-plan.json")
+    report.add_argument("--output", required=True, help="Path to write the output report.md")
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "demo":
+        run_demo()
+        return 0
+
+    if args.command == "plan":
+        try:
+            plan_output = create_visual_plan(
+                article=args.article,
+                profile=args.profile,
+                output=args.output,
+                report=args.report,
+            )
+        except FileNotFoundError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 1
+        except Exception as e:
+            print(f"Error running plan: {e}", file=sys.stderr)
+            return 1
+        if not args.output:
+            _print_json(plan_output)
+        return 0
+
+    if args.command == "report":
+        try:
+            generate_report_from_file(args.plan, args.output)
+            return 0
+        except Exception as e:
+            print(f"Error generating report: {e}", file=sys.stderr)
+            return 1
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pictovap-0.2.1/src/pictova/core/adapters.py

@@ -0,0 +1,76 @@
+"""
+Formal adapter contracts for Pictovap.
+
+Pictovap's core pipeline (Visual Brief -> Fit Score -> Provenance Pack ->
+CMS Placement) has no dependency on any specific image provider or CMS.
+Everything external plugs in through one of the protocols defined here.
+
+These are `typing.Protocol` classes: an adapter does not need to inherit
+from them, it only needs to implement the matching methods (structural
+typing / duck typing). They exist so that:
+
+  - the required shape of an adapter is documented in one importable place
+  - `isinstance(obj, ImageSourceAdapter)` works for runtime checks
+  - IDEs and type checkers can validate third-party adapters
+
+See docs/adapters/overview.md for the conceptual model, and
+docs/contributing/adapters.md for a walkthrough of writing a new one.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Protocol, runtime_checkable
+
+from pictova.core.primitives import CMSPlacement
+
+
+@runtime_checkable
+class ImageSourceAdapter(Protocol):
+    """Supplies candidate images to the Fit Score stage.
+
+    Implementations may call a local folder, a stock photo API, a DAM, or
+    any other source. They must never require credentials to import or
+    construct — missing credentials should surface as an empty result or
+    a clear error only when a search is actually attempted, so the
+    credential-free demo path keeps working.
+    """
+
+    def search_candidates(self, query: str, count: int) -> List[Dict[str, Any]]:
+        """Return up to `count` candidate images matching `query`.
+
+        Each candidate dict must contain at least:
+            id, filename, provider, source_type ("local" | "api" | "url"),
+            local_path (str | None), source_url (str | None), license,
+            attribution (str | None), keywords (list[str]), width, height
+        """
+        ...
+
+
+@runtime_checkable
+class CMSAdapter(Protocol):
+    """Consumes a CMS Placement plan and executes it against a real CMS.
+
+    A CMS adapter translates Pictovap's CMS-agnostic placement plan into
+    the target platform's native representation (e.g. a WordPress
+    Gutenberg block, a Ghost mobiledoc card, a Strapi component).
+    """
+
+    def place(self, placement: CMSPlacement) -> Dict[str, Any]:
+        """Execute the placement plan. Returns a dict with at least:
+            placed (list), failed (list), warnings (list)
+        """
+        ...
+
+
+@runtime_checkable
+class ReportRenderer(Protocol):
+    """Renders a visual plan (JSON-shaped dict) into a human- or
+    machine-facing output format (Markdown, HTML, a CMS payload, etc.).
+    """
+
+    def render(self, plan: Dict[str, Any]) -> str:
+        """Return the rendered report as a string."""
+        ...
+
+
+__all__ = ["ImageSourceAdapter", "CMSAdapter", "ReportRenderer"]