# 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定義とシステムプロンプト生成関数の責務を分離
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