ai_record_finder 0.1.2 → 0.2.0

data/README.md

@@ -4,7 +4,7 @@
 
 It is designed for B2B Rails applications that need strict query safety, tenant boundaries, and model-level authorization.
 
-Documentation homepage: <https://github.com/JijoBose/ai_record_finder/blob/main/docs/HOME.md>
+Documentation homepage: `docs/HOME.md`
 
 ## Installation
 
@@ -38,6 +38,49 @@ AIRecordFinder.configure do |config|
 end
 ```
 
+## Providers
+
+`ai_record_finder` ships with native adapters for two providers. Select one
+with `config.provider` (default: `:openai`).
+
+### OpenAI (default)
+
+```ruby
+AIRecordFinder.configure do |config|
+  config.provider = :openai
+  config.api_key  = ENV.fetch("OPENAI_API_KEY")
+  # config.model_name defaults to "gpt-4o-mini"
+end
+```
+
+This also covers any OpenAI-compatible endpoint (Azure OpenAI, OpenRouter,
+LiteLLM, Ollama, vLLM, ...) — point `api_base_url` at the gateway:
+
+```ruby
+config.api_base_url = "https://openrouter.ai/api/v1"
+```
+
+### Anthropic (native Messages API)
+
+The Anthropic adapter talks to the native `/v1/messages` API (`x-api-key`
+auth, `anthropic-version` header, top-level `system` prompt, `content`-block
+responses) — not the OpenAI-compatibility shim.
+
+```ruby
+AIRecordFinder.configure do |config|
+  config.provider = :anthropic
+  config.api_key  = ENV.fetch("ANTHROPIC_API_KEY")
+  config.model_name = "claude-sonnet-4-6" # default; override for your account access
+
+  # Anthropic-specific knobs:
+  config.max_tokens        = 1024         # required by the Messages API; default 1024
+  config.anthropic_version = "2023-06-01" # default
+end
+```
+
+When `provider` is set, `model_name` and `api_base_url` resolve to that
+provider's defaults unless you assign them explicitly.
+
 ## Usage
 
 ```ruby
@@ -70,10 +113,14 @@ For associated-table constraints, reference fields as `association.column` in na
 
 Core components:
 
-- `AIRecordFinder::Configuration`: runtime safety and API settings.
+- `AIRecordFinder::Configuration`: runtime safety, provider, and API settings.
 - `AIRecordFinder::SchemaIntrospector`: model table/column/association/enum summary.
 - `AIRecordFinder::PromptBuilder`: strict system prompt with schema and DSL contract.
-- `AIRecordFinder::Client`: OpenAI-compatible HTTP transport (Faraday).
+- `AIRecordFinder::Providers`: provider registry and per-vendor transports
+  (`Providers::OpenAI`, `Providers::Anthropic`) built on a shared
+  `Providers::Base` (Faraday).
+- `AIRecordFinder::Client`: transport facade that selects and delegates to the
+  configured provider.
 - `AIRecordFinder::AIAdapter`: AI response extraction and JSON parsing.
 - `AIRecordFinder::DSLParser`: validates DSL structure and values.
 - `AIRecordFinder::SafetyGuard`: model authorization, limit policies, join policies, tenant scope.
@@ -86,6 +133,7 @@ Core components:
 - `AIRecordFinder::InvalidDSL`
 - `AIRecordFinder::AIResponseError`
 - `AIRecordFinder::UnauthorizedModel`
+- `AIRecordFinder::ConfigurationError` (missing API key, unknown provider)
 
 ## Testing
 

data/docs/HOME.md

@@ -1,12 +1,12 @@
 # AIRecordFinder Documentation
 
-Project documentation is publicly available on GitHub.
+This repository is private and uses project-owned documentation.
 
 ## Start Here
 
-- Developer guide: <https://github.com/JijoBose/ai_record_finder/blob/main/docs/DEVELOPER_GUIDE.md>
-- Package overview: <https://github.com/JijoBose/ai_record_finder/blob/main/README.md>
-- Release history: <https://github.com/JijoBose/ai_record_finder/blob/main/CHANGELOG.md>
+- Developer guide: `docs/DEVELOPER_GUIDE.md`
+- Package overview: `README.md`
+- Release history: `CHANGELOG.md`
 
 ## Scope
 

