📄 Documents

Documents are Loopstack’s data storage and exchange mechanism that enable workflows to persist, share, and manipulate structured information. They serve as a convenient way to store data that needs to be accessed across different workflows and pipelines of the same root pipeline run.

Documents define how data is validated and rendered in the Loopstack Studio, enabling direct user-interaction with structured data.

Note: Documents are not designed to be accessed cross root pipeline executions. For storing data permanently and accessing them through different root pipeline runs, implement a custom data storage mechanism using custom tools.

Overview

Documents in Loopstack provide:

Persistent Storage: Data that survives workflow execution
Cross-Workflow Communication: Share data between different workflows and pipelines
Structured Data: JSON Schema validation for data integrity
UI Integration: Automatic form generation for user input and displaying information to the user
Document History: Track changes and updates to document content

Basic Document Structure


documents:
  - name: customer_profile                    # Unique document identifier
    title: "Customer Profile"                 # Display name in Studio
    description: "Customer information form"  # Optional description
    schema:                                   # JSON Schema for validation
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        age:
          type: integer
          minimum: 18
    ui:                                       # UI configuration for Studio
      properties:
        age:
          widget: number
      buttons:
        - transition: processCustomer         # Submit button
          label: "Submit Profile"
    content:                                  # Initial/default content
      name: "John Doe"
      email: "john@example.com"
      age: 30

Document Use Cases

Documents fulfill different roles based on their use cases.

User Input

Documents can be used to render and collect user input through forms in the UI:


documents:
  - name: order_request_form
    title: "New Order Request"
    schema:
      type: object
      properties:
        product:
          type: string
          enum: ["laptop", "desktop", "tablet"]
        quantity:
          type: integer
          minimum: 1
          maximum: 100
      required:
        - product
        - quantity
    ui:
      properties:
        product:
          widget: select
          title: "Product"
          enumOptions:
            - label: Awesome Laptop
              value: "SKU001"
            - label: Big Monitor
              value: "SKU002"
        quantity:
          widget: number
          title: "Quantity"
      buttons:
        - transition: processOrder
          label: "Submit Order"
          enabledWhen:
            - waitingForOrder
    content:
      product: "SKU001"
      quantity: 1

Data Storage and -Exchange

Documents for storing and exchanging structured data between workflows:


documents:
  - name: api_response_cache
    title: "API Response Cache"
    schema:
      type: object
      properties:
        endpoint:
          type: string
        response:
          type: object
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
    content:
      endpoint: null
      response: null
      timestamp: null
      status: null

LLM Structured Output

Documents designed for capturing structured LLM responses with automatic parsing:


documents:
  - name: product_analysis
    title: "Product Analysis Result"
    schema:
      type: object
      properties:
        product_name:
          type: string
        sentiment:
          type: string
          enum: ["positive", "neutral", "negative"]
        recommendation_score:
          type: integer
          minimum: 1
          maximum: 10
      required:
        - product_name
        - sentiment

Note: Loopstack can automatically generate output templates based on document schemas and parse LLM responses to populate structured documents through specialized built-in tools. This enables reliable extraction of structured data from natural language AI responses. See the LLM Structured Output section for detailed implementation guidance.

UI Elements

Documents for rendering specific UI components such as Messages.


documents:
  - name: my_message_to_user
    ui:
      widget: chat-message
    content:
      role: assistant
      content: "Hello World."

Loopstack provides a variety of built-in document types and tools. See Built-in Tools section to learn more.

Document Configuration

Document Properties

Every document definition supports these properties:

name: (mandatory) Unique identifier within the workspace
title: (optional) Display name in Loopstack Studio
description: (optional) Human-readable description
schema: (optional) JSON Schema for data validation
ui: (optional) UI configuration for form generation
content: (optional) Default/initial content

Schema Definition

Use JSON Schema to define the structure and validation rules for your documents:


documents:
  - name: product_catalog_item
    schema:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
        price:
          type: number
          minimum: 0
        category:
          type: string
          enum: ["electronics", "clothing", "books", "home"]
        tags:
          type: array
          items:
            type: string
          maxItems: 10
        in_stock:
          type: boolean
        metadata:
          type: object
          properties:
            sku:
              type: string
              pattern: "^[A-Z]{2}[0-9]{4}$"
            weight:
              type: number
              minimum: 0
      required:
        - name
        - price
        - category
      additionalProperties: false

