ruby-spacy 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bf4e97474302a2fffe019227e5afbb26c815036d13ec75bae6349f7186dff31
-  data.tar.gz: 2cd4012d9545d0a5ad9d2ebb03d07e40ae54acdfb18f0c9132c8848cce5cfd8e
+  metadata.gz: b759c507a1cad8e726bd36ad39e4539894395407e2ac5d64a31b7b907a4e34d8
+  data.tar.gz: 0f02f9b8f6bcf39a49b50b1934905e72c0c13bb9652eee8fbaad3a3b7b58b7e7
 SHA512:
-  metadata.gz: 208f43e0efa0334ec159fb56e836f315bd5469a3768e77e0f6b7fa3ec936e722546e0323cc7bf5790393cc2fc52318e172355b821b6f3c83268de3cbf35ba139
-  data.tar.gz: 753515dcb7fb3e44ea2c4419e83baf9e0e8f9c6810a4f65cbfc3a631414b33019b5a0b4915c9a87edd8ac34fb8aac48673954c092c50e2e1cc152713bde48466
+  metadata.gz: 5b7d8078148e05c860f3ef698b5103cfca533fabfac5001c5afd12419efaae21d6492aa22fcebfba9d9d22bf8701fe2c6a21eb1ee879344cdbd5d897af9b8853
+  data.tar.gz: 4ffab4be8e0338e86c34aad0285cd9471a3d5c570fbf48b4214cdbe5ca5cc01c7d251d4f6d5edc778de2185d89fc3858e094c363499c81f89d5c3a61ab8859c2

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Change Log
 
+## 0.5.0 - 2026-07-21
+### Added
+- `Language#with_llm(provider:)` — provider-neutral block-based LLM API
+  supporting `:openai`, `:anthropic` (Claude), and `:ollama` (local models)
+- `AnthropicHelper` / `AnthropicClient` — Anthropic Messages API support
+  using only net/http (default model: `claude-sonnet-5`; requires
+  `ANTHROPIC_API_KEY`)
+- `base_url:` option for OpenAI client/helper — works with any
+  OpenAI-compatible server (Ollama, LM Studio, llama.cpp server, vLLM,
+  OpenRouter, etc.)
+- `schema:` option for `chat` — Structured Outputs on both providers;
+  returns a validated, parsed Ruby Hash
+- New examples under `examples/llm/` (Anthropic, local Ollama, and a
+  spaCy-vs-LLM NER comparison with structured outputs)
+
+### Changed
+- `temperature` is now sent only when explicitly specified; if a model
+  rejects it, the request is retried once without it. The model-name
+  heuristic (`temperature_unsupported?`) has been removed, so new models
+  work without gem updates. Note: previously a default of 0.7 was sent to
+  models that supported it (also from `Doc#openai_query` /
+  `Doc#openai_completion`); now the API default applies unless you pass
+  `temperature:` yourself
+- Shared HTTP layer (`LLMClientBase`) extracted from `OpenAIClient`;
+  no behavior change for existing OpenAI usage
+- Truncated responses (`finish_reason: length` / `stop_reason: max_tokens`)
+  now emit a warning; with `schema:`, unparseable (e.g. truncated) JSON
+  returns nil with a warning instead of raising `JSON::ParserError`
+- LLM error messages are printed to stderr (`Kernel#warn`) instead of
+  stdout, keeping stdout clean for program output
+- Default model names are now public constants:
+  `OpenAIClient::DEFAULT_MODEL`, `OpenAIClient::DEFAULT_EMBEDDINGS_MODEL`,
+  `AnthropicClient::DEFAULT_MODEL`
+
 ## 0.4.1 - 2026-07-19
 ### Fixed
 - Gem packaging: normalize file permissions at build time so packaged files

data/README.md

@@ -11,14 +11,15 @@
 | ✅ | Named entity recognition                           |
 | ✅ | Syntactic dependency visualization                 |
 | ✅ | Access to pre-trained word vectors                 |
-| ✅ | OpenAI Chat/Completion/Embeddings API integration  |
+| ✅ | LLM integration: OpenAI, Anthropic (Claude), and local models |
 
-Current Version: `0.4.0`
+Current Version: `0.5.0`
 
 - Ruby 4.0 supported
 - spaCy 3.8 supported
