llm_providers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd68399074379aa3cca94d766217abe7270698fa764b1656d1fc585977c47e49
+  data.tar.gz: 6b82fe10d4ae4bb414317c1fbbca2252976032032fcc846c2864154cb54aee62
+SHA512:
+  metadata.gz: 77759c7d037da031e31db5ce76456279d5c1ed104b7df60d19289ceb6cba0ad26b7de1aa80f1e78b1afcc18b41d780ffd34718cb318b6cf905a1947adde806e0
+  data.tar.gz: 598b707ba1f7160b7b6f03b3d291a7d2bf0d726afe55d6fd86b60747c8ebc440438c5e5753597eb36016b0012552404aedc98f3cc3dc28e5ba93465c78a8b73a

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2026-02-13
+
+- Initial release
+- Support for OpenAI, Anthropic, Google, and OpenRouter providers
+- Streaming responses
+- Tool calling support
+- Token usage tracking
+- Configurable logging

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 kaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.ja.md

@@ -0,0 +1,153 @@
+# LlmProviders
+
+[![Gem Version](https://badge.fury.io/rb/llm_providers.svg)](https://rubygems.org/gems/llm_providers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+複数の LLM プロバイダーに対応した軽量な統一インターフェース。依存は `faraday` のみ — ActiveSupport 不要。
+
+[English README](README.md)
+
+## 特徴
+
+- **軽量** — 依存は `faraday` のみ、ActiveSupport 不要
+- **統一インターフェース** — 全プロバイダーで同じ API
+- **ストリーミング** — ブロック構文でリアルタイムトークンストリーミング
+- **ツール呼び出し** — プロバイダー間で一貫したツール/関数呼び出し
+- **トークン追跡** — 全レスポンスに使用量統計（入力、出力、キャッシュ）
+
+## 対応プロバイダー
+
+| プロバイダー | 環境変数 | デフォルトモデル |
+|------------|---------|---------------|
+| `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` |
+
+## インストール
+
+Gemfile に追加:
+
+```ruby
+gem "llm_providers"
+```
+
+## クイックスタート
+
+```ruby
+require "llm_providers"
+
+provider = LlmProviders::Providers.build(:anthropic)
+
+# 同期
+result = provider.chat(
+  messages: [{ role: "user", content: "こんにちは！" }],
+  system: "あなたは親切なアシスタントです。"
+)
+puts result[:content]
+
+# ストリーミング
+provider.chat(messages: [{ role: "user", content: "こんにちは！" }]) do |chunk|
+  print chunk[:content]
+end
+```
+
+## 使い方
+
+### 設定
+
+```ruby
+LlmProviders.configure do |config|
+  config.logger = Rails.logger  # 任意の Logger インスタンス
+end
+```
+
+### プロバイダーオプション
+
+```ruby
+provider = LlmProviders::Providers.build(
+  :openai,
+  model: "gpt-4.1",
+  temperature: 0.7,
+  max_tokens: 4096
+)
+```
+
+### ツール呼び出し
+
+```ruby
+tools = [
+  {
+    name: "get_weather",
+    description: "現在の天気を取得",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string", description: "都市名" }
+      },
+      required: ["location"]
+    }
+  }
+]
+
+result = provider.chat(
+  messages: [{ role: "user", content: "東京の天気は？" }],
+  tools: tools
+)
+
+result[:tool_calls].each do |tc|
+  puts "#{tc[:name]}: #{tc[:input]}"
+end
+```
+
+### レスポンス形式
+
+`chat` は常に以下のハッシュを返します:
+
+```ruby
+{
+  content: "レスポンステキスト",
+  tool_calls: [
+    { id: "...", name: "...", input: {...} }
+  ],
+  usage: {
+    input: 100,           # 入力トークン数
+    output: 50,           # 出力トークン数
+    cached_input: 80      # キャッシュされた入力トークン数（Anthropicのみ）
+  },
+  latency_ms: 1234,
+  raw_response: {...}
+}
+```
+
+### エラーハンドリング
+
+```ruby
+begin
+  result = provider.chat(messages: messages)
+rescue LlmProviders::ProviderError => e
+  puts "エラー: #{e.message}"
+  puts "コード: #{e.code}"  # 例: "anthropic_error", "openai_error"
+end
+```
+
+## サンプル
+
+```bash
+# 対話チャット
+ANTHROPIC_API_KEY=your-key ruby examples/simple_chat.rb
+
+# ワンショット
+ANTHROPIC_API_KEY=your-key ruby examples/one_shot.rb "Hello!"
+
+# ツール呼び出し
+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
+```
+
+## ライセンス
+
+MIT

data/README.md

@@ -0,0 +1,153 @@
+# LlmProviders
+
+[![Gem Version](https://badge.fury.io/rb/llm_providers.svg)](https://rubygems.org/gems/llm_providers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+A lightweight, unified interface for multiple LLM providers. Only depends on `faraday` — no ActiveSupport required.
+
+[日本語版 README](README.ja.md)
+
+## Features
+
+- **Lightweight** — Single dependency (`faraday`), no ActiveSupport
+- **Unified interface** — Same API for all providers
+- **Streaming** — Real-time token streaming with block syntax
+- **Tool calling** — Consistent tool/function calling across providers
+- **Token tracking** — Usage stats (input, output, cached) in every response
+
+## Supported Providers
+
+| Provider | ENV Variable | Default Model |
+|----------|-------------|---------------|
+| `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` |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "llm_providers"
+```
+
+## Quick Start
+
+```ruby
+require "llm_providers"
+
+provider = LlmProviders::Providers.build(:anthropic)
+
+# Synchronous
+result = provider.chat(
+  messages: [{ role: "user", content: "Hello!" }],
+  system: "You are a helpful assistant."
+)
+puts result[:content]
+
+# Streaming
+provider.chat(messages: [{ role: "user", content: "Hello!" }]) do |chunk|
+  print chunk[:content]
+end
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+LlmProviders.configure do |config|
+  config.logger = Rails.logger  # or any Logger instance
+end
+```
+
+### Provider Options
+
+```ruby
+provider = LlmProviders::Providers.build(
+  :openai,
+  model: "gpt-4.1",
+  temperature: 0.7,
+  max_tokens: 4096
+)
+```
+
+### Tool Calling
+
+```ruby
+tools = [
+  {
+    name: "get_weather",
+    description: "Get the current weather",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string", description: "City name" }
+      },
+      required: ["location"]
+    }
+  }
+]
+
+result = provider.chat(
+  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
+  tools: tools
+)
+
+result[:tool_calls].each do |tc|
+  puts "#{tc[:name]}: #{tc[:input]}"
+end
+```
+
+### Response Format
+
+Every `chat` call returns a hash with:
+
+```ruby
+{
+  content: "Response text",
+  tool_calls: [
+    { id: "...", name: "...", input: {...} }
+  ],
+  usage: {
+    input: 100,           # Input tokens
+    output: 50,           # Output tokens
+    cached_input: 80      # Cached input tokens (Anthropic only)
+  },
+  latency_ms: 1234,
+  raw_response: {...}
+}
+```
+
+### 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"
+end
+```
+
+## Examples
+
+```bash
+# Interactive chat
+ANTHROPIC_API_KEY=your-key ruby examples/simple_chat.rb
+
+# One-shot
+ANTHROPIC_API_KEY=your-key ruby examples/one_shot.rb "Hello!"
+
+# With tools
+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
+```
+
+## License
+
+MIT

data/lib/llm_providers/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module LlmProviders
+  class Configuration
+    attr_accessor :logger
+
+    def initialize
+      @logger = Logger.new($stdout)
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def logger
+      configuration.logger
+    end
+  end
+end

data/lib/llm_providers/provider_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LlmProviders
+  class ProviderError < StandardError
+    attr_reader :code
+
+    def initialize(message, code: nil)
+      @code = code
+      super(message)
+    end
+  end
+end

data/lib/llm_providers/providers/anthropic.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module LlmProviders
+  module Providers
+    class Anthropic < Base
+      API_URL = "https://api.anthropic.com/v1/messages"
+      API_VERSION = "2023-06-01"
+
+      def chat(messages:, system: nil, tools: nil, &block)
+        Time.now
+
+        payload = build_payload(messages, system, tools)
+
+        if block_given?
+          stream_response(payload, &block)
+        else
+          sync_response(payload)
+        end
+      end
+
+      protected
+
+      def default_model
+        "claude-sonnet-4-5-20250929"
+      end
+
+      def api_key
+        ENV.fetch("ANTHROPIC_API_KEY")
+      end
+
+      private
+
+      def build_payload(messages, system, tools)
+        payload = {
+          model: @model,
+          max_tokens: @max_tokens,
+          messages: format_messages(messages)
+        }
+
+        if system && !system.empty?
+          payload[:system] = [
+            {
+              type: "text",
+              text: system,
+              cache_control: { type: "ephemeral" }
+            }
+          ]
+        end
+
+        payload[:temperature] = @temperature if @temperature
+
+        if tools && !tools.empty?
+          formatted_tools = format_tools(tools)
+          payload[:tools] = formatted_tools.map.with_index do |tool, i|
+            if i == formatted_tools.size - 1
+              tool.merge(cache_control: { type: "ephemeral" })
+            else
+              tool
+            end
+          end
+        end
+
+        payload
+      end
+
+      def format_messages(messages)
+        result = []
+
+        messages.each do |msg|
+          case msg[:role]
+          when "tool"
+            tool_result = {
+              type: "tool_result",
+              tool_use_id: msg[:tool_call_id],
+              content: msg[:content]
+            }
+
+            if result.last && result.last[:role] == "user" && result.last[:content].is_a?(Array)
+              result.last[:content] << tool_result
+            else
+              result << {
+                role: "user",
+                content: [tool_result]
+              }
+            end
+          when "assistant"
+            if msg[:tool_calls] && !msg[:tool_calls].empty?
+              content = []
+              content << { type: "text", text: msg[:content] } if msg[:content] && !msg[:content].empty?
+              msg[:tool_calls].each do |tc|
+                tc = stringify_keys(tc)
+                content << {
+                  type: "tool_use",
+                  id: tc["id"],
+                  name: tc["name"],
+                  input: tc["input"]
+                }
+              end
+              result << {
+                role: "assistant",
+                content: content
+              }
+            else
+              result << {
+                role: "assistant",
+                content: msg[:content]
+              }
+            end
+          else
+            result << {
+              role: msg[:role],
+              content: msg[:content]
+            }
+          end
+        end
+
+        result
+      end
+
+      def format_tools(tools)
+        tools.map do |tool|
+          {
+            name: tool[:name],
+            description: tool[:description],
+            input_schema: tool[:parameters]
+          }
+        end
+      end
+
+      def stream_response(payload, &block)
+        payload[:stream] = true
+        started_at = Time.now
+
+        full_content = ""
+        tool_calls = []
+        usage = {}
+
+        conn = Faraday.new do |f|
+          f.options.open_timeout = 10
+          f.options.read_timeout = 300
+          f.options.write_timeout = 30
+          f.adapter Faraday.default_adapter
+        end
+
+        response = conn.post(API_URL) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.headers["x-api-key"] = api_key
+          req.headers["anthropic-version"] = API_VERSION
+          req.body = payload.to_json
+          req.options.on_data = proc do |chunk, _|
+            process_stream_chunk(chunk, full_content, tool_calls) do |parsed|
+              if parsed[:content]
+                full_content += parsed[:content]
+                block.call(content: parsed[:content])
+              end
+              usage = parsed[:usage] if parsed[:usage]
+            end
+          end
+        end
+
+        unless response.success?
+          error_message = begin
+            if response.body.is_a?(Hash)
+              response.body["error"]&.dig("message")
+            else
+              response.body.to_s
+            end
+          rescue StandardError
+            response.body.to_s
+          end
+          raise ProviderError.new(
+            (error_message && !error_message.empty? ? error_message : nil) || "API error",
+            code: "anthropic_error"
+          )
+        end
+
+        {
+          content: full_content,
+          tool_calls: tool_calls,
+          usage: usage,
+          latency_ms: ((Time.now - started_at) * 1000).to_i,
+          raw_response: { content: full_content, tool_calls: tool_calls }
+        }
+      end
+
+      def process_stream_chunk(chunk, _full_content, tool_calls)
+        chunk.each_line do |line|
+          next unless line.start_with?("data: ")
+
+          data = line.sub("data: ", "").strip
+          next if data == "[DONE]"
+
+          begin
+            event = JSON.parse(data)
+
+            case event["type"]
+            when "content_block_delta"
+              if event.dig("delta", "type") == "text_delta"
+                yield(content: event.dig("delta", "text"))
+              elsif event.dig("delta", "type") == "input_json_delta"
+                if tool_calls.any?
+                  tool_calls.last[:input_json] ||= ""
+                  tool_calls.last[:input_json] += event.dig("delta", "partial_json").to_s
+                end
+              end
+            when "content_block_start"
+              if event.dig("content_block", "type") == "tool_use"
+                tool_calls << {
+                  id: event.dig("content_block", "id"),
+                  name: event.dig("content_block", "name"),
+                  input: {},
+                  input_json: ""
+                }
+              end
+            when "content_block_stop"
+              if tool_calls.any? && tool_calls.last[:input_json] && !tool_calls.last[:input_json].empty?
+                begin
+                  tool_calls.last[:input] = JSON.parse(tool_calls.last[:input_json])
+                rescue JSON::ParserError
+                  # Keep empty on parse failure
+                end
+                tool_calls.last.delete(:input_json)
+              end
+            when "message_delta"
+              if event["usage"]
+                yield(usage: {
+                  input: event.dig("usage", "input_tokens"),
+                  output: event.dig("usage", "output_tokens"),
+                  cached_input: event.dig("usage", "cache_read_input_tokens")
+                })
+              end
+            end
+          rescue JSON::ParserError
+            # Skip invalid JSON
+          end
+        end
+      end
+
+      def sync_response(payload)
+        started_at = Time.now
+
+        response = http_client.post(API_URL) do |req|
+          req.headers["x-api-key"] = api_key
+          req.headers["anthropic-version"] = API_VERSION
+          req.body = payload
+        end
+
+        unless response.success?
+          raise ProviderError.new(
+            response.body["error"]&.dig("message") || "API error",
+            code: "anthropic_error"
+          )
+        end
+
+        body = response.body
+        content = body["content"]&.find { |c| c["type"] == "text" }&.dig("text") || ""
+
+        tool_calls = body["content"]&.select { |c| c["type"] == "tool_use" }&.map do |tc|
+          { id: tc["id"], name: tc["name"], input: tc["input"] }
+        end || []
+
+        {
+          content: content,
+          tool_calls: tool_calls,
+          usage: {
+            input: body.dig("usage", "input_tokens"),
+            output: body.dig("usage", "output_tokens"),
+            cached_input: body.dig("usage", "cache_read_input_tokens")
+          },
+          latency_ms: ((Time.now - started_at) * 1000).to_i,
+          raw_response: body
+        }
+      end
+    end
+  end
+end

data/lib/llm_providers/providers/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module LlmProviders
+  module Providers
+    class Base
+      def initialize(model: nil, temperature: nil, max_tokens: nil)
+        @model = model || default_model
+        @temperature = temperature || 0.7
+        @max_tokens = max_tokens || 16_384
+      end
+
+      def chat(messages:, system: nil, tools: nil, &block)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def default_model
+        raise NotImplementedError
+      end
+
+      def api_key
+        raise NotImplementedError
+      end
+
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+
+      def http_client
+        @http_client ||= Faraday.new do |f|
+          f.request :json
+          f.response :json
+          f.options.open_timeout = 10
+          f.options.read_timeout = 120
+          f.options.write_timeout = 30
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end