igniter 0.4.3 → 0.5.0

data/lib/igniter/incremental/result.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Incremental
+    # Structured result of a resolve_incrementally call.
+    #
+    # Attributes:
+    #   changed_nodes   — node names whose value_version increased (value actually changed)
+    #   skipped_nodes   — node names that were stale but memoized (deps unchanged, compute skipped)
+    #   backdated_nodes — node names that recomputed but produced the same value
+    #   changed_outputs — Hash{ Symbol => { from: old_value, to: new_value } }
+    #   recomputed_count — total number of compute calls actually executed
+    class Result
+      attr_reader :changed_nodes, :skipped_nodes, :backdated_nodes,
+                  :changed_outputs, :recomputed_count
+
+      def initialize(changed_nodes:, skipped_nodes:, backdated_nodes:,
+                     changed_outputs:, recomputed_count:)
+        @changed_nodes = changed_nodes.freeze
+        @skipped_nodes = skipped_nodes.freeze
+        @backdated_nodes = backdated_nodes.freeze
+        @changed_outputs = changed_outputs.freeze
+        @recomputed_count = recomputed_count
+        freeze
+      end
+
+      # True when at least one output value changed.
+      def outputs_changed?
+        changed_outputs.any?
+      end
+
+      # True when every stale node was memoized — nothing actually ran.
+      def fully_memoized?
+        recomputed_count.zero?
+      end
+
+      # One-line summary for logging.
+      def summary # rubocop:disable Metrics/AbcSize
+        parts = []
+        parts << "#{changed_nodes.size} node(s) changed" if changed_nodes.any?
+        parts << "#{skipped_nodes.size} skipped (memoized)" if skipped_nodes.any?
+        parts << "#{backdated_nodes.size} backdated (same value)" if backdated_nodes.any?
+        parts << "#{recomputed_count} recomputed"
+        parts.join(", ")
+      end
+
+      # Human-readable ASCII report.
+      def explain
+        Formatter.format(self)
+      end
+
+      alias to_s explain
+
+      def to_h # rubocop:disable Metrics/MethodLength
+        {
+          changed_nodes: changed_nodes,
+          skipped_nodes: skipped_nodes,
+          backdated_nodes: backdated_nodes,
+          changed_outputs: changed_outputs.transform_values do |diff|
+            { from: diff[:from], to: diff[:to] }
+          end,
+          recomputed_count: recomputed_count,
+          outputs_changed: outputs_changed?,
+          fully_memoized: fully_memoized?
+        }
+      end
+    end
+  end
+end

data/lib/igniter/incremental/tracker.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Incremental
+    # Subscribes to execution events and records which nodes were changed,
+    # skipped (memoized), or backdated during an incremental resolve pass.
+    #
+    # Takes a pre-snapshot of value_versions before the resolve pass and compares
+    # after to detect what changed, rather than relying on event payloads alone.
+    class Tracker
+      def initialize(execution)
+        @execution = execution
+        @skipped_nodes = []
+        @backdated_nodes = []
+        @recomputed_nodes = []
+        @pre_node_vv = {}
+        @pre_output_values = {}
+      end
+
+      def start!
+        snapshot_pre_state!
+        @execution.events.subscribe(self)
+      end
+
+      # Called by Events::Bus for every event.
+      def call(event)
+        case event.type
+        when :node_skipped
+          @skipped_nodes << event.node_name
+        when :node_backdated
+          @backdated_nodes << event.node_name
+        when :node_succeeded
+          kind = fetch_node_kind(event.node_name)
+          @recomputed_nodes << event.node_name if %i[compute effect].include?(kind)
+        end
+      end
+
+      def build_result # rubocop:disable Metrics/MethodLength
+        # Deduplicate (events may fire multiple times across execution passes)
+        skipped   = @skipped_nodes.uniq
+        backdated = @backdated_nodes.uniq
+        # recomputed = node_succeeded minus skipped (skipped also fires node_succeeded)
+        recomputed = @recomputed_nodes.uniq - skipped
+
+        changed = detect_changed_nodes
+        changed_outputs = detect_changed_outputs
+
+        Result.new(
+          changed_nodes: changed,
+          skipped_nodes: skipped,
+          backdated_nodes: backdated,
+          changed_outputs: changed_outputs,
+          recomputed_count: recomputed.size
+        )
+      end
+
+      private
+
+      def snapshot_pre_state! # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        @execution.compiled_graph.nodes.each do |node|
+          state = @execution.cache.fetch(node.name)
+          @pre_node_vv[node.name] = state&.value_version
+        end
+
+        @execution.compiled_graph.outputs.each do |output_node|
+          src_state = @execution.cache.fetch(output_node.source_root)
+          @pre_output_values[output_node.name] = {
+            value: src_state&.value,
+            value_version: src_state&.value_version
+          }
+        end
+      end
+
+      def detect_changed_nodes
+        @execution.compiled_graph.nodes.each_with_object([]) do |node, memo|
+          pre_vv = @pre_node_vv[node.name]
+          current_vv = @execution.cache.fetch(node.name)&.value_version
+          # Changed = value_version advanced AND it's a compute/effect node
+          next unless %i[compute effect].include?(node.kind)
+          next unless current_vv && current_vv != pre_vv
+
+          memo << node.name
+        end
+      end
+
+      def detect_changed_outputs
+        @execution.compiled_graph.outputs.each_with_object({}) do |output_node, memo|
+          pre = @pre_output_values[output_node.name]
+          next unless pre
+
+          src_state = @execution.cache.fetch(output_node.source_root)
+          current_vv = src_state&.value_version
+
+          next if pre[:value_version] == current_vv
+
+          memo[output_node.name] = { from: pre[:value], to: src_state&.value }
+        end
+      end
+
+      def fetch_node_kind(node_name)
+        return nil unless node_name
+        return nil unless @execution.compiled_graph.node?(node_name)
+
+        @execution.compiled_graph.fetch_node(node_name).kind
+      end
+    end
+  end
+end

