rig-migrate

name	rig-migrate
description	> Use when this capability is needed.

Rig Migration Assistant

Current project Rig version (auto-detected):

!`grep -E '^rig-core|^rig ' Cargo.toml 2>/dev/null || grep -rE 'rig-core\s*=' Cargo.toml */Cargo.toml 2>/dev/null | head -5 || echo "rig-core version not found in Cargo.toml"`

Latest Rig release:

!`cargo search rig-core --limit 1 2>/dev/null || echo "Could not fetch latest version. Check https://crates.io/crates/rig-core"`

Migration Workflow

1. Detect: Compare current version against target version.
2. Audit: Search for deprecated patterns and breaking API usages.
3. Plan: List all files and changes required.
4. Migrate: Apply changes systematically.
5. Validate: Run cargo fmt, cargo clippy --all-targets --all-features, cargo test.

Common Migration Patterns

Send/Sync to WasmCompat (introduced in 0.5+)

All trait bounds must use WASM-compatible variants:

// Before
pub trait MyTrait: Send + Sync {
    fn method(&self) -> impl Future<Output = ()> + Send;
}

// After
use rig::{WasmCompatSend, WasmCompatSync};

pub trait MyTrait: WasmCompatSend + WasmCompatSync {
    fn method(&self) -> impl Future<Output = ()> + WasmCompatSend;
}

Search pattern: grep -rn ': Send\b\|+ Send\b\|: Sync\b\|+ Sync\b' --include='*.rs'

String Error Types to Proper Enums

// Before
fn process() -> Result<(), String> { ... }

// After
#[derive(Debug, thiserror::Error)]
enum ProcessError {
    #[error("Parse failed: {0}")]
    Parse(#[from] serde_json::Error),
}

fn process() -> Result<(), ProcessError> { ... }

Search pattern: grep -rn 'Result<.*,\s*String>' --include='*.rs' (results should be manually verified to avoid false positives)

Provider API Updates

When providers update their APIs, Rig's type definitions change. Check the CHANGELOG for specific field additions/removals.

Typical changes:

• New fields added to request/response structs
• Model constant renames (e.g., GPT_4 -> GPT_4O)
• New capability declarations

CompletionRequest Model Override (new)

CompletionRequest now has an optional model field:

// When constructing CompletionRequest manually, include the field:
let request = CompletionRequest {
    model: None,  // or Some("model-override".to_string())
    preamble: None,
    chat_history: OneOrMany::one("Hello".into()),
    // ... rest of fields
};

Migration Checklist

Use this checklist when migrating:

• Update rig-core version in all Cargo.toml files
• Update companion crate versions (rig-mongodb, rig-lancedb, etc.)
• Search for deprecated API patterns
• Replace Send/Sync with WasmCompatSend/WasmCompatSync
• Replace String error types with proper error enums
• Remove .unwrap() / .expect() on fallible operations
• Update model constants if renamed
• Run cargo fmt && cargo clippy --all-targets --all-features && cargo test
• Verify examples still compile

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.