igniter 0.3.1 → 0.4.3

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

data/lib/igniter/integrations/rails/generators/install/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Igniter
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+        desc "Creates an Igniter initializer in your application."
+
+        def copy_initializer
+          template "igniter.rb.tt", "config/initializers/igniter.rb"
+        end
+
+        def create_contracts_directory
+          empty_directory "app/contracts"
+          create_file "app/contracts/.keep"
+        end
+
+        def show_readme
+          say "", :green
+          say "✓ Igniter installed!", :green
+          say ""
+          say "Next steps:"
+          say "  1. Configure your store in config/initializers/igniter.rb"
+          say "  2. Generate a contract: rails g igniter:contract YourContractName"
+          say ""
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "igniter.configure_store" do
+        # Auto-configure store based on available adapters unless already set
+        next if Igniter.instance_variable_defined?(:@execution_store)
+
+        Igniter.execution_store =
+          if defined?(Redis) && ::Rails.application.config.respond_to?(:redis)
+            Igniter::Runtime::Stores::RedisStore.new(::Redis.current)
+          else
+            Igniter::Runtime::Stores::MemoryStore.new
+          end
+      end
+
+      initializer "igniter.load_contracts" do
+        ::Rails.autoloaders.main.on_load("ApplicationContract") do
+          # Hook point for future eager loading of compiled contracts
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Rails
+    # Controller mixin for delivering external events to running contracts.
+    #
+    # Usage:
+    #   class WebhooksController < ApplicationController
+    #     include Igniter::Rails::WebhookHandler
+    #
+    #     def stripe
+    #       deliver_event_for(
+    #         OrderContract,
+    #         event:            :stripe_payment_succeeded,
+    #         correlation_from: { order_id: params[:metadata][:order_id] },
+    #         payload:          params.to_unsafe_h
+    #       )
+    #     end
+    #   end
+    module WebhookHandler
+      def deliver_event_for(contract_class, event:, correlation_from:, payload: nil, store: nil) # rubocop:disable Metrics/MethodLength
+        payload_data = payload || (respond_to?(:params) ? params.to_unsafe_h : {})
+        correlation = extract_correlation(correlation_from)
+
+        contract_class.deliver_event(
+          event,
+          correlation: correlation,
+          payload: payload_data,
+          store: store || Igniter.execution_store
+        )
+
+        head :ok
+      rescue Igniter::ResolutionError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+
+      private
+
+      def extract_correlation(source)
+        case source
+        when Hash then source.transform_keys(&:to_sym)
+        when Symbol then { source => params[source] }
+        when Array then source.each_with_object({}) { |k, h| h[k.to_sym] = params[k] }
+        else source.to_h.transform_keys(&:to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/rails.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "igniter"
+require_relative "rails/railtie" if defined?(::Rails::Railtie)
+require_relative "rails/contract_job"
+require_relative "rails/webhook_concern"
+require_relative "rails/cable_adapter"
+
+module Igniter
+  module Rails
+  end
+end

data/lib/igniter/invariant.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Represents a named condition that must always hold for a contract's outputs.
+  #
+  # An Invariant wraps a block that receives the contract's declared output values
+  # as keyword arguments and returns a truthy value when the condition holds.
+  #
+  # @example
+  #   inv = Igniter::Invariant.new(:total_non_negative) { |total:, **| total >= 0 }
+  #   inv.check(total: 42)    # => nil  (passed)
+  #   inv.check(total: -1)    # => InvariantViolation
+  class Invariant
+    attr_reader :name, :block
+
+    def initialize(name, &block)
+      raise ArgumentError, "invariant :#{name} requires a block" unless block
+
+      @name  = name.to_sym
+      @block = block
+      freeze
+    end
+
+    # Evaluate invariant against the resolved output values.
+    #
+    # @param resolved_values [Hash] output_name => value for all declared outputs
+    # @return [InvariantViolation, nil] nil when the invariant holds
+    def check(resolved_values)
+      passed = block.call(**resolved_values)
+      passed ? nil : InvariantViolation.new(name: name, passed: false)
+    rescue StandardError => e
+      InvariantViolation.new(name: name, passed: false, error: e)
+    end
+  end
+
+  # Records a single invariant check outcome.
+  class InvariantViolation
+    attr_reader :name, :error
+
+    def initialize(name:, passed:, error: nil)
+      @name   = name.to_sym
+      @passed = passed
+      @error  = error
+      freeze
+    end
+
+    def passed? = @passed
+    def failed? = !@passed
+  end
+end

data/lib/igniter/model/await_node.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    class AwaitNode < Node
+      attr_reader :event_name
+
+      def initialize(id:, name:, event_name:, path: nil, metadata: {})
+        super(
+          id: id,
+          kind: :await,
+          name: name,
+          path: path || name.to_s,
+          dependencies: [],
+          metadata: metadata
+        )
+        @event_name = event_name.to_sym
+      end
+    end
+  end
+end

data/lib/igniter/model/effect_node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a side-effect node in the computation graph.
+    #
+    # An EffectNode wraps an Igniter::Effect adapter class. It participates
+    # in topological ordering, dependency resolution, saga compensations,
+    # and execution reporting like any other node — but is explicitly typed
+    # as a side effect for visibility and audit purposes.
+    class EffectNode < Node
+      attr_reader :adapter_class
+
+      def initialize(id:, name:, dependencies:, adapter_class:, path: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        super(
+          id: id,
+          kind: :effect,
+          name: name,
+          path: path || name,
+          dependencies: dependencies,
+          metadata: metadata
+        )
+        @adapter_class = adapter_class
+      end
+
+      # @return [Symbol] e.g. :database, :http, :cache, :generic
+      def effect_type
+        adapter_class.effect_type
+      end
+
+      # @return [Boolean]
+      def idempotent?
+        adapter_class.idempotent?
+      end
+    end
+  end
+end

data/lib/igniter/model/remote_node.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a node that executes a contract on a remote igniter-server node.
+    # The result is the outputs hash returned by the remote contract.
+    class RemoteNode < Node
+      attr_reader :contract_name, :node_url, :input_mapping, :timeout
+
+      def initialize(id:, name:, contract_name:, node_url:, input_mapping:, timeout: 30, path: nil, metadata: {})
+        super(
+          id: id,
+          kind: :remote,
+          name: name,
+          path: path || name.to_s,
+          dependencies: input_mapping.values.map(&:to_sym),
+          metadata: metadata
+        )
+        @contract_name = contract_name.to_s
+        @node_url      = node_url.to_s
+        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @timeout       = Integer(timeout)
+      end
+    end
+  end
+end

data/lib/igniter/model.rb

@@ -8,6 +8,9 @@ require_relative "model/composition_node"
 require_relative "model/branch_node"
 require_relative "model/collection_node"
 require_relative "model/output_node"
+require_relative "model/await_node"
+require_relative "model/remote_node"
+require_relative "model/effect_node"
 
 module Igniter
   module Model