llm_providers 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 660628c05ed3e6beb83cbf9e9e938ef587a8678beaf6f7c9c9b40046d511d863
-  data.tar.gz: cb83106d26fa942f1bae1122969c41a17e298de5cf58966a0b718ae8fc1fc56b
+  metadata.gz: 39486a92a6fa6a631714e76c434ac822ff9ce3239e0947b0d562d12e48abc257
+  data.tar.gz: c76b7917bf45d857d37c8ac1bf725e80b88d5a8ab578cd3f1522b1a831a9d7cb
 SHA512:
-  metadata.gz: c45d5e3e44a900f721c9314d7f62afda073808f24b73abd9dc305f12079f3509f71ac4abe6d895128ed7a26cf8751254989ec272a52f6031b6161c4c8ad61c7b
-  data.tar.gz: 7086766e28a072c3f6a9b47ac7acc48ba237a09f6bea29e3c1a63b287dd4ecbf07b97d8ef380c9c3823fa8a1144eb50ffd5495a59f69efdd0e5ff01ecacffbee
+  metadata.gz: 9f7fa21339fb2f323af4802cb1b9c8d5631b576036015212ac7969457c90a1f95a5874cff32cb5ba9d481f096093b27c896dd3eca866ad351890cac877321cd0
+  data.tar.gz: f6fb426095fd10973245392db4f079e8db8274269f2846ce9f942d60dd9df310da53989078e853f0ba0371a44b1a4698a81989c83a1eb6dc9348c83a9846caf7

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.3.0] - 2026-10-10
+
+### Breaking
+
+- `temperature` now defaults to `nil` and is sent only when given (it used to default to 0.7). Pass it explicitly to keep the old behavior on models that still accept it.
+- OpenAI reasoning detection is now "everything except the `gpt-3.5*` / `gpt-4*` families". Ids that do not start with those prefixes, such as `ft:gpt-4o-*` fine-tunes, `chatgpt-4o-latest` and `gpt-oss-*`, are now treated as reasoning models: they get `max_completion_tokens` and no `temperature`. OpenRouter is unaffected.
+
+### Changed
+
+- Anthropic non-streaming responses join all text blocks instead of taking the first.
+- Anthropic debug output goes through `LlmProviders.logger.debug` instead of `puts`.
+
+### Added
+
+- `effort:` option (`low`, `medium`, `high`, `xhigh`, `max`; `nil` for the provider default). Anthropic sends `output_config.effort`, OpenAI sends `reasoning_effort` (clamped to `high` below gpt-6), Google sends `thinkingConfig.thinkingLevel` (Gemini 3 and later only; xhigh and max become high), OpenRouter sends `reasoning.effort` (xhigh and max become high). Unknown values raise `ArgumentError`.
+
+### Fixed
+
+- GPT-6 and gpt-5.x models now get `max_completion_tokens` instead of `max_tokens`.
+- Claude 5.x no longer fails with "`temperature` is deprecated for this model".
+- Gemini usage `output` now includes thought tokens, so it is never nil; a response that hits MAX_TOKENS with no text returns empty content instead of raising.
+- Anthropic thinking blocks and `thinking_delta` / `signature_delta` events are ignored in results; Gemini thought-summary parts are left out of content.
+
+## [0.2.2] - 2026-02-27
+
+### Fixed
+
+- Update READMEs: remove experimental label from OpenRouter, add OpenRouter usage docs (headers, routing, models API, error handling)
+
 ## [0.2.1] - 2026-02-27
 
 ### Fixed

data/README.ja.md

@@ -22,7 +22,7 @@
 | `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250929` |
 | `openai` | `OPENAI_API_KEY` | `gpt-5-mini` |
 | `google` | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
-| `openrouter` *(実験的)* | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.5` |
+| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.5` |
 
 ## インストール
 
@@ -68,11 +68,21 @@ end
 provider = LlmProviders::Providers.build(
   :openai,
   model: "gpt-4.1",
-  temperature: 0.7,
-  max_tokens: 4096
+  temperature: 0.7,   # 省略可。デフォルトは nil（送信しない）
+  max_tokens: 4096,
+  effort: "medium"    # 省略可。"low" / "medium" / "high" / "xhigh" / "max"
 )
 ```
 
+- `temperature` のデフォルトは `nil` で、指定したときだけ送信します。0.7 を固定で送っていた 0.2.x までと異なります。Claude 5.x や OpenAI の reasoning モデルは temperature を受け付けません。
+- `effort` は思考の深さの指定です（`nil` ならプロバイダーのデフォルト）。範囲外の値は `ArgumentError` になります。
+  - Anthropic: `output_config: { effort: ... }` にそのまま渡します。
+  - OpenAI: `reasoning_effort` に渡します。`gpt-6*` はそのまま、それ以前の reasoning モデル（gpt-5*、o 系）は `xhigh` / `max` を `high` に丸めます。`gpt-3.5*` / `gpt-4*` では無視されます。
+  - Google: `thinkingConfig.thinkingLevel` に変換します（low→low、medium→medium、high/xhigh/max→high）。Gemini 3 以降（と `*-latest`）にだけ送り、Gemini 2.x では無視します。
+  - OpenRouter: `reasoning: { effort: ... }` として送ります。`xhigh` / `max` は `high` に丸めます。
+- OpenAI は `gpt-3.5*` / `gpt-4*` 以外を reasoning モデルとして扱い、`max_completion_tokens` を使って temperature を送りません。OpenRouter は `vendor/model` 形式の ID なので従来どおり `max_tokens` を使い、temperature は指定時のみ送ります。
+- Google の usage の `output` は思考トークンを含みます。
+
 ### ツール呼び出し
 
 ```ruby
@@ -120,14 +130,32 @@ end
 }
 ```
 
+### OpenRouter
+
+OpenRouter を使えば、単一の API で 300 以上のモデルにアクセスできます。この gem が直接サポートしていないプロバイダー（DeepSeek、Meta Llama、Mistral、Qwen など）に最適です。
+
+```ruby
+provider = LlmProviders::Providers.build(
+  :openrouter,
+  model: "deepseek/deepseek-chat",
+  app_name: "MyApp",
+  app_url: "https://myapp.example.com",
+  provider: { order: ["DeepSeek", "Together"], allow_fallbacks: true }
+)
+
+# 利用可能なモデル一覧
+models = LlmProviders::Providers::Openrouter.models
+models.each { |m| puts "#{m[:id]} (ctx: #{m[:context_length]})" }
+```
+
 ### エラーハンドリング
 
 ```ruby
 begin
   result = provider.chat(messages: messages)
 rescue LlmProviders::ProviderError => e
-  puts "エラー: #{e.message}"
-  puts "コード: #{e.code}"  # 例: "anthropic_error", "openai_error"
+  puts "エラー: #{e.message}"  # OpenRouter: "[DeepSeek] Model is unavailable"
+  puts "コード: #{e.code}"     # 例: "anthropic_error", "openrouter_error"
 end
 ```
 
@@ -146,6 +174,10 @@ ANTHROPIC_API_KEY=your-key ruby examples/with_tools.rb
 # 他のプロバイダー
 OPENAI_API_KEY=your-key ruby examples/simple_chat.rb openai
 GOOGLE_API_KEY=your-key ruby examples/simple_chat.rb google
+
+# OpenRouter (DeepSeek, Llama, Mistral など)
+OPENROUTER_API_KEY=your-key ruby examples/simple_chat.rb openrouter deepseek/deepseek-chat
+OPENROUTER_API_KEY=your-key ruby examples/with_tools.rb openrouter meta-llama/llama-3.3-70b-instruct
 ```
 
 ## ライセンス

data/README.md

@@ -22,7 +22,7 @@ A lightweight, unified interface for multiple LLM providers. Only depends on `fa
 | `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5-20250929` |
 | `openai` | `OPENAI_API_KEY` | `gpt-5-mini` |
 | `google` | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
-| `openrouter` *(experimental)* | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.5` |
+| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.5` |
 
 ## Installation
 
@@ -68,11 +68,21 @@ end
 provider = LlmProviders::Providers.build(
   :openai,
   model: "gpt-4.1",
-  temperature: 0.7,
-  max_tokens: 4096
+  temperature: 0.7,   # optional; defaults to nil (not sent)
+  max_tokens: 4096,
+  effort: "medium"    # optional; "low", "medium", "high", "xhigh" or "max"
 )
 ```
 
