spectre_ai 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a0cd0a25dd4345c62af319d8669a3702ce2e505299c01fbf43e4a94cb3b3109
-  data.tar.gz: 544e5bb1462d2d9477601d6a581d455a30e5b0a5f107ec1264608c0f9b713307
+  metadata.gz: 83d3a297e011e019679dcb12edb0c00f3bb73c6dc599378923627ef257ff6f1f
+  data.tar.gz: 79def4a06049ed718bf0c66ffc7f0a29016d8a0831ab0941cc9c02f0b451ab03
 SHA512:
-  metadata.gz: cdb1062a23c35d4df2ca354eeff42ebd28b5d2ddef3a710ee032917a5a1bad811645f61dc8d5e5914b2fc16cd319768a3bd6ec84f3e9bc4ed50c22af1a073855
-  data.tar.gz: ecca27c2bd3f7ada23f744dd93017b488fbf193652b1bbdf5c3f47110bfd7ae7c042a66398d53592bc3c59d79031c0f46987b12551ebc1b4f1923f215efa55ce
+  metadata.gz: 18cea546ff80840b1cb6087b35305a6efdf17fd8c6b6bea565157336958b02105822bb5725d7bb8e23a170362105506143992feb52ba6834986ced9fe87ab21d
+  data.tar.gz: 2397f388fbab927a41b959c92364f2cbbc50e8d6cebe1ed4a0ea33b631fa0d2e635687d349f523d5f20d88f414d176f9b297163337ed3632232cb520f04040f9

data/CHANGELOG.md

@@ -308,8 +308,94 @@ Key Benefits:\
 - 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:
@@ -336,3 +422,4 @@ Key Benefits:\
   ```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

@@ -22,6 +22,7 @@ module Spectre
       # @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. 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
@@ -44,7 +45,9 @@ module Spectre
         })
 
         max_tokens = args[:max_tokens] || 1024
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools, tool_choice).to_json
+        # 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

@@ -19,6 +19,7 @@ module Spectre
       # @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. 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
@@ -40,7 +41,9 @@ module Spectre
         })
 
         max_tokens = args[:max_tokens]
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
+        # 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

@@ -18,6 +18,7 @@ module Spectre
       # @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. 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,7 +40,9 @@ module Spectre
         })
 
         max_tokens = args[:max_tokens]
-        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
+        # 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

@@ -18,6 +18,7 @@ module Spectre
       # @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
@@ -44,7 +45,9 @@ module Spectre
         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
+        # 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)
@@ -66,7 +69,7 @@ module Spectre
         raise ArgumentError, 'Messages cannot be empty.' if messages.empty?
       end
 
-      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
@@ -74,6 +77,9 @@ module Spectre
         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
 

data/lib/spectre/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spectre_ai
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Ilya Klapatok
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-13 00:00:00.000000000 Z
+date: 2025-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails