ruby-spacy 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bf4e97474302a2fffe019227e5afbb26c815036d13ec75bae6349f7186dff31
-  data.tar.gz: 2cd4012d9545d0a5ad9d2ebb03d07e40ae54acdfb18f0c9132c8848cce5cfd8e
+  metadata.gz: 055dc3da59c059df185ce0d868ba8da07453f0c5c1501d2a61fc5e27e5abee28
+  data.tar.gz: adc27ca2bfcc46ea0ad90bcd2469c2fc5abfdad47982339a7acb085ddeb20de0
 SHA512:
-  metadata.gz: 208f43e0efa0334ec159fb56e836f315bd5469a3768e77e0f6b7fa3ec936e722546e0323cc7bf5790393cc2fc52318e172355b821b6f3c83268de3cbf35ba139
-  data.tar.gz: 753515dcb7fb3e44ea2c4419e83baf9e0e8f9c6810a4f65cbfc3a631414b33019b5a0b4915c9a87edd8ac34fb8aac48673954c092c50e2e1cc152713bde48466
+  metadata.gz: 0ef618c78e55a8607b2975bd91946ab0d337a7fa73982f05fda1bb6db4f8e773b5535b90833fe79de63f8def8a3fb08ce363592a54f941de85b57618f7b7945e
+  data.tar.gz: 0bd57b4cfe238a630c85c93c4b84b0d95b1e07dc74583cf4916fc2b16ba51222c4a35b2a5d5e18e470050ba8680ef642a1d0ba50c6d830b506bf4c4f7b6523f3

