ask-llm-providers 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3eb8f66386fc8bd48d06aaa3b4557a9df584f9366ab431d38b3861890411401
-  data.tar.gz: 9f71aa766c2b545421b56381018cafe2cc0d5b970880898af13a1cd6b8654902
+  metadata.gz: 925a11549bdce89470327b583421ae71aa3b8aa4385efacb9baead5ee8aa7f27
+  data.tar.gz: 8ec764b1b392cf83ac70afb56eb78df2e118150f2e25951580dd1efac628a8af
 SHA512:
-  metadata.gz: 00cecf99e04b04a253a55a6faf3558fa5498d2094582c07dc903d46cbd247ddd65d1126d16fa0744ba973b71e81ea31ce57ff9cdc49a3373530eb2a151b8bec0
-  data.tar.gz: 592e5e26761d59b83afd56ec5300380a64e4126f283a609efdfe06aec86a3d6d5747ff6b8c1f366f1206d5d100af9d3648ceca64c46aee8bdc6756a86026f445
+  metadata.gz: 4bff20df39628b886645cb48d8eb812d6f5e32ae8f5de2ffc433bd577c7e5dd4bf64b429b0efeffefbee79f2ce7af3bdc48a5cabb60f63e0ea0612e61d352130
+  data.tar.gz: 93bef4f89008fbcefcee9362ef9ca35369230012777e9202683d781ebdf872901d796fb847f2cbd74cf86faaa17801233bcaa2731f6058ee72ef45f6d7dadc2c

data/CHANGELOG.md

