Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Migration Guide: v0.1.0 → v0.2.0

Release Date: 2025-10-26 Migration Effort: Low (No breaking changes) Recommended: Yes (Significant stability improvements)

Overview

Yanshi v0.2.0 introduces major stability and observability improvements through Phase 1 enhancements. This release focuses on production-readiness with retry mechanisms, error context tracking, workflow debugging tools, and resource management capabilities.

Key Highlights:

  • ✅ Zero Breaking Changes - Fully backward compatible
  • ✅ Opt-In Features - All new features are optional
  • ✅ Production Ready - Battle-tested with comprehensive test coverage
  • ✅ Performance Optimized - Minimal overhead (< 1ms for most operations)

What’s New

1. Retry Mechanism (Week 1)

Automatic retry with configurable strategies for transient failures.

2. Error Context Enhancement (Week 1)

Detailed error tracking with execution history and input capture.

3. Workflow Debugging Tools (Week 2)

CLI command for workflow validation, visualization, and dry-run.

4. Resource Management (Week 3)

Configurable memory limits with automatic cleanup and monitoring.

Migration Steps

Step 1: Update Dependencies

Update your Cargo.toml:

[dependencies]
yanshi-core = "0.2.0"
yanshi-llm = "0.2.0"
yanshi-cli = "0.2.0"

Then run:

cargo update
cargo build

Step 2: Run Tests

Verify your existing workflows still work:

cargo test

Expected Result: All tests should pass without modifications.

Step 3: Adopt New Features (Optional)

3.1 Enable Retry Mechanism

Add retry configuration to error-prone operations:

#![allow(unused)]
fn main() {
use yanshi_core::{RetryPolicy, RetryStrategy, execute_with_retry};

let policy = RetryPolicy::builder()
    .max_attempts(3)
    .strategy(RetryStrategy::ExponentialBackoff {
        initial_delay_ms: 100,
        max_delay_ms: 5000,
        multiplier: 2.0,
        jitter: true,
    })
    .build();

// Wrap operations that may fail transiently
let result = execute_with_retry(&policy, "api_call", || async {
    // Your operation here
    Ok(data)
}).await?;
}

3.2 Add Error Context Tracking

Enhance error reporting with detailed context:

#![allow(unused)]
fn main() {
use yanshi_core::{execute_with_retry_and_context, ErrorContext};

let result = execute_with_retry_and_context(
    &policy,
    "run_123",
    "process_node",
    Some("data_processor"),
    || async {
        // Your operation
        Ok(result)
    }
).await;

match result {
    Ok(value) => // Handle success,
    Err((error, context)) => {
        // Access detailed error information
        eprintln!("{}", context.detailed_report());
    }
}
}

3.3 Use Workflow Debugging

Debug workflows before execution:

# Validate workflow configuration
yanshi workflow debug workflow.yml --validate

# Visualize DAG structure
yanshi workflow debug workflow.yml --visualize

# Analyze complexity and bottlenecks
yanshi workflow debug workflow.yml --analyze

# Dry-run without execution
yanshi workflow debug workflow.yml --dry-run

3.4 Enable Resource Management

Add memory limits to prevent unbounded growth:

#![allow(unused)]
fn main() {
use yanshi_core::{ResourceLimits, StateMonitor};

let limits = ResourceLimits::builder()
    .max_state_size(100 * 1024 * 1024)  // 100 MB
    .max_value_size(10 * 1024 * 1024)   // 10 MB
    .cleanup_threshold(0.8)              // Clean at 80%
    .auto_cleanup(true)
    .build();

let monitor = StateMonitor::new(limits);

// Track allocations
monitor.record_allocation("data", data.len());

// Check usage
let stats = monitor.get_stats();
if stats.should_cleanup {
    monitor.cleanup(0.5)?;  // Clean to 50%
}

// Cleanup when done
monitor.record_deallocation("data");
}

API Changes

No Breaking Changes ✅

All existing APIs remain unchanged and fully functional.

New APIs Added

Retry Module

  • RetryPolicy - Retry configuration
  • RetryStrategy - Retry timing strategies
  • RetryContext - Retry attempt tracking
  • execute_with_retry() - Simple retry wrapper
  • execute_with_retry_and_context() - Retry with error context

Error Context Module

  • ErrorContext - Detailed error information
  • ErrorInfo - Individual error details
  • ErrorContextBuilder - Fluent API for context creation

Resource Management Module

  • ResourceLimits - Memory limit configuration
  • StateMonitor - Real-time usage tracking
  • ResourceAlert - Usage notifications
  • ResourceStats - Usage statistics

CLI Commands

  • yanshi workflow debug - Workflow debugging command
    • --validate - Validate configuration
    • --visualize - Show DAG structure
    • --analyze - Analyze complexity
    • --plan - Show execution plan
    • --dry-run - Simulate execution

Performance Impact

Overhead Measurements

All features have minimal performance impact:

FeatureOverheadAcceptable?
Retry (no retries)< 100μs✅ Yes
Retry (with retries)< 5ms per retry✅ Yes
Error context< 1ms✅ Yes
Resource tracking< 10μs per operation✅ Yes
Resource cleanup< 10ms for 50 entries✅ Yes

