ruby-spacy 0.4.0 → 0.5.0

data/lib/ruby-spacy/anthropic_helper.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Spacy
+  # A helper class for Anthropic (Claude) API interactions, designed to work
+  # with spaCy's linguistic analysis via the block-based {Language#with_llm} API.
+  #
+  # Provides the same chat interface as {OpenAIHelper}, so code written against
+  # one provider works with the other. Anthropic does not offer an embeddings
+  # API; use the :openai or :ollama provider for embeddings.
+  #
+  # @example Basic usage with linguistic_summary
+  #   nlp = Spacy::Language.new("en_core_web_sm")
+  #   nlp.with_llm(provider: :anthropic) do |ai|
+  #     doc = nlp.read("Apple Inc. was founded by Steve Jobs.")
+  #     ai.chat(system: "Analyze the linguistic data.", user: doc.linguistic_summary)
+  #   end
+  class AnthropicHelper
+    # @return [String] the default model for chat requests
+    attr_reader :model
+
+    # Creates a new AnthropicHelper instance.
+    # @param access_token [String, nil] Anthropic API key (defaults to ANTHROPIC_API_KEY env var)
+    # @param model [String] the default model for chat requests
+    # @param max_tokens [Integer] default maximum tokens in responses
+    # @param temperature [Float, nil] default sampling temperature (omitted from
+    #   requests when nil; models that reject it are retried without it)
+    # @param base_url [String, nil] API endpoint override
+    def initialize(access_token: nil, model: AnthropicClient::DEFAULT_MODEL,
+                   max_tokens: 1000, temperature: nil, base_url: nil)
+      @access_token = access_token || ENV["ANTHROPIC_API_KEY"]
+      raise "Error: ANTHROPIC_API_KEY is not set" unless @access_token
+
+      @model = model
+      @default_max_tokens = max_tokens
+      @default_temperature = temperature
+      @client = AnthropicClient.new(access_token: @access_token,
+                                    base_url: base_url || AnthropicClient::API_ENDPOINT)
+    end
+
+    # Sends a Messages API request.
+    #
+    # Provides convenient `system:` and `user:` keyword arguments as shortcuts.
+    # For multi-turn conversations, pass a full `messages:` array directly
+    # (the system prompt stays a separate `system:` argument — Anthropic takes
+    # it as a top-level parameter, not a message role).
+    #
+    # @param system [String, nil] system prompt
+    # @param user [String, nil] user message content (shortcut)
+    # @param messages [Array<Hash>, nil] full message array (overrides user:)
+    # @param model [String, nil] model override (defaults to instance model)
+    # @param max_tokens [Integer, nil] token limit override
+    # @param temperature [Float, nil] temperature override
+    # @param schema [Hash, nil] JSON Schema for structured outputs; when given,
+    #   the model output is constrained to the schema and the parsed Hash is
+    #   returned. Objects in the schema must set `additionalProperties: false`.
+    # @param raw [Boolean] if true, returns the full API response Hash instead of text
+    # @return [String, Hash, nil] the response text, parsed Hash (if schema:),
+    #   full response Hash (if raw:), or nil on API error, refusal, or when
+    #   the schema output cannot be parsed as JSON (e.g., truncated by the
+    #   token limit)
+    def chat(system: nil, user: nil, messages: nil,
+             model: nil, max_tokens: nil, temperature: nil,
+             schema: nil, raw: false)
+      msgs = messages || (user ? [{ role: "user", content: user }] : [])
+      raise ArgumentError, "No messages provided. Use user:/messages:" if msgs.empty?
+
+      output_config = schema ? { format: { type: "json_schema", schema: schema } } : nil
+
+      response = @client.messages(
+        model: model || @model,
+        messages: msgs,
+        system: system,
+        max_tokens: max_tokens || @default_max_tokens,
+        temperature: temperature || @default_temperature,
+        output_config: output_config
+      )
+
+      return response if raw
+
+      # Safety classifiers can decline a request with HTTP 200 and an empty
+      # or partial content array.
+      if response["stop_reason"] == "refusal"
+        warn "Error: Anthropic API declined the request (stop_reason: refusal)"
+        return nil
+      end
+
+      if response["stop_reason"] == "max_tokens"
+        warn "Warning: response was truncated (stop_reason: max_tokens); consider increasing max_tokens"
+      end
+
+      text = Array(response["content"])
+             .select { |block| block["type"] == "text" }
+             .map { |block| block["text"] }
+             .join
+      schema ? parse_json_content(text) : text
+    rescue AnthropicClient::APIError => e
+      warn "Error: Anthropic API call failed - #{e.message}"
+      nil
+    end
+
+    # Anthropic does not provide an embeddings API.
+    # @raise [NotImplementedError] always
+    def embeddings(*)
+      raise NotImplementedError,
+            "Anthropic does not provide an embeddings API. " \
+            "Use with_llm(provider: :openai) or a local OpenAI-compatible server for embeddings."
+    end
+
+    private
+
+    def parse_json_content(text)
+      JSON.parse(text)
+    rescue JSON::ParserError
+      warn "Error: response is not valid JSON (possibly truncated output); returning nil"
+      nil
+    end
+  end
+end

