متن آسان حصہ ہے: وہ پائپ لائن جو AI کے لکھے مضامین کو تصویروں سے آراستہ کرتی ہے

آپ ایک ڈیویلپر ہیں اور آپ کا کانٹینٹ ہدف مہینے میں درجنوں مضامین، شاید سیکڑوں ہے۔ رائٹنگ ماڈل ڈرافٹ، آؤٹ لائن، میٹا ڈسکرپشن اور اندرونی لنکس سنبھال لیتا ہے۔ پھر پائپ لائن اس ایک مرحلے پر پہنچتی ہے جس کا اپنا کوئی ماڈل نہیں ہوتا — تصاویر — اور رک جاتی ہے۔ اس کی وجہ یہ نہیں کہ تصاویر حاصل کرنا مشکل ہے، بلکہ یہ کہ اس اسٹیک میں کچھ بھی نہیں جانتا کہ کون سی تصویر، کہاں سے، کس لائسنس کے ساتھ، اور کیسے بیان کی جائے۔

یہ مضمون وہی گمشدہ مرحلہ ہے، سرے سے آخر تک منسلک: کس قسم کے سیکشن کے لیے کس قسم کا وژول تیار کیا جائے، وہ پرامپٹ جو ایک مکمل ڈرافٹ کو سرچ بریفس میں بدل دیتا ہے، وہ API کال جو تصاویر واپس لاتی ہے، وہ دوسرا ماڈل جو وہ کھینچتا ہے جو ایک تصویر نہیں کہہ سکتی، اور وہ اسمبلر جو ایسا مارک اپ نکالتا ہے جسے گوگل واقعی پڑھ سکے۔ آخر میں دو مکمل ورک فلوز، فوراً اپنانے کے لیے تیار۔

متن حل ہو گیا ہے۔ رکاوٹ تصویر پر آتی ہے۔

ایک خودکار مضمون پائپ لائن کا سچا آڈٹ کریں۔ آؤٹ لائن: حل۔ ڈرافٹ: حل۔ ٹائٹل، میٹا ڈسکرپشن، اسکیما، اندرونی لنکس، ترجمہ: سب حل، سب ایک ہی ماڈل سے، سب متن میں۔ پھر:

ٹیبل کو ہر کالم دیکھنے کے لیے سائیڈ وے سوائپ کریں →

یہ ناکامی صرف جمالیاتی نہیں، ساختی ہے: مضمون ایک اسٹاک پلیس ہولڈر کے ساتھ شائع ہوتا ہے، یا پچھلے بارہ جیسی ہی تصویر کے ساتھ، یا ایک جنریٹڈ تصویر کے ساتھ جس کا چھ انگلیوں والا ہاتھ قاری کو سب سے پہلے نظر آنے والی چیز ہو۔ اور تصویر محض سجاوٹ نہیں ہے — گوگل کی اپنی امیج دستاویزات صاف کہتی ہیں: alt متن "وہ سب سے اہم اٹریبیوٹ ہے جب تصویر کے میٹا ڈیٹا فراہم کرنے کی بات آتی ہے"، اور ہدایت یہ ہے کہ اصلی <img> ایلیمنٹس تفصیلی alt کے ساتھ استعمال کیے جائیں بجائے CSS بیک گراؤنڈز کے، تاکہ تصویر کو ڈھونڈا اور سمجھا جا سکے۔1

چار قسم کے وژولز، چار قسم کے ماڈلز

سب سے بڑی ڈیزائن غلطی "تصویر" کو ایک ہی پرووائیڈر والا ایک مسئلہ سمجھنا ہے۔ یہ چار مسائل ہیں، اور ان کے درمیان روٹر ایک سروس نہیں بلکہ پرامپٹ کی ایک لائن ہے:

ٹیبل کو ہر کالم دیکھنے کے لیے سائیڈ وے سوائپ کریں →

پائپ لائن، سرے سے آخر تک

پانچ مراحل۔ صرف مرحلہ 3 ایک امیج API کو چھوتا ہے، اور صرف مرحلہ 4 اختیاری ہے:

┌─ 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
└───────────────────────────────────────────────────────────────┘

