createComponentGenerator

import { createComponentGenerator } from '@rudra-js/core';

Call createComponentGenerator once on your server to get a generator. Its generate method turns one page view into a block for RudraComponent to render.

createComponentGenerator(options?: ComponentGeneratorOptions) => ComponentGenerator

Reference

createComponentGenerator(options?)

Parameters

• optionsoptional: Settings for the generator. Each one has a default, so you can leave this out.
  • provideroptional: The model to call, such as createAnthropicProvider or your own ComponentProvider. Defaults to null, which calls no model and bills nothing.
  • cacheoptional: Where the model's answers are kept between requests. Defaults to createMemorySpecCache(). Pass createNullSpecCache() to keep nothing.
  • modelTimeoutMsoptional: How long the model gets to answer, in milliseconds. Defaults to 1500. Past that, core cancels the call and gives you the block core builds without a model.
  • cacheTimeoutMsoptional: How long a cache read gets, in milliseconds. Defaults to 50. Past that, the request carries on as if the cache were empty.
  • generationoptional: Defaults to 'cohort'. Shoppers in the same cohort share the layout and copy the model wrote. Core fills in each shopper's own products. With 'per-shopper', the model writes a block for every shopper and picks the products too.
  • rankoptional: How core orders the products. 'signals', the default, orders them by the shopper's signals. 'given' keeps the order you sent. It applies in 'cohort' mode and to the block core builds without a model. In 'per-shopper' mode the model picks the order.
  • onEventoptional: Called once each time the generator builds a block, with a report on how it went. If your function throws, core ignores the error.
    • key: The cache key this request used. It is null when the generator has no provider, and for generateDeterministic. A store with delete can drop one bad entry by this key.
    • source: 'llm' when the model answered this request. 'cache' when an earlier answer came from the cache. 'fallback' when core built the block without the model.
    • elapsedMs: How long the request took, in milliseconds.
    • calledModel: true when this request started a model call. A request that joined a call already running for the same key gets false.
    • violationsoptional: What core took out of the model's block before serving it. Each one is a string, such as 'empty-block:grid'. They can name products the shopper bought, disliked or has in the basket, so treat logs of them as personal data.
    • usageoptional: The token counts the provider reported. Requests that joined a running call carry the same usage, so add it up only where calledModel is true.
    • degradedReasonoptional: Why core built the block without the model. It is set when source is 'fallback'.
      • 'no-provider': The generator has no provider.
      • 'provider-error': The provider threw.
      • 'timeout': The model took longer than modelTimeoutMs.
      • 'invalid-generation': The model's answer didn't fit the schema.
      • 'unusable-on-serve': Core's checks left no headline or no product to show.
      • 'requested': You called generateDeterministic.
    • erroroptional: What was thrown, when degradedReason is 'provider-error' or 'timeout'.
    • cacheoptional: How the cache read went: 'hit', 'miss', 'error' or 'timeout'. It is missing when no cache was read, as with no provider.

Returns

A ComponentGenerator object with the two methods below.

Caveats

• Create one generator and reuse it for every request. Its default cache and its list of model calls in progress live inside it. A new generator starts with neither.
• generate never rejects because of the model. When the model times out, fails or gives an answer core can't use, you get the block core builds without a model.
• Input that fails parseTrackingInput makes generate reject and generateDeterministic throw. Neither reports an event.

Usage

import { createComponentGenerator, parseTrackingInput, type Product } from '@rudra-js/core';

const generator = createComponentGenerator();

export async function recommendationsFor(shopperId: string, sku: string, catalog: Product[]) {
  const input = parseTrackingInput({
    user: { id: shopperId },
    context: { surface: 'pdp', currentSku: sku },
    candidates: catalog,
  });
  const spec = await generator.generate(input);
  return { spec, products: input.candidates };
}

import { createAnthropicProvider } from '@rudra-js/anthropic';
import { createComponentGenerator } from '@rudra-js/core';

const provider = createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! });

export const generator = createComponentGenerator({ provider });

import { createAnthropicProvider } from '@rudra-js/anthropic';
import { createComponentGenerator } from '@rudra-js/core';

export const generator = createComponentGenerator({
  provider: createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  onEvent(event) {
    switch (event.source) {
      case 'llm':
        console.log(`The model answered in ${event.elapsedMs}ms`);
        break;
      case 'cache':
        console.log('An earlier answer came from the cache');
        break;
      case 'fallback':
        console.warn('Built without the model:', event.degradedReason, event.error);
        break;
    }
  },
});

Troubleshooting

import { createAnthropicProvider } from '@rudra-js/anthropic';
import { createComponentGenerator, type TrackingInputDraft } from '@rudra-js/core';

const provider = createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! });

// wrong
export async function slowRecommendations(input: TrackingInputDraft) {
  const generator = createComponentGenerator({ provider });
  return generator.generate(input);
}

// right
const generator = createComponentGenerator({ provider });

export async function recommendations(input: TrackingInputDraft) {
  return generator.generate(input);
}

Source on GitHub@rudra-js/core on npm