@loopstack/prompt-structured-output-example-workflow

> A module for the Loopstack AI automation framework.

This module provides an example workflow demonstrating how to generate structured output from an LLM using a custom document schema.

Overview

The Prompt Structured Output Example Workflow shows how to use the aiGenerateDocument tool to get structured, typed responses from an LLM. It generates a "Hello, World!" script in a user-selected programming language, with the response structured into filename, description, and code fields.

By using this workflow as a reference, you'll learn how to:

- Define custom document schemas with Zod for structured LLM output
- Use the aiGenerateDocument tool to generate typed responses
- Create custom documents with form configuration
- Store structured data in workflow state using @WithState

This example builds on the basic prompt pattern and is ideal for developers who need typed, structured responses from LLMs.

Installation

You can add this module using the loopstack cli or via npm.

$3

``bash
loopstack add @loopstack/prompt-structured-output-example-workflow
`

This command copies the source files into your src directory.

- It is a great way to explore the code to learn new concepts or add own customizations
- It will set up the module for you, so you do not need to manually update your application

$3

`bash
npm install --save @loopstack/prompt-structured-output-example-workflow
`

Use npm install if you want to use and maintain the module as node dependency.

- Use this, if you do not need to make changes to the code or want to review the source code.

Setup

$3

Set your OpenAI API key as an environment variable:

`bash
OPENAI_API_KEY=sk-...
`

$3

> This step is automatically done for you when using the loopstack add command.

- Add PromptStructuredOutputExampleModule to the imports of default.module.ts or any other custom module.
- Inject the PromptStructuredOutputWorkflow workflow to your workspace class using the @InjectWorkflow() decorator.

See here for more information about working with Modules and Workspaces

How It Works

$3

#### 1. Custom Document Schema

Define a Zod schema for the structured output:

`typescript
export const FileDocumentSchema = z.object({
filename: z.string(),
description: z.string().optional(),
code: z.string(),
});
`

Create a document class that uses this schema:

`typescript
@Injectable()
@BlockConfig({
configFile: __dirname + '/file-document.yaml',
})
@WithArguments(FileDocumentSchema)
export class FileDocument extends DocumentBase {}
`

#### 2. Document UI Configuration

Configure how the document is displayed in the UI:

`yaml
type: document

ui:
form:
order:
- filename
- description
- code
properties:
filename:
title: File Name
readonly: true
description:
title: Description
readonly: true
code:
title: Code
widget: code-view
`

#### 3. Enum Arguments with Select Widget

Use Zod enums to provide a dropdown selection in the UI:

`typescript
@WithArguments(z.object({
language: z.enum(['python', 'javascript', 'java', 'cpp', 'ruby', 'go', 'php']).default('python'),
}))
`

Configure the select widget in YAML:

`yaml
ui:
form:
properties:
language:
title: 'What programming language should the script be in?'
widget: select
`

#### 4. Generating Structured Output

Use aiGenerateDocument with a response.document to get typed output:

`yaml
- tool: aiGenerateDocument
args:
llm:
provider: openai
model: gpt-4o
response:
document: fileDocument
prompt: |
Create a {{ args.language }} script that prints 'Hello, World!' to the console.
Wrap the code in triple-backticks.
assign:
file: ${ result.data.content }
`

The LLM response is automatically parsed into the FileDocument schema.

#### 5. Workflow State

Use @WithState to define typed state that persists across transitions:

`typescript
@WithState(z.object({
file: FileDocumentSchema,
}))
`

Access state values in subsequent transitions:

`yaml
text: |
Successfully generated: {{ file.description }}
`

Dependencies

This workflow uses the following Loopstack modules:

- @loopstack/core - Core framework functionality
- @loopstack/core-ui-module - Provides CreateDocument tool
- @loopstack/ai-module - Provides AiGenerateDocument tool and AiMessageDocument`

About

Author: Jakob Klippel

License: Apache-2.0

$3

- Loopstack Documentation
- Getting Started with Loopstack
- Find more Loopstack examples in the Loopstack Registry