دو خصوصیات ڈایاگرام سے زیادہ اہم ہیں۔ مرحلہ 2 ایک روٹر ہے: یہ فیصلہ کرتا ہے کہ ہر جگہ کون سا پروڈیوسر چلے، تاکہ آپ کبھی فوٹو لائبریری سے بار چارٹ نہ مانگیں۔ اور مرحلہ 5 وہ جگہ ہے جہاں SEO موجود ہے — گوگل جو کچھ بھی تصاویر کے بارے میں دستاویز کرتا ہے (تفصیلی alt، لائسنس میٹا ڈیٹا، LCP-محفوظ hero) وہ یہاں سے نکالا جاتا ہے، ان فیلڈز سے جو سرچ ریسپانس پہلے ہی لے کر آئی تھی۔

مرحلہ 2: ڈرافٹ کو وژول بریفس میں بدلنا

مکمل ڈرافٹ پر ایک ماڈل کال، اور جو واپس آتا ہے وہ کوئی کوئری نہیں بلکہ ایک پلان ہے۔ ایک واحد فوٹو بریف کیسے لکھا جائے — آرٹیکل کا عنوان بدترین ان پٹ کیوں ہے، 12 سے 25 الفاظ کا کیمرہ بریف کیسا دکھتا ہے، اور یہ کن طریقوں سے ناکام ہوتا ہے — یہ سب کچھ ایک آرٹیکل کو الیسٹریٹ کرنے کی گائیڈ میں مکمل طور پر بیان کیا گیا ہے، اور یہاں دہرایا نہیں جا رہا۔ ایک پائپ لائن جو اضافہ کرتی ہے وہ ہے روٹنگ: اسی کال کو سلاٹ در سلاٹ یہ فیصلہ کرنا ہوتا ہے کہ کون سا پروڈیوسر چلے گا — اور چارٹ کی اینٹری ڈیٹا لے کر چلتی ہے جبکہ فوٹو کی اینٹری ایک منظر لے کر چلتی ہے۔

# 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:
ایک کیمرہ بریف لکھیں: ایک ایسا منظر جسے کیمرہ نے کھینچا ہو سکتا تھا، 12 سے 25 الفاظ میں،
   انگریزی میں، جو سیکشن کے موڈ سے مطابقت رکھتا ہو۔ فریم میں جو کچھ ہے اسے بیان کریں،
   موضوع کو کبھی نہیں۔ کوئی تحریر، لوگو، برانڈز یا مشہور شخصیات نہیں؛ کوئی پوشیدہ
   استعارے نہیں۔ (مکمل قواعد، مثالوں اور ناکامی کی صورتوں کے ساتھ:
   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 ہدایت باقی کام مکمل کرتی ہے: چارٹ کی اینٹری صرف وہی نمبرز لے جا سکتی ہے جو ڈرافٹ میں پہلے سے موجود ہوں، تاکہ ماڈل خود سے کچھ گھڑنے کے بجائے صرف نقل کرے۔ ذیل میں ایک ڈیویلپر آرٹیکل کے تین حقیقی سیکشنز پر روٹر دکھایا گیا ہے:

ٹیبل کو ہر کالم دیکھنے کے لیے سائیڈ وے سوائپ کریں →

مرحلہ 3: تصاویر کریڈٹ کے ساتھ واپس آتی ہیں

ہر kind: "photo" اندراج ایک درخواست ہے۔ اوپر والا hero بریف، جب پبلک API کے خلاف چلایا گیا، یہ 147 ms میں واپس کرتا ہے:

GET /search/photos — hero برئف · "ایک ڈیویلپر جو دیر رات ایک ڈیسک پر دو مانیٹرز کے ساتھ کام کر رہا ہو…" · 147 ms

منتخب کردہ HeroUnsplash Unsplash Pexels

آخری سیکشن بریف، بالکل مختلف منظر، 144 ms میں:

GET /search/photos — سیکشن برئف · "دو انجینئرز ایک وائٹ بورڈ کے سامنے کھڑے ہیں جو ڈایاگرامز سے بھرا ہے…" · 144 ms

سرِفہرست نتیجہ · 0.91Pexels Unsplash Unsplash

ہر تصویر کے ساتھ جو کچھ واپس آتا ہے وہی مرحلہ 5 کو ممکن بناتا ہے — صرف ایک فائل نہیں:

{
  "photo_id":  "019e1c7f-0063-759e-b498-33ce1714e6c9",   // اسے محفوظ کریں: کوئی دہرائی نہیں
  "urls": { "small": "…?w=400", "regular": "…?w=1080",
             "large": "…?w=1920" },
  "width": 3000, "height": 1688,          // → لے آؤٹ شفٹ نہیں ہوتی
  "blur_hash": "LJ8gjv9rVq-6OFxanNNFI7xco$Na",   // → اصل پلیس ہولڈر
  "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 (…)" }
}

