ask-llm-providers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 677ec905a0f11d7072c4574d03193b85720065778678e940b38252d2adc2f1a0
+  data.tar.gz: 9cb65bb51e2ea18e6b7c1b92e0d7fcce64aab4b4d8e9d5493215200928e35eb9
+SHA512:
+  metadata.gz: cf49fac238b8ce8a9a8df31dcab9a3854d35401eb45699bbb964b01bf50417e544ba5095a9c9b1e40c68b11095f1d3e35bad386b5549a6a6a8793e28ebb0b85b
+  data.tar.gz: 99e31531be1bbc2b0930f957630118d77de620e3e668750f04ea966a1bcd0c627339623ba59fae69464c7aa07bfe39be354f5934f145d2b6dcb3d8fb24c73c81

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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.md

@@ -0,0 +1,70 @@
+# ask-llm-providers
+
+All LLM providers for the ask-rb ecosystem in one gem. Implements `Ask::Provider`
+from `ask-core` with a capabilities-based interface.
+
+## Supported Providers
+
+| Provider | Auth | Implementation |
+|---|---|---|
+| **OpenAI** + all OpenAI-compatible | `Ask::Auth.resolve(:openai_api_key)` | `Ask::Provider::OpenAI` |
+| **Anthropic** (Claude) | `Ask::Auth.resolve(:anthropic_api_key)` | `Ask::Provider::Anthropic` |
+| **Google Gemini** | `Ask::Auth.resolve(:gemini_api_key)` | `Ask::Provider::Google` |
+| **Vertex AI** | GCP service account | `Ask::Provider::VertexAI` |
+| **Amazon Bedrock** | AWS credentials chain | `Ask::Provider::Bedrock` |
+| **Ollama** (local) | None needed | `Ask::Provider::Ollama` |
+| **Mistral AI** | `Ask::Auth.resolve(:mistral_api_key)` | `Ask::Provider::Mistral` |
+| **Cloudflare Workers AI** | `Ask::Auth.resolve(:cloudflare_api_key)` | `Ask::Provider::Cloudflare` |
+
+## Installation
+
+```ruby
+gem "ask-llm-providers"
+```
+
+## Usage
+
+```ruby
+require "ask-llm-providers"
+
+# All providers are auto-registered with Ask::Models
+models = Ask::Models.find("gpt-4o")
+# => { provider: :openai, capabilities: [...] }
+
+# Use a provider directly
+provider = Ask::Provider::OpenAI.new
+provider.chat(conversation, tools: [], model: "gpt-4o") do |chunk|
+  print chunk.content
+end
+```
+
+## Capabilities
+
+Each provider and model exposes its capabilities:
+
+```ruby
+provider = Ask::Provider::OpenAI.new
+provider.capabilities
+# => [:chat, :streaming, :tool_calls, :vision, :thinking,
+#     :structured_output, :embed, :transcribe, :paint, :moderate]
+
+model = Ask::Models.find("claude-sonnet-4-5")
+model[:capabilities]
+# => [:chat, :streaming, :tool_calls, :vision, :thinking, :prompt_caching]
+
+# Unsupported capabilities raise a helpful error
+provider = Ask::Provider::Anthropic.new
+provider.embed(["text"], model: "claude-sonnet-4-5")
+# => Ask::CapabilityNotSupported: Anthropic (claude-sonnet-4-5) does not support embeddings.
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/llm/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ask
+  module LLM
+    # Simple config wrapper without requiring ostruct.
+    # Wraps a hash and provides method-based access.
+    class Config
+      def initialize(hash = {})
+        @hash = (hash || {}).transform_keys(&:to_sym)
+        # Also accept string keys
+        hash.each { |k, v| @hash[k.to_sym] = v if k.is_a?(String) }
+      end
+
+      def method_missing(name, *args, &block)
+        if name.to_s.end_with?("=")
+          @hash[name.to_s.chomp("=").to_sym] = args.first
+        elsif args.empty?
+          @hash.key?(name) ? @hash[name] : nil
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @hash.key?(name.to_s.sub(/=$/, "").to_sym) || super
+      end
+
+      def to_h
+        @hash.dup
+      end
+    end
+  end
+end

data/lib/ask/llm/http.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ask
+  module LLM
+    # Shared HTTP infrastructure for all providers.
+    module HTTP
+      # Build a Faraday connection for a provider.
+      def self.connection(base_url, headers: {}, request: {})
+        Faraday.new(url: base_url, headers: headers, request: request) do |f|
+          f.request :json
+          f.response :json, content_type: /\bjson$/
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Map an HTTP exception or error response to the appropriate Ask::Error.
+      def self.map_error(status, body, provider:)
+        message = extract_error_message(body, status) || "HTTP #{status} from #{provider}"
+
+        # Check for context length exceeded regardless of status code
+        if body&.dig("error", "code") == "context_length_exceeded"
+          return Ask::ContextLengthExceeded.new("#{provider}: #{message}")
+        end
+
+        case status
+        when 400 then Ask::ProviderError.new(message, status_code: status, response_body: body&.to_json)
+        when 401, 403 then Ask::Unauthorized.new("#{provider}: #{message}")
+        when 429 then Ask::RateLimitError.new("#{provider}: #{message}")
+        when 500 then Ask::ServerError.new("#{provider}: #{message}")
+        when 503 then Ask::ServiceUnavailable.new("#{provider}: #{message}")
+        else Ask::ProviderError.new("#{provider}: #{message}", status_code: status, response_body: body&.to_json)
+        end
+      end
+
+      # Extract a human-readable error message from various provider error formats.
+      def self.extract_error_message(body, status)
+        return nil unless body
+
+        body.dig("error", "message") ||
+          body.dig("error", "msg") ||
+          body.dig("error", "error") ||
+          body["message"] ||
+          body.to_s
+      end
+    end
+  end
+end

data/lib/ask/llm/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module LLM
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/provider/anthropic.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Ask
+  module Providers
+    # Anthropic Claude API provider.
+    class Anthropic < Ask::Provider
+      def initialize(config = {})
+        config = normalize_config(config)
+        super(config)
+        @http = build_http
+      end
+
+      def api_base
+        @config.api_base || "https://api.anthropic.com"
+      end
+
+      def headers
+        {
+          "x-api-key" => @config.api_key,
+          "anthropic-version" => "2023-06-01",
+          "Content-Type" => "application/json"
+        }
+      end
+
+      def chat(messages, model:, tools: nil, temperature: nil, stream: nil, schema: nil, **params, &block)
+        msgs = messages.is_a?(Ask::Conversation) ? messages.to_a : messages
+        payload = build_chat_payload(msgs, model, tools, temperature, stream, schema, **params)
+        if stream
+          chat_stream(payload, model, &block)
+        else
+          chat_nonstream(payload, model)
+        end
+      end
+
+      def embed(_texts, model: nil)
+        raise Ask::UnsupportedFeature, "Anthropic does not support embeddings"
+      end
+
+      def list_models
+        response = @http.get("v1/models")
+        return [] unless response.success?
+        response.body["data"].map { |m| Ask::ModelInfo.new(id: m["id"], provider: slug) }
+      end
+
+      def parse_error(response)
+        body = response.body rescue nil
+        body&.dig("error", "message") || body&.dig("error", "type")
+      end
+
+      class << self
+        def capabilities
+          { chat: true, streaming: true, tool_calls: true, vision: true, thinking: true, prompt_caching: true, structured_output: true }
+        end
+        def configuration_options; %i[api_key api_base]; end
+        def configuration_requirements; %i[api_key]; end
+        def slug; "anthropic"; end
+      end
+
+      private
+
+      def normalize_config(config)
+        return config unless config.is_a?(Hash)
+        Ask::LLM::Config.new(
+          api_key: config[:api_key] || config["api_key"] || config[:anthropic_api_key],
+          api_base: config[:api_base] || config["api_base"]
+        )
+      end
+
+      def build_http
+        LLM::HTTP.connection(api_base, headers: headers, request: { open_timeout: 30, timeout: 120 })
+      end
+
+      def build_chat_payload(messages, model, tools, temperature, stream, schema, **params)
+        system_msgs, chat_msgs = messages.partition { |m| (m[:role] || m["role"]).to_s == "system" }
+        system_content = format_system_content(system_msgs)
+        tools_array = format_tools(tools) if tools&.any?
+
+        payload = {
+          model: model,
+          messages: chat_msgs.map { |m| format_message(m) },
+          max_tokens: params.delete(:max_tokens) || 4096,
+          stream: stream || false
+        }
+
+        payload[:system] = system_content if system_content
+        payload[:tools] = tools_array if tools_array
+        payload[:temperature] = temperature if temperature
+        payload.merge(params)
+      end
+
+      def format_system_content(messages)
+        return nil if messages.empty?
+        texts = messages.map { |m| m[:content] || m["content"] }.compact
+        return nil if texts.empty?
+        texts.join("\n")
+      end
+
+      def format_message(msg)
+        role = (msg[:role] || msg["role"]).to_s
+        content = msg[:content] || msg["content"]
+
+        # Handle tool calls
+        if msg[:tool_calls] || msg["tool_calls"]
+          tc = msg[:tool_calls] || msg["tool_calls"]
+          return {
+            role: role,
+            content: content,
+            tool_calls: tc.map { |t|
+              {
+                type: "tool_use",
+                id: t[:id] || t["id"],
+                name: t.dig(:function, :name) || t.dig("function", "name") || t[:name],
+                input: parse_json(t.dig(:function, :arguments) || t.dig("function", "arguments") || t[:arguments] || "{}")
+              }
+            }.compact
+          }.compact
+        end
+
+        # Handle tool results
+        if msg[:tool_call_id] || msg["tool_call_id"]
+          return {
+            role: "user",
+            content: [{
+              type: "tool_result",
+              tool_use_id: msg[:tool_call_id] || msg["tool_call_id"],
+              content: content || ""
+            }]
+          }
+        end
+
+        { role: role, content: content }.compact
+      end
+
+      def parse_json(str)
+        JSON.parse(str)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          {
+            name: t.respond_to?(:name) ? t.name : t[:name],
+            description: t.respond_to?(:description) ? t.description : t[:description],
+            input_schema: t.respond_to?(:parameters) ? t.parameters : (t[:parameters] || { type: "object", properties: {} })
+          }
+        end
+      end
+
+      def chat_nonstream(payload, model)
+        response = @http.post("v1/messages") { |r| r.body = payload }
+        raise LLM::HTTP.map_error(response.status, response.body, provider: "Anthropic") unless response.success?
+        parse_response(response.body, model)
+      end
+
+      def parse_response(body, model)
+        content_blocks = body["content"] || []
+        text_content = content_blocks.select { |c| c["type"] == "text" }.map { |c| c["text"] }.join
+        tool_blocks = content_blocks.select { |c| c["type"] == "tool_use" }
+        thinking_blocks = content_blocks.select { |c| %w[thinking redacted_thinking].include?(c["type"]) }
+        usage = body["usage"] || {}
+
+        tool_calls = tool_blocks.map do |tb|
+          { id: tb["id"], type: "function", name: tb["name"], arguments: JSON.generate(tb["input"]) }
+        end
+
+        metadata = {
+          model: body["model"] || model,
+          stop_reason: body["stop_reason"],
+          stop_sequence: body["stop_sequence"],
+          input_tokens: usage["input_tokens"],
+          output_tokens: usage["output_tokens"],
+          thinking: thinking_blocks.map { |b| b["thinking"] || b["text"] }.compact.join("\n"),
+          raw: body
+        }.compact
+
+        Ask::Message.new(role: :assistant, content: text_content.empty? ? nil : text_content, tool_calls: tool_calls.empty? ? nil : tool_calls, metadata: metadata)
+      end
+
+      def chat_stream(payload, model, &block)
+        stream = Ask::Stream.new
+        response = @http.post("v1/messages") do |req|
+          req.body = payload.merge(stream: true)
+          req.options.on_data = proc { |data, _bytes, _env| process_anthropic_chunk(data, stream, model, &block) }
+        end
+        raise LLM::HTTP.map_error(response.status, JSON.parse(response.body), provider: "Anthropic") unless response.success?
+        stream.finish!
+        stream
+      end
+
+      def process_anthropic_chunk(raw, stream, model)
+        raw.each_line do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?(":")
+          next unless line.start_with?("event:") || line.start_with?("data:")
+
+          if line.start_with?("data: ")
+            data = line[6..]
+            begin
+              parsed = JSON.parse(data)
+            rescue JSON::ParserError
+              next
+            end
+
+            case parsed["type"]
+            when "content_block_delta"
+              delta = parsed.dig("delta")
+              next unless delta
+              chunk = Ask::Chunk.new(
+                content: delta["text"],
+                finish_reason: delta["type"] == "thinking_delta" ? nil : nil
+              )
+              stream.add(chunk)
+              yield chunk if block_given?
+            when "message_stop"
+              usage = parsed["usage"] || parsed["message"]&.dig("usage")
+              if usage
+                chunk = Ask::Chunk.new(finish_reason: "stop", usage: usage)
+                stream.add(chunk)
+                yield chunk if block_given?
+              end
+            when "message_start"
+              # Message started — no content yet
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/provider/bedrock.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Ask
+  module Providers
+    # Amazon Bedrock provider using the Converse API.
+    # Uses the AWS SDK for authentication (credentials chain: env, ~/.aws, instance profile).
+    class Bedrock < Ask::Provider
+      def initialize(config = {})
+        config = normalize_config(config)
+        super(config)
+      end
+
+      def api_base
+        @config.region || "us-east-1"
+      end
+
+      def chat(messages, model:, tools: nil, temperature: nil, stream: nil, schema: nil, **params, &block)
+        msgs = messages.is_a?(Ask::Conversation) ? messages.to_a : messages
+        payload = build_converse_payload(msgs, model, tools, temperature, schema, **params)
+        if stream
+          chat_stream(payload, model, &block)
+        else
+          chat_nonstream(payload, model)
+        end
+      end
+
+      def embed(_texts, model: nil)
+        raise Ask::UnsupportedFeature, "Bedrock does not support embeddings via Converse API"
+      end
+
+      def list_models
+        # Bedrock doesn't have a list models endpoint — rely on model catalog
+        []
+      end
+
+      def parse_error(response)
+        response.body["message"] rescue nil
+      end
+
+      class << self
+        def capabilities
+          { chat: true, streaming: true, tool_calls: true, vision: true }
+        end
+        def configuration_options; %i[region access_key_id secret_access_key session_token]; end
+        def configuration_requirements; %i[]; end
+        def slug; "bedrock"; end
+      end
+
+      private
+
+      def normalize_config(config)
+        return config unless config.is_a?(Hash)
+        Ask::LLM::Config.new(
+          region: config[:region] || config["region"] || ENV["AWS_REGION"] || "us-east-1",
+          access_key_id: config[:access_key_id] || config["access_key_id"] || ENV["AWS_ACCESS_KEY_ID"],
+          secret_access_key: config[:secret_access_key] || config["secret_access_key"] || ENV["AWS_SECRET_ACCESS_KEY"],
+          session_token: config[:session_token] || config["session_token"] || ENV["AWS_SESSION_TOKEN"]
+        )
+      end
+
+      def build_converse_payload(messages, model, tools, temperature, schema, **params)
+        system_msgs, chat_msgs = messages.partition { |m| (m[:role] || m["role"]).to_s == "system" }
+        payload = {
+          modelId: model,
+          messages: chat_msgs.map { |m| format_bedrock_msg(m) },
+          inferenceConfig: { temperature: temperature || 1.0 }.compact
+        }
+
+        sys = system_msgs.map { |m| m[:content] || m["content"] }.compact
+        payload[:system] = sys.map { |s| { text: s } } if sys.any?
+        if tools&.any?
+          payload[:toolConfig] = { tools: format_bedrock_tools(tools) }
+        end
+        if schema
+          payload[:inferenceConfig][:response_type] = "json_object"
+        end
+        payload.merge(params)
+      end
+
+      def format_bedrock_msg(msg)
+        role = (msg[:role] || msg["role"]).to_s
+        content = msg[:content] || msg["content"]
+        bedrock_role = role == "assistant" ? "assistant" : "user"
+        parts = []
+
+        parts << { text: content } if content
+
+        if msg[:tool_calls] || msg["tool_calls"]
+          (msg[:tool_calls] || msg["tool_calls"]).each do |tc|
+            parts << {
+              toolUse: {
+                toolUseId: tc[:id] || tc["id"],
+                name: tc.dig(:function, :name) || tc.dig("function", "name") || tc[:name],
+                input: parse_json(tc.dig(:function, :arguments) || tc.dig("function", "arguments") || tc[:arguments] || "{}")
+              }
+            }
+          end
+        end
+
+        if msg[:tool_call_id] || msg["tool_call_id"]
+          parts << {
+            toolResult: {
+              toolUseId: msg[:tool_call_id] || msg["tool_call_id"],
+              content: [{ text: content || "" }]
+            }
+          }
+          bedrock_role = "user"
+        end
+
+        { role: bedrock_role, content: parts }
+      end
+
+      def format_bedrock_tools(tools)
+        tools.map do |t|
+          { toolSpec: { name: t.respond_to?(:name) ? t.name : t[:name], description: t.respond_to?(:description) ? t.description : t[:description], inputSchema: { json: t.respond_to?(:parameters) ? t.parameters : (t[:parameters] || { type: "object", properties: {} }) } } }
+        end
+      end
+
+      def parse_json(str)
+        JSON.parse(str)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def bedrock_client
+        require "aws-sdk-bedrockruntime"
+        Aws::BedrockRuntime::Client.new(region: @config.region)
+      end
+
+      def chat_nonstream(payload, model)
+        client = bedrock_client
+        resp = client.converse(payload)
+        parse_bedrock_response(resp, model)
+      rescue Aws::Errors::ServiceError => e
+        raise LLM::HTTP.map_error(e.status_code&.to_i || 500, { message: e.message }, provider: "Bedrock")
+      end
+
+      def parse_bedrock_response(resp, model)
+        output = resp.output
+        return Ask::Message.new(role: :assistant, content: nil) unless output
+
+        msg = output.message
+        text = msg.content&.map { |c| c.text }&.compact&.join
+        tool_uses = msg.content&.select { |c| c.tool_use } || []
+        tool_calls = tool_uses.map do |tu|
+          { id: tu.tool_use.tool_use_id, type: "function", name: tu.tool_use.name, arguments: JSON.generate(tu.tool_use.input.to_h) }
+        end
+
+        usage = resp.usage || {}
+        Ask::Message.new(role: :assistant, content: text, tool_calls: tool_calls.empty? ? nil : tool_calls, metadata: { model: model, stop_reason: resp.stop_reason, input_tokens: usage.input_tokens, output_tokens: usage.output_tokens, raw: resp.to_h })
+      end
+
+      def chat_stream(payload, model, &block)
+        client = bedrock_client
+        stream = Ask::Stream.new
+        resp = client.converse_stream(payload)
+        resp.stream.each do |event|
+          if event.content_block_delta
+            delta = event.content_block_delta.delta
+            chunk = Ask::Chunk.new(content: delta.text) if delta.respond_to?(:text)
+            if chunk
+              stream.add(chunk)
+              yield chunk if block_given?
+            end
+          end
+          if event.message_stop
+            usage = event.message_stop.usage || {}
+            chunk = Ask::Chunk.new(finish_reason: "stop", usage: { input_tokens: usage.input_tokens, output_tokens: usage.output_tokens })
+            stream.add(chunk)
+            yield chunk if block_given?
+          end
+        end
+        stream.finish!
+        stream
+      rescue Aws::Errors::ServiceError => e
+        raise LLM::HTTP.map_error(e.status_code&.to_i || 500, { message: e.message }, provider: "Bedrock")
+      end
+    end
+  end
+end