spectre_ai 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68106b39f46d2b4069e560eb8e51dcc64ed005a05d9f062919db94e628c2c5f4
-  data.tar.gz: c35b62f8f973763c2029620a0b4608e0dd15591c991e9a13b91d427e2b5dddd7
+  metadata.gz: 2a0cd0a25dd4345c62af319d8669a3702ce2e505299c01fbf43e4a94cb3b3109
+  data.tar.gz: 544e5bb1462d2d9477601d6a581d455a30e5b0a5f107ec1264608c0f9b713307
 SHA512:
-  metadata.gz: 7c4632584286d800799a66a1b5ac2f2c5dbb6a9c35597f6c1256dffa94a9f228c2c0ff5aa1a30170a1aae93d9d26cbad42df55297468b853471a3559aa72c69a
-  data.tar.gz: 998ab9f6d356b9f3f9cc404260ea931c35a4e80abb2b6b5f9da1757fbdbc39365bfc0041c9a9ae934f97c954d66fa9ffc8c75a8d66b4228cf5db3f26972bd2e0
+  metadata.gz: cdb1062a23c35d4df2ca354eeff42ebd28b5d2ddef3a710ee032917a5a1bad811645f61dc8d5e5914b2fc16cd319768a3bd6ec84f3e9bc4ed50c22af1a073855
+  data.tar.gz: ecca27c2bd3f7ada23f744dd93017b488fbf193652b1bbdf5c3f47110bfd7ae7c042a66398d53592bc3c59d79031c0f46987b12551ebc1b4f1923f215efa55ce

data/CHANGELOG.md

@@ -198,3 +198,141 @@ Key Benefits:\
 ✅ Keeps the method signature cleaner and future-proof.\
 ✅ Ensures optional parameters are handled dynamically without cluttering the main method signature.\
 ✅ Improves consistency across OpenAI and Ollama providers.
+
+
+# Changelog for Version 2.0.0
+
+**Release Date:** [21st Sep 2025]
+
+### New Provider: Claude (Anthropic)
+
+- Added Spectre::Claude client for chat completions using Anthropic Messages API.
+- New configuration block: `Spectre.setup { |c| c.default_llm_provider = :claude; c.claude { |v| v.api_key = ENV['ANTHROPIC_API_KEY'] } }`.
+- Supports `claude: { max_tokens: ... }` in args to control max tokens.
+
+### Structured Outputs via Tools-based JSON Schema
+
+- Claude does not use `response_format`; instead, when `json_schema` is provided we now:
+  - Convert your schema into a single “virtual” tool (`tools[0]`) with `input_schema`.
+  - Force use of that tool by default with `tool_choice: { type: 'tool', name: <schema_name> }` (respects explicit `tool_choice` if you pass one).
+  - Merge your own `tools` alongside the schema tool without overriding them.
+- Messages content preserves structured blocks (hashes/arrays), enabling images and other block types to be sent as-is.
+
+### Output Normalization (Parity with OpenAI when using json_schema)
+
+- When a `json_schema` is provided and Claude returns a single `tool_use` with no text, we normalize the output to:
+  - `content: <parsed_object>` (Hash/Array), not a JSON string.
+  - This mirrors the behavior you get with OpenAI’s JSON schema mode, simplifying consumers.
+- When no `json_schema` is provided, we return `tool_calls` (raw `tool_use` blocks) plus any text content.
+
+### Error Handling & Stop Reasons
+
+- `stop_reason: 'max_tokens'` → raises `"Incomplete response: The completion was cut off due to token limit."`
+- `stop_reason: 'refusal'` → raises `Spectre::Claude::RefusalError`.
+- Unexpected stop reasons raise an error to make issues explicit.
+
+### Tools and tool_choice Support
+
+- Pass-through for user-defined tools.
+- Respect explicit `tool_choice`; only enforce schema tool when `json_schema` is present and no explicit choice is set.
+
+### Tests & DX
+
+- Added a comprehensive RSpec suite for `Spectre::Claude::Completions`.
+- Ensured spec loading works consistently across environments via `.rspec --require spec_helper` and consistent requires.
+- Full suite passes locally (69 examples).
+
+### Notes
+
+- Claude embeddings are not implemented (no native embeddings model).
+- Behavior change (Claude only): when `json_schema` is used, `:content` returns a parsed object (not a JSON string). If you relied on a string, wrap with `JSON.generate` on the caller side.
+
+
+
+# Changelog for Version 2.0.0
+
+**Release Date:** [21st Sep 2025]
+
+### New Provider: Gemini (Google)
+
+- Added Spectre::Gemini client for chat completions using Google’s OpenAI-compatible endpoint.
+- Added Spectre::Gemini embeddings using Google’s OpenAI-compatible endpoint.
+- New configuration block:
+  ```ruby
+  Spectre.setup do |c|
+    c.default_llm_provider = :gemini
+    c.gemini { |v| v.api_key = ENV['GEMINI_API_KEY'] }
+  end
+  ```
+- Supports `gemini: { max_tokens: ... }` in args to control max tokens for completions.
+- `json_schema` and `tools` are passed through in OpenAI-compatible format.
+
+### Core Wiring
+
+- Added `:gemini` to VALID_LLM_PROVIDERS and provider configuration accessors.
+- Updated Rails generator initializer template to include a gemini block.
+
+### Docs & Tests
+
+- Updated README to include Gemini in compatibility matrix and configuration example.
+- Added RSpec tests for Gemini completions and embeddings (mirroring OpenAI behavior and error handling).
+
+### 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/README.md