-- OpenAI GPT-5 API integration
-- Block-based OpenAI API with linguistic analysis
+- Multi-provider LLM API: OpenAI, Anthropic (Claude), and local models via Ollama or any OpenAI-compatible server
+- Structured outputs (JSON Schema) support
+- Block-based LLM API with linguistic analysis
 
 ## Installation of Prerequisites
 
@@ -588,7 +589,9 @@ end
 
 ## OpenAI API Integration
 
-> ⚠️ This feature requires GPT-5 series models. Please refer to OpenAI's [API reference](https://platform.openai.com/docs/api-reference) for details. Note: GPT-5 models do not support the `temperature` parameter.
+> ⚠️ This feature requires GPT-5 series models. Please refer to OpenAI's [API reference](https://platform.openai.com/docs/api-reference) for details.
+
+> ℹ️ The `temperature` parameter is sent to the API only when you specify it explicitly. If the model does not support it (e.g., GPT-5 series and o-series models), the request is automatically retried once without it — no per-model configuration is needed.
 
 Easily leverage GPT models within ruby-spacy by using an OpenAI API key. When constructing prompts for the `Doc::openai_query` method, you can incorporate the following token properties of the document. These properties are retrieved through tool calls (made internally by GPT when necessary) and seamlessly integrated into your prompt. The available properties include:
 
@@ -903,6 +906,72 @@ nlp.with_openai do |ai|
 end
 ```
 
+### Multi-provider LLM API
+
+The `Language#with_llm` block API generalizes `with_openai` to multiple providers. The helper yielded to the block has the same `chat` interface for every provider.
+
+**Anthropic (Claude):**
+
+```ruby
+# Requires the ANTHROPIC_API_KEY environment variable
+# Default model: claude-sonnet-5 (override with model: "...")
+nlp.with_llm(provider: :anthropic) do |ai|
+  result = ai.chat(
+    system: "You are a linguistic analyst.",
+    user: doc.linguistic_summary
+  )
+  puts result
+end
+```
+
+**Local models via Ollama (no API key needed):**
+
+```ruby
+# Requires a running Ollama server: https://ollama.com
+nlp.with_llm(provider: :ollama, model: "llama3.2") do |ai|
+  puts ai.chat(user: doc.linguistic_summary)
+end
+```
+
+Any other OpenAI-compatible server (LM Studio, llama.cpp server, vLLM, OpenRouter, etc.) works via `base_url:`:
+
+```ruby
+nlp.with_llm(provider: :openai, base_url: "http://localhost:1234/v1",
+             access_token: "not-needed", model: "your-model") do |ai|
+  puts ai.chat(user: "Hello!")
+end
+```
+
+**Structured outputs (`schema:`):** pass a JSON Schema and receive a validated, parsed Ruby Hash — useful for comparing LLM output with spaCy's analysis programmatically. Works with both `:openai` and `:anthropic`. Objects in the schema must set `additionalProperties: false`.
+
+```ruby
+schema = {
+  type: "object",
+  properties: {
+    entities: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { text: { type: "string" }, label: { type: "string" } },
+        required: %w[text label],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["entities"],
+  additionalProperties: false
+}
+
+result = nlp.with_llm(provider: :openai) do |ai|
+  ai.chat(system: "Extract named entities.", user: doc.text, schema: schema)
+end
+result["entities"].each { |ent| puts "#{ent["text"]} (#{ent["label"]})" }
+```
+
+**Note on `temperature`:** for all providers, `temperature` is omitted from requests unless you pass it explicitly (`ai.chat(user: "...", temperature: 0.3)`). Models that reject the parameter (e.g., GPT-5 series, o-series, and current Claude models) are automatically retried once without it, so any model works without per-model configuration.
+
+See `examples/llm/` for complete scripts, including a spaCy-vs-LLM NER comparison.
+
 ## Advanced Usage
 
 ### Setting a Timeout

data/examples/llm/anthropic_chat.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+
+# Requires the ANTHROPIC_API_KEY environment variable
+# Default model: claude-sonnet-5 (override with model: "...")
+
+nlp = Spacy::Language.new("en_core_web_sm")
+doc = nlp.read("The cat sat on the mat while the dog slept under the table.")
+
+result = nlp.with_llm(provider: :anthropic) do |ai|
+  ai.chat(
+    system: "You are a linguistics tutor. Explain the syntactic structure briefly.",
+    user: doc.linguistic_summary
+  )
+end
+
+puts result

