ask-llm-providers 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 677ec905a0f11d7072c4574d03193b85720065778678e940b38252d2adc2f1a0
-  data.tar.gz: 9cb65bb51e2ea18e6b7c1b92e0d7fcce64aab4b4d8e9d5493215200928e35eb9
+  metadata.gz: b0b23746b8ee8cc98e50c44f9e88df977ea81d9214bbda9a25be770021234cc2
+  data.tar.gz: 2a2e628b12eb8e731ea9d46ae0f4076dd42591f03db0cf50759d77d6485e748e
 SHA512:
-  metadata.gz: cf49fac238b8ce8a9a8df31dcab9a3854d35401eb45699bbb964b01bf50417e544ba5095a9c9b1e40c68b11095f1d3e35bad386b5549a6a6a8793e28ebb0b85b
-  data.tar.gz: 99e31531be1bbc2b0930f957630118d77de620e3e668750f04ea966a1bcd0c627339623ba59fae69464c7aa07bfe39be354f5934f145d2b6dcb3d8fb24c73c81
+  metadata.gz: 4e31b5f82ae3aaab7a7bf337df1ebd5afc20b272efc2b630523145bbf82ebbd12faddcaacdb30e531df3cd3a379a82d9d2e96b97d9ff33877eff6eb0c638d320
+  data.tar.gz: 2db527541cb1a8934c6f5ff2e62fbb8ebddf633600e332b040231461eaf9c9b5cb37ec3a70f0079a85404cf8b5fb3751c4f9b88ef075366681044d046ebfdd6b

data/README.md

@@ -7,14 +7,14 @@ from `ask-core` with a capabilities-based interface.
 
 | 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` |
+| **OpenAI** + all OpenAI-compatible | `Ask::Auth.resolve(:openai_api_key)` | `Ask::Providers::OpenAI` |
+| **Anthropic** (Claude) | `Ask::Auth.resolve(:anthropic_api_key)` | `Ask::Providers::Anthropic` |
+| **Google Gemini** | `Ask::Auth.resolve(:gemini_api_key)` | `Ask::Providers::Google` |
+| **Vertex AI** | GCP service account | `Ask::Providers::Google` (via Vertex) |
+| **Amazon Bedrock** | AWS credentials chain | `Ask::Providers::Bedrock` |
+| **Ollama** (local) | None needed | `Ask::Providers::Ollama` |
+| **Mistral AI** | `Ask::Auth.resolve(:mistral_api_key)` | `Ask::Providers::Mistral` |
+| **Cloudflare Workers AI** | `Ask::Auth.resolve(:cloudflare_api_key)` | `Ask::Providers::Cloudflare` |
 
 ## Installation
 
@@ -32,7 +32,7 @@ models = Ask::Models.find("gpt-4o")
 # => { provider: :openai, capabilities: [...] }
 
 # Use a provider directly
-provider = Ask::Provider::OpenAI.new
+provider = Ask::Providers::OpenAI.new
 provider.chat(conversation, tools: [], model: "gpt-4o") do |chunk|
   print chunk.content
 end
@@ -43,21 +43,75 @@ end
 Each provider and model exposes its capabilities:
 
 ```ruby
-provider = Ask::Provider::OpenAI.new
+provider = Ask::Providers::OpenAI.new
 provider.capabilities
-# => [:chat, :streaming, :tool_calls, :vision, :thinking,
+# => { chat: true, streaming: true, tool_calls: true, vision: true, thinking: true,
 #     :structured_output, :embed, :transcribe, :paint, :moderate]
 
 model = Ask::Models.find("claude-sonnet-4-5")
 model[:capabilities]
-# => [:chat, :streaming, :tool_calls, :vision, :thinking, :prompt_caching]
+# => { chat: true, streaming: true, tool_calls: true, vision: true, thinking: true, :prompt_caching]
 
 # Unsupported capabilities raise a helpful error
