spectre_ai 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '03910c4dd38bf7a272fab91c0e9d1431d0f9bdc593abe62035271e9e07f22e89'
-  data.tar.gz: 0f1e927a42785d2f4735e4adf9140efad6815247fca6ce6270ac10ef286ae217
+  metadata.gz: 83d3a297e011e019679dcb12edb0c00f3bb73c6dc599378923627ef257ff6f1f
+  data.tar.gz: 79def4a06049ed718bf0c66ffc7f0a29016d8a0831ab0941cc9c02f0b451ab03
 SHA512:
-  metadata.gz: 48e634fedb903de30ff0acba0b1de5b725fccb2ac0882bf8890740100312c92ae48c6c182612554cdd6968b34df5f6c7958a62caf19492ae29a42d8e084e1458
-  data.tar.gz: b7a382fb583431eff8715147df8f5251e30d528b0a77ecc6c2ecf68b324f57f76e9c6a2634da07f55159713d9cd58684e212b75fee7f5a7e20e56b437725dd55
+  metadata.gz: 18cea546ff80840b1cb6087b35305a6efdf17fd8c6b6bea565157336958b02105822bb5725d7bb8e23a170362105506143992feb52ba6834986ced9fe87ab21d
+  data.tar.gz: 2397f388fbab927a41b959c92364f2cbbc50e8d6cebe1ed4a0ea33b631fa0d2e635687d349f523d5f20d88f414d176f9b297163337ed3632232cb520f04040f9

data/CHANGELOG.md

@@ -280,3 +280,146 @@ 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.
+  
+# Changelog for Version 2.1.1
+
+**Release Date:** [15th Dec 2025]
+
+### Enhancements: Extra generation options for Completions
+
+- You can now pass additional generation options (e.g., `temperature`, `top_p`, `presence_penalty`) directly as keyword arguments to all `Completions.create` methods.
+- For OpenAI, OpenRouter, Gemini, and Claude these extra kwargs are forwarded into the request body automatically.
+- For Ollama, pass extra kwargs at the top level just like other providers. Spectre maps them into `body[:options]` internally (including `max_tokens`). The legacy `ollama: { options: ... }` is now ignored.
+
+### Notes and exclusions
+
+- Control/network keys are not forwarded: `read_timeout`, `open_timeout`.
+- `max_tokens` remains supported:
+  - OpenAI/OpenRouter/Gemini/Claude: stays a top‑level request body field.
+  - Ollama: forwarded into `:options` along with other generation kwargs.
+- Claude: `tool_choice` is NOT auto‑forwarded from extra kwargs; pass it explicitly via the dedicated parameter if needed.
+
+### Examples
+
+```ruby
+# OpenAI
+Spectre::Openai::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'gpt-4o-mini',
+  temperature: 0.1,
+  top_p: 0.9,
+  max_tokens: 512
+)
+
+# OpenRouter
+Spectre::Openrouter::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'openai/gpt-4o-mini',
+  temperature: 0.1,
+  presence_penalty: 0.2,
+  max_tokens: 256
+)
+
+# Gemini (OpenAI‑compatible endpoint)
+Spectre::Gemini::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'gemini-2.5-flash',
+  temperature: 0.1,
+  max_tokens: 256
+)
+
+# Claude
+Spectre::Claude::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'claude-opus-4-1',
+  temperature: 0.1,
+  max_tokens: 512,
+  tool_choice: { type: 'auto' } # pass explicitly when needed
+)
+
+# Ollama — pass options at top level; Spectre maps them to body[:options]
+Spectre::Ollama::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'llama3.1:8b',
+  temperature: 0.1,
+  max_tokens: 256,   # forwarded into body[:options]
+  path: 'api/chat'   # optional: override endpoint path
+)
+## Note: `ollama: { options: ... }` is ignored; use top-level kwargs instead.
+```
+  - Request body formation (max_tokens, tools, response_format.json_schema).
+
+### OpenRouter: Plugins support in chat completions
+
+- Added pass-through support for OpenRouter Plugins in chat completions.
+- You can pass the `plugins` array directly to `Spectre::Openrouter::Completions.create`, and it will be included in the request body.
+
+Example:
+
+```ruby
+Spectre::Openrouter::Completions.create(
+  messages: [ { role: 'user', content: 'Heal my response if needed' } ],
+  model: 'openai/gpt-4o-mini',
+  plugins: [ { id: 'response-healing' } ],
+  temperature: 0.2,
+  max_tokens: 256
+)
+```
+
+Docs: https://openrouter.ai/docs/guides/features/plugins/overview
+
+### 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/README.md

