smart_prompt 0.5.0 → 0.5.1

data/docs/MONITORING_GUIDE.md

@@ -0,0 +1,278 @@
+# History Manager Monitoring Guide
+
+This guide explains the logging and monitoring features available in the SmartPrompt History Manager.
+
+## Overview
+
+The History Manager includes comprehensive logging and monitoring capabilities to help you:
+- Track system operations and performance
+- Debug context selection decisions
+- Monitor resource usage and cache efficiency
+- Export metrics for external monitoring systems
+
+## Configuration
+
+Enable monitoring in your configuration:
+
+```ruby
+config = {
+  monitoring: {
+    enabled: true,        # Enable/disable monitoring
+    log_level: :info      # Log level: :debug, :info, :warn, :error
+  }
+}
+
+manager = SmartPrompt::HistoryManager.new(config)
+```
+
+## Log Levels
+
+### INFO Level
+Logs important operations:
+- Session creation and deletion
+- Message additions
+- Context retrievals
+- Session clearing and exports
+- Cleanup operations
+
+Example:
+```
+[HistoryManager] Session user_123 created with config: max_messages=100, max_tokens=4000
+[HistoryManager] Message added to session user_123: role=user, tokens=15
+[HistoryManager] Session user_123 cleared: 10 -> 1 messages (keep_system=true)
+```
+
+### DEBUG Level
+Logs detailed information for debugging:
+- Cache hits and misses
+- Context selection decisions
+- Strategy selection in hybrid mode
+- Token trimming operations
+- Importance scores
+
+Example:
+```
+[HistoryManager] Session user_123 retrieved from cache
+[SlidingWindowStrategy] selected 5/10 messages (window_size=5, system=0, recent=5)
+[RelevanceBasedStrategy] calculated scores for 30 messages, top 5 scores: [0.85, 0.82, 0.79, 0.75, 0.72]
+[HybridStrategy] Adaptive mode: selected RelevanceBasedStrategy for 30 messages
+```
+
+### ERROR Level
+Logs errors with context:
+- Persistence failures
+- Compression errors
+- Operation failures
+
+Example:
+```
+[HistoryManager] Persistence failed for session user_123: Errno::ENOSPC - No space left on device
+[HistoryManager] Failed to add message to session user_123: ArgumentError - Invalid message format
+```
+
+## Statistics and Metrics
+
+### Session-Specific Statistics
+
+Get statistics for a specific session:
+
+```ruby
+stats = manager.get_stats("session_id")
+
+# Returns:
+{
+  session_id: "session_id",
+  message_count: 25,
+  total_tokens: 1500,
+  created_at: <Time>,
+  updated_at: <Time>,
+  config: { ... }
+}
+```
+
+### System-Wide Statistics
+
+Get statistics for all sessions:
+
+```ruby
+stats = manager.get_stats
+
+# Returns:
+{
+  # Session metrics
+  active_sessions: 10,
+  sessions_created: 50,
+  sessions_deleted: 40,
+  
+  # Message metrics
+  total_messages: 250,
+  messages_added: 300,
+  messages_per_session_avg: 25.0,
+  
+  # Token metrics
+  total_tokens: 15000,
+  tokens_per_session_avg: 1500.0,
+  tokens_per_message_avg: 60.0,
+  
+  # Cache metrics
+  cache_size: 100,
+  cache_hits: 850,
+  cache_misses: 150,
+  cache_hit_rate: 0.85,
+  
+  # Operation metrics
+  context_retrievals: 200,
+  
+  # Compression metrics
+  compression_operations: 5,
+  tokens_saved_by_compression: 5000,
+  
+  # Error metrics
+  persistence_errors: 2
+}
+```
+
+## Metrics Export
+
+Export metrics in various formats for integration with monitoring systems.
+
+### Prometheus Format
+
+```ruby
+metrics = manager.export_metrics(format: :prometheus)
+
+# Returns Prometheus-style metrics:
+# HELP smart_prompt_active_sessions Number of active sessions in cache
+# TYPE smart_prompt_active_sessions gauge
+smart_prompt_active_sessions 10
+
+# HELP smart_prompt_cache_hit_rate Cache hit rate (0.0-1.0)
+# TYPE smart_prompt_cache_hit_rate gauge
+smart_prompt_cache_hit_rate 0.85
+```
+
+### JSON Format
+
+```ruby
+metrics = manager.export_metrics(format: :json)
+
+# Returns JSON string with all metrics
+```
+
+### Hash Format
+
+```ruby
+metrics = manager.export_metrics(format: :hash)
+
+# Returns Ruby hash with all metrics
+```
+
+## Context Selection Debugging
+
+When debug logging is enabled, you can see detailed information about context selection:
+
+```ruby
+# Enable debug logging
+SmartPrompt.logger.level = Logger::DEBUG
+
+# Retrieve context
+context = manager.get_context("session_id", max_tokens: 1000)
+
+# Debug output shows:
+# - Which strategy was selected (for hybrid mode)
+# - How many messages were considered
+# - How many messages were selected
+# - Token counts before and after trimming
+# - Importance scores for relevance-based selection
+```
+
+## Performance Monitoring
+
+Track key performance indicators:
+
+```ruby
+stats = manager.get_stats
+
+# Cache efficiency
+cache_hit_rate = stats[:cache_hit_rate]
+puts "Cache hit rate: #{(cache_hit_rate * 100).round(2)}%"
+
+# Average resource usage
+avg_messages = stats[:messages_per_session_avg]
+avg_tokens = stats[:tokens_per_session_avg]
+puts "Avg messages per session: #{avg_messages.round(2)}"
+puts "Avg tokens per session: #{avg_tokens.round(2)}"
+
+# Compression effectiveness
+if stats[:compression_operations] > 0
+  tokens_saved = stats[:tokens_saved_by_compression]
+  puts "Tokens saved by compression: #{tokens_saved}"
+end
+```
+
+## Error Tracking
+
+Monitor errors to identify issues:
+
+```ruby
+stats = manager.get_stats
+
+if stats[:persistence_errors] > 0
+  puts "Warning: #{stats[:persistence_errors]} persistence errors occurred"
+  # Check logs for details
+end
+```
+
+## Best Practices
+
+1. **Use INFO level in production** - Provides good visibility without excessive logging
+2. **Use DEBUG level for troubleshooting** - Helps diagnose context selection issues
+3. **Monitor cache hit rate** - Low hit rates may indicate cache size is too small
+4. **Track compression metrics** - Verify compression is reducing token usage
+5. **Export metrics regularly** - Integrate with monitoring systems like Prometheus
+6. **Set up alerts** - Alert on high error rates or low cache hit rates
+
+## Example: Complete Monitoring Setup
+
+```ruby
+require 'smart_prompt'
+require 'logger'
+
+# Configure logger
+SmartPrompt.logger = Logger.new('history_manager.log')
+SmartPrompt.logger.level = Logger::INFO
+
+# Configure manager with monitoring
+config = {
+  cache_size: 100,
+  monitoring: {
+    enabled: true,
+    log_level: :info
+  }
+}
+
+manager = SmartPrompt::HistoryManager.new(config)
+
+# Use the manager
+manager.add_message("user_123", { role: "user", content: "Hello" })
+
+# Periodically export metrics
+Thread.new do
+  loop do
+    sleep 60  # Every minute
+    metrics = manager.export_metrics(format: :prometheus)
+    File.write('metrics.prom', metrics)
+  end
+end
+
+# Check statistics
+stats = manager.get_stats
+puts "Active sessions: #{stats[:active_sessions]}"
+puts "Cache hit rate: #{(stats[:cache_hit_rate] * 100).round(2)}%"
+```
+
+## See Also
+
+- [History Optimization Design Document](.kiro/specs/history-optimization/design.md)
+- [Monitoring Example](examples/monitoring_example.rb)
+- [History Manager Tests](test/monitoring_test.rb)

