@cherserg/ai-engine

@cherserg/ai-engine is a TypeScript library for generating landing page structure, block content, and design theme tokens with a Mastra workflow.

The public entry point is LandingGeneratorWorkflow.

Installation

npm install @cherserg/ai-engine

Runtime requirements

• Node.js: >=22.13.0
• Runtime: server-side only
• API key: pass an OpenAI-compatible API key through WorkflowConfig.apiKey

Do not use this package directly in browser/client-side code because LandingGeneratorWorkflow receives an API key.

Quick start

import { LandingGeneratorWorkflow } from "@cherserg/ai-engine";

const workflow = new LandingGeneratorWorkflow({
  apiKey: process.env.OPENAI_API_KEY!,
  blocksCatalog: [
    {
      id: "hero",
      description: "Main landing page hero section",
      schema: {
        type: "object",
        properties: {
          title: { type: "string" },
          subtitle: { type: "string" },
        },
        required: ["title", "subtitle"],
      },
    },
  ],
  designTokens: {
    allowedPalettes: ["light", "dark"],
    allowedFonts: ["sans", "serif"],
  },
});

const result = await workflow.execute({
  initialPrompt: "Generate a landing page for a SaaS CRM product",
});

Public exports

export { LandingGeneratorWorkflow } from "@cherserg/ai-engine";
export type {
  LandingContext,
  WorkflowConfig,
  WorkflowInput,
  WorkflowOutput,
} from "@cherserg/ai-engine";

Use only public exports from @cherserg/ai-engine. Do not import internal files from dist, src, or src/mastra.

Configuration contract

type WorkflowConfig = {
  apiKey: string;
  blocksCatalog: {
    id: string;
    description: string;
    schema: unknown;
  }[];
  designTokens: {
    allowedPalettes: string[];
    allowedFonts: string[];
  };
};

Input contract

type WorkflowInput = {
  initialPrompt: string;
};

Output contract

type WorkflowOutput = {
  layout: string[];
  theme: {
    paletteId: string;
    fontStyleId: string;
    density: "compact" | "comfortable" | "spacious";
  };
  blocksContent: {
    blockId: string;
    data: Record<string, string | number | boolean | string[]>;
  }[];
};

How API key injection works

LandingGeneratorWorkflow creates runtime agents per workflow instance. The constructor receives WorkflowConfig.apiKey, builds Mastra model configs, and passes them to the agents.

This means each LandingGeneratorWorkflow instance can use its own API key.

const workflowA = new LandingGeneratorWorkflow({
  apiKey: userAOpenAiKey,
  blocksCatalog,
  designTokens,
});

const workflowB = new LandingGeneratorWorkflow({
  apiKey: userBOpenAiKey,
  blocksCatalog,
  designTokens,
});

Documentation

• Detailed workflow guide: docs/landing-generator.md
• Integration guide for consuming projects: docs/using-as-library.md

Development

npm run check
npm run build
npm run dev

npm run dev starts Mastra Studio at http://localhost:4111.