spectre_ai 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '03910c4dd38bf7a272fab91c0e9d1431d0f9bdc593abe62035271e9e07f22e89'
-  data.tar.gz: 0f1e927a42785d2f4735e4adf9140efad6815247fca6ce6270ac10ef286ae217
+  metadata.gz: 2a0cd0a25dd4345c62af319d8669a3702ce2e505299c01fbf43e4a94cb3b3109
+  data.tar.gz: 544e5bb1462d2d9477601d6a581d455a30e5b0a5f107ec1264608c0f9b713307
 SHA512:
-  metadata.gz: 48e634fedb903de30ff0acba0b1de5b725fccb2ac0882bf8890740100312c92ae48c6c182612554cdd6968b34df5f6c7958a62caf19492ae29a42d8e084e1458
-  data.tar.gz: b7a382fb583431eff8715147df8f5251e30d528b0a77ecc6c2ecf68b324f57f76e9c6a2634da07f55159713d9cd58684e212b75fee7f5a7e20e56b437725dd55
+  metadata.gz: cdb1062a23c35d4df2ca354eeff42ebd28b5d2ddef3a710ee032917a5a1bad811645f61dc8d5e5914b2fc16cd319768a3bd6ec84f3e9bc4ed50c22af1a073855
+  data.tar.gz: ecca27c2bd3f7ada23f744dd93017b488fbf193652b1bbdf5c3f47110bfd7ae7c042a66398d53592bc3c59d79031c0f46987b12551ebc1b4f1923f215efa55ce

data/CHANGELOG.md

@@ -280,3 +280,59 @@ Key Benefits:\
 ### Behavior Notes
 
 - Gemini OpenAI-compatible chat endpoint requires that the last message in `messages` has role 'user'. Spectre raises an ArgumentError if this requirement is not met to prevent 400 INVALID_ARGUMENT errors from the API.
+
+
+# Changelog for Version 2.1.0
+
+**Release Date:** [12th Nov 2025]
+
+### New Provider: OpenRouter
+
+- Added Spectre::Openrouter provider with:
+  - Chat Completions via `https://openrouter.ai/api/v1/chat/completions` (OpenAI-compatible interface).
+  - Embeddings via `https://openrouter.ai/api/v1/embeddings`.
+  - Provider configuration: `Spectre.setup { |c| c.openrouter { |o| o.api_key = ENV['OPENROUTER_API_KEY']; o.referer = 'https://your.app' ; o.app_title = 'Your App' } }`.
+  - Optional headers supported: `HTTP-Referer` and `X-Title` (as recommended by OpenRouter).
+  - Finish reasons handled per OpenRouter docs: `stop`, `tool_calls`/`function_call`, `length`/`model_length`, `content_filter`, `error`.
+  - Refusal handling (raises an error if the model returns a refusal).
+
+### Structured Outputs (json_schema)
+
+- OpenRouter completions support OpenAI-style `response_format: { type: 'json_schema', json_schema: ... }`.
+- Note for schema authors: many OpenRouter-backed providers require a strict schema:
+  - Include a non-empty `required` array listing all keys in `properties`.
+  - Consider `strict: true` and `additionalProperties: false` for best adherence.
+
+### Tests
+
+- Added RSpec tests for `Spectre::Openrouter::Completions` and `Spectre::Openrouter::Embeddings` covering:
+  - Success responses, error propagation, JSON parse errors.
+  - Finish reasons and refusal handling.
+  - Request body formation (max_tokens, tools, response_format.json_schema).
+
+### Breaking Changes
+
+- Unified `max_tokens` option across providers:
+  - Now accepted only as a top-level argument: `... Completions.create(messages: ..., max_tokens: 256)`.
+  - Removed support for provider-scoped forms like `openai: { max_tokens: ... }`, `openrouter: { max_tokens: ... }`, `claude: { max_tokens: ... }`, `gemini: { max_tokens: ... }`.
+
+### Usage Examples
+
+- OpenRouter (completions):
+  ```ruby
+  Spectre.setup do |c|
+    c.default_llm_provider = :openrouter
+    c.openrouter { |o| o.api_key = ENV['OPENROUTER_API_KEY'] }
+  end
+
+  Spectre::Openrouter::Completions.create(
+    messages: [ { role: 'user', content: 'Hello!' } ],
+    model: 'openai/gpt-4o-mini',
+    max_tokens: 256
+  )
+  ```
+
+- OpenRouter (embeddings):
+  ```ruby
+  Spectre::Openrouter::Embeddings.create('some text', model: 'text-embedding-3-small')
+  ```

data/lib/spectre/claude/completions.rb

@@ -21,7 +21,7 @@ module Spectre
       # @param json_schema [Hash, nil] Optional JSON Schema; when provided, it will be converted into a tool with input_schema and forced via tool_choice unless overridden
       # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
       # @param tool_choice [Hash, nil] Optional tool_choice to force a specific tool use (e.g., { type: 'tool', name: 'record_summary' })
