igniter 0.4.5 → 0.5.1

data/packages/igniter-agents/lib/igniter/ai/agents.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "igniter/agent"
+require_relative "agents/router_agent"
+require_relative "agents/critic_agent"
+require_relative "agents/planner_agent"
+require_relative "agents/chain_agent"
+require_relative "agents/self_reflection_agent"
+require_relative "agents/observer_agent"
+require_relative "agents/evaluator_agent"
+require_relative "agents/evolution_agent"
+
+module Igniter
+  module AI
+    module Agents
+      # Convenience method — list all built-in AI agents.
+      #
+      # @return [Array<Class>]
+      def self.all
+        [RouterAgent, CriticAgent, PlannerAgent, ChainAgent,
+         SelfReflectionAgent, ObserverAgent, EvaluatorAgent, EvolutionAgent]
+      end
+    end
+  end
+end

data/{lib → packages/igniter-agents/lib}/igniter/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "igniter/core/errors"
+
 module Igniter
   # Thread-safe process registry mapping names to agent Refs.
   #

data/packages/igniter-agents/lib/igniter/runtime/registry_agent_adapter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "igniter/core/runtime/agent_adapter"
+
+module Igniter
+  module Runtime
+    # Default agent-node adapter backed by the local process registry.
+    #
+    # This keeps core independent from actor runtime details while still giving
+    # embedded/app usage a straightforward execution model for agent nodes.
+    class RegistryAgentAdapter < AgentAdapter
+      def call(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        ref = fetch_ref(node)
+        return ref if ref.is_a?(Hash)
+
+        {
+          status: :succeeded,
+          output: ref.call(node.message_name, inputs, timeout: node.timeout),
+          agent_trace: success_trace(node, outcome: :replied)
+        }
+      rescue Igniter::PendingDependencyError => e
+        pending(node, e)
+      rescue Igniter::Agent::TimeoutError => e
+        failure(node, e.message, reason: :timeout)
+      end
+
+      def cast(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        ref = fetch_ref(node)
+        return ref if ref.is_a?(Hash)
+
+        ref.send(node.message_name, inputs)
+        { status: :succeeded, output: nil, agent_trace: success_trace(node, outcome: :sent) }
+      end
+
+      private
+
+      def fetch_ref(node)
+        ref = Igniter::Registry.find(node.agent_name)
+        return failure(node, "No registered agent #{node.agent_name.inspect} is available", reason: :not_registered, registered: false, alive: false) unless ref
+        return failure(node, "Registered agent #{node.agent_name.inspect} is not alive", reason: :not_alive, registered: true, alive: false) unless ref.alive?
+
+        ref
+      end
+
+      def success_trace(node, outcome:)
+        {
+          adapter: :registry,
+          mode: node.mode,
+          via: node.agent_name,
+          message: node.message_name,
+          local: true,
+          registered: true,
+          alive: true,
+          outcome: outcome
+        }
+      end
+
+      def failure(node, message, reason:, registered: nil, alive: nil)
+        {
+          status: :failed,
+          error: { message: message },
+          agent_trace: compact_trace({
+            adapter: :registry,
+            mode: node.mode,
+            via: node.agent_name,
+            message: node.message_name,
+            local: true,
+            registered: registered,
+            alive: alive,
+            reason: reason
+          })
+        }
+      end
+
+      def pending(node, error)
+        {
+          status: :pending,
+          message: error.message,
+          deferred_result: error.deferred_result,
+          payload: error.deferred_result&.payload || {},
+          agent_trace: success_trace(node, outcome: :pending)
+        }
+      end
+
+      def compact_trace(trace)
+        trace.each_with_object({}) do |(key, value), memo|
+          memo[key] = value unless value.nil?
+        end
+      end
+    end
+
+    class << self
+      def activate_agent_adapter!
+        self.agent_adapter = RegistryAgentAdapter.new
+      end
+
+      def deactivate_agent_adapter!
+        self.agent_adapter = AgentAdapter.new
+      end
+    end
+  end
+end

data/{lib → packages/igniter-agents/lib}/igniter/supervisor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "igniter/core/errors"
+require_relative "agent"
+
 module Igniter
   # Supervises a group of agents and restarts them when they crash.
   #

data/packages/igniter-agents/lib/igniter-agents.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "igniter/agent"
+require_relative "igniter/registry"
+require_relative "igniter/supervisor"
+require_relative "igniter/agents"
+require_relative "igniter/ai/agents"

data/packages/igniter-ai/README.md

@@ -0,0 +1,20 @@
+# igniter-ai
+
+Local monorepo gem that owns Igniter's AI capability pack:
+
+- `Igniter::AI`
+- AI executors and skills
+- tool registry and tool-use loop support
+- LLM providers
+- transcription providers and result types
+
+Primary entrypoints:
+
+- `require "igniter-ai"`
+- `require "igniter/ai"`
+
+Docs:
+
+- [Guide](../../docs/guide/README.md)
+- [SDK guide](../../docs/guide/sdk.md)
+- [Dev](../../docs/dev/README.md)

data/packages/igniter-ai/lib/igniter/ai/config.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    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
+
+      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, :transcription_providers
+
+      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
+        @providers[:ollama]
+      end
+
+      def anthropic
+        @providers[:anthropic]
+      end
+
+      def openai
+        @providers[:openai]
+      end
+
+      def deepgram
+        @transcription_providers[:deepgram]
+      end
+
+      def assemblyai
+        @transcription_providers[:assemblyai]
+      end
+
+      def provider_config(name)
+        @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
+end

data/{lib/igniter/integrations/llm → packages/igniter-ai/lib/igniter/ai}/context.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Igniter
-  module LLM
+  module AI
     # 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 = Igniter::AI::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, ...}]

data/packages/igniter-ai/lib/igniter/ai/executor.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Igniter
+  module AI
+    # 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.
+    #
+    # == Simple usage (no tools)
+    #
+    #   class DocumentSummarizer < Igniter::AI::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
+    #
+    # == With Igniter::Tool classes (auto tool-use loop)
+    #
+    #   class ResearchAgent < Igniter::AI::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::AI::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
+        # 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::AI.config.default_provider
+          else
+            chain = [name] + Array(fallback)
+            @provider_chain = chain.map(&:to_sym)
+          end
+        end
+
+        # Full provider chain (primary + fallbacks).
+        def provider_chain
+          @provider_chain&.dup || [provider]
+        end
+
+        # 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::AI.config.default_provider
+            )
+          else
+            @model_chain = [name] + Array(fallback)
+          end
+        end
+
+        # Full model chain (primary + fallbacks).
+        def model_chain
+          @model_chain&.dup || [model]
+        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
+
+        # 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::AI.config.provider_config(prov).default_model
+        rescue StandardError
+          "llama3.2"
+        end
+
+        def provider_config
+          Igniter::AI.provider_instance(provider).instance_of?(Class) ? nil : Igniter::AI.config.provider_config(provider)
+        rescue StandardError
+          Igniter::AI.config.ollama
+        end
+      end
+
+      attr_reader :last_usage, :last_context, :last_provider, :last_model, :call_history
+
+      # 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, 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::AI::Skill subclasses (duck-type check).
+          # Using respond_to? avoids a circular require: skill.rb requires this file,
+          # so we can't safely reference Igniter::AI::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.
+      def chat(context:)
+        messages = context.is_a?(Context) ? context.to_a : Array(context)
+        response = provider_instance.chat(
+          messages: messages,
+          model: current_model,
+          **completion_options
+        )
+        @last_usage = provider_instance.last_usage
+        response[:content]
+      end
+
+      # 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: current_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
+
+      # Iterate through the provider/model chain, retrying on ProviderError.
+      # ConfigurationError propagates immediately (missing API key = config bug).
+      #
+      # Does NOT call Igniter::AI.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::AI::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::AI.provider_instance(@last_provider || 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
+
+      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