igniter 0.3.0 → 0.4.0

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

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/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