টেক্সট সহজ অংশ: এআই-লিখিত আর্টিকেলে ছবি বসানোর পাইপলাইন

আপনি একজন ডেভেলপার, যার সামনে একটি কনটেন্ট টার্গেট আছে: মাসে কয়েক ডজন আর্টিকেল, হয়তো কয়েকশোও। লেখা-মডেল ড্রাফট, আউটলাইন, মেটা ডেসক্রিপশন, ইন্টারনাল লিংক সামলায়। তারপর পাইপলাইনটি এমন এক ধাপে থমকে যায় যার নিজস্ব কোনো মডেল নেই — ছবি — এবং থেমে যায়। এটা এই কারণে নয় যে ছবি পাওয়া কঠিন, বরং এই কারণে যে স্ট্যাকের কোনো অংশ জানে না কোন ছবি, কোথা থেকে, কোন লাইসেন্সে, কীভাবে বর্ণিত।

এই আর্টিকেলটি সেই হারিয়ে যাওয়া ধাপ, শুরু থেকে শেষ পর্যন্ত সংযুক্ত: কোন ধরনের সেকশনের জন্য কোন ধরনের ভিজ্যুয়াল তৈরি করতে হবে, যে প্রম্পট একটি সম্পূর্ণ ড্রাফটকে সার্চ ব্রিফে রূপান্তরিত করে, যে API কল ছবি ফিরিয়ে দেয়, দ্বিতীয় মডেল যা একটি ফটোগ্রাফ যা বলতে পারে না তা আঁকে, এবং অ্যাসেম্বলার যা এমন মার্কআপ তৈরি করে যা Google আসলে পড়তে পারে। শেষে আছে দুটি সম্পূর্ণ ওয়ার্কফ্লো, চুরি করার জন্য তৈরি।

টেক্সট সমাধান হয়ে গেছে। ইলাস্ট্রেশনেই আটকায়।

একটি স্বয়ংক্রিয় আর্টিকেল পাইপলাইনের সৎ অডিট করুন। আউটলাইন: সমাধান হয়ে গেছে। ড্রাফট: সমাধান হয়ে গেছে। টাইটেল, মেটা ডেসক্রিপশন, স্কিমা, ইন্টারনাল লিংক, অনুবাদ: সবই সমাধান হয়ে গেছে, একই মডেল দিয়ে, সবই টেক্সটে। তারপর:

প্রতিটি কলাম দেখতে টেবিলটি পাশে সরান →

এই ব্যর্থতা নান্দনিক নয়, এটা কাঠামোগত: আর্টিকেলটি একটি স্টক প্লেসহোল্ডার নিয়ে প্রকাশিত হয়, বা গত বারো বারের মতো একই ছবি নিয়ে, বা এমন একটি জেনারেটেড ইমেজ নিয়ে যার ছয়-আঙুলের হাত পাঠকের চোখে প্রথমেই পড়বে। এবং ছবি সাজানোর জিনিস নয় — Google-এর নিজস্ব ইমেজ ডকুমেন্টেশন সরল ভাষায় বলে: alt টেক্সট “একটি ইমেজের জন্য মেটাডেটা প্রদান করার সবচেয়ে গুরুত্বপূর্ণ অ্যাট্রিবিউট”, এবং নির্দেশনা হল CSS ব্যাকগ্রাউন্ডের বদলে বর্ণনামূলক alt-সহ বাস্তব <img> এলিমেন্ট ব্যবহার করা, যাতে ছবিটি খুঁজে পাওয়া এবং বোঝা যায়।1

চার ধরনের ভিজ্যুয়াল, চার ধরনের মডেল

সবচেয়ে বড় ডিজাইন ভুল হল “ছবি”-কে একটি সমস্যা ভাবা, যার একটাই প্রোভাইডার আছে। আসলে এটা চারটি সমস্যা, এবং এদের মধ্যে রাউটার হল প্রম্পটের একটি লাইন, কোনো সার্ভিস নয়:

প্রতিটি কলাম দেখতে টেবিলটি পাশে সরান →

পাইপলাইন, শুরু থেকে শেষ

পাঁচটি ধাপ। কেবল ধাপ ৩ কোনো ইমেজ API স্পর্শ করে, এবং কেবল ধাপ ৪ অপশনাল:

┌─ 1. WRITE ────────────────────────────────────────────────────┐
   topic ──▶ LLM ──▶ draft.md  (h2 sections, front-matter)
└───────────────────────────────┬───────────────────────────────┘
┌─ 2. BRIEF ────────────────────┴───────────────────────────────┐
   draft.md ──▶ LLM ──▶ { hero: {...}, sections: [ {...} ] }
                     one JSON object: per slot, a kind +
                     either a camera brief or a data/diagram spec
└──────────┬──────────────────────────────────┬─────────────────┘
           │ kind = "photo"                │ kind = "chart" | "diagram"
           ▼                               ▼
┌─ 3. SEARCH ───────────────┐   ┌─ 4. DRAW (optional) ─────────┐
   GET /search/photos          LLM ──▶ mermaid | plotting code
   ← credited photo +           ──▶ sandbox ──▶ .svg / .png
     w/h, blur_hash, alt,       (deterministic render, no
     licence, source URL         invented numbers)
