igniter 0.3.1 → 0.4.0

data/lib/igniter/integrations/llm/providers/anthropic.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Igniter
+  module LLM
+    module Providers
+      # Anthropic Claude provider.
+      # Requires ANTHROPIC_API_KEY environment variable or explicit api_key:.
+      #
+      # API docs: https://docs.anthropic.com/en/api/messages
+      #
+      # Key differences from OpenAI-compatible providers:
+      #   - system prompt is a top-level field, not a message
+      #   - response content is an array of typed blocks (text, tool_use)
+      #   - tool definitions use input_schema instead of parameters
+      class Anthropic < Base # rubocop:disable Metrics/ClassLength
+        ANTHROPIC_VERSION = "2023-06-01"
+        API_BASE = "https://api.anthropic.com"
+
+        def initialize(api_key: ENV["ANTHROPIC_API_KEY"], base_url: API_BASE, timeout: 120)
+          super()
+          @api_key = api_key
+          @base_url = base_url.chomp("/")
+          @timeout = timeout
+        end
+
+        # Send a chat completion request.
+        # Extracts any system message from the messages array automatically.
+        def chat(messages:, model:, tools: [], **options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          validate_api_key!
+
+          system_content, chat_messages = extract_system(messages)
+
+          body = {
+            model: model,
+            max_tokens: options.delete(:max_tokens) || 4096,
+            messages: chat_messages
+          }
+          body[:system] = system_content if system_content
+          body[:tools] = normalize_tools(tools) if tools.any?
+          body[:temperature] = options[:temperature] if options[:temperature]
+          body[:top_p] = options[:top_p] if options[:top_p]
+
+          response = post("/v1/messages", body)
+          parse_response(response)
+        end
+
+        private
+
+        def extract_system(messages)
+          system_msg = messages.find { |m| (m[:role] || m["role"]).to_s == "system" }
+          other = messages.reject { |m| (m[:role] || m["role"]).to_s == "system" }
+          system_content = system_msg ? (system_msg[:content] || system_msg["content"]) : nil
+          [system_content, normalize_messages(other)]
+        end
+
+        def parse_response(response) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          content_blocks = response.fetch("content", [])
+
+          text_content = content_blocks
+                         .select { |b| b["type"] == "text" }
+                         .map { |b| b["text"] }
+                         .join
+
+          tool_calls = content_blocks
+                       .select { |b| b["type"] == "tool_use" }
+                       .map do |b|
+            { name: b["name"].to_s, arguments: (b["input"] || {}).transform_keys(&:to_sym) }
+          end
+
+          usage = response.fetch("usage", {})
+          record_usage(
+            prompt_tokens: usage["input_tokens"] || 0,
+            completion_tokens: usage["output_tokens"] || 0
+          )
+
+          { role: :assistant, content: text_content, tool_calls: tool_calls }
+        end
+
+        def normalize_messages(messages)
+          messages.map do |m|
+            { "role" => (m[:role] || m["role"]).to_s, "content" => (m[:content] || m["content"]).to_s }
+          end
+        end
+
+        def normalize_tools(tools)
+          tools.map do |tool|
+            {
+              "name" => tool[:name].to_s,
+              "description" => tool[:description].to_s,
+              "input_schema" => tool.fetch(:parameters) { { "type" => "object", "properties" => {} } }
+            }
+          end
+        end
+
+        def post(path, body) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          uri = URI.parse("#{@base_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.read_timeout = @timeout
+          http.open_timeout = 10
+
+          request = Net::HTTP::Post.new(uri.path, headers)
+          request.body = JSON.generate(body)
+
+          response = http.request(request)
+          handle_response(response)
+        rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
+          raise Igniter::LLM::ProviderError, "Cannot connect to Anthropic API: #{e.message}"
+        end
+
+        def headers
+          {
+            "Content-Type" => "application/json",
+            "x-api-key" => @api_key.to_s,
+            "anthropic-version" => ANTHROPIC_VERSION
+          }
+        end
+
+        def handle_response(response) # rubocop:disable Metrics/MethodLength
+          unless response.is_a?(Net::HTTPSuccess)
+            body = begin
+              JSON.parse(response.body)
+            rescue StandardError
+              {}
+            end
+            error_msg = body.dig("error", "message") || response.body.to_s.slice(0, 200)
+            raise Igniter::LLM::ProviderError, "Anthropic API error #{response.code}: #{error_msg}"
+          end
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Igniter::LLM::ProviderError, "Anthropic returned invalid JSON: #{e.message}"
+        end
+
+        def validate_api_key!
+          return if @api_key && !@api_key.empty?
+
+          raise Igniter::LLM::ConfigurationError,
+                "Anthropic API key not configured. Set ANTHROPIC_API_KEY or pass api_key: to the provider."
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/providers/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    module Providers
+      class Base
+        attr_reader :last_usage
+
+        def chat(messages:, model:, tools: [], **options)
+          raise NotImplementedError, "#{self.class}#chat must be implemented"
+        end
+
+        def complete(prompt:, model:, system: nil, **options)
+          messages = []
+          messages << { role: "system", content: system } if system
+          messages << { role: "user", content: prompt }
+          response = chat(messages: messages, model: model, **options)
+          response[:content]
+        end
+
+        private
+
+        def record_usage(prompt_tokens: 0, completion_tokens: 0)
+          @last_usage = {
+            prompt_tokens: prompt_tokens,
+            completion_tokens: completion_tokens,
+            total_tokens: prompt_tokens + completion_tokens
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/providers/ollama.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Igniter
+  module LLM
+    module Providers
+      # Ollama provider — calls the local Ollama REST API.
+      # Requires Ollama to be running: https://ollama.com
+      #
+      # Ollama API docs: https://github.com/ollama/ollama/blob/main/docs/api.md
+      class Ollama < Base
+        def initialize(base_url: "http://localhost:11434", timeout: 120)
+          super()
+          @base_url = base_url.chomp("/")
+          @timeout = timeout
+        end
+
+        # Send a chat completion request.
+        # Returns: { role: "assistant", content: "...", tool_calls: [...] }
+        def chat(messages:, model:, tools: [], **options) # rubocop:disable Metrics/MethodLength
+          body = {
+            model: model,
+            messages: normalize_messages(messages),
+            stream: false,
+            options: build_options(options)
+          }.compact
+
+          body[:tools] = normalize_tools(tools) if tools.any?
+
+          response = post("/api/chat", body)
+
+          message = response.fetch("message", {})
+          record_usage(
+            prompt_tokens: response["prompt_eval_count"] || 0,
+            completion_tokens: response["eval_count"] || 0
+          )
+
+          {
+            role: message.fetch("role", "assistant").to_sym,
+            content: message.fetch("content", ""),
+            tool_calls: parse_tool_calls(message["tool_calls"])
+          }
+        end
+
+        def models
+          get("/api/tags").fetch("models", []).map { |m| m["name"] }
+        end
+
+        private
+
+        def post(path, body)
+          uri = URI.parse("#{@base_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.read_timeout = @timeout
+          http.open_timeout = 10
+
+          request = Net::HTTP::Post.new(uri.path, { "Content-Type" => "application/json" })
+          request.body = JSON.generate(body)
+
+          response = http.request(request)
+          handle_response(response)
+        rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
+          raise Igniter::LLM::ProviderError, "Cannot connect to Ollama at #{@base_url}: #{e.message}"
+        end
+
+        def get(path)
+          uri = URI.parse("#{@base_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = 10
+          response = http.get(uri.path)
+          handle_response(response)
+        end
+
+        def handle_response(response)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Igniter::LLM::ProviderError,
+                  "Ollama API error #{response.code}: #{response.body.to_s.slice(0, 200)}"
+          end
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Igniter::LLM::ProviderError, "Ollama returned invalid JSON: #{e.message}"
+        end
+
+        def normalize_messages(messages)
+          messages.map do |msg|
+            { "role" => msg[:role].to_s, "content" => msg[:content].to_s }
+          end
+        end
+
+        def normalize_tools(tools)
+          tools.map do |tool|
+            {
+              "type" => "function",
+              "function" => {
+                "name" => tool[:name].to_s,
+                "description" => tool[:description].to_s,
+                "parameters" => tool.fetch(:parameters, { type: "object", properties: {} })
+              }
+            }
+          end
+        end
+
+        def parse_tool_calls(raw)
+          return [] unless raw.is_a?(Array)
+
+          raw.map do |tc|
+            fn = tc["function"] || tc
+            {
+              name: fn["name"].to_s,
+              arguments: parse_arguments(fn["arguments"])
+            }
+          end
+        end
+
+        def parse_arguments(args)
+          case args
+          when Hash then args.transform_keys(&:to_sym)
+          when String then JSON.parse(args).transform_keys(&:to_sym)
+          else {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+
+        def build_options(opts)
+          known = %i[temperature top_p top_k seed num_predict stop]
+          filtered = opts.slice(*known)
+          filtered.empty? ? nil : filtered.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/providers/openai.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Igniter
+  module LLM
+    module Providers
+      # OpenAI provider (also compatible with Azure OpenAI and any OpenAI-compatible API).
+      # Requires OPENAI_API_KEY environment variable or explicit api_key:.
+      #
+      # API docs: https://platform.openai.com/docs/api-reference/chat
+      #
+      # Compatible with: OpenAI, Azure OpenAI, Groq, Together AI,
+      #                  Mistral, DeepSeek, and any OpenAI-compatible endpoint.
+      class OpenAI < Base # rubocop:disable Metrics/ClassLength
+        API_BASE = "https://api.openai.com"
+
+        def initialize(api_key: ENV["OPENAI_API_KEY"], base_url: API_BASE, timeout: 120)
+          super()
+          @api_key = api_key
+          @base_url = base_url.chomp("/")
+          @timeout = timeout
+        end
+
+        # Send a chat completion request.
+        def chat(messages:, model:, tools: [], **options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          validate_api_key!
+
+          body = {
+            model: model,
+            messages: normalize_messages(messages)
+          }
+          body[:tools] = normalize_tools(tools) if tools.any?
+          body[:temperature] = options[:temperature] if options.key?(:temperature)
+          body[:top_p] = options[:top_p] if options.key?(:top_p)
+          body[:max_tokens] = options[:max_tokens] if options.key?(:max_tokens)
+          body[:seed] = options[:seed] if options.key?(:seed)
+          body[:stop] = options[:stop] if options.key?(:stop)
+
+          response = post("/v1/chat/completions", body)
+          parse_response(response)
+        end
+
+        private
+
+        def parse_response(response) # rubocop:disable Metrics/MethodLength
+          message = response.dig("choices", 0, "message") || {}
+          usage = response.fetch("usage", {})
+
+          record_usage(
+            prompt_tokens: usage["prompt_tokens"] || 0,
+            completion_tokens: usage["completion_tokens"] || 0
+          )
+
+          {
+            role: (message["role"] || "assistant").to_sym,
+            content: message["content"].to_s,
+            tool_calls: parse_tool_calls(message["tool_calls"])
+          }
+        end
+
+        def parse_tool_calls(raw)
+          return [] unless raw.is_a?(Array)
+
+          raw.map do |tc|
+            fn = tc["function"] || {}
+            {
+              name: fn["name"].to_s,
+              arguments: parse_arguments(fn["arguments"])
+            }
+          end
+        end
+
+        def parse_arguments(args)
+          case args
+          when Hash then args.transform_keys(&:to_sym)
+          when String then JSON.parse(args).transform_keys(&:to_sym)
+          else {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+
+        def normalize_messages(messages)
+          messages.map do |m|
+            { "role" => (m[:role] || m["role"]).to_s, "content" => (m[:content] || m["content"]).to_s }
+          end
+        end
+
+        def normalize_tools(tools)
+          tools.map do |tool|
+            {
+              "type" => "function",
+              "function" => {
+                "name" => tool[:name].to_s,
+                "description" => tool[:description].to_s,
+                "parameters" => tool.fetch(:parameters) { { "type" => "object", "properties" => {} } }
+              }
+            }
+          end
+        end
+
+        def post(path, body) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          uri = URI.parse("#{@base_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.read_timeout = @timeout
+          http.open_timeout = 10
+
+          request = Net::HTTP::Post.new(uri.path, headers)
+          request.body = JSON.generate(body)
+
+          response = http.request(request)
+          handle_response(response)
+        rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
+          raise Igniter::LLM::ProviderError, "Cannot connect to OpenAI API at #{@base_url}: #{e.message}"
+        end
+
+        def headers
+          {
+            "Content-Type" => "application/json",
+            "Authorization" => "Bearer #{@api_key}"
+          }
+        end
+
+        def handle_response(response) # rubocop:disable Metrics/MethodLength
+          unless response.is_a?(Net::HTTPSuccess)
+            body = begin
+              JSON.parse(response.body)
+            rescue StandardError
+              {}
+            end
+            error_msg = body.dig("error", "message") || response.body.to_s.slice(0, 200)
+            raise Igniter::LLM::ProviderError, "OpenAI API error #{response.code}: #{error_msg}"
+          end
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Igniter::LLM::ProviderError, "OpenAI returned invalid JSON: #{e.message}"
+        end
+
+        def validate_api_key!
+          return if @api_key && !@api_key.empty?
+
+          raise Igniter::LLM::ConfigurationError,
+                "OpenAI API key not configured. Set OPENAI_API_KEY or pass api_key: to the provider."
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "igniter"
+require_relative "llm/config"
+require_relative "llm/context"
+require_relative "llm/providers/base"
+require_relative "llm/providers/ollama"
+require_relative "llm/providers/anthropic"
+require_relative "llm/providers/openai"
+require_relative "llm/executor"
+
+module Igniter
+  module LLM
+    class Error < Igniter::Error; end
+    class ProviderError < Error; end
+    class ConfigurationError < Error; end
+
+    AVAILABLE_PROVIDERS = Config::PROVIDERS
+
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # Returns a memoized provider instance for the given provider name.
+      def provider_instance(name)
+        @provider_instances ||= {}
+        @provider_instances[name.to_sym] ||= build_provider(name.to_sym)
+      end
+
+      # Reset cached provider instances (useful after reconfiguration).
+      def reset_providers!
+        @provider_instances = nil
+      end
+
+      private
+
+      def build_provider(name)
+        case name
+        when :ollama
+          cfg = config.ollama
+          Providers::Ollama.new(base_url: cfg.base_url, timeout: cfg.timeout)
+        when :anthropic
+          cfg = config.anthropic
+          Providers::Anthropic.new(api_key: cfg.api_key, base_url: cfg.base_url, timeout: cfg.timeout)
+        when :openai
+          cfg = config.openai
+          Providers::OpenAI.new(api_key: cfg.api_key, base_url: cfg.base_url, timeout: cfg.timeout)
+        else
+          raise ConfigurationError, "Unknown LLM provider: #{name}. Available: #{AVAILABLE_PROVIDERS.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/rails/cable_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Rails
+    # ActionCable channel mixin for streaming contract execution events.
+    #
+    # Usage:
+    #   class OrderChannel < ApplicationCable::Channel
+    #     include Igniter::Rails::CableAdapter
+    #
+    #     subscribed do
+    #       stream_contract(OrderContract, execution_id: params[:execution_id])
+    #     end
+    #   end
+    #
+    # Broadcasts events as:
+    #   { type: "node_succeeded", node: "payment", status: "succeeded", payload: { ... } }
+    module CableAdapter
+      def stream_contract(contract_class, execution_id:, store: nil)
+        resolved_store = store || Igniter.execution_store
+        snapshot = resolved_store.fetch(execution_id)
+        instance = contract_class.restore(snapshot)
+
+        instance.subscribe do |event|
+          broadcast_igniter_event(event, execution_id)
+        end
+
+        @_igniter_executions ||= []
+        @_igniter_executions << instance
+      rescue Igniter::ResolutionError => e
+        transmit({ type: "error", message: e.message })
+      end
+
+      private
+
+      def broadcast_igniter_event(event, execution_id)
+        transmit({
+          type: event.type.to_s,
+          execution_id: execution_id,
+          node: event.node_name,
+          path: event.path,
+          status: event.status,
+          payload: event.payload,
+          timestamp: event.timestamp&.iso8601
+        }.compact)
+      end
+    end
+  end
+end

data/lib/igniter/integrations/rails/contract_job.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Rails
+    # Base ActiveJob class for async contract execution.
+    #
+    # Usage:
+    #   class ProcessOrderJob < Igniter::Rails::ContractJob
+    #     contract OrderContract
+    #   end
+    #
+    #   ProcessOrderJob.perform_later(order_id: "ord-123")
+    #   ProcessOrderJob.perform_now(order_id: "ord-123")
+    #
+    # The job starts the contract and persists it to the configured store.
+    # If the contract has correlation keys, the execution can be resumed
+    # later via Contract.deliver_event.
+    class ContractJob
+      # No dependency on ActiveJob here — this class acts as a blueprint.
+      # When Rails is present, subclasses inherit from ApplicationJob automatically
+      # if the user adds `< ApplicationJob` (the recommended pattern).
+
+      class << self
+        def contract(klass = nil)
+          @contract_class = klass if klass
+          @contract_class
+        end
+
+        def store(store_instance = nil)
+          @store = store_instance if store_instance
+          @store || Igniter.execution_store
+        end
+
+        # Wraps perform in an ActiveJob-compatible interface.
+        # Call this when Rails is available to get ActiveJob queueing.
+        def perform_later(**inputs)
+          if defined?(::ActiveJob::Base)
+            ActiveJobAdapter.perform_later(contract_class: contract, inputs: inputs, store: store)
+          else
+            perform_now(**inputs)
+          end
+        end
+
+        def perform_now(**inputs)
+          contract.start(inputs, store: store)
+        end
+      end
+
+      # Included by ActiveJobAdapter to bridge ActiveJob lifecycle.
+      module Perform
+        def perform(contract_class_name:, inputs:, store_class: nil, store_config: nil)
+          klass = Object.const_get(contract_class_name)
+          resolved_store = resolve_store(store_class, store_config)
+          klass.start(inputs.transform_keys(&:to_sym), store: resolved_store)
+        end
+
+        private
+
+        def resolve_store(store_class, _store_config)
+          return Igniter.execution_store unless store_class
+
+          Object.const_get(store_class).new
+        end
+      end
+    end
+
+    # ActiveJob adapter — only defined when ActiveJob is available.
+    if defined?(::ActiveJob::Base)
+      class ActiveJobAdapter < ::ActiveJob::Base
+        include ContractJob::Perform
+
+        queue_as :igniter
+      end
+    end
+  end
+end

data/lib/igniter/integrations/rails/generators/contract/contract_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Igniter
+  module Rails
+    module Generators
+      class ContractGenerator < ::Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+        desc "Creates an Igniter contract."
+
+        class_option :correlate_by, type: :array, default: [], desc: "Correlation key names"
+        class_option :inputs, type: :array, default: [], desc: "Input names"
+        class_option :outputs, type: :array, default: ["result"], desc: "Output names"
+
+        def create_contract
+          template "contract.rb.tt", File.join("app/contracts", class_path, "#{file_name}_contract.rb")
+        end
+      end
+    end
+  end
+end