assay migrate¶

Upgrade configuration from v0 to v1 format.

Synopsis¶

assay migrate --config <CONFIG_FILE> [OPTIONS]

Description¶

Migrates older Assay configuration files to the current v1 format. This includes:

Converting sequence arrays to rule-based DSL
Inlining external policy references
Updating deprecated field names
Adding required version field

Options¶

Option	Description
`--config`, `-c`	Path to config file to migrate
`--dry-run`	Preview changes without writing
`--backup`	Create backup before modifying (default: true)
`--no-backup`	Skip backup creation
`--output`, `-o`	Write to different file instead of in-place

Examples¶

Basic Migration¶

assay migrate --config eval.yaml

# Output:
# Migrating eval.yaml from v0 to v1...
# 
# Changes:
#   - Added: version: "1"
#   - Converted: sequences → rules DSL
#   - Inlined: policies/discount.yaml
#   - Renamed: threshold → min_score (deprecated)
# 
# Created backup: eval.yaml.bak
# Written: eval.yaml

Preview Changes¶

assay migrate --config eval.yaml --dry-run

# Output:
# [DRY RUN] Would apply the following changes:
#
# --- eval.yaml (before)
# +++ eval.yaml (after)
# @@ -1,3 +1,4 @@
# +version: "1"
#  suite: my-agent
#  tests:
# ...

Write to New File¶

assay migrate --config old-eval.yaml --output new-eval.yaml

What Gets Migrated¶

Version Field¶

# Before (v0)
suite: my-agent

# After (v1)
version: "1"
suite: my-agent

Sequence Rules¶

# Before (v0)
tests:
  - id: order_check
    metric: sequence_valid
    sequences:
      - [get_customer, update_customer]
      - [verify_identity, delete_customer]

# After (v1)
tests:
  - id: order_check
    metric: sequence_valid
    rules:
      - type: before
        first: get_customer
        then: update_customer
      - type: before
        first: verify_identity
        then: delete_customer

Inline Policies¶

# Before (v0)
tests:
  - id: args_check
    metric: args_valid
    policy: policies/customer.yaml  # External file

# After (v1)
tests:
  - id: args_check
    metric: args_valid
    policy:  # Inlined
      tools:
        get_customer:
          arguments:
            id:
              type: string
              required: true

Deprecated Fields¶

v0 Field	v1 Field
`threshold`	`min_score`
`must_call`	`rules: [{ type: require }]`
`must_not_call`	`rules: [{ type: blocklist }]`

Backup Behavior¶

By default, migration creates a backup:

eval.yaml      → eval.yaml (updated)
eval.yaml.bak  → eval.yaml.bak (original)

Skip backup:

assay migrate --config eval.yaml --no-backup

Migration Warnings¶

Lossy Conversion¶

Warning: Lossy conversion detected

  The v0 field 'fuzzy_match' has no v1 equivalent.
  This field will be removed.

  If you rely on this behavior, consider:
    1. Using a custom metric
    2. Opening an issue for feature request

Ambiguous Sequences¶

Warning: Ambiguous sequence conversion

  The sequence [A, B, C] could mean:
    - A before B, B before C (chain)
    - A before B, A before C (fan-out)

  Assuming chain behavior. Review the generated rules.

Validation After Migration¶

After migrating, validate the new config:

assay validate --config eval.yaml

# Output:
# ✅ Config valid
# Version: 1
# Tests: 5
# Policies: 2 (inlined)

Rollback¶

If migration causes issues, restore from backup:

mv eval.yaml.bak eval.yaml