🧩 Basic Concepts

This section establishes the technical foundation to building automations with Loopstack you understanding how AI workflows are executed.

Overview

Loopstack automations are build using two essential contepts:

1. Blocks - NestJS services that represent the building blocks of every automation.
2. YAML Configs - Configuration files to define block specific behaviour.

Block Types

There are different Block types, each with specific functionality

1. Workspaces - Organizational containers that group related automations and data
2. Pipelines - Orchestration units that coordinate workflow execution
3. Workflows - State machines that define business processes, call tools and create documents
4. Tools - Functional units that perform specific tasks
5. Documents - Structured data objects that store and display information

Workspaces

Workspaces contain pipelines, which in turn contain workflows. They serve as the top-level organizational unit in Loopstack.

Purpose: Provide organizational structure for your automations.

• Create logical groupings of related automations
• Control access and permissions at a high level

@BlockConfig({
  imports: [
    PromptWorkflow,
    ChatWorkflow,
    PromptStructuredDataWorkflow,
    ToolCallWorkflow,
    ],
    config: {
    title: 'Examples Workspace'
  },
})
export class ExampleWorkspace extends Workspace {}

Pipelines

Pipelines execute other pipelines or workflows in sequential or parallel order.

Purpose: Orchestrate the execution of workflows in a defined pattern.

• Define execution order (sequential or parallel)
• Coordinate data flow between workflows
• Define conditional paths through the automation

@BlockConfig({
  imports: [
    FirstWorkflow,
    SecondWorkflow,
  ],
  config: {
    title: "Example 1: Pipeline Sequence",
  },
  configFile: __dirname + '/context-data-example.sequence.yaml',
})
export class ContextDataExampleSequence extends Pipeline {}

sequence:
  - id: first
    block: FirstWorkflow
 
  - id: second
    block: SecondWorkflow
    args:
    test: ${ this.steps.first.result }

Workflows

Workflows are executed directly or via pipelines. They use tools to perform custom operations. Workflows control the flow of a business process and manage its state.

Purpose: Define specific business processes as state machines with transitions between states.

• Model processes with states (places) and transitions
• Execute tools to perform actions
• Handle errors and decision points
• Manage the flow of data through the process

@BlockConfig({
  imports: [
    AiGenerateText
  ],
  properties: z.object({
    subject: z.string().default("coffee")
  }),
  config: {
    title: 'Example LLM Prompt',
  },
  configFile: __dirname + '/prompt.workflow.yaml',
})
export class PromptWorkflow extends Workflow  {}

transitions:
  - id: prompt
    from: start
    to: prompt_executed
    call:
      - id: execute_prompt
        tool: AiGenerateObject
        args:
          llm:
            provider: openai
            model: gpt-4o
          responseDocument: FileDocument
          prompt: |
            Create a Python script that prints 'Hello, World!' to the console.
            Wrap the code in triple-backticks.
        assign:
          file: ${ result.data }
 
  - id: create_document
    from: prompt_executed
    to: end
    call:
      - tool: CreateDocument
        args:
          document: FileDocument
          update:
            content: ${ file }

Execution Process:

1. Workflow always starts in start state
2. Finds transition with matching from state
3. Executes specified tools with provided arguments
4. Exports results to variables if specified
5. Moves to to state
6. Repeats until reaching terminal end state

Tools

Tools are called by workflow transitions and can execute custom business logic. They can create or modify documents that are displayed in the studio frontend.

Purpose: Perform specific actions or operations within workflows.

• Execute defined operations (API calls, data processing, etc.)
• Accept input arguments
• Manipulate Documents displayed in the Loopstack Studio

@BlockConfig({
  config: {
    description: 'Calculate the sum of two values.',
  },
  properties: z.object({
    a: z.number(),
    b: z.number()
  }),
})
export class MathSumTool extends Tool {
 
  async execute(): Promise<HandlerCallResult> {
    const sum = this.args.a + this.args.b;
    return {
      data: sum
    };
  }
 
}

Documents

Documents are created and used by workflows and tools. They can store data persistently and provide configuration for interactive forms for user input in the Loopstack Studio.

Purpose: Store, display, and collect data throughout the automation process.

• Define data schemas for validation
• Provide UI components for user interaction
• Store information between workflow steps
• Serve as inputs and outputs for tools

@BlockConfig({
  properties: z.object({
    recommendations: z.array(
      z.object({
        description: z.string(),
        example: z.string(),
      }),
    ),
  }),
  configFile: __dirname + '/file-analysis-result.document.yaml',
})
export class FileAnalysisResult extends Document {
  @Expose()
  recommendations: {
    description: string;
    example: string;
  }[];
}

ui:
  properties:
    recommendations:
      title: Recommendations
      items:
        title: Idea
        order:
          - description
          - example
        properties:
          description:
            title: Description
            widget: textarea-expand
          example:
            title: Example
            widget: code-view
  buttons:
    - transition: confirm
      label: "Confirm"

How Components Work Together

Let’s examine how these components interact in a typical automation:

1. A workspace provides organizational structure
2. A pipeline within that workspace defines execution order
3. The pipeline executes one or more workflows
4. Each workflow consists of transitions between states
5. Transitions call tools to perform actions
6. Tools create or modify documents to store and display data

Example Flow

State Persistence

Workflow state is automatically persisted, enabling:

• Execution resume after interruptions
• Human in the loop interaction
• Audit trails of workflow progress
• Historical execution analysis

All other Blocks are not persistent and will be re-executed on every automation run.