flowengine 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6118d723586350e431080d822f01dbda45c9cc58257dd812e4d3dd7c30f8de6
-  data.tar.gz: 606d8ac60526863acb699c166b396d00baa29fdedb009df4c4a4b6bfb4a783a0
+  metadata.gz: af012989841606174c73ceabb8895212385fe8896546229bf4f03f9beec72ccb
+  data.tar.gz: 0d1928d509626fba026b404c411513a10769af29890fc8ceccc090024c364a01
 SHA512:
-  metadata.gz: 00c92c2094931b5c4d427aec5e2de4bce98d733be459aadd367ce58f3d64564c7332c53d8810d37d1f5d95352439572fe2252eb6068a4fa9278c0e1cef223c78
-  data.tar.gz: d9bc34f2cfeb87ee7e6b6bc75e429903db85d4d2482a517240da2ab995bdd38202a03f3585f54a00e5e1d263751cf9f82225e34303889bbb67cdcbc0a7e47e92
+  metadata.gz: 7e49a5c46ed5eb3bdf1025134f94c3b8bb921d4234f7bdc9b081448d410e6bbe933f529fdcdb226099334c760bfeadda947c038c7038f6234e66e35c74cdeb96
+  data.tar.gz: 05d0dced1e4452a20b09b55eae0673e4ebb6e9fc2e76adfcee813148474a71cdb08a69bef9a8f2b9bf388c5aa314a7aaf803259186511c75387c43ce7b1a69a3

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-10 19:57:08 UTC using RuboCop version 1.85.1.
+# on 2026-03-10 21:46:24 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new

data/README.md

@@ -144,9 +144,13 @@ end
 ### Using the Introduction at Runtime
 
 ```ruby
-# 1. Configure an LLM adapter and client
-adapter = FlowEngine::LLM::OpenAIAdapter.new(api_key: ENV["OPENAI_API_KEY"])
-client = FlowEngine::LLM::Client.new(adapter: adapter, model: "gpt-4o-mini")
+# 1. Auto-detect adapter from environment (checks ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY)
+client = FlowEngine::LLM.auto_client
+
+# Or explicitly choose a provider:
+# client = FlowEngine::LLM.auto_client(anthropic_api_key: "sk-ant-...")
+# client = FlowEngine::LLM.auto_client(openai_api_key: "sk-...", model: "gpt-4o")
+# client = FlowEngine::LLM.auto_client(gemini_api_key: "AIza...")
 
 # 2. Create the engine and submit the introduction
 engine = FlowEngine::Engine.new(definition)
@@ -185,10 +189,18 @@ engine.submit_introduction("My SSN is 123-45-6789", llm_client: client)
 
 ### Custom LLM Adapters
 
-The LLM integration uses an adapter pattern. The gem ships with an OpenAI adapter (via the [`ruby_llm`](https://github.com/crmne/ruby_llm) gem), but you can create adapters for any provider:
+The LLM integration uses an adapter pattern. The gem ships with three adapters (all via the [`ruby_llm`](https://github.com/crmne/ruby_llm) gem):
+
+| Adapter | Env Variable | Default Model |
+|---------|-------------|---------------|
+| `AnthropicAdapter` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| `OpenAIAdapter` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `GeminiAdapter` | `GEMINI_API_KEY` | `gemini-2.0-flash` |
+
+You can also create adapters for any other provider:
 
 ```ruby
-class MyAnthropicAdapter < FlowEngine::LLM::Adapter
+class MyCustomAdapter < FlowEngine::LLM::Adapter
   def initialize(api_key:)
     super()
     @api_key = api_key
@@ -200,8 +212,8 @@ class MyAnthropicAdapter < FlowEngine::LLM::Adapter
   end
 end
 