data/lib/ruby-spacy/llm_client_base.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "json"
+
+module Spacy
+  # Shared HTTP layer for LLM API clients ({OpenAIClient}, {AnthropicClient}).
+  # Implements JSON POST requests with retry on rate limits (429/529) and
+  # transient network errors, using only net/http (no external dependencies).
+  class LLMClientBase
+    # Default request timeout in seconds
+    DEFAULT_TIMEOUT = 120
+    # Maximum number of retries for rate-limited requests and network errors
+    MAX_RETRIES = 3
+    # Base delay in seconds for exponential backoff between retries
+    BASE_RETRY_DELAY = 1
+
+    # Raised when an LLM API request fails after retries; carries the HTTP
+    # status code and the parsed response body when available.
+    class APIError < StandardError
+      attr_reader :status_code, :response_body
+
+      def initialize(message, status_code: nil, response_body: nil)
+        @status_code = status_code
+        @response_body = response_body
+        super(message)
+      end
+    end
+
+    def initialize(base_url:, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.sub(%r{/\z}, "")
+      @timeout = timeout
+    end
+
+    private
+
+    # Subclasses provide authentication and API-specific headers.
+    # @return [Hash{String => String}]
+    def request_headers
+      {}
+    end
+
+    # Creates a certificate store with system CA certificates but without CRL checking.
+    # This avoids "unable to get certificate CRL" errors on some systems.
+    def default_cert_store
+      store = OpenSSL::X509::Store.new
+      store.set_default_paths
+      store
+    end
+
+    def post(path, body)
+      uri = URI.parse("#{@base_url}#{path}")
+      retries = 0
+
+      loop do
+        begin
+          http = Net::HTTP.new(uri.host, uri.port)
+          if uri.scheme == "https"
+            http.use_ssl = true
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            http.cert_store = default_cert_store
+          end
+          http.open_timeout = @timeout
+          http.read_timeout = @timeout
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request_headers.each { |key, value| request[key] = value }
+          request.body = body.to_json
+
+          response = http.request(request)
+
+          # Handle rate limiting (429) and overload (529) before general response handling
+          if [429, 529].include?(response.code.to_i)
+            retries += 1
+            if retries <= MAX_RETRIES
+              retry_after = response["Retry-After"]&.to_f
+              delay = retry_after || (BASE_RETRY_DELAY * (2**(retries - 1)) + rand * 0.5)
+              sleep delay
+              next
+            end
+            raise APIError.new("Rate limited after #{MAX_RETRIES} retries",
+                               status_code: response.code.to_i, response_body: response.body)
+          end
+
+          return handle_response(response)
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
+          retries += 1
+          if retries <= MAX_RETRIES
+            delay = BASE_RETRY_DELAY * (2**(retries - 1)) + rand * 0.5
+            sleep delay
+            next
+          end
+          raise APIError.new("Network error after #{MAX_RETRIES} retries: #{e.message}")
+        end
+      end
+    end
+
+    def handle_response(response)
+      body = JSON.parse(response.body)
+
+      case response.code.to_i
+      when 200
+        body
+      when 400..499
+        error_message = body.dig("error", "message") || "Client error"
+        raise APIError.new(error_message, status_code: response.code.to_i, response_body: body)
+      when 500..599
+        error_message = body.dig("error", "message") || "Server error"
+        raise APIError.new(error_message, status_code: response.code.to_i, response_body: body)
+      else
+        raise APIError.new("Unexpected response: #{response.code}", status_code: response.code.to_i, response_body: body)
+      end
+    rescue JSON::ParserError
+      raise APIError.new("Invalid JSON response", status_code: response.code.to_i, response_body: response.body)
+    end
+  end
+end

data/lib/ruby-spacy/openai_client.rb

@@ -1,42 +1,43 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "openssl"
-require "uri"
-require "json"
+require_relative "llm_client_base"
 
 module Spacy
-  # A lightweight OpenAI API client with tools support for GPT-5 series models.
+  # A lightweight OpenAI API client with tools support.
   # This client implements the chat completions and embeddings endpoints
   # without external dependencies.
-  class OpenAIClient
+  #
+  # A custom +base_url+ makes it work with any OpenAI-compatible server
+  # (Ollama, LM Studio, llama.cpp server, vLLM, OpenRouter, etc.).
+  class OpenAIClient < LLMClientBase
+    # Default OpenAI API endpoint
     API_ENDPOINT = "https://api.openai.com/v1"
-    DEFAULT_TIMEOUT = 120
-    MAX_RETRIES = 3
-    BASE_RETRY_DELAY = 1
-
-    class APIError < StandardError
-      attr_reader :status_code, :response_body
-
-      def initialize(message, status_code: nil, response_body: nil)
-        @status_code = status_code
-        @response_body = response_body
-        super(message)
-      end
-    end
-
-    def initialize(access_token:, timeout: DEFAULT_TIMEOUT)
+    # Default model for chat requests
+    DEFAULT_MODEL = "gpt-5-mini"
+    # Default model for embeddings requests
+    DEFAULT_EMBEDDINGS_MODEL = "text-embedding-3-small"
+    # (see LLMClientBase::APIError)
+    APIError = LLMClientBase::APIError
+
+    # @param access_token [String] API key ("ollama" or any placeholder for local servers)
+    # @param timeout [Integer] request timeout in seconds
+    # @param base_url [String] API endpoint; include the version path
+    #   (e.g., "http://localhost:11434/v1" for Ollama)
+    def initialize(access_token:, timeout: DEFAULT_TIMEOUT, base_url: API_ENDPOINT)
+      super(base_url: base_url, timeout: timeout)
       @access_token = access_token
-      @timeout = timeout
     end
 
     # Sends a chat completion request with optional tools support.
-    # Note: GPT-5 series and o-series models do not support the temperature parameter.
+    #
+    # The +temperature+ parameter is sent only when explicitly given. If the
+    # model rejects it (e.g., GPT-5 series and o-series models), the request
+    # is retried once without it.
     #
     # @param model [String] The model to use (e.g., "gpt-5-mini")
     # @param messages [Array<Hash>] The conversation messages
     # @param max_completion_tokens [Integer] Maximum tokens in the response
-    # @param temperature [Float, nil] Sampling temperature (ignored for models that don't support it)
+    # @param temperature [Float, nil] Sampling temperature (omitted when nil)
     # @param tools [Array<Hash>, nil] Tool definitions for function calling
     # @param tool_choice [String, Hash, nil] Tool selection strategy
     # @param response_format [Hash, nil] Response format specification (e.g., { type: "json_object" })
@@ -47,11 +48,7 @@ module Spacy
         messages: messages,
         max_completion_tokens: max_completion_tokens
       }