data/examples/llm/local_llm_ollama.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+
+# Requires a running Ollama server (https://ollama.com):
+#   ollama pull llama3.2
+#   ollama serve
+# No API key is needed.
+
+nlp = Spacy::Language.new("en_core_web_sm")
+doc = nlp.read("I sat on the bank of the river.")
+
+result = nlp.with_llm(provider: :ollama, model: "llama3.2") do |ai|
+  ai.chat(
+    system: "Identify the meaning of the word 'bank' in one short sentence.",
+    user: doc.linguistic_summary
+  )
+end
+
+puts result
+
+# Any OpenAI-compatible server works the same way via base_url, e.g.:
+#   nlp.with_llm(provider: :openai, base_url: "http://localhost:1234/v1",
+#                access_token: "not-needed", model: "your-model") { |ai| ... }

data/examples/llm/structured_ner_comparison.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+
+# Compares spaCy's named entity recognition with an LLM's, using structured
+# outputs so the LLM's answer comes back as a validated Ruby Hash.
+# Requires the OPENAI_API_KEY environment variable
+# (or swap in provider: :anthropic with ANTHROPIC_API_KEY).
+
+nlp = Spacy::Language.new("en_core_web_sm")
+text = "Mr. Best flew to New York on Saturday morning to meet Tim Cook of Apple."
+doc = nlp.read(text)
+
+schema = {
+  type: "object",
+  properties: {
+    entities: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          text: { type: "string" },
+          label: { type: "string", enum: %w[PERSON ORG GPE DATE TIME OTHER] }
+        },
+        required: %w[text label],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["entities"],
+  additionalProperties: false
+}
+
+llm_result = nlp.with_llm(provider: :openai) do |ai|
+  ai.chat(
+    system: "Extract all named entities from the user's text.",
+    user: text,
+    schema: schema
+  )
+end
+
+puts "spaCy entities:"
+doc.ents.each { |ent| puts "  #{ent.text} (#{ent.label})" }
+
+puts "\nLLM entities:"
+llm_result["entities"].each { |ent| puts "  #{ent["text"]} (#{ent["label"]})" }

data/lib/ruby-spacy/anthropic_client.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "llm_client_base"
+
+module Spacy
+  # A lightweight Anthropic Messages API client without external dependencies.
+  class AnthropicClient < LLMClientBase
+    # Default Anthropic API endpoint
+    API_ENDPOINT = "https://api.anthropic.com/v1"
+    # Messages API version header value
+    ANTHROPIC_VERSION = "2023-06-01"
+    # Default model for chat requests
+    DEFAULT_MODEL = "claude-sonnet-5"
+    # (see LLMClientBase::APIError)
+    APIError = LLMClientBase::APIError
+
+    # @param access_token [String] Anthropic API key
+    # @param timeout [Integer] request timeout in seconds
+    # @param base_url [String] API endpoint override
+    def initialize(access_token:, timeout: DEFAULT_TIMEOUT, base_url: API_ENDPOINT)
+      super(base_url: base_url, timeout: timeout)
+      @access_token = access_token
+    end
+
+    # Sends a Messages API request.
+    #
+    # The +temperature+ parameter is sent only when explicitly given. Current
+    # Claude models (Opus 4.7+) reject it; the request is then retried once
+    # without it.
+    #
+    # @param model [String] The model to use (e.g., "claude-sonnet-5")
+    # @param messages [Array<Hash>] The conversation messages
+    # @param system [String, nil] System prompt (top-level parameter)
+    # @param max_tokens [Integer] Maximum tokens in the response (required by the API)
+    # @param temperature [Float, nil] Sampling temperature (omitted when nil)
+    # @param output_config [Hash, nil] Output configuration, e.g.
+    #   { format: { type: "json_schema", schema: {...} } } for structured outputs
+    # @return [Hash] The API response
+    def messages(model:, messages:, system: nil, max_tokens: 1000, temperature: nil, output_config: nil)
+      body = {
+        model: model,
+        max_tokens: max_tokens,
+        messages: messages
+      }
+      body[:system] = system if system
+      body[:temperature] = temperature unless temperature.nil?
+      body[:output_config] = output_config if output_config
+
+      post("/messages", body)
+    rescue APIError => e
+      raise unless body.key?(:temperature) && e.status_code == 400 && e.message.match?(/temperature/i)
+
+      warn "Warning: model does not support the temperature parameter; retrying without it"
+      post("/messages", body.reject { |key, _| key == :temperature })
+    end
+
+    private
+
+    def request_headers
+      {
+        "x-api-key" => @access_token,
+        "anthropic-version" => ANTHROPIC_VERSION
+      }
+    end
+  end
+end

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.1"
+  VERSION = "0.5.0"
 end