-adapter = MyAnthropicAdapter.new(api_key: ENV["ANTHROPIC_API_KEY"])
-client = FlowEngine::LLM::Client.new(adapter: adapter, model: "claude-sonnet-4-20250514")
+adapter = MyCustomAdapter.new(api_key: ENV["MY_API_KEY"])
+client = FlowEngine::LLM::Client.new(adapter: adapter, model: "my-model")
 ```
 
 ### State Persistence
@@ -236,8 +248,11 @@ The core has **zero UI logic**, **zero DB logic**, and **zero framework dependen
 | `Engine` | Stateful runtime: tracks current step, answers, history, and introduction |
 | `Validation::Adapter` | Interface for pluggable validation (dry-validation, JSON Schema, etc.) |
 | `LLM::Adapter` | Abstract interface for LLM API calls |
+| `LLM::AnthropicAdapter` | Anthropic/Claude implementation via `ruby_llm` gem |
 | `LLM::OpenAIAdapter` | OpenAI implementation via `ruby_llm` gem |
+| `LLM::GeminiAdapter` | Google Gemini implementation via `ruby_llm` gem |
 | `LLM::Client` | High-level: builds prompt, calls adapter, parses JSON response |
+| `LLM.auto_client` | Factory: auto-detects provider from environment API keys |
 | `LLM::SensitiveDataFilter` | Rejects text containing SSN, ITIN, EIN patterns |
 | `Graph::MermaidExporter` | Exports the flow definition as a Mermaid diagram |
 

data/lib/flowengine/llm/anthropic_adapter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module FlowEngine
+  module LLM
+    # Anthropic adapter using the ruby_llm gem. Configures the API key
+    # and delegates chat calls to RubyLLM's conversation interface.
+    class AnthropicAdapter < Adapter
+      DEFAULT_MODEL = "claude-sonnet-4-20250514"
+
+      # @param api_key [String, nil] Anthropic API key; falls back to ANTHROPIC_API_KEY env var
+      # @raise [LLMError] if no API key is available
+      def initialize(api_key: nil)
+        super()
+        @api_key = api_key || ENV.fetch("ANTHROPIC_API_KEY", nil)
+        raise LLMError, "Anthropic API key not provided and ANTHROPIC_API_KEY not set" unless @api_key
+      end
+
+      # @param system_prompt [String] system instructions
+      # @param user_prompt [String] user's text
+      # @param model [String] Anthropic model identifier
+      # @return [String] response content from the LLM
+      def chat(system_prompt:, user_prompt:, model: DEFAULT_MODEL)
+        configure_ruby_llm!
+        conversation = RubyLLM.chat(model: model)
+        response = conversation.with_instructions(system_prompt).ask(user_prompt)
+        response.content
+      end
+
+      private
+
+      def configure_ruby_llm!
+        RubyLLM.configure do |config|
+          config.anthropic_api_key = @api_key
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm/gemini_adapter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module FlowEngine
+  module LLM
+    # Google Gemini adapter using the ruby_llm gem. Configures the API key
+    # and delegates chat calls to RubyLLM's conversation interface.
+    class GeminiAdapter < Adapter
+      DEFAULT_MODEL = "gemini-2.0-flash"
+
+      # @param api_key [String, nil] Gemini API key; falls back to GEMINI_API_KEY env var
+      # @raise [LLMError] if no API key is available
+      def initialize(api_key: nil)
+        super()
+        @api_key = api_key || ENV.fetch("GEMINI_API_KEY", nil)
+        raise LLMError, "Gemini API key not provided and GEMINI_API_KEY not set" unless @api_key
+      end
+
+      # @param system_prompt [String] system instructions
+      # @param user_prompt [String] user's text
+      # @param model [String] Gemini model identifier
+      # @return [String] response content from the LLM
+      def chat(system_prompt:, user_prompt:, model: DEFAULT_MODEL)
+        configure_ruby_llm!
+        conversation = RubyLLM.chat(model: model)
+        response = conversation.with_instructions(system_prompt).ask(user_prompt)
+        response.content
+      end
+
+      private
+
+      def configure_ruby_llm!
+        RubyLLM.configure do |config|
+          config.gemini_api_key = @api_key
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm.rb

@@ -2,6 +2,8 @@
 
 require_relative "llm/adapter"
 require_relative "llm/openai_adapter"
+require_relative "llm/anthropic_adapter"
+require_relative "llm/gemini_adapter"
 require_relative "llm/sensitive_data_filter"
 require_relative "llm/system_prompt_builder"
 require_relative "llm/client"
@@ -10,5 +12,37 @@ module FlowEngine
   # Namespace for LLM integration: adapters, system prompt building,
   # sensitive data filtering, and the high-level Client.
   module LLM
+    # Provider registry: ordered by priority (first match wins).
+    # Each entry maps an explicit kwarg name to [env_var, adapter_class, default_model].
+    PROVIDERS = [
+      [:anthropic_api_key, "ANTHROPIC_API_KEY", AnthropicAdapter, AnthropicAdapter::DEFAULT_MODEL],
+      [:openai_api_key, "OPENAI_API_KEY", OpenAIAdapter, "gpt-4o-mini"],
+      [:gemini_api_key, "GEMINI_API_KEY", GeminiAdapter, GeminiAdapter::DEFAULT_MODEL]
+    ].freeze
+
+    # Builds an adapter and Client by detecting which API key is available
+    # in the environment. Priority: Anthropic > OpenAI > Gemini.
+    #
+    # @param anthropic_api_key [String, nil] explicit Anthropic key
+    # @param openai_api_key [String, nil] explicit OpenAI key
+    # @param gemini_api_key [String, nil] explicit Gemini key
+    # @param model [String, nil] override model; auto-selected if nil
+    # @return [Client] configured client with the detected adapter
+    # @raise [LLMError] if no API key is found for any provider
+    def self.auto_client(anthropic_api_key: nil, openai_api_key: nil, gemini_api_key: nil, model: nil)
+      explicit_keys = { anthropic_api_key: anthropic_api_key, openai_api_key: openai_api_key,
+                        gemini_api_key: gemini_api_key }
+
+      PROVIDERS.each do |kwarg, env_var, adapter_class, default_model|
+        key = explicit_keys[kwarg] || ENV.fetch(env_var, nil)
+        next unless key
+
+        adapter = adapter_class.new(api_key: key)
+        return Client.new(adapter: adapter, model: model || default_model)
+      end
+
+      env_vars = PROVIDERS.map { |_, env_var, _, _| env_var }.join(", ")
+      raise FlowEngine::LLMError, "No LLM API key found. Set #{env_vars}"
+    end
   end
 end

data/lib/flowengine/version.rb

@@ -2,5 +2,5 @@
 
 module FlowEngine
   # Semantic version of the flowengine gem (major.minor.patch).
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -127,7 +127,9 @@ files:
 - lib/flowengine/introduction.rb
 - lib/flowengine/llm.rb
 - lib/flowengine/llm/adapter.rb
+- lib/flowengine/llm/anthropic_adapter.rb
 - lib/flowengine/llm/client.rb
+- lib/flowengine/llm/gemini_adapter.rb
 - lib/flowengine/llm/openai_adapter.rb
 - lib/flowengine/llm/sensitive_data_filter.rb
 - lib/flowengine/llm/system_prompt_builder.rb