-
-      # GPT-5 series and o-series models do not support temperature parameter
-      unless temperature_unsupported?(model)
-        body[:temperature] = temperature || 0.7
-      end
+      body[:temperature] = temperature unless temperature.nil?
 
       if tools && !tools.empty?
         body[:tools] = tools
@@ -60,16 +57,7 @@ module Spacy
 
       body[:response_format] = response_format if response_format
 
-      post("/chat/completions", body)
-    end
-
-    # Checks if the model does not support the temperature parameter.
-    # This includes GPT-5 series and o-series (o1, o3, o4-mini, etc.) models.
-    # @param model [String] The model name
-    # @return [Boolean]
-    def temperature_unsupported?(model)
-      name = model.to_s
-      name.start_with?("gpt-5") || name.match?(/\Ao\d/)
+      post_with_temperature_fallback("/chat/completions", body)
     end
 
     # Sends an embeddings request.
@@ -90,77 +78,19 @@ module Spacy
 
     private
 
-    # Creates a certificate store with system CA certificates but without CRL checking.
-    # This avoids "unable to get certificate CRL" errors on some systems.
-    def default_cert_store
-      store = OpenSSL::X509::Store.new
-      store.set_default_paths
-      store
+    def request_headers
+      { "Authorization" => "Bearer #{@access_token}" }
     end
 
-    def post(path, body)
-      uri = URI.parse("#{API_ENDPOINT}#{path}")
-      retries = 0
+    # Models that do not accept the temperature parameter reject it with a 400;
+    # retry once without it so callers need no per-model knowledge.
+    def post_with_temperature_fallback(path, body)
+      post(path, body)
+    rescue APIError => e
+      raise unless body.key?(:temperature) && e.status_code == 400 && e.message.match?(/temperature/i)
 
