Initial project setup: Obsidian intelligent journal organizer
- Add core agent architecture with Command + Skill pattern - Implement Claude API integration for content analysis - Add Obsidian REST API integration for vault operations - Create conversational interface (v2.0) with natural language processing - Add comprehensive configuration management and validation - Include project documentation and developer guides - Set up testing framework with unit, integration, and property tests - Add Kiro specs for Claude API configuration and code quality improvements - Configure project steering files for development guidelines
This commit is contained in:
windyboy
@@ -0,0 +1,387 @@
|
||||
# Design Document
|
||||
|
||||
## Overview
|
||||
|
||||
This design enhances the Claude API configuration system in the Obsidian journal organizer to support custom API URLs and comprehensive model selection. The enhancement maintains backward compatibility while providing flexibility for users to connect to different Claude API endpoints, including proxy servers, regional endpoints, and custom deployments. The design follows the existing configuration patterns and integrates seamlessly with the current Command + Skill architecture.
|
||||
|
||||
## Architecture
|
||||
|
||||
The configuration enhancement will extend the existing YAML-based configuration system with:
|
||||
|
||||
1. **Flexible API URL Configuration**: Support for custom Claude API endpoints
|
||||
2. **Enhanced Model Validation**: Comprehensive model name validation and suggestions
|
||||
3. **Environment Variable Integration**: Full support for environment-based configuration
|
||||
4. **Backward Compatibility Layer**: Seamless migration from existing configurations
|
||||
5. **Configuration Validation Framework**: Robust validation with helpful error messages
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
### Enhanced Claude Configuration Schema
|
||||
|
||||
```python
|
||||
from typing import Optional, Dict, Any, List
|
||||
from pydantic import BaseModel, validator, Field
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
class ClaudeAPIConfig(BaseModel):
|
||||
"""Enhanced Claude API configuration with URL and model validation"""
|
||||
|
||||
api_key: str = Field(..., min_length=1, description="Claude API key")
|
||||
api_url: Optional[str] = Field(
|
||||
default="https://api.anthropic.com",
|
||||
description="Claude API base URL"
|
||||
)
|
||||
model: str = Field(
|
||||
default="claude-3-5-sonnet-20241022",
|
||||
description="Claude model name"
|
||||
)
|
||||
max_tokens: int = Field(default=4096, ge=1, le=200000)
|
||||
temperature: float = Field(default=0.7, ge=0.0, le=1.0)
|
||||
|
||||
@validator('api_url')
|
||||
def validate_api_url(cls, v: Optional[str]) -> str:
|
||||
"""Validate API URL format and accessibility"""
|
||||
if v is None:
|
||||
return "https://api.anthropic.com"
|
||||
|
||||
# Parse URL to validate format
|
||||
parsed = urlparse(v)
|
||||
if not parsed.scheme or not parsed.netloc:
|
||||
raise ValueError(f"Invalid URL format: {v}")
|
||||
|
||||
if parsed.scheme not in ['http', 'https']:
|
||||
raise ValueError(f"URL must use http or https protocol: {v}")
|
||||
|
||||
# Remove trailing slash for consistency
|
||||
return v.rstrip('/')
|
||||
|
||||
@validator('model')
|
||||
def validate_model_name(cls, v: str) -> str:
|
||||
"""Validate Claude model name and provide suggestions"""
|
||||
valid_models = [
|
||||
# Claude 3 series
|
||||
"claude-3-opus-20240229",
|
||||
"claude-3-sonnet-20240229",
|
||||
"claude-3-haiku-20240307",
|
||||
# Claude 3.5 series
|
||||
"claude-3-5-sonnet-20241022",
|
||||
"claude-3-5-haiku-20241022",
|
||||
# Latest aliases
|
||||
"claude-3-opus-latest",
|
||||
"claude-3-sonnet-latest",
|
||||
"claude-3-haiku-latest",
|
||||
"claude-3-5-sonnet-latest",
|
||||
"claude-3-5-haiku-latest"
|
||||
]
|
||||
|
||||
if v not in valid_models:
|
||||
# Check if it follows Claude naming pattern
|
||||
claude_pattern = r'^claude-\d+(\.\d+)?-(opus|sonnet|haiku)(-\d{8}|-latest)?$'
|
||||
if not re.match(claude_pattern, v, re.IGNORECASE):
|
||||
suggestions = ", ".join(valid_models[:5])
|
||||
raise ValueError(
|
||||
f"Invalid model name: {v}. "
|
||||
f"Valid models include: {suggestions}. "
|
||||
f"Model names should follow pattern: claude-X-Y-YYYYMMDD or claude-X-Y-latest"
|
||||
)
|
||||
|
||||
return v
|
||||
```
|
||||
|
||||
### Configuration Loading and Environment Variable Support
|
||||
|
||||
```python
|
||||
import os
|
||||
import re
|
||||
from typing import Any, Dict
|
||||
import yaml
|
||||
|
||||
class ConfigurationLoader:
|
||||
"""Enhanced configuration loader with environment variable expansion"""
|
||||
|
||||
@staticmethod
|
||||
def expand_environment_variables(config_dict: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Recursively expand environment variables in configuration"""
|
||||
|
||||
def expand_value(value: Any) -> Any:
|
||||
if isinstance(value, str):
|
||||
# Handle ${VAR} and ${VAR:-default} patterns
|
||||
pattern = r'\$\{([^}]+)\}'
|
||||
|
||||
def replace_env_var(match):
|
||||
var_expr = match.group(1)
|
||||
if ':-' in var_expr:
|
||||
var_name, default_value = var_expr.split(':-', 1)
|
||||
return os.getenv(var_name.strip(), default_value)
|
||||
else:
|
||||
var_name = var_expr.strip()
|
||||
env_value = os.getenv(var_name)
|
||||
if env_value is None:
|
||||
raise ValueError(
|
||||
f"Environment variable '{var_name}' is not set. "
|
||||
f"Please set it or provide a default value using ${{{var_name}:-default}}"
|
||||
)
|
||||
return env_value
|
||||
|
||||
return re.sub(pattern, replace_env_var, value)
|
||||
|
||||
elif isinstance(value, dict):
|
||||
return {k: expand_value(v) for k, v in value.items()}
|
||||
elif isinstance(value, list):
|
||||
return [expand_value(item) for item in value]
|
||||
else:
|
||||
return value
|
||||
|
||||
return expand_value(config_dict)
|
||||
|
||||
@classmethod
|
||||
def load_config(cls, config_path: str) -> Dict[str, Any]:
|
||||
"""Load and validate configuration with environment variable expansion"""
|
||||
try:
|
||||
with open(config_path, 'r', encoding='utf-8') as f:
|
||||
config_dict = yaml.safe_load(f)
|
||||
|
||||
# Expand environment variables
|
||||
config_dict = cls.expand_environment_variables(config_dict)
|
||||
|
||||
return config_dict
|
||||
|
||||
except FileNotFoundError:
|
||||
raise ConfigurationError(f"Configuration file not found: {config_path}")
|
||||
except yaml.YAMLError as e:
|
||||
raise ConfigurationError(f"Invalid YAML in configuration file: {e}")
|
||||
except ValueError as e:
|
||||
raise ConfigurationError(f"Environment variable error: {e}")
|
||||
```
|
||||
|
||||
### Enhanced Claude API Client
|
||||
|
||||
```python
|
||||
import aiohttp
|
||||
import ssl
|
||||
from typing import Optional, Dict, Any
|
||||
from contextlib import asynccontextmanager
|
||||
|
||||
class ClaudeAPIClient:
|
||||
"""Enhanced Claude API client with configurable endpoint support"""
|
||||
|
||||
def __init__(self, config: ClaudeAPIConfig):
|
||||
self.config = config
|
||||
self.base_url = config.api_url
|
||||
self.api_key = config.api_key
|
||||
self.model = config.model
|
||||
|
||||
@asynccontextmanager
|
||||
async def create_session(self):
|
||||
"""Create HTTP session with proper configuration"""
|
||||
headers = {
|
||||
'Authorization': f'Bearer {self.api_key}',
|
||||
'Content-Type': 'application/json',
|
||||
'User-Agent': 'journal-organizer/1.0'
|
||||
}
|
||||
|
||||
# Configure SSL context for custom endpoints
|
||||
ssl_context = ssl.create_default_context()
|
||||
if self.base_url.startswith('https://localhost') or 'localhost' in self.base_url:
|
||||
ssl_context.check_hostname = False
|
||||
ssl_context.verify_mode = ssl.CERT_NONE
|
||||
|
||||
connector = aiohttp.TCPConnector(ssl=ssl_context)
|
||||
|
||||
async with aiohttp.ClientSession(
|
||||
connector=connector,
|
||||
headers=headers,
|
||||
timeout=aiohttp.ClientTimeout(total=60)
|
||||
) as session:
|
||||
yield session
|
||||
|
||||
async def validate_connection(self) -> bool:
|
||||
"""Validate API connection and credentials"""
|
||||
try:
|
||||
async with self.create_session() as session:
|
||||
# Try a simple API call to validate connection
|
||||
url = f"{self.base_url}/v1/messages"
|
||||
payload = {
|
||||
"model": self.model,
|
||||
"max_tokens": 10,
|
||||
"messages": [{"role": "user", "content": "test"}]
|
||||
}
|
||||
|
||||
async with session.post(url, json=payload) as response:
|
||||
if response.status == 401:
|
||||
raise APIError("Invalid API key or unauthorized access")
|
||||
elif response.status == 404:
|
||||
raise APIError(f"API endpoint not found. Check if {self.base_url} is correct")
|
||||
elif response.status >= 400:
|
||||
error_text = await response.text()
|
||||
raise APIError(f"API error ({response.status}): {error_text}")
|
||||
|
||||
return True
|
||||
|
||||
except aiohttp.ClientError as e:
|
||||
raise APIError(f"Connection error to {self.base_url}: {str(e)}")
|
||||
```
|
||||
|
||||
## Data Models
|
||||
|
||||
### Configuration Migration Support
|
||||
|
||||
```python
|
||||
class ConfigurationMigrator:
|
||||
"""Handle migration from legacy configuration formats"""
|
||||
|
||||
@staticmethod
|
||||
def migrate_claude_config(config_dict: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Migrate legacy Claude configuration to new format"""
|
||||
claude_config = config_dict.get('claude', {})
|
||||
|
||||
# Add default api_url if not present
|
||||
if 'api_url' not in claude_config:
|
||||
claude_config['api_url'] = "https://api.anthropic.com"
|
||||
|
||||
# Ensure model has a default value
|
||||
if 'model' not in claude_config:
|
||||
claude_config['model'] = "claude-3-5-sonnet-20241022"
|
||||
|
||||
# Migrate old model names to new format if needed
|
||||
model_migrations = {
|
||||
"claude-3-sonnet": "claude-3-sonnet-20240229",
|
||||
"claude-3-opus": "claude-3-opus-20240229",
|
||||
"claude-3-haiku": "claude-3-haiku-20240307"
|
||||
}
|
||||
|
||||
if claude_config['model'] in model_migrations:
|
||||
old_model = claude_config['model']
|
||||
new_model = model_migrations[old_model]
|
||||
claude_config['model'] = new_model
|
||||
print(f"INFO: Migrated model '{old_model}' to '{new_model}'")
|
||||
|
||||
config_dict['claude'] = claude_config
|
||||
return config_dict
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Comprehensive Error Management
|
||||
|
||||
```python
|
||||
class ClaudeConfigurationError(ConfigurationError):
|
||||
"""Specific error for Claude API configuration issues"""
|
||||
pass
|
||||
|
||||
class ModelValidationError(ClaudeConfigurationError):
|
||||
"""Error for invalid model names with suggestions"""
|
||||
|
||||
def __init__(self, message: str, suggestions: List[str] = None):
|
||||
super().__init__(message)
|
||||
self.suggestions = suggestions or []
|
||||
|
||||
class APIConnectionError(ClaudeConfigurationError):
|
||||
"""Error for API connection issues"""
|
||||
pass
|
||||
|
||||
def validate_claude_configuration(config: Dict[str, Any]) -> ClaudeAPIConfig:
|
||||
"""Validate Claude configuration with helpful error messages"""
|
||||
try:
|
||||
claude_config = config.get('claude', {})
|
||||
return ClaudeAPIConfig(**claude_config)
|
||||
|
||||
except ValidationError as e:
|
||||
# Transform pydantic errors into user-friendly messages
|
||||
error_messages = []
|
||||
for error in e.errors():
|
||||
field = error['loc'][0] if error['loc'] else 'configuration'
|
||||
message = error['msg']
|
||||
|
||||
if field == 'api_url':
|
||||
error_messages.append(
|
||||
f"Invalid API URL: {message}. "
|
||||
f"Please provide a valid HTTP/HTTPS URL like 'https://api.anthropic.com'"
|
||||
)
|
||||
elif field == 'model':
|
||||
error_messages.append(
|
||||
f"Invalid model name: {message}"
|
||||
)
|
||||
else:
|
||||
error_messages.append(f"Invalid {field}: {message}")
|
||||
|
||||
raise ClaudeConfigurationError(
|
||||
f"Claude configuration errors:\n" + "\n".join(f"- {msg}" for msg in error_messages)
|
||||
)
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Dual Testing Approach
|
||||
|
||||
The testing strategy combines unit tests for specific functionality with property-based tests for comprehensive validation:
|
||||
|
||||
**Unit Tests:**
|
||||
- Test configuration loading with various URL formats
|
||||
- Test model name validation with valid and invalid inputs
|
||||
- Test environment variable expansion with different patterns
|
||||
- Test backward compatibility with legacy configurations
|
||||
- Mock API calls to test connection validation
|
||||
|
||||
**Property-Based Tests:**
|
||||
- Validate that all valid URL formats are accepted
|
||||
- Test that model name validation works across all valid model patterns
|
||||
- Verify environment variable expansion handles all supported formats
|
||||
- Ensure configuration migration preserves all existing functionality
|
||||
|
||||
**Testing Framework:**
|
||||
- Use `pytest` for unit testing framework
|
||||
- Use `hypothesis` for property-based testing
|
||||
- Configure tests to run minimum 100 iterations per property test
|
||||
- Tag each property test with: **Feature: claude-api-configuration, Property {number}: {property_text}**
|
||||
|
||||
Now I need to use the prework tool to analyze the acceptance criteria before writing the correctness properties:
|
||||
|
||||
## Correctness Properties
|
||||
|
||||
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
||||
|
||||
### Property 1: Configuration Field Support
|
||||
*For any* configuration dictionary containing claude section fields (api_url, model), the system should successfully parse and store these values in the configuration object
|
||||
**Validates: Requirements 1.1, 2.1**
|
||||
|
||||
### Property 2: URL Validation and Error Handling
|
||||
*For any* URL string provided as api_url, the system should validate proper URL format, reject malformed URLs with specific error messages, and accept valid HTTP/HTTPS URLs
|
||||
**Validates: Requirements 1.4, 1.5, 4.1**
|
||||
|
||||
### Property 3: Model Name Validation with Suggestions
|
||||
*For any* model name string, the system should validate Claude naming conventions, accept all supported model variants, and provide helpful suggestions when invalid model names are provided
|
||||
**Validates: Requirements 2.2, 2.3, 2.4, 4.2**
|
||||
|
||||
### Property 4: Default Value Behavior
|
||||
*For any* configuration missing api_url or model fields, the system should use appropriate default values (default Anthropic API URL and sensible default model) without errors
|
||||
**Validates: Requirements 1.2, 2.5**
|
||||
|
||||
### Property 5: Custom Configuration Usage
|
||||
*For any* valid custom api_url or model specified in configuration, the system should use these values in API client initialization and requests
|
||||
**Validates: Requirements 1.3**
|
||||
|
||||
### Property 6: Environment Variable Expansion
|
||||
*For any* configuration value containing environment variable references, the system should correctly expand variables for both api_url and model fields, and validate expanded values the same as direct configuration
|
||||
**Validates: Requirements 5.1, 5.2, 5.4, 5.5**
|
||||
|
||||
### Property 7: Environment Variable Error Handling
|
||||
*For any* undefined environment variable referenced in configuration, the system should provide clear error messages indicating which variables are missing
|
||||
**Validates: Requirements 5.3**
|
||||
|
||||
### Property 8: Backward Compatibility
|
||||
*For any* legacy configuration format, the system should load successfully, maintain existing functionality, and provide informational messages about new options without breaking changes
|
||||
**Validates: Requirements 3.1, 3.2, 3.3, 3.4**
|
||||
|
||||
### Property 9: API Connection Validation
|
||||
*For any* API configuration (URL and credentials), the system should validate connectivity when possible and provide clear authentication error messages for invalid credentials
|
||||
**Validates: Requirements 4.3, 4.4**
|
||||
|
||||
### Property 10: Comprehensive Error Messaging
|
||||
*For any* configuration validation failure, the system should provide helpful error messages with corrective suggestions, appropriate logging, and references to documentation where applicable
|
||||
**Validates: Requirements 4.5, 6.3, 6.4**
|
||||
|
||||
### Property-Based Testing Configuration
|
||||
|
||||
Each property test will be tagged with comments referencing the design document property and run with sufficient iterations to catch edge cases through randomization. Tests will use the `hypothesis` library for property-based testing with minimum 100 iterations per test.
|
||||
@@ -0,0 +1,87 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
This specification addresses the need to enhance Claude API configuration flexibility in the Obsidian journal organizer project. Currently, the system has limited Claude API configuration options, lacking support for custom API URLs and comprehensive model selection. This enhancement will provide users with greater flexibility to use different Claude API endpoints and models based on their specific needs and deployment scenarios.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **System**: The Obsidian journal organizer application
|
||||
- **Claude_API**: Anthropic's Claude AI service API
|
||||
- **API_URL**: The base URL endpoint for Claude API requests
|
||||
- **Model_Name**: The specific Claude model identifier (e.g., claude-3-5-sonnet-20241022)
|
||||
- **Configuration**: YAML-based settings that control system behavior
|
||||
- **API_Client**: The component responsible for making requests to Claude API
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: Add Claude API URL Configuration
|
||||
|
||||
**User Story:** As a user, I want to configure a custom Claude API URL, so that I can use different Claude API endpoints including proxy servers, regional endpoints, or custom deployments.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Configuration SHALL support a configurable api_url field in the claude section
|
||||
2. WHEN api_url is not specified, THE System SHALL use the default Anthropic API URL
|
||||
3. WHEN api_url is specified, THE System SHALL use the custom URL for all Claude API requests
|
||||
4. THE System SHALL validate that the api_url follows proper URL format
|
||||
5. WHEN the api_url is invalid, THE System SHALL provide clear error messages during configuration validation
|
||||
|
||||
### Requirement 2: Enhance Model Name Configuration
|
||||
|
||||
**User Story:** As a user, I want flexible model name configuration with validation, so that I can easily switch between different Claude models and get clear feedback when using unsupported models.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Configuration SHALL support model name specification in the claude section
|
||||
2. THE System SHALL validate that the specified model name follows Claude model naming conventions
|
||||
3. WHEN an invalid model name is provided, THE System SHALL provide helpful suggestions for valid model names
|
||||
4. THE System SHALL support all current Claude model variants (claude-3-5-sonnet, claude-3-haiku, claude-3-opus)
|
||||
5. WHEN model configuration is missing, THE System SHALL use a sensible default model
|
||||
|
||||
### Requirement 3: Maintain Backward Compatibility
|
||||
|
||||
**User Story:** As an existing user, I want my current configuration to continue working, so that I don't need to modify my setup when upgrading.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN existing configuration files lack api_url, THE System SHALL use default values without errors
|
||||
2. WHEN existing configuration files use the current model format, THE System SHALL continue to work unchanged
|
||||
3. THE System SHALL not break existing functionality when new configuration options are added
|
||||
4. WHEN loading legacy configuration, THE System SHALL provide informational messages about new available options
|
||||
|
||||
### Requirement 4: Configuration Validation and Error Handling
|
||||
|
||||
**User Story:** As a user, I want clear validation and error messages for Claude API configuration, so that I can quickly identify and fix configuration issues.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN the api_url is malformed, THE System SHALL provide specific error messages indicating the URL format issue
|
||||
2. WHEN the model name is invalid, THE System SHALL suggest valid alternatives
|
||||
3. THE System SHALL validate API connectivity during startup when possible
|
||||
4. WHEN API credentials are invalid for the specified endpoint, THE System SHALL provide clear authentication error messages
|
||||
5. THE System SHALL log configuration validation results at appropriate levels
|
||||
|
||||
### Requirement 5: Environment Variable Support
|
||||
|
||||
**User Story:** As a developer, I want to use environment variables for Claude API configuration, so that I can manage different environments and keep sensitive configuration out of files.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE System SHALL support environment variable expansion for api_url configuration
|
||||
2. THE System SHALL support environment variable expansion for model name configuration
|
||||
3. WHEN environment variables are undefined, THE System SHALL provide clear error messages
|
||||
4. THE System SHALL support mixed configuration (some values from files, some from environment)
|
||||
5. WHEN using environment variables, THE System SHALL validate expanded values the same as direct configuration
|
||||
|
||||
### Requirement 6: Documentation and Examples
|
||||
|
||||
**User Story:** As a user, I want clear documentation and examples for Claude API configuration, so that I can understand how to use the new configuration options.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Configuration example file SHALL include api_url configuration with comments
|
||||
2. THE Configuration example file SHALL include model name options with descriptions
|
||||
3. THE System SHALL provide helpful error messages that reference documentation
|
||||
4. WHEN configuration validation fails, THE System SHALL suggest corrective actions
|
||||
5. THE Documentation SHALL include examples for common use cases (proxy servers, different regions)
|
||||
@@ -0,0 +1,169 @@
|
||||
# Implementation Plan: Claude API Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
This implementation plan enhances the Claude API configuration system to support custom API URLs and comprehensive model selection. The approach maintains backward compatibility while adding flexible configuration options through systematic enhancement of the existing configuration framework.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [-] 1. Enhance Configuration Schema and Validation
|
||||
- [x] 1.1 Create enhanced ClaudeAPIConfig model with pydantic
|
||||
- Add api_url field with URL validation
|
||||
- Add comprehensive model name validation with suggestions
|
||||
- Implement field validators for URL format and model naming conventions
|
||||
- _Requirements: 1.1, 1.4, 2.1, 2.2_
|
||||
|
||||
- [ ]* 1.2 Write property test for configuration field support
|
||||
- **Property 1: Configuration Field Support**
|
||||
- **Validates: Requirements 1.1, 2.1**
|
||||
|
||||
- [ ]* 1.3 Write property test for URL validation
|
||||
- **Property 2: URL Validation and Error Handling**
|
||||
- **Validates: Requirements 1.4, 1.5, 4.1**
|
||||
|
||||
- [ ]* 1.4 Write property test for model validation
|
||||
- **Property 3: Model Name Validation with Suggestions**
|
||||
- **Validates: Requirements 2.2, 2.3, 2.4, 4.2**
|
||||
|
||||
- [x] 2. Implement Environment Variable Support
|
||||
- [x] 2.1 Create ConfigurationLoader with environment variable expansion
|
||||
- Implement ${VAR} and ${VAR:-default} pattern support
|
||||
- Add recursive expansion for nested configuration values
|
||||
- Handle missing environment variables with clear error messages
|
||||
- _Requirements: 5.1, 5.2, 5.3_
|
||||
|
||||
- [x] 2.2 Integrate environment variable expansion into config loading
|
||||
- Update existing configuration loading to use new expansion system
|
||||
- Ensure validation works on expanded values
|
||||
- _Requirements: 5.4, 5.5_
|
||||
|
||||
- [ ]* 2.3 Write property test for environment variable expansion
|
||||
- **Property 6: Environment Variable Expansion**
|
||||
- **Validates: Requirements 5.1, 5.2, 5.4, 5.5**
|
||||
|
||||
- [ ]* 2.4 Write property test for environment variable error handling
|
||||
- **Property 7: Environment Variable Error Handling**
|
||||
- **Validates: Requirements 5.3**
|
||||
|
||||
- [-] 3. Implement Default Value Handling
|
||||
- [x] 3.1 Add default value logic to configuration loading
|
||||
- Set default api_url to "https://api.anthropic.com"
|
||||
- Set default model to "claude-3-5-sonnet-20241022"
|
||||
- Ensure defaults are applied when fields are missing
|
||||
- _Requirements: 1.2, 2.5_
|
||||
|
||||
- [ ]* 3.2 Write property test for default value behavior
|
||||
- **Property 4: Default Value Behavior**
|
||||
- **Validates: Requirements 1.2, 2.5**
|
||||
|
||||
- [x] 4. Enhance Claude API Client
|
||||
- [x] 4.1 Update ClaudeAPIClient to use configurable URL
|
||||
- Modify client initialization to accept custom api_url
|
||||
- Update all API request methods to use configured base URL
|
||||
- Add SSL context handling for localhost and custom endpoints
|
||||
- _Requirements: 1.3_
|
||||
|
||||
- [x] 4.2 Add API connection validation
|
||||
- Implement validate_connection method for testing API connectivity
|
||||
- Add authentication error detection and clear error messages
|
||||
- Handle different types of API errors (404, 401, etc.)
|
||||
- _Requirements: 4.3, 4.4_
|
||||
|
||||
- [ ]* 4.3 Write property test for custom configuration usage
|
||||
- **Property 5: Custom Configuration Usage**
|
||||
- **Validates: Requirements 1.3**
|
||||
|
||||
- [ ]* 4.4 Write property test for API connection validation
|
||||
- **Property 9: API Connection Validation**
|
||||
- **Validates: Requirements 4.3, 4.4**
|
||||
|
||||
- [x] 5. Implement Backward Compatibility
|
||||
- [x] 5.1 Create ConfigurationMigrator for legacy support
|
||||
- Add migration logic for configurations missing new fields
|
||||
- Implement model name migration for old format names
|
||||
- Add informational logging for migration actions
|
||||
- _Requirements: 3.1, 3.2, 3.4_
|
||||
|
||||
- [x] 5.2 Integrate migration into configuration loading process
|
||||
- Apply migration before validation
|
||||
- Ensure existing functionality remains unchanged
|
||||
- _Requirements: 3.3_
|
||||
|
||||
- [ ]* 5.3 Write property test for backward compatibility
|
||||
- **Property 8: Backward Compatibility**
|
||||
- **Validates: Requirements 3.1, 3.2, 3.3, 3.4**
|
||||
|
||||
- [x] 6. Enhance Error Handling and Messaging
|
||||
- [x] 6.1 Implement comprehensive error handling framework
|
||||
- Create ClaudeConfigurationError and related exception classes
|
||||
- Add user-friendly error message transformation
|
||||
- Include corrective suggestions in error messages
|
||||
- _Requirements: 4.1, 4.2, 6.3, 6.4_
|
||||
|
||||
- [x] 6.2 Add configuration validation logging
|
||||
- Implement appropriate logging levels for validation results
|
||||
- Add debug logging for configuration loading steps
|
||||
- _Requirements: 4.5_
|
||||
|
||||
- [ ]* 6.3 Write property test for error messaging
|
||||
- **Property 10: Comprehensive Error Messaging**
|
||||
- **Validates: Requirements 4.5, 6.3, 6.4**
|
||||
|
||||
- [x] 7. Update Configuration Files and Documentation
|
||||
- [x] 7.1 Update config.example.yaml with new options
|
||||
- Add api_url configuration with comments and examples
|
||||
- Add model name options with descriptions
|
||||
- Include examples for common use cases (proxy servers, regions)
|
||||
- _Requirements: 6.1, 6.2, 6.5_
|
||||
|
||||
- [x] 7.2 Update existing Skills to use enhanced configuration
|
||||
- Modify ClaudeAnalyzeSkill and ClaudeTransformSkill to use new config
|
||||
- Ensure all Claude API interactions use the enhanced client
|
||||
- _Requirements: 1.3_
|
||||
|
||||
- [x] 8. Integration and Testing
|
||||
- [x] 8.1 Create comprehensive unit tests
|
||||
- Test configuration loading with various scenarios
|
||||
- Test error handling for invalid configurations
|
||||
- Test migration from legacy configurations
|
||||
- _Requirements: All_
|
||||
|
||||
- [x] 8.2 Create integration tests
|
||||
- Test Skills with different Claude API configurations
|
||||
- Test environment variable scenarios
|
||||
- Test backward compatibility with existing setups
|
||||
- _Requirements: 3.1, 3.2, 5.4_
|
||||
|
||||
- [x] 9. Checkpoint - Ensure all tests pass
|
||||
- Ensure all tests pass, ask the user if questions arise.
|
||||
|
||||
- [x] 10. Final Integration and Validation
|
||||
- [x] 10.1 Test with real API endpoints
|
||||
- Validate with default Anthropic API
|
||||
- Test with proxy server configurations
|
||||
- Verify different model selections work correctly
|
||||
- _Requirements: 1.3, 2.4_
|
||||
|
||||
- [x] 10.2 Validate backward compatibility
|
||||
- Test existing configuration files continue to work
|
||||
- Verify no breaking changes to existing functionality
|
||||
- Test migration messages are appropriate
|
||||
- _Requirements: 3.1, 3.2, 3.3, 3.4_
|
||||
|
||||
- [x] 10.3 Update documentation and troubleshooting guides
|
||||
- Add configuration examples for common scenarios
|
||||
- Update troubleshooting guide with new error messages
|
||||
- Document environment variable usage patterns
|
||||
- _Requirements: 6.3, 6.4, 6.5_
|
||||
|
||||
- [ ] 11. Final checkpoint - Ensure all tests pass
|
||||
- Ensure all tests pass, ask the user if questions arise.
|
||||
|
||||
## Notes
|
||||
|
||||
- Tasks marked with `*` are optional and can be skipped for faster MVP
|
||||
- Each task references specific requirements for traceability
|
||||
- Checkpoints ensure incremental validation
|
||||
- Property tests validate universal correctness properties
|
||||
- Unit tests validate specific examples and edge cases
|
||||
- Focus on maintaining backward compatibility throughout implementation
|
||||
Reference in New Issue
Block a user