-provider = Ask::Provider::Anthropic.new
+provider = Ask::Providers::Anthropic.new
 provider.embed(["text"], model: "claude-sonnet-4-5")
 # => Ask::CapabilityNotSupported: Anthropic (claude-sonnet-4-5) does not support embeddings.
 ```
 
+
+
+## Streaming
+
+```ruby
+stream = provider.chat(
+  [{ role: "user", content: "Tell me a story" }],
+  model: "gpt-4o",
+  stream: true
+) do |chunk|
+  print chunk.content
+end
+
+# After streaming completes, you can access the full response
+puts stream.accumulated_text
+puts stream.accumulated_usage
+```
+
+## Tool Calls
+
+```ruby
+tools = [{
+  name: "get_weather",
+  description: "Get weather for a location",
+  parameters: {
+    type: "object",
+    properties: { location: { type: "string" } },
+    required: ["location"]
+  }
+}]
+
+response = provider.chat(
+  [{ role: "user", content: "What's the weather in NYC?" }],
+  model: "gpt-4o",
+  tools: tools
+)
+# response.tool_call? => true
+# response.tool_calls => [{ id: "call_1", name: "get_weather", arguments: '{"location":"NYC"}' }]
+```
+
+## Error Handling
+
+Provider errors map to structured `Ask::Error` types:
+
+```ruby
+Ask::RateLimitError       # 429 — retry with backoff
+Ask::Unauthorized         # 401/403 — check your API key
+Ask::ServerError          # 500 — provider issue
+Ask::ServiceUnavailable   # 503 — temporary
+Ask::ContextLengthExceeded # context window exceeded
+Ask::ProviderError        # other provider errors
+Ask::CapabilityNotSupported # feature not available on this model
+```
+
 ## Development
 
 ```bash

data/lib/ask/llm/models/openai.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Model definitions for OpenAI and compatible providers.
+# Registered on gem load via Ask::Models.register.
+module Ask
+  module LLM
+    module Models
+      OPENAI_MODELS = [
+        { id: "gpt-4o", family: "gpt4o", capabilities: %w[chat streaming function_calling structured_output vision], context: 128000, output: 16384 },
+        { id: "gpt-4o-mini", family: "gpt4o_mini", capabilities: %w[chat streaming function_calling structured_output vision], context: 128000, output: 16384 },
+        { id: "gpt-4.1", family: "gpt41", capabilities: %w[chat streaming function_calling structured_output vision], context: 1047576, output: 32768 },
+        { id: "gpt-4.1-mini", family: "gpt41_mini", capabilities: %w[chat streaming function_calling structured_output vision], context: 1047576, output: 32768 },
+        { id: "gpt-4.1-nano", family: "gpt41_nano", capabilities: %w[chat streaming function_calling structured_output vision], context: 1047576, output: 32768 },
+        { id: "gpt-4-turbo", family: "gpt4_turbo", capabilities: %w[chat streaming function_calling vision], context: 128000, output: 4096 },
+        { id: "gpt-4", family: "gpt4", capabilities: %w[chat streaming function_calling], context: 8192, output: 8192 },
+        { id: "o1", family: "o1", capabilities: %w[chat streaming function_calling structured_output reasoning], context: 200000, output: 100000 },
+        { id: "o1-mini", family: "o1_mini", capabilities: %w[chat streaming function_calling reasoning], context: 128000, output: 65536 },
+        { id: "o3-mini", family: "o3_mini", capabilities: %w[chat streaming function_calling structured_output reasoning], context: 200000, output: 100000 },
+        { id: "gpt-4o-audio-preview", family: "gpt4o_audio", capabilities: %w[chat streaming audio], context: 128000 },
+        { id: "gpt-4o-realtime-preview", family: "gpt4o_realtime", capabilities: %w[chat streaming audio], context: 128000 },
+        { id: "gpt-4o-mini-realtime-preview", family: "gpt4o_mini_realtime", capabilities: %w[chat streaming audio], context: 128000 },
+        { id: "gpt-4.5-preview", family: "gpt45", capabilities: %w[chat streaming function_calling structured_output vision], context: 128000, output: 16384 },
+        { id: "text-embedding-3-large", family: "embedding3_large", capabilities: %w[embed], context: 8191 },
+        { id: "text-embedding-3-small", family: "embedding3_small", capabilities: %w[embed], context: 8191 },
+        { id: "whisper-1", family: "whisper", capabilities: %w[transcribe] },
+        { id: "tts-1", family: "tts1", capabilities: %w[tts] },
+        { id: "tts-1-hd", family: "tts1_hd", capabilities: %w[tts] },
+        { id: "dall-e-3", family: "dall_e", capabilities: %w[paint] },
+        { id: "dall-e-2", family: "dall_e", capabilities: %w[paint] }
+      ].freeze
+
+      ANTHROPIC_MODELS = [
+        { id: "claude-sonnet-4-5", family: "claude_sonnet", capabilities: %w[chat streaming function_calling vision thinking prompt_caching], context: 200000, output: 8192 },
+        { id: "claude-sonnet-4", family: "claude_sonnet", capabilities: %w[chat streaming function_calling vision thinking prompt_caching], context: 200000, output: 8192 },
+        { id: "claude-4-opus", family: "claude_opus", capabilities: %w[chat streaming function_calling vision thinking prompt_caching], context: 200000, output: 8192 },
+        { id: "claude-3.5-sonnet", family: "claude_sonnet", capabilities: %w[chat streaming function_calling vision thinking], context: 200000, output: 8192 },
+        { id: "claude-3.5-haiku", family: "claude_haiku", capabilities: %w[chat streaming function_calling vision thinking], context: 200000, output: 8192 },
+        { id: "claude-3-opus", family: "claude_opus", capabilities: %w[chat streaming function_calling vision thinking], context: 200000, output: 4096 },
+        { id: "claude-3-sonnet", family: "claude_sonnet", capabilities: %w[chat streaming function_calling vision], context: 200000, output: 4096 },
+        { id: "claude-3-haiku", family: "claude_haiku", capabilities: %w[chat streaming function_calling vision], context: 200000, output: 4096 }
+      ].freeze
+
+      GOOGLE_MODELS = [
+        { id: "gemini-2.5-pro", family: "gemini", capabilities: %w[chat streaming function_calling structured_output vision reasoning], context: 1048576, output: 65536 },
+        { id: "gemini-2.5-flash", family: "gemini", capabilities: %w[chat streaming function_calling structured_output vision], context: 1048576, output: 65536 },
+        { id: "gemini-2.0-flash", family: "gemini", capabilities: %w[chat streaming function_calling structured_output vision], context: 1048576, output: 8192 },
+        { id: "gemini-1.5-pro", family: "gemini", capabilities: %w[chat streaming function_calling structured_output vision], context: 2097152, output: 8192 },
+        { id: "gemini-1.5-flash", family: "gemini", capabilities: %w[chat streaming function_calling structured_output vision], context: 1048576, output: 8192 },
+        { id: "text-embedding-004", family: "embedding", capabilities: %w[embed], context: 2048 }
+      ].freeze
+
+      MISTRAL_MODELS = [
+        { id: "mistral-large-2501", family: "mistral", capabilities: %w[chat streaming function_calling structured_output], context: 128000, output: 4096 },
+        { id: "mistral-small-2501", family: "mistral", capabilities: %w[chat streaming function_calling structured_output], context: 128000, output: 4096 },
+        { id: "mistral-embed", family: "mistral", capabilities: %w[embed], context: 8192 }
+      ].freeze
+
+      OLLAMA_MODELS = [
+        { id: "llama3.2", family: "llama", capabilities: %w[chat streaming], context: 8192 },
+        { id: "llama3.3", family: "llama", capabilities: %w[chat streaming], context: 8192 },
+        { id: "mistral", family: "mistral", capabilities: %w[chat streaming], context: 8192 },
+        { id: "gemma3", family: "gemma", capabilities: %w[chat streaming], context: 8192 },
+        { id: "phi4", family: "phi", capabilities: %w[chat streaming], context: 8192 },
+        { id: "qwen2.5", family: "qwen", capabilities: %w[chat streaming], context: 32768 },
+        { id: "deepseek-r1", family: "deepseek", capabilities: %w[chat streaming reasoning], context: 8192 }
+      ].freeze
+    end
+  end
+end