data/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  # Every branch, so that work in progress is tested before a pull request exists
+  push:
+    branches: ["**"]
+  pull_request:
+  # Weekly run to detect breakage from new spaCy / PyCall / Ruby releases
+  # even when the repository itself is untouched
+  schedule:
+    - cron: "23 3 * * 2"
+
+jobs:
+  test:
+    name: ruby ${{ matrix.ruby }} / python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    # Pull requests from this repository are already covered by the push event;
+    # only run the pull_request event for forks, to avoid duplicate matrices
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    # This project has known hang paths (pipeline calls from non-main threads,
+    # spacy.load hangs that Ruby's Timeout cannot interrupt); never let a job
+    # run until GitHub's 6-hour limit
+    timeout-minutes: 30
+    continue-on-error: ${{ matrix.experimental == true }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          # Ruby 4.1 is not released yet; track the development branch instead
+          - { ruby: head, python: "3.13", experimental: true }
+    env:
+      # PyCall locates the Python interpreter via this variable
+      PYTHON: python
+    steps:
+      - uses: actions/checkout@v7
+
+      # Must precede ruby/setup-ruby: installing the pycall gem compiles its
+      # native extension against this Python
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - id: site-packages
+        run: echo "path=$(python -c 'import site; print(site.getsitepackages()[0])')" >> "$GITHUB_OUTPUT"
+
+      # Cache the language models only (en_core_web_lg alone is several hundred
+      # MB). spaCy itself is intentionally installed fresh on every run so that
+      # new releases are exercised immediately. Bump the key suffix when
+      # upgrading the models.
+      - uses: actions/cache@v6
+        with:
+          path: |
+            ${{ steps.site-packages.outputs.path }}/en_core_web_sm*
+            ${{ steps.site-packages.outputs.path }}/en_core_web_lg*
+          key: spacy-models-${{ matrix.python }}-v1
+
+      # en_core_web_lg is large; install it only on representative jobs.
+      # Tests that need it are skipped automatically where it is absent.
+      - name: Install spaCy and language models
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade spacy
+          python -m spacy download en_core_web_sm
+          if [ "${{ matrix.python }}" = "3.13" ]; then python -m spacy download en_core_web_lg; fi
+
+      - name: Run tests
+        run: bundle exec rake test

data/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Change Log
 
+## 0.6.0 - 2026-08-31
+### Added
+- GitHub Actions CI — Ruby 3.2 to 4.0 (plus ruby-head) and Python 3.11 to 3.14,
+  with a weekly run to catch breakage from new spaCy or PyCall releases
+- `:label` in `Matcher#match` results — the label string of the matched pattern
+
+### Changed
+- PyCall 1.5.3 or later is now required; earlier versions freeze the whole
+  process when Ruby's GC releases a Python object on a non-main thread, which
+  affects any threaded application (Rails, Puma, Sidekiq)
+- Minimum Ruby version raised to 3.2
+- Removed the `numpy` gem dependency; NumPy is used directly through PyCall
+- Relaxed the `terminal-table` requirement to `>= 3.0, < 5`
+- Language models are no longer stored in Python's `__main__`, so creating a
+  `Language` no longer keeps a pipeline alive until the process exits
+- `Language.new(timeout:)` now actually fires. The wait happens on a Python
+  thread rather than through Ruby's `Timeout`, whose watcher thread cannot run
+  while PyCall holds the GVL. `timeout: nil` waits indefinitely, and a timeout
+  is never retried
+- README documents the thread-safety constraint: all spaCy calls must be made
+  from the thread that initialized PyCall
+
+### Deprecated
+- `Language#spacy_nlp_id` — use `#py_nlp` instead; referencing it still works
+  but creates a Python global variable that is never released
+
+### Fixed
+- `Matcher#match` returned a corrupted `:match_id` (often `0`) for labels whose
+  hash was `2**62` or larger, since unsigned 64-bit values do not survive the
+  PyCall boundary. Ids now round-trip through `Language#vocab_string_lookup`,
+  which accepts large ids again
+- Integer attributes reached through `method_missing`, such as `Token#orth`,
+  were silently corrupted for the same reason: 7 of 12 common words returned a
+  negative `orth`. They are now fetched safely, which also restores
+  `Token#rank` for out-of-vocabulary tokens
+
+## 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/Gemfile

@@ -5,15 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in ruby-spacy.gemspec
 gemspec
 
-gem "fiddle" # Required for Ruby 4.0+ (moved from default to bundled gem)
-gem "numpy"
-gem "pycall", "~> 1.5.1"
-gem "terminal-table"
-
 group :development do
   gem "github-markup"
-  gem "minitest", "~> 5.0"
-  gem "rake", "~> 13.0"
   gem "redcarpet"
-  gem "yard"
 end

data/README.md

@@ -11,27 +11,28 @@
 | ✅ | 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.6.0`
 
-- Ruby 4.0 supported
+- Ruby 3.2 to 4.0 supported (PyCall 1.5.3 or later required)
 - 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
 
-**IMPORTANT**: Make sure that the `enable-shared` option is enabled in your Python installation. You can use [pyenv](https://github.com/pyenv/pyenv) to install any version of Python you like. Install Python 3.10.6, for instance, using pyenv with `enable-shared` as follows:
+**IMPORTANT**: Make sure that the `enable-shared` option is enabled in your Python installation. You can use [pyenv](https://github.com/pyenv/pyenv) to install any version of Python you like. spaCy 3.8 supports Python 3.10 and later (wheels are provided for Python 3.10–3.14), so we recommend using one of those versions. Install Python 3.13, for instance, using pyenv with `enable-shared` as follows:
 
 ```shell
-$ env CONFIGURE_OPTS="--enable-shared" pyenv install 3.10.6
+$ env CONFIGURE_OPTS="--enable-shared" pyenv install 3.13
 ```
 
 Remember to make it accessible from your working directory. It is recommended that you set `global` to the version of python you just installed.
 
 ```shell
-$ pyenv global 3.10.6 
+$ pyenv global 3.13
 ```
 
 Then, install [spaCy](https://spacy.io/). If you use `pip`, the following command will do:
@@ -524,6 +525,30 @@ Output:
 | 9    | アルザス       | 0.5644999742507935 |
 | 10   | 南仏           | 0.5547999739646912 |
 
+### Matcher
+
+`Matcher` finds token sequences with rule-based patterns.
+
+```ruby
+require "ruby-spacy"
+
+nlp = Spacy::Language.new("en_core_web_sm")
+
+matcher = nlp.matcher
+matcher.add("GREETING", [[{ LOWER: "hello" }, { IS_PUNCT: true }, { LOWER: "world" }]])
+
+doc = nlp.read("Hello, world!")
+matcher.match(doc).each do |match|
+  span = doc.span(match[:start_index]..match[:end_index])
+  puts "#{match[:label]}: #{span.text}"
+end
+# => GREETING: Hello, world
+```
+
+`Matcher#match` returns an array of hashes with `:match_id` (the label's numeric id), `:start_index`, `:end_index`, and `:label` (the label string).
+
+See `examples/rule_based_matching/` for more examples.
+
 ### PhraseMatcher
 
 `PhraseMatcher` is more efficient than `Matcher` for matching large terminology lists. It's ideal for extracting known entities like product names, company names, or domain-specific terms.
@@ -588,7 +613,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,8 +930,82 @@ 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
 
+### Thread Safety
+
+All spaCy calls must be made from the same thread that initialized PyCall (normally the main thread). Calling the spaCy pipeline from another thread — e.g. `nlp.read(text)` inside a `Thread.new` block, a Rails multi-threaded server, or a Sidekiq worker — will hang the entire process.
+
+Note that attribute access (such as `nlp.pipe_names`) works from other threads, so the failure mode is not obvious: the process only freezes when the pipeline actually runs. The root cause is currently unknown (it is specific to spaCy pipeline execution; other GIL-releasing Python calls work fine from other threads).
+
+If you need concurrent processing, serialize all Python calls onto a single dedicated thread, for example with a worker thread and a queue.
+
 ### Setting a Timeout
 
 You can set a timeout for the `Spacy::Language.new` method:
@@ -913,6 +1014,8 @@ You can set a timeout for the `Spacy::Language.new` method:
 nlp = Spacy::Language.new("en_core_web_sm", timeout: 120) # Set timeout to 120 seconds
 ```
 
+If the model does not finish loading within the given seconds, a `RuntimeError` is raised. Pass `timeout: nil` to wait indefinitely.
+
 ### Document Serialization
 
 You can serialize processed documents to binary format for caching or storage. This is useful when you want to avoid re-processing the same text multiple times.

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/examples/rule_based_matching/creating_spans_from_matches.rb

@@ -14,7 +14,7 @@ doc = nlp.read("Barack Obama was the 44th president of the United States")
 matches = matcher.match(doc)
 
 matches.each do |match|
-  span = Spacy::Span.new(doc, start_index: match[:start_index], end_index: match[:end_index], options: { label: match[:match_id] })
+  span = Spacy::Span.new(doc, start_index: match[:start_index], end_index: match[:end_index], options: { label: match[:label] })
   puts "#{span.text} / #{span.label}"
 end
 

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