Object Generation (ObjectGenerator)

An ObjectGenerator step creates structured JSON data via LLMs. Whether you need to generate lists of items, complex nested objects, or single data entries, ObjectGenerator can be configured to produce exactly the schema you define.

For object generation, we only use LLMs capable of strictly adhering to defined schemas.

Use Cases:

• Generating product descriptions with structured fields.
• Creating recipe objects (as in the “recipe flow” example) with ingredients, steps, times, etc.
• Building any kind of custom JSON for integration with other steps or as a final result (like text for prompts, or data for transformations).

Step Definition

In your Flow’s steps array, add something like:

{
  id: 'myObjectGeneratorStep',
  type: 'ObjectGenerator',
  parameters: {
    description: 'You are a helpful AI that produces JSON data about X...',
    schema: {
      type: 'object',
      properties: {
        title: { type: 'string' },
        items: {
          type: 'array',
          items: {
            type: 'string',
          },
        },
      },
    },
    input: '$.input.myTopic',
    amount: 10,
    creativity: 15,
  },
}

Parameters

• id: Unique identifier for this step.
• type: Must be ObjectGenerator.

• If amount > 1, it returns an object with a key “list” containing multiple items matching the schema.
• If amount = 1 or is omitted, it returns a single object matching the schema.
• contextId can be very useful if you need to split your data generation into multiple steps but still maintain context between them.

Example Usage

{
  id: 'recipesGenerator',
  type: 'ObjectGenerator',
  parameters: {
    description: "You are a very experienced chef with a vast knowledge of recipes. Generate an object with 'recipes' as an array of items, each containing name, ingredients, and instructions.",
    schema: {
      type: 'object',
      properties: {
        recipes: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              name: {
                type: 'string',
                description: 'The recipe name must always be written in japanese!',
              },
              ingredients: {
                type: 'array',
                items: { type: 'string' },
              },
              instructions: {
                type: 'array',
                items: { type: 'string' },
              },
            },
          },
        },
      },
    },
    input: '$.input.recipeType',
    amount: 5,
  },
}

When the flow runs:

1. The step constructs a system prompt from parameters.description.
2. It includes the user’s input ($.input.recipeType) in the final conversation.
3. The LLM will return JSON matching the schema:

Note how the description for the name parameter instructs it to be written in japanese. So that field should always return in japanese. The description property can be very useful when providing more granular instructions on how the LLM should construct the object.

{
  "recipes": [
    {
      "name": "...",
      "ingredients": ["..."],
      "instructions": ["..."]
    },
    ...
  ]
}

4. If you specified amount: 5, it ensures exactly 5 objects in a list or merges them into the main structure—lensless handles that automatically.

Billing & Usage

• ObjectGenerator is charged similarly to LLM usage.
• By default, each call tracks the number of tokens used, updating your cost at $0.000025 * tokens.
• If amount is large, we do iterative chunk calls. Each chunk increments the usage cost.
• Be careful using the amount property. If you set it too high while using a big schema, the cost can become significant.
• For best results, we use reasoning models, so the final billed tokens might include them as well.

Key Points & Best Practices

• The root of your schema must be of type object.
• Schema is your friend — be explicit. The more thorough your schema, the better the LLM can structure results.
• Prompting matters. Provide a clear “description” system prompt. If you see bad results, refine your prompt.
• Testing: Start small (e.g. amount = 2) to ensure the shape is correct. Then scale up once you trust it.
• Complex Schemas: For arrays of objects within objects, carefully nest properties. If the schema is invalid or ambiguous, generation will fail.
• LLM Refusals: If your prompt is too broad, or if the LLM refuses due to policy constraints, you’ll get an error. Ensure your “description” is policy-compliant and straightforward.

Flow example

{
  title: 'Generate a bunch of data objects',
  description: 'Use ObjectGenerator to produce structured JSON for a marketing campaign.',
  input: {
    type: 'object',
    required: ['promptType'],
    properties: {
      topic: {
        type: 'string',
        title: 'Topic for your marketing content',
        description: "e.g., 'Summer Sale' or 'New Electronics Release'",
      },
    },
  },
  steps: [
    {
      id: 'myMarketingObjectGen',
      type: 'ObjectGenerator',
      parameters: {
        description: "You are a marketing copy expert. Generate a JSON object with 'campaigns' array, each containing 'title' and 'blurb'.",
        schema: {
          type: 'object',
          properties: {
            campaigns: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  title: { type: 'string' },
                  blurb: { type: 'string' },
                },
              },
            },
          },
        },
        input: '$.input.topic',
        amount: 5,
        creativity: 12,
      },
    },
  ],
}

After the step completes, $.results.myMarketingObjectGen contains an object like:

{
  "campaigns": [
    { "title": "..." , "blurb": "..." },
    ...
  ]
}

Wrap-Up

ObjectGenerator simplifies creating structured JSON from LLM outputs. It is usually the first step of many flows. Combine it with other Flow steps—like ImageGenerator for text-to-image synergy, or ModelGenerator for advanced training data creation. With robust schema validation, you can trust the shape of the data and store or transform it however you like.