Optimization Tips

  1. Use Fast Mode for Resource Monitoring (when LRU not needed):

    #![allow(unused)]
    fn main() {
    let monitor = StateMonitor::new_fast(limits);  // 80x faster
    }
  2. Disable Features You Don’t Use:

    #![allow(unused)]
    fn main() {
    // If not using error context, use simple retry
    execute_with_retry(&policy, "op", || async { Ok(()) }).await
    }
  3. Configure Appropriate Limits:

    #![allow(unused)]
    fn main() {
    // Don't use unlimited values
    let limits = ResourceLimits::builder()
        .max_state_size(available_memory / 2)  // Use 50% of available
        .build();
    }

Common Migration Scenarios

Scenario 1: Basic Usage (No Changes Needed)

Before v0.2.0:

#![allow(unused)]
fn main() {
let flow = Flow::new(nodes);
let results = flow.run().await?;
}

After v0.2.0:

#![allow(unused)]
fn main() {
// Exact same code works!
let flow = Flow::new(nodes);
let results = flow.run().await?;
}

Migration Effort: None ✅

Scenario 2: Adding Retry to Existing Code

Before v0.2.0:

#![allow(unused)]
fn main() {
async fn fetch_data() -> Result<Data, Error> {
    // Manual retry logic
    for attempt in 0..3 {
        match api_call().await {
            Ok(data) => return Ok(data),
            Err(e) if attempt < 2 => {
                tokio::time::sleep(Duration::from_millis(100)).await;
                continue;
            }
            Err(e) => return Err(e),
        }
    }
    unreachable!()
}
}

After v0.2.0:

#![allow(unused)]
fn main() {
async fn fetch_data() -> Result<Data, YanshiError> {
    let policy = RetryPolicy::builder()
        .max_attempts(3)
        .strategy(RetryStrategy::Fixed { delay_ms: 100 })
        .build();

    execute_with_retry(&policy, "fetch_data", || async {
        api_call().await.map_err(|e| YanshiError::Generic(e.to_string()))
    }).await
}
}

Benefits: Less code, more reliable, configurable

Scenario 3: Improving Error Handling

Before v0.2.0:

#![allow(unused)]
fn main() {
match workflow.execute().await {
    Ok(result) => println!("Success: {:?}", result),
    Err(e) => eprintln!("Error: {}", e),  // Limited information
}
}

After v0.2.0:

#![allow(unused)]
fn main() {
match execute_with_retry_and_context(
    &policy,
    run_id,
    node_name,
    Some(node_type),
    || async { workflow.execute().await }
).await {
    Ok(result) => println!("Success: {:?}", result),
    Err((error, context)) => {
        eprintln!("{}", context.detailed_report());  // Rich debugging info
        // Log context for debugging
        log::error!("Workflow failed: {}", context.summary());
    }
}
}

Benefits: Better debugging, root cause analysis, audit trail

Scenario 4: Adding Resource Monitoring

Before v0.2.0:

#![allow(unused)]
fn main() {
// No memory tracking - potential OOM
let mut state = HashMap::new();
for item in large_dataset {
    state.insert(item.id, item.data);  // Unbounded growth!
}
}

After v0.2.0:

#![allow(unused)]
fn main() {
let limits = ResourceLimits::builder()
    .max_state_size(100 * 1024 * 1024)
    .auto_cleanup(true)
    .build();

let monitor = StateMonitor::new(limits);
let mut state = HashMap::new();

for item in large_dataset {
    let size = std::mem::size_of_val(&item.data);

    if !monitor.record_allocation(&item.id, size) {
        // Handle resource limit
        monitor.cleanup(0.5)?;
        if !monitor.record_allocation(&item.id, size) {
            return Err(YanshiError::ResourcePoolExhausted {
                resource_type: "memory".to_string()
            });
        }
    }

    state.insert(item.id, item.data);
}
}

Benefits: Predictable memory usage, automatic cleanup, no OOM

Troubleshooting

Issue: Tests Fail After Update

Cause: Compilation errors or test failures after upgrading.

Solution:

  1. Clean build artifacts: cargo clean
  2. Update all dependencies: cargo update
  3. Rebuild: cargo build
  4. If using unstable features, check compatibility

Issue: Performance Regression

Cause: Unintended feature overhead.

Solution:

  1. Use fast mode for resource monitoring if not using cleanup
  2. Disable retry for non-transient operations
  3. Check benchmark results: cargo test --test performance_benchmarks

Issue: Memory Usage Increased

Cause: Error context or resource monitoring tracking data.

Solution:

  1. Use StateMonitor::new_fast() for minimal overhead
  2. Configure appropriate max_cache_entries
  3. Enable auto cleanup: .auto_cleanup(true)

Rollback Instructions

If you need to revert to v0.1.0:

[dependencies]
yanshi-core = "0.1.0"
yanshi-llm = "0.1.0"
yanshi-cli = "0.1.0"

Then:

cargo clean
cargo update
cargo build

Note: No code changes needed since v0.2.0 is backward compatible.

Testing Checklist

Before deploying v0.2.0 to production:

  • All existing tests pass without modification
  • Integration tests run successfully
  • Performance benchmarks meet targets
  • Resource limits configured appropriately
  • Error handling tested with new context
  • Retry policies tested for your use cases
  • Workflow debugging commands work
  • Memory usage monitored and acceptable

Getting Help

  • Documentation: docs/ directory
  • Examples: yanshi-core/examples/
  • Issues: https://github.com/anthropics/yanshi/issues
  • Discussions: https://github.com/anthropics/yanshi/discussions

Last Updated: 2025-10-26 Version: 0.2.0 Status: Ready for Review