data/lib/ruby-spacy.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "ruby-spacy/version"
+require_relative "ruby-spacy/llm_client_base"
 require_relative "ruby-spacy/openai_client"
+require_relative "ruby-spacy/anthropic_client"
 require_relative "ruby-spacy/openai_helper"
+require_relative "ruby-spacy/anthropic_helper"
 require "numpy"
 require "pycall"
 require "timeout"
@@ -310,7 +313,8 @@ module Spacy
     # @param access_token [String, nil] OpenAI API key (defaults to OPENAI_API_KEY env var)
     # @param max_completion_tokens [Integer] Maximum tokens in the response
     # @param max_tokens [Integer] Alias for max_completion_tokens (deprecated, for backward compatibility)
-    # @param temperature [Float] Sampling temperature (ignored for GPT-5 models)
+    # @param temperature [Float, nil] Sampling temperature (omitted from requests
+    #   when nil; models that reject it are retried without it)
     # @param model [String] The model to use (default: gpt-5-mini)
     # @param messages [Array<Hash>] Conversation history (for recursive tool calls). Note: this array is modified in place when tool calls occur.
     # @param prompt [String, nil] System prompt for the query
@@ -318,8 +322,8 @@ module Spacy
     def openai_query(access_token: nil,
                      max_completion_tokens: nil,
                      max_tokens: nil,
-                     temperature: 0.7,
-                     model: "gpt-5-mini",
+                     temperature: nil,
+                     model: OpenAIClient::DEFAULT_MODEL,
                      messages: [],
                      prompt: nil,
                      response_format: nil,
@@ -420,7 +424,7 @@ module Spacy
         message["content"]
       end
     rescue OpenAIClient::APIError => e
-      puts "Error: OpenAI API call failed - #{e.message}"
+      warn "Error: OpenAI API call failed - #{e.message}"
       nil
     end
 
@@ -429,10 +433,11 @@ module Spacy
     # @param access_token [String, nil] OpenAI API key (defaults to OPENAI_API_KEY env var)
     # @param max_completion_tokens [Integer] Maximum tokens in the response
     # @param max_tokens [Integer] Alias for max_completion_tokens (deprecated, for backward compatibility)
-    # @param temperature [Float] Sampling temperature (ignored for GPT-5 models)
+    # @param temperature [Float, nil] Sampling temperature (omitted from requests
+    #   when nil; models that reject it are retried without it)
     # @param model [String] The model to use (default: gpt-5-mini)
     # @return [String, nil] The completed text
-    def openai_completion(access_token: nil, max_completion_tokens: nil, max_tokens: nil, temperature: 0.7, model: "gpt-5-mini")
+    def openai_completion(access_token: nil, max_completion_tokens: nil, max_tokens: nil, temperature: nil, model: OpenAIClient::DEFAULT_MODEL)
       # Support both max_completion_tokens and max_tokens for backward compatibility
       max_completion_tokens ||= max_tokens || 1000
 
@@ -450,7 +455,7 @@ module Spacy
       )
       response.dig("choices", 0, "message", "content")
     rescue OpenAIClient::APIError => e
-      puts "Error: OpenAI API call failed - #{e.message}"
+      warn "Error: OpenAI API call failed - #{e.message}"
       nil
     end
 
@@ -460,12 +465,12 @@ module Spacy
     # @param model [String] The embeddings model (default: text-embedding-3-small)
     # @param dimensions [Integer, nil] The number of dimensions for the output embeddings (nil uses model default)
     # @return [Array<Float>, nil] The embedding vector
-    def openai_embeddings(access_token: nil, model: "text-embedding-3-small", dimensions: nil)
+    def openai_embeddings(access_token: nil, model: OpenAIClient::DEFAULT_EMBEDDINGS_MODEL, dimensions: nil)
       client = openai_client(access_token)
       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
 