مرحلہ 4: جو ایک تصویر نہیں کہہ سکتی

منصوبے میں دو جگہیں سرچ کے قابل نہیں، اور بالکل یہاں دوسرا ماڈل اپنی جگہ حاصل کرتا ہے — تصویر بنانے کے لیے نہیں، بلکہ ایسا کوڈ لکھنے کے لیے جو اسے کھینچے۔ یہ فرق اہم ہے: کوڈ کا جائزہ لیا جا سکتا ہے، یہ ڈیٹرمنسٹک ہے اور بار کی اونچائی کو ہیلوسینیٹ نہیں کر سکتا۔

ڈایاگرامز: متن اندر، SVG باہر

Mermaid ایک سادہ متن تعریف سے ڈایاگرامز رینڈر کرتا ہے،3 جو اسے ماڈل کے لیے سب سے محفوظ ہدف بناتا ہے: آؤٹ پٹ کا معائنہ ہو سکتا ہے، git میں diff کیا جا سکتا ہے، اور ہر بار وہی طریقہ رینڈر ہوتا ہے۔ روٹر پہلے ہی spec واپس کر دیتا ہے۔

# 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
# → ایک SVG جس کا PR میں جائزہ لیا جا سکتا ہے، ایسی تصویر نہیں جس پر آپ کو بھروسہ کرنا پڑے

چارٹس: صرف وہ اعداد جو مضمون میں پہلے سے موجود ہیں

وہی اصول، ایک اضافی گارڈ کے ساتھ۔ روٹر نے قدریں ڈرافٹ سے کاپی کیں؛ ماڈل پلاٹنگ کوڈ لکھتا ہے؛ کوڈ سینڈ باکس میں چلتا ہے؛ اسمبلر رینڈر شدہ قدروں کو ماخذ اعداد کے خلاف دوبارہ چیک کرتا ہے اس سے پہلے کہ چارٹ کو صفحے کے قریب آنے کی اجازت ملے۔

import re, matplotlib
matplotlib.use("Agg")                # headless: CI میں کوئی ڈسپلے نہیں
import matplotlib.pyplot as plt

def assert_in_draft(value, draft: str) -> None:
    """ایک پلاٹ کردہ عدد کو مضمون میں ایک عدد کی حیثیت سے موجود ہونا چاہیے۔"""
    # یہاں سبسٹرنگ میچنگ ایک جال ہے: "120" لفظ "1200" کے اندر ہے، اور
    # "?w=1200" کے اندر بھی — سادہ `str(v) in draft` ہر چیز پر پاس ہو جاتا ہے۔
    # لفظی حدود پر میچ کریں، اور 1 234 / 1,234 / 1234 کو قبول کریں۔
    body = re.sub(r"(?<=\d)[  ,](?=\d{3}\b)", "", draft)   # علیحدگی کے نشانات ہٹائیں
    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)       # ہیلوسینیٹڈ قدر → کوئی چارٹ نہیں

    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)                    # ڈیٹرمنسٹک، جائزے کے قابل نتیجہ
    return out

گارڈ مختصر ہے، لیکن اسے احتیاط سے لکھیں: سبسٹرنگ چیک کام نہیں کرتا۔ "120" in draft اس مضمون کے لیے سچ ہے جس میں 1200 یا ?w=1200 موجود ہو، تو سادہ ورژن ہر چیز پر پاس ہو جاتا ہے اور کچھ بھی محفوظ نہیں کرتا۔ ہندسوں کی حدود پر لنگر کریں، ہزار کے علیحدگی کے نشانات کو نارملائز کریں، تو وہ غلطی کی قسم جس کی وجہ سے کسی ٹیکنیکل مضمون کی تنقید کمنٹس میں ہوتی ہے — ایک چارٹ جو اپنے ہی پیراگراف کی نفی کرے — پروڈکشن تک نہیں پہنچ سکتی۔ اسکرین شاٹس بھی یہی اصول اپناتے ہیں: آپ کی حقیقی بلڈ کے خلاف چلایا گیا اسکرپٹ شدہ page.screenshot() آپ کے اپنے UI کے لیے سچ کا واحد ماخذ ہے، اور UI بدلنے کے ساتھ بھی سچا رہتا ہے۔

