@rudra-js/core 0.7.4 → 0.7.5

package/src/component-generator.ts

@@ -2,7 +2,6 @@ import { z } from 'zod';
 import {
   SPEC_VERSION,
   generatedSpecSchema,
-  type Block,
   type ComponentSpec,
   type DegradedReason,
   type GeneratedSpec,
@@ -12,12 +11,11 @@ import { buildFallbackSpec } from './fallback-component.js';
 import { buildPrompt } from './model-prompt.js';
 import type { ComponentProvider, TokenUsage } from './provider.js';
 import { bundleForShopper, capBlocks, placeableHeroSkus, reconcileSpec } from './reconciliation.js';
-import { selectProducts, type RankOrder, type ProductPick } from './product-selection.js';
+import { selectProducts, type RankOrder } from './product-selection.js';
 import { fitToShopper, type FittedSpec } from './fit-to-shopper.js';
 import { buildDigest, toCohortDigest, type SignalDigest } from './signal-digest.js';
 import {
   createMemorySpecCache,
-  cohortCacheKey,
   specCacheKey,
   type CachedSpec,
   type SpecCache,
@@ -31,11 +29,8 @@ import {
 export interface GenerationEvent {
   key: string | null;
   source: SpecSource;
-
   elapsedMs: number;
-
   calledModel: boolean;
-
   violations?: string[];
   usage?: TokenUsage;
   degradedReason?: DegradedReason;
@@ -45,23 +40,16 @@ export interface GenerationEvent {
 
 export interface ComponentGeneratorOptions {
   provider?: ComponentProvider | null;
-
   cache?: SpecCache;
-
   modelTimeoutMs?: number;
-
   cacheTimeoutMs?: number;
-
   generation?: 'cohort' | 'per-shopper';
-
   rank?: RankOrder;
-
   onEvent?: (event: GenerationEvent) => void;
 }
 
 export interface ComponentGenerator {
   generate(input: TrackingInputDraft): Promise<ComponentSpec>;
-
   generateDeterministic(input: TrackingInputDraft): ComponentSpec;
 }
 
@@ -98,23 +86,6 @@ async function withinBudget<T>(
   }
 }
 
-function createSingleFlight() {
-  const inFlight = new Map<string, Promise<ModelCall>>();
-
-  return {
-    isRunning: (key: string) => inFlight.has(key),
-
-    run(key: string, task: () => Promise<ModelCall>): Promise<ModelCall> {
-      const existing = inFlight.get(key);
-      if (existing) return existing;
-
-      const started = task().finally(() => inFlight.delete(key));
-      inFlight.set(key, started);
-      return started;
-    },
-  };
-}
-
 const cachedSpecSchema = z.object({
   spec: generatedSpecSchema,
   generatedAt: z.number(),
@@ -130,6 +101,40 @@ interface ModelCall {
   usage?: TokenUsage;
 }
 
+interface Settings {
+  options: ComponentGeneratorOptions;
+  provider: ComponentProvider | null;
+  cache: SpecCache;
+  generation: 'cohort' | 'per-shopper';
+  rank: RankOrder;
+  modelTimeoutMs: number;
+  cacheTimeoutMs: number;
+  inFlight: Map<string, Promise<ModelCall>>;
+}
+
+interface Run {
+  input: TrackingInput;
+  digest: SignalDigest;
+  promptDigest: SignalDigest;
+  startedAt: number;
+}
+
+interface Trace {
+  calledModel: boolean;
+  cache: CacheRead['outcome'];
+  usage: TokenUsage | undefined;
+  error?: unknown;
+}
+
+type Found =
+  | { spec: GeneratedSpec; generatedAt: number; source: 'cache' | 'llm'; trace: Trace }
+  | { failed: DegradedReason; trace: Trace };
+
+type EventDetails = Pick<
+  GenerationEvent,
+  'calledModel' | 'usage' | 'violations' | 'cache' | 'error'
+>;
+
 function fitCohortSpec(
   spec: GeneratedSpec,
   input: TrackingInput,
@@ -139,222 +144,220 @@ function fitCohortSpec(
   const picks = selectProducts(input, digest, { rank });
   const blocks = capBlocks(spec.blocks);
 
-  let hasBundleBlock = false;
-  const aboveBundle: Block[] = [];
-  for (const block of blocks) {
-    if (block.kind === 'bundle') {
-      hasBundleBlock = true;
-      break;
-    }
-    aboveBundle.push(block);
-  }
-  if (!hasBundleBlock) return fitToShopper(spec, picks, digest.maxItems);
+  const bundleAt = blocks.findIndex((block) => block.kind === 'bundle');
+  if (bundleAt === -1) return fitToShopper(spec, picks, digest.maxItems);
 
-  const chosen = bundleForShopper(input, digest, placeableHeroSkus(aboveBundle, input));
-  if (!chosen) return fitToShopper(spec, picks, digest.maxItems);
+  const heroesAbove = placeableHeroSkus(blocks.slice(0, bundleAt), input);
+  const bundle = bundleForShopper(input, digest, heroesAbove);
+  if (!bundle) return fitToShopper(spec, picks, digest.maxItems);
 
-  const spokenFor = new Set<string>(chosen.skus);
+  const spokenFor = new Set<string>(bundle.skus);
   for (const sku of placeableHeroSkus(blocks, input)) spokenFor.add(sku);
 
   const roomLeft = digest.maxItems - spokenFor.size;
-
   if (roomLeft <= 0) return fitToShopper(spec, picks, digest.maxItems);
 
-  const forGrid: ProductPick[] = [];
-  for (const pick of picks) {
-    if (!spokenFor.has(pick.product.sku)) forGrid.push(pick);
-  }
-
+  const forGrid = picks.filter((pick) => !spokenFor.has(pick.product.sku));
   return fitToShopper(spec, forGrid, roomLeft);
 }
 
 export function createComponentGenerator(
   options: ComponentGeneratorOptions = {},
 ): ComponentGenerator {
-  const provider = options.provider ?? null;
-  const cache = options.cache ?? createMemorySpecCache();
-  const generation = options.generation ?? 'cohort';
-  const rank = options.rank ?? 'signals';
-  const modelTimeoutMs = options.modelTimeoutMs ?? 1_500;
-  const cacheTimeoutMs = options.cacheTimeoutMs ?? 50;
-  const singleFlight = createSingleFlight();
-
-  const report = (event: GenerationEvent): void => {
-    if (!options.onEvent) return;
-    try {
-      options.onEvent(event);
-    } catch {}
+  const settings: Settings = {
+    options,
+    provider: options.provider ?? null,
+    cache: options.cache ?? createMemorySpecCache(),
+    generation: options.generation ?? 'cohort',
+    rank: options.rank ?? 'signals',
+    modelTimeoutMs: options.modelTimeoutMs ?? 1_500,
+    cacheTimeoutMs: options.cacheTimeoutMs ?? 50,
+    inFlight: new Map(),
   };
 
-  const buildDeterministic = (
-    input: TrackingInput,
-    digest: SignalDigest,
-    startedAt: number,
-    key: string | null,
-    degradedReason: DegradedReason,
-    modelCall: Pick<GenerationEvent, 'calledModel' | 'usage' | 'violations' | 'cache' | 'error'> = {
-      calledModel: false,
-    },
-  ): ComponentSpec => {
-    const finishedAt = Date.now();
-    report({
-      key,
-      source: 'fallback',
-      elapsedMs: finishedAt - startedAt,
-      ...modelCall,
-      degradedReason,
-    });
-
-    return {
-      ...buildFallbackSpec(input, digest, { rank }),
-      specVersion: SPEC_VERSION,
-      slot: digest.slot,
-      source: 'fallback',
-      generatedAt: finishedAt,
-      latencyMs: finishedAt - startedAt,
-      provider: null,
-      model: null,
-      degradedReason,
-    };
+  return {
+    generate: (draft) => generate(settings, draft),
+    generateDeterministic: (draft) => generateDeterministic(settings, draft),
   };
+}
 
-  const readCache = async (key: string): Promise<CacheRead> => {
-    try {
-      const stored = await withinBudget('cache read', cacheTimeoutMs, () => cache.get(key));
-      const parsed = cachedSpecSchema.safeParse(stored);
-      return parsed.success ? { outcome: 'hit', entry: parsed.data } : { outcome: 'miss' };
-    } catch (error) {
-      return { outcome: error instanceof TimeoutError ? 'timeout' : 'error' };
-    }
-  };
+async function generate(settings: Settings, draft: TrackingInputDraft): Promise<ComponentSpec> {
+  const run = startRun(settings, draft);
+  const provider = settings.provider;
+  if (!provider) return fallback(settings, run, null, 'no-provider');
+
+  const key = cacheKeyFor(provider, run);
+  const found = await findSpec(settings, provider, run, key);
+  if ('failed' in found)
+    return fallback(settings, run, key, found.failed, eventDetails(found.trace));
+
+  const reconciled = shapeForShopper(settings, run, found.spec);
+  const details = eventDetails(found.trace, reconciled.violations);
+  if (!reconciled.isUsable) return fallback(settings, run, key, 'unusable-on-serve', details);
+
+  const finishedAt = Date.now();
+  report(settings, {
+    key,
+    source: found.source,
+    elapsedMs: finishedAt - run.startedAt,
+    ...details,
+  });
 
-  const storeInBackground = (key: string, cached: CachedSpec): void => {
-    void Promise.resolve()
-      .then(() => cache.set(key, cached))
-      .catch(() => {});
+  return {
+    ...reconciled.spec,
+    specVersion: SPEC_VERSION,
+    slot: run.digest.slot,
+    source: found.source,
+    generatedAt: found.generatedAt,
+    latencyMs: finishedAt - run.startedAt,
+    provider: provider.name,
+    model: provider.model,
   };
+}
+
+function generateDeterministic(settings: Settings, draft: TrackingInputDraft): ComponentSpec {
+  return fallback(settings, startRun(settings, draft), null, 'requested');
+}
+
+function startRun(settings: Settings, draft: TrackingInputDraft): Run {
+  const startedAt = Date.now();
+  const input = parseTrackingInput(draft);
+  const digest = buildDigest(input);
+  const promptDigest = settings.generation === 'cohort' ? toCohortDigest(digest) : digest;
+  return { input, digest, promptDigest, startedAt };
+}
+
+function cacheKeyFor(provider: ComponentProvider, run: Run): string {
+  const identity = { name: provider.name, model: provider.model };
+  const skus = run.input.candidates.map((product) => product.sku);
+  return specCacheKey(run.promptDigest, skus, identity);
+}
+
+async function findSpec(
+  settings: Settings,
+  provider: ComponentProvider,
+  run: Run,
+  key: string,
+): Promise<Found> {
+  const read = await readCache(settings, key);
+  if (read.entry) {
+    const trace = { calledModel: false, cache: read.outcome, usage: undefined };
+    return { spec: read.entry.spec, generatedAt: read.entry.generatedAt, source: 'cache', trace };
+  }
 
-  const askModel = async (
-    active: ComponentProvider,
-    input: TrackingInput,
-    promptDigest: SignalDigest,
-  ): Promise<ModelCall> => {
-    const { system, user } = buildPrompt(input, promptDigest);
+  const calledModel = !settings.inFlight.has(key);
+  let call: ModelCall;
+  try {
+    call = await sharedCall(settings, key, () => askModel(settings, provider, run));
+  } catch (error) {
+    const failed = error instanceof TimeoutError ? 'timeout' : 'provider-error';
+    return { failed, trace: { calledModel, cache: read.outcome, usage: undefined, error } };
+  }
 
-    const result = await withinBudget('generation', modelTimeoutMs, (signal) =>
-      active.generate({ system, user, schema: generatedSpecSchema, signal }),
+  const trace = { calledModel, cache: read.outcome, usage: call.usage };
+  if (!call.spec) return { failed: 'invalid-generation', trace };
+
+  const generatedAt = Date.now();
+  if (calledModel) storeInBackground(settings, key, { spec: call.spec, generatedAt });
+  return { spec: call.spec, generatedAt, source: 'llm', trace };
+}
+
+async function readCache(settings: Settings, key: string): Promise<CacheRead> {
+  try {
+    const stored = await withinBudget('cache read', settings.cacheTimeoutMs, () =>
+      settings.cache.get(key),
     );
+    const parsed = cachedSpecSchema.safeParse(stored);
+    return parsed.success ? { outcome: 'hit', entry: parsed.data } : { outcome: 'miss' };
+  } catch (error) {
+    return { outcome: error instanceof TimeoutError ? 'timeout' : 'error' };
+  }
+}
+
+async function askModel(
+  settings: Settings,
+  provider: ComponentProvider,
+  run: Run,
+): Promise<ModelCall> {
+  const { system, user } = buildPrompt(run.input, run.promptDigest);
+  const result = await withinBudget('generation', settings.modelTimeoutMs, (signal) =>
+    provider.generate({ system, user, schema: generatedSpecSchema, signal }),
+  );
+  const parsed = generatedSpecSchema.safeParse(result.spec);
+  return {
+    spec: parsed.success ? parsed.data : null,
+    ...(result.usage ? { usage: result.usage } : {}),
+  };
+}
+
+function sharedCall(
+  settings: Settings,
+  key: string,
+  ask: () => Promise<ModelCall>,
+): Promise<ModelCall> {
+  const running = settings.inFlight.get(key);
+  if (running) return running;
+  const started = ask().finally(() => settings.inFlight.delete(key));
+  settings.inFlight.set(key, started);
+  return started;
+}
+
+function storeInBackground(settings: Settings, key: string, cached: CachedSpec): void {
+  void Promise.resolve()
+    .then(() => settings.cache.set(key, cached))
+    .catch(() => {});
+}
 
-    const parsed = generatedSpecSchema.safeParse(result.spec);
+function shapeForShopper(settings: Settings, run: Run, spec: GeneratedSpec) {
+  if (settings.generation !== 'cohort') {
+    return reconcileSpec(spec, run.input, run.digest, new Map<string, string>());
+  }
+  const fitted = fitCohortSpec(spec, run.input, run.digest, settings.rank);
+  return reconcileSpec(fitted.spec, run.input, run.digest, fitted.ourReasons);
+}
 
-    return {
-      spec: parsed.success ? parsed.data : null,
-      ...(result.usage ? { usage: result.usage } : {}),
-    };
+function fallback(
+  settings: Settings,
+  run: Run,
+  key: string | null,
+  degradedReason: DegradedReason,
+  details: EventDetails = { calledModel: false },
+): ComponentSpec {
+  const finishedAt = Date.now();
+  report(settings, {
+    key,
+    source: 'fallback',
+    elapsedMs: finishedAt - run.startedAt,
+    ...details,
+    degradedReason,
+  });
+
+  return {
+    ...buildFallbackSpec(run.input, run.digest, { rank: settings.rank }),
+    specVersion: SPEC_VERSION,
+    slot: run.digest.slot,
+    source: 'fallback',
+    generatedAt: finishedAt,
+    latencyMs: finishedAt - run.startedAt,
+    provider: null,
+    model: null,
+    degradedReason,
   };
+}
 
+function eventDetails(trace: Trace, violations?: string[]): EventDetails {
   return {
-    generateDeterministic(draft) {
-      const startedAt = Date.now();
-      const input = parseTrackingInput(draft);
-      return buildDeterministic(input, buildDigest(input), startedAt, null, 'requested');
-    },
-
-    async generate(draft) {
-      const startedAt = Date.now();
-
-      const input = parseTrackingInput(draft);
-      const digest = buildDigest(input);
-
-      if (!provider) {
-        return buildDeterministic(input, digest, startedAt, null, 'no-provider');
-      }
-
-      const identity = { name: provider.name, model: provider.model };
-      const candidateSkus = input.candidates.map((product) => product.sku);
-      const key =
-        generation === 'cohort'
-          ? cohortCacheKey(digest, candidateSkus, identity)
-          : specCacheKey(digest, candidateSkus, identity);
-
-      const read = await readCache(key);
-      const cached = read.entry;
-      let calledModel = false;
-      let answer: { spec: GeneratedSpec; usage?: TokenUsage };
-
-      let generatedAt: number;
-
-      if (cached) {
-        answer = { spec: cached.spec };
-        generatedAt = cached.generatedAt;
-      } else {
-        calledModel = !singleFlight.isRunning(key);
-
-        let call: ModelCall;
-        try {
-          call = await singleFlight.run(key, () =>
-            askModel(provider, input, generation === 'cohort' ? toCohortDigest(digest) : digest),
-          );
-        } catch (error) {
-          const reason = error instanceof TimeoutError ? 'timeout' : 'provider-error';
-          return buildDeterministic(input, digest, startedAt, key, reason, {
-            calledModel,
-            cache: read.outcome,
-            error,
-          });
-        }
-
-        if (!call.spec) {
-          return buildDeterministic(input, digest, startedAt, key, 'invalid-generation', {
-            calledModel,
-            cache: read.outcome,
-            ...(call.usage ? { usage: call.usage } : {}),
-          });
-        }
-
-        answer = { spec: call.spec, ...(call.usage ? { usage: call.usage } : {}) };
-        generatedAt = Date.now();
-
-        if (calledModel) storeInBackground(key, { spec: answer.spec, generatedAt });
-      }
-
-      const { spec: served, ourReasons } =
-        generation === 'cohort'
-          ? fitCohortSpec(answer.spec, input, digest, rank)
-          : { spec: answer.spec, ourReasons: new Map<string, string>() };
-
-      const reconciled = reconcileSpec(served, input, digest, ourReasons);
-      if (!reconciled.isUsable) {
-        return buildDeterministic(input, digest, startedAt, key, 'unusable-on-serve', {
-          calledModel,
-          cache: read.outcome,
-          violations: reconciled.violations,
-          ...(answer.usage ? { usage: answer.usage } : {}),
-        });
-      }
-
-      const finishedAt = Date.now();
-      const source: SpecSource = cached ? 'cache' : 'llm';
-      report({
-        key,
-        source,
-        elapsedMs: finishedAt - startedAt,
-        calledModel,
-        cache: read.outcome,
-        violations: reconciled.violations,
-        ...(answer.usage ? { usage: answer.usage } : {}),
-      });
-
-      return {
-        ...reconciled.spec,
-        specVersion: SPEC_VERSION,
-        slot: digest.slot,
-        source,
-        generatedAt,
-        latencyMs: finishedAt - startedAt,
-        provider: provider.name,
-        model: provider.model,
-      };
-    },
+    calledModel: trace.calledModel,
+    cache: trace.cache,
+    ...(violations ? { violations } : {}),
+    ...(trace.usage ? { usage: trace.usage } : {}),
+    ...('error' in trace ? { error: trace.error } : {}),
   };
 }
+
+function report(settings: Settings, event: GenerationEvent): void {
+  if (!settings.options.onEvent) return;
+  try {
+    settings.options.onEvent(event);
+  } catch {}
+}

package/src/component-spec.ts

@@ -8,25 +8,17 @@ export const EMPHASIS = ['normal', 'featured'] as const;
 
 export const RECOMMENDATION_BASES = [
   'similar_to_current',
-
   'most_viewed',
-
   'complements_cart',
-
   'complements_purchase',
-
   'liked_category',
-
   'popular',
 ] as const;
 
 export const productReferenceSchema = z.object({
   sku: z.string(),
-
   basis: z.enum(RECOMMENDATION_BASES),
-
   reason: z.string().nullable(),
-
   badge: z.string().nullable(),
   emphasis: z.enum(EMPHASIS),
 });
@@ -48,6 +40,10 @@ const gridBlockSchema = z.object({
   items: z.array(productReferenceSchema),
 });
 
+export function columnsFor(count: number, widest: 2 | 3 | 4): 2 | 3 | 4 {
+  return Math.min(widest, Math.max(2, count)) as 2 | 3 | 4;
+}
+
 const carouselBlockSchema = z.object({
   kind: z.literal('carousel'),
   title: z.string().nullable(),
@@ -72,7 +68,6 @@ const bundleBlockSchema = z.object({
   title: z.string().nullable(),
   body: z.string().nullable(),
   ctaLabel: z.string().nullable(),
-
   bundleId: z.string().nullable(),
 });
 
@@ -99,7 +94,6 @@ export const generatedSpecSchema = z.object({
   headline: z.string(),
   subheadline: z.string().nullable(),
   blocks: z.array(blockSchema),
-
   rationale: z.string(),
 });
 export type GeneratedSpec = z.infer<typeof generatedSpecSchema>;
@@ -121,15 +115,10 @@ export interface ComponentSpec extends GeneratedSpec {
   specVersion: typeof SPEC_VERSION;
   slot: string;
   source: SpecSource;
-
   generatedAt: number;
-
   latencyMs: number;
-
   provider: string | null;
-
   model: string | null;
-
   degradedReason?: DegradedReason;
 }
 

package/src/fallback-component.ts

@@ -1,6 +1,6 @@
-import type { GeneratedSpec, ProductReference } from './component-spec.js';
+import { columnsFor, type GeneratedSpec, type ProductReference } from './component-spec.js';
 import type { SignalDigest } from './signal-digest.js';
-import { selectProducts, type SelectOptions, type ProductPick } from './product-selection.js';
+import { selectProducts, type SelectOptions } from './product-selection.js';
 import type { TrackingInput } from './tracking-input.js';
 
 const MIN_PICKS_FOR_A_FEATURED_LEAD = 3;
@@ -19,22 +19,6 @@ function headlineFor(digest: SignalDigest): { headline: string; subheadline: str
   return { headline: 'You might also like', subheadline: null };
 }
 
-function columnsFor(itemCount: number): 2 | 3 | 4 {
-  if (itemCount >= 4) return 4;
-  if (itemCount === 3) return 3;
-  return 2;
-}
-
-function toProductReference(pick: ProductPick, index: number, total: number): ProductReference {
-  return {
-    sku: pick.product.sku,
-    basis: pick.basis,
-    reason: pick.reason,
-    badge: null,
-    emphasis: index === 0 && total >= MIN_PICKS_FOR_A_FEATURED_LEAD ? 'featured' : 'normal',
-  };
-}
-
 export function buildFallbackSpec(
   input: TrackingInput,
   digest: SignalDigest,
@@ -42,7 +26,14 @@ export function buildFallbackSpec(
 ): GeneratedSpec {
   const picks = selectProducts(input, digest, options).slice(0, digest.maxItems);
   const { headline, subheadline } = headlineFor(digest);
-  const items = picks.map((pick, index) => toProductReference(pick, index, picks.length));
+  const isLeadFeatured = picks.length >= MIN_PICKS_FOR_A_FEATURED_LEAD;
+  const items: ProductReference[] = picks.map((pick, index) => ({
+    sku: pick.product.sku,
+    basis: pick.basis,
+    reason: pick.reason,
+    badge: null,
+    emphasis: index === 0 && isLeadFeatured ? 'featured' : 'normal',
+  }));
 
   return {
     tone: 'neutral',
@@ -51,7 +42,7 @@ export function buildFallbackSpec(
     blocks:
       items.length === 0
         ? []
-        : [{ kind: 'grid', title: null, columns: columnsFor(items.length), items }],
+        : [{ kind: 'grid', title: null, columns: columnsFor(items.length, 4), items }],
     rationale: digest.isColdStart
       ? 'Deterministic: no behavioural signals, ranked by rating and stock.'
       : 'Deterministic: ranked by category affinity, revisit, rating and tag overlap.',