data/docs/MULTIMODAL_README.md

@@ -0,0 +1,265 @@
+# SmartPrompt 多模态功能扩展
+
+本文档介绍 SmartPrompt 新增的多模态功能，支持图像和视频分析。
+
+## 新增适配器
+
+### MultimodalAdapter
+
+新的 `MultimodalAdapter` 扩展了原有的 OpenAI 兼容适配器，支持 SiliconFlow 的多模态视觉模型。
+
+## 支持的功能
+
+### 1. 图像分析
+- 单张图像分析
+- 多张图像比较
+- 文档文字提取
+- 场景描述
+
+### 2. 视频分析
+- 视频内容理解
+- 帧提取控制
+- 时序分析
+
+### 3. 多模态对话
+- 图像+文本组合输入
+- 视频+文本组合输入
+- 多图像+文本组合输入
+
+## 快速开始
+
+### 1. 配置
+
+创建配置文件 `config/multimodal_config.yml`：
+
+```yaml
+adapters:
+  multimodal: "MultimodalAdapter"
+
+llms:
+  qwen_vl:
+    adapter: "multimodal"
+    url: "https://api.siliconflow.cn/v1/"
+    api_key: ENV["SILICONFLOW_API_KEY"]
+    default_model: "Qwen/Qwen2.5-VL-7B-Instruct"
+
+default_llm: "qwen_vl"
+```
+
+### 2. 创建工作流
+
+在 `workers/` 目录中创建工作流定义：
+
+```ruby
+# workers/multimodal_workers.rb
+SmartPrompt.define_worker :image_analyzer do
+  use "qwen_vl"
+  model "Qwen/Qwen2.5-VL-7B-Instruct"
+
+  messages = [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: params[:question] },
+        { type: "image_url", image_url: { url: params[:image_url], detail: "auto" } }
+      ]
+    }
+  ]
+
+  sys_msg("你是一个专业的图像分析助手。", params)
+  params.merge(messages: messages)
+  send_msg
+end
+```
+
+### 3. 使用示例
+
+```ruby
+require 'smart_prompt'
+
+# 初始化引擎
+engine = SmartPrompt::Engine.new('config/multimodal_config.yml')
+
+# 图像分析
+result = engine.call_worker(:image_analyzer, {
+  image_url: "https://example.com/image.jpg",
+  question: "描述这张图片的内容"
+})
+
+puts result
+```
+
+## API 参考
+
+### MultimodalAdapter 方法
+
+#### `analyze_image(image_input, prompt, model = nil, detail: "auto", max_tokens: nil)`
+
+分析单张图像。
+
+**参数：**
+- `image_input`: 图像 URL 或本地文件路径
+- `prompt`: 分析提示文本
+- `model`: 可选模型名称
+- `detail`: 图像细节级别（"low", "high", "auto"）
+- `max_tokens`: 最大输出 token 数
+
+#### `analyze_video(video_input, prompt, model = nil, max_frames: 10, fps: 1, detail: "auto")`
+
+分析视频内容。
+
+**参数：**
+- `video_input`: 视频 URL
+- `prompt`: 分析提示文本
+- `model`: 可选模型名称
+- `max_frames`: 最大提取帧数
+- `fps`: 帧率
+- `detail`: 细节级别
+
+#### `analyze_multiple_images(images, prompt, model = nil, detail: "auto")`
+
+分析多张图像。
+
+**参数：**
+- `images`: 图像 URL 数组
+- `prompt`: 分析提示文本
+- `model`: 可选模型名称
+- `detail`: 图像细节级别
+
+### 消息格式
+
+多模态消息使用标准 OpenAI 格式，支持 `image_url` 和 `video_url` 类型：
+
+```ruby
+messages = [
+  {
+    role: "user",
+    content: [
+      { type: "text", text: "分析这张图片" },
+      {
+        type: "image_url",
+        image_url: {
+          url: "https://example.com/image.jpg",
+          detail: "auto"
+        }
+      }
+    ]
+  }
+]
+```
+
+## 支持的多模态模型
+
+### SiliconFlow 支持的多模态模型
+
+- **Qwen2.5-VL 系列**: 视觉语言模型
+- **Qwen3-Omni 系列**: 全模态模型（视觉/音频/视频）
+- **DeepSeek-VL2**: 视觉语言模型
+- **GLM 系列**: 视觉语言模型
+
+## 配置参数
+
+### 图像参数
+
+- `detail`: 控制图像处理细节级别
+  - `"low"`: 低分辨率，更快处理
+  - `"high"`: 高分辨率，更准确
+  - `"auto"`: 自动选择（推荐）
+
+### 视频参数
+
+- `max_frames`: 从视频中提取的最大帧数
+- `fps`: 帧率，控制帧提取频率
+
+## 错误处理
+
+适配器包含完整的错误处理机制：
+
+- 网络连接错误
+- API 认证错误
+- 文件格式错误
+- 响应解析错误
+
+## 示例工作流
+
+### 1. 图像分析工作流
+
+```ruby
+SmartPrompt.define_worker :product_analyzer do
+  use "qwen_vl"
+  model "Qwen/Qwen2.5-VL-7B-Instruct"
+
+  messages = [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "分析这个产品图片，包括产品类型、颜色、特征和可能的用途" },
+        { type: "image_url", image_url: { url: params[:product_image], detail: "high" } }
+      ]
+    }
+  ]
+
+  sys_msg("你是一个专业的产品分析师。", params)
+  params.merge(messages: messages)
+  send_msg
+end
+```
+
+### 2. 视频摘要工作流
+
+```ruby
+SmartPrompt.define_worker :video_summarizer do
+  use "qwen_vl"
+  model "Qwen/Qwen2.5-VL-7B-Instruct"
+
+  messages = [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "请总结这个视频的主要内容" },
+        {
+          type: "video_url",
+          video_url: {
+            url: params[:video_url],
+            detail: "auto",
+            max_frames: params[:max_frames] || 20,
+            fps: params[:fps] || 2
+          }
+        }
+      ]
+    }
+  ]
+
+  sys_msg("你是一个专业的视频摘要助手。", params)
+  params.merge(messages: messages)
+  send_msg
+end
+```
+
+## 最佳实践
+
+1. **图像细节级别**: 对于文字提取使用 `"high"`，对于一般分析使用 `"auto"`
+2. **视频帧率**: 根据视频长度调整，长视频使用较低帧率
+3. **错误处理**: 总是包含适当的错误处理逻辑
+4. **API 限制**: 注意 SiliconFlow 的 API 调用限制
+
+## 故障排除
+
+### 常见问题
+
+1. **图像无法加载**: 检查 URL 可访问性或文件路径
+2. **视频处理超时**: 减少 `max_frames` 或降低 `fps`
+3. **API 认证失败**: 检查 API 密钥和环境变量
+4. **内存不足**: 减少同时处理的图像数量
+
+### 调试模式
+
+启用详细日志记录：
+
+```yaml
+logger_file: "./logs/smart_prompt.log"
+```
+
+## 扩展开发
+
+如需扩展更多多模态功能，可以参考现有的适配器架构，继承 `LLMAdapter` 类并实现相应的方法。