└──────────┬────────────────┘   └──────────────┬───────────────┘
           └───────────────┬──────────────────┘
┌─ 5. ASSEMBLE ─────────────┴───────────────────────────────────┐
   <img> with width/height + fetchpriority | loading
   alt written for a human · visible credit · ImageObject JSON-LD
   photo_id stored so no two pages share a hero
└───────────────────────────────────────────────────────────────┘

ডায়াগ্রামের তুলনায় দুটি বৈশিষ্ট্য বেশি গুরুত্বপূর্ণ। ধাপ ২ একটি রাউটার: এটি প্রতিটি স্লটের জন্য সিদ্ধান্ত নেয় কোন প্রোডিউসার চলবে, তাই আপনি কখনোই একটি ফটো লাইব্রেরিকে বার চার্ট চাইবেন না। এবং ধাপ ৫ হল সেই জায়গা যেখানে SEO বসবাস করে — ইমেজ সম্পর্কে Google যা কিছু নথিভুক্ত করে (বর্ণনামূলক alt, লাইসেন্স মেটাডেটা, একটি LCP-নিরাপদ হিরো) সবই এখানে ইমিট করা হয়, সার্চ রেসপন্স ইতিমধ্যে বহন করা ফিল্ড থেকে।

ধাপ ২: ড্রাফটকে ভিজ্যুয়াল ব্রিফে পরিণত করা

সম্পূর্ণ খসড়ার উপর একটি মাত্র মডেল কল, এবং এর ফলাফল একটা প্ল্যান, কোনো কোয়েরি নয়। একটি একক ফটো ব্রিফ কীভাবে লিখতে হয় — কেন আর্টিকেলের শিরোনাম সবচেয়ে খারাপ ইনপুট, ১২-থেকে-২৫-শব্দের ক্যামেরা ব্রিফ দেখতে কেমন, এবং এটা কোন কোন ভাবে ব্যর্থ হয় — তা সম্পূর্ণভাবে একটি আর্টিকেল ইলাস্ট্রেট করার গাইডে বলা আছে, এখানে তা পুনরাবৃত্তি করা হয়নি। একটা পাইপলাইন যা যোগ করে তা হলো রাউটিং: একই কলকে স্লট-বাই-স্লট ঠিক করতে হয় কোন প্রোডিউসার চলবে — এবং একটা চার্ট এন্ট্রি ডেটা বহন করে যেখানে একটা ফটো এন্ট্রি বহন করে একটা দৃশ্য।

# system prompt — run once per finished draft
You are the art director of a technical publication. Read the article and
return the visual plan: one entry for the hero, one per H2 section.

For each entry choose exactly one kind:
  "photo"    a real scene: someone doing something somewhere, a place,
              an object, a gesture. The default for heroes.
  "chart"    the section states numbers that are IN the article. Never
              invent values: copy them into data, verbatim.
  "diagram"  the section describes a structure, a flow or a sequence.
  "none"     the section is short, or already carries a code block.

Rules for "photo" entries — the field is query:
   একটি ক্যামেরা ব্রিফ লিখুন: এমন একটি দৃশ্য যা ক্যামেরায় ধারণ করা যেত, ১২ থেকে ২৫ শব্দে,
   ইংরেজিতে, বিভাগের মেজাজের সাথে মিলিয়ে। ফ্রেমে কী আছে তার নাম বলুন,
   বিষয়বস্তুর নাম নয়। কোনো লেখা, লোগো, ব্র্যান্ড বা বিখ্যাত ব্যক্তি নয়; কোনো অদৃশ্য
   রূপক নয়। (সম্পূর্ণ নিয়মাবলী, উদাহরণ ও ব্যর্থতার ক্ষেত্রসহ:
   pexafy.com/blog/illustrate-blog-articles-at-scale/)

Do NOT write the alt text of a photo entry: the picture you get back is the
closest match to the brief, not the scene you described, so its alt has to be
written from the chosen photo. Chart and diagram entries DO carry an alt —
there you control exactly what is rendered.

Return JSON only:
{
  "hero": { "kind": "photo", "query": "…", "orientation": "landscape" },
  "sections": [
    { "h2": "…", "kind": "photo",   "query": "…" },
    { "h2": "…", "kind": "chart",   "title": "…", "unit": "ms",
      "data": [ {"label": "…", "value": 0} ], "alt": "…" },
    { "h2": "…", "kind": "diagram", "spec": "flowchart LR; …", "alt": "…" }
  ]
}

kind লাইনটিই বেশিরভাগ কাজ করে, আর data নির্দেশনা বাকিটা করে: একটা চার্ট এন্ট্রি শুধু সেই সংখ্যাগুলোই বহন করতে পারে যা খসড়ায় ইতিমধ্যে আছে, ফলে মডেল উদ্ভাবন না করে প্রতিলিপি করে। এখানে একটা ডেভেলপার আর্টিকেলের তিনটি বাস্তব সেকশনে রাউটারটি দেখানো হলো:

প্রতিটি কলাম দেখতে টেবিলটি পাশে সরান →

ধাপ ৩: ছবিগুলো ক্রেডিটসহ ফিরে আসে

