@aglyn/plugins-ai 1.0.0-beta.236 → 1.0.0-beta.238

package/src/lib/jobs/ai-layout-stock-photos.d.ts

@@ -16,6 +16,7 @@
  */
 import { type PluginMediaIngest } from '@aglyn/aglyn/plugin-manager/plugin-media-ingest';
 import { type StockPhoto, type StockPhotoOrientation, type StockPhotoProvider, type StockPhotoSearchRequest } from '@aglyn/aglyn/plugin-manager/stock-photo-provider';
+import type { NodesMap } from '@aglyn/aglyn/types/nodes';
 import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-language/ai-layout-pictures';
 /**
  * STOCK PHOTOS FOR A LANGUAGE PAGE'S PICTURE SLOTS (AGL-3660).
@@ -26,64 +27,223 @@ import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-
  * server door (`core.media-ingest`), and builds no source at all when either
  * is missing, so a deployment without a key behaves exactly as before.
  *
- * For each slot, in document order:
+ * What the live starts of 2026-10-10 taught (Juniper Clay Works, a ceramic
+ * artist's portfolio, and Willow Wick Candles, a candle store), each photo
+ * traced through the library's cached answers:
  *
- * 1. **Search.** Plain words: the kind of business (the head of the site's
- *    business type, "yoga studio" from "a family-owned yoga studio in
- *    Austin") for the hero; the picture's own subject (the content words of
- *    the alt text the model wrote, else its section's name) with the business
- *    for the rest, and an about picture asks for people. The orientation and
- *    a minimum size come from the slot's frame. The provider caches every
- *    search for a day and keeps its own rate limit.
- * 2. **Pick.** Among the first hits not already on the page, by the job's
- *    seed and the slot, so two sites built from the same words rarely open
- *    with the same photo while one job always picks the same.
- * 3. **Keep.** A photo the site's library already holds (by its source key)
- *    is reused; otherwise its bytes are downloaded from the library and
- *    stored in the site's own media library as the member who started the
- *    job, credited to its photographer. The page names the site's asset,
- *    never the library's address.
+ * - The site's words were read as "portfolio" and "online" — the kind of
+ *   SITE, not the craft — so every search said "serving bowl portfolio" and
+ *   the hero asked for "portfolio": a wallet, fashion models, and a blank
+ *   paper mockup that read as an empty panel beside the brushes.
+ * - A hit naming the object anywhere won: a robin tagged "food bowl" filled
+ *   "Speckled serving bowl", a lilac branch tagged "bud, vase" filled "Tall
+ *   bud vase", letterpress type tagged "set" filled "Nesting bowl set" (its
+ *   head noun was read as "set"), and an antique tea set tagged "brown
+ *   candle" filled "Candle Gift Set".
+ * - The page's 20 seconds ran out after four photos (each copy took ~5s, one
+ *   after another), and the slots left took the starter photos: the laptop
+ *   desk with pink roses under "Candle Wick Trimmer" and a work card, and the
+ *   windowsill plants under another.
  *
- * A slot that finds nothing, any error, a refusal from the library (its
- * storage band, say) or the time running out leaves the slot to a starter
- * photo. Nothing here throws, and none of it is an AI model call: photos cost
- * no AI credits.
+ * So, for each slot:
+ *
+ * 1. **The site's terms** ({@link aiStockSiteTerms}): the business is the
+ *    first clause of its type that says more than what kind of site it is
+ *    ("ceramic artist" from "a portfolio for a ceramic artist who makes
+ *    stoneware bowls"), its craft one word ("ceramic"), and its DOMAIN the
+ *    words a photo of its world names: the craft, the business type's own
+ *    nouns ("stoneware", "soy") and, for common crafts, their kin ("pottery",
+ *    "clay", "wax"). Its broad searches ask for the world itself ("handmade
+ *    ceramics", "pottery").
+ * 2. **Search.** A picture of a thing asks for its subject — the noun phrase
+ *    of the caption, filler dropped — qualified by the craft where it does
+ *    not already name the domain ("ceramic serving bowl"), then the craft and
+ *    the object alone ("ceramic bowl"), then the broad searches. A hero asks
+ *    for the business, then broad; an about picture for the business's
+ *    people, then broad. The orientation and a minimum size come from the
+ *    slot's frame.
+ * 3. **Accept, or reject.** A hit tagged as a mockup, a blank or a template
+ *    never fills anything. A picture of a thing takes only a hit naming its
+ *    OBJECT (the head noun, past "set", "gift", "kit": "bowl" in "nesting
+ *    bowl set", "candle" in "candle gift set") AND either the site's domain
+ *    or the subject's own two-word phrase ("bud vase"). A broad, hero or
+ *    about search takes only a hit naming the domain. The accepted are
+ *    ranked: the object in the hit's first tags (what the photo is OF) over
+ *    a mention in its last, the subject's other words, the domain. Among
+ *    equals the job's seed picks, so two sites differ and one job repeats.
+ * 4. **Never twice.** A photo is placed once per job: not twice on a page,
+ *    and not on a page when another page (or another pass, in this process)
+ *    of the same job already placed it. The caller hands in what the job's
+ *    other pages hold (`avoid`); a pass repeated over its own page keeps its
+ *    own.
+ * 5. **Keep, all at once.** The choosing is done first, slot by slot; the
+ *    copies then run side by side, a few at a time, so a page of eight
+ *    pictures takes about as long as two. A photo the site's library already
+ *    holds (by its source key) is reused; otherwise its bytes are copied
+ *    into the site's own library as the member who started the job, credited
+ *    to its photographer. A copy that fails tries the slot's next accepted
+ *    hit.
+ *
+ * A slot nothing acceptable answered — the library down, refusing, or out
+ * of time — is left `null` for the starter photos. A named object is never
+ * given one while the library answers anything of the site's world: the
+ * broad searches come first. Nothing here throws, and none of it is an AI
+ * model call: photos cost no AI credits.
  */
 /** Wall clock the whole page's photos may take, inside the step's own signal. */
