633 lines
17 KiB
Markdown
633 lines
17 KiB
Markdown
# 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:**
|
|
```rust
|
|
// 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.
|
|
|
|
```rust
|
|
// 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:**
|
|
|
|
```rust
|
|
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:**
|
|
|
|
```rust
|
|
// 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:**
|
|
```rust
|
|
// 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:**
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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:**
|
|
```rust
|
|
// 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.
|
|
|
|
```rust
|
|
// 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:**
|
|
|
|
```rust
|
|
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:**
|
|
|
|
```rust
|
|
// 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:**
|
|
```rust
|
|
// 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:**
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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
|