+- `temperature` defaults to `nil` and is sent only when you set it. Versions up to 0.2.x always sent 0.7. Claude 5.x and OpenAI reasoning models reject the parameter.
+- `effort` sets how hard the model thinks (`nil` means the provider default). Any other value raises `ArgumentError`.
+  - Anthropic: sent as `output_config: { effort: ... }`.
+  - OpenAI: sent as `reasoning_effort`. `gpt-6*` gets the value unchanged; older reasoning models (gpt-5*, o-series) get `xhigh` / `max` clamped to `high`. Ignored for `gpt-3.5*` / `gpt-4*`.
+  - Google: mapped to `thinkingConfig.thinkingLevel` (low, medium, high; xhigh and max become high). Only sent for Gemini 3 and later (and `*-latest` aliases); ignored for Gemini 2.x.
+  - OpenRouter: sent as `reasoning: { effort: ... }`, with xhigh and max clamped to `high`.
+- OpenAI treats every model except `gpt-3.5*` / `gpt-4*` as a reasoning model: it uses `max_completion_tokens` and sends no temperature. OpenRouter ids look like `vendor/model`, so it keeps using `max_tokens` and sends temperature only when given.
+- For Google, usage `output` includes thinking tokens.
+
 ### Tool Calling
 
 ```ruby
@@ -120,14 +130,32 @@ Every `chat` call returns a hash with:
 }
 ```
 
+### OpenRouter
+
+OpenRouter gives you access to 300+ models through a single API — ideal for providers not directly supported by this gem (DeepSeek, Meta Llama, Mistral, Qwen, etc.).
+
+```ruby
+provider = LlmProviders::Providers.build(
+  :openrouter,
+  model: "deepseek/deepseek-chat",
+  app_name: "MyApp",
+  app_url: "https://myapp.example.com",
+  provider: { order: ["DeepSeek", "Together"], allow_fallbacks: true }
+)
+
+# List available models
+models = LlmProviders::Providers::Openrouter.models
+models.each { |m| puts "#{m[:id]} (ctx: #{m[:context_length]})" }
+```
+
 ### Error Handling
 
 ```ruby
 begin
   result = provider.chat(messages: messages)
 rescue LlmProviders::ProviderError => e
-  puts "Error: #{e.message}"
-  puts "Code: #{e.code}"  # e.g., "anthropic_error", "openai_error"
+  puts "Error: #{e.message}"  # OpenRouter: "[DeepSeek] Model is unavailable"
+  puts "Code: #{e.code}"      # e.g., "anthropic_error", "openrouter_error"
 end
 ```
 
@@ -146,6 +174,10 @@ ANTHROPIC_API_KEY=your-key ruby examples/with_tools.rb
 # Other providers
 OPENAI_API_KEY=your-key ruby examples/simple_chat.rb openai
 GOOGLE_API_KEY=your-key ruby examples/simple_chat.rb google
