igniter 0.5.0 → 0.5.2

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

@@ -1,352 +0,0 @@
-# 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.
-    #
-    # == Simple usage (no tools)
-    #
-    #   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
-    #
-    # == 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
-        # 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
-
-        # 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::LLM.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::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
-          Igniter::LLM.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::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.
-      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::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(@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

data/lib/igniter/integrations/llm/providers/anthropic.rb

@@ -1,181 +0,0 @@
-# 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|
-            {
-              id:        b["id"].to_s,
-              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) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
-          messages.flat_map do |m|
-            role = (m[:role] || m["role"]).to_sym
-
-            case role
-            when :assistant
-              calls = Array(m[:tool_calls])
-              if calls.any?
-                # Anthropic requires tool_use blocks inside the content array
-                blocks = []
-                blocks << { "type" => "text", "text" => m[:content].to_s } unless m[:content].to_s.empty?
-                calls.each do |tc|
-                  blocks << {
-                    "type"  => "tool_use",
-                    "id"    => tc[:id].to_s,
-                    "name"  => tc[:name].to_s,
-                    "input" => (tc[:arguments] || {}).transform_keys(&:to_s),
-                  }
-                end
-                [{ "role" => "assistant", "content" => blocks }]
-              else
-                [{ "role" => "assistant", "content" => m[:content].to_s }]
-              end
-            when :tool_results
-              # All results for one LLM turn → single user message with tool_result blocks
-              blocks = Array(m[:results]).map do |r|
-                { "type" => "tool_result", "tool_use_id" => r[:id].to_s, "content" => r[:content].to_s }
-              end
-              [{ "role" => "user", "content" => blocks }]
-            else
-              [{ "role" => role.to_s, "content" => (m[:content] || m["content"]).to_s }]
-            end
-          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

data/lib/igniter/integrations/llm/providers/base.rb

@@ -1,33 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-# 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