openrouter_client 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dfa50003cbe411f1e237d47c2872e053bbe649253abe52df64da017071bf791
-  data.tar.gz: 6279dcb4868bf470016c0df6cfe45fd3c5ebc19284cb7eb54d8d8d6c6ca78bb1
+  metadata.gz: a13939cbccbd1e6a70514d6d422987b702c313d3db1c7226e61966da6c858acb
+  data.tar.gz: edfcd5e0eb7f703b91ca93a04de8f3cf33b0ae219119a65064acbed22c1ce731
 SHA512:
-  metadata.gz: 20fa68b2374b7be8f14b0833fa794d3f2d52f0aea344a2707ab9d3330a6a8c43da36e2f7d27681af2a8a2a8ecfeb926bdb70b7f86819e904b38b76aa1c4f2156
-  data.tar.gz: ecc2aecf1224b2c5ddc1207780ebbc9014a07fd568969d2fda199cdfeaa46ea93ec8badbdacfca74cb6357c3f98ed171e144f584aef2782bfdf50c811ddab100
+  metadata.gz: 5edd0c39d7b2a1c57db82dcd4ab0d5b1e44042b496e54ff1c5b8b79b6268c2b5964b443a7297735e2692ed4388fff70a26d357c4cbabfd2b47eee502ca5422ba
+  data.tar.gz: 86724cc812f08258dd292cd467887c2a94d5866bb670e8394345ed8da2bdd5d596e98760d4a14f432be3d41c9e4a8f5b1585f58ee88ff2874c5eb515fbb672ac

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openrouter_client (0.1.1)
+    openrouter_client (0.1.3)
       faraday (>= 1)
 
 GEM

data/README.md

@@ -215,6 +215,16 @@ model = OpenRouter::Model.find_by!(id: "openai/gpt-4")
 puts model.name           # => "GPT-4"
 puts model.context_length # => 8192
 puts model.input_price    # => 0.00003 (per token)
+
+# Endpoints (available providers for this model)
+model.endpoints.each do |endpoint|
+  puts endpoint.provider_name      # => "OpenAI"
+  puts endpoint.context_length     # => 8192
+  puts endpoint.prompt_price       # => 0.00003
+  puts endpoint.completion_price   # => 0.00006
+  puts endpoint.available?         # => true
+  puts endpoint.supports?(:tools)  # => true
+end
 puts model.output_price   # => 0.00006 (per token)
 puts model.free?          # => false
 