مرحلہ 5: SEO کا سارا معاملہ اسمبلی میں ہے

اب تک جو ہوا اس نے فائلیں اور فیلڈز تیار کیں۔ یہ مرحلہ انہیں مارک اپ میں بدلتا ہے — اور یہاں درست ہونا ضروری ہے، کیونکہ تین دستاویزی رویے ان چند سطروں میں فیصلہ ہوتے ہیں۔

<!-- بائٹس ایک دوسرے origin سے آتی ہیں: ہینڈشیک کی قیمت پہلے ادا کریں -->
<link rel="preconnect" href="https://images.unsplash.com" crossorigin>

<!-- LCP ایلیمنٹ: کبھی lazy نہیں، ہمیشہ اعلیٰ ترجیح -->
<figure>
  <img src="{urls.regular}"
       width="{width}" height="{height}"        <!-- لے آؤٹ شفٹ ختم کرتا ہے -->
       alt="{alt}"                                <!-- انتخاب کے BAAD لکھا گیا -->
       fetchpriority="high" decoding="async"
       style="background:{color_hex}">   <!-- غالب رنگ، 1 فیلڈ -->
  <figcaption>{attribution.html}</figcaption>
</figure>

<!-- سیکشن تصاویر، fold کے نیچے: برعکس سیٹنگز -->
<img src="{urls.regular}" width="{width}" height="{height}"
     alt="{alt}" loading="lazy" decoding="async">

1. Hero کو کبھی lazy-load نہ کریں۔ web.dev واضح ہے: "اپنی LCP تصویر کو کبھی lazy-load نہ کریں، کیونکہ اس سے ہمیشہ غیر ضروری ریسورس لوڈ ڈیلے ہوتا ہے، اور LCP پر منفی اثر پڑتا ہے"، اور یہ اس ایلیمنٹ پر fetchpriority="high" کی سفارش کرتا ہے جو LCP بننے کا امکان رکھتا ہو — کم استعمال کیا جائے، صرف ایک تصویر پر۔4 جو پائپ لائن ہر تصویر پر loading="lazy" لگاتی ہے، hero بھی شامل، خودکار پبلشنگ میں سب سے عام خود ساختہ Core Web Vitals زخم ہے۔
2. ہمیشہ width اور height نکالیں — یہ ریسپانس میں واپس آتے ہیں، تو کوئی بہانہ نہیں؛ یہی ایک attribute جوڑا ہے جو براؤزر کو جگہ محفوظ کرنے دیتا ہے اور لے آؤٹ کو اُچھلنے سے روکتا ہے۔ فائل لوڈ ہونے کے دوران پلیس ہولڈر کے طور پر blur_hash استعمال کریں۔
3. alt انتخاب کے بعد لکھیں، پہلے کبھی نہیں۔ یہ باریک نکتہ ہے۔ منصوبے کا alt فیلڈ اس منظر کو بیان کرتا ہے جو آپ نے مانگا تھا؛ جو تصویر آپ کو ملی وہ سب سے قریب ترین میچ ہے، وہی منظر نہیں۔ بریف کا متن alt کے طور پر شپ کرنا بالکل وہی ایکسیسبیلٹی ناکامی ہے جسے یہ پائپ لائن روکنے کے لیے بنی ہے — ایک ایسی تصویر کی تفصیل جو صفحے پر ہی نہیں ہے۔ منتخب تصویر کے alt_description سے alt بنائیں، اور اسے اس پیراگراف کے خلاف بہتر کریں جس میں یہ موجود ہے۔ گوگل کی ہدایت "مفید، معلومات سے بھرپور کانٹینٹ بنانے پر توجہ دینا ہے جو کلیدی الفاظ کو مناسب طریقے سے استعمال کرے اور صفحے کے کانٹینٹ کے سیاق و سباق میں ہو" ہے، اور یہ خبردار کرتا ہے کہ alt attributes کو کلیدی الفاظ سے بھر دینا "صارف کے تجربے کو منفی بناتا ہے اور آپ کی سائٹ کو اسپیم سمجھا جا سکتا ہے"۔1

وہ حصہ جسے تقریباً کوئی خودکار نہیں کرتا: لائسنس میٹا ڈیٹا

