Add Default Values Support for Variables

[loukratz-bv]

Summary

Add support for default values on QType variables to improve UX when variables have sensible defaults that users may want to override.

Motivation

Currently, QType variables cannot have default values. This means:

1. All inputs must be provided explicitly, even when there's a sensible default
2. Workarounds like PromptTemplate steps are needed to set defaults
3. Optional variables (type: text?) can be null but can't have a fallback value

Real-World Use Case

We want users to provide a custom analysis prompt but have a reasonable default if they don't:

variables:
  - id: analysis_prompt
    type: text
    ui:
      widget: textarea
    # Would like: default: "Analyze the following data and provide insights..."

Without defaults, users must either:

• Always provide the value (poor UX)
• Make it optional and handle None in steps (requires extra logic)
• Add a PromptTemplate step just to set a default (verbose)

Proposed Solution

Add a default field to the Variable schema:

variables:
  - id: analysis_prompt
    type: text
    default: "Analyze this data and provide key insights"
  
  - id: temperature
    type: float
    default: 0.7
  
  - id: max_tokens
    type: int
    default: 2000

Behavior

• If a variable has a default and no value is provided at runtime, use the default
• If a value is provided at runtime, use the provided value (overrides default)
• Default values should be validated against the variable's type
• Default values work with all types (text, int, float, bool, lists, custom types)

Implementation Considerations

Schema Changes

Add default field to Variable model:

class Variable(StrictBaseModel):
    id: str
    type: str | Type
    optional: bool = False
    default: Any | None = None
    ui: TextInputUI | FileUploadUI | None = None

Validation

• Validate that default matches the variable's type
• Consider: Should optional=True and default be mutually exclusive? Or can a variable have both?
  • If both allowed: when value is None, should we use default or keep None?
  • Recommendation: Allow both - use default when value is missing/None

Runtime Behavior

When executing a flow:

1. Check if variable has a value in inputs
2. If not, check if variable has a default
3. If not, raise error (unless optional=True)

UI Integration

• The QType UI should show default values as placeholders in input fields
• Consider showing a "Reset to default" button
• Display the default value in the flow's input documentation

Examples

Simple Defaults

flows:
  - id: llm_chat
    variables:
      - id: prompt
        type: text
      - id: temperature
        type: float
        default: 0.7
      - id: max_tokens
        type: int
        default: 2000

Complex Defaults with UI Hints

flows:
  - id: analysis
    variables:
      - id: data_source
        type: text
      - id: custom_instructions
        type: text
        default: |
          Please analyze the data and provide:
          1. Key trends
          2. Notable anomalies
          3. Actionable recommendations
        ui:
          widget: textarea

Default with Optional

variables:
  - id: api_key
    type: text?
    default: null  # Optional, defaults to null if not provided

Benefits

1. Better UX - Users can run flows with sensible defaults
2. Less boilerplate - No need for initialization steps just to set defaults
3. Self-documenting - Defaults show expected values
4. Flexibility - Users can still override when needed

Testing Requirements

• Unit tests for default value validation
• Integration tests for flow execution with defaults
• Test defaults with all primitive types
• Test defaults with custom types
• Test interaction between default and optional
• Test UI rendering of defaults

Related Issues

• Add Dict-Style Syntax for Tool and Flow Variables #124 - Dict-style variable syntax (complementary feature)

Questions

1. Should serialization preserve default values when generating YAML?
2. Should defaults be allowed for output variables, or only inputs?
3. Should defaults work with references (e.g., client: client_name with default)?