@nextblock-cms/cortex 0.15.10 → 0.16.1

package/lib/ai-seo-metadata.d.ts

@@ -0,0 +1,127 @@
+import { z } from './zod-config';
+/**
+ * The shape we require back from the model. Every field is a trimmed, non-empty
+ * string: a blank meta description is worse than no meta description at all,
+ * because the crawler then indexes an empty tag instead of falling back to the
+ * page copy, so we would rather fail the attempt and let the routing fallback try
+ * the next model than persist an empty value.
+ *
+ * `z.strictObject` is deliberate. Models routinely volunteer extra keys such as
+ * `keywords`, `slug`, or `notes`; rejecting them here keeps the contract honest
+ * and surfaces a drifting prompt as a loud validation error rather than as
+ * silently ignored output. The routing layer treats a validation failure as
+ * retryable, so a chatty model simply costs us one extra attempt.
+ */
+export declare const cortexAiSeoMetadataOutputSchema: z.ZodObject<{
+    metaDescription: z.ZodString;
+    metaTitle: z.ZodString;
+    ogDescription: z.ZodString;
+    ogTitle: z.ZodString;
+}, z.core.$strict>;
+export type CortexAiSeoMetadataOutput = z.infer<typeof cortexAiSeoMetadataOutputSchema>;
+/**
+ * Length budgets applied AFTER parsing rather than trusted to the prompt.
+ *
+ * Every model overshoots a stated character budget some of the time — they count
+ * tokens, not characters, and they cannot see their own output length while
+ * generating it. Asking for "under 60 characters" in the prompt raises the hit
+ * rate but never guarantees it, and a meta title that a search engine truncates
+ * mid-word in the results list is a user-visible defect. So the prompt states the
+ * budget (to get well-shaped copy) and this table enforces it (to get a correct
+ * result).
+ *
+ * The numbers track what search engines and social crawlers actually render:
+ * roughly 60 characters before a title is cut in the results list, roughly 160 for
+ * a description snippet, and the looser Open Graph card limits used by Facebook,
+ * LinkedIn, and Slack unfurls.
+ */
+export declare const CORTEX_AI_SEO_METADATA_LENGTH_BUDGETS: {
+    readonly metaDescription: 160;
+    readonly metaTitle: 60;
+    readonly ogDescription: 200;
+    readonly ogTitle: 88;
+};
+/**
+ * How much page copy we are willing to ship to the model. Long-form posts can run
+ * to tens of thousands of characters, and the leading paragraphs carry almost all
+ * of the signal a title and description need. Truncating here keeps a single call
+ * inside the context window of even the smallest free fallback model, keeps the
+ * request cheap, and — because the free tail is rate-limited by tokens per minute
+ * as well as by requests — materially improves the odds that the first attempt
+ * succeeds instead of falling through the whole registry.
+ */
+export declare const CORTEX_AI_SEO_METADATA_CONTENT_BUDGET = 6000;
+/**
+ * Shorten `value` to at most `maxLength` characters without splitting a word.
+ *
+ * The rule is: prefer the last whitespace inside the budget, because that is the
+ * only cut point guaranteed to leave a complete word behind. When there is no
+ * whitespace inside the budget at all the input is a single long token — a URL, a
+ * German compound noun, a CJK sentence written without spaces — and a hard cut at
+ * exactly `maxLength` is the only option that both respects the budget and returns
+ * something useful, so we take it rather than returning an over-budget string or an
+ * empty one.
+ *
+ * This is exported because it is the piece most likely to be subtly wrong and the
+ * piece the unit tests target directly. `ai-vision.ts` imports it rather than
+ * defining its own copy, both so the alt-text and metadata paths cannot drift apart
+ * in how they shorten a string, and because two modules exporting the same name
+ * through the `export *` barrel in src/index.ts would collide.
+ */
+export declare function truncateOnWordBoundary(value: string, maxLength: number): string;
+/**
+ * Pull the outermost balanced JSON object out of a model response.
+ *
+ * We ask for bare JSON and most models comply, but "most" is not "all": the same
+ * prompt can come back wrapped in ```json fences, prefixed with "Here is the
+ * metadata:", or followed by an unsolicited explanation of the choices made.
+ * Rather than tighten the prompt forever, we tolerate all three shapes here.
+ *
+ * The scan is string-aware on purpose. A naive `indexOf('{')` / `lastIndexOf('}')`
+ * pair breaks the moment a description legitimately contains a brace — and copy
+ * about templating, CSS, or code frequently does. Tracking whether we are inside a
+ * JSON string literal, and honouring backslash escapes within it, means braces in
+ * content are ignored while braces in structure are counted. Nested objects fall out
+ * of the same depth counter for free.
+ *
+ * Returns `null` rather than throwing so the caller can decide that "no JSON here"
+ * is a retryable attempt failure instead of a hard error.
+ */
+export declare function extractJsonObject(value: string): string | null;
+export interface GenerateSeoMetadataParams {
+    abortSignal?: AbortSignal;
+    apiKey?: string | null;
+    content: string;
+    focusKeyword?: string | null;
+    locale?: string | null;
+    modelId?: string | null;
+    siteTitle?: string | null;
+    title?: string | null;
+}
+export interface GenerateSeoMetadataResult {
+    attempts: number;
+    credentialSource: string;
+    metaDescription: string;
+    metaTitle: string;
+    modelId: string;
+    ogDescription: string;
+    ogTitle: string;
+}
+/**
+ * Generate meta and Open Graph copy for a page in a single model call.
+ *
+ * This uses `generateText` plus our own JSON extraction rather than
+ * `generateObject`, following the precedent set by ai-block-generation.ts and for
+ * the reason recorded in ai-cortex-widget-builder.ts: a provider-side JSON schema
+ * (`response_format: json_schema`) is rejected outright by several models reachable
+ * through OpenRouter, and most of the free fallback tier does not advertise
+ * `structured_outputs` at all. Describing the shape in the prompt and validating it
+ * ourselves with Zod is the only approach that works across the entire routing
+ * chain, and it degrades gracefully — a model that wraps its JSON in fences still
+ * succeeds instead of erroring inside the SDK.
+ *
+ * Routing goes through the ordinary text policy, because every field here is text
+ * produced from text. Only the vision path in ai-vision.ts needs a policy of its
+ * own.
+ */
+export declare function generateCortexAiSeoMetadata(params: GenerateSeoMetadataParams): Promise<GenerateSeoMetadataResult>;