گوگل امیج لائسنسنگ کے لیے ImageObject اسٹرکچرڈ ڈیٹا کی حمایت کرتا ہے۔ اسے contentUrl کے علاوہ creator، creditText، copyrightNotice یا license میں سے کم از کم ایک درکار ہوتا ہے، acquireLicensePage کی سفارش کی جاتی ہے، اور لائسنس معلومات والی تصاویر گوگل امیجز میں Licensable بیج کے لیے اہل ہو جاتی ہیں۔5 یہ ہر فیلڈ سرچ ریسپانس میں پہلے سے موجود ہے — تو اسے نکالنا ایک ٹیمپلیٹ ہے، پروجیکٹ نہیں:

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "ImageObject",
  "contentUrl": "{urls.large}",                 // لازمی
  "creator": { "@type": "Person",
                "name": "{photographer_full_name}" },
  "creditText": "{photographer_full_name} on {source}",
  "license": "{LICENSE_URL[source]}",           // لائبریری کا اپنا صفحہ
  "acquireLicensePage": "{source_image_url}"     // تصویر کا صفحہ
}
</script>

# LICENSE_URL `source` فیلڈ کو اس لائسنس سے نقشہ بند کرتا ہے جو حقیقتاً
# تصویر پر لاگو ہے — unsplash.com/license, pexels.com/license, pixabay.com/…

ایک تفصیل جسے درست رکھنا اہم ہے: license کو اس لائسنس کی طرف اشارہ کرنا چاہیے جو اس تصویر پر لاگو ہوتا ہے — ماخذ لائبریری کا اپنا لائسنس صفحہ — نہ کہ آپ کے ڈومین پر کوئی خلاصہ صفحہ۔ گوگل اسے بیج کی اہلیت کا فیصلہ کرنے کے لیے پڑھتا ہے، اور خود سے مماثل URL بطور اشارہ کمزور ہے اور اسے خود سے واپس لنک کے علاوہ کسی چیز کے طور پر ثابت کرنا مشکل ہے۔ اپنا لائسنس خلاصہ قارئین کے لیے ایک اندرونی صفحے پر رکھیں؛ اصلی والا مارک اپ میں ڈالیں۔

اور جب آپ اسمبلر میں ہوں: فائل کو IMG_0042.jpg کے بجائے مختصر تفصیلی نام دیں، اور تصویر کو سائٹ میپ میں شامل کریں — گوگل کا امیج سائٹ میپ فارمیٹ ہر صفحہ URL کے لیے 1,000 تک تصاویر قبول کرتا ہے۔6 دونوں کام پائپ لائن میں ایک ایک لائن کے ہیں اور دونوں کبھی ہاتھ سے نہیں کیے جاتے۔

اپنانے کے لیے دو پائپ لائنز

وہی پانچ مراحل، دو بالکل مختلف شکلیں — ایک ان مضامین کے لیے جو آپ لکھتے ہیں، ایک ان دستاویزات کے لیے جو ایک چلتی ہوئی پروڈکٹ سے میچ کرنی چاہیے۔ جس کی ناکامی کی حالت آپ پہچانتے ہیں، وہ منتخب کریں۔

1 · CI میں dev بلاگ — ریپو میں Markdown

مضامین Markdown کے طور پر رہتے ہیں، تصاویر ان کے ساتھ کمٹ ہوتی ہیں، اور یہ سب کچھ push پر چلتا ہے۔ ڈیٹرمنسٹک، 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   # تصاویر PR میں آ جاتی ہیں
        with: { commit-message: "chore(content): illustrate" }

انسان اب بھی PR کی منظوری دیتا ہے، اور یہی مقصد ہے: پائپ لائن تجویز کرتی ہے، جائزہ لینے والا فیصلہ کرتا ہے، اور اس نے لکھی front-matter کا diff دیکھا جا سکتا ہے۔

سرچ والا نصف حصہ ایک GET کال ہے — درخواست، اس کا score_threshold اور جو فیلڈز یہ واپس کرتی ہے، یہ سب واحد آرٹیکل والی گائیڈ میں لائن بہ لائن لکھے گئے ہیں، اس لیے یہاں انہیں دوبارہ چھاپنے کے بجائے امپورٹ کیا گیا ہے۔ یہ فائل جو کچھ اضافہ کرتی ہے وہ ہر وہ چیز ہے جس کی ضرورت ایک پلان کو ہوتی ہے اور ایک اکیلی تصویر کو نہیں: ایسے بریف پر دوبارہ کوشش جو کچھ واپس نہ لائے، ہر photo_id پر دعویٰ تاکہ کوئی دو صفحات ایک تصویر شیئر نہ کریں، اور واپس آنے والی تصویر سے لکھا گیا آلٹ ٹیکسٹ۔

