smart_prompt 0.4.4 → 0.5.1

data/config/sensenova_config.yml

@@ -0,0 +1,63 @@
+# SenseNova (商汤 日日新) Configuration for SmartPrompt
+#
+# Get an API key from https://platform.sensenova.cn/console and export it as
+# SENSENOVA_API_KEY. A single SenseNovaAdapter covers all four model categories —
+# just point a different llm entry at each model.
+#
+# Two base hosts are in play (verified 2026-06-19):
+#   * token.sensenova.cn/v1          — the free-tier models (sensenova-6.7-flash-lite
+#                                       chat/vision, sensenova-u1-fast image). Works
+#                                       out-of-the-box with a free key.
+#   * api.sensenova.cn/compatible-mode/v2 — paid models (SenseChat-5, SenseNova-V6-Pro).
+#                                       Returns 403 if your key lacks that model.
+#   * api.sensenova.cn/v1/llm/embeddings — Cupido embeddings (native; paid).
+#
+# The image endpoint is NOT under compatible-mode (it 404s there) — it lives on
+# token.sensenova.cn/v1/images/generations and only accepts specific sizes
+# (see VALID_IMAGE_SIZES in sensenova_adapter.rb; default 2048x2048).
+
+adapters:
+  sensenova: "SenseNovaAdapter"
+
+llms:
+  # 1. 商量 文本对话 (free-tier; works with a free key)
+  sensechat:
+    adapter: "sensenova"
+    url: "https://token.sensenova.cn/v1"
+    api_key: ENV["SENSENOVA_API_KEY"]
+    model: "sensenova-6.7-flash-lite"
+    temperature: 0.7
+    # Optional SenseNova sampling extras (forwarded to /chat/completions):
+    # reasoning_effort: "medium"
+    # max_completion_tokens: 4096
+    # Paid alternative: url https://api.sensenova.cn/compatible-mode/v2, model SenseChat-5
+
+  # 2. 商量 图文多模态 (sensenova-6.7-flash-lite is natively multimodal)
+  sensevision:
+    adapter: "sensenova"
+    url: "https://token.sensenova.cn/v1"
+    api_key: ENV["SENSENOVA_API_KEY"]
+    model: "sensenova-6.7-flash-lite"
+    # Paid alternative: url https://api.sensenova.cn/compatible-mode/v2, model SenseNova-V6-Pro
+
+  # 3. Cupido 向量模型 (paid; native endpoint, non-OpenAI response shape)
+  senseembedding:
+    adapter: "sensenova"
+    url: "https://api.sensenova.cn/compatible-mode/v2"
+    embeddings_url: "https://api.sensenova.cn/v1/llm/embeddings"
+    api_key: ENV["SENSENOVA_API_KEY"]
+    model: "Cupido"
+
+  # 4. 秒画 文生图 (free-tier sensenova-u1-fast; native token.sensenova.cn base)
+  senseimage:
+    adapter: "sensenova"
+    url: "https://token.sensenova.cn/v1"
+    image_url: "https://token.sensenova.cn/v1/images/generations"
+    api_key: ENV["SENSENOVA_API_KEY"]
+    model: "sensenova-u1-fast"
+
+default_llm: "sensechat"
+
+template_path: "./templates"
+worker_path: "./workers"
+logger_file: "./logs/smart_prompt.log"

data/config/zhipu_config.yml

