ruby-spacy 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6005c638c2b268fe162b288e124439be6a525952557a48b0b50685bbd2a6ea1
-  data.tar.gz: 41dbc057c9ec51ffa8d6f1149fb8acde3fb52a251299d0209b4e2d351942eac0
+  metadata.gz: 9bf4e97474302a2fffe019227e5afbb26c815036d13ec75bae6349f7186dff31
+  data.tar.gz: 2cd4012d9545d0a5ad9d2ebb03d07e40ae54acdfb18f0c9132c8848cce5cfd8e
 SHA512:
-  metadata.gz: 5be0efa9e649b3d46da859472ce403adaa3cdaa34d4158e7a531680eb2830ae64779ec6ada8f0f6e324cc9cb314fb1fcbc617daa26e37e91a7d14f703caeec2d
-  data.tar.gz: b8f56b4842fea3bec1b35366624c7ab9297c3a3b25c9a8502dc32c623593e511d9da538bf3e5cac272baf854cf4c2c97d4129790b492329183d88873467f8dbb
+  metadata.gz: 208f43e0efa0334ec159fb56e836f315bd5469a3768e77e0f6b7fa3ec936e722546e0323cc7bf5790393cc2fc52318e172355b821b6f3c83268de3cbf35ba139
+  data.tar.gz: 753515dcb7fb3e44ea2c4419e83baf9e0e8f9c6810a4f65cbfc3a631414b33019b5a0b4915c9a87edd8ac34fb8aac48673954c092c50e2e1cc152713bde48466

data/.github/FUNDING.yml

@@ -0,0 +1,6 @@
+# These are supported funding model platforms
+
+github: [yohasebe]
+ko_fi: yohasebe
+buy_me_a_coffee: yohasebe
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Change Log
 
+## 0.4.1 - 2026-07-19
+### Fixed
+- Gem packaging: normalize file permissions at build time so packaged files
+  are world-readable (0644 / 0755). Version 0.4.0 shipped 11 owner-only
+  (0600) files, which made the gem unusable after `sudo gem install`
+
+## 0.4.0 - 2026-02-23
+### Added
+- `Language#with_openai` block API with `OpenAIHelper` for streamlined OpenAI integration
+- `Doc#linguistic_summary` for JSON-formatted spaCy analysis output
+- `Token#idx`, `Span#text`/`Span#to_s`, `Language#memory_zone` (spaCy 3.8+)
+
+### Fixed
+- `Doc#ents` returns proper `Span` objects instead of raw Python objects
+
+### Changed
+- Model name validation in `Language#initialize` for security
+- OpenAI client: temperature support for o-series models, 429 retry with
+  exponential backoff, client reuse, `dimensions`/`response_format` parameters,
+  tool call depth limit
+- Improved `respond_to_missing?` across all wrapper classes
+- Added `instance_variables_to_inspect` for Ruby 4.0+ compatibility
+- Added `base64` gem dependency (required for Ruby 3.4+)
+
 ## 0.3.0 - 2025-01-06
 ### Added
 - Ruby 4.0 support

data/README.md

@@ -13,11 +13,12 @@
 | ✅ | Access to pre-trained word vectors                 |
 | ✅ | OpenAI Chat/Completion/Embeddings API integration  |
 
-Current Version: `0.3.0`
+Current Version: `0.4.0`
 
 - Ruby 4.0 supported
 - spaCy 3.8 supported
 - OpenAI GPT-5 API integration
+- Block-based OpenAI API with linguistic analysis
 
 ## Installation of Prerequisites
 
@@ -843,6 +844,65 @@ Output:
 ...
 ```
 
+### Block-based OpenAI API
+
+The `Language#with_openai` block API provides a streamlined way to combine spaCy's linguistic analysis with OpenAI. The `Doc#linguistic_summary` method generates a JSON summary of spaCy's analysis (tokens, entities, noun chunks, etc.) that can be passed directly to the LLM as context.
+
+**Basic usage:**
+
+```ruby
+require "ruby-spacy"
+
+nlp = Spacy::Language.new("en_core_web_sm")
+doc = nlp.read("Apple Inc. was founded by Steve Jobs in California.")
+
+nlp.with_openai(model: "gpt-5-mini") do |ai|
+  result = ai.chat(
+    system: "You are a linguistic analyst. Analyze the given linguistic data.",
+    user: doc.linguistic_summary
+  )
+  puts result
+end
+```
+
+**Batch processing with `pipe`:**
+
+```ruby
+require "ruby-spacy"
+
+nlp = Spacy::Language.new("en_core_web_sm")
+texts = ["The bank approved the loan.", "I sat on the river bank."]
+
+nlp.with_openai(model: "gpt-5-mini") do |ai|
+  nlp.pipe(texts).each do |doc|
+    result = ai.chat(
+      system: "Identify the meaning of 'bank' in one word based on the linguistic context.",
+      user: doc.linguistic_summary
+    )
+    puts "#{doc.text} => #{result}"
+  end
+end
+```
+
+**Customizing linguistic summary:**
+
+```ruby
+# Include sentences and morphology, exclude noun chunks
+summary = doc.linguistic_summary(
+  sections: [:text, :tokens, :entities, :sentences],
+  token_attributes: [:text, :lemma, :pos, :dep, :head, :morphology]
+)
+```
+
+**Embeddings:**
+
+```ruby
+nlp.with_openai do |ai|
+  vector = ai.embeddings("Hello world")
+  puts vector.length  # => 1536
+end
+```
+
 ## Advanced Usage
 
 ### Setting a Timeout

data/Rakefile

