igniter 0.3.0 → 0.4.0

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 = []
@@ -17,6 +18,7 @@ module Igniter
       UNDEFINED_INPUT_DEFAULT = :__igniter_undefined__
       UNDEFINED_CONST_VALUE = :__igniter_const_undefined__
       UNDEFINED_GUARD_MATCHER = :__igniter_guard_matcher_undefined__
+      UNDEFINED_PROJECT_OPTION = :__igniter_project_undefined__
 
       def input(name, type: nil, required: nil, default: UNDEFINED_INPUT_DEFAULT, **metadata)
         input_metadata = with_source_location(metadata)
@@ -71,6 +73,33 @@ module Igniter
         compute(name, with: from, call: call, executor: executor, **{ category: :map }.merge(metadata), &block)
       end
 
+      def project(name, from:, key: UNDEFINED_PROJECT_OPTION, dig: UNDEFINED_PROJECT_OPTION, default: UNDEFINED_PROJECT_OPTION, **metadata)
+        if key != UNDEFINED_PROJECT_OPTION && dig != UNDEFINED_PROJECT_OPTION
+          raise CompileError, "project :#{name} cannot use both `key:` and `dig:`"
+        end
+
+        if key == UNDEFINED_PROJECT_OPTION && dig == UNDEFINED_PROJECT_OPTION
+          raise CompileError, "project :#{name} requires either `key:` or `dig:`"
+        end
+
+        callable = proc do |**values|
+          source = values.fetch(from.to_sym)
+          extract_projected_value(
+            source,
+            key: key,
+            dig: dig,
+            default: default,
+            node_name: name
+          )
+        end
+
+        compute(name, with: from, call: callable, **{ category: :project }.merge(metadata))
+      end
+
+      def aggregate(name, depends_on: nil, with: nil, call: nil, executor: nil, **metadata, &block)
+        compute(name, depends_on: depends_on, with: with, call: call, executor: executor, **{ category: :aggregate }.merge(metadata), &block)
+      end
+
       def guard(name, depends_on: nil, with: nil, call: nil, executor: nil, message: nil,
                 eq: UNDEFINED_GUARD_MATCHER, in: UNDEFINED_GUARD_MATCHER, matches: UNDEFINED_GUARD_MATCHER,
                 **metadata, &block)
@@ -156,9 +185,12 @@ module Igniter
         )
       end
 
-      def branch(name, with:, inputs:, **metadata, &block)
+      def branch(name, with:, inputs: nil, depends_on: nil, map_inputs: nil, using: nil, **metadata, &block)
         raise CompileError, "branch :#{name} requires a block" unless block
-        raise CompileError, "branch :#{name} requires an `inputs:` hash" unless inputs.is_a?(Hash)
+        raise CompileError, "branch :#{name} requires either `inputs:` or `map_inputs:`/`using:`" if inputs.nil? && map_inputs.nil? && using.nil?
+        raise CompileError, "branch :#{name} cannot combine `inputs:` with `map_inputs:` or `using:`" if inputs && (map_inputs || using)
+        raise CompileError, "branch :#{name} cannot use both `map_inputs:` and `using:`" if map_inputs && using
+        raise CompileError, "branch :#{name} requires an `inputs:` hash" if inputs && !inputs.is_a?(Hash)
 
         definition = BranchBuilder.build(&block)
 
@@ -169,14 +201,18 @@ module Igniter
             selector_dependency: with,
             cases: definition[:cases],
             default_contract: definition[:default_contract],
-            input_mapping: inputs,
+            input_mapping: inputs || {},
+            context_dependencies: normalize_dependencies(depends_on: depends_on, with: nil),
+            input_mapper: map_inputs || using,
             path: scoped_path(name),
             metadata: with_source_location(metadata)
           )
         )
       end
 
-      def collection(name, with:, each:, key:, mode: :collect, **metadata)
+      def collection(name, with:, each:, key:, mode: :collect, depends_on: nil, map_inputs: nil, using: nil, **metadata)
+        raise CompileError, "collection :#{name} cannot use both `map_inputs:` and `using:`" if map_inputs && using
+
         add_node(
           Model::CollectionNode.new(
             id: next_id,
@@ -185,14 +221,53 @@ module Igniter
             contract_class: each,
             key_name: key,
             mode: mode,
+            context_dependencies: normalize_dependencies(depends_on: depends_on, with: nil),
+            input_mapper: map_inputs || using,
             path: scoped_path(name),
             metadata: with_source_location(metadata)
           )
         )
       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
@@ -254,6 +329,32 @@ module Igniter
         end
       end
 
+      def extract_projected_value(source, key:, dig:, default:, node_name:)
+        if key != UNDEFINED_PROJECT_OPTION
+          return fetch_project_value(source, key, default, node_name)
+        end
+
+        current = source
+        Array(dig).each do |part|
+          current = fetch_project_value(current, part, default, node_name)
+        end
+        current
+      end
+
+      def fetch_project_value(source, part, default, node_name)
+        if source.is_a?(Hash)
+          return source.fetch(part) if source.key?(part)
+          return source.fetch(part.to_s) if source.key?(part.to_s)
+          return source.fetch(part.to_sym) if source.key?(part.to_sym)
+        elsif source.respond_to?(part)
+          return source.public_send(part)
+        end
+
+        return default unless default == UNDEFINED_PROJECT_OPTION
+
+        raise ResolutionError, "project :#{node_name} could not extract #{part.inspect}"
+      end
+
       def scoped_path(name)
         return name.to_s if @scope_stack.empty?
 

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/extensions/introspection/graph_formatter.rb

@@ -39,14 +39,18 @@ module Igniter
             if node.kind == :branch
               cases = node.cases.map { |entry| "#{entry[:match].inspect}:#{entry[:contract].name || 'AnonymousContract'}" }
               line += " selector=#{node.selector_dependency}"
+              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
               line += " cases=#{cases.join('|')}"
               line += " default=#{node.default_contract.name || 'AnonymousContract'}"
+              line += " mapper=#{node.input_mapper}" if node.input_mapper?
             end
             if node.kind == :collection
               line += " with=#{node.source_dependency}"
+              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
               line += " each=#{node.contract_class.name || 'AnonymousContract'}"
               line += " key=#{node.key_name}"
               line += " mode=#{node.mode}"
+              line += " mapper=#{node.input_mapper}" if node.input_mapper?
             end
             lines << line
           end

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

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