@@ -0,0 +1,73 @@
+# 智谱 AI (BigModel / GLM) Configuration for SmartPrompt
+#
+# Get an API key from https://open.bigmodel.cn/ and export it as ZHIPUAI_API_KEY.
+# A single ZhipuAIAdapter covers all REST model categories — just point a different
+# llm entry at each model. Defaults use the free-tier models so it runs out-of-box.
+#
+# Base URL: https://open.bigmodel.cn/api/paas/v4  (coding models: .../api/coding/paas/v4)
+# Auth:     Authorization: Bearer <API_KEY>
+
+adapters:
+  zhipu: "ZhipuAIAdapter"
+
+llms:
+  # 1. 文本对话 (free-tier glm-4-flash; paid: glm-4-plus / glm-4-long / glm-5.2)
+  glm:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "glm-4-flash"
+    temperature: 0.7
+    # Optional sampling extras (forwarded to /chat/completions):
+    # top_p: 0.7
+    # max_tokens: 2048
+    # CodeGeeX-4: set `coding: true` (uses the coding base) and model: codegeex-4
+
+  # 2. 图文多模态 (free-tier glm-4v-flash; paid: glm-4v-plus)
+  glm_vision:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "glm-4v-flash"
+
+  # 3. 向量模型 (embedding-3 supports custom dimensions: 256/512/1024/2048)
+  embedding:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "embedding-3"
+    dimensions: 1024
+
+  # 4. 文生图 (free-tier cogview-3-flash; paid: cogview-4 / glm-image)
+  cogview:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "cogview-3-flash"
+
+  # 5. 文生视频 (async: submit -> poll -> download; free-tier cogvideox-flash)
+  cogvideo:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "cogvideox-flash"
+
+  # 6. 语音合成 (GLM-TTS)
+  glm_tts:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "glm-tts"
+
+  # 7. 语音识别 (GLM-ASR-2512)
+  glm_asr:
+    adapter: "zhipu"
+    url: "https://open.bigmodel.cn/api/paas/v4"
+    api_key: ENV["ZHIPUAI_API_KEY"]
+    model: "glm-asr-2512"
+
+default_llm: "glm"
+
+template_path: "./templates"
+worker_path: "./workers"
+logger_file: "./logs/smart_prompt.log"

data/docs/ANTHROPIC_EXAMPLES.md

