savvy_openrouter 0.2.0

data/lib/savvy_openrouter/resources/guardrails.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Guardrails < Base
+      def list(**params)
+        conn.get("/guardrails", params: params)
+      end
+
+      def create(**body)
+        conn.post("/guardrails", body: body, success: [201])
+      end
+
+      def get(id)
+        conn.get("/guardrails/#{id}")
+      end
+
+      def update(id, **body)
+        conn.patch("/guardrails/#{id}", body: body)
+      end
+
+      def delete(id)
+        conn.delete("/guardrails/#{id}")
+      end
+
+      def list_key_assignments(guardrail_id, **params)
+        conn.get("/guardrails/#{guardrail_id}/assignments/keys", params: params)
+      end
+
+      def bulk_assign_keys(guardrail_id, **body)
+        conn.post("/guardrails/#{guardrail_id}/assignments/keys", body: body)
+      end
+
+      def bulk_unassign_keys(guardrail_id, **body)
+        conn.post("/guardrails/#{guardrail_id}/assignments/keys/remove", body: body)
+      end
+
+      def list_member_assignments(guardrail_id, **params)
+        conn.get("/guardrails/#{guardrail_id}/assignments/members", params: params)
+      end
+
+      def bulk_assign_members(guardrail_id, **body)
+        conn.post("/guardrails/#{guardrail_id}/assignments/members", body: body)
+      end
+
+      def bulk_unassign_members(guardrail_id, **body)
+        conn.post("/guardrails/#{guardrail_id}/assignments/members/remove", body: body)
+      end
+
+      def list_all_key_assignments(**params)
+        conn.get("/guardrails/assignments/keys", params: params)
+      end
+
+      def list_all_member_assignments(**params)
+        conn.get("/guardrails/assignments/members", params: params)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/models.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Models < Base
+      # Query params match OpenRouter GET /models (e.g. category, output_modalities, supported_parameters).
+      def list(**params)
+        query = stringify_query(params)
+        conn.get("/models", params: query.empty? ? nil : query)
+      end
+
+      # Uses GET /models with filters, then returns the first model whose prompt + completion pricing are zero.
+      # OpenRouter returns models in curated rank order within a category; first matching free model aligns with
+      # site “top free” picks when combined with output_modalities=text.
+      def first_ranked_free_text_model(category:, output_modalities: "text")
+        res = list(category: category, output_modalities: output_modalities)
+        data = res[:data] || []
+        data.find { |m| free_pricing?(m) }
+      end
+
+      def count
+        conn.get("/models/count")
+      end
+
+      def user
+        conn.get("/models/user")
+      end
+
+      def endpoints(author:, slug:)
+        conn.get("/models/#{author}/#{slug}/endpoints")
+      end
+
+      private
+
+      def stringify_query(params)
+        params.each_with_object({}) do |(k, v), acc|
+          next if v.nil?
+
+          acc[k.to_s] = v
+        end
+      end
+
+      def free_pricing?(model)
+        p = model[:pricing] || {}
+        zero_price?(p[:prompt]) && zero_price?(p[:completion])
+      end
+
+      def zero_price?(value)
+        return false if value.nil?
+
+        value.to_s.gsub(/[^\d.\-eE]/, "").to_f.zero?
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/oauth.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class OAuth < Base
+      def exchange(**body)
+        conn.post("/auth/keys", body: body)
+      end
+
+      def create_auth_code(**body)
+        conn.post("/auth/keys/code", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/organization.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Organization < Base
+      def members
+        conn.get("/organization/members")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/providers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Providers < Base
+      def list
+        conn.get("/providers")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/rerank.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Rerank < Base
+      def create(**params)
+        body = config.merge_chat_body(params)
+        conn.post("/rerank", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/responses.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Responses < Base
+      def create(**params)
+        body = config.merge_responses_body(params)
+        conn.post("/responses", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/videos.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Videos < Base
+      TERMINAL_STATUSES = %w[completed failed cancelled expired].freeze
+
+      def create(**params)
+        body = config.merge_video_body(params)
+        conn.post("/videos", body: body)
+      end
+
+      alias submit create
+
+      def get(job_id)
+        conn.get("/videos/#{job_id}")
+      end
+
+      alias retrieve get
+      alias poll get
+
+      def download(job_id, index: 0)
+        conn.get_raw("/videos/#{job_id}/content", params: { index: index })
+      end
+
+      def stream(job_id, index: 0, &block)
+        raise ArgumentError, "block required" unless block
+
+        conn.stream_get("/videos/#{job_id}/content", params: { index: index }, &block)
+      end
+
+      def poll_until(job_id, interval: 2, timeout: 600)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          res = get(job_id)
+          st = res[:status].to_s
+          return res if TERMINAL_STATUSES.include?(st)
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise TimeoutPollError, "Timed out waiting for video job #{job_id}" if now > deadline
+
+          sleep(interval)
+        end
+      end
+
+      def models
+        conn.get("/videos/models")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/workspaces.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Workspaces < Base
+      def list(**params)
+        conn.get("/workspaces", params: params)
+      end
+
+      def create(**body)
+        conn.post("/workspaces", body: body, success: [201])
+      end
+
+      def get(id)
+        conn.get("/workspaces/#{id}")
+      end
+
+      def update(id, **body)
+        conn.patch("/workspaces/#{id}", body: body)
+      end
+
+      def delete(id)
+        conn.delete("/workspaces/#{id}")
+      end
+
+      def bulk_add_members(workspace_id, **body)
+        conn.post("/workspaces/#{workspace_id}/members/add", body: body)
+      end
+
+      def bulk_remove_members(workspace_id, **body)
+        conn.post("/workspaces/#{workspace_id}/members/remove", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/streaming.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  module Streaming
+    extend self
+
+    # Yields each SSE `data:` payload line (without `data:` prefix), skipping `[DONE]`.
+    def each_sse_data(chunk_enum, &block)
+      buffer = +""
+      chunk_enum.each do |chunk|
+        buffer << chunk
+        flush_sse!(buffer, &block)
+      end
+    end
+
+    private
+
+    def flush_sse!(buffer, &block)
+      while (idx = buffer.index("\n\n"))
+        blob = buffer.slice!(0..(idx + 1))
+        blob.each_line do |line|
+          line = line.strip
+          next if line.empty?
+          next unless line.start_with?("data:")
+
+          payload = line.sub(/\Adata:\s*/, "")
+          block.call(payload) unless payload == "[DONE]"
+        end
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  VERSION = "0.2.0"
+end

data/lib/savvy_openrouter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "savvy_openrouter/version"
+require_relative "savvy_openrouter/errors"
+require_relative "savvy_openrouter/configuration"
+require_relative "savvy_openrouter/completion_retry_policy"
+require_relative "savvy_openrouter/api_call_logger"
+require_relative "savvy_openrouter/connection"
+require_relative "savvy_openrouter/streaming"
+require_relative "savvy_openrouter/client"
+
+module SavvyOpenrouter
+end

data/sig/savvy_openrouter.rbs

@@ -0,0 +1,150 @@
+module SavvyOpenrouter
+  VERSION: String
+
+  class Error < StandardError
+    attr_reader status_code: Integer?
+    attr_reader response_body: untyped
+    def initialize: (?String message, ?status_code: Integer?, ?response_body: untyped) -> void
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ApiError < Error
+  end
+
+  class BadRequestError < ApiError
+  end
+
+  class AuthenticationError < ApiError
+  end
+
+  class PaymentRequiredError < ApiError
+  end
+
+  class ForbiddenError < ApiError
+  end
+
+  class NotFoundError < ApiError
+  end
+
+  class RateLimitError < ApiError
+  end
+
+  class InternalServerError < ApiError
+  end
+
+  class BadGatewayError < ApiError
+  end
+
+  class TimeoutPollError < Error
+  end
+
+  class Configuration
+    attr_accessor api_key: String?
+    attr_accessor base_url: String
+    attr_accessor default_model: String?
+    attr_accessor http_referer: String?
+    attr_accessor app_title: String?
+    attr_reader defaults: Hash[String, untyped]
+    attr_reader video_defaults: Hash[String, untyped]
+    attr_reader responses_defaults: Hash[String, untyped]
+    attr_reader api_call_log: Hash[String, untyped]
+    attr_reader chat_retries: Hash[String, untyped]
+
+    def initialize: (?config_path: String?, **untyped options) -> void
+    def merge_chat_body: (Hash[Symbol | String, untyped] body) -> Hash[String, untyped]
+    def merge_video_body: (Hash[Symbol | String, untyped] body) -> Hash[String, untyped]
+    def merge_responses_body: (Hash[Symbol | String, untyped] body) -> Hash[String, untyped]
+    def self.load_file: (String path) -> Hash[String, untyped]
+    def self.discover_config_file: (?String cwd) -> String?
+  end
+
+  class ApiCallLogger
+    def initialize: (Hash[String, untyped] config) -> void
+    def enabled?: () -> bool
+    def max_body_limit: () -> Integer
+    def record: (Hash[String, untyped] attrs) -> untyped
+    def self.format_body_for_log: (untyped obj, ?max_bytes: Integer) -> String
+  end
+
+  class CompletionRetryPolicy
+    def initialize: (Hash[String, untyped] | false? raw) -> void
+    def max_attempts: () -> Integer
+    def enabled?: () -> bool
+    def retry_http_error?: (ApiError error) -> bool
+    def retry_response?: (Hash[Symbol | String, untyped] response) -> bool
+    def wait_after_attempt: (Integer attempt_number) -> void
+  end
+
+  class Connection
+    DEFAULT_SUCCESS: Array[Integer]
+
+    attr_reader config: Configuration
+
+    def initialize: (Configuration config) -> void
+    def get: (String path, ?params: Hash[Symbol | String, untyped]?, ?success: Array[Integer]?) -> untyped
+    def delete: (String path, ?params: Hash[Symbol | String, untyped]?, ?success: Array[Integer]?) -> untyped
+    def post: (String path, body: Hash[Symbol | String, untyped], ?success: Array[Integer]?) -> untyped
+    def patch: (String path, body: Hash[Symbol | String, untyped], ?success: Array[Integer]?) -> untyped
+    def put: (String path, body: Hash[Symbol | String, untyped], ?success: Array[Integer]?) -> untyped
+    def get_raw: (String path, ?params: Hash[Symbol | String, untyped]?, ?success: Array[Integer]?) -> String
+    def post_raw: (String path, body: Hash[Symbol | String, untyped], ?success: Array[Integer]?) -> String
+    def stream_get: (String path, ?params: Hash[Symbol | String, untyped]?) { (String chunk) -> void } -> void
+    def stream_post: (String path, Hash[Symbol | String, untyped] body) { (String chunk) -> void } -> void
+  end
+
+  class Client
+    attr_reader config: Configuration
+    attr_reader connection: Connection
+
+    def initialize: (?config_path: String?, **untyped options) -> void
+
+    def chat: -> Resources::Chat
+    def responses: -> Resources::Responses
+    def anthropic_messages: -> Resources::AnthropicMessages
+    def embeddings: -> Resources::Embeddings
+    def rerank: -> Resources::Rerank
+    def models: -> Resources::Models
+    def credits: -> Resources::Credits
+    def providers: -> Resources::Providers
+    def generations: -> Resources::Generations
+    def endpoints: -> Resources::Endpoints
+    def analytics: -> Resources::Analytics
+    def audio: -> Resources::Audio
+    def videos: -> Resources::Videos
+    def oauth: -> Resources::OAuth
+    def api_keys: -> Resources::ApiKeys
+    def organization: -> Resources::Organization
+    def guardrails: -> Resources::Guardrails
+    def workspaces: -> Resources::Workspaces
+  end
+
+  module Resources
+    class Chat
+      def completions: (messages: untyped, **untyped params) -> untyped
+      def completions_stream: (messages: untyped, **untyped params) ?{ (String sse_data_line) -> void } -> (Enumerator[String] | void)
+    end
+
+    class Models
+      def list: (**untyped params) -> untyped
+      def count: () -> untyped
+      def user: () -> untyped
+      def endpoints: (author: String, slug: String) -> untyped
+      def first_ranked_free_text_model: (category: String, ?output_modalities: String) -> Hash[Symbol, untyped]?
+    end
+
+    class Videos
+      def create: (**untyped params) -> untyped
+      def get: (String job_id) -> untyped
+      def download: (String job_id, ?index: Integer) -> String
+      def stream: (String job_id, ?index: Integer) { (String chunk) -> void } -> void
+      def poll_until: (String job_id, ?interval: Numeric, ?timeout: Numeric) -> untyped
+      def models: () -> untyped
+    end
+  end
+
+  module Streaming
+    def self.each_sse_data: (Enumerator[String] chunk_enum) { (String payload) -> void } -> void
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: savvy_openrouter
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Bryan Feller
+bindir: exe
+cert_chain: []
+date: 2026-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: 'OpenRouter Ruby client: chat (streaming SSE), configurable retries for
+  non-streaming completions, optional DB-backed API call logging, Responses API defaults,
+  models listing with filters and free-tier hints, embeddings, rerank, audio, video,
+  OAuth, API keys, guardrails, workspaces, and related REST endpoints.'
+email:
+- brizzlefeller@gmail.com
+executables:
+- savvy_openrouter
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/savvy_openrouter
+- lib/generators/savvy_openrouter/install/install_generator.rb
+- lib/generators/savvy_openrouter/install/templates/savvy_openrouter.yml
+- lib/savvy_openrouter.rb
+- lib/savvy_openrouter/api_call_logger.rb
+- lib/savvy_openrouter/client.rb
+- lib/savvy_openrouter/completion_retry_policy.rb
+- lib/savvy_openrouter/configuration.rb
+- lib/savvy_openrouter/connection.rb
+- lib/savvy_openrouter/connection_instrumentation.rb
+- lib/savvy_openrouter/errors.rb
+- lib/savvy_openrouter/resources/analytics.rb
+- lib/savvy_openrouter/resources/anthropic_messages.rb
+- lib/savvy_openrouter/resources/api_keys.rb
+- lib/savvy_openrouter/resources/audio.rb
+- lib/savvy_openrouter/resources/base.rb
+- lib/savvy_openrouter/resources/chat.rb
+- lib/savvy_openrouter/resources/credits.rb
+- lib/savvy_openrouter/resources/embeddings.rb
+- lib/savvy_openrouter/resources/endpoints.rb
+- lib/savvy_openrouter/resources/generations.rb
+- lib/savvy_openrouter/resources/guardrails.rb
+- lib/savvy_openrouter/resources/models.rb
+- lib/savvy_openrouter/resources/oauth.rb
+- lib/savvy_openrouter/resources/organization.rb
+- lib/savvy_openrouter/resources/providers.rb
+- lib/savvy_openrouter/resources/rerank.rb
+- lib/savvy_openrouter/resources/responses.rb
+- lib/savvy_openrouter/resources/videos.rb
+- lib/savvy_openrouter/resources/workspaces.rb
+- lib/savvy_openrouter/streaming.rb
+- lib/savvy_openrouter/version.rb
+- savvy_openrouter-0.1.0.gem
+- sig/savvy_openrouter.rbs
+homepage: https://github.com/brizzlefeller/savvy_openrouter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/brizzlefeller/savvy_openrouter
+  source_code_uri: https://github.com/brizzlefeller/savvy_openrouter
+  changelog_uri: https://github.com/brizzlefeller/savvy_openrouter/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby client for the OpenRouter unified AI API.
+test_files: []