llm-worker-rs/docs/patch_note/v0.2.0.md

Release Notes - v0.2.0

Release Date: 2025-10-14

Overview

Release Notes - v0.2.0

Release Date: 2025-10-14

Overview

Version 0.2.0 introduces significant improvements to the external API, including a builder pattern for Worker construction, simplified Role management, comprehensive error handling improvements, and a new plugin system for extensible LLM providers.

Breaking Changes

1. Role System Redesign

Removed duplicate types:

• RoleConfig has been removed from worker-types
• PromptRoleConfig has been renamed to Role
• All configuration is now unified under worker::prompt_types::Role

Built-in roles removed:

• Role::default() - removed
• Role::assistant() - removed
• Role::code_assistant() - removed

Migration:

// Before (v0.1.0)
let role = RoleConfig::default();

// After (v0.2.0)
use worker::prompt_types::Role;
let role = Role::new(
    "assistant",
    "A helpful AI assistant",
    "You are a helpful, harmless, and honest AI assistant."
);

2. Worker Construction - Builder Pattern

New Type-state Builder API:

Worker construction now uses a type-state builder pattern that enforces required parameters at compile time.

// Before (v0.1.0)
let worker = Worker::new(
    LlmProvider::Claude,
    "claude-3-sonnet-20240229",
    &api_keys,
    role,
    plugin_registry,
)?;

// After (v0.2.0)
let worker = Worker::builder()
    .provider(LlmProvider::Claude)
    .model("claude-3-sonnet-20240229")
    .api_keys(api_keys)
    .role(role)
    .build()?;

Required parameters (enforced at compile-time):

• provider(LlmProvider) - LLM provider
• model(&str) - Model name
• role(Role) - System role configuration

Optional parameters:

• api_keys(HashMap<String, String>) - API keys for providers
• plugin_id(&str) - Plugin identifier for custom providers
• plugin_registry(Arc<Mutex<PluginRegistry>>) - Plugin registry

3. WorkerError Redesign

Complete error type restructuring with structured error information:

Removed duplicate variants:

• ToolExecution (use ToolExecutionError)
• Config (use ConfigurationError)
• Serialization (use JsonError)

New structured error variants:

pub enum WorkerError {
    ToolExecutionError {
        tool_name: String,
        reason: String,
        source: Option<Box<dyn Error>>,
    },
    LlmApiError {
        provider: String,
        message: String,
        status_code: Option<u16>,
        source: Option<Box<dyn Error>>,
    },
    ConfigurationError {
        message: String,
        context: Option<String>,
        source: Option<Box<dyn Error>>,
    },
    ModelNotFound {
        provider: String,
        model_name: String,
    },
    Network {
        message: String,
        source: Option<Box<dyn Error>>,
    },
    JsonError(serde_json::Error),
    Other(String),
}

New helper methods for ergonomic error construction:

// Tool execution errors
WorkerError::tool_execution(tool_name, reason)
WorkerError::tool_execution_with_source(tool_name, reason, source)

// Configuration errors
WorkerError::config(message)
WorkerError::config_with_context(message, context)
WorkerError::config_with_source(message, source)

// LLM API errors
WorkerError::llm_api(provider, message)
WorkerError::llm_api_with_details(provider, message, status_code, source)

// Model errors
WorkerError::model_not_found(provider, model_name)

// Network errors
WorkerError::network(message)
WorkerError::network_with_source(message, source)

Migration:

// Before (v0.1.0)
return Err(WorkerError::ToolExecutionError(
    format!("Tool '{}' failed: {}", tool_name, reason)
));

// After (v0.2.0)
return Err(WorkerError::tool_execution(tool_name, reason));

// With source error
return Err(WorkerError::tool_execution_with_source(
    tool_name,
    reason,
    Box::new(source_error)
));

New Features

1. Plugin System

A new extensible plugin system for custom LLM providers:

Core Components:

• ProviderPlugin trait - Define custom LLM providers
• PluginRegistry - Manage plugin lifecycle
• PluginClient - Adapter for plugin-based clients
• PluginMetadata - Plugin identification and configuration