-      loop do
-        begin
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true
-          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          http.cert_store = default_cert_store
-          http.open_timeout = @timeout
-          http.read_timeout = @timeout
-
-          request = Net::HTTP::Post.new(uri.path)
-          request["Content-Type"] = "application/json"
-          request["Authorization"] = "Bearer #{@access_token}"
-          request.body = body.to_json
-
-          response = http.request(request)
-
-          # Handle 429 rate limiting before general response handling
-          if response.code.to_i == 429
-            retries += 1
-            if retries <= MAX_RETRIES
-              retry_after = response["Retry-After"]&.to_f
-              delay = retry_after || (BASE_RETRY_DELAY * (2**(retries - 1)) + rand * 0.5)
-              sleep delay
-              next
-            end
-            raise APIError.new("Rate limited after #{MAX_RETRIES} retries",
-                               status_code: 429, response_body: response.body)
-          end
-
-          return handle_response(response)
-        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
-          retries += 1
-          if retries <= MAX_RETRIES
-            delay = BASE_RETRY_DELAY * (2**(retries - 1)) + rand * 0.5
-            sleep delay
-            next
-          end
-          raise APIError.new("Network error after #{MAX_RETRIES} retries: #{e.message}")
-        end
-      end
-    end
-
-    def handle_response(response)
-      body = JSON.parse(response.body)
-
-      case response.code.to_i
-      when 200
-        body
-      when 400..499
-        error_message = body.dig("error", "message") || "Client error"
-        raise APIError.new(error_message, status_code: response.code.to_i, response_body: body)
-      when 500..599
-        error_message = body.dig("error", "message") || "Server error"
-        raise APIError.new(error_message, status_code: response.code.to_i, response_body: body)
-      else
-        raise APIError.new("Unexpected response: #{response.code}", status_code: response.code.to_i, response_body: body)
-      end
-    rescue JSON::ParserError
-      raise APIError.new("Invalid JSON response", status_code: response.code.to_i, response_body: response.body)
+      warn "Warning: model does not support the temperature parameter; retrying without it"
+      post(path, body.reject { |key, _| key == :temperature })
     end
   end
 end

data/lib/ruby-spacy/openai_helper.rb

@@ -2,7 +2,11 @@
 
 module Spacy
   # A helper class for OpenAI API interactions, designed to work with spaCy's
-  # linguistic analysis via the block-based {Language#with_openai} API.
+  # linguistic analysis via the block-based {Language#with_llm} /
+  # {Language#with_openai} API.
+  #
+  # With a custom +base_url+, this helper also works with any OpenAI-compatible
+  # server such as Ollama, LM Studio, llama.cpp server, or vLLM.
   #
   # @example Basic usage with linguistic_summary
   #   nlp = Spacy::Language.new("en_core_web_sm")
@@ -10,6 +14,11 @@ module Spacy
   #     doc = nlp.read("Apple Inc. was founded by Steve Jobs.")
   #     ai.chat(system: "Analyze the linguistic data.", user: doc.linguistic_summary)
   #   end
+  #
+  # @example Local model via Ollama
+  #   nlp.with_llm(provider: :ollama, model: "llama3.2") do |ai|
+  #     ai.chat(user: "Say hello.")
+  #   end
   class OpenAIHelper
     # @return [String] the default model for chat requests
     attr_reader :model
@@ -18,19 +27,25 @@ module Spacy
     # @param access_token [String, nil] OpenAI API key (defaults to OPENAI_API_KEY env var)
     # @param model [String] the default model for chat requests
     # @param max_completion_tokens [Integer] default maximum tokens in responses
-    # @param temperature [Float] default sampling temperature
-    def initialize(access_token: nil, model: "gpt-5-mini",
-                   max_completion_tokens: 1000, temperature: 0.7)
+    # @param max_tokens [Integer, nil] alias for max_completion_tokens (takes precedence)
+    # @param temperature [Float, nil] default sampling temperature (omitted from
+    #   requests when nil; models that reject it are retried without it)
+    # @param base_url [String, nil] OpenAI-compatible API endpoint
+    #   (e.g., "http://localhost:11434/v1" for Ollama)
+    def initialize(access_token: nil, model: OpenAIClient::DEFAULT_MODEL,
+                   max_completion_tokens: 1000, max_tokens: nil,
+                   temperature: nil, base_url: nil)
       @access_token = access_token || ENV["OPENAI_API_KEY"]
       raise "Error: OPENAI_API_KEY is not set" unless @access_token
 
       @model = model