@@ -6,14 +6,14 @@
 
 ## Compatibility
 
-| Feature                 | Compatibility  |
-|-------------------------|----------------|
-| Foundation Models (LLM) | OpenAI, Ollama |
-| Embeddings              | OpenAI, Ollama |
-| Vector Searching        | MongoDB Atlas  |
-| Prompt Templates        | ✅            |
+| Feature                 | Compatibility          |
+|-------------------------|------------------------|
+| Foundation Models (LLM) | OpenAI, Ollama, Claude, Gemini |
+| Embeddings              | OpenAI, Ollama, Gemini         |
+| Vector Searching        | MongoDB Atlas          |
+| Prompt Templates        | ✅                      |
 
-**💡 Note:** We will first prioritize adding support for additional foundation models (Claude, Cohere, etc.), then look to add support for more vector databases (Pgvector, Pinecone, etc.). If you're looking for something a bit more extensible, we highly recommend checking out [langchainrb](https://github.com/patterns-ai-core/langchainrb).
+**💡 Note:** We now support OpenAI, Ollama, Claude, and Gemini. Next, we'll add support for additional providers (e.g., Cohere) and more vector databases (Pgvector, Pinecone, etc.). If you're looking for something a bit more extensible, we highly recommend checking out [langchainrb](https://github.com/patterns-ai-core/langchainrb).
 
 ## Installation
 
@@ -49,7 +49,7 @@ This will create a file at `config/initializers/spectre.rb`, where you can set y
 
 ```ruby
 Spectre.setup do |config|
-  config.default_llm_provider = :openai
+  config.default_llm_provider = :openai # or :claude, :ollama, :gemini
 
   config.openai do |openai|
     openai.api_key = ENV['OPENAI_API_KEY']
@@ -59,6 +59,14 @@ Spectre.setup do |config|
     ollama.host = ENV['OLLAMA_HOST']
     ollama.api_key = ENV['OLLAMA_API_KEY']
   end
+
+  config.claude do |claude|
+    claude.api_key = ENV['ANTHROPIC_API_KEY']
+  end
+
+  config.gemini do |gemini|
+    gemini.api_key = ENV['GEMINI_API_KEY']
+  end
 end
 ```
 
@@ -248,8 +256,76 @@ Spectre.provider_module::Completions.create(
 
 This structured format guarantees that the response adheres to the schema you’ve provided, ensuring more predictable and controlled results.
 
-**NOTE:** The JSON schema is different for each provider. OpenAI uses [JSON Schema](https://json-schema.org/overview/what-is-jsonschema.html), where you can specify the name of schema and schema itself. Ollama uses just plain JSON object. 
-But you can provide OpenAI's schema to Ollama as well. We just convert it to Ollama's format.
+**NOTE:** Provider differences for structured output:
+- OpenAI: supports strict JSON Schema via `response_format.json_schema` (see JSON Schema docs: https://json-schema.org/overview/what-is-jsonschema.html).
+- Claude (Anthropic): does not use `response_format`. Spectre converts your `json_schema` into a single "virtual" tool with `input_schema` and, by default, forces its use via `tool_choice` (you can override `tool_choice` explicitly). When the reply consists only of that `tool_use`, Spectre returns the parsed object in `:content` (Hash/Array), not a JSON string.
+- Ollama: expects a plain JSON object in `format`. Spectre will convert OpenAI-style `{ name:, schema: }` automatically into the format Ollama expects.
+
+#### Claude (Anthropic) specifics
+
+- Configure:
+```ruby
+Spectre.setup do |config|
+  config.default_llm_provider = :claude
+  config.claude { |c| c.api_key = ENV['ANTHROPIC_API_KEY'] }
+end
+```
+
+- Structured output with a schema:
+```ruby
+json_schema = {
+  name: "completion_response",
+  schema: {
+    type: "object",
+    properties: { response: { type: "string" } },
+    required: ["response"],
+    additionalProperties: false
+  }
+}
+
+messages = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Say hello' }
+]
+
+result = Spectre.provider_module::Completions.create(
+  messages: messages,
+  json_schema: json_schema,
+  claude: { max_tokens: 256 }
+)
+
+# When only the schema tool is used, Spectre returns a parsed object:
+result[:content] # => { 'response' => 'Hello!' }
+```
+
+- Optional: override tool selection
+```ruby
+Spectre.provider_module::Completions.create(messages: messages, json_schema: json_schema, tool_choice: { type: 'auto' })
+```
+
+- Note: Claude embeddings are not implemented (no native embeddings model).
+
+#### Gemini (Google) specifics
+
+- Chat completions use Google's OpenAI-compatible endpoint. Important: the messages array must end with a user message. If the last message is assistant/system or missing, the API returns 400 INVALID_ARGUMENT (e.g., "Please ensure that single turn requests end with a user role or the role field is empty."). Spectre validates this and raises an ArgumentError earlier to help you fix the history before making an API call.
+- Example:
+
+```ruby
+# Incorrect (ends with assistant)
+messages = [
+  { role: 'system', content: 'You are a funny assistant.' },
+  { role: 'user', content: 'Tell me a joke.' },
+  { role: 'assistant', content: "Sure, here's a joke!" }
+]
+
+# Correct (ends with user)
+messages = [
+  { role: 'system', content: 'You are a funny assistant.' },
+  { role: 'user', content: 'Tell me a joke.' },
+  { role: 'assistant', content: "Sure, here's a joke!" },
+  { role: 'user', content: 'Tell me another one.' }
+]
+```
 
 ⚙️ Function Calling (Tool Use)
 

data/lib/generators/spectre/templates/spectre_initializer.rb

@@ -3,7 +3,7 @@
 require 'spectre'
 
 Spectre.setup do |config|
-  # Chose your LLM (openai, ollama)
+  # Chose your LLM (openai, ollama, claude, gemini)
   config.default_llm_provider = :openai
 
   config.openai do |openai|
@@ -14,4 +14,12 @@ Spectre.setup do |config|
     ollama.host = ENV['OLLAMA_HOST']
     ollama.api_key = ENV['OLLAMA_API_KEY']
   end
+
+  config.claude do |claude|
+    claude.api_key = ENV['ANTHROPIC_API_KEY']
+  end
+
+  config.gemini do |gemini|
+    gemini.api_key = ENV['GEMINI_API_KEY']
+  end
 end

data/lib/spectre/claude/completions.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Claude
+    class RefusalError < StandardError; end
+
+    class Completions
+      API_URL = 'https://api.anthropic.com/v1/messages'
+      DEFAULT_MODEL = 'claude-opus-4-1'
+      DEFAULT_TIMEOUT = 60
+      ANTHROPIC_VERSION = '2023-06-01'
+
+      # Class method to 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, defaults to DEFAULT_MODEL
+      # @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. 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, tool_choice: nil, **args)
+        api_key = Spectre.claude_configuration&.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)
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'x-api-key' => api_key,
+          'anthropic-version' => ANTHROPIC_VERSION
+        })
+
+        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)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "Claude API Error: #{response.code} - #{response.message}: #{response.body}"
+        end
+
+        parsed_response = JSON.parse(response.body)
+
+        handle_response(parsed_response, schema_used: !!json_schema)
+      rescue JSON::ParserError => e
+        raise "JSON Parse Error: #{e.message}"
+      end
+
+      private
+
+      # Validate the structure and content of the messages array.
+      #
+      # @param messages [Array<Hash>] The array of message hashes to validate.
+      #
+      # @raise [ArgumentError] if the messages array is not in the expected format or contains invalid data.
+      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
+
+        if messages.empty?
+          raise ArgumentError, "Messages cannot be empty."
+        end
+      end
+
+      # Helper method to generate the request body for Anthropic Messages API
+      #
+      # @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 hint structured output
+      # @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)
+        system_prompts, chat_messages = partition_system_and_chat(messages)
+
+        body = {
+          model: model,
+          max_tokens: max_tokens,
+          messages: chat_messages
+        }
+
+        # Join multiple system prompts into one. Anthropic supports a string here.
+        body[:system] = system_prompts.join("\n\n") unless system_prompts.empty?
+
+        # If a json_schema is provided, transform it into a "virtual" tool and force its use via tool_choice (unless already provided).
+        if json_schema
+          # Normalize schema input: accept anthropic-style { json_schema: { name:, schema:, strict: } },
+          # OpenAI-like { name:, schema:, strict: }, or a raw schema object.
+          if json_schema.is_a?(Hash) && (json_schema.key?(:json_schema) || json_schema.key?("json_schema"))
+            schema_payload = json_schema[:json_schema] || json_schema["json_schema"]
+            schema_name = (schema_payload[:name] || schema_payload["name"] || "structured_output").to_s
+            schema_object = schema_payload[:schema] || schema_payload["schema"] || schema_payload
+          else
+            schema_name = (json_schema.is_a?(Hash) && (json_schema[:name] || json_schema["name"])) || "structured_output"
+            schema_object = (json_schema.is_a?(Hash) && (json_schema[:schema] || json_schema["schema"])) || json_schema
+          end
+
+          schema_tool = {
+            name: schema_name,
+            description: "Return a JSON object that strictly follows the provided input_schema.",
+            input_schema: schema_object
+          }
+
+          # Merge with any user-provided tools. Prefer a single tool by default but don't drop existing tools.
+          existing_tools = tools || []
+          body[:tools] = [schema_tool] + existing_tools
+
+          # If the caller didn't specify tool_choice, force using the schema tool.
+          body[:tool_choice] = { type: 'tool', name: schema_name } unless tool_choice
+        end
+
+        body[:tools] = tools if tools && !body.key?(:tools)
+        body[:tool_choice] = tool_choice if tool_choice
+
+        body
+      end
+
+      # Normalize content for Anthropic: preserve arrays/hashes (structured blocks), stringify otherwise
+      def self.normalize_content(content)
+        case content
+        when Array
+          content
+        when Hash
+          content
+        else
+          content.to_s
+        end
+      end
+
+      # Partition system messages and convert remaining into Anthropic-compatible messages
+      def self.partition_system_and_chat(messages)
+        system_prompts = []
+        chat_messages = []
+
+        messages.each do |msg|
+          role = (msg[:role] || msg['role']).to_s
+          content = msg[:content] || msg['content']
+
+          case role
+          when 'system'
+            system_prompts << content.to_s
+          when 'user', 'assistant'
+            chat_messages << { role: role, content: normalize_content(content) }
+          else
+            # Unknown role, treat as user to avoid API errors
+            chat_messages << { role: 'user', content: normalize_content(content) }
+          end
+        end
+
+        [system_prompts, chat_messages]
+      end
+
+      # Handles the API response, raising errors for specific cases and returning structured content otherwise
+      #
+      # @param response [Hash] The parsed API response
+      # @param schema_used [Boolean] Whether the request used a JSON schema (tools-based) and needs normalization
+      # @return [Hash] The relevant data based on the stop_reason
+      def self.handle_response(response, schema_used: false)
+        content_blocks = response['content'] || []
+        stop_reason = response['stop_reason']
+
+        text_content = content_blocks.select { |b| b['type'] == 'text' }.map { |b| b['text'] }.join
+        tool_uses = content_blocks.select { |b| b['type'] == 'tool_use' }
+
+        if stop_reason == 'max_tokens'
+          raise "Incomplete response: The completion was cut off due to token limit."
+        end
+
+        if stop_reason == 'refusal'
+          raise RefusalError, "Content filtered: The model's output was blocked due to policy violations."
+        end
+
+        # If a json_schema was provided and Claude produced a single tool_use with no text,
+        # treat it as structured JSON output and return the parsed object in :content.
+        if schema_used && tool_uses.length == 1 && (text_content.nil? || text_content.strip.empty?)
+          input = tool_uses.first['input']
+          return({ content: input }) if input.is_a?(Hash) || input.is_a?(Array)
+        end
+
+        if !tool_uses.empty?
+          return { tool_calls: tool_uses, content: text_content }
+        end
+
+        # Normal end of turn
+        if stop_reason == 'end_turn' || stop_reason.nil?
+          return { content: text_content }
+        end
+
+        # Handle unexpected stop reasons
+        raise "Unexpected stop_reason: #{stop_reason}"
+      end
+    end
+  end
+end