data/lib/ai_record_finder/client.rb

@@ -1,69 +1,21 @@
 # frozen_string_literal: true
 
-require "faraday"
-require "json"
+require_relative "providers"
 
 module AIRecordFinder
-  # HTTP client for OpenAI-compatible chat completion APIs.
+  # Transport facade. Selects the provider configured via
+  # `configuration.provider` and delegates chat completion to it.
+  #
+  # Kept as a stable entry point so callers (and AIAdapter) depend on a single
+  # `#chat_completion(system_prompt:, user_prompt:)` interface regardless of
+  # whether the backing provider is OpenAI, Anthropic, or another vendor.
   class Client
-    CHAT_COMPLETIONS_PATH = "/chat/completions"
-
-    def initialize(configuration:)
-      @configuration = configuration
-      validate_configuration!
+    def initialize(configuration:, connection: nil)
+      @provider = Providers.build(configuration: configuration, connection: connection)
     end
 
     def chat_completion(system_prompt:, user_prompt:)
-      response = connection.post(CHAT_COMPLETIONS_PATH) do |req|
-        req.headers["Authorization"] = "Bearer #{@configuration.api_key}"
-        req.headers["Content-Type"] = "application/json"
-        req.body = JSON.generate(payload(system_prompt, user_prompt))
-      end
-
-      parsed = parse_body(response.body)
-      extract_content(parsed)
-    rescue Faraday::Error => e
-      raise AIResponseError, "AI request failed: #{e.message}"
-    end
-
-    private
-
-    def connection
-      @connection ||= Faraday.new(url: @configuration.api_base_url) do |f|
-        f.options.timeout = @configuration.request_timeout
-        f.options.open_timeout = @configuration.request_timeout
-        f.adapter Faraday.default_adapter
-      end
-    end
-
-    def payload(system_prompt, user_prompt)
-      {
-        model: @configuration.model_name,
-        temperature: @configuration.temperature,
-        messages: [
-          { role: "system", content: system_prompt },
-          { role: "user", content: user_prompt }
-        ]
-      }
-    end
-
-    def parse_body(body)
-      JSON.parse(body)
-    rescue JSON::ParserError
-      raise AIResponseError, "AI response body is not valid JSON"
-    end
-
-    def extract_content(parsed)
-      choices = parsed["choices"]
-      return choices.first.dig("message", "content") if choices.is_a?(Array) && choices.first
-
-      raise AIResponseError, "AI response missing choices.message.content"
-    end
-
-    def validate_configuration!
-      if @configuration.api_key.to_s.strip.empty?
-        raise AIResponseError, "Missing API key. Set AIRecordFinder.configure { |c| c.api_key = ... }"
-      end
+      @provider.chat_completion(system_prompt: system_prompt, user_prompt: user_prompt)
     end
   end
 end

data/lib/ai_record_finder/configuration.rb

@@ -3,24 +3,68 @@
 module AIRecordFinder
   # Runtime configuration for AIRecordFinder.
   class Configuration
-    DEFAULT_MODEL_NAME = "gpt-4o-mini"
-    DEFAULT_API_BASE_URL = "https://api.openai.com/v1"
+    DEFAULT_PROVIDER = :openai
     DEFAULT_MAX_LIMIT = 100
     DEFAULT_TIMEOUT = 15
+    DEFAULT_MAX_TOKENS = 1024
+    DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
-    attr_accessor :api_key, :model_name, :max_limit, :allowed_models,
-                  :api_base_url, :request_timeout, :temperature,
-                  :allowed_associations
+    # Per-provider defaults for endpoint and model. Used only when the
+    # corresponding setting is not explicitly assigned.
+    PROVIDER_DEFAULTS = {
+      openai: {
+        api_base_url: "https://api.openai.com/v1",
+        model_name: "gpt-4o-mini"
+      },
+      anthropic: {
+        api_base_url: "https://api.anthropic.com/v1",
+        model_name: "claude-sonnet-4-6"
+      }
+    }.freeze
+
+    # Backwards-compatible constants (OpenAI defaults).
+    DEFAULT_MODEL_NAME = PROVIDER_DEFAULTS[:openai][:model_name]
+    DEFAULT_API_BASE_URL = PROVIDER_DEFAULTS[:openai][:api_base_url]
+
+    # `max_tokens` and `anthropic_version` are consumed only by the Anthropic
+    # adapter; the OpenAI adapter ignores them.
+    attr_accessor :api_key, :max_limit, :allowed_models, :request_timeout,
+                  :temperature, :allowed_associations, :max_tokens,
+                  :anthropic_version
+    attr_writer :provider, :model_name, :api_base_url
 
     def initialize