UI Configuration

Define how documents appear as forms in Loopstack Studio:


documents:
  - name: survey_form
    title: "Customer Satisfaction Survey"
    schema:
      type: object
      properties:
        feedback:
          type: string
        recommend:
          type: boolean
        contact_info:
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string
    ui:
      properties:
        feedback:
          widget: textarea
          title: "Additional Feedback"
          placeholder: "Tell us more about your experience..."
        recommend:
          widget: checkbox
          title: "Would you recommend us to others?"
        contact_info:
          title: "Contact Information (Optional)"
          properties:
            email:
              widget: input
              title: "Email Address"
            phone:
              widget: input
              title: "Phone Number"
      buttons:
        - transition: process_survey
          label: "Submit Survey"
          enabledWhen:
            - waiting_for_survey
        - transition: saveDraft
          label: "Save Draft"
          variant: secondary
      layout:
        type: vertical
        spacing: medium

UI Widget Types

Loopstack supports various widget types for different data types:

input: Text input field
textarea: Multi-line text area
switch: Boolean input
select: Dropdown selection
radio: Radio button group
checkbox: Single checkbox
slider: Number input

Button Configuration

Define action buttons that trigger workflow transitions:


ui:
  buttons:
    - transition: submit_form          # Workflow transition to trigger
      label: "Submit"                  # Button text
      variant: primary                 # Button style (primary, secondary, danger)
      enabledWhen:                     # States where button is enabled
        - waiting_for_input
        - form_ready
    - transition: save_as_draft
      label: "Save Draft"
      variant: secondary
      enabledWhen:
        - waiting_for_input
    - transition: cancel_form
      label: "Cancel"
      variant: danger
      confirmationMessage: "Are you sure you want to cancel? Unsaved changes will be lost."

Special Button Types


ui:
  buttons:
    - widget: chat
      label: "Chat"
      transition: add_user_message
      enabledWhen:
        - waiting_for_user

Using Documents in Workflows

Documents are manipulated through built-in tools during workflow execution.

Use the create_document, update_document, and load_document tools to create and modify documents. See Working with Documents Tool Examples for more details.

Example Workflow: Manual User Input

Create interactive workflows that wait for user input:


include:
  - core/tools/create-document.yaml
  - core/tools/create-chat-message.yaml
 
workflows:
  - name: approval_workflow
    type: stateMachine
    transitions:
      - name: request_approval
        from: start
        to: waiting_for_approval
        call:
          - tool: create_document
            arguments:
              document: approval_form
              content:
                request_id: ${ context.request.id }
                request_details: ${ context.request.details }
                status: "pending"
 
      - name: process_approval
        from: waiting_for_approval
        to: approved
        when: manual                   # Wait for user interaction
        call:
          - tool: create_document
            arguments:
              document: approval_form
              content: ${ transition.payload }  # User input data
            as: APPROVAL_RESULT
 
      - name: handle_approval
        from: approved
        to: end
        call:
          - tool: create_chat_message
            arguments:
              role: assistant
              content: |
                Approval processed: ${ APPROVAL_RESULT.status }
                Comments: ${ APPROVAL_RESULT.comments }

Data Flow and Context

Cross-Workflow Communication

Documents enable data sharing between different workflows and pipelines:


# Workflow A: Creates customer data
workflows:
  - name: customer_onboarding_workflow
    type: stateMachine
    transitions:
      - name: create_customer_profile
        from: start
        to: end
        call:
          - tool: create_document
            arguments:
              document: customer_profile
              content:
                name: "John Doe"
                email: "john@doe.com"
                tier: "bronze"
                created_date: ${ currentDate }
 
# Workflow B: Uses customer data
workflows:
  - name: welcome_email_workflow
    type: stateMachine
    transitions:
      - name: load_customer_data
        from: start
        to: data_loaded
        call:
          - tool: load_document
            arguments:
              where:
                name: customer_profile
            as: CUSTOMER
 
      - name: send_welcome_email
        from: data_loaded
        to: end
        call:
          - tool: email_sender_tool
            arguments:
              recipient: ${ CUSTOMER.content.email }
              template: "welcome"
              variables:
                customer_name: ${ CUSTOMER.content.name }
                tier: ${ CUSTOMER.content.tier }

Next Steps

With a comprehensive understanding of documents, you’re ready to explore how to create and use templates for modular a configuration.

Continue to Templates →