-      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. For Claude, max_tokens can be passed in the claude hash.
+      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. Provide max_tokens at the top level only.
       # @return [Hash] The parsed response including any tool calls or content
       # @raise [APIKeyNotConfiguredError] If the API key is not set
       # @raise [RuntimeError] For general API errors or unexpected issues
@@ -43,7 +43,7 @@ module Spectre
           'anthropic-version' => ANTHROPIC_VERSION
         })
 
-        max_tokens = args.dig(:claude, :max_tokens) || 1024
+        max_tokens = args[:max_tokens] || 1024
         request.body = generate_body(messages, model, json_schema, max_tokens, tools, tool_choice).to_json
         response = http.request(request)
 

data/lib/spectre/gemini/completions.rb

@@ -18,7 +18,7 @@ module Spectre
       # @param model [String] The model to be used for generating completions, defaults to DEFAULT_MODEL
       # @param json_schema [Hash, nil] An optional JSON schema to enforce structured output (OpenAI-compatible "response_format")
       # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
-      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. For Gemini, max_tokens can be passed in the gemini hash.
+      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. Provide max_tokens at the top level only.
       # @return [Hash] The parsed response including any function calls or content
       # @raise [APIKeyNotConfiguredError] If the API key is not set
       # @raise [RuntimeError] For general API errors or unexpected issues
@@ -39,7 +39,7 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        max_tokens = args.dig(:gemini, :max_tokens)
+        max_tokens = args[:max_tokens]
         request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
         response = http.request(request)
 

data/lib/spectre/openai/completions.rb

@@ -17,7 +17,7 @@ module Spectre
       # @param model [String] The model to be used for generating completions, defaults to DEFAULT_MODEL
       # @param json_schema [Hash, nil] An optional JSON schema to enforce structured output
       # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
-      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. For OpenAI, max_tokens can be passed in the openai hash.
+      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. Provide max_tokens at the top level only.
       # @return [Hash] The parsed response including any function calls or content
       # @raise [APIKeyNotConfiguredError] If the API key is not set
       # @raise [RuntimeError] For general API errors or unexpected issues
@@ -38,7 +38,7 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        max_tokens = args.dig(:openai, :max_tokens)
+        max_tokens = args[:max_tokens]
         request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
         response = http.request(request)
 

data/lib/spectre/openrouter/completions.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Openrouter
+    class Completions
+      API_URL = 'https://openrouter.ai/api/v1/chat/completions'
+      DEFAULT_MODEL = 'openai/gpt-4o-mini'
+      DEFAULT_TIMEOUT = 60
+
+      # Generate a completion based on user messages and optional tools
+      #
+      # @param messages [Array<Hash>] The conversation messages, each with a role and content
+      # @param model [String] The model to be used for generating completions
+      # @param json_schema [Hash, nil] An optional JSON schema to enforce structured output (OpenAI-compatible)
+      # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
+      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout. Provide max_tokens at the top level only.
+      # @return [Hash] The parsed response including any tool calls or content
+      # @raise [APIKeyNotConfiguredError] If the API key is not set
+      # @raise [RuntimeError] For general API errors or unexpected issues
+      def self.create(messages:, model: DEFAULT_MODEL, json_schema: nil, tools: nil, **args)
+        cfg = Spectre.openrouter_configuration
+        api_key = cfg&.api_key
+        raise APIKeyNotConfiguredError, 'API key is not configured' unless api_key
+
+        validate_messages!(messages)
+
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = args.fetch(:read_timeout, DEFAULT_TIMEOUT)
+        http.open_timeout = args.fetch(:open_timeout, DEFAULT_TIMEOUT)
+
+        headers = {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        }
+        headers['HTTP-Referer'] = cfg.referer if cfg.respond_to?(:referer) && cfg.referer
+        headers['X-Title'] = cfg.app_title if cfg.respond_to?(:app_title) && cfg.app_title
+
+        request = Net::HTTP::Post.new(uri.path, headers)
+
+        max_tokens = args[:max_tokens]
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "OpenRouter API Error: #{response.code} - #{response.message}: #{response.body}"
+        end
+
+        parsed_response = JSON.parse(response.body)
+        handle_response(parsed_response)
+      rescue JSON::ParserError => e
+        raise "JSON Parse Error: #{e.message}"
+      end
+
+      private
+
+      def self.validate_messages!(messages)
+        unless messages.is_a?(Array) && messages.all? { |msg| msg.is_a?(Hash) }
+          raise ArgumentError, 'Messages must be an array of message hashes.'
+        end
+        raise ArgumentError, 'Messages cannot be empty.' if messages.empty?
+      end
+
+      def self.generate_body(messages, model, json_schema, max_tokens, tools)
+        body = {
+          model: model,
+          messages: messages
+        }
+        body[:max_tokens] = max_tokens if max_tokens
+        body[:response_format] = { type: 'json_schema', json_schema: json_schema } if json_schema
+        body[:tools] = tools if tools
+        body
+      end
+
+      # Handle OpenRouter finish reasons
+      # https://openrouter.ai/docs/api-reference/overview#finish-reason
+      def self.handle_response(response)
+        message = response.dig('choices', 0, 'message') || {}
+        finish_reason = response.dig('choices', 0, 'finish_reason')
+
+        if message['refusal']
+          raise "Refusal: #{message['refusal']}"
+        end
+
+        case finish_reason
+        when 'stop'
+          return { content: message['content'] }
+        when 'tool_calls', 'function_call'
+          return { tool_calls: message['tool_calls'], content: message['content'] }
+        when 'length', 'model_length'
+          raise 'Incomplete response: The completion was cut off due to token limit.'
+        when 'content_filter'
+          raise "Content filtered: The model's output was blocked due to policy violations."
+        when 'error'
+          raise "Model returned finish_reason=error: #{response.inspect}"
+        else
+          raise "Unexpected finish_reason: #{finish_reason}"
+        end
+      end
+    end
+  end
+end

