ask-llm-providers 0.1.5 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98e73dfa923583db079237386caab024766c6613b202623b73952d3233ddf3ae
-  data.tar.gz: 0aeef8d5eface2a50ffa4365c1d8e53fb47de3d0be54eb88c4ba53dea6fecfff
+  metadata.gz: e0a952555ce477b6a2e1ad523112f779a25cd526e0f255a8b6bac78dca33e1c8
+  data.tar.gz: 1b90e7fe032a0295fff1a9284045b08bb1a3f82d6c3559b9ecf7f47b7a0d2d0c
 SHA512:
-  metadata.gz: 94dd687fc071961fe2495e61788861d676470b42e7352ff5f2d9c53455fe090d9d93c1b122a7b1d769f347d81b7059b44fffb18235fa7c66910b36b193b9f890
-  data.tar.gz: 88d1dbcb9f4fb92d8a447352c725c6e27e89bbc29f46f7d83e96856c9288ec18bcbda236b04e6e7eb85df901187e3f5fcef56c464f5b101b3a12a53534dc2f20
+  metadata.gz: 57eea3bd9cb97969545688494f37be34cc029e94ea7ee0224efd8041b7534e8b6fab82af2c35f276ef9a7b7f8a64a84edff94972b92508554d37b4dafe556f90
+  data.tar.gz: 0fc0ba47aa5437fd38cc0734ca84b15736072d925dea337d3a8f12f2226379c0fa6824e9648829ca5c67860460039457402ec87740690844c89eed97d6c6a3eb

data/lib/ask/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module LLM
-    VERSION = "0.1.5"
+    VERSION = "0.1.8"
   end
 end

data/lib/ask/provider/deepseek.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ask
+  module Providers
+    # DeepSeek API — an OpenAI-compatible provider at api.deepseek.com.
+    # Supports DeepSeek V2, V3, V4 Chat, R1 reasoning, and all DeepSeek models
+    # via the OpenAI-compatible endpoint.
+    #
+    # Configuration via environment:
+    #   DEEPSEEK_API_KEY  — required, your DeepSeek API key
+    #   DEEPSEEK_API_BASE — optional, base URL (default: https://api.deepseek.com)
+    class DeepSeek < OpenAI
+      def api_base
+        @config.base_url || ENV["DEEPSEEK_API_BASE"] || "https://api.deepseek.com"
+      end
+
+      def headers
+        key = @config.api_key || ENV["DEEPSEEK_API_KEY"]
+        h = { "Content-Type" => "application/json" }
+        h["Authorization"] = "Bearer #{key}" if key
+        h
+      end
+
+      class << self
+        def slug; "deepseek"; end
+        def configuration_options; %i[api_key base_url]; end
+        def configuration_requirements; %i[api_key]; end
+        def configured?(config)
+          key = config.respond_to?(:api_key) ? config.api_key : nil
+          key ||= ENV["DEEPSEEK_API_KEY"]
+          key.to_s.length > 0
+        end
+      end
+    end
+  end
+end

data/lib/ask/provider/openai.rb

@@ -71,16 +71,23 @@ module Ask
         config.reject { |k, _| known.include?(k.to_sym) }
       end
 
-      # Restore provider-specific keys after normalize_config strips standard ones.
+      # Resolve provider config from passed options, env vars, and ask-auth chain.
       def normalize_config(config)
         return config if !config.is_a?(Hash)
 
+        slug = self.class.slug
+        env_key = ENV["#{slug.upcase}_API_KEY"]
+        auth_key = Ask::Auth.resolve(:"#{slug}_api_key") rescue nil
+
         merged = {
-          api_key: config[:api_key] || config["api_key"] || config[:openai_api_key],
-          base_url: config[:base_url] || config["base_url"],
+          api_key: config[:api_key] || config["api_key"] ||
+                   config[:"#{slug}_api_key"] || config[:openai_api_key] ||
+                   env_key || auth_key,
+          base_url: config[:base_url] || config["base_url"] ||
+                    ENV["#{slug.upcase}_API_BASE"],
           organization_id: config[:organization_id] || config["organization_id"],
           project_id: config[:project_id] || config["project_id"]
-        }.merge(@provider_keys)
+        }.merge(config.reject { |k, _| %i[api_key base_url organization_id project_id openai_api_key].include?(k.to_sym) })
 
         Ask::LLM::Config.new(merged)
       end
@@ -174,23 +181,3 @@ module Ask
     end
   end
 end
-
-# When the OpenAI provider is subclassed (e.g. OpenCode), normalize_config
-# should also check for env vars matching the subclass slug.
-def normalize_config(config)
-  return config if !config.is_a?(Hash)
-
-  slug = self.class.slug
-  env_key = ENV["#{slug.upcase}_API_KEY"]
-  env_base = ENV["#{slug.upcase}_API_BASE"]
-
-  merged = {
-    api_key: config[:api_key] || config["api_key"] || config[:"#{slug}_api_key"] || config[:"#{slug}_api_key"] || config[:openai_api_key] || env_key,
-    base_url: config[:base_url] || config["base_url"] || env_base,
-    organization_id: config[:organization_id] || config["organization_id"],
-    project_id: config[:project_id] || config["project_id"]
-  }.merge(config.reject { |k, _| %i[api_key base_url organization_id project_id openai_api_key].include?(k.to_sym) })
-
-  # Also preserve original config for subclass-specific key access
-  Ask::LLM::Config.new(merged)
-end