প্রতিটি kind: "photo" এন্ট্রি একটি রিকোয়েস্ট। উপরের হিরো ব্রিফটি, পাবলিক API-এর বিরুদ্ধে চালিয়ে, ১৪৭ ms-এ এটি ফিরিয়ে দেয়:

GET /search/photos — হিরো ব্রিফ · “একজন ডেভেলপার রাতে একটি ডেস্কে কাজ করছে দুটি মনিটর নিয়ে…” · ১৪৭ ms

নির্বাচিত হিরোUnsplash Unsplash Pexels

সর্বশেষ সেকশন ব্রিফ, একটি সম্পূর্ণ আলাদা দৃশ্য, ১৪৪ ms-এ:

GET /search/photos — সেকশন ব্রিফ · “দুইজন ইঞ্জিনিয়ার একটি হোয়াইটবোর্ডের সামনে দাঁড়িয়ে ডায়াগ্রামে ঢাকা…” · ১৪৪ ms

শীর্ষ ফলাফল · ০.৯১Pexels Unsplash Unsplash

প্রতিটি ছবির সাথে যা ফিরে আসে তা হল সেই অংশ যা ধাপ ৫-কে সম্ভব করে তোলে — কেবল একটি ফাইল নয়:

{
  "photo_id":  "019e1c7f-0063-759e-b498-33ce1714e6c9",   // store it: no repeats
  "urls": { "small": "…?w=400", "regular": "…?w=1080",
             "large": "…?w=1920" },
  "width": 3000, "height": 1688,          // → no layout shift
  "blur_hash": "LJ8gjv9rVq-6OFxanNNFI7xco$Na",   // → real placeholder
  "alt_description": "Person types on keyboard in front of dual monitors…",
  "photographer_full_name": "Jakub Żerdzicki",   // → ImageObject.creator
  "source": "Unsplash", "license_type": "free",
  "source_image_url": "https://unsplash.com/photos/…",
  "attribution": { "html": "<span…>Photo by …</span>",
                    "plain": "Photo by Jakub Żerdzicki on Unsplash (…)" }
}

ধাপ ৪: যা একটি ফটোগ্রাফ বলতে পারে না

পরিকল্পনার দুটি স্লট সার্চযোগ্য নয়, এবং এটাই সেই জায়গা যেখানে একটি দ্বিতীয় মডেল তার স্থান অর্জন করে — একটি ছবি আঁকার জন্য নয়, বরং এমন কোড লেখার জন্য যা তা আঁকে। এই পার্থক্যটি গুরুত্বপূর্ণ: কোড রিভিউযোগ্য, ডিটারমিনিস্টিক, এবং একটি বার-এর উচ্চতা নিয়ে হ্যালুসিনেট করতে পারে না।

ডায়াগ্রাম: টেক্সট ইন, SVG আউট

Mermaid একটি প্লেইন-টেক্সট সংজ্ঞা থেকে ডায়াগ্রাম রেন্ডার করে,3 যা এটিকে একটি মডেলের জন্য সবচেয়ে নিরাপদ টার্গেট করে তোলে: আউটপুটটি পরীক্ষাযোগ্য, git-এ ডিফযোগ্য, এবং প্রতিবারই একই ভাবে রেন্ডার হয়। রাউটার ইতিমধ্যে স্পেকটি ফিরিয়েছে।

# the "spec" field of a diagram entry, written to build/graph.mmd
cat build/graph.mmd
flowchart LR
  install["install deps · 480s"] --> compile["compile · 1080s"]
  compile --> test["test suite · 720s"]
  compile --> upload["upload artifacts · 120s"]

npx -y @mermaid-js/mermaid-cli -i build/graph.mmd -o static/img/graph.svg
# → an SVG you can review in the PR, not a picture you have to trust

চার্ট: কেবল সেই সংখ্যাগুলো যা আর্টিকেলে আগে থেকেই আছে

একই নীতি, একটি বাড়তি সতর্কতা। রাউটার ড্রাফট থেকে মানগুলো কপি করেছে; মডেল প্লটিং কোড লেখে; কোড একটি স্যান্ডবক্সে চলে; অ্যাসেম্বলার চার্ট কোনো পেজের কাছে যাওয়ার আগে রেন্ডার করা মানগুলো উৎস সংখ্যার বিরুদ্ধে পুনরায় যাচাই করে।

import re, matplotlib
matplotlib.use("Agg")                # headless: no display in CI
import matplotlib.pyplot as plt

def assert_in_draft(value, draft: str) -> None:
    """A plotted number must appear in the article AS A NUMBER."""
    # Substring matching is the trap here: "120" is inside "1200", and
    # inside "?w=1200" — a naive `str(v) in draft` passes on anything.
    # Match on word boundaries, and accept 1 234 / 1,234 / 1234.
    body = re.sub(r"(?<=\d)[  ,](?=\d{3}\b)", "", draft)   # strip separators
    if not re.search(rf"(?<![\d.]){re.escape(str(value))}(?![\d.])", body):
        raise ValueError(f"{value} is not stated in the article — refusing to plot")