@@ -232,6 +242,44 @@ model = OpenRouter::Model.find("openai/gpt-4")
 completion = model.complete(messages: [{ role: "user", content: "Hello!" }])
 ```
 
+### Embeddings
+
+Generate vector embeddings from text for semantic search, RAG, and more:
+
+```ruby
+# Single text embedding
+embedding = OpenRouter::Embedding.create!(
+  model: "openai/text-embedding-3-small",
+  input: "The quick brown fox jumps over the lazy dog"
+)
+
+puts embedding.vector       # => [0.123, -0.456, ...]
+puts embedding.dimensions   # => 1536
+puts embedding.total_tokens # => 9
+
+# Batch embedding (multiple texts)
+embedding = OpenRouter::Embedding.create!(
+  model: "openai/text-embedding-3-small",
+  input: [
+    "Machine learning is a subset of AI",
+    "Deep learning uses neural networks"
+  ]
+)
+
+embedding.vectors.each_with_index do |vector, i|
+  puts "Text #{i}: #{vector.length} dimensions"
+end
+
+# Access individual embedding data
+embedding.data.each do |item|
+  puts "Index: #{item.index}, Dimensions: #{item.dimensions}"
+end
+
+# List available embedding models
+models = OpenRouter::Embedding.models
+models.each { |m| puts m["id"] }
+```
+
 ### Generation Stats
 
 Query detailed usage information for a completion:

data/lib/openrouter/embedding.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Generate vector embeddings from text using OpenRouter's unified embeddings API.
+  # Embeddings transform text into high-dimensional vectors where semantically similar
+  # texts are positioned closer together in vector space.
+  class Embedding
+    EMBEDDINGS_PATH = "/embeddings"
+    EMBEDDING_MODELS_PATH = "/embeddings/models"
+
+    # @return [String] The model used for embedding
+    attr_reader :model
+    # @return [Array<EmbeddingData>] The embedding data objects
+    attr_reader :data
+    # @return [Hash, nil] Usage statistics
+    attr_reader :usage
+
+    # @param attributes [Hash] Raw response from OpenRouter API
+    def initialize(attributes)
+      @model = attributes["model"]
+      @usage = attributes["usage"]
+      @data = build_data(attributes["data"])
+    end
+
+    # Generate embeddings for the given input.
+    # @param model [String] The embedding model to use (e.g., "openai/text-embedding-3-small")
+    # @param input [String, Array<String>] Text or array of texts to embed
+    # @param client [OpenRouter::Client] HTTP client
+    # @param options [Hash] Additional options (e.g., provider preferences)
+    # @return [OpenRouter::Embedding]
+    def self.create!(model:, input:, client: OpenRouter.client, **options)
+      payload = {
+        model: model,
+        input: input,
+        **options
+      }
+
+      response = client.post(EMBEDDINGS_PATH, payload)
+      new(response)
+    end
+
+    # List available embedding models.
+    # @param client [OpenRouter::Client] HTTP client
+    # @return [Array<Hash>] Array of model information
+    def self.models(client: OpenRouter.client)
+      response = client.get(EMBEDDING_MODELS_PATH)
+      Array(response && response["data"])
+    end
+
+    # Get the first embedding vector (convenience method for single input).
+    # @return [Array<Float>, nil]
+    def vector
+      @data&.first&.embedding
+    end
+
+    # Get all embedding vectors.
+    # @return [Array<Array<Float>>]
+    def vectors
+      @data&.map(&:embedding) || []
+    end
+
+    # Get the dimension of the embedding vectors.
+    # @return [Integer, nil]
+    def dimensions
+      vector&.length
+    end
+
+    # Get the total tokens used.
+    # @return [Integer, nil]
+    def total_tokens
+      @usage&.dig("total_tokens")
+    end
+
+    # Get the prompt tokens used.
+    # @return [Integer, nil]
+    def prompt_tokens
+      @usage&.dig("prompt_tokens")
+    end
+
+    private
+
+    def build_data(data_array)
+      return [] unless data_array
+
+      data_array.map { |attrs| EmbeddingData.new(attrs) }
+    end
+  end
+
+  # Represents a single embedding result within an Embedding response.
+  class EmbeddingData
+    # @return [Integer] Index of this embedding in the batch
+    attr_reader :index
+    # @return [Array<Float>] The embedding vector
+    attr_reader :embedding
+
+    # @param attributes [Hash] Raw attributes from API response
+    def initialize(attributes)
+      @index = attributes["index"]
+      @embedding = attributes["embedding"]
+    end
+
+    # Get the dimension of this embedding vector.
+    # @return [Integer]
+    def dimensions
+      @embedding&.length || 0
+    end
+  end
+end

data/lib/openrouter/endpoint.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents a specific endpoint/provider for a model.
+  # Models can have multiple endpoints from different providers with different pricing and capabilities.
+  class Endpoint
+    # @return [String] Endpoint name
+    attr_reader :name
+    # @return [String] Model name
+    attr_reader :model_name
+    # @return [Integer] Context length in tokens
+    attr_reader :context_length
+    # @return [Hash] Pricing information
+    attr_reader :pricing
+    # @return [String] Provider name (e.g., "OpenAI", "Azure")
+    attr_reader :provider_name
+    # @return [String, nil] Tag
+    attr_reader :tag
+    # @return [Hash, nil] Quantization info
+    attr_reader :quantization
+    # @return [Integer, nil] Maximum completion tokens
+    attr_reader :max_completion_tokens
+    # @return [Integer, nil] Maximum prompt tokens
+    attr_reader :max_prompt_tokens
+    # @return [Array<String>] Supported parameters
+    attr_reader :supported_parameters
+    # @return [String, nil] Endpoint status
+    attr_reader :status
+    # @return [Float, nil] Uptime in the last 30 minutes
+    attr_reader :uptime_last_30m
+    # @return [Boolean] Whether the endpoint supports implicit caching
+    attr_reader :supports_implicit_caching
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    def initialize(attributes)
+      @name = attributes["name"]
+      @model_name = attributes["model_name"]
+      @context_length = attributes["context_length"]
+      @pricing = attributes["pricing"]
+      @provider_name = attributes["provider_name"]
+      @tag = attributes["tag"]
+      @quantization = attributes["quantization"]
+      @max_completion_tokens = attributes["max_completion_tokens"]
+      @max_prompt_tokens = attributes["max_prompt_tokens"]
+      @supported_parameters = attributes["supported_parameters"] || []
+      @status = attributes["status"]
+      @uptime_last_30m = attributes["uptime_last_30m"]
+      @supports_implicit_caching = attributes["supports_implicit_caching"] || false
+    end
+
+    # Get the prompt/input price per token.
+    # @return [Float, nil]
+    def prompt_price
+      @pricing&.dig("prompt")&.to_f
+    end
+
+    # Get the completion/output price per token.
+    # @return [Float, nil]
+    def completion_price
+      @pricing&.dig("completion")&.to_f
+    end
+
+    # Get the image price.
+    # @return [Float, nil]
+    def image_price
+      @pricing&.dig("image")&.to_f
+    end
+
+    # Get any discount percentage.
+    # @return [Float, nil]
+    def discount
+      @pricing&.dig("discount")&.to_f
+    end
+
+    # Check if this endpoint is free.
+    # @return [Boolean]
+    def free?
+      prompt_price&.zero? && completion_price&.zero?
+    end
+
+    # Check if this endpoint is currently available.
+    # Status "0" indicates the endpoint is healthy.
+    # @return [Boolean]
+    def available?
+      @status == "0"
+    end
+
+    # Check if this endpoint supports a specific parameter.
+    # @param parameter [String, Symbol] The parameter to check
+    # @return [Boolean]
+    def supports?(parameter)
+      @supported_parameters.include?(parameter.to_s)
+    end
+  end
+end

data/lib/openrouter/model.rb

@@ -18,7 +18,7 @@ module OpenRouter
     attr_reader :pricing
     # @return [Integer, nil] Top provider information
     attr_reader :top_provider
-    # @return [String, nil] Model architecture
+    # @return [Hash, nil] Model architecture
     attr_reader :architecture
     # @return [Array<String>, nil] Supported parameters
     attr_reader :supported_parameters
@@ -26,6 +26,8 @@ module OpenRouter
     attr_reader :per_request_limits
     # @return [String, nil] Created timestamp
     attr_reader :created
+    # @return [Array<OpenRouter::Endpoint>, nil] Available endpoints for this model
+    attr_reader :endpoints
 
     # @param attributes [Hash] Raw attributes from OpenRouter API
     # @param client [OpenRouter::Client] HTTP client
@@ -68,26 +70,32 @@ module OpenRouter
 
     class << self
       # Find a specific model by ID. Raises NotFoundError if not found.
-      # @param id [String] The model identifier
+      # @param id [String] The model identifier (e.g., "openai/gpt-4")
       # @param client [OpenRouter::Client] HTTP client
       # @return [OpenRouter::Model]
       # @raise [OpenRouter::NotFoundError] if model not found
       def find(id, client: OpenRouter.client)
-        model = find_by(id: id, client: client)
-        raise NotFoundError, "Model not found: #{id}" unless model
+        author, slug = parse_model_id(id)
+        path = "#{MODELS_PATH}/#{author}/#{slug}/endpoints"
+
+        response = client.get(path)
+        return new(response["data"], client: client) if response && response["data"]
 
-        model
+        raise NotFoundError, "Model not found: #{id}"
+      rescue NotFoundError
+        raise
+      rescue OpenRouter::Error
+        raise NotFoundError, "Model not found: #{id}"
       end
 
       # Find a specific model by ID. Returns nil if not found.
-      # @param id [String] The model identifier
+      # @param id [String] The model identifier (e.g., "openai/gpt-4")
       # @param client [OpenRouter::Client] HTTP client
       # @return [OpenRouter::Model, nil]
       def find_by(id:, client: OpenRouter.client)
-        response = client.get(MODELS_PATH)
-        models = Array(response && response["data"])
-        entry = models.find { |model| model["id"] == id }
-        entry ? new(entry, client: client) : nil
+        find(id, client: client)
+      rescue NotFoundError
+        nil
       end
 
       # Find a specific model by ID. Raises NotFoundError if not found.
@@ -144,6 +152,19 @@ module OpenRouter
       def free(client: OpenRouter.client)
         all(client: client).select(&:free?)
       end
+
+      private
+
+      # Parse a model ID into author and slug components.
+      # @param id [String] The model identifier (e.g., "openai/gpt-4")
+      # @return [Array<String>] [author, slug]
+      # @raise [ArgumentError] if the ID format is invalid
+      def parse_model_id(id)
+        parts = id.to_s.split("/", 2)
+        raise ArgumentError, "Invalid model ID format: #{id}. Expected 'author/slug'" if parts.length != 2
+
+        parts
+      end
     end
 
     private
@@ -159,6 +180,13 @@ module OpenRouter
       @supported_parameters = attributes["supported_parameters"]
       @per_request_limits = attributes["per_request_limits"]
       @created = attributes["created"]
+      @endpoints = build_endpoints(attributes["endpoints"])
+    end
+
+    def build_endpoints(endpoints_data)
+      return nil unless endpoints_data
+
+      endpoints_data.map { |attrs| OpenRouter::Endpoint.new(attrs) }
     end
   end
 end

data/lib/openrouter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenRouter
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/openrouter.rb

@@ -113,7 +113,9 @@ end
 require_relative "openrouter/client"
 require_relative "openrouter/completion"
 require_relative "openrouter/stream"
+require_relative "openrouter/endpoint"
 require_relative "openrouter/model"
+require_relative "openrouter/embedding"
 require_relative "openrouter/generation"
 require_relative "openrouter/credit"
 require_relative "openrouter/api_key"

data/rbi/openrouter/embedding.rbi

@@ -0,0 +1,68 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenRouter
+  class Embedding
+    EMBEDDINGS_PATH = T.let(T.unsafe(nil), String)
+    EMBEDDING_MODELS_PATH = T.let(T.unsafe(nil), String)
+
+    sig { returns(String) }
+    def model; end
+
+    sig { returns(T::Array[OpenRouter::EmbeddingData]) }
+    def data; end
+
+    sig { returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def usage; end
+
+    sig { params(attributes: T.untyped).void }
+    def initialize(attributes); end
+
+    sig do
+      params(
+        model: String,
+        input: T.any(String, T::Array[String]),
+        client: OpenRouter::Client,
+        options: T.untyped
+      ).returns(OpenRouter::Embedding)
+    end
+    def self.create!(model:, input:, client: OpenRouter.client, **options); end
+
+    sig { params(client: OpenRouter::Client).returns(T::Array[T::Hash[T.untyped, T.untyped]]) }
+    def self.models(client: OpenRouter.client); end
+
+    sig { returns(T.nilable(T::Array[Float])) }
+    def vector; end
+
+    sig { returns(T::Array[T::Array[Float]]) }
+    def vectors; end
+
+    sig { returns(T.nilable(Integer)) }
+    def dimensions; end
+
+    sig { returns(T.nilable(Integer)) }
+    def total_tokens; end
+
+    sig { returns(T.nilable(Integer)) }
+    def prompt_tokens; end
+
+    private
+
+    sig { params(data_array: T.nilable(T::Array[T::Hash[T.untyped, T.untyped]])).returns(T::Array[OpenRouter::EmbeddingData]) }
+    def build_data(data_array); end
+  end
+
+  class EmbeddingData
+    sig { returns(Integer) }
+    def index; end
+
+    sig { returns(T::Array[Float]) }
+    def embedding; end
+
+    sig { params(attributes: T.untyped).void }
+    def initialize(attributes); end
+
+    sig { returns(Integer) }
+    def dimensions; end
+  end
+end

data/rbi/openrouter/endpoint.rbi

@@ -0,0 +1,69 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenRouter
+  class Endpoint
+    sig { returns(String) }
+    def name; end
+
+    sig { returns(String) }
+    def model_name; end
+
+    sig { returns(Integer) }
+    def context_length; end
+
+    sig { returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def pricing; end
+
+    sig { returns(String) }
+    def provider_name; end
+
+    sig { returns(T.nilable(String)) }
+    def tag; end
+
+    sig { returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def quantization; end
+
+    sig { returns(T.nilable(Integer)) }
+    def max_completion_tokens; end
+
+    sig { returns(T.nilable(Integer)) }
+    def max_prompt_tokens; end
+
+    sig { returns(T::Array[String]) }
+    def supported_parameters; end
+
+    sig { returns(T.nilable(String)) }
+    def status; end
+
+    sig { returns(T.nilable(Float)) }
+    def uptime_last_30m; end
+
+    sig { returns(T::Boolean) }
+    def supports_implicit_caching; end
+
+    sig { params(attributes: T.untyped).void }
+    def initialize(attributes); end
+
+    sig { returns(T.nilable(Float)) }
+    def prompt_price; end
+
+    sig { returns(T.nilable(Float)) }
+    def completion_price; end
+
+    sig { returns(T.nilable(Float)) }
+    def image_price; end
+
+    sig { returns(T.nilable(Float)) }
+    def discount; end
+
+    sig { returns(T::Boolean) }
+    def free?; end
+
+    sig { returns(T::Boolean) }
+    def available?; end
+
+    sig { params(parameter: T.any(String, Symbol)).returns(T::Boolean) }
+    def supports?(parameter); end
+  end
+end

data/rbi/openrouter/model.rbi

@@ -35,6 +35,9 @@ module OpenRouter
     sig { returns(T.nilable(String)) }
     def created; end
 
+    sig { returns(T.nilable(T::Array[OpenRouter::Endpoint])) }
+    def endpoints; end
+
     sig { params(attributes: T.untyped, client: OpenRouter::Client).void }
     def initialize(attributes, client: OpenRouter.client); end
 
@@ -82,11 +85,19 @@ module OpenRouter
 
       sig { params(client: OpenRouter::Client).returns(T::Array[OpenRouter::Model]) }
       def free(client: OpenRouter.client); end
+
+      private
+
+      sig { params(id: String).returns([String, String]) }
+      def parse_model_id(id); end
     end
 
     private
 
     sig { params(attributes: T.untyped).void }
     def reset_attributes(attributes); end
+
+    sig { params(endpoints_data: T.nilable(T::Array[T::Hash[T.untyped, T.untyped]])).returns(T.nilable(T::Array[OpenRouter::Endpoint])) }
+    def build_endpoints(endpoints_data); end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: openrouter_client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Dylan Player
 bindir: exe
 cert_chain: []
-date: 2026-01-06 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -44,6 +44,8 @@ files:
 - lib/openrouter/client.rb
 - lib/openrouter/completion.rb
 - lib/openrouter/credit.rb
+- lib/openrouter/embedding.rb
+- lib/openrouter/endpoint.rb
 - lib/openrouter/generation.rb
 - lib/openrouter/model.rb
 - lib/openrouter/stream.rb
@@ -53,6 +55,8 @@ files:
 - rbi/openrouter/client.rbi
 - rbi/openrouter/completion.rbi
 - rbi/openrouter/credit.rbi
+- rbi/openrouter/embedding.rbi
+- rbi/openrouter/endpoint.rbi
 - rbi/openrouter/generation.rbi
 - rbi/openrouter/model.rbi
 - rbi/openrouter/openrouter.rbi