@@ -0,0 +1,92 @@
+## [0.3.0] — 2026-07-14
+
+### Added
+- **Model catalog system** — `Ask::LLM::Catalog` loads model definitions from per-provider JSON files (`lib/ask/llm/models/*.json`), user overrides (`~/.ask-llm-providers/models.json`), and provider API `list_models()` on explicit refresh.
+- **Per-provider model JSONs** — 12 JSON files (openai, anthropic, gemini, deepseek, opencode, opencode_go, mimo, openrouter, ollama, mistral, bedrock, cloudflare) with id, name, provider, capabilities, context window, modalities, and pricing.
+- **Model aliases** — `Ask::LLM::Aliases` resolves short names (e.g. `claude-sonnet-4` → `claude-sonnet-4-6`). Alias entries are automatically registered into `Ask::ModelCatalog` so `ModelCatalog.find` works with alias names.
+- **User config support** — `~/.ask-llm-providers/models.json` overrides bundled model fields or adds custom models.
+- **`opencode.json` includes `deepseek-v4-flash`** — matches the default model configuration.
+
+### Changed
+- Removed hardcoded `Ask::LLM::Models::OPENAI_MODELS` constants — replaced with catalog-driven model loading.
+- `Ask::LLM::Aliases.resolve` now aliases `deepseek-v4` → `deepseek-v4-flash`, `gpt-4o-latest` → `gpt-4o`, `gpt-4.1-latest` → `gpt-4.1`.
+
+### Fixed
+- Model entries now include `"provider"` field in JSON files (was missing from generated data).
+- User config merges properly override bundled values (was keeping old values on conflict).
+
+## [0.2.2] — 2026-06-25
+
+### Changed
+- Extended per-provider tests (Anthropic 18t, Google 14t, DeepSeek 16t, Mistral, Ollama, Cloudflare, Bedrock). Fixed providers_test.rb syntax error. RuboCop, overcommit, gemspec test, SimpleCov, CI.
+# Changelog
+
+## [0.1.0] — 2026-06-09
+
+Initial release of `ask-llm-providers`, all LLM providers for the ask-rb ecosystem.
+
+### Added
+
+- **OpenAI provider** — Chat Completions API with streaming, tool calls, vision, structured output, embeddings
+- **Anthropic provider** — Messages API with thinking blocks, tool use, prompt caching
+- **Google Gemini provider** — `generateContent` API with function calling, streaming, embeddings
+- **Amazon Bedrock provider** — Converse API with tool configuration
+- **Ollama provider** — Local LLM inference with chat and embeddings endpoints
+- **Mistral AI provider** — OpenAI-compatible API with embeddings support
+- **Cloudflare provider** — Workers AI direct endpoint and AI Gateway passthrough
+- **Error mapping** — Provider-specific HTTP errors → `Ask::Error` types (rate limit, auth, context exceeded, etc.)
+- **Provider registration** — All providers auto-registered with `Ask::Provider` on gem load
+- **Capabilities introspection** — Each provider exposes supported capabilities
+- **Shared HTTP infrastructure** — `Ask::LLM::HTTP` with Faraday connection builder and SSE streaming
+- **Test suite** — 33 tests across all providers and error mapping
+
+## [0.1.8] — 2026-06-18
+
+### Added
+
+- **OpenRouter provider** — `Ask::Providers::OpenRouter`, reads `OPENROUTER_API_KEY`,
+  sets `HTTP-Referer` and `X-Title` headers.
+
+### Fixed
+
+- **`normalize_config` ENV resolution** — Removed broken monkey-patch that defined
+  `normalize_config` on `Object` instead of within the `OpenAI` class. Now resolves
+  `api_key` from: explicit config → subclass-specific key → `ENV` var →
+  `Ask::Auth.resolve` chain. All OpenAI-compatible subclasses (DeepSeek, OpenCode,
+  OpenCodeGo, Mimo, OpenRouter) inherit the fix.
+
+## [0.1.9] — 2026-06-18
+
+### Fixed
+
+- **`format_messages` with Hash tool_calls** — Tool calls can arrive as Hash (keyed
+  by call_id) from some chat implementations, or as Array. The method now detects
+  both formats with `tc.is_a?(Hash) ? tc.values : tc`. Also handles `OpenStruct`
+  tool call objects via `.respond_to?` checks instead of assuming Hash accessors.
+
+## [0.2.0] — 2026-06-19
+
+### Fixed
+
+- **SSE buffering across all streaming providers** — TCP fragmentation in
+  Faraday's `on_data` callback caused silent data loss when SSE events were
+  split across packets. Added persistent `@_sse_buffer` with complete-event
+  extraction via `Ask::LLM::SSEBuffer` module. Affected providers:
+  OpenAI, Anthropic, Cloudflare, Google, Ollama. All OpenAI-compatible
+  subclasses inherit the fix.
+
+### Added
+
+- **`Ask::LLM::SSEBuffer`** — Shared module providing `init_sse_buffer` and
+  `each_sse_event(raw)` for SSE buffering across streaming callbacks.
+- **SSE buffering tests** — 5 new tests covering fragmented data, event
+  boundaries, multiple events, and `[DONE]` sentinel.
+
+## [0.1.10] — 2026-06-18
+
+### Fixed
+
+- **`chat_stream` nil response body** — Streaming requests consume the response body
+  via `on_data` callback, leaving `resp.body` as `nil`. `JSON.parse(nil)` raised
+  `TypeError: no implicit conversion of nil into String`. Now checks
+  `resp.body` before parsing.

data/lib/ask/llm/aliases.json

@@ -0,0 +1,11 @@
+{
+  "claude-sonnet-4": "claude-sonnet-4-6",
+  "claude-sonnet-4-5": "claude-sonnet-4-6",
+  "claude-opus-4": "claude-opus-4-7",
+  "claude-opus-4-5": "claude-opus-4-7",
+  "claude-haiku-4": "claude-haiku-4-5",
+  "gemini-3": "gemini-3-flash",
+  "deepseek-v4": "deepseek-v4-flash",
+  "gpt-4o-latest": "gpt-4o",
+  "gpt-4.1-latest": "gpt-4.1"
+}

data/lib/ask/llm/aliases.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module LLM
+    # Resolves model name aliases to canonical model IDs.
+    #
+    # Aliases are defined in aliases.json and allow users to refer
+    # to models by shorter or more familiar names. Resolution is
+    # provider-scoped — you can alias "claude-sonnet-4" to different
+    # canonical IDs depending on which provider serves it.
+    #
+    #   Ask::LLM::Aliases.resolve("claude-sonnet-4")
+    #   # => "claude-sonnet-4-6"
+    #
+    # Aliases are loaded lazily from the bundled JSON file.
+    module Aliases
+      ALIASES_PATH = File.expand_path("aliases.json", __dir__)
+
+      class << self
+        # Resolve an alias to a canonical model ID.
+        # Returns the input name unchanged if no alias is registered.
+        def resolve(name)
+          load_aliases unless @aliases
+          @aliases[name.to_s] || name.to_s
+        end
+
+        # Register a custom alias at runtime.
+        def register(short_name, canonical_id)
+          load_aliases unless @aliases
+          @aliases[short_name.to_s] = canonical_id.to_s
+        end
+
+        # Reload aliases from the bundled JSON file.
+        def reload!
+          @aliases = nil
+          load_aliases
+        end
+
+        # All registered aliases (for introspection).
+        def all
+          load_aliases unless @aliases
+          @aliases.dup
+        end
+
+        private
+
+        def load_aliases
+          @aliases = {}
+          path = ALIASES_PATH
+          return unless File.exist?(path)
+
+          raw = JSON.parse(File.read(path))
+          raw.each { |k, v| @aliases[k.to_s] = v.to_s }
+        rescue JSON::ParserError
+          # Invalid aliases file — log and use empty map
+        end
+      end
+    end
+  end
+end