data/lib/spectre/claude.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Claude
+    # Require each specific client file here
+    require_relative 'claude/completions'
+  end
+end

data/lib/spectre/gemini/completions.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Gemini
+    class Completions
+      # Using Google's OpenAI-compatible endpoint
+      API_URL = 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions'
+      DEFAULT_MODEL = 'gemini-2.5-flash'
+      DEFAULT_TIMEOUT = 60
+
+      # Class method to 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, 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. 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
+      def self.create(messages:, model: DEFAULT_MODEL, json_schema: nil, tools: nil, **args)
+        api_key = Spectre.gemini_configuration&.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)
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        })
+
+        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 "Gemini 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
+
+      # Validate the structure and content of the messages array.
+      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
+
+        if messages.empty?
+          raise ArgumentError, "Messages cannot be empty."
+        end
+
+        # Gemini's OpenAI-compatible chat endpoint requires that single-turn
+        # and general requests end with a user message. If not, return a clear error.
+        last_role = (messages.last[:role] || messages.last['role']).to_s
+        unless last_role == 'user'
+          raise ArgumentError, "Gemini: the last message must have role 'user'. Got '#{last_role}'."
+        end
+      end
+
+      # Helper method to generate the request body (OpenAI-compatible)
+      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
+
+      # Handles the API response, mirroring OpenAI semantics
+      def self.handle_response(response)
+        message = response.dig('choices', 0, 'message')
+        finish_reason = response.dig('choices', 0, 'finish_reason')
+
+        if message && message['refusal']
+          raise "Refusal: #{message['refusal']}"
+        end
+
+        if finish_reason == 'length'
+          raise "Incomplete response: The completion was cut off due to token limit."
+        end
+
+        if finish_reason == 'content_filter'
+          raise "Content filtered: The model's output was blocked due to policy violations."
+        end
+
+        if finish_reason == 'function_call' || finish_reason == 'tool_calls'
+          return { tool_calls: message['tool_calls'], content: message['content'] }
+        end
+
+        if finish_reason == 'stop'
+          return { content: message['content'] }
+        end
+
+        raise "Unexpected finish_reason: #{finish_reason}"
+      end
+    end
+  end
+end

