llm_specs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 145115f78fbeb2a228a05c2c4752a80576ac693b972cc580f267c56e3d90f724
+  data.tar.gz: 45828acd7744da728d1ebcd017b918af9064f8c531e5e4f6a708e1dd3851b44d
+SHA512:
+  metadata.gz: 2780eb5101b22334cafeeb7c7de12be3ec120d5daa8e0c4f8e2d9930c78c0f6353744c4f35562891d09b28bcc1fe25602cecf4b4b924b9baaf45dc6b4df12d41
+  data.tar.gz: 63ce73155eee23924dfbd0e43f62b66fbb02a224ae861923d17ece9e994fba7951653ffc593f04bd33851c688271cf1b5dd2ab33c20518a0f9c25fcff8c29eeb

data/.tldr.yml

@@ -0,0 +1,2 @@
+emoji: true
+verbose: true

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Max Power
+
+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,63 @@
+# LLMSpecs
+
+LLMSpecs is a lightweight Ruby interface for fetching and caching 
+large language model (LLM) specifications from the [Parsera API](https://llmspecs.parsera.org).
+It provides a simple, efficient way to access model metadata with built-in caching and query support.
+
+## Features
+
+- Fetches LLM specs from: https://api.parsera.org/v1/llm-specs
+- Caches results locally to models.json
+- Provides a queryable catalog of models via .models
+- Supports filtering and lookup by model attributes
+
+##  Model Capabilities
+Each model is represented by an instance of `LLMSpecs::Model`, a value object that encapsulates:
+
+- `id`, `name`, `provider`, `family`
+- Token limits (`context_window`, `max_output_tokens`)
+- Supported modalities (e.g. `text`, `image`)
+- Capabilities such as:
+    - `function_calling?`
+    - `structured_output?`
+    - `streaming?`
+    - `reasoning?`
+    - `citations?`
+    - `batch?`
+
+- Pricing breakdowns via `input_pricing` and `output_pricing`
+
+You can easily check capabilities or pricing:
+```ruby
+model.function_calling?  # => true/false
+model.input_pricing      # => $ per 1M input tokens (default)
+model.output_pricing(:image_tokens)
+```
+
+## Example Usage
+```ruby
+require 'llm_specs'
+
+models = LLMSpecs.models
+```
+
+### Find a model by ID
+```ruby
+model = LLMSpecs.models.find("claude-3-sonnet")
+```
+
+### Filter models
+```ruby
+anthropic_models = LLMSpecs.models.where(provider: "anthropic")
+
+claude_models = LLMSpecs.models.where(provider: "anthropic", family: "claude-3-7-sonnet")
+```
+
+### List all models that support streaming
+```ruby
+streaming_models = LLMSpecs.models.select(&:streaming?)
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "tldr/rake"
+
+task default: :tldr

data/lib/llm_specs/cache.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module LLMSpecs
+  class Cache
+    def initialize(file, ttl: 86400)
+      @file = file
+      @ttl  = ttl
+    end
+    
+    def fetch
+      return read if valid?
+      data = yield
+      write(data)
+      data
+    end
+    
+    def valid?
+      File.exist?(@file) && (Time.now - File.mtime(@file) < @ttl)
+    end
+    
+    def read
+      JSON.parse(File.read(@file), symbolize_names: true)
+    end
+
+    def write(data)
+      File.write(@file, JSON.pretty_generate(data))
+    end
+  end
+end

data/lib/llm_specs/catalog.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module LLMSpecs
+  class Catalog    
+    def initialize(api_uri:, cache_path:)
+      @uri   = URI(api_uri)
+      @cache = Cache.new(cache_path)
+    end
+    
+    def models
+      Collection.new fetch.map(&Model)
+    end
+    
+    private
+    
+    def fetch
+      @cache.fetch do
+        response = Net::HTTP.get_response(@uri)
+        raise FetchError.new(response) unless response.is_a? Net::HTTPSuccess
+        JSON.parse(response.body, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/llm_specs/collection.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module LLMSpecs
+  class Collection < Array
+    def find(id)
+      super() { it.id == id } || raise(ModelNotFound.new(id))
+    end
+
+    def where(**criteria)
+      select do |model| 
+        criteria.all? { |k,v| model.send(k) == v }
+      end
+    end
+    
+    %i[select reject filter].each do |method|
+      define_method(method) do |&block|
+        self.class.new(super(&block))
+      end
+    end
+  end
+end

data/lib/llm_specs/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module LLMSpecs
+  class ModelNotFound < StandardError
+    def initialize(id)
+      super("Couldn't find model with id='#{id}'")
+    end
+  end
+  
+  class FetchError < StandardError
+    attr_reader :response
+    def initialize(response)
+      @response = response
+      super("HTTP fetch failed (status: #{response.status})")
+    end
+  end
+end

data/lib/llm_specs/model.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+module LLMSpecs
+  class Model < Data.define(:id, :name, :provider, :family, :context_window, :max_output_tokens, :modalities, :capabilities, :pricing)
+    def supports?(capability)
+      capabilities.include?(capability.to_s)
+    end
+    
+    %i[function_calling structured_output batch reasoning citations streaming].each do |capability|
+      define_method(:"#{capability}?") { supports?(capability) }
+    end
+    
+    def input_modalities
+      modalities[:input]
+    end
+    
+    def output_modalities
+      modalities[:output]
+    end
+      
+    def input_pricing(type=:text_tokens, price_type=:standard)
+      pricing.dig(type, price_type, :input_per_million)
+    end
+    
+    def output_pricing(type=:text_tokens, price_type=:standard)
+      pricing.dig(type, price_type, :output_per_million)
+    end
+      
+    def self.to_proc
+      ->(hash) { new(**hash) }
+    end
+  end
+end

data/lib/llm_specs/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module LLMSpecs
+  VERSION = "0.1.0"
+end

data/lib/llm_specs.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require "json"
+require "net/http"
+require "forwardable"
+require_relative "llm_specs/errors"
+require_relative "llm_specs/cache"
+require_relative "llm_specs/catalog"
+require_relative "llm_specs/collection"
+require_relative "llm_specs/model"
+
+module LLMSpecs
+  API_URI    = "https://api.parsera.org/v1/llm-specs"
+  CACHE_PATH = "models.json"
+  
+  def self.models
+    @models ||= Catalog.new(api_uri: API_URI, cache_path: CACHE_PATH).models
+  end
+end