data/lib/ask/llm/catalog.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Ask
+  module LLM
+    # Orchestrates model catalog loading from multiple sources:
+    #
+    #   1. Bundled JSON files in lib/ask/llm/models/*.json (shipped with the gem)
+    #   2. ~/.ask-llm-providers/models.json (user-defined overrides)
+    #   3. Provider API list_models() calls (on explicit refresh!)
+    #
+    # Loaded models are registered into Ask::ModelCatalog for use
+    # by ask-agent, ask-mcp, and llm-proxy.
+    #
+    #   Ask::LLM::Catalog.load!  # load bundled + user config
+    #   Ask::LLM::Catalog.refresh!  # also fetch from provider APIs
+    #
+    class Catalog
+      class Error < StandardError; end
+      class LoadError < Error; end
+
+      USER_CONFIG_PATH = File.expand_path("~/.ask-llm-providers/models.json").freeze
+
+      class << self
+        # Load bundled model definitions and user overrides into Ask::ModelCatalog.
+        # Idempotent — subsequent calls clear and reload.
+        def load!
+          instance.clear
+          instance.load_bundled
+          instance.load_user_config
+          instance.register_all
+          true
+        end
+
+        # Like load! but also fetches model lists from configured providers'
+        # list_models() APIs. Unknown models are added with minimal metadata.
+        def refresh!
+          load!
+          instance.fetch_from_providers
+          instance.register_all
+          true
+        end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+      end
+
+        def instance
+          @instance ||= new
+        end
+      end
+
+      def initialize
+        @entries = []
+        @model_keys = Set.new
+      end
+
+      def clear
+        @entries.clear
+        @model_keys.clear
+      end
+
+      # Load bundled model JSONs from the gem's lib/ask/llm/models/ directory.
+      def load_bundled
+        pattern = File.expand_path("models/*.json", __dir__)
+        Dir[pattern].sort.each do |path|
+          raw = JSON.parse(File.read(path))
+          raw.each { |entry| add_entry(entry) }
+        end
+      end
+
+      # Load user-defined model overrides from ~/.ask-llm-providers/models.json.
+      # Silently skipped if the file doesn't exist.
+      def load_user_config
+        path = USER_CONFIG_PATH
+        return unless File.exist?(path)
+
+        raw = JSON.parse(File.read(path))
+        unless raw.is_a?(Array)
+          warn "Warning: #{path} should be a JSON array of model entries, got #{raw.class}"
+          return
+        end
+
+        raw.each { |entry| merge_or_add(entry) }
+      rescue JSON::ParserError => e
+        warn "Warning: Failed to parse #{path}: #{e.message}"
+      end
+
+      # Fetch model lists from all configured providers via their list_models() API.
+      # Adds unknown models with minimal metadata (no capability guessing).
+      def fetch_from_providers
+        Ask::Provider.providers.each do |slug, provider_class|
+          next unless provider_class.configured?(nil)
+
+          begin
+            provider = provider_class.new
+            models = provider.list_models
+            models.each do |m|
+              add_entry(m) unless @model_keys.include?([m[:id], slug.to_s])
+            end
+          rescue StandardError => e
+            warn "Warning: Failed to fetch models from #{slug}: #{e.message}"
+          end
+        end
+      end
+
+      # Register all accumulated entries into Ask::ModelCatalog.
+      # Also registers alias entries so models can be found by alias name.
+      def register_all
+        @entries.each do |entry|
+          info = build_model_info(entry)
+          Ask::ModelCatalog.instance.register(info)
+        end
+
+        register_alias_entries
+      end
+
+      private
+
+      # For each alias (short_name → canonical_id), register a duplicate
+      # ModelInfo for every canonical entry whose id matches.
+      def register_alias_entries
+        Ask::LLM::Aliases.all.each do |short_name, canonical_id|
+          next if short_name == canonical_id
+
+          @entries.each do |entry|
+            next unless entry["id"] == canonical_id || entry[:id] == canonical_id
+
+            alias_entry = entry.merge("id" => short_name)
+            info = build_model_info(alias_entry)
+            Ask::ModelCatalog.instance.register(info)
+          end
+        end
+      end
+
+      def symbolize_keys(hash)
+        hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+      end
+
+      def add_entry(entry)
+        key = entry_key(entry)
+        return if @model_keys.include?(key)
+
+        @entries << entry
+        @model_keys << key
+      end
+
+      def merge_or_add(entry)
+        key = entry_key(entry)
+        existing = @entries.find { |e| entry_key(e) == key }
+
+        if existing
+          existing.merge!(entry)
+        else
+          @entries << entry
+          @model_keys << key
+        end
+      end
+
+      def entry_key(entry)
+        id = entry["id"] || entry[:id]
+        provider = entry["provider"] || entry[:provider]
+        [id, provider.to_s]
+      end
+
+      def build_model_info(entry)
+        e = entry.transform_keys(&:to_sym)
+        modalities = e[:modalities]
+        modalities = symbolize_keys(modalities) if modalities
+
+        Ask::ModelInfo.new(
+          id: e[:id],
+          name: e[:name] || e[:id],
+          provider: e[:provider],
+          family: e[:family],
+          capabilities: Array(e[:capabilities]),
+          context_window: e[:context_window],
+          max_output_tokens: e[:max_output_tokens],
+          modalities: modalities || { input: %w[text], output: %w[text] },
+          pricing: e[:pricing] || {},
+          knowledge_cutoff: e[:knowledge_cutoff] ? Date.parse(e[:knowledge_cutoff].to_s) : nil,
+          created_at: e[:created_at] ? Date.parse(e[:created_at].to_s) : nil,
+          metadata: (e[:metadata] || {}).merge(source: e[:metadata]&.dig("source") || "bundled")
+        )
+      rescue Date::Error
+        Ask::ModelInfo.new(id: e[:id], provider: e[:provider])
+      end
+    end
+  end
+end

data/lib/ask/llm/models/anthropic.json