data/lib/spectre/gemini/embeddings.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Spectre
+  module Gemini
+    class Embeddings
+      # Using Google's OpenAI-compatible endpoint
+      API_URL = 'https://generativelanguage.googleapis.com/v1beta/openai/embeddings'
+      DEFAULT_MODEL = 'gemini-embedding-001'
+      DEFAULT_TIMEOUT = 60
+
+      # Generate embeddings for text
+      def self.create(text, model: DEFAULT_MODEL, **args)
+        api_key = Spectre.gemini_configuration&.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)
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{api_key}"
+        })
+
+        request.body = { model: model, input: text }.to_json
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "Gemini 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/gemini.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Spectre
+  module Gemini
+    require_relative 'gemini/completions'
+    require_relative 'gemini/embeddings'
+  end
+end

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 = "1.2.0"
+  VERSION = "2.1.0"
 end

data/lib/spectre.rb

@@ -5,6 +5,9 @@ require "spectre/embeddable"
 require 'spectre/searchable'
 require "spectre/openai"
 require "spectre/ollama"
+require "spectre/claude"
+require "spectre/gemini"
+require "spectre/openrouter"
 require "spectre/logging"
 require 'spectre/prompt'
 require 'spectre/errors'
@@ -12,8 +15,10 @@ require 'spectre/errors'
 module Spectre
   VALID_LLM_PROVIDERS = {
     openai: Spectre::Openai,
-    ollama: Spectre::Ollama
-    # cohere: Spectre::Cohere,
+    ollama: Spectre::Ollama,
+    claude: Spectre::Claude,
+    gemini: Spectre::Gemini,
+    openrouter: Spectre::Openrouter
   }.freeze
 
   def self.included(base)