def render_chart(entry: dict, draft: str, out: str) -> str:
    labels = [d["label"] for d in entry["data"]]
    values = [d["value"] for d in entry["data"]]
    for v in values:
        assert_in_draft(v, draft)       # hallucinated value → no chart

    fig, ax = plt.subplots(figsize=(8, 4.5), dpi=160)
    ax.barh(labels, values)
    ax.set_xlabel(entry["unit"])
    ax.set_title(entry["title"])
    fig.tight_layout()
    fig.savefig(out)                    # deterministic, reviewable artefact
    return out

সতর্কতাটি ছোট, কিন্তু সেটা সাবধানে লিখুন: একটি সাবস্ট্রিং চেক কাজ করে না। "120" in draft সত্য হয়ে যায় এমন একটি আর্টিকেলের জন্য যাতে 1200 বা ?w=1200 আছে, তাই নাইভ ভার্সনটি সবকিছুর ওপর পাস করে যায় এবং কিছুই রক্ষা করে না। ডিজিট বাউন্ডারিতে অ্যাংকর করুন, হাজারের সেপারেটর নরমালাইজ করুন, এবং যে ধরনের ভুল একটি টেকনিক্যাল আর্টিকেলকে কমেন্টে টুকরো টুকরো করে দেয় — একটি চার্ট নিজের প্যারাগ্রাফের বিপরীত কথা বলছে — সেটি প্রোডাকশনে পৌঁছাতে পারে না। স্ক্রিনশটগুলো একই নীতি অনুসরণ করে: আপনার আসল বিল্ডের বিরুদ্ধে একটি স্ক্রিপ্টেড page.screenshot() হল আপনার নিজের UI-এর একমাত্র সত্যতার উৎস, এবং UI পরিবর্তন হলেও এটি সত্য থেকে যায়।

ধাপ ৫: অ্যাসেম্বলি এখানেই SEO বাস করে

এখন পর্যন্ত সবকিছু ফাইল ও ফিল্ড তৈরি করেছে। এই ধাপ সেগুলোকে মার্কআপে রূপান্তরিত করে — এবং এখানে সুনির্দিষ্ট হওয়া উপযোগী, কারণ এই কয়েকটি লাইনে তিনটি নথিভুক্ত আচরণ নির্ধারিত হয়।

<!-- The bytes come from another origin: pay the handshake early -->
<link rel="preconnect" href="https://images.unsplash.com" crossorigin>

<!-- LCP element: never lazy, always high priority -->
<figure>
  <img src="{urls.regular}"
       width="{width}" height="{height}"        <!-- kills layout shift -->
       alt="{alt}"                                <!-- written AFTER the pick -->
       fetchpriority="high" decoding="async"
       style="background:{color_hex}">   <!-- dominant colour, 1 field -->
  <figcaption>{attribution.html}</figcaption>
</figure>

<!-- Section images, below the fold: the opposite settings -->
<img src="{urls.regular}" width="{width}" height="{height}"
     alt="{alt}" loading="lazy" decoding="async">

1. হিরোকে কখনো লেজি-লোড করবেন না। web.dev স্পষ্ট: “আপনার LCP ইমেজ কখনো লেজি-লোড করবেন না, কারণ তা সর্বদা অপ্রয়োজনীয় রিসোর্স লোড ডিলে সৃষ্টি করবে, এবং LCP-তে নেতিবাচক প্রভাব ফেলবে”, এবং এটি প্রস্তাব করে যে যে এলিমেন্ট সম্ভবত LCP এলিমেন্ট হবে তার ওপর fetchpriority="high" ব্যবহার করুন — সংযতভাবে, একটি ছবিতে।4 এমন একটি পাইপলাইন যা প্রতিটি ছবিতে loading="lazy" স্ট্যাম্প করে, হিরো-সহ, তা স্বয়ংক্রিয় প্রকাশনায় সবচেয়ে সাধারণ স্ব-আরোপিত Core Web Vitals ক্ষত।
2. সব সময় width ও height ইমিট করুন — এগুলো রেসপন্সে ফিরে আসে, তাই কোনো অজুহাত নেই; সেই একক অ্যাট্রিবিউট জোড়াটিই ব্রাউজারকে জায়গা রিজার্ভ করতে দেয় এবং লেআউট জাম্প করা বন্ধ করে। ফাইল লোড হওয়ার সময় প্লেসহোল্ডার হিসেবে blur_hash ব্যবহার করুন।
3. নির্বাচনের পরে alt লিখুন, কখনো আগে না। এটা সূক্ষ্ম বিষয়। পরিকল্পনার alt ফিল্ড সেই দৃশ্যটি বর্ণনা করে যা আপনি চেয়েছিলেন; আপনি যে ছবিটি পেয়েছেন সেটি সবচেয়ে কাছের মিল, সেই দৃশ্য নয়। ব্রিফের টেক্সট alt হিসেবে পাঠানোই ঠিক সেই অ্যাক্সেসিবিলিটি ব্যর্থতা যা এই পাইপলাইনটির এড়ানো উচিত — এমন একটি ছবির বর্ণনা যা পেজে নেই। নির্বাচিত ছবির alt_description থেকে alt তৈরি করুন, যে প্যারাগ্রাফে এটি বসেছে তার বিরুদ্ধে পরিমার্জিত করুন। Google-এর নির্দেশনা হল “উপযোগী, তথ্যে পূর্ণ কনটেন্ট তৈরির ওপর ফোকাস করুন যা কিওয়ার্ড উপযুক্তভাবে ব্যবহার করে এবং পেজের কনটেন্টের প্রসঙ্গের সাথে থাকে”, এবং এটি সতর্ক করে দেয় যে alt অ্যাট্রিবিউটে কিওয়ার্ড ঠেসে দেওয়ার ফলে “একটি নেতিবাচক ব্যবহারকারী অভিজ্ঞতা তৈরি হয় এবং আপনার সাইটকে স্প্যাম হিসেবে দেখা হতে পারে”।1