-      @api_key = nil
-      @model_name = DEFAULT_MODEL_NAME
+      @api_key = @model_name = @api_base_url = nil
+      @provider = DEFAULT_PROVIDER
       @max_limit = DEFAULT_MAX_LIMIT
       @allowed_models = []
-      @api_base_url = DEFAULT_API_BASE_URL
       @request_timeout = DEFAULT_TIMEOUT
       @temperature = 0.0
       @allowed_associations = {}
+      @max_tokens = DEFAULT_MAX_TOKENS
+      @anthropic_version = DEFAULT_ANTHROPIC_VERSION
+    end
+
+    # Normalized provider symbol (e.g. :openai, :anthropic).
+    def provider
+      @provider.to_s.strip.downcase.to_sym
+    end
+
+    # Explicit model name, or the provider default when unset.
+    def model_name
+      @model_name || provider_default(:model_name)
+    end
+
+    # Explicit base URL, or the provider default when unset.
+    def api_base_url
+      @api_base_url || provider_default(:api_base_url)
+    end
+
+    private
+
+    def provider_default(key)
+      defaults = PROVIDER_DEFAULTS[provider] || PROVIDER_DEFAULTS[DEFAULT_PROVIDER]
+      defaults.fetch(key)
     end
   end
 end

data/lib/ai_record_finder/errors.rb

@@ -15,4 +15,7 @@ module AIRecordFinder
 
   # Raised when a model is not explicitly whitelisted.
   class UnauthorizedModel < Error; end
+
+  # Raised when the gem is misconfigured (missing API key, unknown provider, ...).
+  class ConfigurationError < Error; end
 end

data/lib/ai_record_finder/providers/anthropic.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AIRecordFinder
+  module Providers
+    # Anthropic native Messages API (https://api.anthropic.com/v1/messages).
+    #
+    # Differs from OpenAI: x-api-key auth + anthropic-version header, a
+    # top-level `system` prompt, a required `max_tokens`, and a response whose
+    # text lives in a `content` array of typed blocks rather than `choices`.
+    class Anthropic < Base
+      ENDPOINT_PATH = "messages"
+
+      private
+
+      def endpoint_path
+        ENDPOINT_PATH
+      end
+
+      def request_headers
+        {
+          "x-api-key" => configuration.api_key,
+          "anthropic-version" => configuration.anthropic_version,
+          "Content-Type" => "application/json"
+        }
+      end
+
+      def request_payload(system_prompt, user_prompt)
+        {
+          model: configuration.model_name,
+          max_tokens: configuration.max_tokens,
+          temperature: configuration.temperature,
+          system: system_prompt,
+          messages: [
+            { role: "user", content: user_prompt }
+          ]
+        }
+      end
+
+      def extract_content(parsed)
+        blocks = parsed["content"]
+        if blocks.is_a?(Array)
+          text_block = blocks.find { |block| block.is_a?(Hash) && block["type"] == "text" }
+          return text_block["text"] if text_block && !text_block["text"].nil?
+        end
+
+        raise AIResponseError, "AI response missing content text block"
+      end
+    end
+  end
+end