-export declare const AI_LAYOUT_STOCK_PHOTOS_BUDGET_MS = 20000;
-/** Searches one page may ask, cached ones included. */
-export declare const AI_LAYOUT_STOCK_SEARCHES_PER_PAGE = 8;
+export declare const AI_LAYOUT_STOCK_PHOTOS_BUDGET_MS = 30000;
+/** Searches one page may send to the provider; a repeated query is answered from the page's own memory. */
+export declare const AI_LAYOUT_STOCK_SEARCHES_PER_PAGE = 18;
 /** The hits a pick is made among. */
-export declare const AI_LAYOUT_STOCK_PICK_WINDOW = 8;
+export declare const AI_LAYOUT_STOCK_PICK_WINDOW = 40;
 /** The largest photo copied: inside one direct upload. */
 export declare const AI_LAYOUT_STOCK_MAX_BYTES: number;
+/**
+ * The unit job input naming the screen drafts the job's other pages were
+ * written to, whose photos a page does not place again (AGL-3660).
+ */
+export declare const AI_STOCK_PHOTO_PAGES_INPUT = "stockPhotoPages";
+/**
+ * A word's singular, for matching only: "bowls" and "bowl", "vases" and
+ * "vase", "berries" and "berry", "dishes" and "dish" meet. Both sides of a
+ * comparison are reduced the same way, so an odd stem still matches itself.
+ */
+export declare function aiStockStem(word: string): string;
 /**
  * The kind of business in a few words: the first clause of the business
- * type, before a place or an audience, its last three content words (the
- * head of an English noun phrase is at its end).
+ * type that says more than what kind of site it is, before a place, an
+ * audience or what it makes, filler dropped, its last three words (the head
+ * of an English noun phrase is at its end). "ceramic artist" from "a
+ * portfolio for a ceramic artist who makes stoneware bowls"; "candle shop"
+ * from "a small-batch candle shop selling hand-poured soy candles online".
  */
 export declare function aiStockBusinessWords(businessType: string): string;
-/** A picture's subject in a few words: its alt text's first content words, else its section's name. */
+/**
+ * The business's craft in one word: the last of its words that is not the
+ * place it is done in nor the person doing it, singular — "ceramic" from
+ * "ceramics studio" or "ceramic artist", "yoga" from "yoga studio". Empty
+ * when the business is only a place ("a shop").
+ */
+export declare function aiStockCraftWords(business: string): string;
+/** What a site's photos are searched and judged by (AGL-3660). */
+export interface AiStockSiteTerms {
+    /** The kind of business, in a few words: "ceramic artist". */
+    business: string;
+    /** Its craft, one singular word: "ceramic". */
+    craft: string;
+    /**
+     * The stems a photo of the site's world names: the business's own words,
+     * what the things it makes are made of, and the craft's kin. Empty for a
+     * site whose words name no world (a type left blank), and then no hit is
+     * held to it.
+     */
+    domain: string[];
+    /** The searches for the site's world itself, broadest last. */
+    broad: string[];
+}
+/** The site's terms, read from its business type. */
+export declare function aiStockSiteTerms(businessType: string): AiStockSiteTerms;
+/**
+ * A picture's subject in a few words (AGL-3660): the noun phrase its alt
+ * text opens with — its first clause holding more than filler, cut where a
+ * preposition starts the setting, filler dropped, its last three words (the
+ * head noun is the last) — else its section's name.
+ */
 export declare function aiStockSubjectWords(alt: string, sectionName: string): string;
+/**
+ * The thing a subject shows, one singular word: its last word that is not
+ * a set or a wrapper of it — "bowl" from "nesting bowl set", "candle" from
+ * "candle gift set", "vase" from "bud vase". Its last word when every word
+ * is one ("gift set").
+ */
+export declare function aiStockObjectWord(subject: string): string;
 /** The frame's orientation: a wide frame wants a landscape photo, a tall one a portrait. */
 export declare function aiStockOrientation(aspect: number): StockPhotoOrientation;