data/lib/igniter/incremental.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/incremental/result"
+require "igniter/incremental/tracker"
+require "igniter/incremental/formatter"
+
+module Igniter
+  # Incremental computation for Igniter contracts.
+  #
+  # Implements the Salsa/Adapton incremental model:
+  #   - Each compute node tracks a dep_snapshot: the value_versions of its
+  #     dependencies at last compute time.
+  #   - On re-resolution of a stale node, if all dep value_versions are
+  #     unchanged, the compute is skipped entirely (memoization).
+  #   - If a node recomputes but produces the same output value, its own
+  #     value_version is not incremented (backdating), preventing unnecessary
+  #     downstream recomputation.
+  #
+  # These optimizations are built into the core runtime (NodeState, Cache,
+  # Resolver) and are always active. This module adds the reporting API:
+  #   - contract.resolve_incrementally → Incremental::Result
+  #
+  # Usage:
+  #   require "igniter/extensions/incremental"
+  #
+  #   class PricingContract < Igniter::Contract
+  #     define do
+  #       input :base_price
+  #       input :user_tier
+  #       input :exchange_rate
+  #       compute :tier_discount,   depends_on: :user_tier,   call: -> (user_tier:) { ... }
+  #       compute :adjusted_price,  depends_on: %i[base_price tier_discount], call: -> (**) { ... }
+  #       compute :converted_price, depends_on: %i[adjusted_price exchange_rate], call: -> (**) { ... }
+  #       output :converted_price
+  #     end
+  #   end
+  #
+  #   contract = PricingContract.new(base_price: 100, user_tier: "gold", exchange_rate: 1.0)
+  #   contract.resolve_all
+  #
+  #   result = contract.resolve_incrementally(exchange_rate: 1.12)
+  #   result.skipped_nodes    # => [:tier_discount, :adjusted_price]
+  #   result.changed_outputs  # => { converted_price: { from: 100.0, to: 112.0 } }
+  #   result.explain
+  #
+  module Incremental
+    class IncrementalError < Igniter::Error; end
+  end
+end

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

@@ -35,18 +35,46 @@ module Igniter
         end
       end
 
-      PROVIDERS = %i[ollama anthropic openai].freeze
+      class DeepgramConfig
+        attr_accessor :api_key, :base_url, :timeout
+
+        def initialize
+          @api_key  = ENV["DEEPGRAM_API_KEY"]
+          @base_url = "https://api.deepgram.com"
+          @timeout  = 300
+        end
+      end
+
+      class AssemblyAIConfig
+        attr_accessor :api_key, :base_url, :timeout, :poll_interval, :poll_timeout
+
+        def initialize
+          @api_key       = ENV["ASSEMBLYAI_API_KEY"]
+          @base_url      = "https://api.assemblyai.com"
+          @timeout       = 60
+          @poll_interval = 2
+          @poll_timeout  = 300
+        end
+      end
+
+      PROVIDERS                 = %i[ollama anthropic openai].freeze
+      TRANSCRIPTION_PROVIDERS   = %i[openai deepgram assemblyai].freeze
 
       attr_accessor :default_provider