data/lib/ai_record_finder/providers/base.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module AIRecordFinder
+  module Providers
+    # Shared HTTP transport for chat-style LLM providers.
+    #
+    # Subclasses implement the provider-specific contract:
+    #   #endpoint_path, #request_headers, #request_payload, #extract_content
+    #
+    # Endpoint paths MUST be relative (no leading slash) so they append to the
+    # configured base URL's path (e.g. ".../v1") instead of replacing it.
+    class Base
+      def initialize(configuration:, connection: nil)
+        @configuration = configuration
+        @connection = connection
+        validate_configuration!
+      end
+
+      def chat_completion(system_prompt:, user_prompt:)
+        response = post_request(system_prompt, user_prompt)
+        ensure_success!(response)
+        extract_content(parse_body(response))
+      rescue Faraday::Error => e
+        raise AIResponseError, "AI request failed: #{e.message}"
+      end
+
+      private
+
+      attr_reader :configuration
+
+      def post_request(system_prompt, user_prompt)
+        connection.post(endpoint_path) do |req|
+          request_headers.each { |name, value| req.headers[name] = value }
+          req.body = JSON.generate(request_payload(system_prompt, user_prompt))
+        end
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: configuration.api_base_url) do |f|
+          f.options.timeout = configuration.request_timeout
+          f.options.open_timeout = configuration.request_timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def parse_body(response)
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        raise AIResponseError, "AI response body is not valid JSON"
+      end
+
+      # Faraday does not raise on non-2xx, so check the status explicitly. Error
+      # bodies are not guaranteed to be JSON (a gateway may return HTML/plain
+      # text), so this must surface a useful detail without depending on a
+      # successful parse — hence it runs before parse_body.
+      def ensure_success!(response)
+        return if response.success?
+
+        raise AIResponseError, "AI request failed: #{error_detail(response)}"
+      end
+
+      # Both OpenAI and Anthropic nest the human-readable error under
+      # error.message; fall back to the HTTP status for non-JSON error bodies.
+      def error_detail(response)
+        parsed = JSON.parse(response.body.to_s)
+        (parsed.is_a?(Hash) && parsed.dig("error", "message")) || "HTTP #{response.status}"
+      rescue JSON::ParserError
+        "HTTP #{response.status}"
+      end
+
+      def validate_configuration!
+        return unless configuration.api_key.to_s.strip.empty?
+
+        raise ConfigurationError, "Missing API key. Set AIRecordFinder.configure { |c| c.api_key = ... }"
+      end
+
+      # --- Provider contract (subclasses must override) ---
+
+      def endpoint_path
+        raise NotImplementedError, "#{self.class} must implement #endpoint_path"
+      end
+
+      def request_headers
+        raise NotImplementedError, "#{self.class} must implement #request_headers"
+      end
+
+      def request_payload(_system_prompt, _user_prompt)
+        raise NotImplementedError, "#{self.class} must implement #request_payload"
+      end
+
+      def extract_content(_parsed)
+        raise NotImplementedError, "#{self.class} must implement #extract_content"
+      end
+    end
+  end
+end