@@ -0,0 +1,188 @@
+[
+  {
+    "id": "claude-sonnet-4-5",
+    "name": "Claude Sonnet 4.5",
+    "family": "claude_sonnet",
+    "context_window": 200000,
+    "max_output_tokens": 64000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "structured_output",
+      "vision",
+      "reasoning",
+      "prompt_caching",
+      "tool_choice",
+      "parallel_tool_calls"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image",
+        "pdf"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-sonnet-4",
+    "name": "Claude Sonnet 4",
+    "family": "claude_sonnet",
+    "context_window": 200000,
+    "max_output_tokens": 64000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "structured_output",
+      "vision",
+      "reasoning",
+      "prompt_caching",
+      "tool_choice",
+      "parallel_tool_calls"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image",
+        "pdf"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-4-opus",
+    "name": "Claude Opus 4",
+    "family": "claude_opus",
+    "context_window": 200000,
+    "max_output_tokens": 64000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "structured_output",
+      "vision",
+      "reasoning",
+      "prompt_caching",
+      "tool_choice",
+      "parallel_tool_calls"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image",
+        "pdf"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-haiku-4-5",
+    "name": "Claude Haiku 4.5",
+    "family": "claude_haiku",
+    "context_window": 200000,
+    "max_output_tokens": 64000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "structured_output",
+      "vision",
+      "reasoning",
+      "prompt_caching",
+      "tool_choice",
+      "parallel_tool_calls"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image",
+        "pdf"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-opus-4-5",
+    "name": "Claude Opus 4.5",
+    "family": "claude_opus",
+    "context_window": 200000,
+    "max_output_tokens": 64000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "structured_output",
+      "vision",
+      "reasoning",
+      "prompt_caching",
+      "tool_choice",
+      "parallel_tool_calls"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image",
+        "pdf"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-3.5-sonnet",
+    "name": "Claude 3.5 Sonnet",
+    "family": "claude_sonnet",
+    "context_window": 200000,
+    "max_output_tokens": 8192,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "vision",
+      "reasoning"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  },
+  {
+    "id": "claude-3.5-haiku",
+    "name": "Claude 3.5 Haiku",
+    "family": "claude_haiku",
+    "context_window": 200000,
+    "max_output_tokens": 8192,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "vision",
+      "reasoning"
+    ],
+    "modalities": {
+      "input": [
+        "text",
+        "image"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "anthropic"
+  }
+]

data/lib/ask/llm/models/bedrock.json

@@ -0,0 +1 @@
+[]

data/lib/ask/llm/models/cloudflare.json

@@ -0,0 +1 @@
+[]

data/lib/ask/llm/models/deepseek.json

@@ -0,0 +1,85 @@
+[
+  {
+    "id": "deepseek-v4-flash",
+    "name": "DeepSeek V4 Flash",
+    "family": "deepseek_v4",
+    "context_window": 1000000,
+    "max_output_tokens": 384000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "reasoning"
+    ],
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "deepseek"
+  },
+  {
+    "id": "deepseek-v4-pro",
+    "name": "DeepSeek V4 Pro",
+    "family": "deepseek_v4",
+    "context_window": 1000000,
+    "max_output_tokens": 384000,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "reasoning"
+    ],
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "deepseek"
+  },
+  {
+    "id": "deepseek-chat",
+    "name": "DeepSeek Chat",
+    "family": "deepseek_v3",
+    "context_window": 64000,
+    "max_output_tokens": 8192,
+    "capabilities": [
+      "function_calling",
+      "streaming"
+    ],
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "deepseek"
+  },
+  {
+    "id": "deepseek-reasoner",
+    "name": "DeepSeek Reasoner",
+    "family": "deepseek_r1",
+    "context_window": 64000,
+    "max_output_tokens": 8192,
+    "capabilities": [
+      "function_calling",
+      "streaming",
+      "reasoning"
+    ],
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "provider": "deepseek"
+  }
+]