package/lib/ai-seo-metadata.es.js

@@ -0,0 +1,193 @@
+import { generateText as p } from "ai";
+import { buildCortexAiRoutingPolicy as T, runWithCortexAiModelFallback as h, omitUnsupportedCortexAiModelOptions as S, getHttpStatusCode as y, isOpenRouterRecoverableRoutingError as E } from "./ai-model-registry.es.js";
+import "./zod-config.es.js";
+import { z as l } from "zod";
+const b = "Cortex AI SEO metadata generation can only be imported from server-side code.";
+function O() {
+  if (!(typeof window > "u"))
+    throw new Error(b);
+}
+const w = l.strictObject({
+  metaDescription: l.string().trim().min(1),
+  metaTitle: l.string().trim().min(1),
+  ogDescription: l.string().trim().min(1),
+  ogTitle: l.string().trim().min(1)
+}), c = {
+  metaDescription: 160,
+  metaTitle: 60,
+  ogDescription: 200,
+  ogTitle: 88
+}, A = 6e3, D = 6e4, v = /[\s.,;:!?‐-―\-/\\|&+*_"'([{·•]+$/;
+function d(e, t) {
+  const n = e.trim();
+  if (t <= 0)
+    return "";
+  if (n.length <= t)
+    return n;
+  const o = n.slice(0, t), i = o.search(/\s\S*$/);
+  return (i > 0 ? o.slice(0, i) : o).replace(v, "").trim();
+}
+function x(e) {
+  const t = e.replace(/```[a-zA-Z0-9]*/g, ""), n = t.indexOf("{");
+  if (n === -1)
+    return null;
+  let o = 0, i = !1, r = !1;
+  for (let s = n; s < t.length; s++) {
+    const a = t[s];
+    if (i) {
+      r ? r = !1 : a === "\\" ? r = !0 : a === '"' && (i = !1);
+      continue;
+    }
+    if (a === '"') {
+      i = !0;
+      continue;
+    }
+    if (a === "{") {
+      o++;
+      continue;
+    }
+    if (a === "}" && (o--, o === 0))
+      return t.slice(n, s + 1);
+  }
+  return null;
+}
+function _() {
+  const e = c;
+  return [
+    "You are NextBlock Cortex AI, an SEO metadata writer for a content management system.",
+    "Return ONLY a single JSON object. No markdown fences, no commentary, no explanation, no trailing prose.",
+    'The object must have exactly these four keys, all strings, all non-empty: "metaDescription", "metaTitle", "ogDescription", "ogTitle".',
+    "Do not add any other key.",
+    `metaTitle must be at most ${e.metaTitle} characters and read as a search-result headline for this specific page.`,
+    `metaDescription must be at most ${e.metaDescription} characters, summarise what the page actually delivers, and end as a complete thought.`,
+    `ogTitle must be at most ${e.ogTitle} characters and may be slightly more conversational than metaTitle, because it is read on a social card rather than in a results list.`,
+    `ogDescription must be at most ${e.ogDescription} characters and should invite a click without over-promising.`,
+    "Write plain text. No emoji, no surrounding quotation marks, no HTML, no markdown.",
+    "Describe only what the supplied content actually contains. Never invent statistics, prices, dates, awards, or claims that are not in the content.",
+    "Never keyword-stuff, never repeat the focus keyword more than twice across all four fields, and never pad a field to reach its character budget."
+  ].join(" ");
+}
+function C(e) {
+  return [
+    "Write SEO metadata for the following page.",
+    e.title ? `Page title: ${e.title}` : null,
+    e.siteTitle ? `Site name: ${e.siteTitle}. Do not append the site name to metaTitle; the site appends it separately.` : null,
+    e.focusKeyword ? `Focus keyword: ${e.focusKeyword}. Use it naturally in metaTitle and metaDescription, at most once each.` : null,
+    e.locale ? `Write every field in this locale: ${e.locale}. Match its conventions for capitalisation and punctuation.` : null,
+    `Page content:
+${e.content}`
+  ].filter(Boolean).join(`
+
+`);
+}
+function I(e) {
+  const t = x(e);
+  if (!t)
+    throw new Error("Cortex AI returned no JSON object for the SEO metadata request.");
+  let n;
+  try {
+    n = JSON.parse(t);
+  } catch (i) {
+    throw new Error(
+      `Cortex AI returned invalid JSON for the SEO metadata request: ${i instanceof Error ? i.message : String(i)}`
+    );
+  }
+  const o = w.parse(n);
+  return {
+    metaDescription: d(
+      o.metaDescription,
+      c.metaDescription
+    ),
+    metaTitle: d(
+      o.metaTitle,
+      c.metaTitle
+    ),
+    ogDescription: d(
+      o.ogDescription,
+      c.ogDescription
+    ),
+    ogTitle: d(
+      o.ogTitle,
+      c.ogTitle
+    )
+  };
+}
+function R(e) {
+  const t = y(e);
+  if (t === 401 || t === 402 || t === 403)
+    return !1;
+  if (E(e) || t && t >= 500)
+    return !0;
+  const n = e instanceof Error ? e.message : String(e);
+  return /NoContentGenerated|No content generated|Provider returned error|no JSON object|invalid JSON|invalid_type|too_small|unrecognized_keys|Invalid input|aborted|abort|timeout|timed out/i.test(
+    n
+  );
+}
+async function j(e) {
+  O();
+  const t = d(e.content, A);
+  if (!t)
+    throw new Error("Cortex AI SEO metadata generation requires non-empty page content.");
+  const { createCortexAiOpenRouterClient: n } = await import("./ai-client.es.js"), o = await n({
+    apiKey: e.apiKey || void 0
+  }), i = T({
+    credentialSource: o.credentialSource,
+    requestedModelId: e.modelId,
+    selectedModel: o.modelSelection
+  }), r = await h({
+    modelIds: i.modelIds,
+    shouldRetry: R,
+    execute: async (s) => {
+      const a = new AbortController(), m = setTimeout(
+        () => a.abort(),
+        D
+      ), u = () => a.abort();
+      e.abortSignal?.addEventListener("abort", u, { once: !0 }), e.abortSignal?.aborted && a.abort();
+      try {
+        const g = S(
+          {
+            abortSignal: a.signal,
+            maxOutputTokens: 700,
+            maxRetries: 0,
+            prompt: C({
+              content: t,
+              focusKeyword: e.focusKeyword?.trim() || null,
+              locale: e.locale?.trim() || null,
+              siteTitle: e.siteTitle?.trim() || null,
+              title: e.title?.trim() || null
+            }),
+            system: _(),
+            temperature: 0.3
+          },
+          {
+            modelId: s,
+            modelSelection: i.modelSelection
+          }
+        ), f = await p({
+          ...g,
+          model: o.model(s)
+        });
+        return I(f.text);
+      } finally {
+        clearTimeout(m), e.abortSignal?.removeEventListener("abort", u);
+      }
+    }
+  });
+  return {
+    attempts: r.attempts.length,
+    credentialSource: o.credentialSource,
+    metaDescription: r.result.metaDescription,
+    metaTitle: r.result.metaTitle,
+    modelId: r.modelId,
+    ogDescription: r.result.ogDescription,
+    ogTitle: r.result.ogTitle
+  };
+}
+export {
+  A as CORTEX_AI_SEO_METADATA_CONTENT_BUDGET,
+  c as CORTEX_AI_SEO_METADATA_LENGTH_BUDGETS,
+  w as cortexAiSeoMetadataOutputSchema,
+  x as extractJsonObject,
+  j as generateCortexAiSeoMetadata,
+  d as truncateOnWordBoundary
+};

package/lib/ai-vision.cjs.js

@@ -0,0 +1,3 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const C=require("ai"),l=require("./ai-model-registry.cjs.js"),R=require("./ai-seo-metadata.cjs.js"),S="Cortex AI vision generation can only be imported from server-side code.";function L(){if(!(typeof window>"u"))throw new Error(S)}const d=["google/gemma-4-31b-it:free","google/gemma-4-26b-a4b-it:free","google/gemini-2.5-flash-lite","qwen/qwen3-vl-32b-instruct","openai/gpt-4o-mini","google/gemini-2.5-flash"],O=[/(?:^|\/)[^/]*-vl(?:[-:]|$)/i,/vision/i,/(?:^|\/)gemini-/i,/(?:^|\/)gemma-[3-9]/i,/(?:^|\/)gpt-(?:4o|4\.1|5)/i,/(?:^|\/)claude-/i,/(?:^|\/)llama-4/i,/(?:^|\/)pixtral/i,/(?:^|\/)mistral-(?:small|medium|large)-3/i,/(?:^|\/)nova-(?:lite|pro|premier)/i],u=125,p={max:1e3,min:20},M=6e4,T=new Set(['"',"'","«","»","‘","’","‚","“","”","„","`"]),v=/^(?:here(?:'s|’s| is)\s+)?(?:the\s+)?alt(?:[-\s]?text)?\s*[:–—-]\s*/i,N=/^(?:this\s+is\s+)?(?:an?|the)?\s*(?:image|photo|photograph|picture|pic|graphic|illustration|rendering|render)\s+(?:of|showing|depicting|that\s+shows)\s+/i;function X(e){const o=new Set,t=[];for(const n of e){const r=n?.trim();!r||o.has(r)||(o.add(r),t.push(r))}return t}function A(e){const o=e?.trim();return o?d.includes(o)?!0:O.some(t=>t.test(o)):!1}function _(e){const o=e.requestedModelId?.trim()||null,t=e.selectedModel?.modelId?.trim()||null,n=e.credentialSource!=="env"&&t&&A(t)?t:null;return{modelIds:X([o,n,...d])}}function f(e){let o=e.trim();for(;o.length>=2&&T.has(o[0])&&T.has(o[o.length-1]);)o=o.slice(1,-1).trim();return o}function U(e){return!e.endsWith(".")||e.endsWith("...")||e.endsWith("…")?e:(e.match(/[.!?](?=\s|$)/g)||[]).length===1?e.slice(0,-1).trimEnd():e}function b(e,o=u){let t=e.replace(/\s+/g," ").trim(),n=!1;for(let r=0;r<2;r++){t=f(t);const a=t.replace(v,"");a!==t&&(t=a.trim(),n=!0),t=f(t);const i=t.replace(N,"");i!==t&&(t=i.trim(),n=!0)}return n&&t&&(t=t.charAt(0).toUpperCase()+t.slice(1)),R.truncateOnWordBoundary(U(t),o)}function q(e){const o=e.trim();if(!o)throw new Error("Cortex AI alt text generation requires an image URL.");let t;try{t=new URL(o)}catch{throw new Error(`Cortex AI alt text generation requires an absolute http(s) image URL, received "${o}". A storage key or site-relative path must be resolved to a publicly fetchable URL first, because the model provider downloads the image server-side.`)}if(t.protocol!=="http:"&&t.protocol!=="https:")throw new Error(`Cortex AI alt text generation requires an http(s) image URL, received the "${t.protocol}" scheme.`);return t}function P(e){return["You are NextBlock Cortex AI, writing the alt attribute for an image on a website.","You are writing for a person using a screen reader who cannot see the image at all.","Describe only what is visibly present in the image: subjects, their appearance, what they are doing, the setting, and any text that appears in the image.","Never state or guess anything you cannot see — no names, no locations, no dates, no brands, no emotions, and no backstory unless they are legible in the image itself.",`Write one short factual description of at most ${e} characters.`,'Do not begin with "image of", "photo of", "picture of", "graphic of", or any similar phrase; the screen reader already announces that this is an image.','Do not add a label such as "Alt text:" and do not wrap the description in quotation marks.',"Do not keyword-stuff, do not list search terms, and do not repeat a word for emphasis.","Return plain text only: one line, no markdown, no HTML, no JSON, no commentary, no alternatives to choose between.","If surrounding page context is supplied, use it ONLY to disambiguate what you can already see — for example to choose the right word for an object or to know which product is pictured. Never use it to add detail that is not visible in the image."].join(" ")}function D(e){return[`Write the alt attribute for this image, at most ${e.maxLength} characters.`,e.context?`Surrounding page context, for disambiguation only: ${e.context}`:null].filter(Boolean).join(`
+
+`)}function V(e){const o=l.getHttpStatusCode(e);if(o===401||o===402||o===403)return!1;if(l.isOpenRouterRecoverableRoutingError(e)||o&&o>=500)return!0;const t=e instanceof Error?e.message:String(e);return/NoContentGenerated|No content generated|Provider returned error|empty alt text|image|modality|multimodal|not support|unsupported|aborted|abort|timeout|timed out/i.test(t)}async function k(e){L();const o=q(e.imageUrl),t=Number.isFinite(e.maxLength)?Math.round(e.maxLength):u,n=Math.min(p.max,Math.max(p.min,t)),r=e.context?.replace(/\s+/g," ").trim()||null,{createCortexAiOpenRouterClient:a}=await Promise.resolve().then(()=>require("./ai-client.cjs.js")),i=await a({apiKey:e.apiKey||void 0}),x=_({credentialSource:i.credentialSource,requestedModelId:e.modelId,selectedModel:i.modelSelection}),E=[{content:[{text:D({context:r,maxLength:n}),type:"text"},{image:o,type:"image"}],role:"user"}],c=await l.runWithCortexAiModelFallback({modelIds:x.modelIds,shouldRetry:V,execute:async m=>{const s=new AbortController,I=setTimeout(()=>s.abort(),M),g=()=>s.abort();e.abortSignal?.addEventListener("abort",g,{once:!0}),e.abortSignal?.aborted&&s.abort();try{const w=l.omitUnsupportedCortexAiModelOptions({abortSignal:s.signal,maxOutputTokens:400,maxRetries:0,messages:E,system:P(n),temperature:.2},{modelId:m,modelSelection:i.modelSelection}),y=await C.generateText({...w,model:i.model(m)}),h=b(y.text,n);if(!h)throw new Error("Cortex AI returned empty alt text.");return h}finally{clearTimeout(I),e.abortSignal?.removeEventListener("abort",g)}}});return{altText:c.result,attempts:c.attempts.length,credentialSource:i.credentialSource,modelId:c.modelId}}exports.CORTEX_AI_DEFAULT_ALT_TEXT_MAX_LENGTH=u;exports.CORTEX_AI_VISION_MODEL_FALLBACK_REGISTRY=d;exports.buildCortexAiVisionRoutingPolicy=_;exports.generateCortexAiAltText=k;exports.isKnownVisionCapableCortexAiModelId=A;exports.normalizeGeneratedAltText=b;

package/lib/ai-vision.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Ordered list of OpenRouter model ids that genuinely accept image input.
+ *
+ * This list exists precisely BECAUSE the general-purpose fallback registry cannot
+ * be reused here. `CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY` in ai-model-registry.ts
+ * is a text-only tier, and `buildCortexAiRoutingPolicy` actively DISCARDS a
+ * requested model id whenever the credential came from the shared environment key
+ * — it records the request in `ignoredRequestedModelId` and routes to that
+ * text-only tier anyway. That is the right behaviour for text (it stops a caller
+ * spending the house key on an expensive model) but it is fatal for vision: the
+ * call would be dispatched to a model that cannot see the image, and the model
+ * would either error on the unsupported content part or, worse, hallucinate a
+ * description of an image it never received. Hence a separate registry and a
+ * separate policy below.
+ *
+ * The order is: free tier first so an install with no billing set up still gets
+ * working alt text, then paid models in ascending cost, ending with the most
+ * capable one for images the cheaper models fumble.
+ *
+ * - `google/gemma-4-31b-it:free` — the strongest general-purpose free multimodal
+ *   instruct model on OpenRouter; text output, 262k context, no expiry date set.
+ * - `google/gemma-4-26b-a4b-it:free` — its sparse sibling. A second free entry
+ *   matters more than a marginally better one, because the free tier is rate
+ *   limited per model and the first choice is the one everybody else hits too.
+ * - `google/gemini-2.5-flash-lite` — the cheapest reliable paid vision endpoint,
+ *   and the first entry that is not subject to free-tier throttling.
+ * - `qwen/qwen3-vl-32b-instruct` — a dedicated vision-language model; a useful
+ *   second opinion because it fails on a different set of images than Gemini does.
+ * - `openai/gpt-4o-mini` — the most battle-tested vision endpoint available here,
+ *   and the id least likely to be retired without warning.
+ * - `google/gemini-2.5-flash` — the quality backstop for dense screenshots,
+ *   diagrams, and photographs with small but load-bearing detail.
+ *
+ * This list MUST be revisited as OpenRouter's catalog changes. Free-tier ids in
+ * particular churn constantly: they are added, throttled, given an
+ * `expiration_date`, or silently promoted to paid, at which point a request to them
+ * fails with a message `isOpenRouterRecoverableRoutingError` recognises and the
+ * chain simply falls through to the next entry. That fallback keeps the feature
+ * working, but a registry whose whole free head has expired means every alt-text
+ * generation quietly starts costing money — so treat a persistently paid-only
+ * outcome as a signal to refresh this list against
+ * `https://openrouter.ai/api/v1/models`, filtering on
+ * `architecture.input_modalities` containing `image`.
+ */
+export declare const CORTEX_AI_VISION_MODEL_FALLBACK_REGISTRY: readonly string[];
+/**
+ * Default alt-text budget. 125 characters is the long-standing practical ceiling:
+ * older screen readers truncated an `alt` attribute around 125-150 characters, and
+ * anything longer is a sign the image is really conveying content that belongs in a
+ * caption or a long description instead.
+ */
+export declare const CORTEX_AI_DEFAULT_ALT_TEXT_MAX_LENGTH = 125;
+/**
+ * Whether we are prepared to send an image to this model id. Registry membership is
+ * the certain case; the patterns above cover an admin-selected model from a family
+ * we know to be multimodal throughout.
+ */
+export declare function isKnownVisionCapableCortexAiModelId(modelId: string | null | undefined): boolean;
+/**
+ * Build the model chain for a vision call.
+ *
+ * Three rules, each of which differs from the text policy for a reason:
+ *
+ * 1. An explicitly requested model is HONOURED regardless of `credentialSource`.
+ *    The text policy drops a requested id on an `env` credential so a caller cannot
+ *    spend the shared house key on a model the operator did not choose. Applying
+ *    that rule here would silently route an image to a text-only model, which is a
+ *    correctness failure rather than a cost control. A caller that names a vision
+ *    model is making a deliberate choice, and the cost ceiling is already bounded
+ *    by the tiny output budget an alt-text call uses.
+ *
+ * 2. The admin's stored selection participates only when it is `credentialSource`
+ *    'stored' or 'manual' — i.e. the operator's own key, exactly as the text policy
+ *    treats it — AND the id is recognisably vision-capable. An operator who picked,
+ *    say, a text-only reasoning model for the page builder should not have that
+ *    choice quietly break every alt-text generation.
+ *
+ * 3. The vision registry is always appended as a tail, never conditionally. It is
+ *    the safety net: whatever the first two rules produce, there is always a known
+ *    multimodal model behind it.
+ *
+ * De-duplication preserves first-occurrence order, so a requested model that also
+ * appears in the registry stays at the head instead of being tried twice.
+ */
+export declare function buildCortexAiVisionRoutingPolicy(params: {
+    credentialSource: string;
+    requestedModelId?: string | null;
+    selectedModel?: {
+        modelId: string;
+    } | null;
+}): {
+    modelIds: string[];
+};
+/**
+ * Turn whatever the model said into an `alt` attribute value.
+ *
+ * Exported as a named function so the whole post-processing contract can be unit
+ * tested without a network call — this is the part of the vision path most likely
+ * to regress, because every change here is a response to some specific model's
+ * verbal tic and it is easy to break an earlier fix while adding the next one.
+ *
+ * The steps run in this order for a reason: whitespace is collapsed first so a
+ * multi-line answer is matched by the single-line label patterns; quote stripping
+ * and preamble stripping then alternate, because `Alt text: "A grey cat."` needs
+ * both and either order alone leaves one of them behind.
+ */
+export declare function normalizeGeneratedAltText(raw: string, maxLength?: number): string;
+export interface GenerateAltTextParams {
+    abortSignal?: AbortSignal;
+    apiKey?: string | null;
+    context?: string | null;
+    imageUrl: string;
+    maxLength?: number;
+    modelId?: string | null;
+}
+export interface GenerateAltTextResult {
+    altText: string;
+    attempts: number;
+    credentialSource: string;
+    modelId: string;
+}
+/**
+ * Generate an `alt` attribute for an image by actually looking at it.
+ *
+ * The image is attached as an AI SDK v6 image content part inside a user message.
+ * Two consequences of that are worth knowing at the call site: the URL must be
+ * publicly fetchable from the server (the SDK downloads it and inlines base64
+ * rather than forwarding the link, because the provider is created without
+ * `supportedUrls`), and a very large source image inflates the request body on
+ * every attempt in the fallback chain. Passing a resized or CDN-transformed URL is
+ * therefore materially cheaper than passing the original upload.
+ */
+export declare function generateCortexAiAltText(params: GenerateAltTextParams): Promise<GenerateAltTextResult>;