igniter 0.3.1 → 0.4.0

data/lib/igniter/compiler/validators/remote_validator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class RemoteValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          @context.runtime_nodes.each do |node|
+            next unless node.kind == :remote
+
+            validate_url!(node)
+            validate_contract_name!(node)
+            validate_dependencies!(node)
+          end
+        end
+
+        private
+
+        def validate_url!(node)
+          return if node.node_url.start_with?("http://", "https://")
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} has invalid node: URL '#{node.node_url}'. Must start with http:// or https://"
+          )
+        end
+
+        def validate_contract_name!(node)
+          return unless node.contract_name.strip.empty?
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} requires a non-empty contract: name"
+          )
+        end
+
+        def validate_dependencies!(node)
+          node.dependencies.each do |dep_name|
+            next if @context.dependency_resolvable?(dep_name)
+
+            raise @context.validation_error(
+              node,
+              "remote :#{node.name} depends on '#{dep_name}' which is not defined in the graph"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/compiler.rb

@@ -8,6 +8,8 @@ require_relative "compiler/validators/outputs_validator"
 require_relative "compiler/validators/dependencies_validator"
 require_relative "compiler/validators/callable_validator"
 require_relative "compiler/validators/type_compatibility_validator"
+require_relative "compiler/validators/await_validator"
+require_relative "compiler/validators/remote_validator"
 require_relative "compiler/validation_pipeline"
 require_relative "compiler/validator"
 require_relative "compiler/graph_compiler"

data/lib/igniter/contract.rb

@@ -3,8 +3,20 @@
 module Igniter
   class Contract
     class << self
+      def correlate_by(*keys)
+        @correlation_keys = keys.map(&:to_sym).freeze
+      end
+
+      def correlation_keys
+        @correlation_keys || []
+      end
+
       def define(&block)
-        @compiled_graph = DSL::ContractBuilder.compile(name: contract_name, &block)
+        @compiled_graph = DSL::ContractBuilder.compile(
+          name: contract_name,
+          correlation_keys: correlation_keys,
+          &block
+        )
       end
 
       def run_with(runner:, max_workers: nil)
@@ -28,6 +40,45 @@ module Igniter
         @compiled_graph = DSL::SchemaBuilder.compile(schema, name: contract_name)
       end
 
+      def start(inputs = {}, store: nil, **keyword_inputs)
+        resolved_store = store || Igniter.execution_store
+        all_inputs = inputs.merge(keyword_inputs)
+
+        instance = new(all_inputs, runner: :store, store: resolved_store)
+        instance.resolve_all
+
+        correlation = correlation_keys.each_with_object({}) do |key, hash|
+          hash[key] = all_inputs[key] || all_inputs[key.to_s]
+        end
+
+        resolved_store.save(instance.snapshot, correlation: correlation.compact, graph: contract_name)
+        instance
+      end
+
+      def deliver_event(event_name, correlation:, payload:, store: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        resolved_store = store || Igniter.execution_store
+        execution_id = resolved_store.find_by_correlation(
+          graph: contract_name,
+          correlation: correlation.transform_keys(&:to_sym)
+        )
+        unless execution_id
+          raise ResolutionError,
+                "No pending execution found for #{contract_name} with given correlation"
+        end
+
+        instance = restore_from_store(execution_id, store: resolved_store)
+
+        await_node = instance.execution.compiled_graph.await_nodes
+                             .find { |n| n.event_name == event_name.to_sym }
+        raise ResolutionError, "No await node found for event '#{event_name}' in #{contract_name}" unless await_node
+
+        instance.execution.resume(await_node.name, value: payload)
+        instance.resolve_all
+
+        resolved_store.save(instance.snapshot, correlation: correlation.transform_keys(&:to_sym), graph: contract_name)
+        instance
+      end
+
       def restore(snapshot)
         instance = new(
           snapshot[:inputs] || snapshot["inputs"] || {},
@@ -159,9 +210,9 @@ module Igniter
       end
     end
 
-    attr_reader :execution, :result
+    attr_reader :execution, :result, :reactive
 
-    def initialize(inputs = nil, runner: nil, max_workers: nil, **keyword_inputs)
+    def initialize(inputs = nil, runner: nil, max_workers: nil, store: nil, **keyword_inputs)
       graph = self.class.compiled_graph
       raise CompileError, "#{self.class.name} has no compiled graph. Use `define`." unless graph
 
@@ -175,7 +226,7 @@ module Igniter
         end
 
       execution_options = self.class.execution_options.merge(
-        { runner: runner, max_workers: max_workers }.compact
+        { runner: runner, max_workers: max_workers, store: store }.compact
       )
       execution_options[:store] ||= Igniter.execution_store if execution_options[:runner]&.to_sym == :store
 
@@ -220,10 +271,6 @@ module Igniter
       execution.audit.snapshot
     end
 
-    def reactive
-      @reactive
-    end
-
     def subscribe(subscriber = nil, &block)
       execution.events.subscribe(subscriber, &block)
       self
@@ -261,5 +308,9 @@ module Igniter
     def failed?
       execution.failed?
     end
+
+    def pending?
+      execution.pending?
+    end
   end
 end

data/lib/igniter/dsl/contract_builder.rb

@@ -3,12 +3,13 @@
 module Igniter
   module DSL
     class ContractBuilder
-      def self.compile(name: "AnonymousContract", &block)
-        new(name: name).tap { |builder| builder.instance_eval(&block) }.compile
+      def self.compile(name: "AnonymousContract", correlation_keys: [], &block)
+        new(name: name, correlation_keys: correlation_keys).tap { |builder| builder.instance_eval(&block) }.compile
       end
 
-      def initialize(name:)
+      def initialize(name:, correlation_keys: [])
         @name = name
+        @correlation_keys = correlation_keys
         @nodes = []
         @sequence = 0
         @scope_stack = []
@@ -228,8 +229,45 @@ module Igniter
         )
       end
 
+      def remote(name, contract:, node:, inputs:, timeout: 30, **metadata) # rubocop:disable Metrics/MethodLength
+        raise CompileError, "remote :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
+        raise CompileError, "remote :#{name} requires a contract: name" if contract.nil? || contract.to_s.strip.empty?
+        raise CompileError, "remote :#{name} requires a node: URL"     if node.nil?    || node.to_s.strip.empty?
+
+        add_node(
+          Model::RemoteNode.new(
+            id: next_id,
+            name: name.to_sym,
+            contract_name: contract.to_s,
+            node_url: node.to_s,
+            input_mapping: inputs,
+            timeout: timeout,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def await(name, event:, **metadata)
+        add_node(
+          Model::AwaitNode.new(
+            id: next_id,
+            name: name.to_sym,
+            path: scoped_path(name),
+            event_name: event,
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
       def compile
-        Compiler::GraphCompiler.call(Model::Graph.new(name: @name, nodes: @nodes))
+        Compiler::GraphCompiler.call(
+          Model::Graph.new(
+            name: @name,
+            nodes: @nodes,
+            metadata: { correlation_keys: @correlation_keys || [] }
+          )
+        )
       end
 
       private

data/lib/igniter/errors.rb

@@ -29,13 +29,18 @@ module Igniter
       context[:source_location]
     end
 
+    def execution_id
+      context[:execution_id]
+    end
+
     private
 
-    def format_message(message, context)
+    def format_message(message, context) # rubocop:disable Metrics/AbcSize
       details = []
       details << "graph=#{context[:graph]}" if context[:graph]
       details << "node=#{context[:node_name]}" if context[:node_name]
       details << "path=#{context[:node_path]}" if context[:node_path]
+      details << "execution=#{context[:execution_id]}" if context[:execution_id]
       details << "location=#{context[:source_location]}" if context[:source_location]
 
       return message if details.empty?

data/lib/igniter/integrations/llm/config.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    class Config
+      class OllamaConfig
+        attr_accessor :base_url, :default_model, :timeout
+
+        def initialize
+          @base_url = "http://localhost:11434"
+          @default_model = "llama3.2"
+          @timeout = 120
+        end
+      end
+
+      class AnthropicConfig
+        attr_accessor :api_key, :base_url, :default_model, :timeout
+
+        def initialize
+          @api_key = ENV["ANTHROPIC_API_KEY"]
+          @base_url = "https://api.anthropic.com"
+          @default_model = "claude-sonnet-4-6"
+          @timeout = 120
+        end
+      end
+
+      class OpenAIConfig
+        attr_accessor :api_key, :base_url, :default_model, :timeout
+
+        def initialize
+          @api_key = ENV["OPENAI_API_KEY"]
+          @base_url = "https://api.openai.com"
+          @default_model = "gpt-4o"
+          @timeout = 120
+        end
+      end
+
+      PROVIDERS = %i[ollama anthropic openai].freeze
+
+      attr_accessor :default_provider
+      attr_reader :providers
+
+      def initialize
+        @default_provider = :ollama
+        @providers = {
+          ollama: OllamaConfig.new,
+          anthropic: AnthropicConfig.new,
+          openai: OpenAIConfig.new
+        }
+      end
+
+      def ollama
+        @providers[:ollama]
+      end
+
+      def anthropic
+        @providers[:anthropic]
+      end
+
+      def openai
+        @providers[:openai]
+      end
+
+      def provider_config(name)
+        @providers.fetch(name.to_sym) { raise ArgumentError, "Unknown LLM provider: #{name}. Available: #{PROVIDERS.inspect}" }
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    # Manages a conversation message history for multi-turn LLM interactions.
+    # Immutable — each operation returns a new Context.
+    #
+    # Usage:
+    #   ctx = Igniter::LLM::Context.empty(system: "You are a helpful assistant.")
+    #   ctx = ctx.append_user("What is Ruby?")
+    #   ctx = ctx.append_assistant("Ruby is a dynamic language...")
+    #   ctx.messages  # => [{role: :system, ...}, {role: :user, ...}, {role: :assistant, ...}]
+    class Context
+      attr_reader :messages
+
+      def initialize(messages = [])
+        @messages = messages.freeze
+      end
+
+      def self.empty(system: nil)
+        initial = system ? [{ role: :system, content: system }] : []
+        new(initial)
+      end
+
+      def self.from_h(data)
+        msgs = (data[:messages] || data["messages"] || []).map do |m|
+          { role: (m[:role] || m["role"]).to_sym, content: (m[:content] || m["content"]).to_s }
+        end
+        new(msgs)
+      end
+
+      def append_user(content)
+        append(role: :user, content: content)
+      end
+
+      def append_assistant(content)
+        append(role: :assistant, content: content)
+      end
+
+      def append_tool_result(tool_name, content)
+        append(role: :tool, content: content.to_s, name: tool_name.to_s)
+      end
+
+      def append(message)
+        self.class.new(@messages + [message.transform_keys(&:to_sym)])
+      end
+
+      def with_system(content)
+        existing = @messages.reject { |m| m[:role] == :system }
+        self.class.new([{ role: :system, content: content }] + existing)
+      end
+
+      def last_assistant_message
+        @messages.reverse.find { |m| m[:role] == :assistant }
+      end
+
+      def length
+        @messages.length
+      end
+
+      def empty?
+        @messages.empty?
+      end
+
+      def to_a
+        @messages.map { |m| { "role" => m[:role].to_s, "content" => m[:content].to_s } }
+      end
+
+      def to_h
+        { messages: @messages }
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/executor.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    # Base class for LLM-powered compute nodes.
+    #
+    # Subclass and override #call(**inputs) to build prompts and get completions.
+    # Use the #complete and #chat helper methods inside #call.
+    #
+    # Example:
+    #   class DocumentSummarizer < Igniter::LLM::Executor
+    #     provider :ollama
+    #     model "llama3.2"
+    #     system_prompt "You are a concise technical writer."
+    #
+    #     def call(document:)
+    #       complete("Summarize this in 3 bullet points:\n\n#{document}")
+    #     end
+    #   end
+    #
+    #   class OrderContract < Igniter::Contract
+    #     define do
+    #       input :document
+    #       compute :summary, depends_on: :document, with: DocumentSummarizer
+    #       output :summary
+    #     end
+    #   end
+    class Executor < Igniter::Executor
+      class << self
+        def provider(name = nil)
+          return @provider || Igniter::LLM.config.default_provider if name.nil?
+
+          @provider = name.to_sym
+        end
+
+        def model(name = nil)
+          return @model || provider_config.default_model if name.nil?
+
+          @model = name
+        end
+
+        def system_prompt(text = nil)
+          return @system_prompt if text.nil?
+
+          @system_prompt = text
+        end
+
+        def temperature(val = nil)
+          return @temperature if val.nil?
+
+          @temperature = val
+        end
+
+        def tools(*tool_definitions)
+          return @tools || [] if tool_definitions.empty?
+
+          @tools = tool_definitions.flatten
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@provider, @provider)
+          subclass.instance_variable_set(:@model, @model)
+          subclass.instance_variable_set(:@system_prompt, @system_prompt)
+          subclass.instance_variable_set(:@temperature, @temperature)
+          subclass.instance_variable_set(:@tools, @tools&.dup)
+        end
+
+        private
+
+        def provider_config
+          Igniter::LLM.provider_instance(provider).instance_of?(Class) ? nil : Igniter::LLM.config.provider_config(provider)
+        rescue StandardError
+          Igniter::LLM.config.ollama
+        end
+      end
+
+      attr_reader :last_usage, :last_context
+
+      # Subclasses override this method. Use #complete or #chat inside.
+      def call(**_inputs)
+        raise NotImplementedError, "#{self.class.name}#call must be implemented"
+      end
+
+      protected
+
+      # Single-turn completion. Builds a simple user message from prompt.
+      def complete(prompt, context: nil)
+        messages = build_messages(prompt: prompt, context: context)
+        response = provider_instance.chat(
+          messages: messages,
+          model: self.class.model,
+          **completion_options
+        )
+        @last_usage = provider_instance.last_usage
+        @last_context = track_context(context, prompt, response[:content])
+        response[:content]
+      end
+
+      # Multi-turn chat with a Context object or raw messages array.
+      def chat(context:)
+        messages = context.is_a?(Context) ? context.to_a : Array(context)
+        response = provider_instance.chat(
+          messages: messages,
+          model: self.class.model,
+          **completion_options
+        )
+        @last_usage = provider_instance.last_usage
+        response[:content]
+      end
+
+      # Tool-use call. Returns DeferredResult if the LLM wants to call a tool.
+      def complete_with_tools(prompt, context: nil) # rubocop:disable Metrics/MethodLength
+        messages = build_messages(prompt: prompt, context: context)
+        response = provider_instance.chat(
+          messages: messages,
+          model: self.class.model,
+          tools: self.class.tools,
+          **completion_options
+        )
+        @last_usage = provider_instance.last_usage
+
+        if response[:tool_calls].any?
+          defer(payload: { tool_calls: response[:tool_calls], messages: messages })
+        else
+          response[:content]
+        end
+      end
+
+      private
+
+      def provider_instance
+        @provider_instance ||= Igniter::LLM.provider_instance(self.class.provider)
+      end
+
+      def build_messages(prompt:, context: nil)
+        base = []
+        base << { role: "system", content: self.class.system_prompt } if self.class.system_prompt
+
+        if context.is_a?(Context)
+          base + context.to_a + [{ role: "user", content: prompt }]
+        else
+          base + [{ role: "user", content: prompt }]
+        end
+      end
+
+      def completion_options
+        opts = {}
+        opts[:temperature] = self.class.temperature if self.class.temperature
+        opts
+      end
+
+      def track_context(existing, user_prompt, assistant_reply)
+        ctx = existing.is_a?(Context) ? existing : Context.empty(system: self.class.system_prompt)
+        ctx.append_user(user_prompt).append_assistant(assistant_reply)
+      end
+    end
+  end
+end