data/lib/ask/provider/openrouter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ask
+  module Providers
+    # OpenRouter API — an OpenAI-compatible aggregator at openrouter.ai.
+    # Provides access to many models through a single endpoint.
+    #
+    # Configuration via environment:
+    #   OPENROUTER_API_KEY  — required, your OpenRouter API key
+    #   OPENROUTER_API_BASE — optional, base URL (default: https://openrouter.ai/api/v1)
+    class OpenRouter < OpenAI
+      def api_base
+        @config.base_url || ENV["OPENROUTER_API_BASE"] || "https://openrouter.ai/api/v1"
+      end
+
+      def headers
+        h = super
+        key = @config.api_key || ENV["OPENROUTER_API_KEY"]
+        h["Authorization"] = "Bearer #{key}" if key
+        h["HTTP-Referer"] = ENV["OPENROUTER_REFERER"] || "https://github.com/ask-rb"
+        h["X-Title"] = ENV["OPENROUTER_APP_TITLE"] || "ask-rb"
+        h
+      end
+
+      class << self
+        def slug; "openrouter"; end
+        def configuration_options; %i[api_key base_url]; end
+        def configuration_requirements; %i[api_key]; end
+        def configured?(config)
+          key = config.respond_to?(:api_key) ? config.api_key : nil
+          key ||= ENV["OPENROUTER_API_KEY"]
+          key.to_s.length > 0
+        end
+      end
+    end
+  end
+end

data/lib/ask/skills/providers.model_select/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: providers.model_select
+description: How to select the right LLM model for a task — balancing cost, capability, latency, and context window
+---
+
+Use this skill when choosing an LLM model for a specific task. The ask-rb
+ecosystem uses `Ask::ModelCatalog` to resolve models and check capabilities.
+
+## Step 1: Classify the Task
+
+Determine what kind of task you're solving:
+
+| Task Type | Examples | Key Requirements |
+|-----------|----------|-----------------|
+| **Simple chat** | Q&A, summarization, translation | Speed, low cost |
+| **Code generation** | Write functions, review PRs | Strong coding, large context |
+| **Reasoning/analysis** | Debugging, architecture, planning | Deep reasoning, structured output |
+| **Structured extraction** | Parse logs, extract data | JSON mode, function calling |
+| **Vision/multimodal** | Screenshot analysis, document OCR | Image input support |
+| **Long document** | Analyze 100+ page docs | Large context window (200K+) |
+| **Embeddings** | Semantic search, RAG | Embedding model, dimensions |
+
+## Step 2: Query the Model Catalog
+
+Access available models through the catalog:
+
+```ruby
+# List all models
+Ask::ModelCatalog.all
+
+# Filter by capability
+Ask::ModelCatalog.chat_models
+Ask::ModelCatalog.by_provider("openai")
+Ask::ModelCatalog.by_family("gpt")
+Ask::ModelCatalog.embedding_models
+```
+
+Find a specific model by ID:
+
+```ruby
+model = Ask::ModelCatalog.find("gpt-4o")
+model.context_window    # => 128000
+model.max_output_tokens # => 16384
+model.supports?(:function_calling) # => true
+model.capabilities      # => ["function_calling", "structured_output", "reasoning", "vision"]
+model.modalities        # => { input: ["text", "image"], output: ["text"] }
+```
+
+If the catalog doesn't have the model you need, refresh:
+
+```ruby
+Ask::ModelCatalog.refresh!
+```
+
+## Step 3: Evaluate Cost vs Capability
+
+Use pricing data from the catalog:
+
+```ruby
+model = Ask::ModelCatalog.find("gpt-4o")
+pricing = model.pricing.dig(:text_tokens, :standard)
+pricing[:input_per_million]   # $ per 1M input tokens
+pricing[:output_per_million]  # $ per 1M output tokens
+```
+
+**Cost comparison (approximate):**
+
+| Tier | Models | Cost/M tokens (in) | Best For |
+|------|--------|-------------------|----------|
+| **Frontier** | GPT-4o, Claude 4 Sonnet, Gemini 2.5 Pro | $3-15 | Complex reasoning, code generation |
+| **Fast/Cheap** | GPT-4o-mini, Claude 4 Haiku, Gemini 2.5 Flash | $0.15-1.00 | Simple chat, extraction, classification |
+| **Reasoning** | o3, o4-mini, DeepSeek R1 | $2-10 | Deep analysis, math, multi-step tasks |
+| **Specialized** | Embedding, image, audio models | Varies | Non-chat tasks |
+
+## Step 4: Match Capabilities to Task Requirements
+
+Check if a model supports the features you need:
+
+```ruby
+model.supports?(:function_calling) # For tool use
+model.supports?(:structured_output) # For JSON mode
+model.supports?(:vision)           # For image analysis
+model.supports?(:reasoning)        # For complex reasoning
+```
+
+**Capability requirements by task:**
+
+| Need | Check | Fallback |
+|------|-------|----------|
+| Tool calling | `supports?(:function_calling)` | Use text instruction instead |
+| JSON output | `supports?(:structured_output)` | Prompt-engineering |
+| Image processing | `modalities[:input].include?("image")` | Describe image in text |
+| Audio processing | `modalities[:input].include?("audio")` | Transcribe first |
+| Deep reasoning | `supports?(:reasoning)` | Chain-of-thought prompting |
+
+## Step 5: Consider Context Window Requirements
+
+Choose context window based on your input size:
+
+```ruby
+model.context_window  # total tokens the model can process
+```
+
+**Guidelines:**
+- **8K-16K** — Simple Q&A, short conversations
+- **32K-64K** — Code review, medium documents, multi-turn conversations
+- **100K-200K** — Large codebases, long documents, RAG with many chunks
+- **1M-2M** — Gemini 2.5 Pro, Gemini 2.0 Flash for massive documents
+
+Be aware that large context windows increase latency and cost even if you don't
+use them all.
+
+## Step 6: Pick the Right Embedding Model
+
+For RAG and semantic search:
+
+```ruby
+Ask::ModelCatalog.embedding_models
+```
+
+**Recommendations:**
+- **General purpose**: `text-embedding-3-large` (256-3072 dims)
+- **Best accuracy**: `text-embedding-3-large` with 3072 dimensions
+- **Fast/Cheap**: `text-embedding-3-small` (512 dimensions)
+- **Multilingual**: `text-embedding-3-small` (supports 100+ languages)
+
+## Decision Tree
+
+```
+Task Type?
+├── Simple chat / extraction
+│   └── Fast model (GPT-4o-mini, Claude 4 Haiku)
+│       → Cheapest adequate model
+├── Code generation / review
+│   └── Frontier model (GPT-4o, Claude 4 Sonnet)
+│       → Needs function calling + max capability
+├── Deep reasoning / debugging
+│   └── Reasoning model (o4-mini, DeepSeek R1, o3)
+│       → Needs chain-of-thought + analysis
+├── Long document analysis
+│   └── Large context (Gemini 2.5 Pro 1M, GPT-4o)
+│       → Needs context window > input size
+├── Multimodal (image/video)
+│   └── Vision-capable (GPT-4o, Claude 4 Sonnet, Gemini 2.5)
+│       → Check modalities[:input] includes image
+├── Embeddings / RAG
+│   └── text-embedding-3-large / small
+│       → Not a chat model
+└── Audio / Voice
+    └── GPT-4o-audio, Gemini Audio
+        → Check modalities[:output] includes audio
+```
+
+## Provider Selection
+
+Consider provider reliability and features:
+
+| Provider | Strengths | Weaknesses |
+|----------|-----------|------------|
+| **OpenAI** | Best tool calling, broad model range | Higher cost for frontier |
+| **Anthropic** | Excellent code, long context | Slower for simple tasks |
+| **Google Gemini** | Massive context (1M+), fast | Fewer integration tools |
+| **DeepSeek** | Cheap reasoning, open weights | Limited ecosystem |
+| **Ollama** | Local, free, private | Slow, no hosted offerings |