import frontmatter
from photo_search import search   # ایک GET /search/photos; `used` میں موجود ids کو چھوڑ دیتا ہے

def find_photo(entry: dict, used: set) -> dict | None:
    """تلاش کریں؛ اگر بریف بہت مخصوص تھی تو ایک بار وسیع کریں، پھر ترک کریں۔"""
    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"])   # اسے لے لیں: پوری سائٹ پر دہرائی نہیں
            return photo
    return None                        # کالر فیصلہ کرے: جگہ چھوڑ دیں، یا ناکام ہو جائیں

def widen(query: str) -> str:
    """آخری جملہ ہٹا دیں — عام طور پر یہی زیادہ مخصوص ہوتا ہے۔"""
    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:                    # کوئی hero بری hero سے بہتر ہے
        raise SystemExit(f"{path}: no photo above threshold — rewrite the brief")

    post["hero"] = {                    # وہ سب کچھ جو ٹیمپلیٹ کو درکار ہے
        "src": hero["urls"]["regular"], "w": hero["width"], "h": hero["height"],
        # alt وہی تصویر بیان کرتا ہے جو ہمیں ملی، وہ منظر نہیں جو ہم نے مانگا۔
        "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، اسکرین ریڈرز کے لیے ~125 حروف تک تراشا گیا۔
    اگر بہتر چاہیں تو پیراگراف کے ساتھ ماڈل کو دوبارہ بھیجیں۔"""
    base = photo.get("alt_description") or photo.get("description", "")
    return base[:125].rstrip(" ,;")

2 · دستاویزات اور چینج لاگ — پہلے اسکرین شاٹس، آخر میں تصاویر

روٹر کی ڈیفالٹس کو الٹ دیں۔ پروڈکٹ دستاویزات میں ایماندارانہ وژول تقریباً ہمیشہ آپ کی اپنی UI ہوتی ہے: ایک Playwright اسکرپٹ جو حقیقی بلڈ کھولتا ہے، ایک مقررہ viewport سیٹ کرتا ہے اور بالکل وہی حالت کیپچر کرتا ہے جو پیراگراف بیان کرتا ہے۔ ڈایاگرامز آرکیٹیکچر صفحات کو کور کرتے ہیں، اور تصاویر صرف تصوراتی اور لینڈنگ صفحات پر ظاہر ہوتی ہیں — جہاں اسکرین شاٹ کچھ نہ کہہ سکے۔

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)   # ریٹینا-صاف
    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()
# دستاویزات کی بلڈ جیسی CI جاب میں چلتا ہے → اسکرین شاٹ کبھی UI کے ایسے
# ورژن کو بیان نہیں کر سکتا جو اب موجود ہی نہیں۔

دو ورژن جن کا نام لینا ضروری ہے لیکن اپنی الگ ترکیب کے لائق نہیں۔ پروگرامیٹک SEO لوپ کو الٹ دیتا ہے: ایک ڈیٹابیس سے جنریٹ ہونے والے سیکڑوں صفحات کے ساتھ آپ فی صفحہ سرچ نہیں کرتے — ایک درخواست 100 تصاویر تک واپس کر سکتی ہے، تو آپ فی موضوعاتی کلسٹر سرچ کرتے ہیں اور ایک پول سے تخصیص کرتے ہیں، ایک یونیک ایسیس کی رکاوٹ ڈی ڈوپلیکیشن کرتی ہے (وہ آرکیٹیکچر، مکمل تفصیل میں)۔ اور نیوز لیٹرز اور سوشل کارڈز کو ایک ہی تصویر کی چار crops میں ضرورت ہوتی ہے: photo_id محفوظ رکھیں، urls سے وہ سائز مانگیں جو آپ کو چاہیے، اور صرف اس وقت دوبارہ سرچ کریں جب کوئی crop حقیقتاً ناکام ہو جائے۔

وہی پائپ لائن، ایک ایجنٹ کی صورت میں

اگر ماڈل پہلے ہی ڈرافٹ لکھ رہا ہے، تو مختصر ترین راستہ یہ ہے کہ اسے سرچ ٹول براہِ راست دے دیا جائے، بجائے اس کے کہ عمل کے مختلف مراحل کے درمیان JSON کو منتقل کیا جائے۔ Pexafy ایک ہوسٹڈ Model Context Protocol سرور mcp.pexafy.com/mcp پر چلاتا ہے۔ کنیکٹر سیٹ اپ اور اس کے فراہم کردہ ٹولز کا احاطہ کہیں اور کیا گیا ہے — ڈیسک ٹاپ اور ایڈیٹر سیٹ اپ سنگل آرٹیکل گائیڈ میں، CI رنر کے لیے ہیڈلیس ورژن اسکیل پر مواد کے آرٹیکل میں، اور وسیع تر کنیکٹر مارکیٹ کی صورتحال — کون MCP امیج سرور فراہم کرتا ہے، کن شرائط پر — AI ایجنٹس کے لیے امیج سرچ انفراسٹرکچر کے مطالعے میں۔ یہاں دکھانے کے قابل بات یہ ہے کہ جب ایجنٹ کے پاس یہ ٹولز ہوں تو اس پائپ لائن کا کیا ہوتا ہے: یہ پانچ مراحل کے بجائے ایک ہی ہدایت بن جاتی ہے۔

You  یہ ڈرافٹ ہے۔ وژول پلان بناؤ، اسے illustrate کرو، اور ایک PR کھولو۔
     چارٹس صرف ان اعداد سے جو متن میں پہلے سے موجود ہیں۔

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"

یہ آخری لائن ہی وجہ ہے کہ اس لوپ میں ایک خالص اسکرپٹ کے بجائے ایجنٹ رکھنا فائدہ مند ہے: خودکار تصویر کشی کی ناکامی کی حالت ایک بری بریف ہوتی ہے، اور بری بریف کو دوبارہ لکھنا بالکل وہ کام ہے جس کے لیے ایک لینگویج ماڈل بنایا گیا ہے۔ ڈیٹرمنسٹک حصے — تخصیص، ڈی ڈوپلیکیشن، عددی گارڈ — کوڈ میں ہی رکھیں۔

ایک illustrated مضمون کی قیمت کیا ہے

ہر مضمون میں تین فوٹو جگہوں کا مطلب ہے تین سرچ درخواستیں، تو فری پلان (5,000 درخواستیں/ماہ) کور کرتا ہے 1,666 مضامین ہر مہینے — اس سے پہلے کہ ادائیگی کا کوئی سوال اٹھے — اور اگر آپ ہر مضمون کے بجائے ہر موضوعاتی کلسٹر پر سرچز کو pool کریں تو یہ حد ایک اور درجہ ترتیب سے آگے بڑھ جاتی ہے۔ پلان بہ پلان تفصیل، اور وہ pooling آرکیٹیکچر جو اسے غیر متعلق بنا دیتا ہے، دیکھیں بڑے پیمانے پر کانٹینٹ کو illustrate کرنے والا ساتھی مضمون میں۔

فی مضمون دو ماڈل کالز — ایک ڈرافٹ کے لیے، ایک وژول پلان کے لیے — چند ہزار ٹوکنز کی ہیں اور پائپ لائن کی سب سے سستی لائن ہوں گی؛ Mermaid اور matplotlib رینڈرز صرف CI سیکنڈز کی قیمت لیتے ہیں۔ جو نمبر لوگوں کو حیران کرتا ہے وہ یہ ہے کہ کون سی لائن سستی نہیں: ہر مضمون میں چار تصاویر جنریٹ کرنا، ماہانہ چار سو تصاویر، اور وہ کوششیں جو کارآمد نہ نکلیں — اور آؤٹ پٹ پھر بھی کوئی فوٹوگرافر، کوئی تاریخ اور کوئی سورس URL نہیں رکھتا۔

یہ پائپ لائن کیا نہیں سنبھالتی

ایک ایماندارانہ سیکشن، کیونکہ جو ناکامی یہ روکتی ہے وہ مہنگی ہے۔ اچھی طرح illustrated مضمون پھر بھی ایک مضمون ہے: حقیقی فوٹوگرافی، درست چارٹس اور صحیح مارک اپ ایک ایسے صفحے کو بہتر بناتے ہیں جو موجود ہونے کا حق رکھتا ہے۔ یہ کمزور، بڑی مقدار میں تیار کیا گیا کانٹینٹ رینک نہیں کرا سکتے۔ گوگل کی اسپیم پالیسیاں scaled content abuse کا نام لیتی ہیں — بہت سے صفحات بنیادی طور پر رینکنگز پر اثر ڈالنے کے لیے جنریٹ کرنا اور صارفین کو کم قیمت دینا، خواہ آٹومیشن شامل ہو یا نہ ہو — اور اس فیصلے میں تصویروں کے معیار کا کوئی کردار نہیں۔7

تو وہ فریم ورک جو قائم رہتا ہے: یہ پائپ لائن ایک معیار کی زمین ہے جسے آپ کنٹرول کرتے ہیں، ان صفحات پر لاگو ہوتی ہے جن کے پاس شائع ہونے کی پہلے سے وجہ موجود ہو۔ جہاں یہ ثابت طور پر فائدہ دیتی ہے:

• ایسی اصلیت جسے قاری تصدیق کر سکے۔ ایک اصلی فوٹوگرافر اور سورس URL کے ساتھ کریڈٹ لائن ایک ایسا دعویٰ ہے جسے چیک کیا جا سکتا ہے — اور وہی فیلڈز گوگل کے پڑھے جانے والے ImageObject مارک اپ کو بھی فیڈ کرتی ہیں۔
• ایکسیسبیلٹی اور Core Web Vitals۔ اصلی alt متن، ہر تصویر پر پیمائشیں، ایک hero جسے کبھی lazy-load نہیں کیا جاتا۔ ہر مضمون پر ضرب دیں جو آپ شائع کرتے ہیں اور یہی سائٹ کی امیج-کوالٹی کہانی ہے۔
• جہاں چیک کیا جا سکے وہاں درستگی۔ ایک چارٹ جس کے اعداد مضمون کے خلاف اثبات شدہ ہوں، چلتی ہوئی بلڈ سے جنریٹ کیا گیا اسکرین شاٹ، PR میں متن کے طور پر جائزے کے قابل ڈایاگرام — تین وژولز جو ٹیسٹ کی ناکامی کے بغیر سچ سے ہٹ نہیں سکتے۔

کریڈٹ کے معاملے میں، پائپ لائن سے متعلق نکتہ محدود ہے: کریڈٹ کو ہمیشہ ظاہر کرنے کے حق میں دلیل کہیں اور دی گئی ہے، اور ایک خودکار اسمبلر جو اضافہ کرتا ہے وہ یہ ہے کہ وہی attribution اسٹرنگ جو یہ پرنٹ کرتا ہے، وہی creditText ہے جس کی ساختہ ڈیٹا کو ضرورت ہوتی ہے۔ ایک فیلڈ، دو جگہیں، ایک ہی ٹیمپلیٹ پاس میں خارج — یہی وجہ ہے کہ پائپ لائن کے پاس اسے چھوڑنے کا انسان سے بھی کم عذر ہوتا ہے۔

کہاں سے شروع کریں

1. روٹر پرامپٹ شامل کریں کسی بھی چیز میں جو پہلے سے آپ کے ڈرافٹس لکھتی ہے، اور JSON پرنٹ کریں اس پر عمل کیے بغیر۔ دس منصوبے پڑھیں۔ اگر بریفس منظر کے بجائے موضوعات کا نام لیں تو کوئی انٹیگریشن لکھنے سے پہلے پرامپٹ درست کریں۔
2. صرف فوٹو جگہیں وائر کریں۔ ہر بریف کے لیے ایک GET /search/photos، اور پہلے دن سے photo_id محفوظ کریں — 3,000 لائیو صفحات پر بعد میں لگائی گئی ڈی ڈوپلیکیشن ایک مائیگریشن ہے، کالم نہیں۔
3. width، height اور alt نکالیں اسی کمٹ میں۔ یہ سب سے سستا Core Web Vitals کام ہے جو آپ کبھی کریں گے۔
4. پھر مرحلہ 4 شامل کریں، چارٹس سے پہلے ڈایاگرامز — Mermaid متن ہے، تو یہ سنٹیکس ایرر کے سوا کسی ناکامی کی حالت کے بغیر ہے۔
5. عددی گارڈ شامل کریں پہلا چارٹ قاری تک پہنچنے سے پہلے، بعد میں نہیں۔

حوالہ جات اور فوٹ نوٹس