-      @default_max_completion_tokens = max_completion_tokens
+      @default_max_completion_tokens = max_tokens || max_completion_tokens
       @default_temperature = temperature
-      @client = OpenAIClient.new(access_token: @access_token)
+      @client = OpenAIClient.new(access_token: @access_token,
+                                 base_url: base_url || OpenAIClient::API_ENDPOINT)
     end
 
-    # Sends a chat completion request to OpenAI.
+    # Sends a chat completion request.
     #
     # Provides convenient `system:` and `user:` keyword arguments as shortcuts
     # for building simple message arrays. For more complex conversations, pass
@@ -41,41 +56,63 @@ module Spacy
     # @param messages [Array<Hash>, nil] full message array (overrides system:/user:)
     # @param model [String, nil] model override (defaults to instance model)
     # @param max_completion_tokens [Integer, nil] token limit override
+    # @param max_tokens [Integer, nil] alias for max_completion_tokens (takes precedence)
     # @param temperature [Float, nil] temperature override
     # @param response_format [Hash, nil] response format (e.g., { type: "json_object" })
+    # @param schema [Hash, nil] JSON Schema for structured outputs; when given,
+    #   the model output is constrained to the schema and the parsed Hash is
+    #   returned. Objects in the schema must set `additionalProperties: false`
+    #   and list all properties in `required`.
     # @param raw [Boolean] if true, returns the full API response Hash instead of text
-    # @return [String, Hash, nil] the response text, full response Hash (if raw:), or nil on error
+    # @return [String, Hash, nil] the response text, parsed Hash (if schema:),
+    #   full response Hash (if raw:), or nil on API error or when the schema
+    #   output cannot be parsed as JSON (e.g., truncated by the token limit)
     def chat(system: nil, user: nil, messages: nil,
-             model: nil, max_completion_tokens: nil,
-             temperature: nil, response_format: nil, raw: false)
+             model: nil, max_completion_tokens: nil, max_tokens: nil,
+             temperature: nil, response_format: nil, schema: nil, raw: false)
       msgs = messages || build_messages(system: system, user: user)
       raise ArgumentError, "No messages provided. Use system:/user: or messages:" if msgs.empty?
 
+      if schema
+        response_format = {
+          type: "json_schema",
+          json_schema: { name: "response", strict: true, schema: schema }
+        }
+      end
+
       response = @client.chat(
         model: model || @model,
         messages: msgs,
-        max_completion_tokens: max_completion_tokens || @default_max_completion_tokens,
+        max_completion_tokens: max_tokens || max_completion_tokens || @default_max_completion_tokens,
         temperature: temperature || @default_temperature,
         response_format: response_format
       )
 
-      raw ? response : response.dig("choices", 0, "message", "content")
+      return response if raw
+
+      choice = response.dig("choices", 0)
+      if choice&.dig("finish_reason") == "length"
+        warn "Warning: response was truncated (finish_reason: length); consider increasing max_completion_tokens"
+      end
+
+      content = choice&.dig("message", "content")
+      schema && content ? parse_json_content(content) : content
     rescue OpenAIClient::APIError => e
-      puts "Error: OpenAI API call failed - #{e.message}"
+      warn "Error: OpenAI API call failed - #{e.message}"
       nil
     end
 
-    # Generates text embeddings using OpenAI's embeddings API.
+    # Generates text embeddings using the embeddings API.
     #
     # @param text [String] the text to embed
     # @param model [String] the embeddings model
     # @param dimensions [Integer, nil] number of dimensions (nil uses model default)
     # @return [Array<Float>, nil] the embedding vector, or nil on error
-    def embeddings(text, model: "text-embedding-3-small", dimensions: nil)
+    def embeddings(text, model: OpenAIClient::DEFAULT_EMBEDDINGS_MODEL, dimensions: nil)
       response = @client.embeddings(model: model, input: text, dimensions: dimensions)
       response.dig("data", 0, "embedding")
     rescue OpenAIClient::APIError => e
-      puts "Error: OpenAI API call failed - #{e.message}"
+      warn "Error: OpenAI API call failed - #{e.message}"
       nil
     end
 
@@ -87,5 +124,12 @@ module Spacy
       msgs << { role: "user", content: user } if user
       msgs
     end
+
+    def parse_json_content(text)
+      JSON.parse(text)
+    rescue JSON::ParserError
+      warn "Error: response is not valid JSON (possibly truncated output); returning nil"
+      nil
+    end
   end
 end

data/lib/ruby-spacy/version.rb

@@ -2,5 +2,5 @@
 
 module Spacy
   # The version number of the module
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end