data/lib/ask/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module LLM
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/ask/provider/anthropic.rb

@@ -33,7 +33,7 @@ module Ask
       end
 
       def embed(_texts, model: nil)
-        raise Ask::UnsupportedFeature, "Anthropic does not support embeddings"
+        raise Ask::CapabilityNotSupported, "Anthropic does not support embeddings"
       end
 
       def list_models

data/lib/ask/provider/bedrock.rb

@@ -25,7 +25,7 @@ module Ask
       end
 
       def embed(_texts, model: nil)
-        raise Ask::UnsupportedFeature, "Bedrock does not support embeddings via Converse API"
+        raise Ask::CapabilityNotSupported, "Bedrock does not support embeddings via Converse API"
       end
 
       def list_models

data/lib/ask/provider/openai.rb

@@ -7,6 +7,7 @@ module Ask
     # +base_url+ override.
     class OpenAI < Ask::Provider
       def initialize(config = {})
+        @provider_keys = extract_provider_keys(config)
         config = normalize_config(config)
         super(config)
         @http = build_http
@@ -51,28 +52,37 @@ module Ask
       end
 
       class << self
-def slug; "openai"; end
-                def capabilities
+        def slug; "openai"; end
+        def capabilities
           { chat: true, streaming: true, tool_calls: true, vision: true, thinking: true, structured_output: true, embed: true, transcribe: true, paint: true, moderate: true }
         end
         def configuration_options; %i[api_key base_url organization_id project_id]; end
         def configuration_requirements; %i[api_key]; end