যে অংশ প্রায় কেউ স্বয়ংক্রিয় করে না: লাইসেন্স মেটাডেটা

Google ইমেজ লাইসেন্সিংয়ের জন্য ImageObject স্ট্রাকচার্ড ডেটা সমর্থন করে। এর জন্য contentUrl প্রয়োজন এবং সাথে creator, creditText, copyrightNotice বা license-এর অন্তত একটি, এটি acquireLicensePage প্রস্তাব করে, এবং লাইসেন্স তথ্য থাকা ছবিগুলো Google Images-এ Licensable ব্যাজের জন্য যোগ্য হতে পারে।5 এই ফিল্ডগুলোর প্রতিটিই সার্চ রেসপন্সে ইতিমধ্যে আছে — তাই সেগুলো ইমিট করা একটি টেম্প্লেট, প্রজেক্ট নয়:

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "ImageObject",
  "contentUrl": "{urls.large}",                 // required
  "creator": { "@type": "Person",
                "name": "{photographer_full_name}" },
  "creditText": "{photographer_full_name} on {source}",
  "license": "{LICENSE_URL[source]}",           // the library's own page
  "acquireLicensePage": "{source_image_url}"     // the photo's page
}
</script>

# LICENSE_URL maps the `source` field to the licence that actually governs
# the photo — unsplash.com/license, pexels.com/license, pixabay.com/…

একটি বিস্তারিত বিষয় যা সঠিকভাবে করা জরুরি: license-এর সেই লাইসেন্সের দিকেই নির্দেশ করা উচিত যা সেই ছবিকে নিয়ন্ত্রণ করে — উৎস লাইব্রেরির নিজস্ব লাইসেন্স পেজ — আপনার ডোমেনের কোনো সারাংশ পেজ নয়। Google এটি পড়ে ব্যাজ যোগ্যতা নির্ধারণ করে, এবং একটি সেল্ফ-রেফারেন্সিয়াল URL একটি সংকেত হিসেবে দুর্বল, এবং নিজের কাছে ফিরে আসা লিংক ছাড়া অন্য কিছু হিসেবে রক্ষা করা কঠিন। পাঠকদের জন্য আপনার নিজের লাইসেন্স সারাংশ একটি ইন্টারনাল পেজ হিসেবে রাখুন; মার্কআপে ক্যানোনিকালটি রাখুন।

আর যখন আপনি অ্যাসেম্বলারে আছেন: ফাইলটিকে IMG_0042.jpg-এর চেয়ে একটি ছোট বর্ণনামূলক নাম দিন, এবং ছবিটি একটি সাইটম্যাপে যোগ করুন — Google-এর ইমেজ সাইটম্যাপ ফরম্যাট প্রতি পেজ URL-এ ১,০০০টি পর্যন্ত ছবি গ্রহণ করে।6 দুটোই একটি পাইপলাইনে এক লাইন এবং কোনোটাই হাতে করা হয় না।

চুরি করার জন্য দুটি পাইপলাইন

একই পাঁচটি ধাপ, দুটি সম্পূর্ণ আলাদা গঠন — একটি আপনি লেখা আর্টিকেলের জন্য, একটি একটি চলমান প্রোডাক্টের সাথে মিলতে হবে এমন ডকুমেন্টেশনের জন্য। যেটার ব্যর্থতার ধরন আপনি চিনতে পারেন সেটা বেছে নিন।

১ · CI-তে ডেভ ব্লগ — রেপোতে Markdown

আর্টিকেলগুলো Markdown হিসেবে থাকে, ছবিগুলো তাদের পাশে কমিট করা থাকে, এবং পুরো ব্যাপারটি পুশে চলে। ডিটারমিনিস্টিক, PR-এ রিভিউযোগ্য, কোনো API-এর ওপর রানটাইম ডিপেন্ডেন্সি নেই:

on: { pull_request: { paths: ["content/**.md"] } }