Example:

use worker::plugin::{ProviderPlugin, PluginRegistry};

// Register a plugin
let mut registry = PluginRegistry::new();
registry.register(Arc::new(CustomProviderPlugin::new()))?;

// Use plugin with Worker
let worker = Worker::builder()
    .provider(LlmProvider::OpenAI) // Base provider type
    .model("custom-model")
    .plugin_id("custom-provider")
    .plugin_registry(Arc::new(Mutex::new(registry)))
    .role(role)
    .build()?;

Plugin Features:

• Custom provider implementation
• API key validation
• Model listing
• Health checks
• Dynamic configuration schemas
• Optional dynamic library loading (#[cfg(feature = "dynamic-loading")])

2. Examples

New example files:

1. worker/examples/builder_basic.rs

   • Demonstrates the new builder pattern API
   • Shows basic Worker construction
   • Example tool registration

2. worker/examples/plugin_usage.rs

   • Plugin system usage example
   • Custom provider implementation
   • Plugin registration and usage

Improvements

Error Handling

1. Structured error information - All errors now carry contextual information (provider, tool name, status codes, etc.)
2. Error source tracking - #[source] attribute enables full error chain tracing
3. Automatic conversions - Added From implementations for common error types:
   • From<reqwest::Error> → Network error
   • From<std::io::Error> → ConfigurationError
   • From<serde_json::Error> → JsonError
   • From<Box<dyn Error>> → Other error

Code Organization

1. Eliminated duplicate types between worker-types and worker crates
2. Clearer separation of concerns - Role定義とシステムプロンプト生成関数の責務を分離
3. Consistent error construction - All error sites updated to use new helper methods

Files Changed

Modified (11 files):

• Cargo.lock - Dependency updates
• worker-types/src/lib.rs - Removed duplicate types
• worker/Cargo.toml - Version and dependency updates
• worker/src/config_parser.rs - Role type updates
• worker/src/lib.rs - Builder pattern, error handling updates
• worker/src/llm/gemini.rs - Error handling improvements
• worker/src/llm/ollama.rs - Error handling improvements
• worker/src/mcp_config.rs - Error handling updates
• worker/src/mcp_tool.rs - Error handling improvements
• worker/src/prompt_composer.rs - Role type imports
• worker/src/prompt_types.rs - PromptRoleConfig → Role rename
• worker/src/types.rs - Complete WorkerError redesign

Added (5 files):

• worker/src/builder.rs - Type-state builder implementation
• worker/src/plugin/mod.rs - Plugin system core
• worker/src/plugin/example_provider.rs - Example plugin implementation
• worker/examples/builder_basic.rs - Builder pattern example
• worker/examples/plugin_usage.rs - Plugin usage example

Renamed (1 file):

• worker/README.md → README.md - Moved to root

Migration Guide

Step 1: Update Role Construction

Replace all RoleConfig and built-in role usage:

// Remove old imports
// use worker::RoleConfig;

// Add new import
use worker::prompt_types::Role;

// Replace role construction
let role = Role::new(
    "your-role-name",
    "Role description",
    "Your system prompt template"
);

Step 2: Update Worker Construction

Replace direct Worker::new() calls with builder pattern:

let worker = Worker::builder()
    .provider(provider)
    .model(model_name)
    .api_keys(api_keys)
    .role(role)
    .build()?;

Step 3: Update Error Handling

Replace old error construction with new helper methods:

// Configuration errors
WorkerError::ConfigurationError("message".to_string())
// becomes:
WorkerError::config("message")

// Tool errors
WorkerError::ToolExecutionError(format!("..."))
// becomes:
WorkerError::tool_execution(tool_name, reason)

// Pattern matching
match error {
    WorkerError::ConfigurationError(msg) => { /* ... */ }
    // becomes:
    WorkerError::ConfigurationError { message, .. } => { /* ... */ }
}

Acknowledgments

This release includes significant API improvements based on architectural review and refactoring to improve type safety, error handling, and code maintainability.

Next Steps

See the examples in worker/examples/ for complete usage demonstrations:

• builder_basic.rs - Basic Worker construction
• plugin_usage.rs - Plugin system usage

Breaking Changes

1. Role System Redesign

Removed duplicate types:

• RoleConfig has been removed from worker-types
• PromptRoleConfig has been renamed to Role
• All configuration is now unified under worker::prompt_types::Role

Built-in roles removed:

• Role::default() - removed
• Role::assistant() - removed
• Role::code_assistant() - removed

Migration:

// Before (v0.1.0)
let role = RoleConfig::default();

// After (v0.2.0)
use worker::prompt_types::Role;
let role = Role::new(
    "assistant",
    "A helpful AI assistant",
    "You are a helpful, harmless, and honest AI assistant."
);

2. Worker Construction - Builder Pattern

New Type-state Builder API:

Worker construction now uses a type-state builder pattern that enforces required parameters at compile time.

// Before (v0.1.0)
let worker = Worker::new(
    LlmProvider::Claude,
    "claude-3-sonnet-20240229",
    &api_keys,
    role,
    plugin_registry,
)?;

// After (v0.2.0)
let worker = Worker::builder()
    .provider(LlmProvider::Claude)
    .model("claude-3-sonnet-20240229")
    .api_keys(api_keys)
    .role(role)
    .build()?;

Required parameters (enforced at compile-time):

• provider(LlmProvider) - LLM provider
• model(&str) - Model name
• role(Role) - System role configuration

Optional parameters:

• api_keys(HashMap<String, String>) - API keys for providers
• plugin_id(&str) - Plugin identifier for custom providers
• plugin_registry(Arc<Mutex<PluginRegistry>>) - Plugin registry

3. WorkerError Redesign

Complete error type restructuring with structured error information:

Removed duplicate variants:

• ToolExecution (use ToolExecutionError)
• Config (use ConfigurationError)
• Serialization (use JsonError)

New structured error variants:

pub enum WorkerError {
    ToolExecutionError {
        tool_name: String,
        reason: String,
        source: Option<Box<dyn Error>>,
    },
    LlmApiError {
        provider: String,
        message: String,
        status_code: Option<u16>,
        source: Option<Box<dyn Error>>,
    },
    ConfigurationError {
        message: String,
        context: Option<String>,
        source: Option<Box<dyn Error>>,
    },
    ModelNotFound {
        provider: String,
        model_name: String,
    },
    Network {
        message: String,
        source: Option<Box<dyn Error>>,
    },
    JsonError(serde_json::Error),
    Other(String),
}

New helper methods for ergonomic error construction:

// Tool execution errors
WorkerError::tool_execution(tool_name, reason)
WorkerError::tool_execution_with_source(tool_name, reason, source)

// Configuration errors
WorkerError::config(message)
WorkerError::config_with_context(message, context)
WorkerError::config_with_source(message, source)

// LLM API errors
WorkerError::llm_api(provider, message)
WorkerError::llm_api_with_details(provider, message, status_code, source)

// Model errors
WorkerError::model_not_found(provider, model_name)

// Network errors
WorkerError::network(message)
WorkerError::network_with_source(message, source)

Migration:

// Before (v0.1.0)
return Err(WorkerError::ToolExecutionError(
    format!("Tool '{}' failed: {}", tool_name, reason)
));

// After (v0.2.0)
return Err(WorkerError::tool_execution(tool_name, reason));

// With source error
return Err(WorkerError::tool_execution_with_source(
    tool_name,
    reason,
    Box::new(source_error)
));

New Features

1. Plugin System

A new extensible plugin system for custom LLM providers:

Core Components:

• ProviderPlugin trait - Define custom LLM providers
• PluginRegistry - Manage plugin lifecycle
• PluginClient - Adapter for plugin-based clients
• PluginMetadata - Plugin identification and configuration

Example:

use worker::plugin::{ProviderPlugin, PluginRegistry};

// Register a plugin
let mut registry = PluginRegistry::new();
registry.register(Arc::new(CustomProviderPlugin::new()))?;

// Use plugin with Worker
let worker = Worker::builder()
    .provider(LlmProvider::OpenAI) // Base provider type
    .model("custom-model")
    .plugin_id("custom-provider")
    .plugin_registry(Arc::new(Mutex::new(registry)))
    .role(role)
    .build()?;

Plugin Features:

• Custom provider implementation
• API key validation
• Model listing
• Health checks
• Dynamic configuration schemas
• Optional dynamic library loading (#[cfg(feature = "dynamic-loading")])

2. Examples

New example files:

1. worker/examples/builder_basic.rs

   • Demonstrates the new builder pattern API
   • Shows basic Worker construction
   • Example tool registration

2. worker/examples/plugin_usage.rs

   • Plugin system usage example
   • Custom provider implementation
   • Plugin registration and usage

Improvements

Error Handling

1. Structured error information - All errors now carry contextual information (provider, tool name, status codes, etc.)
2. Error source tracking - #[source] attribute enables full error chain tracing
3. Automatic conversions - Added From implementations for common error types:
   • From<reqwest::Error> → Network error
   • From<std::io::Error> → ConfigurationError
   • From<serde_json::Error> → JsonError
   • From<Box<dyn Error>> → Other error

Code Organization

1. Eliminated duplicate types between worker-types and worker crates
2. Clearer separation of concerns - Role definition vs. PromptComposer execution
3. Consistent error construction - All error sites updated to use new helper methods

Files Changed

Modified (11 files):

• Cargo.lock - Dependency updates
• worker-types/src/lib.rs - Removed duplicate types
• worker/Cargo.toml - Version and dependency updates
• worker/src/config_parser.rs - Role type updates
• worker/src/lib.rs - Builder pattern, error handling updates
• worker/src/llm/gemini.rs - Error handling improvements
• worker/src/llm/ollama.rs - Error handling improvements
• worker/src/mcp_config.rs - Error handling updates
• worker/src/mcp_tool.rs - Error handling improvements
• worker/src/prompt_composer.rs - Role type imports
• worker/src/prompt_types.rs - PromptRoleConfig → Role rename
• worker/src/types.rs - Complete WorkerError redesign

Added (5 files):

• worker/src/builder.rs - Type-state builder implementation
• worker/src/plugin/mod.rs - Plugin system core
• worker/src/plugin/example_provider.rs - Example plugin implementation
• worker/examples/builder_basic.rs - Builder pattern example
• worker/examples/plugin_usage.rs - Plugin usage example

Renamed (1 file):

• worker/README.md → README.md - Moved to root

Migration Guide

Step 1: Update Role Construction

Replace all RoleConfig and built-in role usage:

// Remove old imports
// use worker::RoleConfig;

// Add new import
use worker::prompt_types::Role;

// Replace role construction
let role = Role::new(
    "your-role-name",
    "Role description",
    "Your system prompt template"
);

Step 2: Update Worker Construction

Replace direct Worker::new() calls with builder pattern:

let worker = Worker::builder()
    .provider(provider)
    .model(model_name)
    .api_keys(api_keys)
    .role(role)
    .build()?;

Step 3: Update Error Handling

Replace old error construction with new helper methods:

// Configuration errors
WorkerError::ConfigurationError("message".to_string())
// becomes:
WorkerError::config("message")

// Tool errors
WorkerError::ToolExecutionError(format!("..."))
// becomes:
WorkerError::tool_execution(tool_name, reason)

// Pattern matching
match error {
    WorkerError::ConfigurationError(msg) => { /* ... */ }
    // becomes:
    WorkerError::ConfigurationError { message, .. } => { /* ... */ }
}

Acknowledgments

This release includes significant API improvements based on architectural review and refactoring to improve type safety, error handling, and code maintainability.

Next Steps

See the examples in worker/examples/ for complete usage demonstrations:

• builder_basic.rs - Basic Worker construction
• plugin_usage.rs - Plugin system usage