-                def configured?(config)
-          (config.respond_to?(:api_key) && !config.api_key.to_s.empty?) ||
-            (config.respond_to?(:openai_api_key) && !config.openai_api_key.to_s.empty?)
-        end
+        def assume_models_exist?; false; end
       end
 
       private
 
+      # Extract and store any provider-specific config keys (e.g., opencode_api_key).
+      # These are not part of the standard OpenAI config but are used by subclasses.
+      def extract_provider_keys(config)
+        return {} unless config.is_a?(Hash)
+        known = %i[api_key base_url organization_id project_id openai_api_key]
+        config.reject { |k, _| known.include?(k.to_sym) }
+      end
+
+      # Restore provider-specific keys after normalize_config strips standard ones.
       def normalize_config(config)
         return config if !config.is_a?(Hash)
-        Ask::LLM::Config.new(
+
+        merged = {
           api_key: config[:api_key] || config["api_key"] || config[:openai_api_key],
           base_url: config[:base_url] || config["base_url"],
           organization_id: config[:organization_id] || config["organization_id"],
           project_id: config[:project_id] || config["project_id"]
-        )
+        }.merge(@provider_keys)
+
+        Ask::LLM::Config.new(merged)
       end
 
       def build_http
@@ -140,12 +150,22 @@ def slug; "openai"; end
           parsed = JSON.parse(data) rescue next
           choice = parsed.dig("choices", 0) or next
           delta = choice["delta"] || {}
-          chunk = Ask::Chunk.new(content: delta["content"], tool_calls: parse_stream_tool_calls(delta["tool_calls"]), finish_reason: choice["finish_reason"], usage: parsed["usage"])
+          thinking = extract_thinking(parsed, delta)
+          chunk = Ask::Chunk.new(content: delta["content"], tool_calls: parse_stream_tool_calls(delta["tool_calls"]), finish_reason: choice["finish_reason"], usage: parsed["usage"], thinking: thinking)
           stream.add(chunk)
           yield chunk if block_given?
         end
       end
 
+      # Extract thinking/reasoning content from provider response.
+      # Some providers (Anthropic, DeepSeek) send thinking in a separate field.
+      def extract_thinking(parsed, delta)
+        delta["reasoning_content"] || delta["thinking"] ||
+          parsed.dig("choices", 0, "delta", "reasoning_content") ||
+          parsed.dig("choices", 0, "delta", "thinking") ||
+          parsed.dig("choices", 0, "reasoning_content")
+      end
+
       def parse_stream_tool_calls(calls)
         return nil unless calls&.any?
         calls.map { |tc| { id: tc["id"], name: tc.dig("function", "name"), arguments: tc.dig("function", "arguments"), index: tc["index"] } }

data/lib/ask-llm-providers.rb

@@ -10,6 +10,7 @@ require "base64"
 # Common infrastructure
 require_relative "ask/llm/config"
 require_relative "ask/llm/http"
+require_relative "ask/llm/models/openai"
 
 # Load providers
 require_relative "ask/provider/openai"
@@ -28,3 +29,21 @@ Ask::Provider.register(:bedrock, Ask::Providers::Bedrock)
 Ask::Provider.register(:ollama, Ask::Providers::Ollama)
 Ask::Provider.register(:mistral, Ask::Providers::Mistral)
 Ask::Provider.register(:cloudflare, Ask::Providers::Cloudflare)
+
+
+# Register known models for each provider in the catalog
+[
+  [Ask::Providers::OpenAI, Ask::LLM::Models::OPENAI_MODELS],
+  [Ask::Providers::Anthropic, Ask::LLM::Models::ANTHROPIC_MODELS],
+  [Ask::Providers::Google, Ask::LLM::Models::GOOGLE_MODELS],
+  [Ask::Providers::Mistral, Ask::LLM::Models::MISTRAL_MODELS],
+  [Ask::Providers::Ollama, Ask::LLM::Models::OLLAMA_MODELS]
+].each do |provider, models|
+  models.each do |m|
+    Ask::ModelCatalog.instance.register(Ask::ModelInfo.new(
+      id: m[:id], provider: provider.slug, family: m[:family],
+      capabilities: m[:capabilities],
+      context_window: m[:context], max_output_tokens: m[:output]
+    ))
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-llm-providers
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto
@@ -13,16 +13,16 @@ dependencies:
   name: ask-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: ask-auth
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -163,6 +177,7 @@ files:
 - lib/ask-llm-providers.rb
 - lib/ask/llm/config.rb
 - lib/ask/llm/http.rb
+- lib/ask/llm/models/openai.rb
 - lib/ask/llm/version.rb
 - lib/ask/provider/anthropic.rb
 - lib/ask/provider/bedrock.rb