@@ -10,3 +10,16 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: :test
+
+# Gem packaging preserves on-disk file modes; owner-only permissions here
+# produce gems whose files are unreadable after a sudo install. Executable
+# status is determined by path alone because local (Dropbox-synced) modes
+# are unreliable.
+task :normalize_permissions do
+  `git ls-files -z`.split("\x0").each do |f|
+    executable = f.start_with?("bin/", "exe/")
+    File.chmod(executable ? 0o755 : 0o644, f)
+  end
+end
+
+Rake::Task["build"].enhance([:normalize_permissions])

data/lib/ruby-spacy/openai_client.rb

@@ -13,7 +13,7 @@ module Spacy
     API_ENDPOINT = "https://api.openai.com/v1"
     DEFAULT_TIMEOUT = 120
     MAX_RETRIES = 3
-    RETRY_DELAY = 1
+    BASE_RETRY_DELAY = 1
 
     class APIError < StandardError
       attr_reader :status_code, :response_body
@@ -31,24 +31,25 @@ module Spacy
     end
 
     # Sends a chat completion request with optional tools support.
-    # Note: GPT-5 series models do not support the temperature parameter.
+    # Note: GPT-5 series and o-series models do not support the temperature parameter.
     #
     # @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 GPT-5 models)
+    # @param temperature [Float, nil] Sampling temperature (ignored for models that don't support it)
     # @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" })
     # @return [Hash] The API response
-    def chat(model:, messages:, max_completion_tokens: 1000, temperature: nil, tools: nil, tool_choice: nil)
+    def chat(model:, messages:, max_completion_tokens: 1000, temperature: nil, tools: nil, tool_choice: nil, response_format: nil)
       body = {
         model: model,
         messages: messages,
         max_completion_tokens: max_completion_tokens
       }
 
-      # GPT-5 series models do not support temperature parameter
-      unless gpt5_model?(model)
+      # GPT-5 series and o-series models do not support temperature parameter
+      unless temperature_unsupported?(model)
         body[:temperature] = temperature || 0.7
       end
 
@@ -57,25 +58,32 @@ module Spacy
         body[:tool_choice] = tool_choice || "auto"
       end
 
+      body[:response_format] = response_format if response_format
+
       post("/chat/completions", body)
     end
 
-    # Checks if the model is a GPT-5 series model.
-    # GPT-5 models have different parameter requirements (no temperature support).
-    def gpt5_model?(model)
-      model.to_s.start_with?("gpt-5")
+    # 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/)
     end
 
     # Sends an embeddings request.
     #
     # @param model [String] The embeddings model (e.g., "text-embedding-3-small")
     # @param input [String] The text to embed
+    # @param dimensions [Integer, nil] The number of dimensions for the output embeddings
     # @return [Hash] The API response
-    def embeddings(model:, input:)
+    def embeddings(model:, input:, dimensions: nil)
       body = {
         model: model,
         input: input
       }
+      body[:dimensions] = dimensions if dimensions
 
       post("/embeddings", body)
     end
@@ -94,36 +102,45 @@ module Spacy
       uri = URI.parse("#{API_ENDPOINT}#{path}")
       retries = 0
 
-      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_response(response)
-      rescue Net::OpenTimeout, Net::ReadTimeout => e
-        retries += 1
-        if retries <= MAX_RETRIES
-          sleep RETRY_DELAY
-          retry
-        end
-        raise APIError.new("Request timed out after #{MAX_RETRIES} retries: #{e.message}")
-      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
-        retries += 1
-        if retries <= MAX_RETRIES
-          sleep RETRY_DELAY
-          retry
+      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
-        raise APIError.new("Network error after #{MAX_RETRIES} retries: #{e.message}")
       end
     end
 

data/lib/ruby-spacy/openai_helper.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # @example Basic usage with linguistic_summary
+  #   nlp = Spacy::Language.new("en_core_web_sm")
+  #   nlp.with_openai(model: "gpt-5-mini") 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 OpenAIHelper
+    # @return [String] the default model for chat requests
+    attr_reader :model
+
+    # Creates a new OpenAIHelper instance.
+    # @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)
+      @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_temperature = temperature
+      @client = OpenAIClient.new(access_token: @access_token)
+    end
+
+    # Sends a chat completion request to OpenAI.
+    #
+    # Provides convenient `system:` and `user:` keyword arguments as shortcuts
+    # for building simple message arrays. For more complex conversations, pass
+    # a full `messages:` array directly.
+    #
+    # @param system [String, nil] system message content (shortcut)
+    # @param user [String, nil] user message content (shortcut)
+    # @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 temperature [Float, nil] temperature override
+    # @param response_format [Hash, nil] response format (e.g., { type: "json_object" })
+    # @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
+    def chat(system: nil, user: nil, messages: nil,
+             model: nil, max_completion_tokens: nil,
+             temperature: nil, response_format: nil, raw: false)
+      msgs = messages || build_messages(system: system, user: user)
+      raise ArgumentError, "No messages provided. Use system:/user: or messages:" if msgs.empty?
+
+      response = @client.chat(
+        model: model || @model,
+        messages: msgs,
+        max_completion_tokens: max_completion_tokens || @default_max_completion_tokens,
+        temperature: temperature || @default_temperature,
+        response_format: response_format
+      )
+
+      raw ? response : response.dig("choices", 0, "message", "content")
+    rescue OpenAIClient::APIError => e
+      puts "Error: OpenAI API call failed - #{e.message}"
+      nil
+    end
+
+    # Generates text embeddings using OpenAI's 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)
+      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}"
+      nil
+    end
+
+    private
+
+    def build_messages(system: nil, user: nil)
+      msgs = []
+      msgs << { role: "system", content: system } if system
+      msgs << { role: "user", content: user } if user
+      msgs
+    end
+  end
+end

data/lib/ruby-spacy/version.rb

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