data/lib/ai_record_finder/providers/openai.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AIRecordFinder
+  module Providers
+    # OpenAI (and OpenAI-compatible) Chat Completions API.
+    class OpenAI < Base
+      ENDPOINT_PATH = "chat/completions"
+
+      private
+
+      def endpoint_path
+        ENDPOINT_PATH
+      end
+
+      def request_headers
+        {
+          "Authorization" => "Bearer #{configuration.api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+
+      def request_payload(system_prompt, user_prompt)
+        {
+          model: configuration.model_name,
+          temperature: configuration.temperature,
+          messages: [
+            { role: "system", content: system_prompt },
+            { role: "user", content: user_prompt }
+          ]
+        }
+      end
+
+      def extract_content(parsed)
+        choices = parsed["choices"]
+        if choices.is_a?(Array) && choices.first
+          # content is null when the model replies with tool_calls only.
+          content = choices.first.dig("message", "content")
+          return content unless content.nil?
+        end
+
+        raise AIResponseError, "AI response missing choices[0].message.content"
+      end
+    end
+  end
+end

data/lib/ai_record_finder/providers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "providers/base"
+require_relative "providers/openai"
+require_relative "providers/anthropic"
+
+module AIRecordFinder
+  # Provider strategy registry. Maps a configured provider symbol to the
+  # concrete transport that speaks that vendor's chat API.
+  module Providers
+    REGISTRY = {
+      openai: OpenAI,
+      anthropic: Anthropic
+    }.freeze
+
+    # @param configuration [AIRecordFinder::Configuration]
+    # @param connection [Faraday::Connection, nil] injectable transport (tests)
+    # @return [AIRecordFinder::Providers::Base]
+    def self.build(configuration:, connection: nil)
+      provider_class = REGISTRY[configuration.provider]
+      unless provider_class
+        raise ConfigurationError,
+              "Unknown provider #{configuration.provider.inspect}. " \
+              "Supported providers: #{REGISTRY.keys.join(", ")}"
+      end
+
+      provider_class.new(configuration: configuration, connection: connection)
+    end
+
+    def self.supported
+      REGISTRY.keys
+    end
+  end
+end

data/lib/ai_record_finder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AIRecordFinder
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/ai_record_finder.rb

@@ -3,6 +3,7 @@
 require_relative "ai_record_finder/version"
 require_relative "ai_record_finder/errors"
 require_relative "ai_record_finder/configuration"
+require_relative "ai_record_finder/providers"
 require_relative "ai_record_finder/client"
 require_relative "ai_record_finder/schema_introspector"
 require_relative "ai_record_finder/prompt_builder"

data/spec/client_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "json"
+
+RSpec.describe AIRecordFinder::Client do
+  def stub_connection(base_url, expected_path, response)
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.post(expected_path) do |_env|
+      [200, { "Content-Type" => "application/json" }, JSON.generate(response)]
+    end
+    Faraday.new(url: base_url) { |f| f.adapter :test, stubs }
+  end
+
+  it "delegates to the OpenAI provider by default" do
+    cfg = AIRecordFinder::Configuration.new.tap { |c| c.api_key = "k" }
+    conn = stub_connection(
+      cfg.api_base_url, "/v1/chat/completions",
+      { "choices" => [{ "message" => { "content" => "openai-out" } }] }
+    )
+
+    client = described_class.new(configuration: cfg, connection: conn)
+
+    expect(client.chat_completion(system_prompt: "s", user_prompt: "u")).to eq("openai-out")
+  end
+
+  it "delegates to the Anthropic provider when configured" do
+    cfg = AIRecordFinder::Configuration.new.tap do |c|
+      c.api_key = "k"
+      c.provider = :anthropic
+    end
+    conn = stub_connection(
+      cfg.api_base_url, "/v1/messages",
+      { "content" => [{ "type" => "text", "text" => "anthropic-out" }] }
+    )
+
+    client = described_class.new(configuration: cfg, connection: conn)
+
+    expect(client.chat_completion(system_prompt: "s", user_prompt: "u")).to eq("anthropic-out")
+  end
+
+  it "raises ConfigurationError when the API key is missing" do
+    cfg = AIRecordFinder::Configuration.new
+
+    expect { described_class.new(configuration: cfg) }
+      .to raise_error(AIRecordFinder::ConfigurationError, /Missing API key/)
+  end
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe AIRecordFinder::Configuration do
+  subject(:config) { described_class.new }
+
+  it "defaults to the OpenAI provider with its model and base URL" do
+    expect(config.provider).to eq(:openai)
+    expect(config.model_name).to eq("gpt-4o-mini")
+    expect(config.api_base_url).to eq("https://api.openai.com/v1")
+  end
+
+  it "resolves Anthropic defaults when the provider is :anthropic" do
+    config.provider = :anthropic
+
+    expect(config.model_name).to eq("claude-sonnet-4-6")
+    expect(config.api_base_url).to eq("https://api.anthropic.com/v1")
+  end
+
+  it "normalizes provider strings and casing to a symbol" do
+    config.provider = "Anthropic"
+
+    expect(config.provider).to eq(:anthropic)
+  end
+
+  it "prefers explicitly assigned model_name and api_base_url over provider defaults" do
+    config.provider = :anthropic
+    config.model_name = "claude-opus-4-8"
+    config.api_base_url = "https://gateway.internal/v1"
+
+    expect(config.model_name).to eq("claude-opus-4-8")
+    expect(config.api_base_url).to eq("https://gateway.internal/v1")
+  end
+
+  it "falls back to OpenAI defaults for an unrecognized provider" do
+    config.provider = :unknown
+
+    expect(config.model_name).to eq("gpt-4o-mini")
+    expect(config.api_base_url).to eq("https://api.openai.com/v1")
+  end
+
+  it "exposes Anthropic-specific defaults" do
+    expect(config.max_tokens).to eq(1024)
+    expect(config.anthropic_version).to eq("2023-06-01")
+  end
+end