@@ -618,14 +623,56 @@ module Spacy
       end
     end
 
-    # Yields an {OpenAIHelper} instance for making OpenAI API calls within a block.
+    # Yields a provider-specific LLM helper for making API calls within a block.
     # The helper is configured once and reused for all calls within the block,
     # making it efficient for batch processing with {#pipe}.
     #
+    # Providers:
+    # - +:openai+ — OpenAI API (or any OpenAI-compatible endpoint via +base_url:+).
+    #   Yields an {OpenAIHelper}.
+    # - +:anthropic+ — Anthropic (Claude) Messages API. Yields an {AnthropicHelper}.
+    # - +:ollama+ — shortcut for a local Ollama server
+    #   (+base_url: "http://localhost:11434/v1"+, no API key needed).
+    #   Yields an {OpenAIHelper}.
+    #
+    # @param provider [Symbol] :openai (default), :anthropic, or :ollama
+    # @param opts [Hash] helper options (access_token:, model:, max_tokens:,
+    #   temperature:, base_url:, ...) — see {OpenAIHelper#initialize} and
+    #   {AnthropicHelper#initialize}
+    # @yield [OpenAIHelper, AnthropicHelper] the helper instance for making API calls
+    # @return [Object] the block's return value
+    # @example Claude
+    #   nlp.with_llm(provider: :anthropic) do |ai|
+    #     ai.chat(system: "Analyze.", 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
+    def with_llm(provider: :openai, **opts)
+      helper = case provider.to_sym
+               when :openai
+                 OpenAIHelper.new(**opts)
+               when :anthropic
+                 AnthropicHelper.new(**opts)
+               when :ollama
+                 OpenAIHelper.new(**{ base_url: "http://localhost:11434/v1",
+                                      access_token: "ollama" }.merge(opts))
+               else
+                 raise ArgumentError, "Unknown LLM provider: #{provider} (use :openai, :anthropic, or :ollama)"
+               end
+      yield helper
+    end
+
+    # Yields an {OpenAIHelper} instance for making OpenAI API calls within a block.
+    # Equivalent to {#with_llm} with +provider: :openai+.
+    #
     # @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
+    # @param temperature [Float, nil] default sampling temperature (omitted from
+    #   requests when nil)
+    # @param base_url [String, nil] OpenAI-compatible API endpoint override
     # @yield [OpenAIHelper] the helper instance for making API calls
     # @return [Object] the block's return value
     # @example Batch processing with pipe
@@ -634,13 +681,14 @@ module Spacy
     #       ai.chat(system: "Analyze.", user: doc.linguistic_summary)
     #     end
     #   end
-    def with_openai(access_token: nil, model: "gpt-5-mini",
-                    max_completion_tokens: 1000, temperature: 0.7)
+    def with_openai(access_token: nil, model: OpenAIClient::DEFAULT_MODEL,
+                    max_completion_tokens: 1000, temperature: nil, base_url: nil)
       helper = OpenAIHelper.new(
         access_token: access_token,
         model: model,
         max_completion_tokens: max_completion_tokens,
-        temperature: temperature
+        temperature: temperature,
+        base_url: base_url
       )
       yield helper
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-spacy
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Yoichiro Hasebe
@@ -208,6 +208,9 @@ files:
 - examples/linguistic_features/similarity_between_lexemes.rb
 - examples/linguistic_features/similarity_between_spans.rb
 - examples/linguistic_features/tokenization.rb
+- examples/llm/anthropic_chat.rb
+- examples/llm/local_llm_ollama.rb
+- examples/llm/structured_ner_comparison.rb
 - examples/openai_integration/openai_completion.rb
 - examples/openai_integration/openai_embeddings.rb
 - examples/openai_integration/openai_query_1.rb
@@ -217,6 +220,9 @@ files:
 - examples/rule_based_matching/creating_spans_from_matches.rb
 - examples/rule_based_matching/matcher.rb
 - lib/ruby-spacy.rb
+- lib/ruby-spacy/anthropic_client.rb
+- lib/ruby-spacy/anthropic_helper.rb
+- lib/ruby-spacy/llm_client_base.rb
 - lib/ruby-spacy/openai_client.rb
 - lib/ruby-spacy/openai_helper.rb
 - lib/ruby-spacy/version.rb