@@ -224,6 +224,78 @@ Spectre.provider_module::Completions.create(
 
 ```
 
+#### Passing extra generation options (temperature, top_p, etc.)
+
+You can pass common generation options directly as keyword arguments to `Completions.create`.
+
+- OpenAI/OpenRouter/Gemini/Claude: extra kwargs are forwarded into the request body (e.g., `temperature`, `top_p`, `presence_penalty`).
+- Ollama: pass extra kwargs the same way (top-level). Spectre will put them into `body[:options]` internally (including `max_tokens`). The `ollama: { options: ... }` hash is no longer used.
+- Excluded control keys: `read_timeout`, `open_timeout` are never forwarded.
+- Provider differences for `max_tokens`:
+  - OpenAI/OpenRouter/Gemini/Claude: `max_tokens` is a top‑level field in the request body.
+  - Ollama: `max_tokens` is forwarded into `body[:options]`.
+- Claude: `tool_choice` is not auto‑forwarded; provide it explicitly via the `tool_choice:` parameter when needed.
+
+Examples:
+
+```ruby
+# OpenAI
+Spectre::Openai::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'gpt-4o-mini',
+  temperature: 0.1,
+  top_p: 0.9,
+  max_tokens: 512
+)
+
+# OpenRouter
+Spectre::Openrouter::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'openai/gpt-4o-mini',
+  temperature: 0.1,
+  presence_penalty: 0.2,
+  max_tokens: 256
+)
+
+# OpenRouter with Plugins
+# Docs: https://openrouter.ai/docs/guides/features/plugins/overview
+Spectre::Openrouter::Completions.create(
+  messages: [ { role: 'user', content: 'Heal my response if needed' } ],
+  model: 'openai/gpt-4o-mini',
+  plugins: [ { id: 'response-healing' } ],
+  temperature: 0.2,
+  max_tokens: 256
+)
+
+# Gemini (OpenAI‑compatible endpoint)
+Spectre::Gemini::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'gemini-2.5-flash',
+  temperature: 0.1,
+  max_tokens: 256
+)
+
+# Claude
+Spectre::Claude::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'claude-opus-4-1',
+  temperature: 0.1,
+  max_tokens: 512,
+  tool_choice: { type: 'auto' } # pass explicitly when needed
+)
+
+# Ollama — pass options at top level (Spectre maps them to body[:options])
+Spectre::Ollama::Completions.create(
+  messages: [ { role: 'user', content: 'Hi' } ],
+  model: 'llama3.1:8b',
+  temperature: 0.1,      # forwarded into body[:options]
+  max_tokens: 256,       # forwarded into body[:options]
+  path: 'api/chat'       # optional: override endpoint path
+)
+
+# Note: `ollama: { options: ... }` is ignored; use top-level kwargs instead.
+```
+
 **Using a JSON Schema for Structured Output**
 
 For cases where you need structured output (e.g., for returning specific fields or formatted responses), you can pass a `json_schema` parameter. The schema ensures that the completion conforms to a predefined structure:

data/lib/spectre/claude/completions.rb

@@ -21,7 +21,8 @@ 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.
+      #   Any additional kwargs (e.g., temperature:, top_p:) will be forwarded into the request body.
       # @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,8 +44,10 @@ module Spectre
           'anthropic-version' => ANTHROPIC_VERSION
         })
 
-        max_tokens = args.dig(:claude, :max_tokens) || 1024
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools, tool_choice).to_json
+        max_tokens = args[:max_tokens] || 1024
+        # Forward extra args (like temperature) into the body, excluding control/network keys
+        forwarded = args.reject { |k, _| [:read_timeout, :open_timeout, :max_tokens, :tool_choice].include?(k) }
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools, tool_choice, forwarded).to_json
         response = http.request(request)
 
         unless response.is_a?(Net::HTTPSuccess)
@@ -83,7 +86,7 @@ module Spectre
       # @param max_tokens [Integer] The maximum number of tokens for the completion
       # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
       # @return [Hash] The body for the API request
-      def self.generate_body(messages, model, json_schema, max_tokens, tools, tool_choice)
+      def self.generate_body(messages, model, json_schema, max_tokens, tools, tool_choice, forwarded)
         system_prompts, chat_messages = partition_system_and_chat(messages)
 
         body = {
@@ -125,6 +128,11 @@ module Spectre
         body[:tools] = tools if tools && !body.key?(:tools)
         body[:tool_choice] = tool_choice if tool_choice
 
+        # Merge any extra forwarded options (e.g., temperature, top_p)
+        if forwarded && !forwarded.empty?
+          body.merge!(forwarded.transform_keys(&:to_sym))
+        end
+
         body
       end
 

data/lib/spectre/gemini/completions.rb

@@ -18,7 +18,8 @@ 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.
+      #   Any additional kwargs (e.g., temperature:, top_p:) will be forwarded into the request body.
       # @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,8 +40,10 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        max_tokens = args.dig(:gemini, :max_tokens)
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
+        max_tokens = args[:max_tokens]
+        # Forward extra args (like temperature) into the body, excluding control/network keys
+        forwarded = args.reject { |k, _| [:read_timeout, :open_timeout, :max_tokens].include?(k) }
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools, forwarded).to_json
         response = http.request(request)
 
         unless response.is_a?(Net::HTTPSuccess)
@@ -75,7 +78,7 @@ module Spectre
       end
 
       # Helper method to generate the request body (OpenAI-compatible)
-      def self.generate_body(messages, model, json_schema, max_tokens, tools)
+      def self.generate_body(messages, model, json_schema, max_tokens, tools, forwarded)
         body = {
           model: model,
           messages: messages
@@ -85,6 +88,11 @@ module Spectre
         body[:response_format] = { type: 'json_schema', json_schema: json_schema } if json_schema
         body[:tools] = tools if tools
 
+        # Merge any extra forwarded options (e.g., temperature, top_p)
+        if forwarded && !forwarded.empty?
+          body.merge!(forwarded.transform_keys(&:to_sym))
+        end
+
         body
       end
 

data/lib/spectre/ollama/completions.rb

@@ -17,9 +17,9 @@ 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. You can pass in the ollama hash to specify the path and options.
-      # @param args.ollama.path [String, nil] The path to the Ollama API endpoint, defaults to API_PATH
-      # @param args.ollama.options [Hash, nil] Additional model parameters listed in the documentation for the https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values such as temperature
+      # @param args [Hash, nil] optional arguments like read_timeout and open_timeout.
+      #   Any additional top-level kwargs (e.g., temperature:, max_tokens:) will be forwarded into body[:options], same as other providers forward into body.
+      # @param path [String, nil] Top-level path override for the Ollama API endpoint, defaults to API_PATH
       # @return [Hash] The parsed response including any function calls or content
       # @raise [HostNotConfiguredError] If the API host is not set in the provider configuration.
       # @raise [APIKeyNotConfiguredError] If the API key is not set
@@ -32,7 +32,7 @@ module Spectre
 
         validate_messages!(messages)
 
-        path = args.dig(:ollama, :path) || API_PATH
+        path = args[:path] || API_PATH
         uri = URI.join(api_host, path)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true if uri.scheme == 'https'
@@ -44,7 +44,13 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        options = args.dig(:ollama, :options)
+        # Forward extra top-level args (like temperature, max_tokens) into body[:options],
+        # excluding control/network keys and the request path override.
+        forwarded = args.reject { |k, _| [:read_timeout, :open_timeout, :path].include?(k) }
+        options = nil
+        if forwarded && !forwarded.empty?
+          options = forwarded.transform_keys(&:to_sym)
+        end
         request.body = generate_body(messages, model, json_schema, tools, options).to_json
         response = http.request(request)
 

data/lib/spectre/openai/completions.rb

@@ -17,7 +17,8 @@ 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.
+      #   Any additional kwargs (e.g., temperature:, top_p:) will be forwarded into the request body.
       # @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,8 +39,10 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        max_tokens = args.dig(:openai, :max_tokens)
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
+        max_tokens = args[:max_tokens]
+        # Forward extra args (like temperature) into the body, excluding control/network keys
+        forwarded = args.reject { |k, _| [:read_timeout, :open_timeout, :max_tokens].include?(k) }
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools, forwarded).to_json
         response = http.request(request)
 
         unless response.is_a?(Net::HTTPSuccess)
@@ -82,7 +85,7 @@ module Spectre
       # @param max_tokens [Integer, nil] The maximum number of tokens for the completion
       # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
       # @return [Hash] The body for the API request
-      def self.generate_body(messages, model, json_schema, max_tokens, tools)
+      def self.generate_body(messages, model, json_schema, max_tokens, tools, forwarded)
         body = {
           model: model,
           messages: messages
@@ -92,6 +95,11 @@ module Spectre
         body[:response_format] = { type: 'json_schema', json_schema: json_schema } if json_schema
         body[:tools] = tools if tools # Add the tools to the request body if provided
 
+        # Merge any extra forwarded options (e.g., temperature, top_p)
+        if forwarded && !forwarded.empty?
+          body.merge!(forwarded.transform_keys(&:to_sym))
+        end
+
         body
       end
 

data/lib/spectre/openrouter/completions.rb

@@ -0,0 +1,113 @@
+# 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.
+      #   Any additional kwargs (e.g., temperature:, top_p:) will be forwarded into the request body.
+      # @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]
+        # Forward extra args into body, excluding control/network keys
+        forwarded = args.reject { |k, _| [:read_timeout, :open_timeout, :max_tokens].include?(k) }
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools, forwarded).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, forwarded)
+        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
+        if forwarded && !forwarded.empty?
+          body.merge!(forwarded.transform_keys(&:to_sym))
+        end
+        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.1"
 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.1
 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-12-15 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