-      attr_reader :providers
+      attr_reader :providers, :transcription_providers
 
-      def initialize
+      def initialize # rubocop:disable Metrics/MethodLength
         @default_provider = :ollama
         @providers = {
           ollama: OllamaConfig.new,
           anthropic: AnthropicConfig.new,
           openai: OpenAIConfig.new
         }
+        @transcription_providers = {
+          openai: @providers[:openai], # reuse existing OpenAI config
+          deepgram: DeepgramConfig.new,
+          assemblyai: AssemblyAIConfig.new
+        }
       end
 
       def ollama
@@ -61,8 +89,24 @@ module Igniter
         @providers[:openai]
       end
 
+      def deepgram
+        @transcription_providers[:deepgram]
+      end
+
+      def assemblyai
+        @transcription_providers[:assemblyai]
+      end
+
       def provider_config(name)
-        @providers.fetch(name.to_sym) { raise ArgumentError, "Unknown LLM provider: #{name}. Available: #{PROVIDERS.inspect}" }
+        @providers.fetch(name.to_sym) do
+          raise ArgumentError, "Unknown LLM provider: #{name}. Available: #{PROVIDERS.inspect}"
+        end
+      end
+
+      def transcription_provider_config(name)
+        @transcription_providers.fetch(name.to_sym) do
+          raise ArgumentError, "Unknown transcription provider: #{name}. Available: #{TRANSCRIPTION_PROVIDERS.inspect}"
+        end
       end
     end
   end

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

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Igniter
   module LLM
+    # Raised when the tool-use loop exceeds max_tool_iterations.
+    class ToolLoopError < Error; end
+
     # 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:
+    # == Simple usage (no tools)
+    #
     #   class DocumentSummarizer < Igniter::LLM::Executor
     #     provider :ollama
     #     model "llama3.2"
@@ -18,25 +24,68 @@ module Igniter
     #     end
     #   end
     #
-    #   class OrderContract < Igniter::Contract
-    #     define do
-    #       input :document
-    #       compute :summary, depends_on: :document, with: DocumentSummarizer
-    #       output :summary
+    # == With Igniter::Tool classes (auto tool-use loop)
+    #
+    #   class ResearchAgent < Igniter::LLM::Executor
+    #     provider :anthropic
+    #     model "claude-sonnet-4-6"
+    #     system_prompt "You are a research assistant. Use tools when needed."
+    #
+    #     tools SearchWeb, WriteFile     # Igniter::Tool subclasses
+    #     capabilities :web_access, :filesystem_write
+    #     max_tool_iterations 10
+    #
+    #     def call(question:)
+    #       complete(question)
+    #       # Auto-loop: LLM → tool_use → capability check → Tool#call → result → LLM
     #     end
     #   end
+    #
+    # == Provider failover
+    #
+    #   class MyAgent < Igniter::LLM::Executor
+    #     provider :anthropic, fallback: [:openai, :ollama]
+    #     model "claude-sonnet-4-6", fallback: ["gpt-4o", "llama3.2"]
+    #     # On ProviderError, retries with OpenAI/GPT-4o, then Ollama/llama3.2
+    #   end
     class Executor < Igniter::Executor
       class << self
-        def provider(name = nil)
-          return @provider || Igniter::LLM.config.default_provider if name.nil?
+        # Set or get the primary provider, with optional fallback chain.
+        #
+        # @param name     [Symbol, nil] :ollama, :anthropic, or :openai
+        # @param fallback [Array<Symbol>] providers to try on ProviderError, in order
+        def provider(name = nil, fallback: nil)
+          if name.nil?
+            @provider_chain&.first || Igniter::LLM.config.default_provider
+          else
+            chain = [name] + Array(fallback)
+            @provider_chain = chain.map(&:to_sym)
+          end
+        end
 
-          @provider = name.to_sym
+        # Full provider chain (primary + fallbacks).
+        def provider_chain
+          @provider_chain&.dup || [provider]
         end
 