+/**
+ * One search a slot tries. A `broad` one asks for the site's world and
+ * takes any hit of it; any other picture of a thing takes only a hit naming
+ * the thing.
+ */
+export interface AiStockSearch extends StockPhotoSearchRequest {
+    broad?: boolean;
+    /** The words its hits are scored by, where they are not the slot's own subject (a product's searches, AGL-3676). */
+    subject?: string;
+    /** A word every hit must name: a product's photo names the shop's category (AGL-3676). */
+    requires?: string;
+}
+/**
+ * A product's searches (AGL-3676), most specific first: each of its subjects
+ * — its name's noun phrase, then its photo's — with the shop's category
+ * where the phrase does not already say it ("candle gift box"), then the
+ * category alone, a plain photo of what the shop sells. Every one must find a
+ * hit naming the category, so no product is ever filled with a lifestyle shot
+ * of something else: the beta.237 Willow Wick start put a laptop and roses
+ * under "Candle Wick Trimmer" and an antique tea set under "Candle Gift Set".
+ */
+export declare function aiStockProductSearches(slot: Pick<AiLayoutPictureSlot, 'aspect' | 'product'>, craft: string): AiStockSearch[];
 /** The searches a slot tries, in order, most specific first, each distinct. */
-export declare function aiStockSearchesFor(slot: Pick<AiLayoutPictureSlot, 'role' | 'alt' | 'aspect'>, words: {
-    business: string;
-    subject: string;
-}): StockPhotoSearchRequest[];
-/** The pick among a search's hits: not on the page yet, among the first few, by the seed. */
-export declare function aiStockPick(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string): StockPhoto | null;
+export declare function aiStockSearchesFor(slot: Pick<AiLayoutPictureSlot, 'role' | 'alt' | 'aspect'>, terms: Pick<AiStockSiteTerms, 'business' | 'craft' | 'domain' | 'broad'>, subject: string): AiStockSearch[];
+/** What a hit is judged by. */
+export interface AiStockJudgement {
+    /** The words the picture is of; empty for a picture of the site's world. */
+    subject?: string;
+    /** The site's domain stems ({@link AiStockSiteTerms.domain}). */
+    domain?: readonly string[];
+    /**
+     * Whether a hit must name the subject's object. A broad search, a hero
+     * and an about picture need only name the domain.
+     */
+    strict?: boolean;
+    /** A word every hit must name: a product's photo names the shop's category (AGL-3676). */
+    requires?: string;
+}
+/**
+ * How well a hit shows what a slot needs (AGL-3660), or 0 when it must not
+ * fill it: a mockup or a blank never; a picture of a thing only when the hit
+ * names its object AND either the site's world or the subject's own
+ * two-word phrase ("bud vase", "wick trimmer"); anything else only when it
+ * names the site's world (when the site names one). Among the accepted, the
+ * object among the hit's first tags counts 4 (a mention among its last, 2),
+ * the subject's two-word phrase 3, each of its other words 1, and the
+ * site's world 1, plus a quarter when it is among the first tags.
+ */
+export declare function aiStockRelevance(photo: Pick<StockPhoto, 'tags' | 'alt' | 'pageUrl'>, judgement: AiStockJudgement): number;
+/**
+ * A search's acceptable hits in the order they are tried (AGL-3660): those
+ * not placed yet, among the first few the library returned, those it must
+ * not take dropped ({@link aiStockRelevance}), best first; the seed turns
+ * the hits that score alike, so two jobs differ and one job repeats itself.
+ */
+export declare function aiStockRank(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, judgement?: AiStockJudgement): StockPhoto[];
+/** The pick among a search's hits: the first {@link aiStockRank} would try, or `null`. */
+export declare function aiStockPick(photos: readonly StockPhoto[], used: ReadonlySet<string>, seed: string, judgement?: AiStockJudgement): StockPhoto | null;
+/**
+ * The library photos a stored page already shows: every `image` whose
+ * source is the site's media reference. Starter photos are the platform's,
+ * not the job's, and are not listed.
+ */
+export declare function aiStockPlacedSrcs(nodes: NodesMap | null | undefined): string[];
+/** Forgets every job's placed photos; for specs. */
+export declare function aiStockForgetJobPhotos(): void;
 export interface AiLayoutStockPhotoSourceInput {
     hostId: string;
     /** The member the photos are stored as: the job's creator. */
     uid: string;
-    /** The job's seed, as the starter photos turn by. */
+    /** The job's seed, as the starter photos turn by; also the scope a photo is placed under. */
     seed: string;
     /** The site's business type, else the job's brief. */
     business: string;
     /** The page's section names, by plan index. */
     sectionNames: readonly string[];
+    /**
+     * The job the member started (`aiOriginJobId`), so a photo is placed once
+     * across its pages. Absent, only the page itself is kept free of repeats.
+     */
+    jobId?: string;
+    /** Asset srcs or source keys the job's other pages already show. */
+    avoid?: readonly string[];
+    /** The most searches this source sends; a page's own bound where absent. A store's products search more (AGL-3676). */
+    searches?: number;
     signal?: AbortSignal;
 }
 export interface AiLayoutStockPhotoDeps {