@@ -0,0 +1,559 @@
+# Anthropic Claude Examples for SmartPrompt
+
+This document provides comprehensive examples for using Anthropic's Claude models with SmartPrompt. Claude offers powerful capabilities including advanced reasoning, multimodal understanding (text + images), tool calling, and streaming responses.
+
+## Table of Contents
+
+1. [Setup and Configuration](#setup-and-configuration)
+2. [Basic Chat Examples](#basic-chat-examples)
+3. [Multimodal Examples (Vision)](#multimodal-examples-vision)
+4. [Tool Calling Examples](#tool-calling-examples)
+5. [Streaming Response Examples](#streaming-response-examples)
+6. [Advanced Usage](#advanced-usage)
+7. [Best Practices](#best-practices)
+
+## Setup and Configuration
+
+### 1. Install Dependencies
+
+Ensure you have the `anthropic` gem installed:
+
+```ruby
+gem 'anthropic', '~> 1.14'
+```
+
+### 2. Set API Key
+
+Set your Anthropic API key as an environment variable:
+
+```bash
+export ANTHROPIC_API_KEY='your-api-key-here'
+```
+
+### 3. Configure SmartPrompt
+
+Create or update `config/anthropic_config.yml`:
+
+```yaml
+adapters:
+  anthropic: "AnthropicAdapter"
+
+llms:
+  claude:
+    adapter: "anthropic"
+    api_key: ENV["ANTHROPIC_API_KEY"]
+    model: "claude-3-5-sonnet-20241022"
+    temperature: 0.7
+    max_tokens: 4096
+
+  claude_haiku:
+    adapter: "anthropic"
+    api_key: ENV["ANTHROPIC_API_KEY"]
+    model: "claude-3-5-haiku-20241022"
+    temperature: 0.7
+    max_tokens: 4096
+
+  claude_opus:
+    adapter: "anthropic"
+    api_key: ENV["ANTHROPIC_API_KEY"]
+    model: "claude-3-opus-20240229"
+    temperature: 0.7
+    max_tokens: 4096
+```
+
+## Basic Chat Examples
+
+### Simple Question-Answer
+
+```ruby
+require 'smart_prompt'
+
+engine = SmartPrompt::Engine.new('config/anthropic_config.yml')
+
+SmartPrompt.define_worker :simple_chat do
+  use "claude"
+  sys_msg("You are a helpful AI assistant.")
+  prompt(params[:message])
+  send_msg
+end
+
+response = engine.call_worker(:simple_chat, {
+  message: "What is the capital of France?"
+})
+puts response
+```
+
+**Run the example:**
+```bash
+ruby examples/anthropic_basic_chat.rb
+```
+
+### Multi-turn Conversation
+
+```ruby
+SmartPrompt.define_worker :conversation do
+  use "claude"
+  sys_msg("You are a knowledgeable history teacher.")
+  prompt(params[:message], with_history: true)
+  send_msg
+end
+
+# First message
+response1 = engine.call_worker(:conversation, {
+  message: "Who was the first president of the United States?"
+})
+
+# Follow-up message (maintains context)
+response2 = engine.call_worker(:conversation, {
+  message: "What were his major accomplishments?"
+})
+```
+
+### Using Different Models
+
+```ruby
+# Claude 3.5 Sonnet - Best balance of intelligence and speed
+SmartPrompt.define_worker :sonnet_chat do
+  use "claude"
+  model "claude-3-5-sonnet-20241022"
+  prompt(params[:message])
+  send_msg
+end
+
+# Claude 3.5 Haiku - Fastest, most cost-effective
+SmartPrompt.define_worker :haiku_chat do
+  use "claude_haiku"
+  model "claude-3-5-haiku-20241022"
+  prompt(params[:message])
+  send_msg
+end
+
+# Claude 3 Opus - Highest quality for complex tasks
+SmartPrompt.define_worker :opus_chat do
+  use "claude_opus"
+  model "claude-3-opus-20240229"
+  prompt(params[:message])
+  send_msg
+end
+```
+
+### Temperature Control
+
+```ruby
+# Creative writing (high temperature)
+SmartPrompt.define_worker :creative_chat do
+  use "claude_creative"  # temperature: 0.9
+  sys_msg("You are a creative writer.")
+  prompt("Write a creative tagline for a coffee shop.")
+  send_msg
+end
+
+# Precise analysis (low temperature)
+SmartPrompt.define_worker :precise_chat do
+  use "claude_precise"  # temperature: 0.3
+  sys_msg("You are a precise analyst.")
+  prompt("Analyze this data and provide key insights.")
+  send_msg
+end
+```
+
+## Multimodal Examples (Vision)
+
+Claude can analyze images alongside text. Supported formats: JPEG, PNG, GIF, WebP (up to 5MB).
+
+### Analyze Image from URL
+
+```ruby
+SmartPrompt.define_worker :image_analyzer do
+  use "claude"
+  sys_msg("You are an expert at analyzing images.")
+  prompt(params[:message])
+  send_msg
+end
+
+response = engine.call_worker(:image_analyzer, {
+  message: [
+    { type: "text", text: "What do you see in this image?" },
+    { type: "image_url", image_url: "https://example.com/image.jpg" }
+  ]
+})
+```
+
+**Run the example:**
+```bash
+ruby examples/anthropic_multimodal.rb
+```
+
+### Analyze Local Image (Base64)
+
+```ruby
+require 'base64'
+
+# Read and encode image
+image_data = File.binread("./path/to/image.jpg")
+base64_image = Base64.strict_encode64(image_data)
+data_url = "data:image/jpeg;base64,#{base64_image}"
+
+response = engine.call_worker(:image_analyzer, {
+  message: [
+    { type: "text", text: "Describe this image in detail." },
+    { type: "image_url", image_url: data_url }
+  ]
+})
+```
+
+### Compare Multiple Images
+
+```ruby
+response = engine.call_worker(:image_analyzer, {
+  message: [
+    { type: "text", text: "Compare these two images." },
+    { type: "image_url", image_url: "https://example.com/image1.jpg" },
+    { type: "image_url", image_url: "https://example.com/image2.jpg" }
+  ]
+})
+```
+
+### OCR and Text Extraction
+
+```ruby
+SmartPrompt.define_worker :ocr_extractor do
+  use "claude"
+  sys_msg("You are an expert at reading text from images.")
+  prompt(params[:message])
+  send_msg
+end
+
+response = engine.call_worker(:ocr_extractor, {
+  message: [
+    { type: "text", text: "Extract all text from this image." },
+    { type: "image_url", image_url: "https://example.com/document.jpg" }
+  ]
+})
+```
+
+### Product Image Analysis
+
+```ruby
+SmartPrompt.define_worker :product_analyzer do
+  use "claude"
+  sys_msg("You are a product analyst for e-commerce.")
+  prompt(params[:message])
+  send_msg
+end
+
+response = engine.call_worker(:product_analyzer, {
+  message: [
+    { type: "text", text: "Analyze this product image and provide:\n1. Product description\n2. Key features\n3. Suggested title" },
+    { type: "image_url", image_url: "https://example.com/product.jpg" }
+  ]
+})
+```
+
+## Tool Calling Examples
+
+Claude can use external tools/functions to perform actions or retrieve information.
+
+### Simple Weather Tool
+
+```ruby
+weather_tool = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get the current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "The city and state, e.g. San Francisco, CA"
+          },
+          unit: {
+            type: "string",
+            enum: ["celsius", "fahrenheit"],
+            description: "Temperature unit"
+          }
+        },
+        required: ["location"]
+      }
+    }
+  }
+]
+
+SmartPrompt.define_worker :weather_assistant do
+  use "claude"
+  sys_msg("You are a weather assistant. Use the get_weather tool.")
+  prompt(params[:message])
+  params.merge(tools: weather_tool)
+  send_msg
+end
+
+response = engine.call_worker(:weather_assistant, {
+  message: "What's the weather in Tokyo?"
+})
+```
+
+**Run the example:**
+```bash
+ruby examples/anthropic_tool_calling.rb
+```
+
+### Multiple Calculator Tools
+
+```ruby
+calculator_tools = [
+  {
+    type: "function",
+    function: {
+      name: "add",
+      description: "Add two numbers",
+      parameters: {
+        type: "object",
+        properties: {
+          a: { type: "number" },
+          b: { type: "number" }
+        },
+        required: ["a", "b"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "multiply",
+      description: "Multiply two numbers",
+      parameters: {
+        type: "object",
+        properties: {
+          a: { type: "number" },
+          b: { type: "number" }
+        },
+        required: ["a", "b"]
+      }
+    }
+  }
+]
+
+SmartPrompt.define_worker :calculator do
+  use "claude"
+  sys_msg("You are a calculator assistant.")
+  prompt(params[:message])
+  params.merge(tools: calculator_tools)
+  send_msg
+end
+```
+
+### Database Query Tool
+
+```ruby
+database_tool = [
+  {
+    type: "function",
+    function: {
+      name: "query_database",
+      description: "Query the customer database",
+      parameters: {
+        type: "object",
+        properties: {
+          query_type: {
+            type: "string",
+            enum: ["customer_info", "order_history", "product_details"]
+          },
+          customer_id: { type: "string" }
+        },
+        required: ["query_type"]
+      }
+    }
+  }
+]
+```
+
+### Complex Tool with Nested Parameters
+
+```ruby
+search_tool = [
+  {
+    type: "function",
+    function: {
+      name: "search_products",
+      description: "Search products with filters",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          filters: {
+            type: "object",
+            properties: {
+              category: { type: "string" },
+              price_range: {
+                type: "object",
+                properties: {
+                  min: { type: "number" },
+                  max: { type: "number" }
+                }
+              },
+              in_stock: { type: "boolean" }
+            }
+          },
+          sort_by: {
+            type: "string",
+            enum: ["price_asc", "price_desc", "popularity"]
+          }
+        },
+        required: ["query"]
+      }
+    }
+  }
+]
+```
+
+## Streaming Response Examples
+
+Streaming provides better user experience by showing responses as they're generated.
+
+### Basic Streaming
+
+```ruby
+SmartPrompt.define_worker :streaming_chat do
+  use "claude"
+  sys_msg("You are a helpful assistant.")
+  prompt(params[:message])
+  send_msg
+end
+
+engine.call_worker_by_stream(:streaming_chat, {
+  message: "Tell me a story about a brave knight."
+}) do |chunk, bytesize|
+  if chunk.is_a?(Hash) && chunk["type"] == "content_block_delta"
+    text = chunk.dig("delta", "text")
+    print text if text
+  end
+end
+```
+
+**Run the example:**
+```bash
+ruby examples/anthropic_streaming.rb
+```
+
+### Handling Different Event Types
+
+```ruby
+engine.call_worker_by_stream(:streaming_chat, {
+  message: "Explain photosynthesis."
+}) do |chunk, bytesize|
+  if chunk.is_a?(Hash)
+    case chunk["type"]
+    when "message_start"
+      # Message started
+      puts "[Starting response...]"
+    when "content_block_start"
+      # Content block started
+    when "content_block_delta"
+      # Incremental text
+      text = chunk.dig("delta", "text")
+      print text if text
+    when "content_block_stop"
+      # Content block finished
+    when "message_stop"
+      # Message complete
+      puts "\n[Response complete]"
+    end
+  end
+end
+```
+
+### Streaming with Progress Tracking
+
+```ruby
+char_count = 0
+
+engine.call_worker_by_stream(:streaming_chat, {
+  message: "Write a Python function for Fibonacci."
+}) do |chunk, bytesize|
+  if chunk.is_a?(Hash) && chunk["type"] == "content_block_delta"
+    text = chunk.dig("delta", "text")
+    if text
+      print text
+      char_count += text.length
+    end
+  end
+end
+
+puts "\n[Total characters: #{char_count}]"
+```
+
+### Streaming with Error Handling
+
+```ruby
+begin
+  engine.call_worker_by_stream(:streaming_chat, {
+    message: "What are the benefits of exercise?"
+  }) do |chunk, bytesize|
+    if chunk.is_a?(Hash) && chunk["type"] == "content_block_delta"
+      text = chunk.dig("delta", "text")
+      print text if text
+    end
+  end
+  puts "\n[Stream completed successfully]"
+rescue SmartPrompt::LLMAPIError => e
+  puts "\n[Error: #{e.message}]"
+end
+```
+
+## Advanced Usage
+
+### Custom Endpoint (Proxy or Private Deployment)
+
+```yaml
+llms:
+  claude_custom:
+    adapter: "anthropic"
+    api_key: ENV["ANTHROPIC_API_KEY"]
+    url: "https://your-custom-endpoint.com"
+    model: "claude-3-5-sonnet-20241022"
+```
+
+### Combining Multimodal and Tool Calling
+
+```ruby
+tools = [
+  {
+    type: "function",
+    function: {
+      name: "identify_object",
+      description: "Identify objects in the image",
+      parameters: {
+        type: "object",
+        properties: {
+          object_name: { type: "string" }
+        },
+        required: ["object_name"]
+      }
+    }
+  }
+]
+
+SmartPrompt.define_worker :multimodal_tools do
+  use "claude"
+  sys_msg("You can analyze images and use tools.")
+  prompt(params[:message])
+  params.merge(tools: tools)
+  send_msg
+end
+
+response = engine.call_worker(:multimodal_tools, {
+  message: [
+    { type: "text", text: "What objects do you see? Use the identify_object tool." },
+    { type: "image_url", image_url: "https://example.com/scene.jpg" }
+  ]
+})
+```
+
+### Conversation with Mixed Content
+
+```ruby
+SmartPrompt.define_worker :mixed_conversation do
+  use "cla