@@ -52,6 +57,21 @@ module Spectre
       yield @providers[:ollama] if block_given?
     end
 
+    def claude
+      @providers[:claude] ||= ClaudeConfiguration.new
+      yield @providers[:claude] if block_given?
+    end
+
+    def gemini
+      @providers[:gemini] ||= GeminiConfiguration.new
+      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
@@ -65,6 +85,19 @@ module Spectre
     attr_accessor :host, :api_key
   end
 
+  class ClaudeConfiguration
+    attr_accessor :api_key
+  end
+
+  class GeminiConfiguration
+    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
 
@@ -90,6 +123,18 @@ module Spectre
       config.providers[:ollama]
     end
 
+    def claude_configuration
+      config.providers[:claude]
+    end
+
+    def gemini_configuration
+      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: 1.2.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ilya Klapatok
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails
@@ -53,8 +53,13 @@ files:
 - lib/generators/spectre/templates/rag/user.yml.erb
 - lib/generators/spectre/templates/spectre_initializer.rb
 - lib/spectre.rb
+- lib/spectre/claude.rb
+- lib/spectre/claude/completions.rb
 - lib/spectre/embeddable.rb
 - lib/spectre/errors.rb
+- lib/spectre/gemini.rb
+- lib/spectre/gemini/completions.rb
+- lib/spectre/gemini/embeddings.rb
 - lib/spectre/logging.rb
 - lib/spectre/ollama.rb
 - lib/spectre/ollama/completions.rb
@@ -62,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