-        def model(name = nil)
-          return @model || provider_config.default_model if name.nil?
+        # Set or get the primary model, with optional fallback list.
+        # Fallback models align positionally with the provider fallback chain.
+        #
+        # @param name     [String, nil]
+        # @param fallback [Array<String>] models to use per fallback provider
+        def model(name = nil, fallback: nil)
+          if name.nil?
+            @model_chain&.first || default_model_for(
+              @provider_chain&.first || Igniter::LLM.config.default_provider
+            )
+          else
+            @model_chain = [name] + Array(fallback)
+          end
+        end
 
-          @model = name
+        # Full model chain (primary + fallbacks).
+        def model_chain
+          @model_chain&.dup || [model]
         end
 
         def system_prompt(text = nil)
@@ -51,23 +100,43 @@ module Igniter
           @temperature = val
         end
 
+        # Register tools. Accepts Igniter::Tool subclasses (enables auto tool-use
+        # loop in #complete) or raw Hash definitions (backward-compatible with
+        # the deferred #complete_with_tools pattern).
         def tools(*tool_definitions)
           return @tools || [] if tool_definitions.empty?
 
           @tools = tool_definitions.flatten
         end
 
+        # Maximum number of tool-use iterations in the auto-loop.
+        # Prevents infinite loops when the LLM keeps requesting tools.
+        # Ignored when no Tool classes are registered. Default: 10.
+        def max_tool_iterations(n = nil)
+          n ? (@max_tool_iterations = n.to_i) : (@max_tool_iterations || 10)
+        end
+
         def inherited(subclass)
           super
+          subclass.instance_variable_set(:@provider_chain, @provider_chain&.dup)
+          subclass.instance_variable_set(:@model_chain, @model_chain&.dup)
+          # Keep legacy @provider / @model ivars in sync for backward compat
           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)
+          subclass.instance_variable_set(:@max_tool_iterations, @max_tool_iterations)
         end
 
         private
 
+        def default_model_for(prov)
+          Igniter::LLM.config.provider_config(prov).default_model
+        rescue StandardError
+          "llama3.2"
+        end
+
         def provider_config
           Igniter::LLM.provider_instance(provider).instance_of?(Class) ? nil : Igniter::LLM.config.provider_config(provider)
         rescue StandardError
@@ -75,7 +144,7 @@ module Igniter
         end
       end
 
-      attr_reader :last_usage, :last_context
+      attr_reader :last_usage, :last_context, :last_provider, :last_model, :call_history
 
       # Subclasses override this method. Use #complete or #chat inside.
       def call(**_inputs)
@@ -84,17 +153,42 @@ module Igniter
 
       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]