+
+# OpenRouter (DeepSeek, Llama, Mistral, etc.)
+OPENROUTER_API_KEY=your-key ruby examples/simple_chat.rb openrouter deepseek/deepseek-chat
+OPENROUTER_API_KEY=your-key ruby examples/with_tools.rb openrouter meta-llama/llama-3.3-70b-instruct
 ```
 
 ## License

data/lib/llm_providers/providers/anthropic.rb

@@ -48,6 +48,7 @@ module LlmProviders
         end
 
         payload[:temperature] = @temperature if @temperature
+        payload[:output_config] = { effort: @effort } if @effort
 
         if tools && !tools.empty?
           formatted_tools = format_tools(tools)
@@ -131,8 +132,7 @@ module LlmProviders
         payload[:stream] = true
         started_at = Time.now
 
-        puts "[Anthropic] stream_response payload tools: #{payload[:tools]&.size || 0}"
-        puts "[Anthropic] payload[:tools] = #{payload[:tools].inspect}" if payload[:tools]
+        LlmProviders.logger.debug "[Anthropic] stream_response payload tools: #{payload[:tools]&.size || 0}"
 
         full_content = ""
         tool_calls = []
@@ -163,9 +163,9 @@ module LlmProviders
                 end
               end
             when "content_block_start"
-              puts "[Anthropic] content_block_start: #{event["content_block"]&.dig("type")}"
+              LlmProviders.logger.debug "[Anthropic] content_block_start: #{event["content_block"]&.dig("type")}"
               if event.dig("content_block", "type") == "tool_use"
-                puts "[Anthropic] Tool use started: #{event.dig("content_block", "name")}"
+                LlmProviders.logger.debug "[Anthropic] Tool use started: #{event.dig("content_block", "name")}"
                 tool_calls << {
                   id: event.dig("content_block", "id"),
                   name: event.dig("content_block", "name"),
@@ -262,7 +262,7 @@ module LlmProviders
         end
 
         body = response.body
-        content = body["content"]&.find { |c| c["type"] == "text" }&.dig("text") || ""
+        content = (body["content"] || []).select { |c| c["type"] == "text" }.map { |c| c["text"].to_s }.join
 
         tool_calls = body["content"]&.select { |c| c["type"] == "tool_use" }&.map do |tc|
           { id: tc["id"], name: tc["name"], input: tc["input"] }

data/lib/llm_providers/providers/base.rb

@@ -5,9 +5,17 @@ require "faraday"
 module LlmProviders
   module Providers
     class Base
-      def initialize(model: nil, temperature: nil, max_tokens: nil)
+      EFFORT_LEVELS = %w[low medium high xhigh max].freeze
+
+      # temperature: nil means "provider default" (not sent).
+      # effort: nil means "provider default"; otherwise one of EFFORT_LEVELS.
+      def initialize(model: nil, temperature: nil, max_tokens: nil, effort: nil)
         @model = model || default_model
-        @temperature = temperature || 0.7
+        @temperature = temperature
+        @effort = effort&.to_s
+        unless @effort.nil? || EFFORT_LEVELS.include?(@effort)
+          raise ArgumentError, "effort must be one of #{EFFORT_LEVELS.join(", ")} (got #{effort.inspect})"
+        end
         @max_tokens = max_tokens || 16_384
       end
 

data/lib/llm_providers/providers/google.rb

@@ -6,6 +6,9 @@ module LlmProviders
   module Providers
     class Google < Base
       BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models"
+      THINKING_LEVELS = {
+        "low" => "low", "medium" => "medium", "high" => "high", "xhigh" => "high", "max" => "high"
+      }.freeze
 
       def chat(messages:, system: nil, tools: nil, &block)
         payload = build_payload(messages, system, tools)
@@ -29,6 +32,15 @@ module LlmProviders
 
       private
 
+      # thinkingLevel exists from Gemini 3 on (and on *-latest aliases); Gemini 2.x
+      # uses thinkingBudget and would reject it, so effort is ignored there.
+      def thinking_level_supported?
+        return true if @model.match?(/-latest$/)
+
+        major = @model[/\Agemini-(\d+)/, 1]
+        !major.nil? && major.to_i >= 3
+      end
+
       def api_url(stream: false)
         action = stream ? "streamGenerateContent" : "generateContent"
         "#{BASE_URL}/#{@model}:#{action}?key=#{api_key}"
@@ -38,11 +50,15 @@ module LlmProviders
         payload = {
           contents: format_messages(messages),
           generationConfig: {
-            maxOutputTokens: @max_tokens,
-            temperature: @temperature
+            maxOutputTokens: @max_tokens
           }
         }
 
+        payload[:generationConfig][:temperature] = @temperature if @temperature
+        if @effort && thinking_level_supported?
+          payload[:generationConfig][:thinkingConfig] = { thinkingLevel: THINKING_LEVELS.fetch(@effort) }
+        end
+
         payload[:system_instruction] = { parts: [{ text: system }] } if system && !system.empty?
 
         payload[:tools] = format_tools(tools) if tools && !tools.empty?
@@ -186,7 +202,7 @@ module LlmProviders
           if candidate
             parts = candidate.dig("content", "parts") || []
             parts.each do |part|
-              yield(content: part["text"]) if part["text"]
+              yield(content: part["text"]) if part["text"] && !part["thought"]
               next unless part["functionCall"]
 
               tool_calls << {
@@ -198,16 +214,22 @@ module LlmProviders
           end
 
           if event["usageMetadata"]
-            yield(usage: {
-              input: event.dig("usageMetadata", "promptTokenCount"),
-              output: event.dig("usageMetadata", "candidatesTokenCount")
-            })
+            yield(usage: usage_from(event["usageMetadata"]))
           end
         rescue JSON::ParserError => e
           LlmProviders.logger.debug "[Google] JSON parse error: #{e.message}, data: #{data[0, 200]}"
         end
       end
 
+      # Thinking tokens are billed as output and consume maxOutputTokens, so count them.
+      def usage_from(meta)
+        meta ||= {}
+        {
+          input: meta["promptTokenCount"],
+          output: meta["candidatesTokenCount"].to_i + meta["thoughtsTokenCount"].to_i
+        }
+      end
+
       def sync_response(payload)
         started_at = Time.now
 
@@ -226,7 +248,7 @@ module LlmProviders
         candidate = body.dig("candidates", 0)
         parts = candidate&.dig("content", "parts") || []
 
-        content = parts.filter_map { |p| p["text"] }.join
+        content = parts.filter_map { |p| p["text"] unless p["thought"] }.join
         tool_calls = parts.filter_map do |p|
           next unless p["functionCall"]
 
@@ -240,10 +262,7 @@ module LlmProviders
         {
           content: content,
           tool_calls: tool_calls,
-          usage: {
-            input: body.dig("usageMetadata", "promptTokenCount"),
-            output: body.dig("usageMetadata", "candidatesTokenCount")
-          },
+          usage: usage_from(body["usageMetadata"]),
           latency_ms: ((Time.now - started_at) * 1000).to_i,
           raw_response: body
         }

data/lib/llm_providers/providers/openai.rb

@@ -31,25 +31,42 @@ module LlmProviders
 
       def build_payload(messages, system, tools)
         formatted = format_messages(messages, system)
-        reasoning_model = @model.match?(/^(o1|o3|o4|gpt-5)/)
-
         payload = {
           model: @model,
           messages: formatted
         }
 
-        payload[:temperature] = @temperature unless reasoning_model
-
-        if @model.match?(/^(gpt-4o|gpt-5|o1|o3|o4)/)
+        if reasoning_model?
           payload[:max_completion_tokens] = @max_tokens
+          effort = reasoning_effort
+          payload[:reasoning_effort] = effort if effort
         else
-          payload[:max_tokens] = @max_tokens
+          payload[:temperature] = @temperature if @temperature
+          if @model.match?(/^gpt-4o/)
+            payload[:max_completion_tokens] = @max_tokens
+          else
+            payload[:max_tokens] = @max_tokens
+          end
         end
 
         payload[:tools] = format_tools(tools) if tools && !tools.empty?
         payload
       end
 
+      # Everything except the legacy chat families (gpt-3.5*, gpt-4*) is a
+      # reasoning model: gpt-5*, gpt-6*, o-series and whatever comes next.
+      def reasoning_model?
+        !@model.match?(/^(gpt-3\.5|gpt-4)/)
+      end
+
+      # gpt-6* accepts the full effort range; older reasoning models top out at "high".
+      def reasoning_effort
+        return nil unless @effort
+        return @effort if @model.match?(/^gpt-6/)
+
+        %w[xhigh max].include?(@effort) ? "high" : @effort
+      end
+
       def format_messages(messages, system)
         result = []
         result << { role: "system", content: system } if system && !system.empty?

data/lib/llm_providers/providers/openrouter.rb

@@ -54,9 +54,18 @@ module LlmProviders
 
       private
 
+      # OpenRouter ids are "vendor/model" (e.g. "openai/gpt-6-luna"). OpenRouter
+      # normalizes max_tokens/temperature across vendors, so we never apply the
+      # OpenAI reasoning rule here: send max_tokens, and temperature only if given.
+      # `effort` is forwarded as `reasoning: { effort: ... }`, with xhigh/max clamped to "high".
+      def reasoning_model?
+        false
+      end
+
       def build_payload(messages, system, tools)
         payload = super
         payload[:provider] = @provider_preferences if @provider_preferences
+        payload[:reasoning] = { effort: %w[xhigh max].include?(@effort) ? "high" : @effort } if @effort
         payload
       end
 

data/lib/llm_providers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmProviders
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_providers
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - kaba
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -81,6 +82,7 @@ metadata:
   source_code_uri: https://github.com/kabaken/llm-providers
   changelog_uri: https://github.com/kabaken/llm-providers/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -95,7 +97,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Multi-provider LLM client for OpenAI, Anthropic, Google, OpenRouter
 test_files: []