data/docs/RELEVANCE_BASED_STRATEGY_IMPLEMENTATION.md

@@ -0,0 +1,124 @@
+# RelevanceBasedStrategy Implementation Summary
+
+## Overview
+Successfully implemented the RelevanceBasedStrategy class for the SmartPrompt history optimization feature. This strategy selects messages based on a combination of recency and semantic relevance to the current message.
+
+## Implementation Details
+
+### Core Features Implemented
+1. **RelevanceBasedStrategy Class** (`lib/smart_prompt/relevance_based_strategy.rb`)
+   - Implements the ContextStrategy interface
+   - Configurable top-k message selection
+   - Weighted scoring combining recency and relevance
+   - Keyword-based similarity using Jaccard index
+   - Optional embedding-based similarity with fallback
+   - Token limit enforcement
+   - Temporal ordering preservation
+
+2. **Key Methods**
+   - `select_messages`: Main selection logic with relevance scoring
+   - `calculate_score`: Combines recency and relevance weights
+   - `calculate_keyword_similarity`: Jaccard similarity for text comparison
+   - `calculate_semantic_similarity`: Embedding-based similarity with error handling
+   - `cosine_similarity`: Vector similarity calculation
+   - `trim_to_token_limit`: Ensures token constraints are met
+   - `should_compress?`: Recommends compression at 3x top_k threshold
+
+3. **Configuration Options**
+   - `top_k`: Number of messages to select (default: 10)
+   - `recency_weight`: Weight for recency in scoring (default: 0.3)
+   - `relevance_weight`: Weight for relevance in scoring (default: 0.7)
+   - `embedding_service`: Optional service for semantic embeddings
+
+## Testing
+
+### Unit Tests (`test/relevance_based_strategy_test.rb`)
+- 17 test cases covering:
+  - Empty input handling
+  - Fallback to recency when no current message
+  - Relevance-based selection with current message
+  - Keyword similarity calculation
+  - Cosine similarity calculation
+  - Token limit enforcement
+  - Configuration options
+  - Error handling and edge cases
+
+### Integration Tests (`test/relevance_based_strategy_integration_test.rb`)
+- 5 test cases covering:
+  - Integration with Session class
+  - Token limit respect in real scenarios
+  - Empty session handling
+  - System message handling
+  - Compression threshold detection
+
+### Test Results
+- All 22 tests pass successfully
+- No diagnostics errors
+- Proper error handling verified
+
+## Example Usage
+
+```ruby
+# Create strategy with custom configuration
+strategy = SmartPrompt::RelevanceBasedStrategy.new(
+  top_k: 5,
+  recency_weight: 0.3,
+  relevance_weight: 0.7
+)
+
+# Select relevant messages
+current_message = SmartPrompt::Message.new(
+  role: "user",
+  content: "Tell me about neural networks"
+)
+
+selected = strategy.select_messages(
+  session.get_messages,
+  max_tokens: 100,
+  current_message: current_message
+)
+```
+
+## Requirements Validation
+
+All task requirements have been met:
+
+✅ **Requirement 6.1**: Context strategy parameter support
+✅ **Requirement 8.1**: Semantic importance-based prioritization
+✅ **Requirement 8.2**: Multiple strategy support
+✅ **Requirement 8.3**: Semantic importance scoring
+✅ **Requirement 10.2**: Semantically related message inclusion
+✅ **Requirement 10.5**: Vector similarity support (when embeddings available)
+
+## Files Created/Modified
+
+### Created
+- `lib/smart_prompt/relevance_based_strategy.rb` - Main implementation
+- `test/relevance_based_strategy_test.rb` - Unit tests
+- `test/relevance_based_strategy_integration_test.rb` - Integration tests
+- `examples/relevance_based_strategy_example.rb` - Usage example
+
+### Modified
+- `lib/smart_prompt.rb` - Added require statement for new strategy
+
+## Key Design Decisions
+
+1. **Keyword Similarity**: Uses Jaccard index for simple, effective text comparison
+2. **Fallback Mechanism**: Gracefully falls back to keyword similarity if embeddings fail
+3. **Temporal Ordering**: Maintains conversation flow by re-ordering selected messages by timestamp
+4. **Token Trimming**: Removes oldest messages first when enforcing token limits
+5. **Compression Threshold**: Recommends compression at 3x top_k to balance memory and quality
+
+## Performance Characteristics
+
+- **Time Complexity**: O(n log n) where n is message count (due to sorting)
+- **Space Complexity**: O(n) for scoring all messages
+- **Token Calculation**: Cached in Message objects for efficiency
+
+## Future Enhancements
+
+The implementation supports optional embedding services for more sophisticated semantic similarity. When an embedding service is provided, the strategy will use vector-based cosine similarity instead of keyword matching.
+
+## Conclusion
+
+The RelevanceBasedStrategy is fully implemented, tested, and integrated into the SmartPrompt framework. It provides intelligent message selection based on semantic relevance, making it ideal for complex discussions where context matters more than simple recency.