jobs:
  illustrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: python plan_to_pr.py $(git diff --name-only origin/main -- 'content/*.md')
        env:
          PEXAFY_API_KEY: ${{ secrets.PEXAFY_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: peter-evans/create-pull-request@v6   # images land in the PR
        with: { commit-message: "chore(content): illustrate" }

একজন মানুষ এখনও PR অনুমোদন করে, যেটাই এখানকার মূল বিষয়: পাইপলাইন প্রস্তাব করে, রিভিউয়ার সিদ্ধান্ত নেয়, এবং এটি যে ফ্রন্ট-ম্যাটার লিখেছে তা ডিফযোগ্য।

সার্চের অর্ধেকটা একটাই GET — রিকোয়েস্ট, এর score_threshold এবং এটি যেসব ফিল্ড ফেরত দেয় তা লাইন ধরে ধরে একক-আর্টিকেল গাইডে লেখা আছে, তাই এখানে তা পুনর্মুদ্রণের বদলে ইমপোর্ট করা হয়েছে। এই ফাইলটি যা যোগ করে তা হলো একটা প্ল্যান-এর জন্য প্রয়োজনীয় সবকিছু, যা একটা মাত্র ফটোর জন্য দরকার হয় না: এমন একটা ব্রিফের জন্য রিট্রাই যা কিছুই ফেরত দেয়নি, একটা photo_id-এর উপর দাবি যাতে দুটো পেজ একই ছবি শেয়ার না করে, এবং ফিরে আসা ফটো থেকে লেখা alt।

import frontmatter
from photo_search import search   # একটাই GET /search/photos; `used`-এ থাকা id বাদ দেয়

def find_photo(entry: dict, used: set) -> dict | None:
    """Search; if the brief was too specific, widen it once, then give up."""
    orientation = entry.get("orientation", "landscape")
    for query in (entry["query"], widen(entry["query"])):
        photo = search(query, orientation, used)
        if photo:
            used.add(photo["photo_id"])   # claim it: no repeats site-wide
            return photo
    return None                        # caller decides: skip the slot, or fail

def widen(query: str) -> str:
    """Drop the last clause — usually the over-specific one."""
    return query.rsplit(" in ", 1)[0] if " in " in query else query

def illustrate(path: str, plan: dict, used: set) -> None:
    post = frontmatter.load(path)
    hero = find_photo(plan["hero"], used)
    if hero is None:                    # no hero is better than a bad one
        raise SystemExit(f"{path}: no photo above threshold — rewrite the brief")

    post["hero"] = {                    # everything the template needs
        "src": hero["urls"]["regular"], "w": hero["width"], "h": hero["height"],
        # The alt describes the photo we GOT, never the scene we asked for.
        "alt": alt_for(hero, section=post.get("title", "")),
        "bg": hero["color_hex"], "credit": hero["attribution"]["html"],
        "creator": hero["photographer_full_name"], "id": hero["photo_id"],
        "source": hero["source"],
        "source_url": hero["source_image_url"],   # → acquireLicensePage
    }
    open(path, "w").write(frontmatter.dumps(post))

def alt_for(photo: dict, section: str) -> str:
    """alt_description as the base, trimmed to ~125 chars for screen readers.
    Send it back through the model with the paragraph if you want better."""
    base = photo.get("alt_description") or photo.get("description", "")
    return base[:125].rstrip(" ,;")

২ · ডকস ও চেঞ্জলগ — প্রথমে স্ক্রিনশট, শেষে ছবি

রাউটারের ডিফল্টগুলো উল্টে দিন। প্রোডাক্ট ডকুমেন্টেশনে সৎ ভিজ্যুয়াল প্রায় সবসময়ই আপনার নিজের UI: একটি Playwright স্ক্রিপ্ট যা আসল বিল্ড খোলে, একটি স্থির ভিউপোর্ট সেট করে এবং প্যারাগ্রাফটি ঠিক যে অবস্থা বর্ণনা করে সেটাই ক্যাপচার করে। ডায়াগ্রামগুলো আর্কিটেকচার পেজগুলো কভার করে, এবং ফটোগ্রাফ কেবল কনসেপচুয়াল ও ল্যান্ডিং পেজগুলোতে দেখা যায় — যেখানে একটি স্ক্রিনশট কিছুই বলবে না।

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page(viewport={"width": 1440, "height": 900},
                            device_scale_factor=2)   # retina-crisp
    page.goto("http://localhost:3000/dashboard")
    page.get_by_role("button", name="New API key").click()
    page.screenshot(path="static/img/docs/new-api-key.png")
    browser.close()
# Runs in the same CI job as the docs build → the screenshot can never
# describe a version of the UI that no longer exists.

দুটি ভ্যারিয়েন্ট উল্লেখ করা উপযোগী, যদিও তাদের নিজস্ব রেসিপি লাগে না। প্রোগ্রামেটিক SEO লুপটি উল্টে দেয়: একটি ডেটাবেস থেকে তৈরি শত শত পেজের সাথে আপনি প্রতি পেজে সার্চ করেন না — একটি রিকোয়েস্ট পর্যন্ত ১০০টি ছবি ফিরিয়ে দেয়, তাই আপনি প্রতি টপিক ক্লাস্টারে সার্চ করেন এবং একটি পুল থেকে বরাদ্দ করেন, যেখানে একটি ইউনিকনেস কনস্ট্রেইন্ট ডিডুপ্লিকেশন করে (সম্পূর্ণ আর্কিটেকচারটি)। এবং নিউজলেটার ও সোশ্যাল কার্ডে একই ছবি চারটি ক্রপে প্রয়োজন হয়: photo_id রেখে দিন, urls থেকে আপনার প্রয়োজনীয় সাইজ চান, এবং যখন একটি ক্রপ আসলেই ব্যর্থ হয় তখনই আবার সার্চ করুন।

একই পাইপলাইন, একটি এজেন্ট হিসেবে

যদি একটা মডেল ইতিমধ্যে খসড়া লিখছে, তাহলে সবচেয়ে ছোট পথ হলো প্রসেসের মধ্যে JSON আদান-প্রদান না করে সরাসরি এটিকে সার্চ টুল দিয়ে দেওয়া। Pexafy mcp.pexafy.com/mcp-এ একটি হোস্টেড Model Context Protocol সার্ভার চালায়। কানেক্টর সেটআপ এবং এটি যেসব টুল দেয়, তা অন্যত্র আলোচনা করা হয়েছে — ডেস্কটপ ও এডিটর সেটআপ একক-আর্টিকেল গাইডে, CI রানারের জন্য হেডলেস ভ্যারিয়েন্ট স্কেলে কনটেন্ট নিয়ে আর্টিকেলে, এবং বৃহত্তর কানেক্টর মার্কেট দেখতে কেমন — কে কী শর্তে MCP ইমেজ সার্ভার সরবরাহ করে — তা AI এজেন্টদের জন্য ইমেজ সার্চ ইনফ্রাস্ট্রাকচার নিয়ে করা স্টাডিতে আছে। এখানে দেখানোর মতো বিষয় হলো: এজেন্টের হাতে টুলগুলো এসে গেলে এই পাইপলাইনের কী হয় — এটি আর পাঁচটা ধাপ থাকে না, একটামাত্র নির্দেশনা হয়ে যায়।

You  Here is the draft. Build the visual plan, illustrate it, and open a PR.
     Charts only from numbers already in the text.

Agent  → plan: hero=photo · §2=chart · §3=diagram · §4=photo
      → search_photos(q="a developer working late at a desk with two
         monitors and a mechanical keyboard in a dark room…")
      ← 16 photos · 147 ms · picked #1, 3000×1688, credited
      → mermaid-cli build/graph.mmd → static/img/graph.svg
      → chart.py §2 → 4 values checked against the draft ✓
      → search_photos(q="two engineers standing at a whiteboard…")
      ← 16 photos · 144 ms · picked #1

      ✓ 4 slots filled · 2 API calls · alt + credit + ImageObject written
      ⚠ §5 returned nothing above 0.5 — brief too abstract, rewritten as
        "a person at a kitchen table checking figures on a laptop"

শেষ লাইনটিই সেই কারণ যার জন্য এই লুপে একটি খাঁটি স্ক্রিপ্টের বদলে একটি এজেন্ট রাখার মূল্য আছে: স্বয়ংক্রিয় ইলাস্ট্রেশনের ব্যর্থতার ধরন হল একটি খারাপ ব্রিফ, এবং একটি খারাপ ব্রিফ পুনর্লিখন করাটাই ঠিক একটি ভাষা মডেলের কাজ। ডিটারমিনিস্টিক অংশগুলো — বরাদ্দকরণ, ডিডুপ্লিকেশন, নিউমেরিক গার্ড — কোডে রাখুন।

একটি ইলাস্ট্রেটেড আর্টিকেলের খরচ কত

প্রতি আর্টিকেলে তিনটি ফটো স্লট মানে তিনটি সার্চ রিকোয়েস্ট, তাই ফ্রি প্ল্যান (5,000 requests/month) কভার করে প্রতি মাসে 1,666 আর্টিকেল, তাও পেমেন্টের কোনো প্রশ্ন ওঠার আগেই — এবং যদি আপনি প্রতি আর্টিকেলে না করে প্রতি টপিক ক্লাস্টারে সার্চ পুল করেন, তাহলে এই সীমা আরও এক অর্ডার অফ ম্যাগনিটিউড এগিয়ে যায়। প্ল্যান-অনুযায়ী বিস্তারিত হিসাব, এবং যে পুলিং আর্কিটেকচার একে অপ্রয়োজনীয় করে তোলে, তা আছে স্কেলে কনটেন্ট ইলাস্ট্রেট করা নিয়ে সহচর আর্টিকেলে।

প্রতি আর্টিকেলে দুটি মডেল কল — একটি ড্রাফটের জন্য, একটি ভিজ্যুয়াল পরিকল্পনার জন্য — কয়েক হাজার টোকেন হবে এবং পাইপলাইনে সবচেয়ে সস্তা লাইন হবে; Mermaid ও matplotlib রেন্ডারের খরচ শুধু CI সেকেন্ড। যে সংখ্যাটি মানুষকে চমকে দেয় তা হল কোন লাইনটি সস্তা নয়: প্রতি আর্টিকেলে চারটি ছবি জেনারেট করা, মাসে চারশো ছবি, সাথে যে প্রচেষ্টাগুলো টেকেনি — এবং আউটপুটটি তখনও কোনো ফটোগ্রাফার, কোনো তারিখ, কোনো উৎস URL বহন করে না।

এই পাইপলাইন যা ঠিক করে না

একটি সৎ সেকশন, কারণ যে ব্যর্থতা এটি রোধ করে তা খরচবহুল। একটি ভালোভাবে ইলাস্ট্রেটেড আর্টিকেল তবুও একটি আর্টিকেল: বাস্তব ফটোগ্রাফি, নির্ভুল চার্ট এবং সঠিক মার্কআপ এমন একটি পেজকে উন্নত করে যার থাকার যোগ্যতা আছে। এগুলো পাতলা, ব্যাপক-উৎপাদিত কনটেন্টকে র‍্যাংক করাতে পারে না। Google-এর স্প্যাম পলিসি স্কেল্ড কনটেন্ট অ্যাবিউজ-এর নাম দেয় — অনেক পেজ মূলত র‍্যাংকিং ম্যানিপুলেট করতে জেনারেট করা এবং ব্যবহারকারীদের কম মূল্য দেওয়া, অটোমেশন জড়িত থাকুক বা না থাকুক — এবং ইলাস্ট্রেশনের গুণমান সেই বিচারে একটি ফ্যাক্টর নয়।7

তাই যে ফ্রেমিং টিকে থাকে সেটা হল: এই পাইপলাইনটি একটি গুণমানের ফ্লোর যা আপনি নিয়ন্ত্রণ করেন, যা এমন পেজগুলোতে প্রয়োগ করা হয় যাদের প্রকাশিত হওয়ার একটি কারণ ইতিমধ্যেই আছে। যেখানে এটি প্রমাণযোগ্যভাবে ফল দেয়:

• একটি পাঠক যাচাই করতে পারে এমন প্রোভিনেন্স। একটি আসল ফটোগ্রাফার ও একটি উৎস URL-সহ একটি ক্রেডিট লাইন এমন একটি দাবি যা যাচাই করা যায় — এবং একই ফিল্ডগুলো Google পড়া ImageObject মার্কআপে ফিড করে।
• অ্যাক্সেসিবিলিটি ও Core Web Vitals। আসল alt টেক্সট, প্রতিটি ছবিতে ডাইমেনশন, একটি হিরো যা কখনো লেজি-লোড হয় না। প্রতিটি প্রকাশিত আর্টিকেল দিয়ে গুণ করুন এবং এটাই সাইটের ইমেজ-কোয়ালিটি স্টোরি।
• যাচাইযোগ্য জায়গায় নির্ভুলতা। এমন একটি চার্ট যার সংখ্যাগুলো আর্টিকেলের বিরুদ্ধে যাচাই করা, চলমান বিল্ড থেকে জেনারেট করা একটি স্ক্রিনশট, PR-এ টেক্সট হিসেবে রিভিউযোগ্য একটি ডায়াগ্রাম — তিনটি ভিজ্যুয়াল যা সত্য থেকে বিচ্যুত হতে পারে না একটি টেস্ট ব্যর্থ না হয়ে।

অ্যাট্রিবিউশনের ক্ষেত্রে, পাইপলাইন-নির্দিষ্ট পয়েন্টটি সংকীর্ণ: সবসময় ক্রেডিট রেন্ডার করার পক্ষে যুক্তি অন্যত্র দেওয়া আছে, এবং একটা স্বয়ংক্রিয় অ্যাসেম্বলার যা যোগ করে তা হলো — যে attribution স্ট্রিং এটি প্রিন্ট করে সেটাই স্ট্রাকচার্ড ডেটার প্রয়োজনীয় creditText। একটা ফিল্ড, দুটো জায়গা, একই টেমপ্লেট পাসে নিঃসৃত — এই কারণেই একটা পাইপলাইনের এটি বাদ দেওয়ার অজুহাত একজন মানুষের চেয়েও কম থাকে।

কোথা থেকে শুরু করবেন

1. রাউটার প্রম্পট যোগ করুন যা কিছু ইতিমধ্যেই আপনার ড্রাফট লিখছে তার সাথে, এবং JSON প্রিন্ট করুন কোনো ব্যবস্থা না নিয়ে। দশটি পরিকল্পনা পড়ুন। যদি ব্রিফগুলো দৃশ্যের বদলে টপিকের নাম দেয়, তবে কোনো ইন্টিগ্রেশন লেখার আগে প্রম্পটটি ঠিক করুন।
2. কেবল ফটো স্লটগুলো সংযুক্ত করুন। প্রতি ব্রিফে একটি GET /search/photos, এবং প্রথম দিন থেকে photo_id সংরক্ষণ করুন — ৩,০০০ লাইভ পেজে পিছিয়ে গিয়ে ডিডুপ্লিকেশন বসানো একটি মাইগ্রেশন, কোনো কলাম নয়।
3. একই কমিটে width, height ও alt ইমিট করুন। এটাই সবচেয়ে সস্তা Core Web Vitals কাজ যা আপনি কখনো করবেন।
4. তারপর ধাপ ৪ যোগ করুন, চার্টের আগে ডায়াগ্রাম — Mermaid টেক্সট, তাই এটাই একমাত্র ব্যর্থতার ধরন যা সিনট্যাক্স ত্রুটির বাইরে যায় না।
5. প্রথম চার্ট একজন পাঠকের কাছে পৌঁছানোর আগে নিউমেরিক গার্ড যোগ করুন, পরে নয়।

তথ্যসূত্র ও ফুটনোট