@aglyn/plugins-ai 1.0.0-beta.235 → 1.0.0-beta.237

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).
@@ -28,17 +29,33 @@ import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-
  *
  * For each slot, in document order:
  *
- * 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)
+ * 1. **Search.** Plain words. The hero asks for the kind of business (the
+ *    head of the site's business type, "yoga studio" from "a family-owned
+ *    yoga studio in Austin"). Any other picture asks for its SUBJECT: the
+ *    noun phrase that opens the alt text the model wrote, its filler
+ *    adjectives dropped ("serving bowl" from "A beautiful hand-thrown serving
+ *    bowl on a linen cloth"), qualified by the site's craft where the phrase
+ *    does not already say it ("serving bowl ceramic" for a ceramics studio).
+ *    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; one page never asks the same words twice.
+ * 2. **Rank.** A picture of a thing must show the thing: every hit is scored
+ *    by how many of the subject's words its tags, its description and its
+ *    page's address name (singular and plural alike, the head noun counting
+ *    double), and a hit naming none of them never fills a picture of a
+ *    thing. The live Juniper Clay start put crackers under "Serving bowl"
+ *    and plants under "Espresso cup". Among the best-scored hits the job's
+ *    seed picks, so two sites built from the same words rarely open with the
+ *    same photo while one job always picks the same.
+ * 3. **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 maker's portrait in About is
+ *    never a vase in Selected work. The caller hands in what the job's other
+ *    pages hold (`avoid`); a pass repeated over its own page keeps its own.
+ * 4. **Fall back.** A picture of a thing nothing relevant answered asks once
+ *    more for the place itself ("ceramics studio interior"), a neutral photo
+ *    any caption sits under, before it is left to a starter photo.
+ * 5. **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,
@@ -51,39 +68,109 @@ import { type AiLayoutPictureSlot, type AiLayoutPictureSource } from '../layout-
  */
 /** 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;
+/** 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 = 12;
 /** The hits a pick is made among. */
 export declare const AI_LAYOUT_STOCK_PICK_WINDOW = 8;
 /** 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).
  */
 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, singular — "ceramic" from "small-batch ceramics
+ * studio", "yoga" from "yoga studio". Empty when the business is only a
+ * place ("a shop").
+ */
+export declare function aiStockCraftWords(business: string): string;
+/**
+ * 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 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 gallery picture's searches must find a hit
+ * naming its subject; a `neutral` one asks for the place itself, which any
+ * caption sits under.
+ */
+export interface AiStockSearch extends StockPhotoSearchRequest {
+    neutral?: boolean;
+}
 /** 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;
+    craft?: string;
+}): AiStockSearch[];
+/**
+ * How well a hit names a subject (AGL-3660): each subject word its tags, its
+ * description or its page's address names counts once, the head noun (the
+ * subject's last word) twice, and a craft word a quarter, as a tiebreak.
+ * Zero when it names none of the subject.
+ */
+export declare function aiStockRelevance(photo: Pick<StockPhoto, 'tags' | 'alt' | 'pageUrl'>, terms: {
+    subject: string;
+    craft?: string;
+}): number;
+export interface AiStockRankOptions {
+    /** The words a hit is scored by; none, and every hit scores alike. */
+    subject?: string;
+    craft?: string;
+    /** A hit naming none of the subject is no candidate at all. */
+    strict?: boolean;
+}
+/**
+ * A search's hits in the order they are tried (AGL-3660): those not placed
+ * yet, among the first few, best-scored 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, options?: AiStockRankOptions): 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, options?: AiStockRankOptions): 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[];
     signal?: AbortSignal;
 }
 export interface AiLayoutStockPhotoDeps {