data/lib/ask-llm-providers.rb

@@ -23,6 +23,8 @@ require_relative "ask/provider/cloudflare"
 require_relative "ask/provider/opencode"
 require_relative "ask/provider/opencode_go"
 require_relative "ask/provider/mimo"
+require_relative "ask/provider/deepseek"
+require_relative "ask/provider/openrouter"
 
 # Register providers with the Ask::Provider registry
 Ask::Provider.register(:openai, Ask::Providers::OpenAI)
@@ -35,6 +37,8 @@ Ask::Provider.register(:cloudflare, Ask::Providers::Cloudflare)
 Ask::Provider.register(:opencode, Ask::Providers::OpenCode)
 Ask::Provider.register(:opencode_go, Ask::Providers::OpenCodeGo)
 Ask::Provider.register(:mimo, Ask::Providers::Mimo)
+Ask::Provider.register(:deepseek, Ask::Providers::DeepSeek)
+Ask::Provider.register(:openrouter, Ask::Providers::OpenRouter)
 
 # Register known models for each provider in the catalog
 [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-llm-providers
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.8
 platform: ruby
 authors:
 - Kaka Ruto
@@ -182,6 +182,7 @@ files:
 - lib/ask/provider/anthropic.rb
 - lib/ask/provider/bedrock.rb
 - lib/ask/provider/cloudflare.rb
+- lib/ask/provider/deepseek.rb
 - lib/ask/provider/google.rb
 - lib/ask/provider/mimo.rb
 - lib/ask/provider/mistral.rb
@@ -189,6 +190,8 @@ files:
 - lib/ask/provider/openai.rb
 - lib/ask/provider/opencode.rb
 - lib/ask/provider/opencode_go.rb
+- lib/ask/provider/openrouter.rb
+- lib/ask/skills/providers.model_select/SKILL.md
 homepage: https://github.com/ask-rb/ask-llm-providers
 licenses:
 - MIT