+      # Single-turn completion, or auto tool-use loop when Igniter::Tool subclasses
+      # are registered via the +tools+ DSL.
+      #
+      # Wraps execution in the provider failover chain: on ProviderError the next
+      # provider/model pair is tried. ConfigurationError is NOT caught — a missing
+      # API key is a configuration bug, not a transient provider failure.
+      #
+      # @param prompt  [String]
+      # @param context [Context, nil]
+      # @return [String] final LLM text response
+      def complete(prompt, context: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        with_provider_fallback do
+          # Accept both Igniter::Tool and Igniter::Skill subclasses (duck-type check).
+          # Using respond_to? avoids a circular require: skill.rb requires this file,
+          # so we can't safely reference Igniter::Skill or Igniter::Tool::Discoverable here.
+          tool_classes = self.class.tools.select do |t|
+            t.is_a?(Class) && t.respond_to?(:tool_name) && t.respond_to?(:to_schema)
+          end
+
+          result = if tool_classes.any?
+                     run_tool_loop(prompt: prompt, context: context, tool_classes: tool_classes)
+                   else
+                     messages = build_messages(prompt: prompt, context: context)
+                     response = provider_instance.chat(
+                       messages: messages,
+                       model: current_model,
+                       **completion_options
+                     )
+                     @last_usage   = provider_instance.last_usage
+                     @last_context = track_context(context, prompt, response[:content])
+                     response[:content]
+                   end
+
+          track_call_history(prompt, result)
+          result
+        end
       end
 
       # Multi-turn chat with a Context object or raw messages array.
@@ -102,19 +196,21 @@ module Igniter
         messages = context.is_a?(Context) ? context.to_a : Array(context)
         response = provider_instance.chat(
           messages: messages,
-          model: self.class.model,
+          model: current_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.
+      # Tool-use call for the distributed/deferred pattern.
+      # Returns DeferredResult if the LLM requests a tool call.
+      # For automatic tool execution, use #complete with Igniter::Tool classes.
       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,
+          model: current_model,
           tools: self.class.tools,
           **completion_options
         )
@@ -129,8 +225,99 @@ module Igniter
 
       private
 
+      # Iterate through the provider/model chain, retrying on ProviderError.
+      # ConfigurationError propagates immediately (missing API key = config bug).
+      #
+      # Does NOT call Igniter::LLM.provider_instance directly; instead it resets
+      # @provider_instance = nil before each attempt so that the #provider_instance
+      # accessor re-evaluates (or a test's define_method override takes effect).
+      def with_provider_fallback # rubocop:disable Metrics/MethodLength
+        chain      = self.class.provider_chain
+        mchain     = self.class.model_chain
+        last_error = nil
+
+        chain.each_with_index do |prov, i|
+          @last_provider     = prov
+          @last_model        = mchain[i] # nil when chain is shorter → current_model falls back
+          @provider_instance = nil # clear memo; forces re-evaluation per attempt
+
+          begin
+            return yield
+          rescue Igniter::LLM::ProviderError => e
+            last_error = e
+          end
+        end
+
+        raise last_error
+      end
+
+      # The model to use for the current request (set by with_provider_fallback,
+      # or falls back to the class-level default).
+      def current_model
+        @last_model || self.class.model
+      end
+
+      # Execute the tool-use loop until the LLM produces a plain-text response.
+      def run_tool_loop(prompt:, context:, tool_classes:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        messages     = build_messages(prompt: prompt, context: context)
+        schemas      = tool_classes.map(&:to_schema)
+        allowed_caps = self.class.declared_capabilities
+        max_iters    = self.class.max_tool_iterations
+        iters        = 0
+
+        loop do
+          response = provider_instance.chat(
+            messages: messages,
+            model: current_model,
+            tools: schemas,
+            **completion_options
+          )
+          @last_usage = provider_instance.last_usage
+
+          return response[:content] if response[:tool_calls].empty?
+
+          iters += 1
+          if iters > max_iters
+            raise ToolLoopError,
+                  "Tool loop exceeded max_tool_iterations (#{max_iters}) for #{self.class.name}"
+          end
+
+          # Append assistant's tool-use turn (preserves tool_call ids for Anthropic/OpenAI)
+          messages << {
+            role: "assistant",
+            content: response[:content],
+            tool_calls: response[:tool_calls]
+          }
+
+          # Execute each requested tool and collect results
+          results = response[:tool_calls].map do |tc|
+            klass   = tool_classes.find { |k| k.tool_name == tc[:name].to_s }
+            content = dispatch_tool(klass, tc, allowed_caps)
+            { id: tc[:id].to_s, name: tc[:name].to_s, content: content }
+          end
+
+          # All results for this iteration go into a single :tool_results message.
+          # Each provider's normalize_messages converts this to its native format.
+          messages << { role: :tool_results, results: results }
+        end
+      end
+
+      def dispatch_tool(klass, tool_call, allowed_caps)
+        return "Unknown tool: #{tool_call[:name]}" unless klass
+
+        result = klass.new.call_with_capability_check!(
+          allowed_capabilities: allowed_caps,
+          **tool_call[:arguments]
+        )
+        result.is_a?(String) ? result : JSON.generate(result)
+      rescue Igniter::Tool::CapabilityError
+        raise
+      rescue StandardError => e
+        "Error: #{e.class}: #{e.message}"
+      end
+
       def provider_instance
-        @provider_instance ||= Igniter::LLM.provider_instance(self.class.provider)
+        @provider_instance ||= Igniter::LLM.provider_instance(@last_provider || self.class.provider)
       end
 
       def build_messages(prompt:, context: nil)
@@ -154,6 +341,12 @@ module Igniter
         ctx = existing.is_a?(Context) ? existing : Context.empty(system: self.class.system_prompt)
         ctx.append_user(user_prompt).append_assistant(assistant_reply)
       end
+
+      def track_call_history(input, output)
+        @call_history ||= []
+        @call_history << { input: input, output: output.to_s, timestamp: Time.now }
+        @call_history = @call_history.last(20) if @call_history.size > 20
+      end
     end
   end
 end