ask-core 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5579b4c8482eca770eebc83285f046ad7797d1a032f8d55e355028c7986a9776
-  data.tar.gz: 4d21bf4c9c13690ff1368b01a364ff7f961de2347660fdb33bc989ff0635c418
+  metadata.gz: 2b573cb0709bd479e2a888becc0ce41cacafcf5f2e48afee24b2d6af1a7b99d5
+  data.tar.gz: c690b789d00985df0d9723c4f436c6b4a51e62f1857479af9ff2f652b59cd7d8
 SHA512:
-  metadata.gz: b309f9490cde3fc1c6b0712757256804af5b34f562d7114596e8cf4c69f4fb273558afd05e5545bab22fdcce13f9d0bb2214f1ef3794776a96fea8576900804c
-  data.tar.gz: 19ceabf03606c291b4edea7ec222cc8152d61a13be16429428906325d2334b21ff4c97d328731a2264c9b6f5b26c9dc0d34481c30dbb0e2d69f71a4d6b048dc3
+  metadata.gz: 4506564311573fcd2a43d277eef97157d1abafa7add2968bc336551ad1f6e4133f87b1aa2d47607963e2c0b3d0fdfb92ad332c6ff55eddb3a927276cee647a3e
+  data.tar.gz: ec2c10ed1152e01783272fffc16ff0695334c53bae829d9a0ebb7077317c084b3587490d6bc80820e2c78fd10e19e676dfe319147f667a4a453f763fb08782a7

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.2.4] — 2026-07-17
+
+### Added
+
+- **Rich error categories** — `RateLimitError` now carries `category` (`RateLimitCategory::VENDOR` or `::LOCAL`), `rate_limit_type` (`RateLimitType::REQUESTS`, `::TOKENS`, `::CONCURRENT`, `::BUDGET`), and `retry_after` (seconds) for intelligent error handling. Inspired by LiteLLM's error hierarchy.
+
+## [0.2.3] — 2026-07-14
+
+### Changed
+- `Ask::ModelCatalog.find(model_id)` now returns `Array<Ask::ModelInfo>` (all matches) — provider preference disambiguation is removed. Provider-scoped `find(model_id, provider)` still returns a single model or raises.
+- Removed `Ask::ModelCatalog::PROVIDER_PREFERENCE`. No preference list anywhere — all providers and models are treated equally.
+
 ## [0.2.2] — 2026-07-14
 
 ### Added

data/lib/ask/errors.rb

@@ -28,9 +28,6 @@ module Ask
   # Raised when the context window is exceeded.
   class ContextLengthExceeded < Error; end
 
-  # Raised when the API rate limit is hit.
-  class RateLimitError < Error; end
-
   # Raised when authentication fails.
   class Unauthorized < Error; end
 
@@ -40,11 +37,41 @@ module Ask
   # Raised when the service is unavailable.
   class ServiceUnavailable < Error; end
 
+  # Categories for {RateLimitError} — tells you who rate-limited the request.
+  module RateLimitCategory
+    VENDOR = :vendor  # upstream LLM provider (OpenAI, Anthropic, etc.)
+    LOCAL  = :local   # ask-rb's own limiter (ask-auth thresholds)
+  end
+
+  # Rate limit dimension that was exceeded — orthogonal to {RateLimitCategory}.
+  module RateLimitType
+    REQUESTS   = :requests    # requests-per-minute ceiling
+    TOKENS     = :tokens      # tokens-per-minute ceiling
+    CONCURRENT = :concurrent  # max parallel requests
+    BUDGET     = :budget      # spend budget cap
+  end
+
+  # Raised when the API rate limit is hit.
+  # Carries optional category, type, and retry_after for intelligent handling.
+  class RateLimitError < Error
+    # @return [Symbol, nil] who rate-limited (:vendor, :local)
+    attr_reader :category
+
+    # @return [Symbol, nil] which limit was hit (:requests, :tokens, :concurrent, :budget)
+    attr_reader :rate_limit_type
+
+    # @return [Integer, Float, nil] suggested seconds to wait before retrying
+    attr_reader :retry_after
+
+    def initialize(message, category: nil, rate_limit_type: nil, retry_after: nil)
+      @category = category
+      @rate_limit_type = rate_limit_type
+      @retry_after = retry_after
+      super(message)
+    end
+  end
+
   # Raised when a provider's API returns an unexpected response.
-  # @!attribute [r] status_code
-  #   @return [Integer, nil] the HTTP status code
-  # @!attribute [r] response_body
-  #   @return [String, nil] the raw response body
   class ProviderError < Error
     attr_reader :status_code, :response_body
 

data/lib/ask/models.rb

@@ -256,12 +256,11 @@ module Ask
     end
   end
 
-  # Catalog of available AI models. Provides model resolution by name/ID,
-  # filtering by capability, and refresh from the models.dev API.
+  # Catalog of available AI models.
   #
-  #   Ask::ModelCatalog.find("gpt-4o")
-  #   Ask::ModelCatalog.chat_models
-  #   Ask::ModelCatalog.refresh!
+  #   Ask::ModelCatalog.find("gpt-4o")                  # => ModelInfo or raises
+  #   Ask::ModelCatalog.find("gpt-4o", provider: "openai")  # => ModelInfo or raises
+  #   Ask::ModelCatalog.where("gpt-4o")                 # => [ModelInfo, ...] (all matches)
   #
   class ModelCatalog
     include Enumerable
@@ -269,17 +268,8 @@ module Ask
     # @return [String] URL for the models.dev API
     MODELS_DEV_URL = "https://models.dev/api.json".freeze
 
-    # Ordered provider preference for disambiguation.
-    PROVIDER_PREFERENCE = %w[
-      openai anthropic gemini vertexai bedrock
-      opencode opencode_go
-      openrouter deepseek mistral perplexity xai
-      mimo
-      azure ollama gpustack github
-    ].freeze
-
     # Methods delegated to the singleton instance.
-    DELEGATES = %i[all each find chat_models embedding_models
+    DELEGATES = %i[all each find where chat_models embedding_models
                    audio_models image_models by_family by_provider
                    refresh!].freeze
 
@@ -319,19 +309,28 @@ module Ask
       @models.each(&block)
     end
 
-    # Find a model by ID, optionally scoped to a provider.
+    # Find a single model by ID. Scopes to provider when given.
     # @param model_id [String] model identifier
-    # @param provider [String, nil] provider slug
+    # @param provider [String, nil] provider slug (optional keyword)
     # @return [Ask::ModelInfo]
-    # @raise [ModelNotFound] if the model is not found
-    def find(model_id, provider = nil)
+    # @raise [ModelNotFound] if no matching model is found
+    def find(model_id, provider: nil)
       if provider
-        find_with_provider(model_id, provider.to_s)
+        @models.find { |m| m.id == model_id && m.provider == provider.to_s } ||
+          raise(ModelNotFound, "Model #{model_id.inspect} not found for provider #{provider.inspect}.")
       else
-        find_without_provider(model_id)
+        @models.find { |m| m.id == model_id } ||
+          raise(ModelNotFound, "Unknown model: #{model_id.inspect}.")
       end
     end
 
+    # Find all models matching an ID. Never raises.
+    # @param model_id [String] model identifier
+    # @return [Array<Ask::ModelInfo>] matching models (empty if none)
+    def where(model_id)
+      @models.select { |m| m.id == model_id }
+    end
+
     # @return [Ask::ModelCatalog] new catalog containing only chat models
     def chat_models
       self.class.new(@models.select(&:chat?))
@@ -391,31 +390,6 @@ module Ask
 
     private
 
-    def find_with_provider(model_id, provider)
-      exact = @models.find { |m| m.id == model_id && m.provider == provider }
-      return exact if exact
-
-      @models.find { |m| m.id == model_id && m.provider == provider } ||
-        raise(ModelNotFound, "Model #{model_id.inspect} not found for provider #{provider.inspect}. " \
-                             "Try ModelCatalog.refresh! to update the catalog.")
-    end
-
-    def find_without_provider(model_id)
-      matches = @models.select { |m| m.id == model_id }
-      return preferred_match(matches) if matches.any?
-
-      raise ModelNotFound, "Unknown model: #{model_id.inspect}. " \
-                           "Try ModelCatalog.refresh! to update the catalog."
-    end
-
-    def preferred_match(candidates)
-      return candidates.first if candidates.size == 1
-
-      candidates.min_by do |model|
-        PROVIDER_PREFERENCE.index(model.provider) || PROVIDER_PREFERENCE.length
-      end
-    end
-
     def fetch_from_models_dev(timeout: 10)
       uri = URI(MODELS_DEV_URL)
       http = Net::HTTP.new(uri.host, uri.port)

data/lib/ask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ask
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Kaka Ruto