data/lib/spectre/openrouter/embeddings.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Openrouter
+    class Embeddings
+      API_URL = 'https://openrouter.ai/api/v1/embeddings'
+      DEFAULT_MODEL = 'text-embedding-3-small' # OpenRouter proxies OpenAI and others; user can override with provider/model
+      DEFAULT_TIMEOUT = 60
+
+      # Generate embeddings for a given text
+      #
+      # @param text [String] the text input for which embeddings are to be generated
+      # @param model [String] the model to be used for generating embeddings, defaults to DEFAULT_MODEL
+      # @param args [Hash] optional arguments like read_timeout and open_timeout
+      # @return [Array<Float>] the generated embedding vector
+      # @raise [APIKeyNotConfiguredError] if the API key is not set
+      # @raise [RuntimeError] for general API errors or unexpected issues
+      def self.create(text, model: DEFAULT_MODEL, **args)
+        cfg = Spectre.openrouter_configuration
+        api_key = cfg&.api_key
+        raise APIKeyNotConfiguredError, 'API key is not configured' unless api_key
+
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = args.fetch(:read_timeout, DEFAULT_TIMEOUT)
+        http.open_timeout = args.fetch(:open_timeout, DEFAULT_TIMEOUT)
+
+        headers = {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        }
+        headers['HTTP-Referer'] = cfg.referer if cfg.respond_to?(:referer) && cfg.referer
+        headers['X-Title'] = cfg.app_title if cfg.respond_to?(:app_title) && cfg.app_title
+
+        request = Net::HTTP::Post.new(uri.path, headers)
+        request.body = { model: model, input: text }.to_json
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "OpenRouter API Error: #{response.code} - #{response.message}: #{response.body}"
+        end
+
+        JSON.parse(response.body).dig('data', 0, 'embedding')
+      rescue JSON::ParserError => e
+        raise "JSON Parse Error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/spectre/openrouter.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Openrouter
+    # Require each specific client file here
+    require_relative 'openrouter/embeddings'
+    require_relative 'openrouter/completions'
+  end
+end

data/lib/spectre/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spectre # :nodoc:all
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/spectre.rb

@@ -7,6 +7,7 @@ require "spectre/openai"
 require "spectre/ollama"
 require "spectre/claude"
 require "spectre/gemini"
+require "spectre/openrouter"
 require "spectre/logging"
 require 'spectre/prompt'
 require 'spectre/errors'
@@ -16,8 +17,8 @@ module Spectre
     openai: Spectre::Openai,
     ollama: Spectre::Ollama,
     claude: Spectre::Claude,
-    gemini: Spectre::Gemini
-    # cohere: Spectre::Cohere,
+    gemini: Spectre::Gemini,
+    openrouter: Spectre::Openrouter
   }.freeze
 
   def self.included(base)
@@ -66,6 +67,11 @@ module Spectre
       yield @providers[:gemini] if block_given?
     end
 
+    def openrouter
+      @providers[:openrouter] ||= OpenrouterConfiguration.new
+      yield @providers[:openrouter] if block_given?
+    end
+
     def provider_configuration
       providers[default_llm_provider] || raise("No configuration found for provider: #{default_llm_provider}")
     end
@@ -87,6 +93,11 @@ module Spectre
     attr_accessor :api_key
   end
 
+  class OpenrouterConfiguration
+    # OpenRouter additionally recommends setting Referer and X-Title headers
+    attr_accessor :api_key, :referer, :app_title
+  end
+
   class << self
     attr_accessor :config
 
@@ -120,6 +131,10 @@ module Spectre
       config.providers[:gemini]
     end
 
+    def openrouter_configuration
+      config.providers[:openrouter]
+    end
+
     private
 
     def validate_llm_provider!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spectre_ai
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ilya Klapatok
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-24 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails
@@ -67,6 +67,9 @@ files:
 - lib/spectre/openai.rb
 - lib/spectre/openai/completions.rb
 - lib/spectre/openai/embeddings.rb
+- lib/spectre/openrouter.rb
+- lib/spectre/openrouter/completions.rb
+- lib/spectre/openrouter/embeddings.rb
 - lib/spectre/prompt.rb
 - lib/spectre/searchable.rb
 - lib/spectre/version.rb